ee7458b2df
Purge the residual task/phase ordinals review caught ((T2), (queue cut 1) ×3, T6, P-I, 'this cut' ×6 including battery-expansion finds in two untouched notes and a workflow JSDoc); drop the 'externally logged as Decision 21' parenthetical and rename the remaining bare decision-21 mentions; mark the gui-layering IPC bridge row as a hypothetical example; restore the GATE_NOTICE doc-typecheck clause and the py-types 'measured' provenance; say subprocess-backed in filesystem.md; add the picker note path. Amend the citations note: merged-PR evidence anchors in Agent Notes are sanctioned, and the candidate gate patterns gain the four shapes the sweep missed. All nine touched pairs re-recorded.
4.9 KiB
Agent Note: Cite committed artifacts, never design-session ordinals
Status: implemented
English | 中文
Problem
Large design and review sessions leave working shorthand — decision ordinals, audit item codes, plan section numbers, task and stack ordinals, reviewer rulings — that reads naturally while the session transcript is open and resolves to nothing after it closes. A repo-wide audit found the pattern concentrated in packages/client: bare (decision 12/16/19/20/21) citations of which only decision 21 had a committed owner, (audit C2/S1/S3/S7) codes with no audit document anywhere, design §4.7 / web2 §0 / plan §1.4 references to uncommitted drafts, plan-phase labels (T2/T5/T9, P-I, W5), stack positions ("a later PR in this stack") in durable JSDoc, and "ruling" / "design ledger" vocabulary. The same families appeared in tests, CSS comments, generator templates, CI comments, and Agent Notes ("this PR/branch/review round" vantage, review-choreography attributions, stale "deferred to a later PR" claims whose targets had since shipped). The documentation standard already banned the change-history half (previously/now, PR and commit references) but stated no counterpart rule for citations, so unresolvable ordinals kept landing.
Decision
Durable prose — comments, JSDoc, docs, notes, test comments and titles — cites only committed artifacts, resolvable in-repo without grep archaeology:
- Name the owning Agent Note (its path at least once per file, a searchable name inline), the doc page path, or a GitHub issue number. PR, commit, branch, and stack positions stay banned in docs and code per the documentation standard; issues are durable and citable, and Agent Notes may cite merged PRs as evidence anchors — the standard routes change stories to commits, PRs, Agent Notes, and postmortems, and a note is that home.
- A design-session ordinal whose decision has a committed owner is replaced by the decision's name — the ordinal once logged as "decision 21" is now "the plain-text-reference decision", owned by the web input-machine note; the ordinal itself resolves nowhere in-repo and was dropped everywhere. An ordinal without an owner is deleted and its factual clause restated to stand alone.
- Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
- Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
- Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice.
One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (scripts/gen-doc-graphs.ts, scripts/gen-tool-catalog.ts, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records.
Alternatives considered
- Commit the design ledgers and audit documents so the ordinals resolve. Rejected: session transcripts are working artifacts, not maintained references; committing them would create a parallel, ungated decision corpus beside Agent Notes, and their internal numbering would still drift.
- A mechanical gate for the banned vocabulary. Deferred: the vocabulary is unbounded natural language, and the audit's recall batteries need judgment to separate leakage from legitimate prose ("wait" the noun, contrastive "actually", runtime old/new states). A narrow high-precision gate (for example
\(decision \d,\(audit [A-Z]\d,\bcut \d,this cut, a bare\bT\d\b, andP-I) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly those last four shapes, so they lead the candidate list. - Delete the rationale that cited dead artifacts. Rejected: the factual clauses were preserved or restated; only citations, review choreography, and derivation transcripts were removed, per the prose standard's complete-proposition rule.
Verification
The audit's grep batteries (English and Chinese, comments and prose, --hidden for .agents/) return no design-ordinal citations outside recorded fixtures and archived notes; verify-type-equiv, the gen-* freshness checks, and verify-translation-pairing pin the regenerated and re-recorded surfaces. Coverage gap: no gate rejects a new ordinal citation — review owns the rule.
Consequences
- A comment's citations resolve by path or name; readers never reconstruct a closed session to follow one.
- Design sessions must land their decisions in Agent Notes before durable prose can cite them; ordinal shorthand stays inside the session.
- Citations get longer (a note path instead of "(decision 21)") in exchange for grep-free resolution.