Skip to content

Two app-source comments quote a DESIGN.md §09 that no longer says any of it — the stale-pointer pattern, pointing the other way - #74

Merged
zhuangjianguo merged 1 commit into
mainfrom
claude/issue-71-stale-design-quotes
Sep 10, 2026
Merged

Two app-source comments quote a DESIGN.md §09 that no longer says any of it — the stale-pointer pattern, pointing the other way#74
zhuangjianguo merged 1 commit into
mainfrom
claude/issue-71-stale-design-quotes

Conversation

@claude

@claude claude Bot commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Fixes #71

Two comments, nothing else: both hunks sit inside /** … */ blocks, 2 files, +13 −4. No metadata key, no widget, no dataset field or dimension, no DESIGN.md change.

1. src/dashboards/legal.dashboard.ts — quote removed, pointer left behind

Chose removal over updating — the card's preferred option, and this was its one judgement call, so here is the reason. The header carried a copy of a six-item list whose master lives in DESIGN.md §09, and the copy lost the race three times in two days. Verified on this branch rather than taken from the card:

$ git log --oneline -S '平均周转' -- DESIGN.md      → 1127e52 (in PR #40, merge 296fab8, 2026-09-09)
$ git log --oneline -S '各阶段合同数漏斗' -- DESIGN.md → 30fd863 (PR #70, 2026-09-10)
$ git show 1127e52 -- DESIGN.md | grep 法务工作台
-- **法务工作台** — 待受理数 · 审查中 · 超 SLA · 谈判停滞 · 平均周转(本月 vs 上月)· 各阶段合同数漏斗
+- **法务工作台** — 待受理数 · 审查中 · 审查超 30 天(固定阈值,写进砖的标题)· 谈判停滞 · 审批吞吐(本月 vs 上月,用平台 `compareTo`)· 各阶段合同数(横向条形图…)

Updating the copy buys correctness until the next §09 edit and leaves the same trap armed. A pointer cannot drift, and the one thing a reader actually needs from that line — which of §09's three dashboards this file is — survives a pointer intact. The new header says the list is deliberately absent, so the next reader does not helpfully paste it back:

 * 法务工作台 — DESIGN.md §09's first dashboard.
 *
 * §09's brick list is deliberately NOT copied here. The copy that used to sit
 * on these lines drifted three times in two days — two of its six items were
 * rewritten by PR #40 (`1127e52`, 2026-09-09) and the third by PR #70
 * (`30fd863`, 2026-09-10) — and by the end all three described bricks this file
 * does not implement. §09 is the source and a pointer to it cannot drift; the
 * widgets below each carry their own comment for their own shape.

"all three described bricks this file does not implement" is checkable inside this file: the board has review_ageing titled In Review Over 30 Days (not a 超 SLA tile), approval_throughput titled Approved This Month (not an average turnaround), and a horizontal-bar (not a funnel). The claim is deliberately about this file, not about what §09 currently declines — see the sweep below for why that mattered.

2. src/datasets/cycle-time.dataset.ts — the comparison stops asserting a funnel

The measurement stays exactly as it was: signed_at (72) exceeding submitted_at (60), and its reason (the demo's in-force book was backfilled with signature dates and no intake). Only the contrast — "The status funnel on the legal workbench is the honest funnel" — is rewritten, because that widget has been a horizontal-bar since PR #57 (#48) and §09 records the same non-monotone book as the reason. The replacement points at §09 instead of re-describing it, does not name the widget id, and re-promises no stage order.

Verification the edits landed — before/after counts, not an editor's exit code

spelling before after
各阶段合同数漏斗 (src/) 1 0
The status funnel on the legal workbench (src/) 1 0
is the honest funnel (src/) 1 0
DESIGN.md §09's first dashboard: (src/) 1 0
超 SLA (src/) 2 1
平均周转 (src/) 2 1
§09's brick list is deliberately NOT copied here 0 1
There is no funnel on the legal 0 1

The two residual hits are legal.dashboard.ts:143 and :182, per-widget comments outside this card's two-comment scope. They are the subject of the follow-up card below, not an oversight.

Gates — all four exit 0, and they genuinely cover these files

Exit codes captured into a variable before any pipe (cmd > log 2>&1; EXIT=$?), run at 96e83ad:

validate-exit:0      ✓ Validation passed (905ms)
lint-exit:0          21 warning(s), 5 suggestion(s) (910ms)   [pre-existing, none in the two files]
typecheck-exit:0     tsc --noEmit, no output
i18n-gate-exit:0     ✓ i18n gate — 0 missing keys across 2 locale(s)

Unlike the recent DESIGN.md-only cards, these files are inside the gates' surface: src/**/* is in tsconfig's include and both files are in the metadata graph, so pnpm typecheck really does read them and pnpm validate really does parse the dashboard and the dataset around these comments. No "no gate reads this file" claim is made here, because it would be false.

The honest ablation is therefore the opposite shape — proving a defect in one of these files is caught. Mutation proven on disk before the run, restore proven by blob hash and an empty git diff HEAD rather than by an exit code:

HEAD blob: 55a5600c3ad3ff7abb9d0d4c781a356c7430920a
-- mutation on disk, marker count: 1        (appended `const ablation: number = ;`)
mutated-typecheck-exit:2
src/datasets/cycle-time.dataset.ts(85,26): error TS1109: Expression expected.
restored blob: 55a5600c3ad3ff7abb9d0d4c781a356c7430920a   RESTORE OK (blob matches HEAD)
git-diff-HEAD-empty:yes    marker after restore: 0

A trap … EXIT INT TERM with an absolute repo path guarded the mutation. Comments themselves are invisible to tsc, which is exactly why the drift went unnoticed for two days; the gates bound the file, not the prose inside it.

Sweep — other comments quoting a DESIGN.md § list rather than pointing at it

Asked for by the card, because two such quotes drifted at once. Not "nothing else": there are seven more, one cluster of which is stale in the same direction.

Stale (filed, not fixed here — out of scope, and not mechanical):

  • src/dashboards/executive.dashboard.ts:4–5 — quotes §09's 管理层 list including 审批瓶颈(各台阶平均停留), which §09 replaced with 各台阶路由量 and then explicitly declined ("§09 原列的「审批瓶颈(各台阶平均停留)」同样不交付"). The board already implements the routing bricks (route_legal_head · route_finance · route_executive · route_gm), so the header advertises something the file below it does not build.
  • src/dashboards/executive.dashboard.ts:139, 141 · src/dashboards/legal.dashboard.ts:143, 182 · src/datasets/cycle-time.dataset.ts:7 — five comments still framed as "§09 asks for X, and we cannot deliver it": 各台阶平均停留 · 超 SLA · 平均周转 · 各段时长. All four were placed outside the V1.0 surface by the same 2026-09-09 ruling that §09 now records, so the framing is inverted — §09 no longer asks. Their substance is correct and is what §09 itself now cites; the fix is a reframe, not a deletion, which is why it is a separate card and not a rider here.

Accurate copies today, still copies (reported, not filed): finance.dashboard.ts:4–5 (§09's 财务 list) · dashboards/index.ts:1 (the three dashboard names) · contract.dataset.ts:4, obligation.dataset.ts:4, payment.dataset.ts:4 (one-line §09 dataset bullets) · pages/contract_detail.page.ts:132 (§05's highlights list). Each re-checked against §09 / §05 on 30fd863 and each still matches word for word.

No browser run owed

The diff changes no runnable surface: comments do not lower into metadata and the built stack is byte-identical. pnpm validate parsing both files green is the whole of what is verifiable here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R3n3GGzobdegM4HUzah1iR


Generated by Claude Code

The legal dashboard's header carried a copy of §09's six-brick list. That
copy drifted three times in two days — two items rewritten by PR #40
(1127e52), the third by PR #70 (30fd863) — and by the end all three
described bricks this file does not implement. Replace the copy with a
pointer to §09, which cannot drift.

The cycle-time dataset's stage-count paragraph contrasted its counts with
"the status funnel on the legal workbench", a funnel that has not existed
since PR #57 made that widget a bar chart. Keep the measurement and its
reason (signed_at 72 exceeds submitted_at 60; backfilled in-force book,
no intake) and drop the claim that a funnel exists to contrast with.

Comments only: no metadata, no behaviour, no DESIGN.md change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3n3GGzobdegM4HUzah1iR
@zhuangjianguo
zhuangjianguo marked this pull request as ready for review September 10, 2026 11:36
@zhuangjianguo
zhuangjianguo merged commit 9ba4d78 into main Sep 10, 2026
2 checks passed
zhuangjianguo pushed a commit that referenced this pull request Sep 10, 2026
…ng (#75)

The 2026-09-09 maintainer ruling (PR #40, 1127e52) put per-stage durations,
per-type SLA breach and approval dwell outside the V1.0 surface, and 09 now
records that. Five comments still read as "09 asks for X and we cannot
deliver it", which inverts the authority: the source file was presented as
falling short of the design when it is in fact what the design settled on.

Each now says what the code delivers and why that is right, citing 09 as the
authority that agrees. The four route_* tiles ARE 09's brick at the executive
position; the fixed 30-day tile IS what 09 prescribes for review ageing, with
F3's reminder firing on the same threshold so the tile and the reminder cannot
tell two stories; approval_throughput IS 09's brick; and the stage-reached
counts with no duration measure ARE 09's bullet for the dataset.
executive.dashboard.ts's header takes PR #74's remedy — the copied list out, a
pointer in — naming the one brick it advertised that this file never built.

No measurement is deleted. The ISO-text AVG() average year, the -0.85
difference of two average years, ADR-0021 taking no SQL or expressions, and
sys_approval_request holding zero rows all stay, reframed from shortfall into
the reasons 09 itself now cites. Every citation of the upstream tracker gains
the qualifier that the in-flight fix makes the wrong path ERROR rather than
adding date arithmetic, so a duration stays uncomputable after it lands.

Three stale forward-promises inside those same comments go with them: a
daily-job-stamped review_due_at said to "belong to card 09", the same route
said to be "raised on the PR" — both now forbidden by 09 outright — and a
claim that a group title says "Routing Load", a string that exists nowhere in
the repo.

Comment-only. The gates do cover these files, and an ablation shows why the
drift survived anyway: restoring the three files to their pre-fix state leaves
all four gates green, because tsc parses comments and reads nothing in them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R3n3GGzobdegM4HUzah1iR
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Two app-source comments quote a DESIGN.md §09 that no longer says any of it — the stale-pointer pattern, pointing the other way

2 participants