# 流程规范（Dungeon Sweeper）

> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。
> 分工：硬性红线的一句话索引在 CLAUDE.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。

**开工任何批次前必须通读本文。**

## 1. 分支纪律（worktree 铁律）

主工作区（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 被钩子拦截
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限

## 2. 五段流水线

一切要做的东西按五段流水线走：**登记 → 文档设计／美术设计（双轨）→ 写需求卡片 → 迭代编排 → 实现**。段间不自动流转，每段转进由用户发令；每段一个用户级技能入口，登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。

| 段 | 入口技能 | 产出 | 出入口铁律 |
|---|---|---|---|
| 一·登记 | 无（闸管格式） | 06-待办清单条目 | 条目=标题登记元数据＋正文四属性（现状/缺口/归属/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |
| 二·文档设计／美术设计 | doc-design（文档轨，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从 06 取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；轨闭合凭据记入 06 状态（文档轨=文档路径+版本号，美术轨=样张过审+art-bible 条款版本） |
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程直入四类（缺陷修复/工程债/测试基建/重构）凭证据跳过设计轨；卡片必经 grilling 多轮复核、零待裁点才成立；写完在 06 状态记「已写卡」＋卡片路径（防遗忘） |
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程直入证据）③总估时 ≤2 周 ④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 13 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |

**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、06 状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。

**流水线闸**：`tools/pipeline_gate.py` 机检 06-待办清单与 roadmap 两文件的格式与互相引用；将注册进 `run_all_gates.sh` 文档域（注册归第二批，本批不注册）。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。

## 3. 批次工作流标准清单

每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：

**开工前**
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺
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`，**按本批改动域选档**：只碰 `game/`、`tools/`、`artwork/` → `--code`；只碰 `design/`、`active.md`、`roadmap.md`、`CLAUDE.md` → `--docs`；同时跨两域、或改的是全部闸共用的壳（闸脚本本身/探针包装器）→ 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验
11. **合并后主区全量复跑**——合并可能引入冲突或环境差异，落回 master 后再跑全套
12. **会话完成落记**——active.md 快照与状态记录更新（含删除已完结旧条目，doc-conventions 第 10 节）；跨会话教训写入记忆库；漏删旧条目由 `tools/audit_active_state.py` 在全量档抓（合回闸强制，脚本即清单）。**例外**：active.md 是会话状态唯一源、不是文档产出物，实现批照写（合回闸钩子本就对它放行）；`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 节

## 4. 测试执行两入口铁规（细则）

测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。

**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。

**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（代码域＝冒烟/单元/探针两档/渲染闸/静态扫描/回放对拍；文档域＝gdd_lint/doc_link/doc_term/active.md 体量；熵增闸两域都含）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于改闸件本身或一次改动跨两域。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。

## 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. 闸机轮次纪律

1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验
2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可
3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批
4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）

## 7. 像素结构件工作纪律

1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）
2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感
3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错
4. **修复默认附前后对比图+像素审计**，不等用户索要