Implementation notes are shown to users as help text — field and dashboard-widget descriptions cite hook files, card numbers, DESIGN.md sections and PRs

[objectstack-fleet]

Part of #95 — the objects, dashboards, flows and translation-bundle half. The descriptions that live in files held by other in-flight work (listed under "Left for the follow-up") are not touched here, so #95 remains open after this merges.

What changed

Every description in the claimed surface was enumerated and classified as user-facing, implementation note, or mixed. The notes and mixed ones were rewritten for the person reading the screen, in English and in zh-CN, and any implementation detail that was not already in the object or flow header now sits in a code comment beside the field. No key is added or removed, no option value, label key or behaviour changes.

Area	Descriptions enumerated	Rewritten	Kept as user-facing
src/objects/*.object.ts	115 (11 object-level, 1 validation rule, 103 field)	54 field	61
src/dashboards/**	22 (3 dashboard, 19 widget)	4 widget	18
src/flows/** (excluding the two held flows)	10	6	4
src/translations/en/**	mirrors every inline change above	58	—
src/translations/zh-CN/**	values that carried the same notes, or a wrong state table	15	—

What left user-facing text: hook file names (contract.hook.ts, mirror.hook.ts), card numbers ("card 09"), DESIGN.md section citations, "see the PR", decision and upstream issue numbers, flow codes (F1, F3, F4, F5, F6, F8, F13, F14, F15, F16, S2/S6), API field and object names (currency_code, is_expiring, clm_payment_plan.planned_amount and so on), and mechanics such as "stored mirror", "write layer", "guard reads the children directly", "1-based", "seeded type SLA".

Where a note was useful to a user, the meaning stays and the mechanics go. Two examples: the review-ageing tile still says it is a fixed 30-day threshold; the department field still says department-level sharing is not in the standard product.

Mirror-field help (display names) now says "Filled in automatically as ..." and shows the shape in words (for example "clause title · status").

Corrections, not only rewording

Four help texts were wrong, and each was rewritten anyway:

• Contract type → Review SLA (days) claimed the overdue reminder fires per this value. The reminder fires at 30 days for every type (legal-review-sla.flow.ts, decision [Decision] §09 要「各段时长」和「超 SLA」，但语义层算不出时间差——两问共用一个补法 #31). The help now says so in both locales.
• Obligation → Status omitted In Progress → Overdue, and the zh-CN text also omitted Pending → Overdue. Payment plan → Status omitted both Partial edges. Both locales now match the state machine in contract.hook.ts.
• Contract → End Date / Expiring Soon attributed the flag to F13. It is set by F12 renewal_notice. This is now stated in the new code comment; the user text names no flow.
• Contract → Contract Language said "ISO 639-1 code" on a picker that lists language names. It now reads "The language whose text governs the contract".

The review-ageing widget help used to get cut off after two lines ("…a fixed threshol…"). It now leads with "A fixed 30-day threshold…", which fits; the tile title already states "Over 30 Days".

Left for the follow-up (held files, not in this PR's surface)

• src/flows/contract-approval.flow.ts (held by PR On a README-configured install the approval ladder sticks forever at its first rung — manager_review resolves to manager:undefined, locks the contract, and no approver is told anything is waiting #101): the rung label Head of Legal + Finance Controller (会签) (line 280) and the edge label Legal + finance (会签) (line 433).
• src/actions/contract-lifecycle.actions.ts (held by PR The intake wizard's "Submit now" fails for every requester — FLOW_FAILED, the edit-window RLS policy refuses the post-submit row, while the header Submit button on the same draft succeeds #91): the submit, send-to-approval and activate descriptions cite F2, F5, F9 and activated_at (lines 105, 122, 146), and so do their clm_contract._actions keys in both bundles.
• src/actions/contract-backfill.actions.ts (not in the claimed surface): the action description (active, is_backfilled, line 48), the param help "It becomes both signed_at and executed_at" (line 57) and "kind final_signed" (line 58), plus the _actions.executed_upload.description bundle key.
• src/datasets/** (not in the surface): contract_cycle_time says "see the module comment"; obligation_metrics and payment_metrics say "the arrears the daily job stamps". The datasets.* bundle keys are the same text.
• src/profiles/*.profile.ts and src/sharing/contract.sharing.ts (not in the surface): the row-policy and sharing-rule descriptions shown in Setup open with "DESIGN.md §04" and policy names.
• src/views/** and src/apps/**: owned by Seven smaller things a real user hits (from the 17.7.0 browser pass): legal tabs shown to requesters, a template toggle with no template, renewal with no link, orphan drafts, a false demo note, an empty landing page for lawyers #99. My scan found no implementation note there.

Gates — on 7794860 (the head of this PR)

Run as pnpm verify through the container's verify lock (VERDICT command-exit 0). The four gates are the same set CI runs.

> objectstack validate
  ✓ Validation passed (1114ms)

> objectstack lint
  6 suggestion(s) (1098ms)
  (all six are the pre-existing contract_approval empty-slate notices; the file is untouched)

> tsc --noEmit
  (no output, exit 0)

> node scripts/check-lint-i18n-gate.mjs
✓ i18n gate
  LOCALES  : "en", "zh-CN" checked (required: en, zh-CN)
  REACH    : 12 surface classes walked — object=34 · field=273 · option=188 · section=35 · view=37 · action=55 · app=2 · navigation=28 · dashboard=40 · widget=38 · dataset=70 · page=12
  COVERAGE : 0 missing keys across 2 locale(s)

Control-byte self-scan over the 25 changed files: no match.

Browser evidence

pnpm exec objectstack dev --ui --compile --seed-admin --no-watch -p 3495 was run on a fresh SQLite file, once on 46e65f0 (before) and once on this branch (after). Playwright drove the pre-installed Chromium, signed in as the seeded dev admin, and read each form's text.

• Boot: no degraded, no such table or plugin-load failure. The 9 boot diagnostics are the same in both runs: scheduled work is off by deployment policy, the analytics security-bridge notice, plain-HTTP OAuth on loopback, and one sys_migration UNIQUE insert retry.
• Browser console in both runs: one 401 on GET /api/v1/auth/get-session before sign-in, plus one 404 resource load on the login page. Nothing else.

What the screen showed (one line per help text, before → after):

1. Deviations → New → Status: "open → accepted / rejected / withdrawn; the decided states are terminal (contract.hook.ts)." → "Moves from Open to Accepted, Rejected or Withdrawn; those three are final."
2. Dashboards → Legal Workbench, widget help:
   • "Older than every seeded type SLA (longest is 10 days) — a fixed threshol…" → "A fixed 30-day threshold, not each contract type's own review SLA."
   • "The ball is in their court — the queue F4 chases" → "…the queue to chase".
   • "Not an average duration — see the PR." → "A count, not an average turnaround time."
3. Contracts → New: this form renders the same field help the Backfill Executed Contract dialog inherits from its field-backed params. It showed 15 changed help texts, among them:
   • Our Signing Entity no longer ends "(DESIGN.md §01: signing entities are configuration, not schema)".
   • End Date: "The expiry job (F13) flags is_expiring renewal_notice_days before this date." → "The contract is flagged Expiring Soon once this date is within its renewal notice period."
   • Requesting Department no longer cites "RLS" and "(§13 Q2)".

zh-CN was checked with a browser locale of zh-CN. The Legal Workbench showed "固定的 30 天阈值，不是各合同类型自己的审查时限。" and "这是数量，不是平均周转时长。". The new-obligation form showed the corrected status table "待办可转为进行中、已完成、已豁免或已逾期；进行中可转为已完成、已豁免或已逾期；…".

The PM seat has the screenshots, three before and three after, plus one zh-CN dashboard.

Acceptance notes

• Party → Country still reads "Drives governing-law defaults and screening." Nothing in the app reads country_code: its only uses are highlightFields and a list column, and the intake form's governing-law input has no default. Measured on the party New form in the browser. This is not an implementation note, so it is not rewritten here; it is reported to the seat.
• The payment-plan.object.ts header comment still draws the old state table without the partial edges. This is a code comment, not user text, and is left as is.
• Field help that names data-entry formats (the Signers JSON shape, ISO country/currency codes on text inputs) is kept: the user types those.

Deviations from the suggested route

• Backfill dialog. Reaching it needs the execute_contract capability, which the seeded platform admin does not hold. Granting it on a local database was refused by the session's permission classifier. That database was deleted and the "before" run repeated on a fresh one. The evidence uses the contract create form, which renders the same inherited field help. The action's own param help is in a file outside this surface (listed above).
• Commits are split by area (objects with their bundle keys, dashboards with theirs, flows, then one follow-up tweak) rather than putting the translation bundles in a commit of their own, so that every commit leaves the en bundle equal to the inline source.

---

Generated by Claude Code