gplan-2/design/engineering/process-conventions.md

流程规范（Dungeon Sweeper）

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

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

1. 分支纪律（worktree 铁律）

主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：

1. 开工：每批次先建独立 worktree：git worktree add ../g-plan2-<任务名> -b <任务分支>；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）
2. 收尾：迭代 loop 批次验证全绿（冒烟+场景探针）后在主工作区 git merge --no-ff <任务分支>，再 git worktree remove+删分支；合回前若 master 已被别的批次推进，先在分支里 git merge master 解冲突、重跑本域闸再合回。非 loop 批次合回前同样按本批改动域跑闸（见 §3.9：纯文档批跑 --docs）；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑
3. 豁免面：仅 .zcode/（钩子与配置）与 .qoder/（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截
4. 本铁律由 PreToolUse 钩子 .zcode/hooks/worktree-guard.sh 强制兜底；钩子只约束 agent，用户手工改动不受限

2. 五段流水线

一切要做的东西按五段流水线走：登记 → 文档设计／美术设计（双轨）→ 写需求卡片 → 迭代编排 → 实现。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 .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 迭代行	编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程直入证据）③总估时三条线——所选卡估时按区间中值求和（单位工作日、写精确值不取整）：低于 5 个工作日不得编（硬下限，2026-10-21 用户立：不希望单迭代编太少）；5–10 个工作日为常规区间、直接编；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日不得编（硬上限，2026-10-21 用户立：用户确认也不放行，必须拆批）④写完 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. 批次工作流标准清单

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

开工前

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

环境与基线 4. 独立 worktree+拷导入缓存——按 §1 建 worktree；先拷主区 .godot/ 目录与字体 .import 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则） 5. 涉数值改动先采改前读数——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟

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

完成 9. 批末按域验收才合并——在任务 worktree 内跑 tools/run_all_gates.sh，按本批改动域选档：本批改动触及 game/（游戏工程代码、测试、探针、场景）→ --code；不触及 game/ 的一切改动（design/、根规则文件、tools/ 工具脚本、.zcode/ 配置等）→ --docs；同批混触 game/ 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的唯一入口、唯一清单与唯一域划分，闸件增减、分域调整都只改它；本文与其他文档禁另列闸件清单（清单散落多处正是 iter27 漏跑 probe_gate --full 的成因）。跑完写回执 game/tests/.gates/receipt.json（含 domain 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（五况拦截：缺回执／quick 模式／回执 commit ≠ HEAD／域不覆盖本次改动／含新增红）。闸件（tools/ 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时的变异验证（test-conventions §6），闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底 10. 合并后主区按域复跑——合并可能引入冲突或环境差异，落回 master 后按本批改动域复跑：触及 game/ 的批＝全量复跑（维持）；纯文档域批＝复跑文档域档（秒级），不再全量 11. 批次完成后的登记义务——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。design/ 与根规则文件（AGENTS.md/roadmap.md/待办清单.md/体验验证清单.md）实现批禁写，见 §12 12. 文档同步闸（实现批禁写文档）——实现批禁写 design/ 整个目录与根规则文件，要往外交代的东西一律落 reports/：实现报告 reports/iter<N>-实现报告-<日期>.md（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 reports/iter<N>-代拍板-<日期>.md、GDD 反哺点清单 reports/iter<N>-反哺点-<日期>.md（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）任何批都不直改：用户在会话中逐点裁决后，由非迭代批（工具/规则/文档批）写入 design/（执行入口=doc-design 技能），并把反哺条目从 reports/ 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 reports/ 与待办清单；需求卡片必列「关联文档同步面」按两层标注 13. 实机目检归用户，只登记不阻塞——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 14. 中间产物吸收即死——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节 15. 改动级验收闭合——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §9

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

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

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

分级周期口径：全部验证闸收编在 tools/run_all_gates.sh 一个入口下（脚本即清单，且即域划分的唯一出处），分三档——--code／--docs 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；--quick 是全量档的中段自检形态（跳过渲染闸与静态扫描）；不带参数＝两域全量，用于一次改动同批混触 game/ 与文档面。完成出库按所选域全绿，回执由合回闸按 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. 修复默认附前后对比图+像素审计，不等用户索要