docs(acm2-74): consolidate design documentation

docs/README.md

@@ -1,61 +1,77 @@
 # 设计文档入口
 
-实现核对日期：2026-09-11（代码基线以 `git log -- docs/` 为准）。文档描述**目标设计**，不等于已实现；测试通过不等于现场已发布。进度与缺口在 Plane（ACM2）跟踪；文档只记录「对外主张当前是否可声明」，见 [invariants.md](invariants.md) 声明边界。
+`docs/` 是本系统目标设计的唯一依据：只记录「设计是什么」与「对外主张当前是否可声明」。实现进度、缺口处置与排期在 Plane（ACM2），不在本文档体系内。
 
-## 1. 按读者选入口
-
-| 你是谁 | 从哪读起 |
-|---|---|
-| 新开发者 | [invariants.md](invariants.md)（前提 / 不变量 / 声明边界）→ [design.md](design.md)（机制）→ [reference.md](reference.md)（参数 / 指标 / 模块） |
-| 库方 / 上游接口人 | [contracts.md](contracts.md)（条款 `C-x` 与待确认 `Q`） |
-| 值班主任 / 运维 | [reference.md](reference.md)（参数与指标）→ [invariants.md](invariants.md)（哪些主张当前不可声明）。执行规程在上线/切流前另立，设计阶段只保留前置条件与红线 |
-| 评审 / PR 作者 | [invariants.md](invariants.md) + 本文 §5 评审清单 |
-
-## 2. 文档职责（一个事实只有一处定义）
+## 1. 文档职责（一个事实只有一处定义）
 
 | 文档 | 唯一职责 |
 |---|---|
-| [architecture.md](architecture.md) | 系统边界、模块职责、存储归属、架构决策（D1–D4）。 |
-| [invariants.md](invariants.md) | 前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、验证映射。 |
-| [design.md](design.md) | 管道机制：收报·水位、主泵·处理·事务边界、回填、投递、作业与归档。 |
-| [contracts.md](contracts.md) | 对外承诺与要求（`C-x`）、待确认事项（`Q`）。 |
-| [reference.md](reference.md) | 参数注册表、指标与健康、模块入口、错误分类。 |
-| [flight-state.md](flight-state.md) | 航班域模型与合并语义。 |
-| [user-stories.md](user-stories.md) | US / OPS 验收目标。 |
-| [legacy/](legacy/) | 现役行为基线与外部协议事实（[SIS 规范](legacy/SIS_AODB_RMS-V0.1.md)、[XSD](legacy/unisysaodbsis.xsd)）。外部协议事实（报文结构、字段语义、上游行为）以 SIS/XSD 为准；legacy 现役行为只是基线，已知缺陷不作依据；与本系统目标设计的已知差异见 `C-25`/`C-26`，确认状态见 `Q13`/`Q14`。 |
+| [README.md](README.md) | 入口、阅读顺序、文件职责、事实归属、ID 语法与引用纪律。 |
+| [requirements.md](requirements.md) | 阶段范围与非目标、`US-xx` / `OPS-x` 验收目标、需求覆盖与依赖。 |
+| [architecture.md](architecture.md) | 系统边界、模块职责、存储归属、总体流程与 `D1`–`D4` 决策。 |
+| [specification.md](specification.md) | 术语、外部契约 `C-x`、前提 `PRE-x`、不变量 `INV-x`、声明边界 `CLM-x`、待确认 `Qn`、当前已知偏差 `G-NAME`、验证映射。 |
+| [implementation.md](implementation.md) | 数据模型、状态机、管道机制、事务、投递、作业与恢复；航班域权威模型与合并语义。 |
+| [reference.md](reference.md) | 参数 `PARAM:<key>`、指标与健康、模块与代码入口、错误分类。 |
+| [legacy/](legacy/) | 外部协议与旧系统基线：现役行为对拍、[SIS 规范](legacy/SIS_AODB_RMS-V0.1.md)、[XSD](legacy/unisysaodbsis.xsd)、[历史决策记录](legacy/decision-flight-state-history.md)。外部协议事实（报文结构、字段语义、上游行为）以 SIS/XSD 为准；legacy 现役行为只是基线，已知缺陷不作依据。 |
+
+## 2. 按读者选入口
+
+| 你是谁 | 从哪读起 |
+|---|---|
+| 新开发者 | [specification.md](specification.md)（前提 / 不变量 / 声明边界）→ [implementation.md](implementation.md)（机制与航班域）→ [reference.md](reference.md)（参数 / 指标 / 代码入口） |
+| 库方 / 上游接口人 | [specification.md](specification.md)（`C-x` 与 `Q`） |
+| 值班主任 / 运维 | [reference.md](reference.md)（参数与指标）→ [specification.md](specification.md)（哪些主张当前不可声明）。执行规程在上线/切流前另立（`docs/runbooks/`），设计阶段只保留前置条件与红线 |
+| 评审 / PR 作者 | [specification.md](specification.md) + 本文「维护清单」 |
 
 ## 3. 事实归属表
 
 | 事实 | 唯一归属 | 其他文档怎么写 |
 |---|---|---|
