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:
1 parent
8084527b68
commit
27812167ef
14 files changed
+102
-213
No files matched your search
@@ -196,7 +196,7 @@
|
||||
| 域 | 闸 | 本批改动落在这些路径即属该域 |
|
||||
|---|---|---|
|
||||
| **代码域** | run_smoke、run_all、probe_gate `--click`、probe_gate `--full`、render_gate、static_scan、回放确定性对拍(条件件) | `game/`、`tools/`、`artwork/` |
|
||||
| **文档域** | gdd_lint、doc_link_audit、doc_term_audit、active.md 体量闸 | `design/`、`active.md`、`roadmap.md`、`CLAUDE.md` |
|
||||
| **文档域** | gdd_lint、doc_link_audit、doc_term_audit、流水线闸 | `design/`、`roadmap.md`、`CLAUDE.md` |
|
||||
| **两域都含** | repo_structure_audit(熵增闸:顶层目录/根文件/图像白名单/退役路径/design 子目录五查——文档批新增或挪动 `.md` 同样会绊它;纯文本扫描秒级) | — |
|
||||
|
||||
口径三条:**域划分的唯一出处是 `tools/run_all_gates.sh`**(`--code`/`--docs`/不带参数=全量),本表是它的现状登记、不是第二份清单;改闸件本身或一次改动跨两域 → 跑全量档(§6.2 共享件例外);合回闸按 merge diff 路径推出应验的域,再校验回执的 `domain` 字段与新增红。代码域跑前先过**素材齐盘预检**——`game/assets/art/**` 与一切 `*.import` 边车都不入 git(2026-09-29 裁定),worktree 冷检出必空盘,空盘态冒烟 V1 成片假红、渲染闸更是一段 golden 都不比。
|
||||
|
||||
@@ -96,5 +96,5 @@
|
||||
## 6. 流程纪律
|
||||
|
||||
1. **大改动三段走**:设计稿/伪代码 → 用户审阅 → 实现;实现禁止先于审阅。修改记录落切片 README。
|
||||
2. **实现批收尾双登记**:切片 README 修改记录 + 根目录 `active.md` 条目(会话状态唯一状态源),缺一不可。
|
||||
2. **实现批完成后的登记义务**:切片 README 写修改记录,06 条目按 doc-conventions §12.1 推进状态,批次过程与结论进 git 提交信息与 `reports/`(2026-10-18 用户裁:根目录会话状态文件已废除,禁止再在其中登记条目)。
|
||||
3. **呈现层缺陷的教训回写 D1 GDD 设计输入**(信号载荷 schema / 场景级测试 / 时点状态可见性)。
|
||||
@@ -1,7 +1,7 @@
|
||||
# 文档写作规范(写文档前必读)
|
||||
|
||||
> **地位**:本文是文档写作的规范权威,与 `design/dev/code-conventions.md`(代码规范)对等;CLAUDE.md 只留导航指针,细则以本文为准。
|
||||
> **适用范围**:`design/` 下一切现行文档、根目录 `active.md` 与 `roadmap.md`;概念建模与跨文档引用见 `design/dev/concept-conventions.md`。
|
||||
> **适用范围**:`design/` 下一切现行文档与根目录 `roadmap.md`;概念建模与跨文档引用见 `design/dev/concept-conventions.md`。
|
||||
|
||||
## 0. 总纲
|
||||
|
||||
@@ -96,11 +96,11 @@
|
||||
|
||||
## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/dev/concept-conventions.md`
|
||||
|
||||
## 10. 会话记录纪律
|
||||
## 10. 会话状态——仓库根不设状态文件
|
||||
|
||||
**active.md 定性:状态文件——状态记录,不是工作日志。** 根目录 `active.md` 是会话状态的唯一状态源,**每一行当下为真**;历史归 git 提交史。只许写三类:①当前状态快照(≤10 条滚动窗口);②未决面(进行中批次/待人闸/待裁点指针);③当前迭代滚动工作条目。禁止写入:已完结批次的历史叙述、待办裁决事项(归 06)、跨会话教训(归记忆库);并行会话禁止整体复原/回退本文件。退役规则:**用户确认任务完成时清除当前会话写过的状态条目——状态清除即任务完成的证明**;条目完结判据=批次已入库+结论已进快照+未决面无条目指向;迭代收口兜底删除已完结条目,超过 30 条必须清。**机械闸**=`tools/audit_active_state.py`,判四条可机械测的膨胀签名(条目数上限、快照行数上限、条目编号重复、指向中间文档的死指针),随 `tools/run_all_gates.sh` 全量档跑并由合回闸强制——收口漏删旧条目,合回时会被拦下。
|
||||
**2026-10-18 用户裁:根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计:整文件被读 448 次、平均每次 14 KB 进上下文,但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上,明确写「从它所载内容得知某事实」的只有 20 个会话;文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链,测不出语义失真:10-15 清到 8.6 KB/3 条,10-17 已回到 40 KB,用户为「只写不删」连续三次发火,规矩照样失效。
|
||||
|
||||
条目用完整白话句子写清结论本身,长度服从可读性(能看懂比字数少重要);禁把定稿摘要、义务清单整段搬进条目(详情归权威文档);第 4 节用语纪律对状态记录同等生效;条目记裁决结论本身,不记中间文档文件指针(见第 11 节)。
|
||||
废除后的分工:**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节;**待办与待裁**看 [06-待办清单](../gdd/06-待办清单.md)(唯一登记处);**批次过程与结论**看 git 提交信息与 `reports/`;**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件,也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移,这正是本次统计查出七条失实陈述的成因。
|
||||
|
||||
## 11. 文档生命周期:吸收即死
|
||||
|
||||
@@ -111,8 +111,8 @@
|
||||
| 吸收即死 | 中间文档结论写进权威文档(GDD 对应节/art-bible/registry)那一刻,文件即删 |
|
||||
| 未决先迁再死 | 未决内容先迁现行事实源(06/roadmap 卡/GDD 对应节),然后文档即死 |
|
||||
| 永不入库 | 迭代出口后中间产物一律删除且不许提交;迭代进行中可暂存工作区,出口批一并清 |
|
||||
| 引用面口径 | 活文档对中间文档的指路阻塞删除:先改写指路句为结论内联或 git 提交号再删;active.md 状态记录引用不阻塞 |
|
||||
| 状态记录记结论 | 条目记裁决结论本身不记中间文档指针;中间文档删除后不留死链指针 |
|
||||
| 引用面口径 | 活文档对中间文档的指路阻塞删除:先改写指路句为结论内联或 git 提交号再删 |
|
||||
| 删除不留死链 | 中间文档删除后,任何现行文档禁止再留指向它的文件路径;改指结论或提交号 |
|
||||
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md;可再生原始数据不入库 |
|
||||
| 出口清理项 | 每迭代出口检查单必含:本迭代中间产物逐份核对(结论已吸收、未决已迁移)后删除 |
|
||||
| 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档暂存地,入内文件默认到期即死 |
|
||||
|
||||
@@ -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 采集档位细则
|
||||
|
||||
|
||||
Reference in new issue
Block a user