docs(harness): 文档体系重构(止血最小集)——两层模型+机器可检蒸馏门

全局 ~/.claude/CLAUDE.md(仓外)退役「每任务 dated review+execution 双档」→两层喂料(WHAT/HOW)+收口蒸馏,增量 deprecate(旧档兼容)。本仓:engineering-conventions §10.6(两层心法/判层/蒸馏门/留痕 frontmatter);wave-close 第5/8步机器可检蒸馏门;AGENTS §2 目标锚去双 roadmap 二义 + §3.3 两层前门索引(模块进度 SoT=总账§2 / 自动记忆界外 / memorys 判死)。评审 CE 5 人格(coherence/feasibility/scope/product/design)压缩至止血最小集,砍两层新目录/新收口门/评审舰队正式替换。WHAT=docs/brainstorms/2026-06-17-文档体系重构-requirements.md;决策记忆 docs-system-hybrid-two-layer(仓外)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-17 16:29:58 +00:00 · 2026-06-17 16:29:58 +00:00 · 15efff4dee
commit 15efff4dee
parent 38729ffdaa
5 changed files with 260 additions and 1 deletions
--- a/.agents/rules/engineering-conventions.md
+++ b/.agents/rules/engineering-conventions.md
@ -273,3 +273,15 @@ subject: 动词开头，简明描述（中英文均可）
 - **与 dated spec 的关系**：dated `review/execution/report`（§10.1）= 某波次工作期过程档；**波次收口时把活内容折进对应子系统 canonical**（wave-close 第 8 步），dated 源档随即 `git rm`（已折入）或 `git mv _archive/`（账本/取证类留参考 + tombstone）。canonical 之外不再久留同主题 dated 流水。
 - **分层（不双写）**：canonical（子系统 SoT·深）＞ `.agents/knowledge/*`（AI 速查一句话·浅）＞ `docs/architecture/` Doc A/B/C + 技术决策版（基线 WHAT/HOW）＞ `docs/mvp/MVP进度总账.md`（跨线状态）。重叠处 canonical 是 SoT，其余留速查 + 指针。
 - **导航**：`docs/agent-specs/_index.md` 列全部 canonical（一域一档）+ 生成域设计链 + KEEP + 归档指针。维护见记忆 `agent-specs-canonical-structure`。