-| 水位 `W`、空洞判定与推进条件 | design「收报与水位」 | contracts 写对库方的承诺 `C-1`–`C-3`；reference 写参数 |
-| 保留期下界 `R_keep`、清除前置条件 | contracts「保留与清除」 | design 只引 `C-x`；执行步骤在上线前另立 |
-| 处理标记值集与写权限 | contracts `C-5` | design 只写行为约束「只写空标记、不回撤、不覆盖」（`INV-7`） |
-| 回填四结果、放弃语义、`R` 的作用 | design「回填」 | invariants 记结论与可声明性 |
-| 退避 / `claim-batch` / 回填期限等取值 | reference「参数」 | design 只引 `PARAM:x` |
-| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | invariants「前提」 | 其他文档只引 `PRE-x` |
-| 航班身份、合并语义、`STATE_VERSION`、`OPERATION_DAY` | flight-state.md | design 只引域规则 |
-| 对外术语（落信 / 入站 / 库方 / 处理标记） | contracts「术语」 | — |
+| 水位 `W`、空洞判定与推进条件 | implementation.md「收报与水位」 | specification.md 写对库方的承诺 `C-1`–`C-3`；reference.md 写参数 |
+| 保留期下界 `R_keep`、清除前置条件 | specification.md「契约」 | implementation.md 只写行为约束；执行步骤在上线前另立 |
+| 处理标记值集与写权限 | specification.md `C-5` | implementation.md 只写行为约束「只写空标记、不回撤、不覆盖」（`INV-7`） |
+| 回填四结果、放弃语义、`R` 的作用 | implementation.md「回填」 | specification.md 记结论与可声明性 |
+| 退避 / `claim-batch` / 回填期限等取值 | reference.md「参数」 | 其余文档只引 `PARAM:<key>` |
+| 消费权排他、ID 不复位、报文不可变、时钟、单实例 | specification.md「前提」 | 其他文档只引 `PRE-x` |
+| 航班身份、合并语义、`STATE_VERSION`、`OPERATION_DAY` | implementation.md「航班域」 | 其余文档只引域规则与 `INV-x` |
+| 对外术语（落信 / 入站 / 库方 / 处理标记） | specification.md「术语」 | — |
+| 管道内部术语（`W` / 队头 / 终态 / 回填意图） | implementation.md「术语与持久化记录」 | — |
 
-## 4. 引用与写作纪律
+## 4. ID 定义语法与引用纪律
 
