Cite committed artifacts, never design-session ordinals
引用已提交的产物，绝不引用设计会话序号
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 own
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 and postmortems may cite merged PRs and issues as evidence, per the documentation standard's change-story routing.
- 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. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
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. The dsh-trim-cot-leakage skill operationalizes these rules: the audit taxonomy, the committed recall batteries, and few-shot examples for deciding what to keep or delete.
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,P-I,used to, a bare\bv1\b, and§\d— the last excluding citations whose section numbering has a committed owner, such as web-styling.md's own §N) is the candidate if the pattern recurs; review of the purge itself caught residuals in exactly the cases those searches missed, 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, archived notes, the trim skill's own files, and this note's quoted evidence; 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.
中文
问题
大型设计与评审会话会留下工作速记：决策序号、审计条目代号、计划章节编号、任务与栈序号、评审人裁定。这些速记在会话 transcript（文本记录）还开着时读起来顺理成章，一旦关闭就什么也解析不到。一次全仓库审计发现该模式集中在 packages/client：裸写的 (decision 12/16/19/20/21) 引用中只有决策 21 有已提交的归属文档；(audit C2/S1/S3/S7) 代号在任何地方都没有对应的审计文档；design §4.7／web2 §0／plan §1.4 指向未提交的草稿；计划阶段标签（T2/T5/T9、P-I、W5）；持久 JSDoc 里的栈内位置（"a later PR in this stack"）；以及「ruling」（裁定）、「design ledger」（设计台账）一类词汇。同样的几类模式也出现在测试、CSS 注释、生成器模板、CI 注释与 Agent Note 中（「本 PR／本分支／本评审轮」视角、评审编排式的归因、目标其后已经交付却仍写着「推迟到后续 PR」的陈旧说法）。文档标准早已禁止了变更历史这一半（previously/now、PR（Pull Request）与 commit 引用），却没有为引用写下对应的规则，于是无法解析的序号不断落进仓库。
决策
持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 与事故复盘（postmortem）可依文档标准的变更故事归置规则引用已合并的 PR 与 issue 作为证据。
- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 web 输入状态机 note；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
- 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
- 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）符合只描述当前状态的要求；「this cut」这类指示当前版本的标记在任何地方都仍被禁止。
一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（scripts/gen-doc-graphs.ts、scripts/gen-tool-catalog.ts、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码中的 JSDoc（改后重新同步到文档页）以及双语对侧文件（改后重新记录配对）。dsh-trim-cot-leakage 技能把这些规则落地为可执行工作流：审计分类法、已提交的成批召回检索，以及用于判断保留或删除内容的少样本示例。
曾考虑的替代方案
- **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如
\(decision \d、\(audit [A-Z]\d、\bcut \d、this cut、裸\bT\d\b、P-I、used to、裸\bv1\b与§\d——最后一种需排除章节编号有已提交归属的引用，如 web-styling.md 自身的 §N）；对本次清扫自身的评审恰好在这些检索未覆盖的案例中发现残留，因此它们位居候选清单之首。 - **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
验证
审计的成批 grep 检索（英文与中文、注释与行文、对 .agents/ 加 --hidden）在已录制 fixture、已归档 Agent Note、该清理技能自身文件与本笔记引用的证据之外没有命中任何设计序号引用；verify-type-equiv、各 gen-* 新鲜度检查与 verify-translation-pairing 把重新生成与重新记录的表面固定下来。覆盖缺口：没有门禁会拒绝新的序号引用，这条规则由评审把关。
后果
- 注释中的引用凭路径或名称即可解析；读者永远不必为追溯一条引用而重建已关闭的会话。
- 设计会话必须先把决策落进 Agent Note，持久行文才能引用这些决策；序号速记只留在会话内部。
- 引用变长了（用一条 note 路径取代「(decision 21)」），换来的是无需 grep 即可解析。