+
+### 10.6 两层阅读心法 + 留痕 frontmatter + 蒸馏门（2026-06-17 文档体系重构立）
+
+> 由来：2026-06-17 文档体系重构（留痕喂料 `docs/brainstorms/2026-06-17-文档体系重构-requirements.md`，决策记忆 `docs-system-hybrid-two-layer`）。把全部文档归两层**阅读心法**（非新目录/标签，映射 §10.5 canonical + §10.1 dated 流水 + CE 的 brainstorms/plans），并补判层规则、留痕最低 frontmatter、机器可检蒸馏门。配套全局 `~/.claude/CLAUDE.md` 已退役「每任务必产 dated 双档」重量级约定。
+
+- **两层（映射现有结构，不新建目录）**：
+  - **策展层（少而准·人读即现行真相）**＝canonical 活档（§10.5）+ `AGENTS.md` §1–2 前门/目标锚 + `docs/architecture/` Doc A/B/C + `docs/mvp/MVP进度总账`（模块进度**唯一 SoT＝其 §2 矩阵**）+ `.agents/`。每个概念在策展层**只有一个 SoT**。
+  - **留痕/笔记层（放开累积·检索而非通读）**＝`docs/agent-specs/` dated `review/execution/report`（§10.1）+ `docs/brainstorms/`（WHAT 喂料）+ `docs/plans/`（HOW 喂料）+ 收口报告 + `_archive/`。允许累积、不强删，靠 git + frontmatter 检索。
+- **判层规则（物理信号，零上下文 agent 据此归层）**：`_index` 标 canonical 的 + `AGENTS`/`docs/architecture`/`docs/mvp` ＝策展；`docs/{brainstorms,plans}` + agent-specs dated `<type>` + `_archive/` ＝留痕。**「孤儿」只针对策展层**（策展 SoT 必须前门一跳可达）；留痕前门不可达＝设计如此，不算孤儿。
+- **蒸馏门（治「更新不及时」的机制，非口号）**：收口若产生留痕（新 brainstorm/plan/report/dated spec），**必须产出「蒸馏 diff」（把可复用洞见提升进策展层 canonical/`.agents`）或显式声明「无可蒸馏＋理由」**（对齐 §10.2 SHIPPED 横幅与回填检查的「不回填＋理由」模式）。落 wave-close 第 5 步。
+- **留痕最低 frontmatter**：新留痕文件头带 `date` / `topic` / `status` / `superseded-by`（被取代时填）；**存量不强制全量回填**（doc-organizer 巡检时按需补 canonical 候选）。
+- **每任务记录约定（取代旧「重量级双档」）**：一任务＝一 WHAT 喂料（需求/brainstorm，`docs/brainstorms/` 或 agent-specs `review`）+ 一 HOW 喂料（plan，`docs/plans/` 或 agent-specs `execution`），轻量、收口蒸馏后留痕；**不再强制每任务产 dated review+execution PAIR + master spec + 分阶段 spec + 固定两轮评审**（旧约定已在全局 prompt 退役为兼容保留）。评审**按风险裁**：高裁量/跨模块才上对抗或多视角评审，机械活不上。
--- a/.agents/skills/wave-close-checklist.md
+++ b/.agents/skills/wave-close-checklist.md
@ -11,9 +11,10 @@
 - [ ] **3. 回填检查（裁定类必做）**：拍板/闸门判定/口径变更须同步修订受影响的蓝图档/蒸馏档/对外档（Doc A/B/C、tech-decisions、glossary、BP 等），或在提交说明显式声明「不回填 + 理由」。（原作战清单回填铁律，2026-06-10 HJ-AUDIT-001）
 - [ ] **4. `.agent` 文件（仅结构变化时）**：新建模块、目录职责/边界变化时更新对应 `.agent`；**纯进度推进不改 `.agent`**（进度一律以总账为准——避免再造「Day-0 横幅」式陈旧）。
 - [ ] **5. 蒸馏**：可复用产出回写 `.agents/`（事实→knowledge / 红线→rules / 配方→skills / 流程→workflows），先查重后新增；**操作配方必须落 `.agents/skills/`，不得只存会话私有记忆**（私有记忆换会话/换 agent/换人即不可见）。
+  - **蒸馏门（2026-06-17 文档体系重构，[`../rules/engineering-conventions.md`](../rules/engineering-conventions.md) §10.6）**：本波若产生留痕（新 brainstorm/plan/report/dated spec），**必须产出「蒸馏 diff」（洞见提升进策展层 canonical/`.agents`）或显式声明「无可蒸馏＋理由」**——杜绝留痕只堆不蒸馏致策展层陈旧（治「更新不及时」）。
 - [ ] **6. 索引同步**：`.agents/` 有结构性变更（增/删/改名）时，同步 `.agents/README.md` 清单 + `AGENTS.md` §5 导航表（两处都要，§5 曾漏更两个 skill）。
 - [ ] **7. 编排资产入库**：本波用过的 Workflow 脚本 / 探针 / 一次性工具入库（对应 spec 目录或编排器目录），收口报告落 `docs/agent-specs/`；确不入库的，在收口报告声明「不入库 + 理由」。
