DKChan
1d4ac91e3b
用户令「迭代完成前必须全量跑一遍所有测试」。起因是 iter27 台账只记 probe --click 未记 --full，t17_defer_probe 红了整个迭代无人发现——根因是闸清单散落 CLAUDE.md / process-conventions.md / test-conventions.md 三处、彼此不一致、且无任何机器校验。 - tools/run_all_gates.sh（新）：全部验证闸的唯一入口与唯一清单，串跑冒烟/单元/探针 --click/--full/渲染/doc 三闸/静态扫描/熵增闸共十道，写回执 game/tests/.gates/receipt.json。 与 baseline.json 比对判定：基线红且红项清单未变＝存量红零新增（不判失败）， 基线绿转红或红项清单变化＝新增红（判红）。python 解释器自动解析带 PIL 的解释器 并前置 PATH（渲染闸三个脚本依赖 PIL，用错解释器会假红）。 - .zcode/hooks/worktree-guard.sh：Bash 分支加合回闸——merge/rebase/cherry-pick 进 master 前按目标分支反查 worktree 回执，校验 commit 匹配/非 quick/无新增红三态， 任一不满足 exit 2 拦截（九态实测：匹配放行、commit 错/quick/含红/无回执/rebase 全拦）。 - game/smoke/t17_defer_probe.gd：隔离面从 main.save_manager = iso_c 改 ProbeUiUtil.isolate_save（iter27 已确立口径）。原写法对 getter-only 属性赋值无效 ——组合根 save_manager/meta 是 autoload 读视图，隔离必须落在单例上。修复后 --full 转绿。 - doc_link 三处死链归零：数据配置.md 已退役探针指路、元进度.md/天赋树.md 已改名文档链接。 - CLAUDE.md / process-conventions.md §3第10条 / test-conventions.md §4 三处 「交付前跑什么」统一为一句话＝跑 run_all_gates.sh，删散落清单。 闸况：冒烟 0 / 单元 0 / --click 0 / --full 0 / 渲染 0 / doc_link 0 / doc_term 0 / 熵增 0；gdd_lint 与 static_scan 为存量红，已落 baseline.json 待判读清偿。
10 KiB
流程规范（Dungeon Sweeper）
约束范围：一切批次的流程纪律——分支与 worktree、三段开发流程、批次工作流、测试执行细则、像素件工作纪律。 分工：硬性红线的一句话索引在 CLAUDE.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。
开工任何批次前必须通读本文。
1. 分支纪律（worktree 铁律）
主工作区（master 检出）只作合并落点与共享状态载体，一切开发/设计改动不得直接发生在主工作区：
- 开工：每批次先建独立 worktree：
git worktree add ../g-plan2-<任务名> -b <任务分支>；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运） - 收尾：迭代 loop 批次验证全绿（冒烟+场景探针）后在主工作区
git merge --no-ff <任务分支>，再git worktree remove+删分支；合并前先看 active.md 尾部状态记录，防并行会话撞号/漏捎带；收口按 doc-conventions 第 10 节退役规则删除已完结条目。非 loop 批次默认收口不跑闸（两入口铁规），用户点名或当场问 - 豁免面：仅根目录
active.md（会话收口）与.zcode/（钩子配置）允许主工作区直改；其余一律走 worktree，主工作区 git commit 被钩子拦截 - 本铁律由 PreToolUse 钩子
.zcode/hooks/worktree-guard.sh强制兜底；钩子只约束 agent，用户手工改动不受限
2. 三段开发流程
一切要做的东西按三段走：设计 → 写需求卡片 → 实现。段间不自动流转，每段转进由用户发令。
| 段 | 产出 | 出入口铁律 |
|---|---|---|
| 一·设计 | GDD 文档或 art-bible | 用户提起或从 06-待办清单 取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许落文档；完成判据=待裁点清零，带未裁点的是讨论稿；不自动进写卡段，写卡须用户另行发令 |
| 二·写需求卡片 | 需求卡片（写作规范见用户级技能 req-card） | 设计定稿后用户发令；例外=缺陷修复/工程债/测试基建/重构凭 bug 证据或 06 条目直接进入；新玩法/新系统/新内容必须有设计定稿前置；卡片必经 grilling 多轮复核、零待裁点才成立；入库必在 06 登记一条（防遗忘）；编入后续未完成迭代（roadmap 迭代行），无空位与用户确认开新一轮 |
| 三·实现 | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 /iter 技能与本文 §3 执行；设计权威文档（GDD/art-bible）批内一律不更新，实现批只出迭代实现报告（见 §3 第 12 条）；收口人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
3. 批次工作流标准清单
每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：
开工前
- 先检索后提问——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑
- 需求卡片全列备选案——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺
- 用户发开工令才动手——需求卡片经用户批准（U0）后方开工
环境与基线
4. 独立 worktree+拷导入缓存——按 §1 建 worktree；先拷主区 .godot/ 目录与字体 .import 边车再跑测试，否则全量重导入资源近似卡死
5. 改码前定基线三查——记录冒烟全绿数目、单元测试套数、现行模拟基线读数；改完同口径对拍，红绿才能归因到本批
6. 涉数值改动先采改前读数——与改后同随机种子配对比较并写明对拍口径；无数值改动禁跑模拟
实施
7. 新功能必配新测试——新增玩法/机制必须配套新测试套件进 tests/run_all；没有对应测试的变更不许合并
8. 验收改动先行声明——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补
9. 验收函数变异验证——新增/改写的验收函数（冒烟断言/探针自检/闸机判据）必须配一次变异验证：故意把被测件改坏成该类缺陷形态 → 跑最窄那道闸确认变红 → git checkout 精确还原；变异点/跑的闸/红输出摘要/还原结论四件记入实现报告变异验证记录表；无变异红记录的断言不写「已验收」，只写「已实现，拦截能力未证」（细则见 test-conventions §6）
收口
10. 批末全量验收才合并——在任务 worktree 内跑 tools/run_all_gates.sh（不带 --quick），全绿才合回 master。该脚本是全部验证闸的唯一入口与唯一清单，闸件增减只改它；本文与其他文档禁另列闸件清单（清单散落多处正是 iter27 漏跑 probe_gate --full 的成因）。跑完写回执 game/tests/.gates/receipt.json，合回时由 worktree-guard 强制校验
11. 合并后主区全量复跑——合并可能引入冲突或环境差异，落回 master 后再跑全套
12. 会话收口落记——active.md 快照与状态记录更新（含删除已完结旧条目，doc-conventions 第 10 节）；跨会话教训写入记忆库
13. 文档同步闸——机械面文档（roadmap 行/registry/active.md 记账/README 工具注）合并前随批更新完毕方算收口；设计权威文档批内不更新：实现批收口出迭代实现报告（design/qa/iter<N>-实现报告-<日期>.md：各卡状态+代拍板追认单+GDD 反哺点节），反哺点同步登记 06-待办清单，用户逐点裁决后另批落文；反哺点未落文期间相关 GDD 节视为待反哺，读前先查 06；需求卡片必列「关联文档同步面」按两层标注
14. 实机目检归用户，只登记不阻塞——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务；禁把等目检当停工理由或收口前置
15. 中间产物吸收即死——细则见 CLAUDE.md 硬性红线与 doc-conventions 第 11 节
4. 测试执行两入口铁规（细则）
测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①迭代 loop 开发（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②用户主动点名。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。
MC/verifier 触发细则：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；无数值改动的会话禁跑 MC；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。
分级周期口径：全部验证闸收编在 tools/run_all_gates.sh 一个入口下（脚本即清单），分两档——--quick 档跳过渲染闸（需开显示器）与静态扫描，供迭代中段自检；收口出库一律跑全量档（不带 --quick），回执由合回闸强制校验。真人实机目检归用户不进自动闸。
5. MC 采集档位细则
四档硬闸（全表与统计精度见 sim-data/README.md「MC 采集档位表」）：
| 档 | 用途 | 上限 | 触发权 |
|---|---|---|---|
| 一档·调研 | 调研/数值分析 | 总量 >40 | 只能由用户发起——需求卡片/计划书/agent 均无权授权 |
| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 |
| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 |
| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 |
配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；对拍断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。
6. 闸机轮次纪律
- 孤立验证先行——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验
- 调试期最窄确认——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可
- 长批试车——≥2 分钟的跑批（逐位对拍冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批
- 开工坑册扫描——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）
7. 像素结构件工作纪律
- 先抄后造——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）
- 验收口径写成像素级视觉判据——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感
- ±1px 一律坐标推导——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错
- 修复默认附前后对比图+像素审计，不等用户索要