Skip to content

Commit c0bff72

Browse files
committed
docs(standards): 补登历史文档回写的唯一合法形态
依据 = 控制方的**张力裁决(K,常设)**:「本批文档回写的**唯一合法形态 = 「原文 + 就地加注」**;派单里凡出现「删掉 / 移除 / 改成」这类**字面删改**措辞,**一律按「加注作废 / 加注更正」执行**,并在报告里指出该措辞与 V2 的冲突;**不要**为了迁就措辞去破 V2」(控制方已自陈该要求自相矛盾并登记为控制方错误;T21 的处置被登记为**正例**)+ AGENTS.md §6「规范过时时先改规范」。 形态 = **纯追加**(在 `### 第四部分:文档维护节奏` 与 `### 第五部分:CHANGELOG 规范` 之间**新增一个小节**,既有内容一字未改)⇒ 本提交 **+11 行 / −0 行**。 【逐字对照:改了哪一行 / 原文是什么】 - **位点**:`docs/standards/documentation.md`,`### 第五部分:CHANGELOG 规范` 之前。 - **原文(保留,一字未动)**:`### 第五部分:CHANGELOG 规范` 及其全部正文;第四部分正文(文档即代码原则 / 维护触发点 / 定期审查)**同样一字未动**。 - **加注(新增小节)**:`### 第四部分之补 · 历史文档的回写形态:「原文 + 就地加注」是唯一合法形态(常设;2026-09-13 批 7 落账)`,含: 1. **背景**:规格 / 版本记录 / 台账这类**历史文档**承载审计链 —— 旧文本本身就是证据(「当时是怎么写的」决定后来能不能对上账)。 2. 🔴 **唯一合法形态 = 「原文 + 就地加注」**:**不得**字面删除 / 改写历史句;更正以「🔻 …(原文保留)」块表达,使**原文可读、结论唯一**。 3. 🔴 **机器判据 = 「diff 只有 `+` 行、`−` 列为 0」**(`git diff --numstat` 的删除列 + `git diff` 的 `^-` 行数)⇒ 派单里凡出现「**删掉 / 移除 / 改成**」这类字面删改措辞,**一律按「加注作废 / 加注更正」执行**,并在报告里指出该措辞与该判据的冲突;**不要为迁就措辞去破该判据**。 4. 🔴 **「不改历史原文」不能只看 `numstat` 删除列** —— 回写类单元**必须另做「标题 / 锚逐条对拍」**;并**逐字记录本批的那次事故**(首版误删小节标题,`numstat` 当时读作 `+150/−0`,**掩盖**了删除;靠标题对拍自捉)。 5. **数字与结论必须带时点与来源**:同一指标在不同时点的两个读数**都留**(逐字给本批的例子:「上游时点 578 文件 / 295–299 = 20」→「重跑时点 579 / 21」)+ **差额归因**;**不得**只留一个使历史不可复算。 6. **引述纪律**:入库文档里凡转述他人给的数字 / 路径**必须标明来源**;事后证伪 ⇒ **保留错文 + 就地加注更正**,并**登记「错文曾被入库」这一事实**(逐字给本批的例子:控制方的引述错误被抄进入库文档,随后更正)。 - ⚠️ **机械证明(「只追加」)**:该文件的 `#`–`####` 标题 **HEAD 31 → 工作树 32**,**子序列校验 = 被删或被改 0 处**、**新增恰 1 处**(即本小节标题)。**注意子序列校验的必要性**:按行号逐条对拍时,本次插入会把后续 13 个标题整体下移一格,**看起来像 14 处差异** —— 🔴 **回写类单元的对拍必须用「子序列 / 包含」口径,不能只按同索引比对**(这条本身也补强了上面第 4 点)。 【门禁读数(串行,工作树;与基线逐条对账)】 - `node scripts/docs-check.mjs` ⇒ **exit 0** ·「扫描 **281** / 检查 **181**,五项全 ✅」(**未新增 / 删除 `.md`** ⇒ 扫描数不变)⇒ 与基线 **281/181 逐字一致** - `node scripts/line-limits.mjs --full` ⇒ **exit 0** ·「>600 硬限 **0** · 301–600 档 **121** · 登记条目 **121**」⇒ 与基线**逐字一致** - `node scripts/check-command-registry.mjs` ⇒ **exit 0** ·「定义 **311** / 注册 **311** / 重复 **0**」⇒ 与基线**逐字一致** - `git diff --numstat -- docs/standards/documentation.md` ⇒ **11 / 0**;`git diff` 的 `^-` 行数 = **0** - 行数:`documentation.md` **200 → 211** 【诚实边界】 - 本节把一条**批内裁决**提升为 `docs/standards/` 的**常设规则** —— 依据是 AGENTS.md §6「规范过时时先改规范」与控制方裁决里的「**一般化登记**」逐字;**未**改动本文件任何既有条款。 - 与**上一条提交**(`docs(versions): 更正贴边件漏项计数为一条`)**原子分离**:那条只改 `v0.22`(计数更正 + 两条裁决的批内落账),本条只改 `docs/standards/`(通则)。控制方原话是「一条小提交」⇒ 此处**拆成两条**以满足「**一个提交只做一件事**」,**已在本提交与报告中登记该拆分**。
1 parent 75175a5 commit c0bff72