- [ ] **8. 目录退役 + 分层（2026-06-16 目录治理新增，配套 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md) §10）**：本波 `execution`/`edit-plan` 收口后顶部状态横幅翻 `SHIPPED`（被推翻的翻 `SUPERSEDED→替代档`）；**spike 代码 / 批跑证据 / 模型原始输出不入文档树**——结论留 `*.md` 或收口报告，原始件 untracked 或移仓级 `spikes/`（`__pycache__`/`node_modules` 已 gitignore，勿 `git add` 批量 json/png）；**更新 `docs/agent-specs/_index.md` 活地图**（活档清单 + supersede 链 + 归档指针）。目的：杜绝「打过时标不归档」式堆积（治理审计根因）。**+ 一题一活档（§10.4）**：同一任务设计档**收敛成最小自洽集**（典型 1 review + 1 execution），被取代者**同提交**删/归档（演进就地修订、禁「一 pivot 一文件」、禁单独连推过期档）。
+- [ ] **8. 目录退役 + 分层（2026-06-16 目录治理新增，配套 [`../rules/engineering-conventions.md`](../rules/engineering-conventions.md) §10）**：本波 `execution`/`edit-plan` 收口后顶部状态横幅翻 `SHIPPED`（被推翻的翻 `SUPERSEDED→替代档`）；**spike 代码 / 批跑证据 / 模型原始输出不入文档树**——结论留 `*.md` 或收口报告，原始件 untracked 或移仓级 `spikes/`（`__pycache__`/`node_modules` 已 gitignore，勿 `git add` 批量 json/png）；**更新 `docs/agent-specs/_index.md` 活地图**（活档清单 + supersede 链 + 归档指针）。目的：杜绝「打过时标不归档」式堆积（治理审计根因）。**+ 一题一活档（§10.4）**：同一任务设计档**收敛成最小自洽集**（典型 1 review + 1 execution），被取代者**同提交**删/归档（演进就地修订、禁「一 pivot 一文件」、禁单独连推过期档）。**+ 留痕 frontmatter（§10.6）**：新留痕文件（brainstorms/plans/report）头带 `date/topic/status/superseded-by`；留痕原地累积，前门（`AGENTS.md` §3.3）只给检索入口、不逐条挂。

 ## 提交前 30 秒自检

@ -22,4 +23,6 @@
 head -8 docs/mvp/MVP进度总账.md | grep 最近更新
 # 作战清单不应残留已完成项（完成项应已移入归档）
 grep -c "✅" docs/mvp/MVP作战清单.md   # 期望 ≈ 0
+# 本波若新增留痕(brainstorms/plans/report),应有对应蒸馏 diff 或「无可蒸馏」声明(§10.6 蒸馏门)
+git status --short docs/brainstorms docs/plans 2>/dev/null
 ```
--- a/AGENTS.md
+++ b/AGENTS.md
@ -38,6 +38,8 @@ Key quantitative targets:
 > - **Investor edition (HJ-ARCH-002):** **5-person core team + ¥4,300/month infra + 11-week MVP**, emphasizing capital efficiency and window-of-opportunity validation.
 > - **MVP execution spec (HJ-MVP-SPEC-001):** **10 people × 3 weeks (15 working days)**, emphasizing contract-first + five-station parallelism. Acceptance = the **55 P0 product features** in Doc A; workload **≈ 137 technical items**.
 > - Generation success rate: **use the execution spec's ≥80%** (the investor edition gives no direct number). Cite metrics against the corresponding document.
+>
+> **Daily-default = the MVP execution-spec edition** (10 people × 3 weeks / 55 P0 / ≈137 technical items); the investor edition is for external / capital-efficiency framing only, not the day-to-day execution baseline. **This §1–2 IS the single source of truth for the top-level objective anchor** (current MVP objective = the one-line full-chain closed loop above). Detail homes — `docs/mvp/goals.md` (charter), `.agents/knowledge/mvp-scope-and-milestones.md` (55 P0 detail), `docs/agent-specs/战略与合规.md` (moat / compliance) — expand from here via pointer; do not stand up a parallel objective doc.

 ---

@ -76,6 +78,23 @@ games-development-ai/
 └── .agents/                   # Agent capability hub (knowledge/rules/skills/workflows)
 ```

