流程规范（Dungeon Sweeper）

约束范围：一切批次的流程纪律——车道（一切改动走独立 worktree，主区只作合并落点）、五段流水线、批次工作流、测试执行细则、像素件工作纪律。分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。

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

1. 分支纪律（worktree 铁律）

主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区（2026-10-31 用户裁恢复；验证模型＝批内按 §4 改完即测、合回后远端 CI 是唯一强制全量验证点，细则见本节第 3 条）：

worktree 车道（一切面）：每回合先建独立 worktree（建区粒度＝回合，会话单区细则见第 5 条）：git worktree add ../g-plan2-<任务名> -b <任务分支>；建区后立刻跑 tools/setup_worktree_userdir.sh——给该区独立 Godot user 目录（测试夹具、试玩日志、截图产物不与其他区共用；主区不生成，真实档保持原位）。所有改动与提交都在 worktree 内自由进行——commit 点零钩子检查（tools/hooks/pre-commit 已删除）。豁免面仅 .zcode/（钩子与配置）与 .qoder/（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）
收口顺序（固定）：冻结 → 件核 → 并 master → 重塑 → 主区合回 → 删区——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先在 worktree 内 git merge master 解冲突（必须在合回之前，合回后才并＝CI 验的是中间态）；重塑＝迭代分支（iter 形）合回前执行 python tools/reshape_cards.py，把分支线性史按卡末态快照压成一卡一笔（可选追加一笔纯文档收尾），master 台账由此每卡一行——工具自带「重塑前后树逐字节一致」断言与 backup 分支，不改任何文件内容；非迭代批免重塑；然后主工作区 git merge --no-ff <任务分支>——这是主区唯一合法写动作（合回守卫对迭代分支数卡校验，未归卡提交拦下）。合回落地即 git worktree remove＋删分支（合回即删，2026-09-19 原裁）；post-merge 钩子已在合回落地时自动触发 CI，红态不回滚合并——新开修复 worktree（fix-<任务名> 分支，非 iter 形免重塑免数卡）修复提交再合，落地复验追绿后删修复区。批内的验证义务按 §4 改完即测铁规履行——改完即测自己改过的那部分，不请示、不等点名；收口顺序本身不设跑批关口
合回后验证（远端 CI，2026-11-03 用户裁）：git merge 合回 master 落地后 post-merge 钩子（tools/hooks/post-merge）自动 git push origin master 触发远端 CI（Gitea Actions，runner＝Mac 本机 host 模式），工作流按改动域分流（分流算法单点＝tools/ci/domain_route.sh：游戏码批＝两域全量含渲染闸，文档批＝文档域秒级闸，纯闸件/管线批＝零触发）——唯一强制全量验证点。远端结果用 tools/ci_check.sh <合并提交> 按需现查（读该提交任务的 run 自身 status/conclusion，只呈报、不落盘），agent 开工先读 CI 状态的纪律不变，红未修不开新批。绿须坐实：零触发批的 run 照样建、照样 conclusion=success，但跑闸步是 skipped（run 55 实证）——一条闸都没跑不构成验证，现查件对此呈报「未验」（退出码 4），禁当绿证用；job 列表为空、取不到步级读数或工作流里没有跑闸步时呈报「不可判」，同样禁当绿证。CI 红态不回滚合并——修复走新开修复 worktree（fix-<任务名> 分支，非 iter 形免重塑免数卡），修复合回落地即再推再验追绿（追绿同链）。导入缓存刷新（.godot 不入 git 的在册坑）由工作流「导入缓存刷新」步接管。合回零等待纪律（2026-11-04 用户裁，取代 2026-11-02 回执等待纪律）：合回落地即向用户呈报本批总结并止回合——不挂后台轮询、不等回执、不被唤醒；CI 结论什么时候要看就现查一次（tools/ci_check.sh，run 那时早已落定，秒级）。退役缘由＝原轮询件把「commit status 离开 pending」当终局判据，会把 run 未落定期的尝试级失败写成终局红（run 37 实证：开跑 36 秒写红，该 run 三分半后 conclusion=success），且零触发批与 runner 排队必熬满超时再写红；同 commit 的多路轮询还重复覆写同一份判定。跑闸等一切分钟级跑批的等待纪律不变——后台运行，禁前台 sleep／轮询循环。
执法分层（全机械，零自觉依赖）：①.zcode/hooks/worktree-guard.sh（PreToolUse，本机件不入 git）——agent 侧：主工作区 Edit/Write 与主区非 merge git commit 拦截（豁免 .zcode/、.qoder/；worktree 内目标快速放行；合并收尾提交凭 MERGE_HEAD 豁免）、git commit --no-verify 拦截（该旗标仅属用户）、iter 分支合回的一卡一提交数卡校验、规则闸（写 design/／game/ 前核对会话规约读取记录）。②post-merge 钩子——远端 CI 触发（只推送，不挂等待；仅主工作区，任务 worktree 内的合并不触发）。③git 层不设车道钩子——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层）
会话单区（2026-11-04 用户裁）：建区粒度＝回合——同一时刻每会话至多一个 worktree 在役；合入删区之前，会话内用户追加的事项一律并入在役区推进，禁为追加事项另开新区。区内全部事项完成后只做一次合入（一次 git merge --no-ff、post-merge 一次推送、远端 CI 只跑一次），追加事项在合入提交信息里分列；无改动需求的事项不建区。合回删区后用户再发令的事项＝新回合，另开新区（区名取该回合主任务名）。CI 红的 fix-<任务名> 修复区属同一回合的追绿延续，不另算新区。迭代实现批（iter 形分支）独占回合——其他类事项不得并入迭代区（合回守卫数卡校验本就拦未归卡提交），待其合回后按新回合另开。

