25dcd7293c
Delete design-session citations (decision/audit/plan ordinals, stack positions), change narration, review choreography, and reviewer-addressed justification from comments, JSDoc, docs, READMEs, Agent Notes, tests, and generator templates; restate every affected fact as current-state contract prose. Fix generated docs at their sources and regenerate the catalogs and cordis-surface regions; re-paste type-equiv blocks; update every bilingual counterpart and re-record the pairs. Record the citation rule in the committed-artifact-citations Agent Note.
4.5 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 per the documentation standard; issues are durable and citable.
- A design-session ordinal with a committed owner is replaced by the owner's name — decision 21 lives in the web input-machine note as the plain-text-reference decision. 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 \dand\(audit [A-Z]\d) is the candidate if the pattern recurs. - 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.