From 27812167ef8dc9728d3956828abb9a0dd4993f63 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 18 Oct 2026 07:28:48 +0800 Subject: [PATCH] =?UTF-8?q?refactor(=E7=8A=B6=E6=80=81=E8=A7=84=E7=9F=A9):?= =?UTF-8?q?=20=E5=BA=9F=E9=99=A4=E6=A0=B9=E7=9B=AE=E5=BD=95=E4=BC=9A?= =?UTF-8?q?=E8=AF=9D=E7=8A=B6=E6=80=81=E6=96=87=E4=BB=B6=20active.md=20?= =?UTF-8?q?=E4=B8=8E=E5=85=A8=E5=A5=97=E6=89=A7=E6=B3=95=E4=BB=B6=EF=BC=88?= =?UTF-8?q?2026-10-18=20=E7=94=A8=E6=88=B7=E8=A3=81=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 判据（对 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」与查尾号条款。 --- CLAUDE.md | 7 +- active.md | 63 ------------- design/dev/architecture/architecture.md | 2 +- design/dev/code-conventions.md | 2 +- design/dev/doc-conventions.md | 12 +-- design/dev/process-conventions.md | 10 +- design/gdd/06-待办清单.md | 71 ++++++++++++++ game/tests/.gates/baseline.json | 4 - reports/README.md | 2 +- roadmap.md | 14 ++- sim-data/README.md | 2 +- tools/audit_active_state.py | 120 ------------------------ tools/repo_structure_audit.py | 2 +- tools/run_all_gates.sh | 4 +- 14 files changed, 102 insertions(+), 213 deletions(-) delete mode 100644 active.md delete mode 100644 tools/audit_active_state.py diff --git a/CLAUDE.md b/CLAUDE.md index 8dd957fe..227da653 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,7 +34,7 @@ - `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑 - `tools/` — python 工具脚本；`archive/` — 收口归档 zip（gitignored） - `reports/` — 迭代批产出物（实现报告/代拍板追认单/GDD 反哺点清单）；**实现批唯一可写目录**，只放 .md，不是事实源（细则见 `reports/README.md`） -- 根目录：`active.md`（会话状态唯一状态源，退役规则见 doc-conventions 第 10 节）、`roadmap.md`（里程碑）、`stage.txt`/`review-mode.txt`（运行开关） +- 根目录：`roadmap.md`（里程碑＋迭代总表六列＋顶部「当前位」节＝现在做什么）、`stage.txt`/`review-mode.txt`（运行开关）；仓库根禁止再设会话状态文件（2026-10-18 用户裁，细则见 doc-conventions 第 10 节） ## 规范导航（动手前先查表） @@ -49,11 +49,12 @@ | 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | | 架构（唯一事实源） | `design/dev/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 | | 术语、已锁数值 | `design/registry/entities.yaml`——仅 owner 文档可修订，冲突须显式提出 | -| 会话进度 / 路线图 | 根 `active.md`（状态文件：只记现在，每行当下为真；快照+未决面+滚动条目）· 根 `roadmap.md` | +| 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `design/gdd/06-待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` | ## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约） -- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：active.md 会话收口、.zcode 钩子配置） +- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：`.zcode/` 与 `.qoder/` 两份本机 harness 配置，实测均不入 git） +- **仓库根禁止设会话状态文件**（2026-10-18 用户裁废除 `active.md`）——现状看 roadmap「当前位」，待办看 06，过程看 git 提交信息，产出物看 `reports/`；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节） - 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测 - 交付前验收 = 跑 `tools/run_all_gates.sh` **按改动域**全绿（唯一入口、唯一闸清单、唯一域划分，禁在文档另列）；合回 master 由 worktree-guard 按 diff 推域校验回执强制（process-conventions §3） - **两类批**——**迭代批**（代码实现，`/iter` 发射）：**禁写 `design/` 整个目录**（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；产出物只准写 `reports/`；批末只跑代码域闸。**非迭代批**（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地走五段流水线相应段（文档设计段入口=用户级技能 doc-design；登记条目格式由流水线闸强制） diff --git a/active.md b/active.md deleted file mode 100644 index 0f686e1b..00000000 --- a/active.md +++ /dev/null @@ -1,63 +0,0 @@ -# 会话状态：Dungeon Sweeper（扫雷 × 自动战斗）——唯一状态源·状态文件（2026-10-09 立宪） - -> **定性（2026-10-09 用户裁决）：状态文件，非历史档案**——本文件每一行都必须在当下为真；历史变更一律以 git 提交史为准（删除的条目可在 git 历史版本中完整复原）。 -> 写入边界：只写快照、未决面、当前迭代工作条目。待办裁决归 `design/gdd/06-待办清单.md`，跨会话教训归记忆库；已完结批次条目（已入库+结论进快照+无未决项指向）在迭代收口时删除，超 30 条必须清。细则见 `design/dev/doc-conventions.md` §10。 -> 并行会话禁止将本文件整体复原/回退。 - - -- **阶段**：M3——Alpha 版本的完整实现（2026-10-09 立规：未明令宣布完成前停留 M3，迭代只排 M3 需求，M4 不排期；根目录 stage.txt 为旧阶段开关仅存档） -- **系统索引**：`design/gdd/02-系统清单.md`（2026-09-14 循环式新骨架根索引；旧 `systems-index.md` 已封存于 `design/archive/gdd-2026-09-14/`，只读参考） -- **概念文档**：`design/gdd/00-游戏概念.md`（新骨架顶层文档；旧版 game-concept/game-pillars 已随归档封存） -- **原型**：概念原型 demo 已删除（2026-09-12，垂直切片承接）；验证结论 PROCEED 载于 git 历史，原报告路径已散佚；原型已演进为 `game/` 工程 -- **引擎**：Godot 4.7.2 + GDScript（2026-09-07 锁定；`.claude/docs/technical-preferences.md` + `docs/engine-reference/godot/`；**MEDIUM RISK**——2026-09-12 `/setup-engine refresh` 逐条核实 4.5–4.7 官方迁移指南，无破坏架构契约项，current-best-practices.md 已建） -- **架构**：`design/dev/architecture/architecture.md` v1.6（2026-09-12 /create-architecture 产出；2026-10-15 确立为架构唯一事实源——历史决策文档体系已废除、沿革归 git commit log；review-mode.txt = solo） -- **待办清单**：`design/gdd/06-待办清单.md`（2026-09-16 收编批起为全项目待拍板唯一登记处；系统文档只留指路存根，新增条目直接登记清单，裁决后改状态列留痕） -- **批次产出物**：迭代批的实现报告、代拍板追认单、GDD 反哺点清单落根目录 `reports/`（2026-10-17 用户裁：迭代批禁止写 `design/`，`reports/` 是其唯一可写目录）；证据只留最新一轮，细则见 `design/dev/doc-conventions.md` §11 -- **工程路线图**：根目录 `roadmap.md`（里程碑时间线的权威；实时状态看下方快照节） - -## 当前状态快照（收口批先更新本节，再追加状态记录；≤10 行） -- **更新于**：2026-10-17（**迭代 30 卡②③剔除批**——用户令：卡②战斗一屏样张、卡③二三关棋盘观感剔出迭代 30 移 06 状态「待设计」，理由=两卡本质是设计澄清/美术定稿环节、无现成素材，不满足代码实现批开发条件；卡①保留零回滚；roadmap 迭代 30 行/迭代进度行/主战场行三处换代＋06 新登待设计条；v1.4 原卡片留 `design/research/` 作设计素材；同批清理三 iter30 worktree 与分支。此前同日：线头收编批合并、迭代 30 卡① `7ffd1dc0` 与文档批 `34f3cdb3` 落地、迭代 29 批 `fff4f120`、闸按域分跑批 `60c25ca3`、GDD 反哺写入批 `bd6ab32e`，M4 数值批已废归 06 待裁）。 -- **最新闸态**：重闸唯一入口 `tools/run_all_gates.sh` 按改动域分跑（代码域 01 冒烟／02 单元／03-04 探针／05 渲染／09 静态扫描／10 熵增／11 对拍，文档域 06 gdd_lint／07 doc_link／08 doc_term／08b active.md 体量／10 熵增；**域划分只在该脚本定义一处，文档禁止另列闸清单**）。文档域末次回执 commit=分支尖（2026-10-17 线头收编批，见合并说明），零新增红。代码域末次实测读数（2026-10-17 迭代 30 卡①合并态，回执 commit=`7ffd1dc0`）：冒烟 1151/0、单元 34 套件（type_glow_test 51 检查）、探针十八断言、渲染 golden 棋盘×3（0.13/0.11/0.10%）与菜单（0.14%）均在容差内、static_scan 相对基线「改善」（基线红→现绿）；**11 号闸 parity 是条件闸件，本批判未触面（diff 未触数值/存档/RNG/结算面）SKIP**，迭代 29 批判为触面、须 `PARITY_APPROVED=1` 才发起，MC 未跑。 -- **迭代 28 交付**：修好启动时菜单被冒险层盖住的装配顺序，层序收敛为唯一装配合同（散落的两处 `move_child` 删除）；boot 链路、九阶段生命周期、启动态菜单 golden 三组验收补全；本批新立硬规则「验收函数无变异红记录不算验收成立」，三处规约落文。 -- **迭代 27 交付**：三屏壳场景与局态物化、结算五段拆分、RunLedger 单类持四账、模态编排类、类型闸、死代码退役，编排器由 1725 行降到 1325 行。 -- **规约体系现状**：规则文件按领域拆为 7 份、单文件上限 150 行，CLAUDE.md 只留元信息、命令、目录、规范导航与一行一条红线；动手前按规范导航表查对应细则。2026-10-17 增两条硬边界：迭代批（`/iter` 发射的代码实现）对 `design/` 只读、禁止在其中新增/修改/删除任何文件，产出物只准落 `reports/`，批末只跑代码域闸；非迭代批（工具/规则/文档改动）不占 roadmap 迭代号，按改动域跑闸。 -- **人闸在册两件**：迭代 27 全流程走查〔07 ㉖〕与迭代 28 启动态菜单〔07 ㉗〕，均登记不阻塞；贫矿脉目检项〔07 ⑪〕已随 2026-10-16 屏蔽令转记失效；迭代 19~26 的目检已于 2026-10-14 全部核销。 -- **簿记出清**：迭代 19~26 的代拍板追认单与 GDD 反哺点已全部裁决落文，对应 14 份迭代实现报告按「证据只留最新」删除（git 历史可考）。 -- **已裁在册**：M4 数值批已废（2026-10-16 用户删卡令——禁止再以该名义立批/规划/引用已删卡，四项数值欠账归 06 在册、重新归属待裁）；**迭代 29=测试分层与门禁语义修正批已合并**（`fff4f120`，十提交）；**迭代 30=UI 呈现批·卡①未开格类型徽章批已合并**（`7ffd1dc0`，2026-10-17；卡片 v1.4＋开工前预授权 U1 四项已用完）；**原卡②③已于 2026-10-17 用户令剔除迭代 30、移 06 状态「待设计」**（前置=设计讨论→需求澄清→美术定稿，禁未定稿直接开工）；迭代 27/28 位预留追加卡。 -- **界面美化三层**：第一层三件全部交付；余第二层三件（贴图/字体/样张）与第三层其余（九宫格切片/棋盘观感）待立项。 - -## 未决面（进行中/待人闸/待裁点指针；现行事实源登记处=`design/gdd/06-待办清单.md`） -- 待用户裁决（06 在册）：美术审计两项 P0（art-bible 死样张指涉、主角像素管线重产）；去毒残留词是否清扫（「魔法道具」约 30 处、「罕见」约 18 处）；喂雷流 R5 甲重启条件回落文；「通关」与「通过第 N 关」全库口径统一（约 273 处）；**贫矿脉屏蔽的设计语义面反哺五处**（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注——均描述已撤回功能，待裁是否改写，机械面已同步）。 -- 待登记 06：需求卡片入库纪律一条（502 批遗留，2026-10-17 在 06 清单内查无该条，属悬空待办）。 -- 待用户追认：仅剩 req-card 技能的 WorkBuddy 与 ZCode 两份副本是否取齐一项。迭代 27 代拍板十五项、迭代 28 十三项（含四条白名单外）、迭代 29 十二项、迭代 30 卡① 七项已于 2026-10-17 用户令全部同意（iter30 追认令原文「追认没有问题」）——iter27/28/29 三份实现报告（2026-10-17 文档批已迁位 `reports/`）的追认单节已就地标注追认结果，iter30 卡① 追认单（独立文件）文末已加追认结果行；迭代 29 第四节「经你裁决的四项」不在追认范围（当时已问过已答）。 -- 待发令：迭代 27/28 预留追加卡；黑话清扫第二波（GDD 正文流程动词族约三千处）；规则文件编写 skill（按规则文件审计与目录划分批的工作流提炼，见提交 `81c0ee2b`）。〔原待发令的迭代 30 卡②③已于 2026-10-17 用户令剔除，移 06 状态「待设计」——非发令项，重启须先过设计定稿〕 -- 待批准发起：**11 号闸 parity 回放确定性对拍**（迭代 29 把它收编为重闸里的条件闸件，每次跑批只做触面判定、不自动跑；迭代 29 批已判触面并挂 NEED-APPROVAL，批准方式＝带 `PARITY_APPROVED=1` 发起，MC 须用户批准才跑）。 -- 在途分支未合并 master（读现状时勿当已入库）：**无**。线头清理（2026-10-17 用户令）：`art-standee-20261006` 已合并入 master（立绘定档批机检三件＋文档修正，见状态记录 511）、`doc-adr-fixes-20261014` 判废删除（ADR 体系已废、内容 git 历史可考），两 worktree 与分支同删。已合并的 worktree/分支清理（2026-10-17 用户令执行）：`g-plan2-iter29-testlayers`、`g-plan2-menusub-20261016` 两工作区与分支 `adr-purge-20261015`、`adr-leak-fix-20261016` 已删；`ci-removal-20261015` 已按 2026-10-16 既裁重做（只删 `.github/workflows/tests.yml`、撤 ADR 两条）合并 `db032fb5` 后工作区与分支同删；**在盘待删**：`g-plan2-carddoc-20261017`（分支 `carddoc-20261017` 已合并 `480d8118`）。`g-plan2-iter30-glow`／`g-plan2-iter30-fb`／`g-plan2-iter30-sample` 三工作区与分支已随 2026-10-17 卡②③剔除批删除（sample 分支 5 个未合入提交——卡②样张批 T0/T1/515 终止/active 清理——随用户「3 个工作区全部删除」令一并废弃，git 历史可考）。 -- 在册观察（06 登记，非阻塞）：迭代 27 卡片义务补登两项——长函数余量 17 个中的装配/校验函数、lambda 连接防回归。 - -## 状态记录（滚动窗口：仅当前迭代；退役规则见 doc-conventions §10） - -- **496（2026-10-15，迭代 28 启动装配与生命周期验收补全批总收口）**：单会话交付七提交并合并 5b958ff6，冒烟 1086→1125/0（新增 42 条断言，退役 3 条把错误顺序写成期望值的裸下标断言）。四条结论：①启动装配顺序错误（菜单被冒险层盖住）已修，层序判定收进单一合同 `LAYER_CONTRACT`，散落的两处手工 `move_child` 删除；②boot 链路十断言与九阶段×五引用面生命周期矩阵入库；③渲染面补两件探针自检、墨色判据与启动态菜单 golden；④六次变异注入全部见红并精确还原，拦截能力已证。变异 3 顺带证明墨色占比判据自身不可靠——菜单被藏时底层棋盘仍给高反差像素，该强弱分层写进 code-conventions §3.6。批内类型闸自纠一笔（`main.gd:453` 缺元素类型，改 `Array[Variant]` 后 S9 归零）。存档面风险已核实：全部 worktree 共享同一份 `user://save.json`，定位过程中临时移开的真实档已逐字节校验还原。 - -- **499（2026-10-15，active.md 收口机制批）**：用户裁定收口检查的触发时机不能挂在"一轮答话结束"上——旧的 Stop 钩子判的是「active.md 内容有没有变」，追加新条目就算变，结构上永远抓不到"没删旧条目"；且它比对的还是已废弃路径 `production/session-state/active.md`。实测三份 harness 副本现已全部失效：Qoder 侧快照零份、ZCode 侧没接 Stop 事件、Claude 侧配置为空。改法分两层：机械层 = `tools/audit_active_state.py` 判五条膨胀签名（状态记录条目数超 30、快照行数超 10、条目编号重复、快照整行自我重复、指向 `design/qa`|`design/research` 的死指针），并入 `tools/run_all_gates.sh` 为 08b，由既有合回闸回执强制，不另立第二份闸清单；语义层 = `active-closing` 技能，规定用户问「任务是否结束」时先跑闸、按 §10 三判据逐条核对并删除、报删除清单，然后才回答。变异验证：对换代前的 34 条版本报 5 项红（连 472/477/481/494 撞号与 6 处报告死指针一并抓出），对退役后的 3 条版本报绿。钩子副本收敛为单一事实源：`.qoder/settings.json` 改指 `.zcode/hooks/worktree-guard.sh`，该脚本加 `QODER_PROJECT_DIR` 兼容并把 `.qoder/` 纳入豁免面（gitignored 配置走 worktree 带不进去），`.qoder/hooks/` 三份副本删除。脚本层守卫五例实测（stdin 直喂）：主区改 tracked 文档拦、改 active.md 放行、改 .qoder 放行、主区 commit 拦、无全量回执的 merge 拦。**待核**：hooks 属各 harness 私有配置、不随仓库传播——ZCode 侧确认在跑，Qoder 侧本会话活体探针未被执行（`.claude/settings.json` 仍为空），故拦截力目前只在 ZCode 生效，成因待诊断。全量闸由用户自跑，本批按令合回 master（分支 `active-gate-20261015`，合并见提交史）。 - -- **500（2026-10-15，决策文档体系废除 + architecture.md 确立架构唯一事实源，文档批）**：用户裁「ADR 不需要保存，任何决策记录在 git commit log 里记好，不需要工作日志文档存在」——七份 `adr-0001~0007` 全删（内容留 git 历史），architecture.md 删「ADR 审计」「ADR 立项清单」两节、文档状态立「事实源地位」条（唯一事实源），未决表关闭 QQ-01/02/03、立项清单在途事项转登记 QQ-11~14，补 A1 生成姿态与 autoload 四件（ConfigDB/RngService/SaveManager/MetaProgression）事实；CLAUDE.md 新增「架构事实唯一源」红线并恢复 RNG 单点红线；doc-conventions §5/§11 落架构唯一事实源条文；registry 删 18 处 adr 字段；game/ 约 60 处代码注释与 GDD/qa/research/roadmap/tests README 引用全清，豁免标记 `ADR-0007-exempt`→`rng-seed-exempt` 五处同步（main.gd/static_scan.sh/architecture.md/06/iter27）；主区 4 个未跟踪今日产物（测试审计报告/两张需求卡片/自造短语清单）就地清除。走 worktree `adr-purge-20261015` 合并 4ed48b86；死链校验 1206 链接 0 死链、gdd_lint 0 不通过；按用户令未跑测试闸（本会话合回闸未触发、receipt 未生成）。代码中 `adr`/`adr5` 等为 AdventureRunner 既有局部变量名（smoke/单测 5 文件约 60 处），非文档引用、未动。**遗留呈报待用户裁**：`ci-removal-20261015` worktree 的 ADR 两条改动已被本批取代（仅 CI 清除部分对迭代 29 有效）、`doc-adr-fixes-20261014` 分支方向已废，两个 worktree/分支的去留待裁（2026-10-17 核：`ci-removal-20261015` 已合并 master、worktree 仍在盘；`doc-adr-fixes-20261014` 仍未合并，两条的现状与清理待令都记在未决面。同日再核：两线头已随状态记录 511 收编清偿——ci-removal 合并删净，doc-adr-fixes 判废删除）。 - -- **501（2026-10-15~16，简明技术中文用语规范批总收口）**：用户令对 design/gdd 全 45 文件做三层语言规范并融合词表——词面约 250 处按术语表「用语规范」A 表替换（不得→禁止/收口→完成/随批→顺带等 12 行，五子代理分四波执行+逐处语境裁决）、术语表 v1.12 新立「用语规范」节（STC 词表为权威+豁免三类+注销词义限定注）、词条五组（总线/抽屉、机能件/机制件、装板/摇号、坍塌显形、增益归一）+死链全库清零（3 处：config_fatal_probe 去向双证落 v0.4 行注、武器锻造漏改 2 处）+doc_term_audit 吸收 A 表 10 词与随批/台账补扫通道。**本批两教训**：①合回闸与「文档批零测试」铁规冲突时助手机械服从、擅跑全量测试两轮（含渲染闸），用户暴怒——正解=改闸的判断条件，现守卫已加「纯文档合入豁免」（merge diff 不触 game/ 直接放行，代码合入仍全量闸）；②坑册新增：守卫按命令文本解析分支名（cd 前缀/环境变量前缀连坐误拦）、.import 边车被全局忽略致 worktree 冷检出探针 texture=null 假红。合并 af321c03（九提交，纯文档合入未跑测试，同日 4ed48b86 前例）。 -- **502（2026-10-16，迭代 29 编入批——roadmap 门牌登记）**：用户令「把需求卡片写进 roadmap 的迭代 29」——此前需求卡片只存在于中间文档，roadmap 仍写「下一前沿=迭代 29+ M4 数值批」，致别的会话启动迭代 29 时跑去做 M4（该卡同日已被用户删除＝死引用）。本批三改：①roadmap 迭代 29 行改写为「测试分层与门禁语义修正批」（需求卡片=`design/research/需求卡片-测试分层与门禁语义修正批-2026-10-15.md`，v1.4，T0–T8≈5.5–7d，开工门 U0＝Q3–Q7 裁点＋卡片 v2.0 重核＋`/iter` 发令），新增「迭代 30+ 位空」行记录 M4 废除（禁止再以该名义立批/规划/引用已删卡；四项欠账归 06 在册待裁），迭代 23+ 原始泊位行加作废注仅作排期史保留；②需求卡片升 v1.5（排期行与 §5 同步行更新；登记 v2.0 重核遗留＝残留 CI 措辞四处＋事实基线换代〔冒烟 1086→1125/0、门禁五闸→run_all_gates.sh 编排、architecture.md 测试域节已成文、Q3 的 CI timeout 前提消失〕；订正 v1.3 版本条目尾部重复段）；③本文件快照与未决面三行同步换代。文档三闸全绿（gdd_lint 0 不通过／死链 0／疑似现行 0）。提交 21c83f5。**遗留待用户裁**：06 待办清单登记一条（卡片入库纪律）；`ci-removal-20261015` 分支重做（撤 ADR 两条、只保留删 .github/、rebase 现行 master）。（2026-10-17 核：该分支已按现状合并、重做令失效；「06 登记一条」至今在 06 清单内查无，已改记在未决面的待登记项。） - -- **503（2026-10-16，贫矿脉屏蔽＋DS_DEBUG 写死批总收口）**：用户令两项一波走完（worktree `g-plan2-shielddebug-20261016`，五提交，合并 d3356985，合并后主区冒烟 1126/0 兜底）。**①贫矿脉屏蔽**：`variation.tres` 删 skewed_veins 行（用户裁「地形变异特异关卡后续重新做设计，先屏蔽」）——Boss/精英图全局池空→`_resolve_global_variant` 空行回落→region 布置原路兜底，玩家面零横幅零角标零资源偏斜；冒烟 7 处断言换代为「全局池空→region 兜底回落」路径（行数 7→6／boss 池去 global 行／L2 boss+elite 全局决议空行／格子级恰一行且在 {magma,ash}／快照空态一致／同种子确定性含 variants 字典逐位）；resource_face 机制代码（RewardEconomy 偏斜投影／schema 互锁／负样本）零触碰，重建设计直接加行即可；删行依据与首发批裁决记录改写为屏蔽注记（git 历史可溯）。**②DS_DEBUG 写死**：`main.gd:219` 环境变量读取退役、`_debug_entry` 恒 true（用户令「直接写死，不读环境变量，太麻烦」）——全库 DS_DEBUG 引用清零（含浮窗内用户可见工具提示文案）；闸断言三处换代（smoke V2f 改恒开／click_probe 原「未设时不得默认开」反转为「未恒开即失守」并挪至 boot 段、设置面关闭段补 ModalStack 遮挡恢复断言／tune_probe 删自设环境变量死代码）；**发布前删除事项＝main.gd:219 一行**（无 CI，两道恒开断言会红兜底；该行现行位置与行号见 507 条＝`game/presentation/main.gd:196`）。**闸面三修**（首跑抓出）：冒烟跨块引用 bb/crng 出作用域 Parse Error（hoist 为 boss1_ids/variants/calls）；shot_probe 截图前走 `_close_modal` 真实单口归一浮窗（写死后 boot 即开压菜单——boot 顶层检查／golden 19%／文字占比 0.00% 三处受扰；视觉契约与调试模式解耦，发布前删写死时基线不受影响）；click_probe 恒开断言归位。**基线 09 指纹刷新**：静态扫描红项清单与基线不符，经主区与分支 `audit_file_headers` 输出逐行一致（128 行）证明非本批引入（漂移源于 20f4a7dc 之后主区 .gd 头注变动），按「人工确认后重生成」条款对齐指纹，红项仍为存量 127 处。**验收**：全量闸通过（存量红零新增，回执 commit＝HEAD）；worktree 与分支已清理。**读数义务归 M4**：Boss 图资源面分布与 region 布置读数（本批 MC 零跑，内容回落既有 region 行为）。**反哺点待裁**：设计语义面五处描述已撤回功能（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注）；机械面四件已随批同步（07 ⑪ 转记失效／architecture 行数 7→6／数据配置清单／06 战斗节点地图类型差异化条）。 -- **506（2026-10-16，迭代 29 测试分层与门禁语义修正批总收口）**：用户 `/iter 29` 发令，单会话八提交交付（worktree `g-plan2-iter29-testlayers`，分支 `iter29-testlayers-20261016`）。**核心是把验收语义从「跑一遍没崩＝通过」扭到「三层完备＋判定可靠」**，三硬闸每条都有反例实证：改前「探针打印 PASS 后 quit(1)」判全绿、「零断言套件」判 all green (0 checks)、「子套件中途报 SCRIPT ERROR」判 PASS；改后三条全部见红。**本机两个坑写进注释防复发**：①`OS.execute` 的输出管道恒空（子套件输出须交命令解释器重定向落盘再读）；②`OS.get_executable_path()` 返回 GUI 子系统 exe，其子进程 stdout/stderr 句柄无效，必须换 `*_console.exe`。断言下限用专用退出码 2（不是 1——致命类套件期望 1，返回 1 会被 expect 协议放过）。**三层承载**：L1 补六套（board_generator／minesweeper_rules／config_db_resolver／config_db_cross_validator／hud_presenter／battle_narrator，27→33 套），三屏壳归 L3 探针；L2 建 `tests/integration/` 首个用例（存档⇄RNG 往返，含旧档经迁移链后仍可续玩这条真实路径）；L3 新建 `screen_flow_probe`（六步主流程＋两条回退，每步判屏级互斥）入轻闸。**parity 收编为重闸 11 号条件闸件**（每次跑批做触面判定，触面也不自动跑——MC 须用户批准），本批即判触面，挂 NEED-APPROVAL 待裁。**扫描域**：S3 路径由裸 `core` 修正为 `game/core`（此前恒零命中恒绿、什么都不扫），补 S5，并给每条规则加零命中自检（扫描面为空即判红，路径写歪时自检跟着一起红）。**四处经用户裁决的改动**：fx_grant_gp 补行来源豁免（每局 7 次断言失败被闸长期漏过）／manifest 增 negative 字段（负面套件的错误是测试目标）／config_db_test 的 rows 定型数组赋值改 assign（**10 条敌人表行集纪律断言从未执行过**，修后两条正向见红＝夹具缺 depth-0 锚行，补锚行全绿）／system_contracts 空桩换真实实例。**台账与时效**：15 个游离脚本逐个定性成表（存疑按在役）；golden 先判再动，实测 changed 0.00%／0.15% 判有效不重制。**架构事实源回写**：三硬闸矩阵「缺失」→「在位」、S 表 S3/S5 更新、新增「三层承载与判定原则」小节。**验收**：重闸 exit=0（存量红零新增，回执 commit＝HEAD），冒烟 1127/0 持平，轻闸墙钟 363→405s。**遗留待裁**：11 号闸 parity 是否批准发起、GDD 反哺三条、06 在册七项。 - -- **507（2026-10-16，调试入口全局浮层角标批——屏内三枚角标合并为最顶层浮层）**：用户看完上一批（屏内角标形态）交付态后定稿：不做置顶钮式按需出现，要「**UI 最顶层浮层、不被任何 UI 遮挡**」（调研 Material FAB 与 NN/g 置顶钮规范后用户给出的修正——位置惯例一致但浮层语义不同）。实现（worktree `g-plan2-dbgfloat-20261016`，两提交，合并 746c1bb4，主区冒烟 1127/0 兜底）：**三枚屏内角标（菜单右下/战斗 HUD 右下/地图顶栏）合并为一枚全局浮层角标**——LAYER_CONTRACT 末位新增 `{"key":"debug_badge","kind":"float"}`（只落树序＝最顶绘制序、**不注册 ModalStack**：`open()` 遮挡记账只隐藏登记层，故任何模态/覆盖层开都不遮它＝用户需求的机制根因）；main 直接子层，构建走 `ui_assembler.build_debug_badge`（右下角 16px＋FS_HINT＋豁免宽度基准＋grow BEGIN）；地图屏底栏 85px 常驻→`_sync_status_entry` 按 `map_on` 抬 `offset_bottom` 至底栏上方 16px；战斗屏状态角标经 MarginContainer 让位（right 16/bottom 52）不再被压；屏内三处 `debug_badge` 全删（menu_screen/board_zone_view/level_map_screen），main 两处接线与 sync 四条可见性/置灰行清除（浮层常显不置灰）。**断言换代**：smoke V2f 查 `main.debug_badge` boot 可见；click_probe 遮挡判据移至**设置面开中段**（浮层角标此时仍应可见＝直接验「不遮挡」）；tune_probe ①点击路径与⑨对局中角标全改 `main.debug_badge`（T2 防线三断言不动——non_locking×遮挡复活×has_open 组合回归）。**过程两处**：①一处替换误写成重复状态角标接线（指向不存在方法）——提交前 grep 自纠；②基线 06 刷新：`01-核心循环.md` 表格占比 43% 越线为今日 9846a29f（删副标题行）引入的存量，主区实测同红、本批零 design/ 改动，按人工确认条款对齐指纹（该条红灯与 R5 缺流程图均已由提交 `fcb8c3f8`＋`8c18b52b` 结案，基线 06 已改回绿）；09 静态扫描本批转绿（并行会话 R0 文件头锁批清偿 127 处存量）。**发布前删除事项**：`game/presentation/main.gd:196` 一行（2026-10-17 核实行号，原记 `main.gd:219` 已漂移）——删该行后角标可见性（同函数下一行 `:197`）随门控失效自动隐藏，无第二删除点。 -- **508（2026-10-17，代拍板追认单落状态批）**：用户令「追认单的所有我都是同意的」——迭代 27 十五项／28 十三项（含四条白名单外）／29 十二项共 40 项代拍板全部同意，三份实现报告的追认单节各加一行追认结果。两处保留：①iter28 第 14 项只认「本批动作」（只补 ZCode 副本、未擅自取齐），「req-card 两副本是否取齐」仍是待裁问题，留在未决面；②iter29 第四节「经你裁决的四项」当时已问过已答，不属追认范围，原文不动。连带改 06「闸按改动域分跑批的两处代拍板」条①②为已追认，③迁位欠账补计 `iter29-实现报告`（该条登记时只列两份，漏计第三份）。roadmap 迭代进度行三处「代拍板追认单…待用户」换代为已追认。worktree `g-plan2-ratify-20261017`，文档域闸 `--docs` 零新增红（回执 commit=9a7dfcf6），合并 `eabaeee0`。**本文件三行改动（待追认行／在途分支行／本条）留在主区工作副本未提交**——主区另有并行会话的未提交件（`game/project.godot`／M4 卡片删除／五份未跟踪文档），按「只合本批自有改动」令不代为提交，等下一次动 active.md 的批一起入库。GDD 反哺点八条（27 两条／28 三条／29 三条）未随本批处理，属设计权威文档改动、需逐点裁决另批写入。 - -- **509（2026-10-17，GDD 反哺点写入批——迭代 27/28/29 八条＋一条建议逐点裁决）**：用户裁「全部按推荐案执行」（文档批，不占迭代号，worktree `g-plan2-gddfb-20261017`）。写入面：①**architecture.md v1.7→v1.8**——新增「战斗域装配现状」（结算五段 授予→增益/减益→战斗→衰减→判定，段序骨架冻结于 `SettlementTable.segment_order`；RunLedger 单类四账所有权 AdventureRunner 独占）与「呈现层装配与会话生命周期」（三屏壳+组合根句柄面／视觉层装配合同立条款、合同表不摘录——唯一事实源=`main.gd` `LAYER_CONTRACT` 现行 17 项五类 kind，登记时 16 层按代码实态订正／RunScope `_begin_session` 换会话整节点释放、无独立收束函数／九阶段×五引用面存活性矩阵认账入册／ModalFlow 互斥域 tags）两节；「初始化顺序」补启动后置条件六条（登记时「十断言」现为六组 11 条——2026-10-16 角标令 V2f 拆两条）；呈现层 D1 行与实现实证读数换代。②**code-conventions.md §4 第 7–12 条**——S9 类型闸三规则与扫描面口径／`:= {}` 推断形态不算债／`# type-hint: ignore` 行级白名单／`# rng-seed-exempt` 豁免通道／--script 模式禁裸 autoload 标识符／Variant 参数化现行口径（元素精化不入硬纪律）。③④⑨**test-conventions.md 新增 §7 判定三硬闸**（闸承载三闸齐备义务＋负面套件仅豁免错误扫描一闸＋新写测试件全类型标注写法纪律，暂不机器闸——S9 扫描面产品码）与 **§8 判定可靠性优先于覆盖率**（§六第 4 项建议随此反映：脚本错误静默中断所在函数剩余断言的机制事实＋三处实证＋写验收函数自证断言全数执行义务；覆盖率度量是否引入仍 06 在册待裁）。⑤**07 v1.4**——㉖① 全流程走查保留不注销，节首加 `screen_flow_probe` 机检承接注记。三笔旧账清零：iter27/28/29 三份实现报告 `git mv` 往 `reports/`（06 条③迁位账清零，全库引用改指新路径、死链复验零死链；roadmap 九处 iter21–26 已删报告死指针改「已退役（git 历史可考）」、iter27/28/29 改指新位）；iter29 报告 §六第 0 项按合并现实改写（`fff4f120` 已合回，两红各自结案：菜单 golden 重采 `dac9a94b`、01 篇 R5 流程图 `fcb8c3f8`＋`8c18b52b`）；06 补登迭代 29 反哺专条（该批漏登）且 27/28 反哺条按「吸收即死」退役为已写入。06 :687 死引用「code-conventions.md §3.6」顺带订正（该内容现独立成文于 test-conventions.md §6）。本批并把 508 批自述「等下一次动 active.md 的批一起入库」的主区未提交行改动随本批提交入库；主区其他并行未提交件（`game/project.godot`／M4 卡片删除／五份未跟踪文档／`layout_probe.gd.uid`）仍零触碰。文档域 --docs 零新增红（回执 commit=分支尖，见合并说明）。 - -- **510（2026-10-17，迭代 30 卡① 未开格类型徽章批总收口）**：用户「完成迭代30的开发」——三卡串行只做卡①（代码实现批，worktree `g-plan2-iter30-glow`，分支 `iter30-glow-20261017`，合回前 merge master `2aa7e8fd` 后重闸，快进合并 `7ffd1dc0`）。**实现**：Q1 丙案主路径 shader 距离场（`cell_type_glow.gdshader`＋`cell_type_glow_layer.gd` 承载件，与 `_desat_mat` 共存实测未撞墙、a 案程序绘制兜底未启用）；五组微光色板与九型归组单点 `ui_kit.gd`（TG_GLOW_*＋`glow_group_for_cell_type`，呈现参数 α170／带宽 cell÷8）；board_view 作用集＝`_diggable` ∩ 身份可查 ∩ 灯光区 − r0，相位门控与接触带同源，Q4 丙案默认开。**唯一停机呈报**：群伤组初版 #FF1A31 与冻结绯红 #FF2D55 的 ΔH 5.40°（触 art-bible §4.2 既裁冻结面）→ 用户裁「换更暗档 #A61D37」（冻结值 V=0.65 档、色相零移动）；五组现全数「只动明度不动色相」（ΔH ≤0.13°）。**断言三件**：冒烟八相 24 项（1127→1151，含契约 1 同板同序列 on/off 双实例 12 步 digest 对照）／单测 type_glow_test 五段 51 检查（33→34 套件）／ui_input_probe case⑰ 活板面（十八断言）。**渲染取证**：board_shot 双帧（motion_scale=0.5 停格隔离）三关 glow=2/4/4、带外零变化、生效格实绘非空；判据源探针（夹具面五组齐现）相邻组 CR 最弱对 1.232；off 帧对 2026-09-30 代 golden 三基线漂移 0.13/0.11/0.10%（≤2%，基线未重制）。**变异验证 M1–M5 五组反例实证**（归组错映／清单外静默／相位切换不重算／α=0 不绘／派生路径误触玩法 API，红输出与还原实录见实现报告 §四）。**验收**：`--code` 重闸零新增红（09 由基线红转绿判「改善」；11 号 parity 判未触面 SKIP），回执 commit=`7ffd1dc0`＝分支尖。**坑档两条入注释**：探针裸视图必须接生产同源身份解析（否则作用集恒空、PASS 假绿——实跑两次 glow=0）；`Callable.bind()` 动态派发对类型化参数做 Object 硬校验，回调传参改成员现值＋直接方法引用。**产出物**：`reports/iter30-实现报告-2026-10-17.md`（含实机目检总清单 V10 人闸五项，登记不阻塞）／`iter30-代拍板追认单-2026-10-17.md`（§9 白名单 7 项待追认）／`iter30-反哺点-2026-10-17.md`（§5 七条待用户裁决归文档批）。**遗留**：反哺点七条待裁（06 条目状态＋措辞、HUD框架 :140/:269、08 表现表、art-bible 明度档修订条目、roadmap 批内状态、Q3 两带分工＋06 新待办、07 目检人闸条）；实机目检人闸待用户过目（「很丑」终审位）；群伤暗档 provisional 待样张批转正；阔视野带 desc「微光范围 8→12 格」与卡 §4「不扩微光」冲突属数据文本批（treasure_items.tres:47，实现报告 §六登记，不占反哺点条数）；`g-plan2-iter30-glow` 工作区在盘待删（同 carddoc）。 - -- **511（2026-10-17，在途线头收编批——立绘定档分支合入＋两条老线头清理）**：用户令「art-standee-20261006 合入；完成之后把两个工作区删除」。①**`art-standee-20261006` 合入**（worktree `g-plan2-standee-tier`，2026-10-06/07 立绘定档与站桩重排实装批，领先 5 笔、落后曾达 478 笔；先 merge master 解一处冲突——art-bible 定档行取 master 用语规范版、排版行取分支「允许向上溢出盒顶 N px」甲案版）。落 master 内容：10-07 三处文档修正（art-bible §8.2 站桩排版③大体档溢出甲案与光柱脱钩／§8.3 参考核验废路径 `production/mockups/`→`artwork/mockups/`／battle.md 敌方站桩行同款甲案措辞——三处 master 实查均仍为旧措辞即从未落库）＋06 新登「战斗区背景图替换——B 区舞台插画＋临时光柱退役」条（2026-10-07 用户点名登记）＋机检三件工具（`tools/standee_asset_check.py` 逐键档高升级版、`tools/palette_check.py`、`tools/path_check.py`；依赖 `STANDEE_TIER_H` master 已有）＋四份过程文档归档（实装批任务书／交接说明／artwork 独立仓 dry-run 清单／立绘读数 txt）。**该批止于 B 段工具闸，C 段引擎实装、D 段人闸未跑，roadmap 迭代位归属仍待用户裁**。②**13 件未跟踪立绘先抢救再删区**：`_tmp_standee_new/`（八敌＋主角三态＋九人对照总图＋读数，149K，素材不入 git）已拷至主区 `artwork/archive/standee-tier-20261007/`（gitignore 豁免面零状态噪音）；该批 AI 生成像素立绘在 2026-10-14「精细手绘像素」方向裁定下的去留归用户后裁。③**`doc-adr-fixes-20261014` 判废删除、不合入**（worktree `g-plan2-doc-adr-fixes`）：五笔提交改的 10 文件全数失效——7 份 `adr-*.md` 已被废除批删除（modify/delete 冲突面）、architecture.md v1.4 被 v1.8 超越、02 清单与 registry 实查零 ADR 字样；分支内 ADR 审查报告已被分支自身第三笔删除，git 历史 `302b5b2c` 可考（Qoder 会话「报告仍在分支」系误报，已核）。两 worktree 与分支（`-d`／`-D`）均删，merge 说明载 --docs 闸回执。 - -- **512（2026-10-17，迭代 30 卡① 文档批——代拍板七项追认＋反哺点七条回写）**：用户令「追认没有问题;反哺点可以都进行回写」两项一波走完（文档批，不占迭代号，worktree `g-plan2-iter30-fb`，分支 `iter30-fb-20261017`，基于 master `0a164958`、合回前 merge master 解 active.md 一处冲突——本批状态记录原编 511 与 master 线头收编批 511 撞号，按 iter29 先例改 512）。**追认**：卡①代拍板白名单 7 项全部同意，追认结果行加在 `reports/iter30-代拍板追认单-2026-10-17.md` 文末（用户令原文「追认没有问题」）。**反哺点七条全部回写**：①06-待办清单——条目状态待办→已完成（入库 7ffd1dc0、冒烟 1151/0、单测 34 套、探针 case⑰、07 ㉘ 人闸五项）＋色相措辞修正为「样张 v2 冻结既裁值」＋2026-10-05 实查读数刷新（bonus_pick_overlay.gd 已改名 curio_pick_overlay.gd:97、TG_* 五族在役 ui_kit.gd:49-53）＋新增「卡顶色带与格面微光两带统一」待办条（Q3 甲案）；②HUD框架——实装状态行转「已实装（迭代 30 卡① 2026-10-17 入库，合并 `7ffd1dc0`）」、验收行转正式验收（去「待实施批落地后验收」括注）、版本历史 v0.19、口径史注记后补两带分工注记；③08-Alpha版本标准——「五 · 表现」表新增「未开格类型微光（五组色相＋明度档）」行（在役；明度档 provisional 值，样张批复核转正）＋版本历史 v1.9＋文头状态行 v1.8→v1.9；④art-bible——五组明度档 provisional 值（芥末黄 #F7DF43／黄绿 #68D042／青 #30A6A6／紫罗兰 #7B5BD6／绯红 **#A61D37**＝冻结 #FF2D55 的 V=0.65 档；五组 ΔH ≤0.13° 色相零移动）＋生成口径（渲染合成空间伽马阶梯、相邻组模型 CR 1.245/1.234/1.239/1.270、判据线 1.20、实测最弱对 1.232、群伤暗档停机呈报留痕）落版本历史 v3.15；§4.2/§4.6.3 权威面零改动、§2.1 未追加（Q5 甲案静态）；头注「现行为」v3.11→v3.15 漏更订正；⑤roadmap——迭代进度行、近期主战场行与迭代 30 表行状态列同步卡①已入库（②③待 `/iter` 发令）；⑥Q3 甲案两带分工——注记落 HUD框架 微光节、06 新待办条（见①）；⑦07-体验验证清单——新增 ㉘ 节五项人闸（五组一眼可分／不遮数字〔环不外溢〕／出圈灭入圈复亮／整屏不脏／群伤暗档 #A61D37 观感〔provisional，读数归样张批〕）＋版本历史 v1.5。**反哺点清单批注**：`reports/iter30-反哺点-2026-10-17.md` 加「回写结果」节逐条标已回写。**验收**：文档域闸 `tools/run_all_gates.sh --docs` 零新增红（回执 commit=`34f3cdb3`）。**遗留**：卡②③待 `/iter` 发令（未决面在册）；实机目检人闸五项（07 ㉘）待用户过目；群伤暗档 provisional 待样张批转正；`g-plan2-iter30-fb` 工作区待合回后清理。 - -- **513（2026-10-17，迭代 30 卡②③剔除批——零回滚·状态换代）**：用户先令排查迭代 30 已合入 master 的提交面（卡①实现五提交＋文档批＋卡片批等 14 笔在案），复查卡①质量后裁「卡①没有问题，保留」，**零 git 回滚**；随后裁定卡②③本质为设计澄清/美术定稿环节（卡②样张即设计目标图、产出规格反向给素材批；卡③挂素材轴定性人闸且素材规格依赖卡②产出），不满足「迭代=代码实现批」开发条件，令剔除迭代 30、在 06 登记状态「**待设计**」（前置=设计讨论→需求澄清→美术定稿，v1.4 原卡留 `design/research/` 作素材，禁未定稿直接开工）。落地：roadmap 三处换代（迭代 30 表行改单卡①＋剔除注、迭代进度行、近期主战场行）＋06 新登待设计条（两卡分列）；同批按前令删除三 worktree（`g-plan2-iter30-fb`／`iter30-glow`／`iter30-sample`）与三分支，sample 分支 5 个未合入提交一并废弃（含卡②样张批 T0/T1 方向稿三张与 515 终止记账，git 历史可考）。主区并行未提交件（术语表/project.godot/M4 卡片删除等）零触碰。 diff --git a/design/dev/architecture/architecture.md b/design/dev/architecture/architecture.md index 280b86e0..09761f97 100644 --- a/design/dev/architecture/architecture.md +++ b/design/dev/architecture/architecture.md @@ -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 都不比。 diff --git a/design/dev/code-conventions.md b/design/dev/code-conventions.md index 931b540a..f561a4d1 100644 --- a/design/dev/code-conventions.md +++ b/design/dev/code-conventions.md @@ -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 / 场景级测试 / 时点状态可见性）。 diff --git a/design/dev/doc-conventions.md b/design/dev/doc-conventions.md index f39033f0..b0cd3dea 100644 --- a/design/dev/doc-conventions.md +++ b/design/dev/doc-conventions.md @@ -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/` 是中间文档暂存地，入内文件默认到期即死 | diff --git a/design/dev/process-conventions.md b/design/dev/process-conventions.md index cfb61b88..ee3cee98 100644 --- a/design/dev/process-conventions.md +++ b/design/dev/process-conventions.md @@ -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-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.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 采集档位细则 diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index f7d1f2a4..34dab072 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -580,3 +580,74 @@ **归属**：全工程（排雷循环/战斗循环/冒险循环/呈现层/数据表/冒烟测试均触及；主责=术语表裁定执行） **状态**：待写卡 + + +--- + +#### 需求卡片入库纪律未登记——502 批遗留的悬空待办（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：2026-10-16 迭代 29 编入批（提交 `21c83f5`）认定「需求卡片写进了 roadmap 却没在 06 登记」属流程漏洞，需要补一条卡片入库纪律。该条至今在 06 清单内查无（2026-10-17 与 2026-10-18 两次全文检索零命中）。唯一记过它的地方是根目录状态文件未决面第 31 行，该文件已于 2026-10-18 用户裁废除，故改记本条防遗忘。 + +**归属**：design/dev/process-conventions.md 五段流水线的登记段 + +**状态**：待裁决（这条纪律要不要立；立则写进 process-conventions） + +--- + +#### req-card 技能的 WorkBuddy 与 ZCode 两份副本内容不一致——取齐待裁（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：用户级技能 req-card 在本机有两份副本，分别位于 WorkBuddy 与 ZCode 两个 harness 的用户目录 skills/req-card/SKILL.md（都在仓库之外，仓内没有任何登记处）。2026-10-18 逐字节比对：两份内容不同——迭代 28 那批只补了 ZCode 一份，WorkBuddy 那份没跟着改。这条欠账此前只记在根目录会话状态文件的未决面第 32 行，该文件已于 2026-10-18 用户裁废除，故改记本条。 + +**归属**：用户级技能 req-card（仓库外两份副本） + +**状态**：待裁决（以哪一份为权威取齐，或两份各自演化） + +--- + +#### 「魔法道具」与「罕见」两个旧叫法的残留未扫——扫不扫待裁（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：「魔法道具」随 2026-09-15 可选类道具删除而失效，「罕见」随 2026-09-14 分辨率档位批换装而失效，正文里仍有残留。2026-10-18 实数（全仓 markdown 检索）：魔法道具 23 处、罕见 17 处；此前根目录状态文件记的「约 30 处／约 18 处」系旧读数。两词都不在 `tools/doc_term_audit.py` 的退役词表里，机器闸抓不到，只能人工裁。 + +**归属**：design/gdd/ 正文用语（权威对照=design/gdd/术语表.md） + +**状态**：待裁决（扫或不扫；扫则把两词追加进 doc_term_audit 退役词表防再犯） + +--- + +#### 「通关」与「通过第 N 关」两种口径混用——统一与否待裁（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：「通关」一词既被用来指「打完一整局冒险」，也被用来指「通过第 N 关」，2026-10-18 实测 design/gdd 内 188 处（此前状态文件记 273 处，口径是全仓）。歧义直接影响难度曲线读数与验收判据的表述——同一个「通关率」两种读法差一个数量级。 + +**归属**：design/gdd/01-核心循环.md 与难度曲线、验收类文档的措辞口径 + +**状态**：待裁决（是否定单一口径并逐处改写） + +--- + +#### 流程动词族黑话的第二波清扫待发令——GDD 正文约三千处（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：2026-10-15 用语规范批只按 A 表替换了词面约 250 处（十二行），流程动词族——需要作者额外解释才看得懂的一类说法——在 GDD 正文仍有约三千处未处理。第二波至今未发令。 + +**归属**：design/gdd 全树正文用语（权威词表=design/gdd/术语表.md 用语规范节） + +**状态**：待裁决（第二波的范围与发令时点） + +--- + +#### 数据整改批回填 06 时按最近映射改写了九条存疑——判法待用户抽查（2026-10-18 登记，来源=批次移交，设计面=反哺点） + +**现状**：2026-10-18 数据整改批（提交 `60050a98`）把 06 存量 73 条按 doc-conventions §12.1 新格式逐条回填，其中九条属存疑映射、留了抽查清单：解锁界面目检消解、资产升档去留、氛围层并条、天赋树欠账两件、调参点评与 GP 换算入卡口径、奇物孤儿点、design/qa 七项状态词、迭代 30 剔除条重叠。同批首跑 08c 流水线闸拦下一条真不一致——M4 五条欠账被回填成引用 2026-10-16 已删除的卡片，追加提交 `865eaa30` 才退回待文档设计。这九条改写是否贴合原意，至今无人核过。 + +**归属**：design/gdd/06-待办清单.md 的回填质量 + +**状态**：待裁决（用户逐条抽查，不贴合的改回原口径） + +--- + +#### 调试入口写死行必须在发布前删除——game/presentation/main.gd:196（2026-10-18 登记，来源=批次移交，设计面=工程直入） + +**现状**：2026-10-16 用户令把调试入口改为恒开，`game/presentation/main.gd:196` 的 `_debug_entry` 现恒为 true、不再读环境变量（2026-10-18 实查该行仍为 `_debug_entry = true` 并带「发布前清」注释；:197 是最顶层浮层角标的可见性赋值）。发布前删掉 :196 这一行即可——角标可见性随门控失效自动隐藏，无第二处改动点。不删的后果：正式包里调试浮层与角标常显。证据=该行代码注释与 2026-10-16 调试入口批的实装记录。 + +**归属**：game/presentation/main.gd（Alpha 发布准备） + +**状态**：待写卡 diff --git a/game/tests/.gates/baseline.json b/game/tests/.gates/baseline.json index b78ea52f..4c091ca6 100644 --- a/game/tests/.gates/baseline.json +++ b/game/tests/.gates/baseline.json @@ -33,10 +33,6 @@ "exit": "0", "fp": "green" }, - "08b active.md 体量": { - "exit": "0", - "fp": "green" - }, "08c 流水线闸": { "exit": "0", "fp": "green" diff --git a/reports/README.md b/reports/README.md index 78db298d..8689c62d 100644 --- a/reports/README.md +++ b/reports/README.md @@ -16,7 +16,7 @@ - **不放设计结论。** 本目录的文件是"待处理的申请单"，不是事实源。反哺点由你在会话中讨论定稿后， 另开文档批写进 `design/`，写完即可删除本目录对应条目。 - **不放图。** 图像白名单不含本目录，放了会被熵增闸判红。 -- **不放进度状态。** 会话状态的唯一来源是根目录 `active.md`。 +- **不放进度状态。** 现在做什么看根 `roadmap.md` 顶部「当前位」节，待办与待裁看 `design/gdd/06-待办清单.md`（2026-10-18 用户裁：根目录会话状态文件已废除，本目录也不许兼做状态记录）。 ## 生命周期 diff --git a/roadmap.md b/roadmap.md index 70b1001c..65371072 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,6 +1,12 @@ # 工程路线图（批次执行制：里程碑 + 批次序列 + loop 规范） -> 一句话：项目级进度视图——走到哪了、接下来按什么顺序走、每个批怎么跑。**实时状态以仓库根 [active.md](active.md) 顶部「当前状态快照」节为准**（会话级、高频更新）；待办事项明细以 [06-待办清单](design/gdd/06-待办清单.md) 为唯一登记处（条目级）；本文件只管批级序列与门，里程碑移动才更新。 +> 一句话：项目级进度视图——走到哪了、接下来按什么顺序走、每个批怎么跑。待办与待裁事项以 [06-待办清单](design/gdd/06-待办清单.md) 为唯一登记处（条目级）；批次过程与结论查 git 提交信息与 `reports/`（2026-10-18 用户裁：根目录会话状态文件已废除，本节顶部「当前位」三行即其替代）。 + +## 当前位（只回答「现在该做什么」；三行内随批次换代，禁止在此扩写成状态快照） + +- **阶段**：M3——Alpha 版本的完整实现（2026-10-09 立规：未明令宣布完成前停留 M3，迭代只排 M3 需求，M4 不排期；根目录 stage.txt 为旧阶段开关仅存档）。 +- **迭代位**：迭代 1–30 全部已完成或已终止（末位＝迭代 30 卡① 未开格类型徽章批，合并 `7ffd1dc0`，2026-10-17）；**当前无在做的迭代**。 +- **下一步**：未编排。候选全在 06 状态列——营地交互重做五卡（已写卡待编迭代）、代码术语刷新批（待写卡）、迭代 30 原卡②③（待美术／设计定稿后重新立卡）；编排与发令权归用户。 ## 里程碑时间线 @@ -67,7 +73,7 @@ 1. **一迭代一 loop**：所有更改任务（功能/文档/数值/素材接线）一律进本路线图的迭代，每迭代先立计划书再开工，一个迭代一次合并登记——**零散并行会话退场**（多会话并行 = 冲突源+介入成本；2026-09-27 起单迭代串行执行）。状态记录记「批」= 本文件记「迭代」，同物异名。 2. **例外 = 零碎 bug**：单独会话 mini-loop 修复（修→轻闸→状态记录登记），不立计划书、不占迭代位；同屏同类 bug 攒够一笔可并入下一个迭代当任务卡。 -3. **用户输入闸显式化**：迭代门里所有需要用户表态的点（否决原因/裁决/试玩）在 active.md「未决面」可见，解一个开一个。 +3. **用户输入闸显式化**：迭代门里所有需要用户表态的点（否决原因/裁决/试玩）登记在 [06-待办清单](design/gdd/06-待办清单.md) 的状态列（待裁决／待美术设计／待写卡），解一个开一个。 ## 批次 loop 规范（loop engineering） @@ -82,8 +88,8 @@ 5. **重闸**（批末 Tn）：`tools/run_all_gates.sh` **按本批改动域跑**（只碰 `game/`、`tools/`、`artwork/` → `--code`；只碰 `design/` 与根规则文件 → `--docs`；跨两域或改闸件本身 → 不带参数全量），所选域全绿——闸件清单、顺序与域划分只在该脚本里定义，本文件与 CLAUDE.md/规约均不另列；MC 逐位对拍（涉核心）+ 素材批加机检断言另行。 6. **人闸**（停机交付）：真人目检清单 + 代拍板追认清单 + 异步终审触点（样张类）——本循环内唯一必经人审。 7. **异常分级**：L1 自救（一次重试）→ L2 记录继续（连续 3 次同红灯升级）→ L3 停机写报告等用户。 -8. **收口五步**：①active.md 快照 ②状态记录条目 ③里程碑移动更新本文件——**实现批禁写本文件**（2026-10-17 用户裁：代码实现批只准写 `reports/`），该步归文档批做，实现批在 `reports/iter-反哺点-<日期>.md` 列明该改哪一行 ④阶段变更改 stage.txt ⑤批末闸序列**按本批改动域**全绿留痕（loop_dashboard 已随目录收敛退役，透视职责由 06+状态记录承接）。 +8. **批次完成后的五步登记**：①06 条目状态按 doc-conventions §12.1 推进（做完整条删除）②本文件顶部「当前位」三行换代，涉及里程碑移动时同步里程碑表 ③**实现批禁写本文件与 `design/`**（2026-10-17 用户裁：代码实现批只准写 `reports/`），该改哪一行写进 `reports/iter-反哺点-<日期>.md`，由文档批执行 ④阶段变更改 stage.txt ⑤批末闸序列**按本批改动域**全绿留痕（回执 commit 对齐分支尖）。 ## 维护纪律 -同「批次 loop 规范」第 8 条收口五步；本文件由里程碑移动触发更新（批次开工/收口不强制改本文件，改的是 active.md 与 06）。快照节 ≤10 行，装不下的细节进状态记录。 +同「批次 loop 规范」第 8 条五步登记；本文件由里程碑移动与「当前位」换代触发更新（批次开工不强制改本文件，待办明细改 06）。「当前位」限三行，装不下的细节进 06 条目与 git 提交信息。 diff --git a/sim-data/README.md b/sim-data/README.md index 08e02346..c21b5aaa 100644 --- a/sim-data/README.md +++ b/sim-data/README.md @@ -34,4 +34,4 @@ - 采集：`game/smoke/adventure_monte_carlo.gd`（git）——参数 n/seed0/policy，seed 逐局独立 - 锚格式：stdout 捕获，每局一行 `RUNSUM` JSON（81000 锚=800 行=400×2 档）；自 2026-10-03 档位规起新锚统一=去前缀纯 JSONL 按种子升序（旧形态 analyze.py 直读会炸，见上「MC 采集档位表」配套纪律⑧） - 分析：`analyze.py`+`growth_model.py`（git）。⚠ analyze.py 默认输入名系首批遗留（runsum_600.jsonl 已不存在），跑现行锚须 `RUNSUM=<锚文件>` 指定，其完成度%段对现行锚未验证 -- fulllog 全量日志不留盘（.gitignore 排除）；`iteration_log.md` 系 Package B 时代批日志留盘不入库，新模拟批记录在 active.md 台账 +- fulllog 全量日志不留盘（.gitignore 排除）；`iteration_log.md` 系 Package B 时代批日志留盘不入库；新模拟批的读数与结论写在该批的 git 提交信息与 `reports/` 报告里（2026-10-18 用户裁：根目录会话状态文件已废除） diff --git a/tools/audit_active_state.py b/tools/audit_active_state.py deleted file mode 100644 index 1950c70d..00000000 --- a/tools/audit_active_state.py +++ /dev/null @@ -1,120 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -"""audit_active_state.py — 根目录 active.md 体量闸（doc-conventions §10 的机械面） - -状态文件只记当下：条目只增不减就是腐烂。本脚本查五条机械可判的膨胀签名—— -状态记录条目数超上限、快照节行数超上限、条目编号重复、快照整行自我重复、 -指向中间文档（design/qa、design/research）的死指针。 - -退出码：0=全绿；1=有红（逐条打印差额，供收口批据此删条目）。 -用法：python tools/audit_active_state.py [--file PATH] [--quiet] -""" -import argparse -import os -import re -import sys - -ENTRY_LIMIT = 30 # §10：状态记录超过 30 条必须清 -SNAPSHOT_LIMIT = 10 # §10：当前状态快照 ≤10 行 -INTERMEDIATE_PREFIX = ("design/qa/", "design/research/") -ENTRY_RE = re.compile(r"^- \*\*(\d+)( 续)?") -BULLET_RE = re.compile(r"^- .{20,}") -PATH_RE = re.compile(r"design/(?:qa|research)/[^\s)`,，。）]+?\.md") - - -def split_sections(text): - """按二级标题切段；标题前的内容归入 '' 键（文件头元信息，本闸不判）。""" - out, key = {}, "" - for line in text.splitlines(): - if line.startswith("## "): - key = line[3:].strip() - out[key] = [] - continue - out.setdefault(key, []).append(line) - return out - - -def find_key(sections, prefix): - for name in sections: - if name.startswith(prefix): - return name - return None - - -def audit(path, repo): - with open(path, encoding="utf-8") as f: - sections = split_sections(f.read()) - reds = [] - - snap_key = find_key(sections, "当前状态快照") - rec_key = find_key(sections, "状态记录") - if snap_key is None: - reds.append("A0 快照节缺失：状态文件必须含「当前状态快照」节") - if rec_key is None: - reds.append("A0 状态记录节缺失：状态文件必须含「状态记录」节") - - snap = [ln for ln in sections.get(snap_key, []) if BULLET_RE.match(ln)] - if len(snap) > SNAPSHOT_LIMIT: - reds.append("A1 快照节 %d 条，超上限 %d——先删被新一轮取代的旧行，别只往顶部加" - % (len(snap), SNAPSHOT_LIMIT)) - - seen = {} - for ln in snap: - seen[ln] = seen.get(ln, 0) + 1 - dups = [ln for ln, n in seen.items() if n > 1] - if dups: - reds.append("A2 快照节有 %d 行整行自我重复（换代不彻底的签名）：%s" - % (len(dups), dups[0][:60] + " …")) - - nums, conts = [], [] - for ln in sections.get(rec_key, []): - m = ENTRY_RE.match(ln) - if m: - (conts if m.group(2) else nums).append(int(m.group(1))) - if len(nums) > ENTRY_LIMIT: - reds.append("A3 状态记录 %d 条，超硬上限 %d——按 §10 判据删除已完结批次条目" - % (len(nums), ENTRY_LIMIT)) - repeated = sorted({n for n in nums if nums.count(n) > 1}) - if repeated: - reds.append("A4 条目编号重复（并行侧写撞号）：%s" - % "、".join(str(n) for n in repeated)) - - body = "\n".join(sections.get(snap_key, []) + sections.get(rec_key, []) - + sections.get(find_key(sections, "未决面"), [])) - dead = sorted({p for p in PATH_RE.findall(body) - if not os.path.exists(os.path.join(repo, p.replace("`", "")))}) - if dead: - reds.append("A5 指向中间文档的死指针 %d 处（文件已按 §11 退役，条目却还在引）：%s" - % (len(dead), "、".join(dead))) - return reds, len(nums), len(snap) - - -def main(): - ap = argparse.ArgumentParser(description="active.md 体量闸") - ap.add_argument("--file", default=None, help="待审文件（默认为本仓库根目录 active.md）") - ap.add_argument("--quiet", action="store_true", help="只输出结论行") - args = ap.parse_args() - - repo = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) - path = args.file or os.path.join(repo, "active.md") - if not os.path.exists(path): - print("[active.md 体量闸] 找不到文件：%s" % path) - return 1 - reds, entries, snap = audit(path, repo) - if reds: - print("[active.md 体量闸] FAIL：%d 项——状态记录 %d 条 / 快照 %d 行" % (len(reds), entries, snap)) - for r in reds: - print(" " + r) - return 1 - if not args.quiet: - print("[active.md 体量闸] PASS：状态记录 %d 条 / 快照 %d 行，编号唯一、指针全活" % (entries, snap)) - return 0 - - -if __name__ == "__main__": - try: - sys.stderr.reconfigure(encoding="utf-8", errors="replace") - sys.stdout.reconfigure(encoding="utf-8", errors="replace") - except Exception: - pass - sys.exit(main()) diff --git a/tools/repo_structure_audit.py b/tools/repo_structure_audit.py index 89366a11..51be951c 100644 --- a/tools/repo_structure_audit.py +++ b/tools/repo_structure_audit.py @@ -25,7 +25,7 @@ ROOT = Path(__file__).resolve().parent.parent # 清单的家——实现批只准往这里写，design/ 全目录对它只读。只放 .md，不放图（图像白名单不含此目录）。 TOP_DIRS = {"archive", "artwork", "design", "game", "sim-data", "tools", "reports"} # 2) 根目录文件白名单 -ROOT_FILES = {"CLAUDE.md", "active.md", "roadmap.md", "stage.txt", "review-mode.txt", +ROOT_FILES = {"CLAUDE.md", "roadmap.md", "stage.txt", "review-mode.txt", ".gitignore", ".zcodeignore"} # 3) 图像允许目录（相对路径前缀；archive/ 为归档 zip 不扫） # design/qa/ 收编（迭代 5 返工批 2026-09-29——U2 目检预览图/QA 呈现产物归位，commit 留痕） diff --git a/tools/run_all_gates.sh b/tools/run_all_gates.sh index dd7eab51..26286f7f 100644 --- a/tools/run_all_gates.sh +++ b/tools/run_all_gates.sh @@ -9,7 +9,7 @@ # 用法：tools/run_all_gates.sh [--code|--docs|--quick] # --code 只跑代码域闸（01 冒烟／02 单元／03 探针 --click／04 探针 --full／05 渲染闸／09 静态扫描 # ／11 回放确定性对拍＋10 熵增闸）——本批改动触及 game/ 时用（游戏工程的唯一代码验收域）。 -# --docs 只跑文档域闸（06 gdd_lint／07 doc_link／08 doc_term／08b active.md 体量／08c 流水线闸 +# --docs 只跑文档域闸（06 gdd_lint／07 doc_link／08 doc_term／08c 流水线闸 # ＋10 熵增闸） # ——本批改动不触及 game/ 时用：design/、根规则文件、tools/ 工具脚本、.zcode/ 配置等 # 一切非 game 改动的本域验收。 @@ -182,8 +182,6 @@ if in_domain docs; then gate "06 gdd_lint" "gdd_lint.log" "$PY" "$REPO/tools/gdd_lint.py" gate "07 doc_link" "doc_link.log" "$PY" "$REPO/tools/doc_link_audit.py" --strict gate "08 doc_term" "doc_term.log" "$PY" "$REPO/tools/doc_term_audit.py" --strict -# ── 6b. 状态文件体量闸（active.md 只记现在：条目数/快照行数/编号/死指针四条硬上限）── -gate "08b active.md 体量" "active_state.log" "$PY" "$REPO/tools/audit_active_state.py" # ── 8c. 流水线闸（06 条目状态机＋roadmap 迭代总表＋一次交叉核，判据=doc-conventions §12）── gate "08c 流水线闸" "pipeline.log" "$PY" "$REPO/tools/pipeline_gate.py" fi