-1. **引用只用稳定 ID**：`PRE-x`、`INV-x`、`CLM-x`、`C-x`、`D-x`、`OPS-x`、`PARAM:x`、`[G-x]`、`[Q-x]`、`US-xx`、`ACM2-nn`。**不再用章节号做跨文档引用。**
-   本条取代旧版 README 的「其他文档引用章节号」规则：章节号随增删章节腐烂，指针失效后必然被改写为复述——重构前实测有 30 处「唯一定义处」与 33 处跨文档章节引用。
-2. 指针之后**不再复述**被指内容。若两处需要同一段话，说明它放错了位置。
-3. 文档不记进度，只记「主张是否可对外声明」。进度在 Plane。
-4. 机制段只写「是什么 / 为什么」。验收 → invariants 验证映射；前置条件、红线与库方方案 → contracts / invariants；参数默认值 → reference；操作步骤在上线/切流前另立规程，设计阶段不写。一句话一个主张；只强调关键结论，避免整段加粗。
-5. 数值只有两个家：参数默认值与指标名在 reference.md；契约数值（保留期、值集、下界）在 contracts.md。
+**持久规范 ID 族**：`US-nn`、`OPS-n`、`Dn`、`C-n`、`PRE-n`、`INV-n`、`CLM-n`、`Qn`、`G-NAME`、`PARAM:<key>`。
+
+- 定义只能出现在所属文件，并采用固定语法：
+  - `US-xx` 用三级标题（`### US-01 …`）；
+  - `C-x`、`INV-x` 用加粗定义行（`- **C-5** …`）；
+  - `CLM-n`、`OPS-n`、`Dn`、`PRE-n`、`Qn`、`G-NAME` 与 `PARAM:<key>` 用注册表首列；首列必须是**单个裸 ID**
+    （`` `ID` `` 或 `ID`）。成组登记（`` `a` / `b` ``）、带括注的首列与写成 `` `ID` `` 的引用行都不算定义。
+  - 同一行登记多个 ID（如验证映射的 `INV-20 / CLM-3`）是引用行，不构成定义。
+  其他位置一律是引用。
+- 编号稳定：条款被取代时标 `[作废 by C-y]` 并保留原文；不静默改写，不重编号。
+- **引用只用稳定 ID**，不用章节号：写 `INV-3`、`C-8`、`PARAM:msgx.pipeline.claim-batch`，或「见 implementation.md『收报与水位』」这类文件名 + 小节名指针。章节号随增删章节腐烂，指针失效后必然被改写为复述。
+- 指针之后**不再复述**被指内容。若两处需要同一段话，说明它放错了位置。
+- 外部 SIS 证据统一写 `SIS:<section>`（如 `SIS:3.16-note-4`），解析到 [legacy/SIS_AODB_RMS-V0.1.md](legacy/SIS_AODB_RMS-V0.1.md) 的章节；它不属于本项目规范 ID，不参与唯一定义检查。
+- `G-NAME` 是活跃偏差 ID：定义只在 specification.md「当前已知偏差」注册表，其他位置只写标记；偏差闭合时在同一变更中删除定义与全仓引用，历史与关闭证据只留 Plane。
+
+**数值只有两个家**：参数默认值与指标名在 reference.md；契约数值（保留期、值集、下界）在 specification.md。
+
+**文档不记进度**：不写日期式状态、完成记录与 changelog；只记「主张是否可对外声明」（`CLM-x`）。
 
 ## 5. 维护清单
 
-**Q 答复落地（4 步）**：① 在 contracts.md 就地补结论与日期 → ② 改 reference.md 的默认值与「依据」列 → ③ 机制有变才改 design.md → ④ 在 invariants.md 的 CLM 上划掉挂起。
+**Q 答复落地（4 步）**：① 在 specification.md 就地补结论与日期 → ② 改 reference.md 的默认值与「依据」列 → ③ 机制有变才改 implementation.md → ④ 在 specification.md 的 CLM 上划掉挂起。
+
+**偏差闭合**：在 specification.md 删除该 `G` 定义，并删除全仓 `G-NAME` 引用；关闭证据留在 Plane。
 
 **PR 评审 4 问**：新事实是否已有归属？是否复述了别处？是否用了稳定 ID？是否把运维 / 验收写进了机制段？
 
-**尺寸触发器**：design.md 超过约 800 行才按子系统再拆；invariants.md 超过两页先怀疑混进了机制。
+**日常维护**：运行 `scripts/check-docs.sh`，校验顶层六文件、ID 定义唯一性与全仓引用、旧文件名与章节号零命中、活跃 `G`、仓库内链接。合并或重命名文档时传入迁移前 Git 基线（`scripts/check-docs.sh <基线>`），额外比较持久 ID 与活跃 `G` 集合。
 
-## 6. 当前状态
+**尺寸触发器**：implementation.md 的管道与航班域两章各自超过约 500 行才考虑拆入 `docs/` 专题目录。
 
-- 2026-09-11 文档体系重构：新增 invariants.md / contracts.md / reference.md；design.md 由 design.md + message-lifecycle.md 合并，后者于 2026-09-12 删除（内容已全部并入 design.md）；跨文档引用由章节号改为稳定 ID。
-- 不建 runbooks.md：设计阶段没有可执行的运行环境，操作步骤在上线/切流前另立（见 Plane ACM2-48）；设计阶段需要的只有前置条件与红线，它们分别在 contracts（`C-7`–`C-12`）与 invariants（CLM-x）。
-- 目标设计与交付状态分离：未交付、未确认、不可声明的主张见 invariants.md 的声明边界与 Plane ACM2，不在正文里逐段标注。
+## 6. 不建的文件
+
+- 顶层不再增加 Markdown：`docs/` 顶层固定为上述 6 个文件加允许的专题目录。
+- 不建运行规程文件：设计阶段没有可执行的运行环境，操作步骤在上线/切流前另立（`docs/runbooks/*.md`）；设计阶段需要的只有前置条件与红线，它们分别在 specification.md（`C-7`–`C-12`）与 specification.md 的 `CLM-x`。
+- 声明边界与 Plane 分离：未交付、未确认、不可声明的主张记在 specification.md，逐项处置在 Plane（ACM2），不在正文逐段标注。