1 file changed

Lines changed: 11 additions & 0 deletions

File tree

‎docs/standards/documentation.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,17 @@
113113
- 删除过时内容
114114
- 补充缺失内容
115115

116+
### 第四部分之补 · 历史文档的回写形态:**「原文 + 就地加注」是唯一合法形态**(常设;2026-09-13 批 7 落账)
117+
118+
**背景**:规格 / 版本记录 / 台账这类**历史文档**承载审计链 —— 它们的旧文本本身就是证据(「当时是怎么写的」决定了后来能不能对上账)。批 7 的文档回写统一采用 **「原文一字不改 + 就地加注」**:更正、作废、角色变更、状态回退**一律以加注表达**,旧句原样留档。
119+
120+
**规则**:
121+
- 🔴 **唯一合法形态 = 「原文 + 就地加注」**。**不得**字面删除 / 改写历史句;更正以「🔻 …(原文保留)」块表达,使**原文可读、结论唯一**。
122+
- 🔴 **机器判据 = 「diff 只有 `+` 行、`−` 列为 0」**(`git diff --numstat` 的删除列 + `git diff` 的 `^-` 行数)。⇒ 派单里凡出现「**删掉 / 移除 / 改成**」这类**字面删改**措辞,**一律按「加注作废 / 加注更正」执行**,并在报告里指出该措辞与「`−` 列为 0」的冲突。**不要为迁就措辞去破该判据。**
123+
- 🔴 **「不改历史原文」不能只看 `numstat` 删除列** —— 回写类单元**必须另做「标题 / 锚逐条对拍」**(`HEAD` 的 `^#{1,4}\s` 行 vs 工作树逐条比对)。批 7 已发生一次**首版误删小节标题、靠标题对拍自捉**的事故(`numstat` 当时读作 `+150/−0`,**掩盖**了那次删除)。
124+
- **数字与结论必须带时点与来源**:同一指标在不同时点的两个读数**都留**(例:「上游时点 578 文件 / 295–299 = 20」→「重跑时点 579 / 21」),并给出**差额归因**;**不得**只留一个使历史不可复算。
125+
- **引述纪律**:入库文档里凡转述他人给的数字 / 路径,**必须标明来源**;若事后证伪,**保留错文 + 就地加注更正**,并**登记「错文曾被入库」这一事实**(本批已发生一次:控制方的引述错误被逐字抄进入库文档)。
126+
116127
### 第五部分:CHANGELOG 规范
117128

118129
遵循 [Keep a Changelog](https://keepachangelog.com/) 格式:

0 commit comments

Comments
 (0)