diff --git a/CLAUDE.md b/CLAUDE.md index d9d78364..8dd957fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,7 @@ ## 运行与验证(工作目录 = 含 project.godot 的切片目录) -- **交付前验收 = 跑 `tools/run_all_gates.sh`,按本批改动域选档(`--code` 只跑代码域/`--docs` 只跑文档域/不带参数=两域全量),所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单,**域划分也只写在它这一个地方**,闸件增减与分域调整都只改它,文档禁另列清单。改闸件本身、或一次改动同时跨两域时跑全量档(§6.2 共享件例外)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执(缺回执/quick 模式/回执 commit ≠ HEAD/域不覆盖本次改动/含新增红,五况一律拦截) +- **交付前验收 = 跑 `tools/run_all_gates.sh`,按本批改动域选档(`--code` 只跑代码域/`--docs` 只跑文档域/不带参数=两域全量),所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单,**域划分也只写在它这一个地方**,闸件增减与分域调整都只改它,文档禁另列清单。一次改动同批混触 `game/` 与文档面时跑全量档。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执(缺回执/quick 模式/回执 commit ≠ HEAD/域不覆盖本次改动/含新增红,五况一律拦截) - 单件直跑(调试期最窄确认用,**不构成验收**):系统级断言面 `python tools/run_smoke.py`(名带 smoke 但不止存活检查,术语见 `game/tests/README.md`)· 场景探针 `…console.exe --headless --path . res://smoke/ui_probe.tscn` · 单元 `… --script res://tests/run_all.gd` - 调参批量:`--script res://smoke/adventure_monte_carlo.gd`(全冒险期望)· `res://smoke/reward_expectation.gd`(奖励期望);通关率/难度类测量一律走全冒险 - 数值验证:`python tools/balance_verifier.py`(采集端 `res://smoke/verifier_batch.gd`,报告落 `design/qa/`) diff --git a/design/dev/process-conventions.md b/design/dev/process-conventions.md index e9d1bf59..cfb61b88 100644 --- a/design/dev/process-conventions.md +++ b/design/dev/process-conventions.md @@ -50,8 +50,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 后再跑全套 +10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`,**按本批改动域选档**:本批改动触及 `game/`(游戏工程代码、测试、探针、场景)→ `--code`;不触及 `game/` 的一切改动(`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等)→ `--docs`;同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**,闸件增减、分域调整都只改它;**本文与其他文档禁另列闸件清单**(清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 字段),合回时由 worktree-guard 按 diff 路径推域强制校验。闸件(`tools/` 下机检脚本与闸壳)自身的改动不占合回全量——其质量义务=落批时的变异验证(test-conventions §6),闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以合回全量为兜底 +11. **合并后主区按域复跑**——合并可能引入冲突或环境差异,落回 master 后按本批改动域复跑:触及 `game/` 的批=全量复跑(维持);纯文档域批=复跑文档域档(秒级),不再全量 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-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务)、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由非迭代批(工具/规则/文档批)写入 `design/`,并把反哺条目从 `reports/` 清掉(吸收即死)。机械面文档(roadmap 行/registry/README 工具注)同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与 06;需求卡片必列「关联文档同步面」按两层标注 14. **实机目检归用户,只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务;禁把等目检当停工理由或完成前置 @@ -63,7 +63,7 @@ **MC/verifier 触发细则**:仅在数值验证场景触发(改数值前后取证);normal 档为主、perfect 按需;**无数值改动的会话禁跑 MC**;结构位移类「存档锚」须先向用户请示定性再跑;需求卡片预设步骤的前提消失时(如「带值裁定后重锚」实际未投值)停问勿照字面执行。 -**分级周期口径**:全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下(**脚本即清单,且即域划分的唯一出处**),分三档——`--code`/`--docs` 按本批改动域只跑该域闸(代码域=冒烟/单元/探针两档/渲染闸/静态扫描/回放对拍;文档域=gdd_lint/doc_link/doc_term/active.md 体量;熵增闸两域都含);`--quick` 是全量档的中段自检形态(跳过渲染闸与静态扫描);**不带参数=两域全量**,用于改闸件本身或一次改动跨两域。完成出库按所选域全绿,回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。 +**分级周期口径**:全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下(**脚本即清单,且即域划分的唯一出处**),分三档——`--code`/`--docs` 按本批改动域只跑该域闸(代码域=冒烟/单元/探针两档/渲染闸/静态扫描/回放对拍;文档域=gdd_lint/doc_link/doc_term/active.md 体量;熵增闸两域都含);`--quick` 是全量档的中段自检形态(跳过渲染闸与静态扫描);**不带参数=两域全量**,用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿,回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。 ## 5. MC 采集档位细则 diff --git a/tools/run_all_gates.sh b/tools/run_all_gates.sh index 20633c4c..8b1168f2 100644 --- a/tools/run_all_gates.sh +++ b/tools/run_all_gates.sh @@ -8,12 +8,14 @@ # # 用法:tools/run_all_gates.sh [--code|--docs|--quick] # --code 只跑代码域闸(01 冒烟/02 单元/03 探针 --click/04 探针 --full/05 渲染闸/09 静态扫描 -# /11 回放确定性对拍+10 熵增闸)——本批改动只碰 game/、tools/、artwork/ 时用本档。 +# /11 回放确定性对拍+10 熵增闸)——本批改动触及 game/ 时用(游戏工程的唯一代码验收域)。 # --docs 只跑文档域闸(06 gdd_lint/07 doc_link/08 doc_term/08b active.md 体量+10 熵增闸) -# ——本批改动只碰 design/、active.md、roadmap.md、CLAUDE.md 时用本档。 +# ——本批改动不触及 game/ 时用:design/、根规则文件、tools/ 工具脚本、.zcode/ 配置等 +# 一切非 game 改动的本域验收。 # --quick 全量档的中段自检形态:跳过渲染闸(窗口化,需开显示器)与静态扫描;完成出库禁用。 -# 不带参数 = 全量档(两域全跑)。改闸件本身、或改动同时跨两域时,按 process-conventions §6.2 -# 共享件例外跑全量。 +# 不带参数 = 全量档(两域全跑),触发条件=同批混触 game/ 与文档面。闸件(tools/ 下机检脚本 +# 与闸壳)自身的改动不占合回全量——其质量义务=落批时的变异验证(test-conventions §6); +# 闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以全量为兜底。 # **域划分只在本脚本里定义一处**——文档只写「按改动域跑本脚本」,禁另列闸清单(清单散落多处 # 正是 iter27 漏跑 probe_gate --full 的成因)。 #