docs: fix re-review findings — seat-migration obligation, evidence rule moved into the standard, first-cut family settled

Restore the ReactNode seats' pending-migration obligation the earlier
rewrite had flipped into a permanent exception; state the merged-PR/issue
evidence allowance in docs/AGENTS.md itself so the citations note defers
to the standard instead of overriding it; rewrite the one current-state
'first cut' fact and record the historical-stage-name exemption (with
indexical stamps still banned); pairs re-recorded.
This commit is contained in:
Tianyi Cui
2026-08-09 17:46:21 +08:00
parent ee7458b2df
commit e697bb3ca1
8 changed files with 12 additions and 12 deletions

View File

@@ -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: 7d99a27238f25e7084fbbc816787c3c76a62bd89
2026-08-09-committed-artifact-citations.zh.md: f09ae024c480d95dc95e39c62fbd1dc31f5b92a1
2026-08-09-committed-artifact-citations.md: 890555df2968d706ba732aa8a3507bf81d187e3f
2026-08-09-committed-artifact-citations.zh.md: 7eb446cca8fc0109814a8b2669a9a7031db9647b

View File

@@ -12,11 +12,11 @@ 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 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.
- 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](../../../../docs/AGENTS.md)'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](../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.
- 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.

View File

@@ -12,11 +12,11 @@ Status: implemented
持久行文注释、JSDoc、文档、Agent Note、测试注释与测试标题只引用已提交的产物无需 grep 考古即可在仓库内解析:
- 点名归属的 Agent Note其路径在每个文件里至少出现一次行内用可检索的名称、文档页面路径或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列issue 是持久且可引用的Agent Note 还可引用已合并的 PR 作为证据锚点——文档标准将变更故事归置于 commit、PR、Agent Note 与事后分析note 正是这一归宿
- 点名归属的 Agent Note其路径在每个文件里至少出现一次行内用可检索的名称、文档页面路径或 GitHub issue 编号。PR、commit、分支与栈位置依文档标准在文档与代码中仍在禁止之列issue 是持久且可引用的Agent Note 与事后分析可依[文档标准](../../../../docs/AGENTS.md)的变更故事归置规则引用已合并的 PR 与 issue 作为证据
- 决策有已提交归属文档的设计会话序号替换为该决策的名称——曾以「决策 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 不受此约束:已录制的模型输出与封存的历史保持原有行文。
- 已录制的 fixture测试前置数据、快照与已归档的 Agent Note 不受此约束:已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内,历史阶段名称(「首版交付了 X」属于安全的现状表述指示性版本戳「本版」「this cut」在任何地方都仍被禁止。
一次全仓库清理把这些规则应用到了各个行文表面,包括生成器持有的模板(`scripts/gen-doc-graphs.ts``scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语改后重新生成、type-equiv 源码 JSDoc改后把文档页重新粘贴以及双语对侧文件改后重新记录配对