2. 五段流水线

需求改动（游戏代码，含随逻辑写/改的测试）按五段流水线走：登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现；工程／文档设计／美术素材三类改动不走写卡与编排段，走「（如需设计讨论）→ 用户发令 → 独立 worktree 直改 → 合回 CI」（车道细则见 §1）。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝「冻结待凑批」，不可开工。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 .zcode/skills/：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。

段	入口技能	产出	出入口铁律
一·登记	无（闸管格式）	待办清单条目	条目=标题登记元数据（日期/来源/可选优先级）＋正文四属性（实况/缺口/改动面/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节
二·文档设计／美术设计	doc-design（文档线，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出）	GDD 文档或 art-bible／过审样张素材	用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；设计线闭合凭据记入待办清单实况清单（文档线=文档路径+版本号，美术线=art-bible 条款版本）；缺哪条线写在缺口属性，闭合与否写在状态段
三·写需求卡片	req-card	需求卡片	设计线闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=需求性工程条目（缺陷修复／重构等改游戏行为）凭实况里的证据指认跳过设计线；配套维护类（工程债/测试基建/工具维护，不动游戏行为）＝工程改动直改类，不走本段，由用户发令直改；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入实况清单（防遗忘）
四·迭代编排	iter-plan	roadmap 迭代行	编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间中值求和（单位工作日、写精确值不取整）：卡片任何工作量均可编入（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认
五·实现	iter	代码与配置，可运行的游戏	需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+实现决定记录写齐即完成批内义务

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

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

3. 批次工作流标准清单

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

开工前

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

环境与基线 4. 一切批走 worktree 车道＋拷导入缓存——按 §1 建 worktree（建区粒度＝回合，同回合多批共用一区——§1 第 5 条）；涉代码域跑闸或测试的批先拷主区 .godot/ 目录与字体 .import 边车（纯文档批免拷），否则全量重导入资源近似卡死。检出工作区无改动即无验证义务（§4 的反面），直接开工；闸壳每次跑批先自检/自愈本区 user 目录隔离（§1 第 1 条），建不起来即拒跑 5. 涉数值改动先采改前读数——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟。Alpha 阶段口径（2026-11-04 用户裁）：Alpha 阶段先做机制与内容填充，数值层统一修正殿后——本阶段的投放批与内容批零读数、零 MC 取证，改前读数与难度带读数义务后移到数值统一修正批执行；本条对数值统一修正批本身恢复原义。

实施 6. 新功能必配新测试——新增玩法/机制必须配套新测试套件进 tests/run_all，并按 test-conventions §8 挂进改动—验收对照表；两者的履行与取证按 §4 改完即测铁规（改完即跑、读数在案），不在收口顺序里另设跑批关口。拆件/重构产出的新 core 件不属新增玩法，由 test-conventions §8.3「新增 core 件的覆盖登记义务」承接（被 tests 面点名，或在能力行申报「经宿主链覆盖」），核对动作归本清单第 10 条的收尾提交 7. 验收改动先行声明——验收变化（基线换代/探针增改/旧断言改判）预先写进需求卡片，禁事后补