+### 3.3 Two-layer documentation & retrieval (2026-06-17 doc-system refactor)
+
+Docs fall into **two layers** — a reading principle, not new directories (classification / distill-gate rules in [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) §10.6; rationale in `docs/brainstorms/2026-06-17-文档体系重构-requirements.md`):
+
+- **Curated layer (few & current · read it = current truth)** — one SoT per concept:
+  - Top-level objective / positioning → this file §1–2 (the MVP objective anchor)
+  - Product WHAT / technical HOW / mapping → Doc A/B/C (§4 table)
+  - Cross-cutting progress + 13-module completion → `docs/mvp/MVP进度总账.md` (**module progress single SoT = its §2 matrix**)
+  - Each subsystem's current architecture → the canonical living docs under `docs/agent-specs/` (undated topic names; see `_index.md`)
+  - Reusable capability / rules / playbooks → `.agents/`
+- **Trace layer (accumulate freely · retrieve, don't read linearly)** — the front door gives a single retrieval entry, not per-file links:
+  - Design / task feeders: `docs/brainstorms/` (WHAT), `docs/plans/` (HOW), and dated `review/execution/report` under `docs/agent-specs/`
+  - History / evidence: `docs/agent-specs/_archive/`, close-out reports
+  - **Retrieval entry** = `docs/agent-specs/_index.md` (living map) + git grep + frontmatter
+- **Out of bounds**: Claude auto-memory (`~/.claude/projects/.../memory/`, engine-managed · outside the repo · per-session private) — a personal accelerator only; **the repo is the authoritative source**, and anything reusable must be distilled back into `.agents/` to count.
+- **Dead store**: `docs/memorys/` (legacy, read-only, no longer growing; new traces go to `docs/brainstorms/` + `docs/plans/`).
+
 ---

 ## 4. Required Reading Order Before Any Task
--- a/docs/brainstorms/2026-06-17-文档体系重构-requirements.md
+++ b/docs/brainstorms/2026-06-17-文档体系重构-requirements.md
@ -0,0 +1,140 @@
+---
+date: 2026-06-17
+topic: 文档体系重构
+title: 文档体系重构 —— 止血最小集(混合两层·阅读心法)
+---
+
+# 文档体系重构 —— 止血最小集(混合两层·阅读心法)
+
+## 摘要
+
+把文档体系的**止血最小集**做掉:① 改全局 prompt,退役"每任务 dated 双档"约定(流水与陈旧的发动机);② `AGENTS.md` 补全唯一前门索引 + 去重;③ 校准 §1–2 目标锚;④ 清死 store。两层(策展少而准 / 留痕放开检索)作为**阅读心法映射到现有 canonical 结构**,不新建目录/标签;蒸馏桥沿用现有 wave-close 步骤并补一条机器可检最低门。保留自研主干,不整体迁 CE。
+
+---
+
+## 问题背景
+
+四病:散乱、更新不及时、过多(`docs/agent-specs/` 276 文件)、初版目标不清晰。知识散在 `.agents` / `docs/memorys` / Claude 自动记忆 / 收口报告。今天(2026-06-17)的 canonical 重构已把 settled 子系统收成约 7 份活档,但只做了一半(生成域仍 dated 流水,另一 session 收敛中)。
+
+**根因(评审确认的最高杠杆点)= 流程提示词。** 全局 `~/.claude/CLAUDE.md` 的 large-task 协议仍要求每任务产 dated `review.md` + `execution.md` 双档(再加 master spec、分阶段 spec、两轮评审),这是"流水与陈旧"的发动机:产出已转 canonical,流程没改。改它 = 止血;存量整理是低杠杆慢性病,可分批。
+
+CE 曾被议作整体替代:**CE 确缺程序管理层**(`docs/mvp` 闸门/进度账是这种硬日历闸门 MVP 的心跳,CE 把状态推给 git + 外部 tracker);但"CE 无蒸馏"不实——CE 的 `solutions` 层有 `promote`/`refresh`,真正不归档不蒸馏的只是它的 brainstorm/plan **每任务喂料**。故结论 = 混合,不整体迁。
+
+---
+
+## 关键决策
+
+- **止血优先(先关水龙头)。** 改 prompt 是唯一阻止未来文档继续变烂的高杠杆动作;存量整理低杠杆、可分批、可等生成域 session 收敛。本次只做最小止血集。
+
+- **两层是阅读心法,不是新结构。** 策展层 = 现有 canonical/SoT;留痕层 = 现有 `docs/brainstorms`+`plans`+收口报告+`_archive`。映射到今天 canonical 重构已建的结构,不新建标签/目录,避免双命名 churn。
+
+- **混合而非整体 CE(校准版)。** 真因 = CE 缺程序管理层;"CE 无蒸馏"措辞已收窄(CE `solutions` 有 promote/refresh)。结论不变:保留主干,只借 CE 评审人格(试用)、brainstorm→plan 喂料、单锚模式。
+
+- **全局 prompt 增量 deprecate,不硬替换。** 本仓自己是该约定头号依赖方(276 文件 / `_index` / 记忆铁律),且其它项目无法盘点 → 旧双档标 deprecated/兼容,新任务走两层;改写与本仓约定 + 在飞 session 原子同步,避免 split-brain。
+
+- **蒸馏要机制不要口号。** 现有 wave-close 第 5/8 步已有蒸馏却没拦住陈旧 = 证据;补一条机器可检最低门(留痕新增 → 收口必须产"蒸馏 diff 或显式无可蒸馏 + 理由")。
+
+```mermaid
+flowchart TB
+  ENTRY["AGENTS.md:唯一前门索引 + 顶层目标锚(§1-2)"]
+  subgraph CURATED["策展层 · 少而准 · 人读即现行真相"]
+    ABC["Doc A/B/C:产品·模块·映射"]
+    PROG["MVP进度总账(含 §2 模块矩阵)"]
+    CANON["各子系统 canonical 活档"]
+    ADIR[".agents 能力库"]
+  end
+  subgraph TRACE["留痕/笔记层 · 放开累积 · 检索而非通读"]
+    FEED["brainstorms / plans"]
+    REP["收口报告 + _archive(含 census 快照)"]
+  end
+  ENTRY --> CURATED
+  ENTRY -. "检索入口" .-> TRACE
+  TRACE == "收口蒸馏(机器可检门)" ==> CURATED
+```
+
+---
+
+## 需求
+
+**两层 = 阅读心法(不新建结构)**
+
+- R1. 两层映射现有结构,不新建目录/标签:策展层 = 现有 canonical/SoT(`AGENTS.md` 前门、Doc A/B/C、`MVP进度总账`含 §2 模块矩阵、各子系统 canonical、`.agents`);留痕层 = `docs/brainstorms`+`docs/plans`+收口报告+`_archive`(放开累积、检索)。
+- R2. 判层规则(物理信号):`_index` 标 canonical 的 + `AGENTS`/`docs/architecture`/`docs/mvp` = 策展;`docs/{brainstorms,plans}` + agent-specs 非 canonical + `_archive` = 留痕。"孤儿"只针对策展层(策展 SoT 必须前门一跳可达);留痕前门不可达 = 设计如此。
+
+**① 改 prompt(止血)**
+
+- R3. 通盘改写全局 `~/.claude/CLAUDE.md` 的 large-task 协议块(非只挖两词):退役"每任务必产 dated review+execution 双档 + master + 分阶段 spec + 两轮评审",改为两层原理(WHAT/HOW 临时喂料 → 收口蒸馏进策展正典 → 喂料留痕)。
+- R4. 增量 deprecate:旧双档路径标 deprecated/兼容保留,新任务走两层;写法项目无关,本项目特定路径留本仓 `AGENTS.md`。
+- R5. 前置原子条件:改全局前先同步本仓 `engineering-conventions §10` + `_index` 规范 + `wave-needs-review-and-execution-spec-pair` 记忆,并与在飞 session owner 确认不再产新双档;同一原子批次。
+
+**② AGENTS 补索引 + 去重**
+
+- R6. `AGENTS.md` 唯一前门:完整覆盖策展层(逐项指向唯一 SoT)+ 留痕层给单一检索入口(不逐条挂);不新建 master 文档。
+- R7. 去重:同一概念在策展层只有一个 SoT,其余处改一句话 + 指针。
+
+**③ 校准 §1–2 目标锚**
+
+- R8. 不新建锚(§1–2 已是锚):认领唯一目标 SoT,其余目标源(`docs/mvp/goals.md`、总账 §0、`mvp-scope-and-milestones`、`战略与合规`)各归位为一句话 + 指针。
+- R9. 消双 roadmap 二义:日常默认 = 执行版(10 人 3 周),投资人版仅对外;"MVP 现行目标"一句话可答。
+
+**④ 清死 store + 知识归位**
+
+- R10. `docs/memorys` 判死(只读/归档,不再新增;新留痕走 `docs/brainstorms`+`plans`)。
+- R11. Claude 自动记忆划界外:引擎托管、仓外、不可纳管;定位 = 个人会话加速,**仓内为权威源**,有复用价值须蒸馏回 `.agents` 才算数。
+- R12. 真正收敛只 `.agents`(策展)+ 收口报告(留痕);不新增第 5 个 store;`.agents` 维持策展纪律(一主题一档、查重、过时即删)。
+
+**蒸馏与检索(治"更新不及时"的真机制)**
+
+- R13. 蒸馏沿用现有 wave-close 第 5/6/8 步(核对微调,不新增门);补机器可检最低门:本波产生留痕 → 收口须产"蒸馏 diff 或显式无可蒸馏 + 理由"(对齐 §10 第 8 步既有模式)。
+- R14. 留痕检索最低约定:新留痕文件强制 frontmatter 最小字段(`date`/`topic`/`status`/`superseded-by`);存量不全量回填(doc-organizer 巡检按需补);`ce-learnings-researcher` 接入待后议。
+
+**事实归位(修自相矛盾)**
+
+- R15. census(`docs/agent-specs/2026-06-17-产品功能与技术模块-完成度与优先级总账.md`)判为一次性留痕快照(留 agent-specs、dated 合理),不进策展前门;模块完成度策展 SoT = `MVP进度总账 §2`(census 是其功能粒度快照,可被指针引用)。
+- R16. 模块进度唯一家 = `MVP进度总账 §2`;子系统 canonical 的"现状"段只写该子系统设计决策落地状态(并声明"模块真实度见 §2");不依赖不存在的"各模块 `.agent`"。
+
+---
+
+## 成功标准
+
+- 改 prompt 后,新任务不再产 dated review/execution 双档(止血生效)。
+- 前门一跳可达任一策展 SoT;策展层无孤儿、无重复 SoT;判层规则可操作。
+- "MVP 现行目标"一句话可答,§1–2 与总账 §0 / Doc A 一致、双 roadmap 主从明确。
+- `docs/memorys` 不再新增;无第 5 个仓内 store;Claude 自动记忆明确划界外。
+- 留痕新增时,收口产出"蒸馏 diff 或显式无可蒸馏 + 理由"(蒸馏门可检)。
+
+---
+
+## 范围边界
+
+**砍(本次不做):**
+
+- 两层作为新目录/标签体系(只作阅读心法)。
+- 新增收口门(改为核对微调现有 wave-close 第 5/6/8 步)。
+- CE 评审舰队"正式替代"现有评审(本次只借用试跑;是否替代另开独立决策,不 supersede `review-prefer-codex-xhigh` / `impl-review-one-opus-round`)。
+
+**推迟:**
+
+- 全部文档逐项归两层 + 知识大迁移 → 交 `doc-organizer` 巡检分批,等生成域 session 收敛。
+- census 是否提升为策展层;存量 141 档 frontmatter 回填范围;`ce-learnings-researcher` 接入。
+
+**拒绝(不变):** 不外迁 GitHub Issues、不退役自研主干、不整体迁 CE。
+
+---
+
+## 依赖与假设
+
+- **多 session 枢纽协调:** `AGENTS.md` / `.agents/README` / `_index` / `wave-close-checklist` 是双 session 共享枢纽 → 改动串行 / 最小 diff / 落地前同步在飞 session 进度(对齐"独占资源串行")。
+- **全局 prompt 是显式承担的已知风险**(非已消除):其它项目无法盘点 → 增量 deprecate 兜底。
+- **Claude 自动记忆仓外不可纳管**(见 R11)。
+- **本文档 = 留痕喂料:** 收口时其决策蒸馏进 harness(`AGENTS.md` / `.agents`)+ 全局 prompt;此为一次性元任务,区别于常规收口蒸馏(常规只进 canonical/`.agents`,不含全局 prompt)。
+
+---
+
+## 待定问题
+
+**可留到规划阶段:**
+
+- 全局 large-task 协议块的具体改写文本(与第 55–69 行咬合的两轮评审/master spec 段一并通盘改)。
+- census 最终去留(留痕快照 vs 提升策展)。
+- 存量 frontmatter 回填范围与 `ce-learnings-researcher` 是否接入。
--- a/docs/plans/2026-06-17-文档体系重构-plan.md
+++ b/docs/plans/2026-06-17-文档体系重构-plan.md
@ -0,0 +1,85 @@
+---
+date: 2026-06-17
+topic: 文档体系重构
+type: execution
+status: shipped
+origin: docs/brainstorms/2026-06-17-文档体系重构-requirements.md
+title: 文档体系重构(止血最小集)执行计划
+---
+
+# 文档体系重构(止血最小集)执行计划
+
+> WHAT 见 `origin` 需求文档。本文件是 HOW:执行序、改哪些文件、验证、回滚。
+> 本计划本身是**留痕喂料**(两层模型留痕层);收口时蒸馏入 harness 后留痕。
+
+## 目标与范围
+
+落地需求文档的 4 个动作(① 改全局 prompt ② AGENTS 补索引去重 ③ 校准 §1-2 锚 ④ 清死 store)+ 评审高置信修正。**不做**:两层新目录/标签、新收口门、评审舰队正式替换、全量文档归两层(推迟给 doc-organizer)。
+
+## 涉及文件
+
+| 文件 | 动作 | 层 |
+|---|---|---|
+| `~/.claude/CLAUDE.md`(全局,第 ~55–69 行 large-task 协议块) | 通盘改写为两层 + 增量 deprecate | 跨项目契约 |
+| `AGENTS.md` §1–2 / §3–5 | 锚校准 + 前门索引去重 | 策展枢纽 |
+| `.agents/rules/engineering-conventions.md` §10 | 退役双档规则 + 落两层/判层/frontmatter/蒸馏门 | 策展枢纽 |
+| `.agents/skills/wave-close-checklist.md` 第 5/6/8 步 | 核对微调 + 留痕归位 + 机器可检蒸馏门 | 策展枢纽 |
+| `docs/agent-specs/_index.md` | census 标留痕快照 + 留痕检索入口登记 | 策展枢纽 |
+| `docs/mvp/MVP进度总账.md` §2 / 各子系统 canonical「现状」段 | 措辞对齐(模块进度唯一 SoT=§2) | 策展 |
+| `docs/memorys/` | 判死标注(只读) | 留痕 |
+| 记忆 `wave-needs-review-and-execution-spec-pair` | 改两层喂料口径 | 仓外记忆 |
+
+> ⚠️ `AGENTS.md` / `.agents/README` / `_index.md` / `wave-close-checklist.md` 是**双 session 共享枢纽**——见 Phase 0。
+
+## 执行序
+
+### Phase 0 — 协调与前置(不改文件)
+- P0-1. 与在飞 session owner 确认:(a) 改上述枢纽文件的时间窗(串行,避免 push 撞车);(b) 其生成域设计链**不再产新 dated 双档**(否则全局改后 split-brain)。
+- P0-2. 草拟全局 prompt 新「large-task 协议块」文本(覆盖 R3/R4:两层原理 + 旧双档标 deprecated/兼容),**先交创始人过目**;未获 OK 不进 Phase 2。
+
+### Phase 1 — 本仓策展层与规范(枢纽文件,与在飞 session 串行,单批次)
+- P1-1. `engineering-conventions §10`:退役「每任务 dated review+execution 双档」规则;落两层原理 + 判层规则(R2)+ 留痕最低 frontmatter `date/topic/status/superseded-by`(R14)+ 机器可检蒸馏门(R13)。
+- P1-2. `wave-close-checklist` 第 5/6/8 步:核对微调,补「留痕归位」+「收口须产蒸馏 diff 或显式『无可蒸馏+理由』」(R13);**不新增步**。
+- P1-3. `AGENTS.md` §1–2:认领唯一目标 SoT,goals.md/总账§0/mvp-scope/战略与合规 各归位为一句 + 指针;消双 roadmap 二义(日常默认=执行版)(R8/R9)。
+- P1-4. `AGENTS.md` §3–5:补唯一前门索引——策展层逐项指向 SoT + 留痕层单一检索入口(不逐条挂)+ 判层规则(R6/R7)。
+- P1-5. `docs/memorys` 判死(只读,前门给检索入口,R10);`AGENTS`/`.agents` 注明 Claude 自动记忆界外、仓内权威(R11)。
+- P1-6. census 归位:`_index`/前门标其为留痕快照(R15);`MVP进度总账 §2` 定为模块进度唯一 SoT,子系统 canonical「现状」段措辞改为「只写本子系统设计落地状态,模块真实度见 §2」(R16);删任何「各模块 .agent 记进度」表述。
+- P1-7. 更新记忆 `wave-needs-review-and-execution-spec-pair` 为两层喂料口径。
+
+### Phase 2 — 全局 prompt(原子,Phase 1 同批次收尾)
+- P2-1. 创始人 OK 后,改全局 `~/.claude/CLAUDE.md` large-task 协议块(通盘,含与之咬合的两轮评审/master/分阶段段)为两层 + 增量 deprecate。
+
+### Phase 3 — 验证(对成功标准)
+- 模拟一个新任务流:确认不再要求产 dated 双档(止血生效)。
+- 前门一跳可达性自检:策展 SoT 无孤儿、无重复。
+- 「MVP 现行目标」一句话可答,§1–2 与总账§0/Doc A 一致。
+- `docs/memorys` 无新增;无第 5 个仓内 store;自动记忆界外声明在位。
+- 蒸馏门:造一个留痕新增场景,确认收口要求「蒸馏 diff 或显式无可蒸馏+理由」。
+
+### Phase 4 — 收口蒸馏 + 留痕归档
+- 本 brainstorm + 本 plan 作留痕喂料;蒸馏已入 harness;`_index`/前门登记其留痕检索入口;决策记忆已落 `docs-system-hybrid-two-layer.md`。
+
+## 边界失败路径
+- 在飞 session 拒绝串行/时间窗冲突 → Phase 1 推迟,先单独做 Phase 2 的草拟(不落盘)。
+- 创始人不批全局新文本 → Phase 2 挂起,Phase 1 本仓改动仍可独立完成(本仓 AGENTS 优先级高于全局)。
+
+## 验证方法
+每 Phase 后:`git diff` 自检 + 上述成功标准逐条勾。本仓 harness 改动不涉编译;若触及构建相关另按 `staging-ops` 冒烟门(本次预计不涉)。
+
+## 完成条件
+4 动作落地 + 成功标准全过 + 留痕归档 + 决策记忆在位。
+
+## 回滚策略
+- 每 Phase 独立 commit;全局 prompt 改动**单独 commit**便于单独 revert。
+- 增量 deprecate ⇒ 旧约定兼容保留,回滚=把旧段恢复为推荐路径,无破坏性。
+- 多 session:push 前按 `[[multi-session-shared-tree-push-conflict]]` 配方处理撞车(find 挪走别人 untracked,再 rebase+push)。
+
+## 收口（2026-06-17 · SHIPPED）
+
+止血最小集已落工作树并验证绿:
+- 全局 `~/.claude/CLAUDE.md` 退役 dated 双档 → 两层喂料(增量 deprecate,旧档兼容)。
+- 本仓:`engineering-conventions §10.6`(两层心法/判层/蒸馏门/frontmatter)、`wave-close` 第 5/8 步机器可检蒸馏门、`AGENTS §2` 目标锚去双 roadmap 二义 + `§3.3` 两层前门索引(模块进度 SoT=总账§2 / 自动记忆界外 / memorys 判死)。
+- 决策蒸馏入记忆 `docs-system-hybrid-two-layer`。
+- 验证:全局旧双档段 0 残留 + 两层段在;本仓三件 grep 全中。
+
+**待选择性提交**:仅 stage 本任务 5 处(conventions/wave-close/AGENTS + 新 brainstorm/plan),**排除**另一 session 在飞的生成域「固定游戏架构-SAA」档。推迟项(全量归两层 / census 提升 / frontmatter 回填 / `ce-learnings-researcher` 接入)交 `doc-organizer` 巡检分批。