# 流程规范（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/`（钩子配置）允许主工作区直改；其余一律走 worktree，主工作区 git commit 被钩子拦截
4. 本铁律由 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. 批次工作流标准清单

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

**开工前**
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺
3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工

**环境与基线**
4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死
5. **改码前定基线三查**——记录冒烟全绿数目、单元测试套数、现行模拟基线读数；改完同口径对拍，红绿才能归因到本批
6. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明对拍口径；无数值改动禁跑模拟

**实施**
7. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并
8. **验收改动先行声明**——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补
9. **验收函数变异验证**——新增/改写的验收函数（冒烟断言/探针自检/闸机判据）必须配一次变异验证：故意把被测件改坏成该类缺陷形态 → 跑最窄那道闸确认变红 → `git checkout` 精确还原；变异点/跑的闸/红输出摘要/还原结论四件记入实现报告变异验证记录表；**无变异红记录的断言不写「已验收」，只写「已实现，拦截能力未证」**（细则见 test-conventions §6）

**收口**
10. **批末四闸全绿才合并**——冒烟+单元测试+场景探针+改前改后读数对拍
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**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。

**分级周期口径**：轻闸（run_smoke 全量+ui_input_probe；触碰 presentation 加跑 ui_click_probe+ui_layout_probe）可随变更执行；重闸=轻闸+probe_gate --click+probe_gate --full（ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四探针）+render_gate（窗口化渲染闸：shot_probe 七屏样张 A-D 断言+fx_shot/board_shot 取证+棋盘 golden 逐像素）+run_all 单元全套+doc 三闸（gdd_lint/doc_link_audit/doc_term_audit）+熵增闸（repo_structure_audit）；重闸属周期执行——统一在批次收口或固定周检跑，不进每次变更；真人实机目检归用户不进自动闸。

## 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. **修复默认附前后对比图+像素审计**，不等用户索要