refactor(状态规矩): 废除根目录会话状态文件 active.md 与全套执法件(2026-10-18 用户裁)

判据(对 869 个 ZCode 会话与 16 个 Qoder 会话的读写统计):active.md 被整文件读 448 次、
单次中位数 14 KB、累计 6.09 MB 进上下文,311/320 个碰它的会话把它当第一个工具调用读;
但 7311 个提及它的思考片段的语境分布是——写入与编号簿记 327 个会话、并行冲突与避让 234 个、
退役与失真核对 162 个,而明确写「从它所载内容得知某事实」的只有 20 个会话。
逐条核 41 个条目:独特且现行 2 条(另 3 个子句)、别处已有权威源 14 条、陈旧或自相矛盾 7 条、
已完结批次的历史叙述 18 条;按字节约 95% 属后三类。失实样本:architecture 版本记 v1.6 实为 v1.8、
规则文件数记 7 份实为 6 份、迭代 27/28 记「位预留追加卡」而 roadmap 记已完成、三个已删 worktree
仍记「在盘待删」、同一条既宣称「文档禁列闸清单」又自行列出 01–11 全套闸。
执法件已建一轮仍拦不住:08b 体量闸只测条目数/行数/编号/死链,测不出语义失真;钩子不随仓库传播,
只有 ZCode 在跑;10-15 清到 8.6 KB、10-17 回到 40 KB,用户为「只写不删」连续三次发火。

改动面:
- 删 active.md 与 tools/audit_active_state.py;run_all_gates.sh 摘除 08b 闸件与头注、
  baseline.json 删 08b 记录(现存 12 闸)、repo_structure_audit.py 根文件白名单去 active.md
- doc-conventions §10 改写为「仓库根不设状态文件」并留裁决与判据(保持 §11/§12 编号不漂);
  §11 表两行去状态文件口径;§4 适用范围去 active.md
- process-conventions §1 第 2/3 条(合回前查尾号防撞号、豁免面)、§3 第 12 条(批次完成后的
  登记义务)、§6 分级周期口径(闸件清单不再在文档重列)四处换代
- code-conventions「实现批收尾双登记」改为单登记;CLAUDE.md 目录节、规范导航行、worktree 豁免
  行三处换代,红线新增「仓库根禁止设会话状态文件」一条
- roadmap.md 顶部新增「当前位」三行(阶段/迭代位/下一步)接替原快照职责,头注、执行纪律第 3 条、
  loop 规范第 8 条、维护纪律四处改指 06 与本文;reports/README.md 与 sim-data/README.md 两处
  现行指路改口;architecture.md 文档域闸表行去 active.md 体量闸与触发路径
- 06-待办清单迁入七条真残值(原仅载于该文件):卡片入库纪律悬空待办、req-card 两副本取齐、
  魔法道具与罕见残留(实数 23/17 处,旧记约 30/18)、通关口径统一(gdd 内 188 处,旧记 273)、
  黑话第二波待发令、数据整改批九条存疑待抽查(该批未提交面所载)、发布前删除 main.gd:196 调试
  入口写死行(工程直入·待写卡)

harness 侧另批处理(.zcode/ 与用户级技能不入 git):session-snapshot.sh 与 config.json 注册、
worktree-guard.sh 的 active.md 豁免白名单、active-closing 技能、doc-consistency-check 第 8/9 项、
iter 与 req-card 技能里的「唯一例外=active.md」与查尾号条款。
This commit is contained in:
DKChan committed 2026-10-18 07:28:48 +08:00
1 parent 8084527b68
commit 27812167ef
14 files changed
+102 -213

No files matched your search

