From 22809f9b7924fb7d6b3daf3da0ccc9ccbe156e64 Mon Sep 17 00:00:00 2001 From: DKChan <524912269@qq.com> Date: Sun, 1 Nov 2026 02:09:29 +0800 Subject: [PATCH] =?UTF-8?q?=E5=B7=A5=E7=A8=8B+=E6=96=87=E6=A1=A3(=E5=90=88?= =?UTF-8?q?=E5=9B=9E=E5=8D=B3=E5=88=A0=E6=94=B9=E5=9B=9E=E6=89=B9=C2=B7?= =?UTF-8?q?=E7=94=A8=E6=88=B7=E4=BB=A4):=20=E5=88=A0=E5=8C=BA=E6=97=B6?= =?UTF-8?q?=E6=9C=BA=E6=94=B9=E5=9B=9E2026-09-19=E5=8E=9F=E8=A3=81?= =?UTF-8?q?=E3=80=8C=E5=90=88=E5=9B=9E=E5=8D=B3=E5=88=A0=E3=80=8D=E2=80=94?= =?UTF-8?q?=E2=80=94=E3=80=8CCI=E5=85=A8=E9=87=8F=E7=BB=BF=E2=86=92?= =?UTF-8?q?=E5=88=A0=E5=8C=BA=E3=80=8D=E7=B3=BB10-30=E6=9C=AC=E5=9C=B0CI?= =?UTF-8?q?=E5=8C=96=E6=89=B9(c91bbddd)=E9=87=8D=E5=86=99=C2=A71=E6=97=B6?= =?UTF-8?q?=E5=A4=B9=E5=B8=A6=E3=80=81=E6=9C=AA=E7=BB=8F=E7=94=A8=E6=88=B7?= =?UTF-8?q?=E5=8D=95=E7=8B=AC=E8=A3=81=E6=96=AD,10-31=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E6=81=A2=E5=A4=8D=E6=89=B9(94628fca)=E6=B2=BF=E7=94=A8?= =?UTF-8?q?=E6=9C=AA=E5=A4=8D=E4=BD=8D;=E6=81=A2=E5=A4=8D=E6=94=B6?= =?UTF-8?q?=E5=8F=A3=3D=E5=86=BB=E7=BB=93=E2=86=92=E4=BB=B6=E6=A0=B8?= =?UTF-8?q?=E2=86=92=E5=B9=B6master=E2=86=92=E9=87=8D=E5=A1=91=E2=86=92?= =?UTF-8?q?=E4=B8=BB=E5=8C=BAmerge=20--no-ff=E2=86=92=E5=90=88=E5=9B=9E?= =?UTF-8?q?=E8=90=BD=E5=9C=B0=E5=8D=B3git=20worktree=20remove+=E5=88=A0?= =?UTF-8?q?=E5=88=86=E6=94=AF,CI=E7=94=B1post-merge=E9=92=A9=E5=AD=90?= =?UTF-8?q?=E5=9C=A8=E5=90=88=E5=9B=9E=E8=90=BD=E5=9C=B0=E6=97=B6=E8=87=AA?= =?UTF-8?q?=E5=8A=A8=E8=A7=A6=E5=8F=91=E3=80=81=E4=B8=8E=E5=88=A0=E5=8C=BA?= =?UTF-8?q?=E8=A7=A3=E8=80=A6;=E7=BA=A2=E6=80=81=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E8=BD=A6=E9=81=93=E6=8D=A2=E8=BD=A8=3D=E6=96=B0=E5=BC=80?= =?UTF-8?q?=E4=BF=AE=E5=A4=8Dworktree(fix-<=E4=BB=BB=E5=8A=A1=E5=90=8D>?= =?UTF-8?q?=E5=88=86=E6=94=AF,=E9=9D=9Eiter=E5=BD=A2=E5=85=8D=E9=87=8D?= =?UTF-8?q?=E5=A1=91=E5=85=8D=E6=95=B0=E5=8D=A1,=E4=BF=AE=E5=A4=8D?= =?UTF-8?q?=E5=BD=92=E5=B1=9E=E5=8E=9F=E6=89=B9=E5=8D=A1=E7=89=87)?= =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=90=88=E5=9B=9E=E8=BF=BD=E7=BB=BF,?= =?UTF-8?q?=E8=BF=BD=E7=BB=BF=E5=A4=8D=E9=AA=8C=E8=90=BDpost-merge,post-co?= =?UTF-8?q?mmit=E9=92=A9=E5=AD=90=E9=99=8D=E4=B8=BA=E7=BA=A2=E6=80=81?= =?UTF-8?q?=E4=B8=BB=E5=8C=BA=E7=9B=B4=E6=8F=90=E5=85=9C=E5=BA=95=E8=A7=A6?= =?UTF-8?q?=E5=8F=91(=E6=9C=BA=E4=BB=B6=E9=9B=B6=E5=8A=A8);=E8=A7=84?= =?UTF-8?q?=E5=88=99=E6=96=87=E6=9C=AC=E4=BA=94=E6=96=87=E4=BB=B6=E5=8D=81?= =?UTF-8?q?=E4=B8=80=E5=A4=84=E9=9A=8F=E5=8A=A8:AGENTS=E8=BD=A6=E9=81=93?= =?UTF-8?q?=E9=93=81=E5=BE=8B=E8=A1=8C/=E8=BF=90=E8=A1=8C=E4=B8=8E?= =?UTF-8?q?=E9=AA=8C=E8=AF=81=E9=A6=96=E6=9D=A1/=E6=94=B9=E5=8A=A8?= =?UTF-8?q?=E5=9B=9B=E7=B1=BB=E8=A1=8C,process-conventions=20=C2=A71.2?= =?UTF-8?q?=E6=94=B6=E5=8F=A3=E5=BA=8F=E5=88=97=E4=B8=8E=E7=BA=A2=E6=80=81?= =?UTF-8?q?=E5=8F=A5/=C2=A71.3/=C2=A71.9=E2=91=A0,test-conventions=20?= =?UTF-8?q?=C2=A74,iter=E6=8A=80=E8=83=BD=E4=B8=A4=E5=A4=84+.qoder?= =?UTF-8?q?=E9=95=9C=E5=83=8F=E4=B8=A4=E5=A4=84(.zcode/.qoder=E8=B1=81?= =?UTF-8?q?=E5=85=8D=E9=9D=A2=E4=B8=BB=E5=8C=BA=E7=9B=B4=E6=94=B9=E4=B8=8D?= =?UTF-8?q?=E5=85=A5git);=E4=BB=B6=E6=A0=B8=3D=E6=97=A7=E8=AF=AD=E4=B9=89?= =?UTF-8?q?=E5=85=A8=E5=BA=93grep=E9=9B=B6=E6=AE=8B=E7=95=99,=E5=AE=88?= =?UTF-8?q?=E5=8D=AB=E6=95=B0=E5=8D=A1=E6=8F=90=E7=A4=BA=E3=80=8C=E5=9B=9E?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1worktree=E3=80=8D=E8=AF=AD=E4=B9=89=E4=BB=8D?= =?UTF-8?q?=E5=87=86(=E6=8B=A6=E6=88=AA=E6=97=B6=E4=BB=BB=E5=8A=A1?= =?UTF-8?q?=E5=8C=BA=E5=B0=9A=E5=9C=A8)=E9=9B=B6=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 6 +++--- design/engineering/process-conventions.md | 6 +++--- design/engineering/test-conventions.md | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e8d73a72..c30947c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ ## 运行与验证（工作目录 = 含 project.godot 的切片目录） -- **合回验证 = 本地 CI（2026-10-30 用户裁）**：git merge 合回 master 落地后，post-merge 钩子（`tools/hooks/post-merge`）后台触发 `tools/ci_runner.sh` 跑一次全量域闸（调 `tools/run_all_gates.sh` 不带参数档，02 全套件），结果落 `game/tests/.gates/ci-status.json`（commit／绿红／红闸名单＋关键日志行／耗时）＋`ci-history.jsonl` 流水账；CI 红态下每个修复提交经 post-commit 钩子（`tools/hooks/post-commit`）自动追绿复验，绿态与无状态零触发——批内提交零钩子检查、合回只验一次，同一份字节禁止第二次人手跑。CI 红不回滚合并，红项在案、修复提交追绿；开工先读 CI 状态，红未修不开新批。跑批起手自动 `--editor --quit` 刷类名缓存（.godot 缓存不入 git，防合并后失配假红）。`tools/run_all_gates.sh` 仍是全部验证闸的**唯一入口与唯一清单，域划分与选闸算法只写在它这一个地方**，闸件增减与分域调整都只改它，文档禁另列清单；`--code`／`--docs`／`--quick` 手动档只服务开发期按域跑批（开发期窄测纪律见 process-conventions §6），不构成验收；全量回归由用户自发发起 +- **合回验证 = 本地 CI（2026-10-30 用户裁）**：git merge 合回 master 落地后，post-merge 钩子（`tools/hooks/post-merge`）后台触发 `tools/ci_runner.sh` 跑一次全量域闸（调 `tools/run_all_gates.sh` 不带参数档，02 全套件），结果落 `game/tests/.gates/ci-status.json`（commit／绿红／红闸名单＋关键日志行／耗时）＋`ci-history.jsonl` 流水账；CI 红态下修复合回落地即由 post-merge 钩子复验追绿（红态修复走新开修复 worktree，`fix-<任务名>` 分支，免重塑免数卡；post-commit 钩子保留为红态主区直提兜底触发，绿态与无状态零触发）——批内提交零钩子检查、合回只验一次，同一份字节禁止第二次人手跑。CI 红不回滚合并，红项在案、修复合回追绿；开工先读 CI 状态，红未修不开新批。跑批起手自动 `--editor --quit` 刷类名缓存（.godot 缓存不入 git，防合并后失配假红）。`tools/run_all_gates.sh` 仍是全部验证闸的**唯一入口与唯一清单，域划分与选闸算法只写在它这一个地方**，闸件增减与分域调整都只改它，文档禁另列清单；`--code`／`--docs`／`--quick` 手动档只服务开发期按域跑批（开发期窄测纪律见 process-conventions §6），不构成验收；全量回归由用户自发发起 - 单件直跑（调试期最窄确认用，**不构成验收**）：冒烟测试 `python tools/run_smoke.py`（`game/tests/smoke_boot.tscn` 极小启动场景）· 系统测试 `python tools/run_system_test.py`（宿主 `game/tests/system_test.gd`）· 场景探针 `…console.exe --headless --path . res://probe/ui_probe.tscn` · 单元与集成 `… --script res://tests/run_all.gd` - 调参批量：`--script res://sim/adventure_monte_carlo.gd`（全冒险期望）· `res://sim/reward_expectation.gd`（奖励期望）；关卡完成率/难度类测量一律走全冒险 - 数值验证：`python tools/balance_verifier.py`（采集端 `res://sim/verifier_batch.gd`，报告与原始数据落 `sim-data/`） @@ -93,11 +93,11 @@ ## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约） -- 车道铁律（2026-10-31 用户裁恢复）——主工作区只作合并落点，一切开发/设计改动走独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`（建区即跑 `tools/setup_worktree_userdir.sh`），收口＝冻结→件核→并 master→重塑→主区 `git merge --no-ff`→CI 全量绿→删区，CI 红回任务 worktree 修复合回；主区唯一合法写动作＝合并，agent 侧由 worktree-guard 拦主区 Edit/Write 与非 merge 提交；豁免面仅 `.zcode/`、`.qoder/`（不入 git，主区直改）；commit 点零钩子检查（pre-commit 直改闸已退役），全量验证归合回后本地 CI（`tools/hooks/post-merge` 触发，见「运行与验证」首条）；`--no-verify` 仅属用户，agent 禁用（细则见 process-conventions §1） +- 车道铁律（2026-10-31 用户裁恢复）——主工作区只作合并落点，一切开发/设计改动走独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`（建区即跑 `tools/setup_worktree_userdir.sh`），收口＝冻结→件核→并 master→重塑→主区 `git merge --no-ff`→删区（合回即删，2026-09-19 原裁），CI 红不回滚合并——新开修复 worktree（`fix-<任务名>` 分支，免重塑免数卡）修复合回追绿；主区唯一合法写动作＝合并，agent 侧由 worktree-guard 拦主区 Edit/Write 与非 merge 提交；豁免面仅 `.zcode/`、`.qoder/`（不入 git，主区直改）；commit 点零钩子检查（pre-commit 直改闸已退役），全量验证归合回后本地 CI（`tools/hooks/post-merge` 触发，见「运行与验证」首条）；`--no-verify` 仅属用户，agent 禁用（细则见 process-conventions §1） - **仓库根禁止设会话状态文件**（`active.md` 已废除）——现状看 roadmap「当前位」，待办看待办清单，过程看 git 提交信息，产出物看 `reports/`；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节） - 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测 - 合回后验证 = 本地 CI 全量域闸全绿（唯一强制验证点；唯一入口、唯一闸清单、唯一域划分与选闸算法仍只在 `tools/run_all_gates.sh`，禁在文档另列；触发与追绿语义见「运行与验证」首条与 process-conventions §1）。开发期手动跑批按需选档（`--code` 关联档选测——02 跑「卡片申报 ∪ diff 推导」并集套件、三件保险恒跑、横切面回落全量——算法只在闸脚本内定义），手动跑不构成验收；全量回归由用户自发发起。文档面批与代码面批验收同走合回 CI 全量（`--docs` 仅属开发期手动档，process-conventions §1） -- **改动四类**——**需求改动**（游戏代码，含随逻辑写/改的测试代码）：唯一走「写需求卡片＋编入迭代批次」通道；迭代实现批禁写 `design/` 整个目录、两份根流程清单（`待办清单.md`/`体验验证清单.md`）与 `game/tests/README.md`（能力清单，归写卡段维护）（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；合回后由本地 CI 全量验证（红项修复提交追绿，process-conventions §1）。**工程改动**（tools/、闸件、模拟测量工具、纯测试维护——不改变游戏行为的配套代码）、**文档设计改动**、**美术素材改动**：不写需求卡片、不编迭代批次，由用户发令走独立 worktree 直改＋合回（车道铁律，commit 点零钩子检查）；大体量改动（含触及代码面的工程改动如纯测试维护）同车道无特殊通道；文档设计类写入走 doc-design 技能（登记条目格式由流水线闸强制） +- **改动四类**——**需求改动**（游戏代码，含随逻辑写/改的测试代码）：唯一走「写需求卡片＋编入迭代批次」通道；迭代实现批禁写 `design/` 整个目录、两份根流程清单（`待办清单.md`/`体验验证清单.md`）与 `game/tests/README.md`（能力清单，归写卡段维护）（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；合回后由本地 CI 全量验证（红项修复合回追绿，process-conventions §1）。**工程改动**（tools/、闸件、模拟测量工具、纯测试维护——不改变游戏行为的配套代码）、**文档设计改动**、**美术素材改动**：不写需求卡片、不编迭代批次，由用户发令走独立 worktree 直改＋合回（车道铁律，commit 点零钩子检查）；大体量改动（含触及代码面的工程改动如纯测试维护）同车道无特殊通道；文档设计类写入走 doc-design 技能（登记条目格式由流水线闸强制） - 五段流水线铁律——**需求改动**（游戏代码）按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」五段推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点——需求卡片任何工作量皆可写、皆可编入迭代，工作量限制只属迭代层（迭代估时总量 <5 个工作日＝「冻结待凑批」、不可开工）；流水线闸 `tools/pipeline_gate.py` 强制（已注册进 run_all_gates.sh 文档域）；实现段零裁断——卡片没写清=上游缺陷，停该卡退回上游，禁内联求裁（process-conventions §2，格式与状态机=doc-conventions §12）。工程／文档设计／美术素材三类改动不走写卡与编排段：（如需设计讨论）→ 用户发令 → 独立 worktree 直改 → 合回 CI（车道细则=process-conventions §1） - MC/模拟：无数值改动零跑；档位硬闸见 `sim-data/README.md`「MC 采集档位表」，一档只能由用户发起 - 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6） diff --git a/design/engineering/process-conventions.md b/design/engineering/process-conventions.md index 2d2bc86d..09393e77 100644 --- a/design/engineering/process-conventions.md +++ b/design/engineering/process-conventions.md @@ -10,8 +10,8 @@ 主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区（2026-10-31 用户裁恢复；2026-10-30 的「主区直改＋直提」车道与 commit 点 pre-commit 直改闸随之退役；验证模型不动——合回后本地 CI 仍是唯一强制验证点）： 1. **worktree 车道（一切面）**：每批先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；建区后立刻跑 `tools/setup_worktree_userdir.sh`——给该区独立 Godot user 目录（测试夹具、试玩日志、截图产物不与其他区共用；主区不生成，真实档保持原位）。所有改动与提交都在 worktree 内自由进行——commit 点零钩子检查（`tools/hooks/pre-commit` 已删除）。豁免面仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效） -2. **收口顺序（固定）**：**冻结 → 件核 → 并 master → 重塑 → 主区合回 → CI 验证 → 删区**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先在 worktree 内 `git merge master` 解冲突（必须在合回之前，合回后才并＝CI 验的是中间态）；**重塑**＝迭代分支（iter 形）合回前执行 `python tools/reshape_cards.py`，把分支线性史按卡末态快照压成一卡一笔（可选追加一笔纯文档收尾），master 台账由此每卡一行——工具自带「重塑前后树逐字节一致」断言与 backup 分支，不改任何文件内容；非迭代批免重塑；然后主工作区 `git merge --no-ff <任务分支>`——这是主区唯一合法写动作（合回守卫对迭代分支数卡校验，未归卡提交拦下）。**CI 全绿后才 `git worktree remove`＋删分支；CI 红不删区——回任务 worktree 修复提交再合，追绿后删区**。游戏类测试（冒烟/单测/MC/探针）批内默认零执行（两入口铁规，见 §4），用户点名或当场问才跑 -3. **合回后验证（本地 CI，2026-10-30 用户裁）**：git merge 合回 master 落地后 post-merge 钩子（`tools/hooks/post-merge`）后台触发 `tools/ci_runner.sh merge` 对 master 尖跑一次全量域闸——唯一强制全量验证点；CI 红态下每个修复提交经 post-commit 钩子（`tools/hooks/post-commit`）自动追绿复验（钩子仅主工作区生效——修复合回落地即触发），绿态与无状态零触发。重跑判据：同一份字节禁止第二次人手跑；有意义的重跑只剩「验证修复」一类。CI 红不回滚合并——红项记 `game/tests/.gates/ci-status.json`，开工先读 CI 状态，红未修不开新批。跑批起手 `--editor --quit` 刷类名缓存（在册坑：.godot 缓存不入 git，合并后失配假红假绿）。并跑语义＝跑完补跑（coalesce）：跑批期间新触发不中断当前轮，轮尾对最新尖端补跑，绝不逐笔各跑一轮 +2. **收口顺序（固定）**：**冻结 → 件核 → 并 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 形免重塑免数卡）修复提交再合，落地复验追绿后删修复区**。游戏类测试（冒烟/单测/MC/探针）批内默认零执行（两入口铁规，见 §4），用户点名或当场问才跑 +3. **合回后验证（本地 CI，2026-10-30 用户裁）**：git merge 合回 master 落地后 post-merge 钩子（`tools/hooks/post-merge`）后台触发 `tools/ci_runner.sh merge` 对 master 尖跑一次全量域闸——唯一强制全量验证点；CI 红态下修复合回落地即由 post-merge 钩子复验追绿（红态修复走新开修复 worktree，`fix-<任务名>` 分支，非 iter 形免重塑免数卡；post-commit 钩子保留为红态主区直提兜底触发，绿态与无状态零触发）。重跑判据：同一份字节禁止第二次人手跑；有意义的重跑只剩「验证修复」一类。CI 红不回滚合并——红项记 `game/tests/.gates/ci-status.json`，开工先读 CI 状态，红未修不开新批。跑批起手 `--editor --quit` 刷类名缓存（在册坑：.godot 缓存不入 git，合并后失配假红假绿）。并跑语义＝跑完补跑（coalesce）：跑批期间新触发不中断当前轮，轮尾对最新尖端补跑，绝不逐笔各跑一轮 4. **执法分层（全机械，零自觉依赖）**：①`.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／post-commit 钩子——本地 CI 触发（仅主工作区；任务 worktree 内的合并不触发）。③git 层不设车道钩子（pre-commit 直改闸已退役）——用户手工改动不受限；ZCode 层只约束 agent（子代理不经守卫层） ## 2. 五段流水线 @@ -49,7 +49,7 @@ **完成** 8. **合回后 CI 验证（唯一强制验证点）**——主工作区 `git merge --no-ff <任务分支>` 落地后 post-merge 钩子自动跑全量域闸（不带参数档，02 全套件），判定与红项落 `game/tests/.gates/ci-status.json`。全量是唯一强制档：跨卡触面、探针与未申报套件的消费漏网只有全量闸能抓（迭代 44 实证），关联档选测的盲区由它兜底。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分（含选闸算法与套件族映射表）**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。开发期手动跑批按需选档（按文件性质判域：代码面→`--code`，文档件→`--docs`，两类都有→全量；`--code` 关联档选测——02 只跑「需求卡片申报 ∪ diff 推导」并集套件、00 冒烟／01 系统测试／09 静态扫描三件保险恒跑、横切面回落全量——算法见闸脚本），手动跑不构成验收。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占 CI 全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变；闸真崩溃时 CI 判红在案（跑不出回执＝verdict 红，fail-closed 语义保留） -9. **重跑语义（2026-10-30 用户裁，取代原「每批一次／合并后零复跑」口径）**——同一份字节禁止第二次人手跑；允许的重跑只剩两类：① CI 红后的修复提交（post-commit 钩子自动追绿复验，每笔修复至多触发一轮）；② 用户自发发起的全量回归。「跑都跑了再跑一遍保险」「顺手改点再补一跑」都不构成重跑理由。类名缓存刷新与开机确认由 CI 跑批起手接管（§1 第 2 条），合并后无手工动作 +9. **重跑语义（2026-10-30 用户裁，取代原「每批一次／合并后零复跑」口径）**——同一份字节禁止第二次人手跑；允许的重跑只剩两类：① CI 红后的修复合回（post-merge 钩子复验，每轮修复至多触发一轮）；② 用户自发发起的全量回归。「跑都跑了再跑一遍保险」「顺手改点再补一跑」都不构成重跑理由。类名缓存刷新与开机确认由 CI 跑批起手接管（§1 第 2 条），合并后无手工动作 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-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务+实现决定记录——超白名单／超卡片明列范围事项逐条记「决了什么／为什么／代价／撤销方式」，全部按卡执行时只写一行「零拍板」）、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注 12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 diff --git a/design/engineering/test-conventions.md b/design/engineering/test-conventions.md index af6e306a..09c7c39e 100644 --- a/design/engineering/test-conventions.md +++ b/design/engineering/test-conventions.md @@ -27,7 +27,7 @@ ## 4. 验证时机（合回后本地 CI 制，2026-10-30 换代） -开发期窄测义务不变：每批开发中，本批新增/改动的验收测试自己跑绿即收口（卡内只测自己改的东西，process-conventions §6）。全量验证归合回后的本地 CI：git merge 合回 master 触发 post-merge 钩子跑 `tools/run_all_gates.sh` 不带参数档（两域全量，02 全套件——跨卡触面与关联档选测的盲区由全量兜底），结果落 `game/tests/.gates/ci-status.json`；CI 红态下修复提交经 post-commit 钩子自动追绿。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。 +开发期窄测义务不变：每批开发中，本批新增/改动的验收测试自己跑绿即收口（卡内只测自己改的东西，process-conventions §6）。全量验证归合回后的本地 CI：git merge 合回 master 触发 post-merge 钩子跑 `tools/run_all_gates.sh` 不带参数档（两域全量，02 全套件——跨卡触面与关联档选测的盲区由全量兜底），结果落 `game/tests/.gates/ci-status.json`；CI 红态下修复合回落地即由 post-merge 钩子复验追绿（修复走新开 `fix-<任务名>` 修复 worktree，process-conventions §1）。同一份字节禁止第二次人手跑。该脚本是全部验证闸的唯一入口与唯一清单，域划分与选闸算法只写在脚本里，本文禁另列闸件清单。 行为探针使用随机化玩家行为（封印/停手/刷新/无效点击）——自动玩家不做的动作就是测试盲区。 ## 5. 测试函数怎么写——验收清单条目的落码规范