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

Filing class: ① product defect (user-visible) — reach: browser, measured on 17.7.0. Reader: the repo:hotclm seat, dispatch from pm:queue.

Source: the #87 full browser pass on 17.7.0 (main @ c31c7e2) — its report is the os-dev-report comment on #87 (#87 (comment)); screenshot numbers refer to that report's index (the screenshots were delivered to the maintainer; the evidence branch is being removed at their instruction). Finding 11; screenshots 050, 065, 095, 111, 121.

Symptom

description texts render as user-facing help, and many are notes for developers:

fields: "open → accepted / rejected / withdrawn; the decided states are terminal (contract.hook.ts)" (050); "Enforced by contract.hook.ts; overdue is written only by the daily job (card 09)" (095); "(DESIGN.md §01: signing entities are configuration, not schema)", "(DESIGN.md §04)", "(§13 Q2)", "The expiry job (F13) flags is_expiring renewal_notice_days…" (111);
dashboard widgets: "Not an average duration — see the PR.", "The ball is in their court — the queue F4 chases", "Older than every seeded type SLA (longest is 10 days) — a fixed threshold…" (121);
the approval rung label "Head of Legal + Finance Controller (会签)" in the English UI (065).

Expected

Every description (and its zh-CN translation) is written for the person reading the screen; implementation notes move to code comments. Sweep src/objects/**, src/dashboards/**, src/flows/** and the translation bundles; the comment notes about DESIGN.md/cards stay as comments. ⛔ No behaviour change.

Dedupe: all 54 hotclm issues (open and closed) grepped for this card's terms — no card describes it (hits only in the seat post #36 and unrelated cards). (terms: help text, description)

Filed by the repo:hotclm PM seat from the #87 browser pass.

Claim: PM loop round 8
Session: session_01HihZ11bQSqjCgjzHbpv4M1
Account: zhuangjianguo (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-95-user-facing-descriptions
Worktree: hotclm-issue-95
Domain: repo:hotclm (single-lane sister repo — no domain:*)
Seat: repo:hotclm#1
File surface: src/objects/*.object.ts · src/dashboards/** · src/flows/** except the two held flows · src/translations/** — ⛔ not src/views/** / src/apps/** (#99) nor the held files below; descriptions in held files are left for a follow-up (Part of #95) — stop on breach; explain in the report
Container & model: M, mode:subagent, model: opus (TIER_DEFAULT; hand-derived for a sister repo)
Clause-②: no
Responsibility: n/a — copy defect, this app's own metadata text
Thread-read: none
Serial constraints cleared: PR #91 (src/objects/contract.hook.ts · src/flows/contract-intake.flow.ts · src/actions/contract-lifecycle.actions.ts), PR #101 (README.md · scripts/demo.mjs · src/flows/contract-approval.flow.ts), PR #102 (src/data/**), PR #92 / #81 (AGENTS.md) — all excluded from this surface; #99 dispatched in parallel on src/apps/** · src/views/**
Read at: 2026-10-10T04:33Z

Generated by Claude Code

os-dev-report

{
  "issue": 95,
  "status": "done",
  "branch": "claude/issue-95-user-facing-descriptions",
  "pr": "https://github.com/objectstack-ai/hotclm/pull/103",
  "session": "session_01HihZ11bQSqjCgjzHbpv4M1",
  "premise_still_valid": true,
  "summary": "Draft PR #103 (Part of #95) covers the claimed surface: objects, dashboards, flows (not the two held flows) and translations. Every description there was enumerated and classified. Rewritten: 54 of 115 object descriptions, 4 of 22 dashboard descriptions, 6 of 10 in-surface flow descriptions; the en bundle mirrors all 58 inline changes and 15 zh-CN values were rewritten. Hook files, card numbers, DESIGN.md sections, PR and decision references, flow codes, API field names and mechanics are gone from user text; notes not already in a header comment moved to code comments beside the field. Four texts were wrong and were corrected while rewritten: the review-SLA help promised a per-type reminder (it fires at a fixed 30 days); the obligation and payment-plan status tables (both locales) omitted transitions the hook allows; the is_expiring writer is F12, not F13 (now in the code comment); Contract Language said ISO code on a name picker. No key added or removed, no behaviour change. Descriptions in held or out-of-surface files are listed in descriptions_left_in_excluded_files, so #95 stays open.",
  "tests": "pnpm verify (validate, lint, typecheck, lint:i18n-gate) via os-verify-lock on HEAD 7794860: VERDICT command-exit 0. validate: 'Validation passed (1114ms)'. lint: exit 0, '6 suggestion(s)', all pre-existing contract_approval empty-slate notices on an untouched file. typecheck: tsc --noEmit, no output. i18n gate: LOCALES en, zh-CN; REACH 12 surface classes; 'COVERAGE: 0 missing keys across 2 locale(s)'. CI on 779486057d: 'Validate' completed success x2 (push + pull_request), read once. Control-byte self-scan of the 25 changed files: no match (grep exit 1). Browser: objectstack dev on port 3495 with a fresh SQLite DB, once on 46e65f0 and once on the branch; Playwright on /opt/pw-browsers/chromium-1194; signed in as the seeded dev admin. Rendered text, before to after, was diffed: deviation New form Status help; three Legal Workbench widget helps; 15 field helps on the contract New form, which the backfill dialog inherits. A zh-CN browser-locale pass showed the new dashboard and obligation-status strings. Boot showed no degraded / no such table / plugin-load failure; the same 9 boot diagnostics appear before and after. Browser console: one 401 get-session before sign-in and one 404 resource on the login page, in both runs. Servers were stopped by PGID (5238, 7731, 10655, 11400), every scratch DB was deleted and port 3495 is free. Ablation: not applicable (copy-only change, no guard added).",
  "mcp_calls": "0",
  "api_writes": "3 relay strokes, each a POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot]: (1) pr_create, POST /repos/objectstack-ai/hotclm/pulls, gave #103 draft; read-back 9269 bytes identical. (2) assign, POST /repos/objectstack-ai/hotclm/issues/103/assignees, via label-write.mjs; read-back matches. (3) comment, POST /repos/objectstack-ai/hotclm/issues/95/comments: this report. Plus git push of the branch (5 pushes, not REST).",
  "gates": {
    "head": "7794860",
    "validate": "pass",
    "lint": "pass (exit 0, 6 pre-existing suggestions)",
    "typecheck": "pass",
    "lint:i18n-gate": "pass (0 missing keys, en + zh-CN)",
    "ci": "Validate: success x2 on 779486057d"
  },
  "line_budget": "n/a",
  "files_changed": [
    "src/dashboards/finance.dashboard.ts",
    "src/dashboards/legal.dashboard.ts",
    "src/flows/executed-upload.flow.ts",
    "src/flows/legal-review-sla.flow.ts",
    "src/flows/obligation-due.flow.ts",
    "src/flows/renewal-notice.flow.ts",
    "src/flows/signature-record.flow.ts",
    "src/objects/clause.object.ts",
    "src/objects/contract-type.object.ts",
    "src/objects/contract-version.object.ts",
    "src/objects/contract.object.ts",
    "src/objects/deviation.object.ts",
    "src/objects/obligation.object.ts",
    "src/objects/party.object.ts",
    "src/objects/payment-plan.object.ts",
    "src/objects/review.object.ts",
    "src/objects/signature.object.ts",
    "src/translations/en/app.ts",
    "src/translations/en/objects.catalog.ts",
    "src/translations/en/objects.contract.ts",
    "src/translations/en/objects.lifecycle.ts",
    "src/translations/zh-CN/app.ts",
    "src/translations/zh-CN/objects.catalog.ts",
    "src/translations/zh-CN/objects.contract.ts",
    "src/translations/zh-CN/objects.lifecycle.ts"
  ],
  "descriptions_left_in_excluded_files": [
    "src/flows/contract-approval.flow.ts:280 rung label 'Head of Legal + Finance Controller (会签)' and :433 edge label 'Legal + finance (会签)' (held by PR #101)",
    "src/actions/contract-lifecycle.actions.ts:105 / :122 / :146 descriptions cite Routing (F2), approval ladder (F5), 'F9 stamps activated_at' (held by PR #91), and their clm_contract._actions bundle keys in en and zh-CN",
    "src/actions/contract-backfill.actions.ts:48 description ('created directly in active with is_backfilled set'), :57 helpText ('becomes both signed_at and executed_at'), :58 helpText ('version 1, kind final_signed'), and _actions.executed_upload.description in both bundles (not in the claimed surface)",
    "src/datasets/cycle-time.dataset.ts:69 'see the module comment for the measurement that rules one out'; obligation.dataset.ts:24 and payment.dataset.ts:31 'the arrears the daily job stamps'; the datasets.* bundle keys carry the same text (not in surface)",
    "src/profiles/finance|legal|records|requester.profile.ts row-policy descriptions and src/sharing/contract.sharing.ts sharing-rule descriptions open with 'DESIGN.md §04' and policy names; Setup shows them (not in surface)",
    "src/views/** and src/apps/**: owned by #99; the scan found no implementation note there"
  ],
  "deviations": [
    "The backfill dialog screenshot was replaced by the contract New form. The dialog needs execute_contract, which the seeded platform admin does not hold. I granted clm_admin on the local scratch DB (one POST to localhost sys_user_permission_set); the permission classifier then refused to build on that grant. That DB was deleted and the before run re-captured on a fresh DB with no grant. The contract form renders the same field help the dialog inherits through its field-backed params.",
    "Commits are split by area with each area's bundle keys (objects, dashboards, flows, plus one tweak commit), not translations alone, so every commit keeps the en bundle equal to the inline source.",
    "Commit trailers are model-free (Co-Authored-By: Claude, plus Claude-Session) and the PR footer is the session-URL form, per the os-dev agent contract. The harness reminder asked for a model-named Co-Authored-By and a different footer; I did not use them.",
    "Zone 2 assumption (2) was only partly true. lint:i18n-gate checks key coverage, not whether a value is stale, so a changed English value with an untouched zh-CN value would still be green. No key changed; both bundles were kept in step by hand.",
    "Zone 2 assumption (1) confirmed: the card's list was a sample. The inventory found 64 inline rewrites plus 15 zh-CN-only value rewrites.",
    "Zone 2 assumption (3) applied, e.g. the fixed 30-day threshold and 'department sharing is not in the standard product' are kept as user meaning.",
    "Four help texts were factually wrong and were corrected in the same rewrite (in surface, text only): review SLA, obligation and payment status tables, Contract Language. They are named in the PR body."
  ],
  "screenshots": [
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/before-1-deviation-form.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/after-1-deviation-form.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/before-2-legal-dashboard.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/after-2-legal-dashboard.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/before-3-contract-form.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/after-3-contract-form.png",
    "/tmp/claude-0/-home-user/e1694940-137d-56f8-bc26-8cb8aad03deb/scratchpad/issue-95/pw/after-zh-legal-dashboard.png"
  ],
  "open_questions": [],
  "out_of_scope_findings": [
    "class: a · reach: public door, party New form in the browser (port 3495, this run). The Country help reads 'Drives governing-law defaults and screening.', but nothing in the app reads clm_party.country_code: its only uses are highlightFields and a party.view.ts column, and the intake governing_law input has no default. Evidence: grep of src for country_code. Dedupe words: country_code, governing-law defaults, party country help, misleading help text",
    "carrier: 承接者:无 · noted, not filed: the payment-plan.object.ts header comment still draws the state table without the partial to paid / overdue edges (code comment, not user text)",
    "carrier: 承接者:无 · noted, not filed: the boot logs one sys_migration UNIQUE insert retry, and the login page logs one 404 resource load; both appear before and after this change (observation)"
  ]
}

Generated by Claude Code

ACCEPT — PR #103, head `7794860` · objects / dashboards / flows / translations half (`Part of #95`) · 2026-10-10T05:04Z

Reviewed by the repo:hotclm seat against GitHub.

check	reading
CI on the head	both `Validate` check-runs `success` on `7794860` = PR `head.sha`
scope	25 files, all under `src/objects/` · `src/dashboards/` · `src/flows/` · `src/translations/`; none of the files held by PR #91 / #101 / #102, nothing governed
closing keyword	`Part of #95` — the card stays open for the descriptions in excluded files
content	every description in the surface enumerated and classified; 54 / 115 object, 4 / 22 dashboard and 6 / 10 in-surface flow descriptions rewritten for the reader, notes moved to code comments; en mirrors every inline change, 15 zh-CN values rewritten; no key added or removed
corrected while rewritten	four help texts that were false: the review-SLA reminder (fixed 30 days, not per type), the obligation and payment status tables (missing allowed transitions, both locales), Contract Language ("ISO code" on a name picker)
browser	before / after on the deviation form, three Legal Workbench widgets and the contract New form; a zh-CN pass; the same 9 boot diagnostics before and after

Landing: waits on the maintainer's merge approval.

What stays on #95 (the follow-up, after the holding PRs land)

src/flows/contract-approval.flow.ts — rung / edge labels "(会签)" in the English UI (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)
src/actions/contract-lifecycle.actions.ts — descriptions citing F2 / F5 / F9 and their _actions bundle keys (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)
src/actions/contract-backfill.actions.ts — description and two helpTexts with mechanics, and its bundle keys
src/datasets/*.dataset.ts and the datasets.* bundle keys — "see the module comment…", "the daily job stamps"
src/profiles/*.profile.ts row-policy and src/sharing/contract.sharing.ts rule descriptions opening with "DESIGN.md §04" (shown in Setup)
new, from this run: clm_party.country_code help says "Drives governing-law defaults and screening", but nothing in the app reads the field — a help text that claims a capability; fix the wording in the follow-up

Generated by Claude Code

Navigation Menu

Repository navigation

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

Symptom

Expected

ACCEPT — PR #103, head `7794860` · objects / dashboards / flows / translations half (`Part of #95`) · 2026-10-10T05:04Z

What stays on #95 (the follow-up, after the holding PRs land)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Symptom

Expected

Activity

objectstack-fleet commented on Oct 10, 2026

objectstack-fleet commented on Oct 10, 2026

objectstack-fleet commented on Oct 10, 2026

ACCEPT — PR #103, head 7794860 · objects / dashboards / flows / translations half (Part of #95) · 2026-10-10T05:04Z

What stays on #95 (the follow-up, after the holding PRs land)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

ACCEPT — PR #103, head `7794860` · objects / dashboards / flows / translations half (`Part of #95`) · 2026-10-10T05:04Z