+5 -5
View File
@@ -7,11 +7,11 @@
## 1. 分支纪律(worktree 铁律)
主工作区(master 检出)只作合并落点与共享状态载体,一切开发/设计改动禁止直接发生在主工作区:
主工作区(master 检出)只作合并落点,一切开发/设计改动禁止直接发生在主工作区:
1. **开工**:每批次先建独立 worktree:`git worktree add ../g-plan2-<任务名> -b <任务分支>`;所有改动与验证都在 worktree 内进行(未跟踪文件不会出现在新 worktree,需手工搬运)
2. **收尾**:迭代 loop 批次验证全绿(冒烟+场景探针)后在主工作区 `git merge --no-ff <任务分支>`,再 `git worktree remove`+删分支;合并前先看 active.md 尾部状态记录,防并行会话撞号/漏捎带;完成按 doc-conventions 第 10 节退役规则删除已完结条目。非 loop 批次默认完成不跑闸(两入口铁规),用户点名或当场问
3. **豁免面**:仅根目录 `active.md`(会话完成)、`.zcode/`(钩子与配置,入库)与 `.qoder/`(本机 harness 配置,gitignored 不入 git,走 worktree 反而带不进去)允许主工作区直改;其余一律走 worktree,主工作区 git commit 被钩子拦截
2. **收尾**:迭代 loop 批次验证全绿(冒烟+场景探针)后在主工作区 `git merge --no-ff <任务分支>`,再 `git worktree remove`+删分支;合回前若 master 已被别的批次推进,先在分支里 `git merge master` 解冲突、重跑本域闸再合回。非 loop 批次默认完成不跑闸(两入口铁规),用户点名或当场问
3. **豁免面**:仅 `.zcode/`(钩子与配置)与 `.qoder/`(本机 harness 配置)允许主工作区直改——两份实测均不入 git(走 worktree 反而带不进去,改动只对本机生效);其余一律走 worktree,主工作区 git commit 被钩子拦截
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底;钩子只约束 agent,用户手工改动不受限
## 2. 五段流水线
@@ -52,7 +52,7 @@
**完成**
10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`,**按本批改动域选档**:本批改动触及 `game/`(游戏工程代码、测试、探针、场景)→ `--code`;不触及 `game/` 的一切改动(`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等)→ `--docs`;同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**,闸件增减、分域调整都只改它;**本文与其他文档禁另列闸件清单**(清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推域强制校验。闸件(`tools/` 下机检脚本与闸壳)自身的改动不占合回全量——其质量义务=落批时的变异验证(test-conventions §6),闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以合回全量为兜底
11. **合并后主区按域复跑**——合并可能引入冲突或环境差异,落回 master 后按本批改动域复跑:触及 `game/` 的批=全量复跑(维持);纯文档域批=复跑文档域档(秒级),不再全量
12. **会话完成落记**——active.md 快照与状态记录更新(含删除已完结旧条目,doc-conventions 第 10 节);跨会话教训写入记忆库;漏删旧条目由 `tools/audit_active_state.py` 在全量档抓(合回闸强制,脚本即清单)。**例外**:active.md 是会话状态唯一源、不是文档产出物,实现批照写(合回闸钩子本就对它放行);`design/` 与根规则文件(`CLAUDE.md`/`roadmap.md`)实现批禁写,见 §13
12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态(做完整条删除),涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代,跨会话教训写记忆库。批次过程与结论由 git 提交信息承载,禁止再写会话状态文件(2026-10-18 用户裁,见 doc-conventions 第 10 节)。`design/` 与根规则文件(`CLAUDE.md`/`roadmap.md`)实现批禁写,见 §13
13. **文档同步闸(2026-10-17 改口径:实现批禁写文档)**——实现批**禁写 `design/` 整个目录与根规则文件**,要往外交代的东西一律落 `reports/`:实现报告 `reports/iter<N>-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务)、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由非迭代批(工具/规则/文档批)写入 `design/`,并把反哺条目从 `reports/` 清掉(吸收即死)。机械面文档(roadmap 行/registry/README 工具注)同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与 06;需求卡片必列「关联文档同步面」按两层标注
14. **实机目检归用户,只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务;禁把等目检当停工理由或完成前置
15. **中间产物吸收即死**——细则见 CLAUDE.md 硬性红线与 doc-conventions 第 11 节
@@ -63,7 +63,7 @@
**MC/verifier 触发细则**:仅在数值验证场景触发(改数值前后取证);normal 档为主、perfect 按需;**无数值改动的会话禁跑 MC**;结构位移类「存档锚」须先向用户请示定性再跑;需求卡片预设步骤的前提消失时(如「带值裁定后重锚」实际未投值)停问勿照字面执行。
**分级周期口径**:全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下(**脚本即清单,且即域划分的唯一出处**),分三档——`--code`/`--docs` 按本批改动域只跑该域闸(代码域=冒烟/单元/探针两档/渲染闸/静态扫描/回放对拍;文档域=gdd_lint/doc_link/doc_term/active.md 体量;熵增闸两域都含);`--quick` 是全量档的中段自检形态(跳过渲染闸与静态扫描);**不带参数=两域全量**,用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿,回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。
**分级周期口径**:全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下(**脚本即清单,且即域划分的唯一出处**),分三档——`--code`/`--docs` 按本批改动域只跑该域闸(闸件清单与域划分只写在脚本头部注释,本文不重列);`--quick` 是全量档的中段自检形态(跳过渲染闸与静态扫描);**不带参数=两域全量**,用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿,回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。
## 5. MC 采集档位细则