完成 8. 合回后 CI 验证（唯一强制全量验证点）——主工作区 git merge --no-ff <任务分支> 落地后 post-merge 钩子自动推送 origin master 触发远端 CI；远端按改动域分流（§1 第 3 条），全量档兜的是跨卡触面、探针与未申报套件的消费漏网（迭代 44 实证），判定与红项用 tools/ci_check.sh <合并提交> 按需现查（读 run 终局态，只呈报不落盘）。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。tools/run_all_gates.sh 是全部验证闸的唯一入口、唯一清单与唯一域划分（含选闸算法与套件族映射表），闸件增减、分域调整都只改它；本文与其他文档禁另列闸件清单（清单散落多处正是 iter27 漏跑 probe_gate --full 的成因）。开发期的验证义务与选档一律见 §4，CI 全量档不替代它。闸件（tools/ 下机检脚本与闸壳）自身的改动不占 CI 全量——其质量义务＝按 §4 把该件实跑一遍（最小参数全路径含产出落盘）并核对判据口径未变；闸真崩溃时远端 CI 判红在案（job 失败＝verdict 红，fail-closed 语义保留） 9. 重跑语义（2026-10-30 用户裁）——同一份字节禁止第二次人手跑；允许的重跑只剩两类：① CI 红后的修复合回（post-merge 钩子再推再验，每轮修复至多触发一轮）；② 用户自发发起的全量回归。「跑都跑了再跑一遍保险」「顺手改点再补一跑」都不构成重跑理由。导入缓存刷新由远端工作流「导入缓存刷新」步接管，合并后无手工动作 10. 批次完成后的登记义务——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。design/ 与根规则文件（AGENTS.md/roadmap.md/待办清单.md/体验验证清单.md）实现批禁写，见 §12 11. 文档同步闸（实现批禁写文档）——实现批禁写 design/ 整个目录与根规则文件，另禁写 game/tests/README.md（能力清单，归写卡段维护，test-conventions §8.9），要往外交代的东西一律落 reports/：实现报告 reports/iter<N>-实现报告-<日期>.md（各卡状态+实机目检总清单+遗留读数义务+实现决定记录——超白名单／超卡片明列范围事项逐条记「决了什么／为什么／代价／撤销方式」，全部按卡执行时只写一行「零拍板」）、GDD 反哺点清单 reports/iter<N>-反哺点-<日期>.md（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）任何批都不直改：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 design/（执行入口=doc-design 技能），并把反哺条目从 reports/ 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 reports/ 与待办清单；需求卡片必列「关联文档同步面」按两层标注 12. 实机目检归用户，只登记不阻塞——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 13. 中间产物吸收即死——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节 14. 改动级验收闭合——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动的验收断言从真实入口进入、在当轮真实跑批中执行并通过（判据绑定面口径=test-conventions §8.4；禁变异类测试与撤销类取证，2026-10-24/28 用户两裁）；合回前独立验收审计。细则=test-conventions §8

4. 改完即测铁规（细则）

改完即测（2026-11-05 用户裁，取代原「测试执行两入口铁规」及一切「默认零执行／先请示／不构成验收」口径）——任何会话里的任何改动，落笔之后立刻跑一遍覆盖该改动面的验证并跑绿、读数写进这一步的提交信息，这一步才算完成。跑什么由改动面决定，载体一律见 tools/run_all_gates.sh 的域划分与该件自身的直跑方式：游戏行为面＝被改的测试套件与场景探针从真实入口直跑；文档面＝该脚本的文档域档；工具件与闸壳＝该件自己最小参数全路径跑一遍含产出落盘（动了闸壳本体时，按 §6 第 2 条它的最小充分单元就是全套档）。不扩出改动面、不请示、不等点名；未改动的面不测，零改动的会话（问答/调研/审查/纯读码）根本不触发本条。合回后远端 CI 的全量跑批不替代本条，本条也不得拿去重跑 CI 已跑过的同一份字节（§3 第 9 条）。读数类采集（MC/verifier）不在该域划分内，不属本条义务，触发权与档位见 §5。

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

分档口径：全部验证闸收编在 tools/run_all_gates.sh 一个入口下（脚本即清单，且即域划分的唯一出处）——按改动域选档跑，档位清单与选闸算法只写在脚本头部注释，本文不重列；开发期的跑批义务一律按 §4 履行。唯一强制全量点＝合回后远端 CI（§1 第 3 条、§3 第 8 条）。真人实机目检归用户不进自动闸。

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；四档仅承接数值验证场景，读数采集的触发权不随 §4 改完即测铁规扩大。

6. 闸机轮次纪律（§4 改完即测的执行形状：何时只跑最小单元、何时才够格跑全套）

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

7. 像素结构件工作纪律

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

22 KiB Raw Blame History Unescape Escape