docs: fix review findings — residual ordinals, hypothetical IPC row, citation-rule amendments
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.
This commit is contained in:
Tianyi Cui
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
|
||||
2026-08-09-committed-artifact-citations.md: a34a779977a05b66b1587049ef4a38f0c1cfa0cb
|
||||
2026-08-09-committed-artifact-citations.zh.md: 6eb1810dddfcb38095270d4cdcb00eccef167183
|
||||
2026-08-09-committed-artifact-citations.md: 7d99a27238f25e7084fbbc816787c3c76a62bd89
|
||||
2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
|
||||
|
||||
@@ -12,8 +12,8 @@ Large design and review sessions leave working shorthand — decision ordinals,
|
||||
|
||||
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](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) as the plain-text-reference decision. An ordinal without an owner is deleted and its factual clause restated to stand alone.
|
||||
- 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](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md); 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.
|
||||
@@ -23,7 +23,7 @@ One repo-wide purge applied these rules across the prose surfaces, including the
|
||||
## 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` and `\(audit [A-Z]\d`) is the candidate if the pattern recurs.
|
||||
- **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`, and `P-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
|
||||
|
||||
@@ -12,8 +12,8 @@ Status: implemented
|
||||
|
||||
持久行文（注释、JSDoc、文档、Agent Note、测试注释与测试标题）只引用已提交的产物，无需 grep 考古即可在仓库内解析：
|
||||
|
||||
- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准仍在禁止之列；issue 是持久且可引用的。
|
||||
- 有已提交归属文档的设计会话序号替换为该归属文档的名称：决策 21 即 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md) 中的纯文本引用决策。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
|
||||
- 点名归属的 Agent Note（其路径在每个文件里至少出现一次，行内用可检索的名称）、文档页面路径，或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列；issue 是持久且可引用的，Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析，note 正是这一归宿。
|
||||
- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 21」记录的序号如今是「纯文本引用决策」，归属于 [web 输入状态机 note](../architecture/2026-07-25-web-input-machine-and-slash-pipeline.md)；该序号本身在仓库内无从解析，已全部移除。没有归属文档的序号予以删除，其事实性语句改写为可独立成立的表述。
|
||||
- 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
|
||||
- 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
|
||||
- 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。
|
||||
@@ -23,7 +23,7 @@ Status: implemented
|
||||
## 曾考虑的替代方案
|
||||
|
||||
- **把设计台账与审计文档提交入库，让序号得以解析。**不予采纳：会话 transcript 是工作产物，不是持续维护的参考资料；提交它们会在 Agent Note 之外形成一套平行且不受门禁约束的决策语料，其内部编号也仍会漂移。
|
||||
- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d` 与 `\(audit [A-Z]\d`）。
|
||||
- **为被禁词汇建一道机械门禁。**暂缓：这类词汇是无界的自然语言，审计中以查全为目标的成批检索需要人工判断，才能把泄漏与正当行文区分开（作名词的「wait」、表转折的「actually」、运行时的新旧状态）。若该模式再次出现，候选方案是一道窄而高查准的门禁（例如 `\(decision \d`、`\(audit [A-Z]\d`、`\bcut \d`、`this cut`、裸 `\bT\d\b` 与 `P-I`）；对本次清扫自身的评审恰好在后四种形态中发现残留，因此它们位居候选清单之首。
|
||||
- **删除引用了失效产物的设计理由。**不予采纳：事实性语句都得到保留或改写；依行文标准的完整命题规则，删掉的只有引用、评审编排与推导过程记录。
|
||||
|
||||
## 验证
|
||||
|
||||
Reference in New Issue
Block a user