Merge branch 'master' into iter30-glow-20261017
This commit is contained in:
DKChan committed
commit
2aa7e8fdc1
11 files changed
+156
-60
No files matched your search
@@ -12,47 +12,44 @@
|
||||
- **引擎**：Godot 4.7.2 + GDScript（2026-09-07 锁定；`.claude/docs/technical-preferences.md` + `docs/engine-reference/godot/`；**MEDIUM RISK**——2026-09-12 `/setup-engine refresh` 逐条核实 4.5–4.7 官方迁移指南，无破坏架构契约项，current-best-practices.md 已建）
|
||||
- **架构**：`design/dev/architecture/architecture.md` v1.6（2026-09-12 /create-architecture 产出；2026-10-15 确立为架构唯一事实源——历史决策文档体系已废除、沿革归 git commit log；review-mode.txt = solo）
|
||||
- **待办清单**：`design/gdd/06-待办清单.md`（2026-09-16 收编批起为全项目待拍板唯一登记处；系统文档只留指路存根，新增条目直接登记清单，裁决后改状态列留痕）
|
||||
- **批次出口报告**：随批落 `design/qa/`（证据只留最新一轮，doc-conventions §11）
|
||||
- **批次产出物**：迭代批的实现报告、代拍板追认单、GDD 反哺点清单落根目录 `reports/`（2026-10-17 用户裁：迭代批禁止写 `design/`，`reports/` 是其唯一可写目录）；证据只留最新一轮，细则见 `design/dev/doc-conventions.md` §11
|
||||
- **工程路线图**：根目录 `roadmap.md`（里程碑时间线的权威；实时状态看下方快照节）
|
||||
|
||||
## 当前状态快照（收口批先更新本节，再追加状态记录；≤10 行）
|
||||
- **更新于**：2026-10-16（**迭代 29 测试分层与门禁语义修正批已入库**——三硬闸落地＋L2/L3 建承载＋L1 补洞六套＋S3/S5 修复；冒烟 1127/0、run_all 33 套、轻闸探针 10 件、重闸全绿存量红零新增；M4 数值批已废、四项欠账归 06 在册待裁）。
|
||||
- **最新闸态**：迭代 29 批末冒烟 1127/0、run_all 33 套（含 1 集成）、probe --click 残留 0、render golden 棋盘×3 0.00%＋菜单 0.15%、doc 三闸与熵增对基线零新增、static_scan S3/S5 新落地（S10 存量 127 在册）；**11 号闸 parity 判为触面、待用户批准才发起**，MC 未跑。
|
||||
- **probe --full 曾有一件红**：`t17_defer_probe`「关卡画面未出现」，用户已裁为存量红、不阻合并（合并 5b958ff6）；根因是探针未隔离带断点的真实存档，该修复已随 `gatefix-20261015` 合入 master（合并 de8d28b6）。
|
||||
- **更新于**：2026-10-17（**GDD 反哺点写入批**——用户裁「全部按推荐案」：迭代 27 两条／28 三条／29 三条＋一条建议写入 architecture.md v1.8、code-conventions.md §4 第 7–12 条、test-conventions.md §7–§8、07 v1.4；三份实现报告迁位 `reports/`、roadmap 死指针清零；此前同日已合并迭代 29 批 `fff4f120` 与闸按域分跑批 `60c25ca3`〔重闸三档、迭代批禁写 design/、建 reports/〕，M4 数值批已废归 06 待裁）。
|
||||
- **最新闸态**：重闸唯一入口 `tools/run_all_gates.sh` 按改动域分跑（代码域 01 冒烟／02 单元／03-04 探针／05 渲染／09 静态扫描／10 熵增／11 对拍，文档域 06 gdd_lint／07 doc_link／08 doc_term／08b active.md 体量／10 熵增；**域划分只在该脚本定义一处，文档禁止另列闸清单**）。文档域末次回执 commit=`3f9ec7c5`，五闸全绿零存量红（本反哺写入批的 --docs 回执=分支尖，见合并说明）。代码域末次实测读数（2026-10-16 合并后主区）：冒烟 1127/0、单元 33 套（含 1 集成）、探针 --click 残留 0、渲染 golden 棋盘×3 与菜单均 0.00%（菜单基线已在合并代码上重采 `dac9a94b`）、static_scan S3/S5 在位、S10 文件头存量已由清偿批归零（基线里的 09 仍记红，下次跑代码域时按「基线红→现绿」对齐）、doc 三闸与熵增对基线零新增；**11 号闸 parity 是条件闸件，迭代 29 批判为触面、须 `PARITY_APPROVED=1` 才发起**，MC 未跑。
|
||||
- **迭代 28 交付**：修好启动时菜单被冒险层盖住的装配顺序，层序收敛为唯一装配合同（散落的两处 `move_child` 删除）；boot 链路、九阶段生命周期、启动态菜单 golden 三组验收补全；本批新立硬规则「验收函数无变异红记录不算验收成立」，三处规约落文。
|
||||
- **迭代 27 交付**：三屏壳场景与局态物化、结算五段拆分、RunLedger 单类持四账、模态编排类、类型闸、死代码退役，编排器由 1725 行降到 1325 行。
|
||||
- **规约体系现状**：规则文件按领域拆为 7 份、单文件上限 150 行，CLAUDE.md 只留元信息、命令、目录、规范导航与一行一条红线；动手前按规范导航表查对应细则。
|
||||
- **规约体系现状**：规则文件按领域拆为 7 份、单文件上限 150 行，CLAUDE.md 只留元信息、命令、目录、规范导航与一行一条红线；动手前按规范导航表查对应细则。2026-10-17 增两条硬边界：迭代批（`/iter` 发射的代码实现）对 `design/` 只读、禁止在其中新增/修改/删除任何文件，产出物只准落 `reports/`，批末只跑代码域闸；非迭代批（工具/规则/文档改动）不占 roadmap 迭代号，按改动域跑闸。
|
||||
- **人闸在册两件**：迭代 27 全流程走查〔07 ㉖〕与迭代 28 启动态菜单〔07 ㉗〕，均登记不阻塞；贫矿脉目检项〔07 ⑪〕已随 2026-10-16 屏蔽令转记失效；迭代 19~26 的目检已于 2026-10-14 全部核销。
|
||||
- **簿记出清**：迭代 19~26 的代拍板追认单与 GDD 反哺点已全部裁决落文，对应 14 份迭代实现报告按「证据只留最新」删除（git 历史可考）。
|
||||
- **已裁在册**：M4 数值批已废（2026-10-16 用户删卡令——禁止再以该名义立批/规划/引用已删卡，四项数值欠账归 06 在册、重新归属待裁）；**迭代 29=测试分层与门禁语义修正批 ✅ 已入库**（需求卡片 v2.0 零待裁点；收口遗留＝11 号闸 parity 对拍待批准发起、GDD 反哺三条待裁、06 在册遗留七项）；迭代 27/28 位预留追加卡。
|
||||
- **已裁在册**：M4 数值批已废（2026-10-16 用户删卡令——禁止再以该名义立批/规划/引用已删卡，四项数值欠账归 06 在册、重新归属待裁）；**迭代 29=测试分层与门禁语义修正批已合并**（`fff4f120`，十提交）；**迭代 30=UI 呈现三卡批已编入·待开工**（2026-10-16 用户令编入，提交 `272cc1ad`；三卡待裁项同日按推荐方案代拍板留痕、卡片均 v1.2；迭代内串行 ①未开格类型徽章→②战斗一屏样张→③二三关棋盘观感，禁三线并行；开工门 U0＝`/iter` 发令）；迭代 27/28 位预留追加卡。
|
||||
- **界面美化三层**：第一层三件全部交付；余第二层三件（贴图/字体/样张）与第三层其余（九宫格切片/棋盘观感）待立项。
|
||||
|
||||
## 未决面（进行中/待人闸/待裁点指针；现行事实源登记处=`design/gdd/06-待办清单.md`）
|
||||
- 待用户裁决（06 在册）：迭代 27 GDD 反哺两条；迭代 28 GDD 反哺三条；美术审计两项 P0（art-bible 死样张指涉、主角像素管线重产）；去毒残留词是否清扫（「魔法道具」约 30 处、「罕见」约 18 处）；喂雷流 R5 甲重启条件回落文；「通关」与「通过第 N 关」全库口径统一（约 273 处）；**贫矿脉屏蔽的设计语义面反哺五处**（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注——均描述已撤回功能，待裁是否改写，机械面已同步）。
|
||||
- 待用户追认：迭代 27 代拍板十五项、迭代 28 代拍板十三项（含四条白名单外），清单在两份现行实现报告的追认单节（`design/qa/iter27-实现报告-2026-10-14.md`、`design/qa/iter28-实现报告-2026-10-15.md`）；req-card 技能的 WorkBuddy 与 ZCode 两份副本是否取齐待裁。
|
||||
- 待发令：**迭代 29 测试分层与门禁语义修正批**（U0 门：Q3–Q7 裁点＋卡片 v2.0 重核＋`/iter` 发令）；迭代 27/28 预留追加卡；黑话清扫第二波（GDD 正文流程动词族约三千处）；规则文件编写 skill（按 497 批工作流提炼）。
|
||||
- **迭代 29 已合入（2026-10-16 用户令「直接合入，不用重测」）**：合并提交 `fff4f120`，分支 `iter29-testlayers-20261016` 十提交入库。合入前卡的两个红均非本批引入（渲染闸 `menu_boot.png` 4.61% 已由并行会话 dbgfloat 批重制基线解决；gdd_lint `01-核心循环.md` R5 缺流程图归其引入批 `9846a29f`）。本批遗留：11 号闸 parity 对拍待用户批准发起（`PARITY_APPROVED=1`）、GDD 反哺三条待裁、06 在册遗留七项。
|
||||
- 在途分支未合入 master（读现状时勿当已入库）：`art-standee-20261006`（artwork 独立仓 dry-run 报告＋立绘定档，领先 5 笔）、`stc-norm-20261015`（GDD 用语规范批，领先 4 笔）；`gatefix-20261015` 已合入 master（合并 de8d28b6）；`ci-removal-20261015` **未合入**（4 项改动仍是 worktree 未提交状态——其 ADR 定位两条已被 2026-10-15「决策文档体系废除」批取代，仅 CI 清除部分对迭代 29 仍有效）；`doc-adr-fixes-20261014` **方向已废**（ADR 四节重建/修订注记与用户「ADR 不需要保存」裁定相反，分支去留待用户裁）。
|
||||
- 待用户裁决（06 在册）：美术审计两项 P0（art-bible 死样张指涉、主角像素管线重产）；去毒残留词是否清扫（「魔法道具」约 30 处、「罕见」约 18 处）；喂雷流 R5 甲重启条件回落文；「通关」与「通过第 N 关」全库口径统一（约 273 处）；**贫矿脉屏蔽的设计语义面反哺五处**（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注——均描述已撤回功能，待裁是否改写，机械面已同步）。
|
||||
- 待登记 06：需求卡片入库纪律一条（502 批遗留，2026-10-17 在 06 清单内查无该条，属悬空待办）。
|
||||
- 待用户追认：仅剩 req-card 技能的 WorkBuddy 与 ZCode 两份副本是否取齐一项。迭代 27 代拍板十五项、迭代 28 十三项（含四条白名单外）、迭代 29 十二项已于 2026-10-17 用户令「追认单的所有我都是同意的」全部同意，三份实现报告（2026-10-17 文档批已迁位 `reports/`）的追认单节已就地标注追认结果；迭代 29 第四节「经你裁决的四项」不在追认范围（当时已问过已答）。
|
||||
- 待发令：**迭代 30 UI 呈现三卡批**（三卡 v1.2 零待裁残留，迭代内串行 ①→②→③，开工门 U0＝`/iter` 发令；卡片=`design/research/需求卡片-未开格类型徽章批-2026-10-16.md`／`design/research/需求卡片-战斗一屏样张批-2026-10-16.md`／`design/research/需求卡片-二三关棋盘观感批-2026-10-16.md`；三批合计 ≈11–14d 超软盒 7d，须按批次分会话逐个发令）；迭代 27/28 预留追加卡；黑话清扫第二波（GDD 正文流程动词族约三千处）；规则文件编写 skill（按规则文件审计与目录划分批的工作流提炼，见提交 `81c0ee2b`）。
|
||||
- 待批准发起：**11 号闸 parity 回放确定性对拍**（迭代 29 把它收编为重闸里的条件闸件，每次跑批只做触面判定、不自动跑；迭代 29 批已判触面并挂 NEED-APPROVAL，批准方式＝带 `PARITY_APPROVED=1` 发起，MC 须用户批准才跑）。
|
||||
- 在途分支未合并 master（读现状时勿当已入库）：`art-standee-20261006`（worktree `g-plan2-standee-tier`，领先 5 笔——artwork 独立仓 dry-run 报告＋立绘定档）、`doc-adr-fixes-20261014`（worktree `g-plan2-doc-adr-fixes`，领先 5 笔，**方向已废**——ADR 四节重建/修订注记与用户「ADR 不需要保存」裁定相反，分支与 worktree 去留待裁）。已合并的 worktree/分支清理（2026-10-17 用户令执行）：`g-plan2-iter29-testlayers`、`g-plan2-menusub-20261016` 两工作区与分支 `adr-purge-20261015`、`adr-leak-fix-20261016` 已删；`ci-removal-20261015` 已按 2026-10-16 既裁重做（只删 `.github/workflows/tests.yml`、撤 ADR 两条）合并 `db032fb5` 后工作区与分支同删；**仅剩 `g-plan2-carddoc-20261017` 工作区在盘**（分支 `carddoc-20261017` 已合并 `480d8118`），删除待令。
|
||||
- 在册观察（06 登记，非阻塞）：迭代 27 卡片义务补登两项——长函数余量 17 个中的装配/校验函数、lambda 连接防回归。
|
||||
|
||||
## 状态记录（滚动窗口：仅当前迭代；退役规则见 doc-conventions §10）
|
||||
|
||||
- **496（2026-10-15，迭代 28 启动装配与生命周期验收补全批总收口）**：单会话交付七提交并合并 5b958ff6，冒烟 1086→1125/0（新增 42 条断言，退役 3 条把错误顺序写成期望值的裸下标断言）。四条结论：①启动装配顺序错误（菜单被冒险层盖住）已修，层序判定收进单一合同 `LAYER_CONTRACT`，散落的两处手工 `move_child` 删除；②boot 链路十断言与九阶段×五引用面生命周期矩阵入库；③渲染面补两件探针自检、墨色判据与启动态菜单 golden；④六次变异注入全部见红并精确还原，拦截能力已证。变异 3 顺带证明墨色占比判据自身不可靠——菜单被藏时底层棋盘仍给高反差像素，该强弱分层写进 code-conventions §3.6。批内类型闸自纠一笔（`main.gd:453` 缺元素类型，改 `Array[Variant]` 后 S9 归零）。存档面风险已核实：全部 worktree 共享同一份 `user://save.json`，定位过程中临时移开的真实档已逐字节校验还原。
|
||||
|
||||
- **497（2026-10-15，规则文件审计与目录划分批收口）**：对照 Anthropic 与 OpenAI 七个真实仓库 40~330 行的实测密度重整规约——规则文件由 3 份 560 行拆为 7 份 543 行，单文件 150 行硬上限，CLAUDE.md 压到 68 行只留元信息、命令、目录划分、规范导航和一行一条红线；细则按领域归位到 process/test/doc/code/concept 五份规约，反面案例另存案例库不常驻加载。迭代 28 并行落文的变异验证硬规则按新结构重归位（细则在 test-conventions §6）。合并 81c0ee2b，worktree 与分支已清理。
|
||||
|
||||
- **498（2026-10-15，active.md 退役清理批）**：按 doc-conventions §10 执行一次状态退役——删除迭代 20~27 的 31 条已完结条目（判据三条齐备：批次已入库、结论已进快照、未决项不指向条目；内容可在 git 历史完整复原），状态记录由 34 条降到 3 条，回到 30 条硬上限内。快照节原为 21 条且整块自我重复（两条「更新于」、两条「批末闸全绿」、两条逐字相同的「迭代 26 交付」），去重换代为 10 条。删掉「项目当前位置」整节——该节滞后于快照与 roadmap，里程碑归 `roadmap.md`、实时进度归快照节。未决面按迭代 27/28 现行待裁与待追认重列，并把三条在途未合入分支登记在册以免被当已入库。本批零代码、零其他文档改动。
|
||||
|
||||
- **499（2026-10-15，active.md 收口机制批）**：用户裁定收口检查的触发时机不能挂在"一轮答话结束"上——旧的 Stop 钩子判的是「active.md 内容有没有变」，追加新条目就算变，结构上永远抓不到"没删旧条目"；且它比对的还是已废弃路径 `production/session-state/active.md`。实测三份 harness 副本现已全部失效：Qoder 侧快照零份、ZCode 侧没接 Stop 事件、Claude 侧配置为空。改法分两层：机械层 = `tools/audit_active_state.py` 判五条膨胀签名（状态记录条目数超 30、快照行数超 10、条目编号重复、快照整行自我重复、指向 `design/qa`|`design/research` 的死指针），并入 `tools/run_all_gates.sh` 为 08b，由既有合回闸回执强制，不另立第二份闸清单；语义层 = `active-closing` 技能，规定用户问「任务是否结束」时先跑闸、按 §10 三判据逐条核对并删除、报删除清单，然后才回答。变异验证：对换代前的 34 条版本报 5 项红（连 472/477/481/494 撞号与 6 处报告死指针一并抓出），对退役后的 3 条版本报绿。钩子副本收敛为单一事实源：`.qoder/settings.json` 改指 `.zcode/hooks/worktree-guard.sh`，该脚本加 `QODER_PROJECT_DIR` 兼容并把 `.qoder/` 纳入豁免面（gitignored 配置走 worktree 带不进去），`.qoder/hooks/` 三份副本删除。脚本层守卫五例实测（stdin 直喂）：主区改 tracked 文档拦、改 active.md 放行、改 .qoder 放行、主区 commit 拦、无全量回执的 merge 拦。**待核**：hooks 属各 harness 私有配置、不随仓库传播——ZCode 侧确认在跑，Qoder 侧本会话活体探针未被执行（`.claude/settings.json` 仍为空），故拦截力目前只在 ZCode 生效，成因待诊断。全量闸由用户自跑，本批按令合回 master（分支 `active-gate-20261015`，合并见提交史）。
|
||||
|
||||
- **500（2026-10-15，决策文档体系废除 + architecture.md 确立架构唯一事实源，文档批）**：用户裁「ADR 不需要保存，任何决策记录在 git commit log 里记好，不需要工作日志文档存在」——七份 `adr-0001~0007` 全删（内容留 git 历史），architecture.md 删「ADR 审计」「ADR 立项清单」两节、文档状态立「事实源地位」条（唯一事实源），未决表关闭 QQ-01/02/03、立项清单在途事项转登记 QQ-11~14，补 A1 生成姿态与 autoload 四件（ConfigDB/RngService/SaveManager/MetaProgression）事实；CLAUDE.md 新增「架构事实唯一源」红线并恢复 RNG 单点红线；doc-conventions §5/§11 落架构唯一事实源条文；registry 删 18 处 adr 字段；game/ 约 60 处代码注释与 GDD/qa/research/roadmap/tests README 引用全清，豁免标记 `ADR-0007-exempt`→`rng-seed-exempt` 五处同步（main.gd/static_scan.sh/architecture.md/06/iter27）；主区 4 个未跟踪今日产物（测试审计报告/两张需求卡片/自造短语清单）就地清除。走 worktree `adr-purge-20261015` 合并 4ed48b86；死链校验 1206 链接 0 死链、gdd_lint 0 不通过；按用户令未跑测试闸（本会话合回闸未触发、receipt 未生成）。代码中 `adr`/`adr5` 等为 AdventureRunner 既有局部变量名（smoke/单测 5 文件约 60 处），非文档引用、未动。**遗留呈报待用户裁**：`ci-removal-20261015` worktree 的 ADR 两条改动已被本批取代（仅 CI 清除部分对迭代 29 有效）、`doc-adr-fixes-20261014` 分支方向已废，两个 worktree/分支的去留待裁。
|
||||
- **500（2026-10-15，决策文档体系废除 + architecture.md 确立架构唯一事实源，文档批）**：用户裁「ADR 不需要保存，任何决策记录在 git commit log 里记好，不需要工作日志文档存在」——七份 `adr-0001~0007` 全删（内容留 git 历史），architecture.md 删「ADR 审计」「ADR 立项清单」两节、文档状态立「事实源地位」条（唯一事实源），未决表关闭 QQ-01/02/03、立项清单在途事项转登记 QQ-11~14，补 A1 生成姿态与 autoload 四件（ConfigDB/RngService/SaveManager/MetaProgression）事实；CLAUDE.md 新增「架构事实唯一源」红线并恢复 RNG 单点红线；doc-conventions §5/§11 落架构唯一事实源条文；registry 删 18 处 adr 字段；game/ 约 60 处代码注释与 GDD/qa/research/roadmap/tests README 引用全清，豁免标记 `ADR-0007-exempt`→`rng-seed-exempt` 五处同步（main.gd/static_scan.sh/architecture.md/06/iter27）；主区 4 个未跟踪今日产物（测试审计报告/两张需求卡片/自造短语清单）就地清除。走 worktree `adr-purge-20261015` 合并 4ed48b86；死链校验 1206 链接 0 死链、gdd_lint 0 不通过；按用户令未跑测试闸（本会话合回闸未触发、receipt 未生成）。代码中 `adr`/`adr5` 等为 AdventureRunner 既有局部变量名（smoke/单测 5 文件约 60 处），非文档引用、未动。**遗留呈报待用户裁**：`ci-removal-20261015` worktree 的 ADR 两条改动已被本批取代（仅 CI 清除部分对迭代 29 有效）、`doc-adr-fixes-20261014` 分支方向已废，两个 worktree/分支的去留待裁（2026-10-17 核：`ci-removal-20261015` 已合并 master、worktree 仍在盘；`doc-adr-fixes-20261014` 仍未合并，两条的现状与清理待令都记在未决面）。
|
||||
|
||||
- **501（2026-10-15~16，简明技术中文用语规范批总收口）**：用户令对 design/gdd 全 45 文件做三层语言规范并融合词表——词面约 250 处按术语表「用语规范」A 表替换（不得→禁止/收口→完成/随批→顺带等 12 行，五子代理分四波执行+逐处语境裁决）、术语表 v1.12 新立「用语规范」节（STC 词表为权威+豁免三类+注销词义限定注）、词条五组（总线/抽屉、机能件/机制件、装板/摇号、坍塌显形、增益归一）+死链全库清零（3 处：config_fatal_probe 去向双证落 v0.4 行注、武器锻造漏改 2 处）+doc_term_audit 吸收 A 表 10 词与随批/台账补扫通道。**本批两教训**：①合回闸与「文档批零测试」铁规冲突时助手机械服从、擅跑全量测试两轮（含渲染闸），用户暴怒——正解=改闸的判断条件，现守卫已加「纯文档合入豁免」（merge diff 不触 game/ 直接放行，代码合入仍全量闸）；②坑册新增：守卫按命令文本解析分支名（cd 前缀/环境变量前缀连坐误拦）、.import 边车被全局忽略致 worktree 冷检出探针 texture=null 假红。合并 af321c03（九提交，纯文档合入未跑测试，同日 4ed48b86 前例）。
|
||||
- **502（2026-10-16，迭代 29 编入批——roadmap 门牌登记）**：用户令「把需求卡片写进 roadmap 的迭代 29」——此前需求卡片只存在于中间文档，roadmap 仍写「下一前沿=迭代 29+ M4 数值批」，致别的会话启动迭代 29 时跑去做 M4（该卡同日已被用户删除＝死引用）。本批三改：①roadmap 迭代 29 行改写为「测试分层与门禁语义修正批」（需求卡片=`design/research/需求卡片-测试分层与门禁语义修正批-2026-10-15.md`，v1.4，T0–T8≈5.5–7d，开工门 U0＝Q3–Q7 裁点＋卡片 v2.0 重核＋`/iter` 发令），新增「迭代 30+ 位空」行记录 M4 废除（禁止再以该名义立批/规划/引用已删卡；四项欠账归 06 在册待裁），迭代 23+ 原始泊位行加作废注仅作排期史保留；②需求卡片升 v1.5（排期行与 §5 同步行更新；登记 v2.0 重核遗留＝残留 CI 措辞四处＋事实基线换代〔冒烟 1086→1125/0、门禁五闸→run_all_gates.sh 编排、architecture.md 测试域节已成文、Q3 的 CI timeout 前提消失〕；订正 v1.3 版本条目尾部重复段）；③本文件快照与未决面三行同步换代。文档三闸全绿（gdd_lint 0 不通过／死链 0／疑似现行 0）。提交 21c83f5。**遗留待用户裁**：06 待办清单登记一条（卡片入库纪律）；`ci-removal-20261015` 分支重做（撤 ADR 两条、只保留删 .github/、rebase 现行 master）。
|
||||
|
||||
- **503（2026-10-16，贫矿脉屏蔽＋DS_DEBUG 写死批总收口）**：用户令两项一波走完（worktree `g-plan2-shielddebug-20261016`，五提交，合并 d3356985，合并后主区冒烟 1126/0 兜底）。**①贫矿脉屏蔽**：`variation.tres` 删 skewed_veins 行（用户裁「地形变异特异关卡后续重新做设计，先屏蔽」）——Boss/精英图全局池空→`_resolve_global_variant` 空行回落→region 布置原路兜底，玩家面零横幅零角标零资源偏斜；冒烟 7 处断言换代为「全局池空→region 兜底回落」路径（行数 7→6／boss 池去 global 行／L2 boss+elite 全局决议空行／格子级恰一行且在 {magma,ash}／快照空态一致／同种子确定性含 variants 字典逐位）；resource_face 机制代码（RewardEconomy 偏斜投影／schema 互锁／负样本）零触碰，重建设计直接加行即可；删行依据与首发批裁决记录改写为屏蔽注记（git 历史可溯）。**②DS_DEBUG 写死**：`main.gd:219` 环境变量读取退役、`_debug_entry` 恒 true（用户令「直接写死，不读环境变量，太麻烦」）——全库 DS_DEBUG 引用清零（含浮窗内用户可见工具提示文案）；闸断言三处换代（smoke V2f 改恒开／click_probe 原「未设时不得默认开」反转为「未恒开即失守」并挪至 boot 段、设置面关闭段补 ModalStack 遮挡恢复断言／tune_probe 删自设环境变量死代码）；**发布前删除事项＝main.gd:219 一行**（无 CI，两道恒开断言会红兜底）。**闸面三修**（首跑抓出）：冒烟跨块引用 bb/crng 出作用域 Parse Error（hoist 为 boss1_ids/variants/calls）；shot_probe 截图前走 `_close_modal` 真实单口归一浮窗（写死后 boot 即开压菜单——boot 顶层检查／golden 19%／文字占比 0.00% 三处受扰；视觉契约与调试模式解耦，发布前删写死时基线不受影响）；click_probe 恒开断言归位。**基线 09 指纹刷新**：静态扫描红项清单与基线不符，经主区与分支 `audit_file_headers` 输出逐行一致（128 行）证明非本批引入（漂移源于 20f4a7dc 之后主区 .gd 头注变动），按「人工确认后重生成」条款对齐指纹，红项仍为存量 127 处。**验收**：全量闸通过（存量红零新增，回执 commit＝HEAD）；worktree 与分支已清理。**读数义务归 M4**：Boss 图资源面分布与 region 布置读数（本批 MC 零跑，内容回落既有 region 行为）。**反哺点待裁**：设计语义面五处描述已撤回功能（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注）；机械面四件已随批同步（07 ⑪ 转记失效／architecture 行数 7→6／数据配置清单／06 战斗节点地图类型差异化条）。
|
||||
- **504（2026-10-16，需求卡片升 v2.0——三轮复查结论落文，U0 门只欠发令）**：grilling 两轮＋一轮只读深挖后一次性升版（用户令「实现相关的都可以用你推荐的，但重新检查一遍」）。**首轮十一问按推荐全裁**：L2 承载+2 例（Core-Core／A1×A2 随属主批增量）／parity 收编为**条件闸件**（仅 diff 触 data-tables/meta-save/rng/settlement 跑，否则 SKIP，守住「MC 无数值改动零跑」红线）／CI timeout 前提已死、改铸为轻闸墙钟预算（T0-② 实测，超用户上限才议分层或并发）／integration 并入 run_all manifest／S9 存量豁免维持、本批新写测试件全类型标注（升 🔴 契约 8）／golden 失效显式重制+呈报+复闸／smoke 两名不改名只加注。**第二轮两项亦按甲**：N1＝§2 改指针（事实面归 architecture.md「测试与质量域」三张表，禁双载体漂移——ADR 教训同款防复发）；N2＝T6 收 S3 路径修正（core→game/core＋零命中自检，+0.25d）。**事实订正四处**：PASS 串判定面实为 8 件探针（非 4）／game/smoke 实为 29 个 .gd（非 38）／T5 的 status_container 不是零覆盖（2 单测已指名）→ 换 board_generator／README「ci-removal 批已改写门禁节」前提不成立（分支未合入）→ CI 残留 8 处（README 6＋run_all.gd 头注 2）改由本批 T2 清除。**死引用订正**：CLAUDE.md:21/:106/:116 与 §0 的 :102-103（文件已压到 71 行）、tests.yml（已删）、golden_compare.py:11（实际 :13）。**新增义务**：本批落地后须回写 architecture.md 的「三条判定硬闸现行状态」矩阵（缺失→在位）与 S 表。估时 T0–T8≈6.0–7.5d（+0.5d），软盒 7d 维持。**U0 现状：零待裁点＋v2.0 成立，仅欠 `/iter` 发令**；唯一待补输入＝轻闸墙钟上限（T0-② 前给即可）。文档三闸全绿。
|
||||
|
||||
- **505（2026-10-16，调试入口修正批——503「写死」的用户实测否决与纠偏）**：用户 F5 实测 503 交付态：**浮窗 boot 自动开把开始屏盖成调试面板**（640×约700 居中面板盖掉大半个屏，用户体感「直接进到了调试面板，退出之后才回到开始面板」），且**菜单层没有任何浮窗入口**——iter18 卡⑦ P2 甲把右下角「调试」角标迁去两屏的理由正是「DS_DEBUG=1 启动即开」，该理由随写死后依然成立但用户根本不接受这个形态（从没带过环境变量、首次见）。用户令查三问（入口在哪/何时触发/触发后效果）后定性：我的「完成逻辑」把「写死」做成了「原样继承启动即开」，而用户要的是「调试常驻可用」——入口可见、按需开。修正（worktree `g-plan2-dbgentry-20261016`，合并 752c9a0a，主区冒烟 1127/0 兜底）：①`main.gd` `_ready` 删 boot 自动开浮窗（`_debug_entry` 门控保留）②恢复开始屏右下角「调试」角标——实现自 git 历史 `40fb4a5c^` 原样恢复（PRESET_BOTTOM_RIGHT 16px 角距＋FS_HINT＋豁免宽度基准），`ui_assembler` 返回键补 `dbgbtn`、`scenes/menu_screen.gd` 暴露句柄、接线 `pressed→_on_debug_badge_pressed`③浮窗 desc 文案改三处入口说明。**探针/断言四处换代**：smoke V2f 改「boot 不开浮窗＋菜单角标可见」、V1a 收回严格判据；click_probe boot 检查反转＋角标检查翻转为缺失才红＋删浮窗恢复断言；tune_probe ① 改角标真实点击开窗路径；shot_probe 删浮窗归一段（死代码）。**首轮冒烟抓两处自伤并修复**（教训在册）：①返回键漏 `dbgbtn`→`menu_screen` 句柄 null→`_build_ui` 中断→V1c 层序红（_layer_node 缺失三层）——装配器加返回键必须同批查 `menu_screen.gd` 句柄赋值；②角标 `visible` 赋值在 `_build_ui`（读到 `_debug_entry` 初始 false）而门控落定在其后——**门控变量赋值晚于消费点的顺序坑**，挪到 `_ready` 门控行之后。**发布前删除事项更新**：删 `main.gd:219` 一行时，角标可见性（同函数下一行）随门控失效自动隐藏，无第二删除点。
|
||||
- **502（2026-10-16，迭代 29 编入批——roadmap 门牌登记）**：用户令「把需求卡片写进 roadmap 的迭代 29」——此前需求卡片只存在于中间文档，roadmap 仍写「下一前沿=迭代 29+ M4 数值批」，致别的会话启动迭代 29 时跑去做 M4（该卡同日已被用户删除＝死引用）。本批三改：①roadmap 迭代 29 行改写为「测试分层与门禁语义修正批」（需求卡片=`design/research/需求卡片-测试分层与门禁语义修正批-2026-10-15.md`，v1.4，T0–T8≈5.5–7d，开工门 U0＝Q3–Q7 裁点＋卡片 v2.0 重核＋`/iter` 发令），新增「迭代 30+ 位空」行记录 M4 废除（禁止再以该名义立批/规划/引用已删卡；四项欠账归 06 在册待裁），迭代 23+ 原始泊位行加作废注仅作排期史保留；②需求卡片升 v1.5（排期行与 §5 同步行更新；登记 v2.0 重核遗留＝残留 CI 措辞四处＋事实基线换代〔冒烟 1086→1125/0、门禁五闸→run_all_gates.sh 编排、architecture.md 测试域节已成文、Q3 的 CI timeout 前提消失〕；订正 v1.3 版本条目尾部重复段）；③本文件快照与未决面三行同步换代。文档三闸全绿（gdd_lint 0 不通过／死链 0／疑似现行 0）。提交 21c83f5。**遗留待用户裁**：06 待办清单登记一条（卡片入库纪律）；`ci-removal-20261015` 分支重做（撤 ADR 两条、只保留删 .github/、rebase 现行 master）。（2026-10-17 核：该分支已按现状合并、重做令失效；「06 登记一条」至今在 06 清单内查无，已改记在未决面的待登记项。）
|
||||
|
||||
- **503（2026-10-16，贫矿脉屏蔽＋DS_DEBUG 写死批总收口）**：用户令两项一波走完（worktree `g-plan2-shielddebug-20261016`，五提交，合并 d3356985，合并后主区冒烟 1126/0 兜底）。**①贫矿脉屏蔽**：`variation.tres` 删 skewed_veins 行（用户裁「地形变异特异关卡后续重新做设计，先屏蔽」）——Boss/精英图全局池空→`_resolve_global_variant` 空行回落→region 布置原路兜底，玩家面零横幅零角标零资源偏斜；冒烟 7 处断言换代为「全局池空→region 兜底回落」路径（行数 7→6／boss 池去 global 行／L2 boss+elite 全局决议空行／格子级恰一行且在 {magma,ash}／快照空态一致／同种子确定性含 variants 字典逐位）；resource_face 机制代码（RewardEconomy 偏斜投影／schema 互锁／负样本）零触碰，重建设计直接加行即可；删行依据与首发批裁决记录改写为屏蔽注记（git 历史可溯）。**②DS_DEBUG 写死**：`main.gd:219` 环境变量读取退役、`_debug_entry` 恒 true（用户令「直接写死，不读环境变量，太麻烦」）——全库 DS_DEBUG 引用清零（含浮窗内用户可见工具提示文案）；闸断言三处换代（smoke V2f 改恒开／click_probe 原「未设时不得默认开」反转为「未恒开即失守」并挪至 boot 段、设置面关闭段补 ModalStack 遮挡恢复断言／tune_probe 删自设环境变量死代码）；**发布前删除事项＝main.gd:219 一行**（无 CI，两道恒开断言会红兜底；该行现行位置与行号见 507 条＝`game/presentation/main.gd:196`）。**闸面三修**（首跑抓出）：冒烟跨块引用 bb/crng 出作用域 Parse Error（hoist 为 boss1_ids/variants/calls）；shot_probe 截图前走 `_close_modal` 真实单口归一浮窗（写死后 boot 即开压菜单——boot 顶层检查／golden 19%／文字占比 0.00% 三处受扰；视觉契约与调试模式解耦，发布前删写死时基线不受影响）；click_probe 恒开断言归位。**基线 09 指纹刷新**：静态扫描红项清单与基线不符，经主区与分支 `audit_file_headers` 输出逐行一致（128 行）证明非本批引入（漂移源于 20f4a7dc 之后主区 .gd 头注变动），按「人工确认后重生成」条款对齐指纹，红项仍为存量 127 处。**验收**：全量闸通过（存量红零新增，回执 commit＝HEAD）；worktree 与分支已清理。**读数义务归 M4**：Boss 图资源面分布与 region 布置读数（本批 MC 零跑，内容回落既有 region 行为）。**反哺点待裁**：设计语义面五处描述已撤回功能（地形变异.md §全局作用域型／HUD 框架三层预告／教学引导手册行／难度曲线与Boss 两行／art-bible §4.6.3 括注）；机械面四件已随批同步（07 ⑪ 转记失效／architecture 行数 7→6／数据配置清单／06 战斗节点地图类型差异化条）。
|
||||
- **506（2026-10-16，迭代 29 测试分层与门禁语义修正批总收口）**：用户 `/iter 29` 发令，单会话八提交交付（worktree `g-plan2-iter29-testlayers`，分支 `iter29-testlayers-20261016`）。**核心是把验收语义从「跑一遍没崩＝通过」扭到「三层完备＋判定可靠」**，三硬闸每条都有反例实证：改前「探针打印 PASS 后 quit(1)」判全绿、「零断言套件」判 all green (0 checks)、「子套件中途报 SCRIPT ERROR」判 PASS；改后三条全部见红。**本机两个坑写进注释防复发**：①`OS.execute` 的输出管道恒空（子套件输出须交命令解释器重定向落盘再读）；②`OS.get_executable_path()` 返回 GUI 子系统 exe，其子进程 stdout/stderr 句柄无效，必须换 `*_console.exe`。断言下限用专用退出码 2（不是 1——致命类套件期望 1，返回 1 会被 expect 协议放过）。**三层承载**：L1 补六套（board_generator／minesweeper_rules／config_db_resolver／config_db_cross_validator／hud_presenter／battle_narrator，27→33 套），三屏壳归 L3 探针；L2 建 `tests/integration/` 首个用例（存档⇄RNG 往返，含旧档经迁移链后仍可续玩这条真实路径）；L3 新建 `screen_flow_probe`（六步主流程＋两条回退，每步判屏级互斥）入轻闸。**parity 收编为重闸 11 号条件闸件**（每次跑批做触面判定，触面也不自动跑——MC 须用户批准），本批即判触面，挂 NEED-APPROVAL 待裁。**扫描域**：S3 路径由裸 `core` 修正为 `game/core`（此前恒零命中恒绿、什么都不扫），补 S5，并给每条规则加零命中自检（扫描面为空即判红，路径写歪时自检跟着一起红）。**四处经用户裁决的改动**：fx_grant_gp 补行来源豁免（每局 7 次断言失败被闸长期漏过）／manifest 增 negative 字段（负面套件的错误是测试目标）／config_db_test 的 rows 定型数组赋值改 assign（**10 条敌人表行集纪律断言从未执行过**，修后两条正向见红＝夹具缺 depth-0 锚行，补锚行全绿）／system_contracts 空桩换真实实例。**台账与时效**：15 个游离脚本逐个定性成表（存疑按在役）；golden 先判再动，实测 changed 0.00%／0.15% 判有效不重制。**架构事实源回写**：三硬闸矩阵「缺失」→「在位」、S 表 S3/S5 更新、新增「三层承载与判定原则」小节。**验收**：重闸 exit=0（存量红零新增，回执 commit＝HEAD），冒烟 1127/0 持平，轻闸墙钟 363→405s。**遗留待裁**：11 号闸 parity 是否批准发起、GDD 反哺三条、06 在册七项。
|
||||
|
||||
- **507（2026-10-16，调试入口全局浮层角标批——屏内三枚角标合并为最顶层浮层）**：用户看完上一批（屏内角标形态）交付态后定稿：不做置顶钮式按需出现，要「**UI 最顶层浮层、不被任何 UI 遮挡**」（调研 Material FAB 与 NN/g 置顶钮规范后用户给出的修正——位置惯例一致但浮层语义不同）。实现（worktree `g-plan2-dbgfloat-20261016`，两提交，合并 746c1bb4，主区冒烟 1127/0 兜底）：**三枚屏内角标（菜单右下/战斗 HUD 右下/地图顶栏）合并为一枚全局浮层角标**——LAYER_CONTRACT 末位新增 `{"key":"debug_badge","kind":"float"}`（只落树序＝最顶绘制序、**不注册 ModalStack**：`open()` 遮挡记账只隐藏登记层，故任何模态/覆盖层开都不遮它＝用户需求的机制根因）；main 直接子层，构建走 `ui_assembler.build_debug_badge`（右下角 16px＋FS_HINT＋豁免宽度基准＋grow BEGIN）；地图屏底栏 85px 常驻→`_sync_status_entry` 按 `map_on` 抬 `offset_bottom` 至底栏上方 16px；战斗屏状态角标经 MarginContainer 让位（right 16/bottom 52）不再被压；屏内三处 `debug_badge` 全删（menu_screen/board_zone_view/level_map_screen），main 两处接线与 sync 四条可见性/置灰行清除（浮层常显不置灰）。**断言换代**：smoke V2f 查 `main.debug_badge` boot 可见；click_probe 遮挡判据移至**设置面开中段**（浮层角标此时仍应可见＝直接验「不遮挡」）；tune_probe ①点击路径与⑨对局中角标全改 `main.debug_badge`（T2 防线三断言不动——non_locking×遮挡复活×has_open 组合回归）。**过程两处**：①一处替换误写成重复状态角标接线（指向不存在方法）——提交前 grep 自纠；②基线 06 刷新：`01-核心循环.md` 表格占比 43% 越线为今日 9846a29f（删副标题行）引入的存量，主区实测同红、本批零 design/ 改动，按人工确认条款对齐指纹（该条红灯与 R5 缺流程图均已由提交 `fcb8c3f8`＋`8c18b52b` 结案，基线 06 已改回绿）；09 静态扫描本批转绿（并行会话 R0 文件头锁批清偿 127 处存量）。**发布前删除事项**：`game/presentation/main.gd:196` 一行（2026-10-17 核实行号，原记 `main.gd:219` 已漂移）——删该行后角标可见性（同函数下一行 `:197`）随门控失效自动隐藏，无第二删除点。
|
||||
- **508（2026-10-17，代拍板追认单落状态批）**：用户令「追认单的所有我都是同意的」——迭代 27 十五项／28 十三项（含四条白名单外）／29 十二项共 40 项代拍板全部同意，三份实现报告的追认单节各加一行追认结果。两处保留：①iter28 第 14 项只认「本批动作」（只补 ZCode 副本、未擅自取齐），「req-card 两副本是否取齐」仍是待裁问题，留在未决面；②iter29 第四节「经你裁决的四项」当时已问过已答，不属追认范围，原文不动。连带改 06「闸按改动域分跑批的两处代拍板」条①②为已追认，③迁位欠账补计 `iter29-实现报告`（该条登记时只列两份，漏计第三份）。roadmap 迭代进度行三处「代拍板追认单…待用户」换代为已追认。worktree `g-plan2-ratify-20261017`，文档域闸 `--docs` 零新增红（回执 commit=9a7dfcf6），合并 `eabaeee0`。**本文件三行改动（待追认行／在途分支行／本条）留在主区工作副本未提交**——主区另有并行会话的未提交件（`game/project.godot`／M4 卡片删除／五份未跟踪文档），按「只合本批自有改动」令不代为提交，等下一次动 active.md 的批一起入库。GDD 反哺点八条（27 两条／28 三条／29 三条）未随本批处理，属设计权威文档改动、需逐点裁决另批写入。
|
||||
|
||||
- **509（2026-10-17，GDD 反哺点写入批——迭代 27/28/29 八条＋一条建议逐点裁决）**：用户裁「全部按推荐案执行」（文档批，不占迭代号，worktree `g-plan2-gddfb-20261017`）。写入面：①**architecture.md v1.7→v1.8**——新增「战斗域装配现状」（结算五段 授予→增益/减益→战斗→衰减→判定，段序骨架冻结于 `SettlementTable.segment_order`；RunLedger 单类四账所有权 AdventureRunner 独占）与「呈现层装配与会话生命周期」（三屏壳+组合根句柄面／视觉层装配合同立条款、合同表不摘录——唯一事实源=`main.gd` `LAYER_CONTRACT` 现行 17 项五类 kind，登记时 16 层按代码实态订正／RunScope `_begin_session` 换会话整节点释放、无独立收束函数／九阶段×五引用面存活性矩阵认账入册／ModalFlow 互斥域 tags）两节；「初始化顺序」补启动后置条件六条（登记时「十断言」现为六组 11 条——2026-10-16 角标令 V2f 拆两条）；呈现层 D1 行与实现实证读数换代。②**code-conventions.md §4 第 7–12 条**——S9 类型闸三规则与扫描面口径／`:= {}` 推断形态不算债／`# type-hint: ignore` 行级白名单／`# rng-seed-exempt` 豁免通道／--script 模式禁裸 autoload 标识符／Variant 参数化现行口径（元素精化不入硬纪律）。③④⑨**test-conventions.md 新增 §7 判定三硬闸**（闸承载三闸齐备义务＋负面套件仅豁免错误扫描一闸＋新写测试件全类型标注写法纪律，暂不机器闸——S9 扫描面产品码）与 **§8 判定可靠性优先于覆盖率**（§六第 4 项建议随此反映：脚本错误静默中断所在函数剩余断言的机制事实＋三处实证＋写验收函数自证断言全数执行义务；覆盖率度量是否引入仍 06 在册待裁）。⑤**07 v1.4**——㉖① 全流程走查保留不注销，节首加 `screen_flow_probe` 机检承接注记。三笔旧账清零：iter27/28/29 三份实现报告 `git mv` 往 `reports/`（06 条③迁位账清零，全库引用改指新路径、死链复验零死链；roadmap 九处 iter21–26 已删报告死指针改「已退役（git 历史可考）」、iter27/28/29 改指新位）；iter29 报告 §六第 0 项按合并现实改写（`fff4f120` 已合回，两红各自结案：菜单 golden 重采 `dac9a94b`、01 篇 R5 流程图 `fcb8c3f8`＋`8c18b52b`）；06 补登迭代 29 反哺专条（该批漏登）且 27/28 反哺条按「吸收即死」退役为已写入。06 :687 死引用「code-conventions.md §3.6」顺带订正（该内容现独立成文于 test-conventions.md §6）。本批并把 508 批自述「等下一次动 active.md 的批一起入库」的主区未提交行改动随本批提交入库；主区其他并行未提交件（`game/project.godot`／M4 卡片删除／五份未跟踪文档／`layout_probe.gd.uid`）仍零触碰。文档域 --docs 零新增红（回执 commit=分支尖，见合并说明）。
|
||||
@@ -2,13 +2,13 @@
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 版本：1.7
|
||||
- 最近更新：2026-10-16（④架构原则层名中文化补漏——原则 1 残留 Core/Feature 英文层名改中文；⑤模块归属命名规约描述同步 code-conventions 文件头新规——头注禁写文档链接，「实现 GDD：xxx」一类已废止）
|
||||
- 版本：1.8
|
||||
- 最近更新：2026-10-17（迭代 27/28 GDD 反哺点写入——新增「呈现层装配与会话生命周期」节（视觉层装配合同/三屏壳/RunScope 生命周期与存活性矩阵/ModalFlow tags 协议）、战斗域现状补结算五段与 RunLedger 四账、初始化顺序补启动后置条件六条，均 2026-10-17 用户裁按推荐案写入；实现实证行读数换代）
|
||||
- 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||||
- 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调）
|
||||
- 覆盖 GDD：现行全集——`design/gdd/` 顶层 00–08 共 9 件 + `systems/` 五域 25 件（排雷循环 4 / 战斗循环 5 / 冒险循环 5 / 跨局循环 5 / 表现与支撑 6）+ `ux/` 8 件；原英文命名 12 份系统 GDD 已全部迁入中文域目录，原「未设计」预留（A5 扫雷秘宝 / C1–C4 / B5 / D3–D6）均已立项成文
|
||||
- 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 28 已入库合并——冒烟 1125/0、单元 27 套件、本地五闸在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；迭代 29 已入库合并——冒烟 1127/0、单元 33 套（含 1 集成）、重闸按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计
|
||||
- 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债）
|
||||
- 主程序可行性：跳过 — solo 模式
|
||||
|
||||
@@ -119,11 +119,16 @@
|
||||
| **difficulty**（C3） | DifficultyTable 回填、全部曲线数值调参所有权、战斗期望表（切片 monte_carlo 为工具原型） | 调参输出（经 D2 R1 解析/编排器传递，禁反向调用生成） | ConfigDB、B1 对账输出（调参约束清单）、A1 报告 C | 无 |
|
||||
| **meta_progression**（C4，Alpha） | MetaTable、钥石账本、天赋树域（MetaTreeTable 12 节点 v0.8——Fork 一节点双态/row 字段退役/RULE_KEYS 六键/彩蛋特化觉醒，迭代 21 T1 换代）+ 同调位槽位判定（树点亮数单源——T4 槽位收编） | tree_can_buy/tree_buy/tree_buy_fork/tree_toggle_fork（写口唯一）、hero_override 注入（树淬炼 flat+锻造路线加值位预留 0）、tree_rule_keys | D3、C2、ConfigDB | 无 |
|
||||
|
||||
### 战斗域装配现状（迭代 27——2026-10-17 用户裁写入）
|
||||
|
||||
- **结算五段**：B1 编排器的每轮结算序列拆为 `game/core/settlement/` 五个段类——GrantSegment（①授予段，含旗判与 counter/grant 助手单点）→ AuraSegment（②增益/减益段）→ CombatSegment（③战斗段）→ DecaySegment（④衰减段）→ VerdictSegment（⑤判定段，返回裁定，终局早退语义留 B1）。段序骨架冻结于 `SettlementTable.segment_order` 语义，B1 退为段序编排+接线；段类可直接 `new()` 单测（`settle_segments_test` 在役）。
|
||||
- **RunLedger 四账**：`game/core/run_ledger.gd` 单类持四本共享账——同调充能账／真视使用计数／冒险域计数器／统一冒险加算区。所有权：AdventureRunner 开局构造、全程唯一宿主；LevelRunner 经 `set_run_ledger` 下传装配 encounter；战斗侧（B1）经 `encounter["ledger"]` 拿引用、只走 read/append 原语族。审计 P1-4「共享可变字典跨三层三处可写」由「函数签名上不可见的共享引用」换成签名可见的显式类，时点语义（战末导出/开局回灌）逐字不变。
|
||||
|
||||
### 呈现层
|
||||
|
||||
| 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API |
|
||||
|---|---|---|---|---|
|
||||
| **D1 HUD**（切片 lite 已拆 9 单元：BoardView / HUDView / HudPresenter / BattleLogView / ItemWindowOverlay / NodeOverlay / LevelStripView / TunePanel / UiKit + 组合根 main.gd；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26）、输入→意图翻译（**唯一提交路径 = settle_batch，不直调 A3**）、呈现义务状态记录（A2×6 / B2×4 / B3×4 / B4×5 / B1×3） | 视图单元接口（信号外发、setter 只读注入） | A2 compute_move_path / ActionOutcome；A3 ap/rap；B1 步骤流行协议（数据源）；ConfigDB display_name | **MEDIUM**：Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目（CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化） |
|
||||
| **D1 HUD**（呈现面拆分持续换代：组合根 main.gd + 三屏壳（MenuScreen/CampScreen/AdventureScreen）+ views/ 视图单元（现行承载面见「呈现层装配与会话生命周期」节；早期 9 单元清单与 LevelStripView 已随场景换代退役）；营地覆盖层=四柜台并排〔树淬炼主界面/锻造工坊·秘宝匣钥匙门/图鉴常开——迭代 21 T6 程序占位重排〕） | 全部 Control/CanvasLayer（例外：BoardView 棋盘本体与 BattleStageView 站桩本体 = Control 壳 + SubViewportContainer + SubViewport + Node2D 世界〔BoardWorld/CellUnit；StageWorld/StandeeBody——B 区 slot_row 伴随件留壳层〕，探针契约面不变——棋盘 Node2D 迁移批 Phase A 2026-09-23 / 战斗舞台 Phase B 2026-09-26）、输入→意图翻译（**唯一提交路径 = settle_batch，不直调 A3**）、呈现义务状态记录（A2×6 / B2×4 / B3×4 / B4×5 / B1×3） | 视图单元接口（信号外发、setter 只读注入） | A2 compute_move_path / ActionOutcome；A3 ap/rap；B1 步骤流行协议（数据源）；ConfigDB display_name | **MEDIUM**：Control / CanvasLayer / draw_* / InputEvent / RichTextLabel——对照 breaking-changes.md 4.5–4.7 条目（CanvasItem 线条无抗锯齿羽化、设备 ID 常量、RichTextLabel 图片参数两轮变化） |
|
||||
| **battle_presentation**（B5，垂直切片后） | 结算动画 / 伤害数字 / 战斗舞台 | （契约规范源：`../../gdd/systems/战斗循环/战斗表现.md`——前置「战斗表现美术测试」锁双舞台陷阱） | B1 步骤流（回放脚本源）、D1 | **MEDIUM**：AnimationPlayer（String→StringName 变更）/ Tween |
|
||||
| **audio**（D4，Alpha） | 音频挂点 | （挂点 = B1 明细行类型流；负反馈聚合——单结算至多一次） | B1 流水 | AudioStreamPlayer（4.7 area_mask 默认 1→0 注意） |
|
||||
| **tutorial**（D5，Alpha） | 教学条目 | （口径来源：A2/A3/B3/B1 各教学条目） | 各上游 | 无 |
|
||||
@@ -132,6 +137,46 @@
|
||||
|
||||
---
|
||||
|
||||
## 呈现层装配与会话生命周期（迭代 27/28 完成反哺——2026-10-17 用户裁按推荐案写入）
|
||||
|
||||
### 三屏壳与组合根句柄面
|
||||
|
||||
- 呈现场景拆为三屏壳：MenuScreen（开始菜单屏）／CampScreen（营地屏）／AdventureScreen（冒险屏——内含关卡地图与战斗两容器）。
|
||||
- 屏成员经组合根 main.gd 一级句柄暴露（探针挂载假设 `main.X` 路径零迁移）；局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。
|
||||
|
||||
### 视觉层装配合同
|
||||
|
||||
- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（现行 17 项，kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。
|
||||
- 全仓唯一落位口 = `_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟 V1d 源码断言判红；**改层序只改合同表**。
|
||||
- 具体层清单不复制进本文（双写失同步禁令）——查现行 17 项直接读 `main.gd`。
|
||||
|
||||
### 会话生命周期（RunScope）
|
||||
|
||||
- `run_scope.gd` = 纯状态承载 Node：零信号连接、零视图构建、零核心写调用（连接只在组合根，组合根经 `run_scope.X` 读写）。
|
||||
- 会话更替机制：`_begin_session()` 新建会话节点挂树、旧会话节点**整节点 `queue_free()`**——无独立收束函数，跨局字段清理靠节点释放机制（原手工复位清单随其消亡，新增跨局字段零新增泄漏点）；`_ready` 即建闲时会话，`run_scope` 永非 null。
|
||||
- **存活性矩阵**（九阶段 × 五引用面，2026-10-17 用户裁认账阶段划分；执行判据=冒烟 V3a–V3i。计划书原十阶段中「开局停点」与「地图选路」在现行流程同为关卡画面停点态、无可观测中间态，合并为一处断言）：
|
||||
|
||||
| 阶段 | run_scope | adventure | runner | settlement |
|
||||
|---|---|---|---|---|
|
||||
| ① 闲时 | 在树（闲时会话） | null | null | null |
|
||||
| ② 开局停点 | 在树 | alive | alive | null |
|
||||
| ③ 战斗中 | 在树 | alive | alive | alive |
|
||||
| ④ 结算后（胜利停点）／⑤ 选路页 | 在树 | alive | alive | both |
|
||||
| ⑥ 终局面 | 在树 | alive | alive | null |
|
||||
| ⑦ 回菜单收束 | 新闲时会话即刻在树（旧会话已释放——无真空窗） | null | null | null |
|
||||
| ⑧ 各模态开合后（设置/生涯/营地/调试） | 闲时会话零扰动 | null | null | null |
|
||||
| ⑨ 两连局+续玩断点 | 换全新会话在树 | alive | both | both |
|
||||
|
||||
- 三态记号沿用冒烟参数：**alive**=应有实例、**null**=必须缺位（实测非空判红）、**both**=按分支可空可活（如胜停点后走向选路或直接终局）。对象有值但已失效一律判「悬挂」红。
|
||||
- 第五引用面=四持句柄件（`_treasure_ui`／`_bonus`／`_camp_pres`／`_modal_flow`，另有 `_row_pacer`）：其会话取值 Callable 与 `run_scope` 成员**逐面同源比对**（回调悬挂=两值不等即红），会话更替零残留由矩阵每阶段顺带铁证。
|
||||
|
||||
### 模态编排（ModalFlow/ModalStack）
|
||||
|
||||
- `modal_flow.gd` = 模态编排纯逻辑类（依赖仅 ModalStack + 查询 Callable，可直接 `new()` 单测）：开合编排（遮挡记账单口 + T17 演播后排窗挂起）／棋盘输入锁谓词／角标置灰谓词三职责。
|
||||
- 互斥排除语义随层登记（`register(node, tags)`）：`debug_overlay=["non_locking"]`、`level_screen=["screen_state"]`，其余层零标签——原调用点排除式条件拼装已消亡。
|
||||
|
||||
---
|
||||
|
||||
## 测试与质量域
|
||||
|
||||
> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。
|
||||
@@ -259,6 +304,15 @@ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB
|
||||
→ 关卡末：通关结算（钥石/GP/专长 level_clear 渠道——现行语义归 冒险结构 GDD；原 clear_inventory 随库存轴下线退役 2026-09-15）
|
||||
```
|
||||
|
||||
**启动后置条件**（2026-10-17 用户裁入册——迭代 28 以冒烟 V2a–V2f 共 11 条断言把「启动完成后玩家该看到什么」成文；执行判据事实源在 `game/smoke/smoke_all.gd`）：
|
||||
|
||||
1. ConfigDB 就绪且表已载（`is_ready` + hero 表在座）。
|
||||
2. 系统设置已落引擎态——Master 音量 mute/volume_db = settings_store 现值；减动效开关 = `UiKit.motion_scale`。
|
||||
3. 启动态菜单可见（boot 后自树顶向下第一个可见内容层 = 开始层——菜单被冒险屏盖住即红）。
|
||||
4. 续玩钮可见态恒等于断点在档态（双向：无断点隐藏/有断点可见/清断点回隐；boot 路径与刷新单口同源）。
|
||||
5. 闲时会话已在树（`run_scope` 非空、非冒险会话、在树——永非 null 契约的启动侧证明）。
|
||||
6. 调试浮窗 boot 不自动开（菜单优先，2026-10-16 用户令）+ 调试入口全局浮层角标 boot 可见。
|
||||
|
||||
---
|
||||
|
||||
## API 边界
|
||||
|
||||
@@ -68,6 +68,12 @@
|
||||
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。
|
||||
5. **重命名脚本必须同步 `.uid` 文件**；新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存，否则 `--headless --script` 模式解析失败。
|
||||
6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**（迭代 27——2026-10-17 用户裁写入）——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码（`game/core`+`game/data`+`game/presentation`；smoke/tests 豁免——测量面容器直构是既有惯例）。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
8. **`:= {}` 推断形态不算债**——`var x := {}` 类赋值推断属类型推断合法面，不入 R1 扫描；只有显式写的非参数化容器注解才算无类型容器。
|
||||
9. **行级白名单通道 `# type-hint: ignore`**——豁免该行不入 S9；豁免理由必须随行注明（现行例：`board_generator` 四函数的 db 参鸭子型——typed 参拒冒烟夹具 `_BoardRowStub` 注入）。
|
||||
10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）。
|
||||
11. **`--script` 模式禁裸 autoload 标识符**——`ConfigDB`/`RngService` 等 autoload 名在 `--headless --script` 模式编译器不解析（parse error）；产品码与测试夹具一律经节点路径取用（`get_node("/root/…")`／`AUTOLOAD_PATH_*` 常量）；静态扫描域 S5 硬失败承载在位。
|
||||
12. **Variant 参数化现行口径**——账本类字典/数组标注 `Dictionary[Variant, Variant]`/`Array[Variant]` 即合格（满足 R1）；元素类型精化列后续事项、不入硬纪律，口径变更须用户裁决后续批次另行写入。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -65,3 +65,22 @@
|
||||
- **如实标注拦截边界**——判据本身只覆盖弱面的（如「只证伪整框空白／整框糊，不证明框里是何内容」），在断言注释与报告里写明边界，并说明强判据由哪一件承担。
|
||||
|
||||
**判据强弱分层**：同一缺陷面往往需要多件配合——**可见性／状态源类**缺陷由 `is_visible_in_tree`、树序、状态源取值的**运行期断言**抓；**内容／观感类**缺陷由 **golden 逐像素比对**抓；**占比／统计类**判据（墨色占比、纹理幅度）只能兜「整框空白／整框糊／压 busy 纹理」，是补充不是主力。写卡时按此分层配齐，别指望一条断言包打。
|
||||
|
||||
## 7. 判定三硬闸——闸承载的构造义务（迭代 29 三硬闸 2026-10-17 用户裁升格为纪律）
|
||||
|
||||
任何**新增或改写的闸承载**（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归架构文档「测试与质量域」节（本文不另列闸件清单）：
|
||||
|
||||
1. **退出码为唯一权威判据**——输出里的 PASS 串只作附加判据不作判据主体；打印 PASS 后 `quit(1)` 必须判红。
|
||||
2. **SCRIPT ERROR / Parse Error 扫描面在位**——GDScript 脚本错误不改进程退出码、不计失败数（机制事实见 §8），错误标记必须扫输出，且判据必须覆盖「跑了但半途脚本错误」态——退出码 0 但输出缺预期签名同样判红（防静默退出）。
|
||||
3. **断言数下限**——零断言的正常返回与断言失败必须区分开（现行做法：`Kit.finish` 零断言返回专用退出码 2，不与「断言失败=1」混用，否则致命类套件的期望码协议会放过空跑）。
|
||||
- 负面套件（测试目标就是产生错误输出）仅可豁免第 2 闸，且须在 manifest 显式标记，其余两闸照判。
|
||||
- 子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空。
|
||||
|
||||
**新写测试件全类型标注**（2026-10-17 用户裁写法纪律）——新写的测试件（冒烟断言／探针／单测）参数、返回值、容器一律带类型标注，与 S9 对产品码的要求同型；存量不强制清扫，被批次触碰时顺带换代。暂不机器闸（S9 扫描面=产品码，smoke/tests 豁免是测量面直构惯例的既有裁量）。
|
||||
|
||||
## 8. 判定可靠性优先于覆盖率（迭代 29 核心命题 2026-10-17 用户裁成节）
|
||||
|
||||
- 「跑一遍没崩＝通过」无效：测试绿只证明**当前代码没犯这个错**，不证明**犯了这个错会被抓住**；断言存在不等于断言执行。
|
||||
- **脚本错误会静默中断所在函数的剩余断言，而套件仍报全绿**（机制事实）：GDScript 无脚本错误陷阱 API，错误不改进程退出码、不计失败数。三处实证：①2026-09-19「309 项 0 失败」实为断言未跑全（状态记录 83）；②敌人表行集纪律 10 条断言因定型数组赋值错误从未执行（迭代 29 修复后两条正向见红＝夹具本缺锚行）；③`Callable` 形参类型写错致解析函数返回 null、后续断言整段蒸发。
|
||||
- 由此产生两条义务：**写闸件**按 §7 配三硬闸；**写验收函数**必须自证断言全数执行——变异验证（§6）为主证，反例实证（构造缺陷态改前判绿／改后判红）与零命中自检（扫描面为空即判红）为辅证。
|
||||
- **覆盖率不是目标**：行覆盖率度量缺失（Godot 无内建，第三方属新基建，是否引入 06 在册待裁）；现行补洞=零指名单测清单+人工判定，判定可靠性靠上列自证手段，不靠覆盖率数字。
|
||||
+27
-10
@@ -66,7 +66,7 @@
|
||||
|
||||
**指针**：`design/research/需求卡片-UI交互与观感批-2026-10-13.md`
|
||||
|
||||
**状态**：**已完成（2026-10-14，迭代 26 总完成——单会话 /goal+iter U0 全量交付）**——六项全落地（T0 基线+枚举/T1 五态/T2 Nearest+白名单/T3 换墨/T4 光柱/T5 细节/T5b 诊断钮），冒烟 987→1055/0（+68 断言）+run_all 25 套+probe click/full+render_gate golden 处置在册+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）。上方第一层第二/三条、第三层四条（<4.5:1／氛围层光柱半／元素细节余项）按卡片 §5 同步面已注销或改写；实现报告=design/qa/iter26-实现报告-2026-10-14.md；反哺点四条见下条待用户逐点裁决
|
||||
**状态**：**已完成（2026-10-14，迭代 26 总完成——单会话 /goal+iter U0 全量交付）**——六项全落地（T0 基线+枚举/T1 五态/T2 Nearest+白名单/T3 换墨/T4 光柱/T5 细节/T5b 诊断钮），冒烟 987→1055/0（+68 断言）+run_all 25 套+probe click/full+render_gate golden 处置在册+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）。上方第一层第二/三条、第三层四条（<4.5:1／氛围层光柱半／元素细节余项）按卡片 §5 同步面已注销或改写；实现报告已退役（git 历史可考）；反哺点四条见下条，已于 2026-10-14 用户裁决写入
|
||||
|
||||
#### 迭代 26 UI 交互与观感批——GDD 反哺点四条（2026-10-14 顺带登记，待用户逐点裁决另批写入文档）
|
||||
|
||||
@@ -604,11 +604,11 @@
|
||||
|
||||
#### 闸按改动域分跑批的两处代拍板 + 旧实现报告迁位欠账（2026-10-17 登记，闸分域批）
|
||||
|
||||
**现状**：用户裁定「改代码的批只跑代码闸、改文档的批只跑文档闸」与「迭代批禁写 `design/`」两条，落地时撞上一处既有规则没覆盖的缝隙，本批按推荐方案先做并登记待追认：① **active.md 记账例外**——§3.12 要求每批更新 active.md 快照与状态记录，而合回闸钩子本就对 active.md 放行（它被定为「会话状态唯一源」而非文档产出物）；本批把禁写面落在 `design/` 与根规则文件（`CLAUDE.md`/`roadmap.md`），**active.md 实现批照写**，读法若不符请推翻。② **`reports/` 新顶层目录**——熵增闸「新增顶层目录须同批改 CLAUDE.md Project Layout + 脚本白名单两处」，本批已同批改齐（`repo_structure_audit.py` TOP_DIRS + CLAUDE.md 第 36 行 + `reports/README.md` 立目）。③ **旧实现报告未迁位**——`design/qa/iter27-实现报告-2026-10-14.md`、`iter28-实现报告-2026-10-15.md` 两份现行报告仍在 `design/qa/`，且 active.md 第 32 行待追认指针指向该路径；新口径要求实现批产出物归 `reports/`。本批未搬（搬动会改动两份历史报告的落位与引用面，属文档动作，不属闸改造）。
|
||||
**现状**：用户裁定「改代码的批只跑代码闸、改文档的批只跑文档闸」与「迭代批禁写 `design/`」两条，落地时撞上一处既有规则没覆盖的缝隙，本批按推荐方案先做并登记待追认：① **active.md 记账例外**——§3.12 要求每批更新 active.md 快照与状态记录，而合回闸钩子本就对 active.md 放行（它被定为「会话状态唯一源」而非文档产出物）；本批把禁写面落在 `design/` 与根规则文件（`CLAUDE.md`/`roadmap.md`），**active.md 实现批照写**，读法若不符请推翻。② **`reports/` 新顶层目录**——熵增闸「新增顶层目录须同批改 CLAUDE.md Project Layout + 脚本白名单两处」，本批已同批改齐（`repo_structure_audit.py` TOP_DIRS + CLAUDE.md 第 36 行 + `reports/README.md` 立目）。③ **旧实现报告未迁位**——`reports/iter27-实现报告-2026-10-14.md`、`iter28-实现报告-2026-10-15.md` 两份现行报告仍在 `design/qa/`，且 active.md 第 32 行待追认指针指向该路径；新口径要求实现批产出物归 `reports/`。本批未搬（搬动会改动两份历史报告的落位与引用面，属文档动作，不属闸改造）。
|
||||
|
||||
**归属**：①②已追认（2026-10-17 用户令「追认单的所有我都是同意的」，本批已生效）；③归下一次文档批
|
||||
|
||||
**状态**：待办——①②已追认清零；③待迁位（现仍在 `design/qa/` 的是**三份**：iter27/iter28/iter29，本条登记时漏计 iter29；迁时同批改 active.md 待追认行指针并按死链检查复验）
|
||||
**状态**：待办——①②已追认清零；③**已清（2026-10-17 文档批：三份 iter27/28/29 实现报告已 `git mv` 往 `reports/`，全库引用同批改指新路径，死链检查复验零死链；active.md 待追认行指针就地同步）**
|
||||
|
||||
#### 文档/结构闸存量欠账（2026-10-08 迭代 19 总完成批登记）
|
||||
|
||||
@@ -663,9 +663,9 @@
|
||||
|
||||
**状态**：备忘（长函数拆分无独立需求驱动不动；lambda 连接数若有审计工具化需求归类型闸后续）
|
||||
|
||||
#### 迭代 27 代码架构技术债修复批——GDD 反哺点两条（2026-10-14 顺带登记，待用户逐点裁决另批写入文档）
|
||||
#### 迭代 27 代码架构技术债修复批——GDD 反哺点两条（2026-10-14 顺带登记；2026-10-17 用户逐点裁决，已写入）
|
||||
|
||||
**现状**：五波全量入库（单会话交付；逐位一致逐项比对三变体五跑全同；实现报告=design/qa/iter27-实现报告-2026-10-14.md）。实现与设计权威文档的差异/缺口如下，经裁决后另批写入文档——**机械面已顺带改动的只有本条与 07/roadmap**。
|
||||
**现状**：五波全量入库（单会话交付；逐位一致逐项比对三变体五跑全同；实现报告=reports/iter27-实现报告-2026-10-14.md）。实现与设计权威文档的差异/缺口如下，经裁决后另批写入文档——**机械面已顺带改动的只有本条与 07/roadmap**。
|
||||
|
||||
**归属**：工程债/重构批完成反哺（不阻塞，不排期）
|
||||
|
||||
@@ -674,7 +674,7 @@
|
||||
| 1 | design/dev/architecture/architecture.md | 场景分层（三屏壳+组合根句柄面）/会话生命周期（RunScope 物化）/结算五段 Segment（core/settlement/）/RunLedger 四账所有权/ModalFlow 模态编排层与互斥域 tags 协议——现行陈述滞后于实态 |
|
||||
| 2 | design/dev/code-conventions.md | §4 语言纪律机器化（S9+audit_type_hints.py 三规则）；`:= {}` 推断形态豁免口径；`# type-hint: ignore` 行级白名单与 `# rng-seed-exempt` S1/S2 标记豁免通道；--script 模式禁裸 autoload 标识符纪律（新）；Variant 参数化口径与元素精化后续 |
|
||||
|
||||
**状态**：备忘（反哺点待裁决；代拍板追认单十五项见实现报告 §三；残留人闸=07 ㉖ 五件登记不阻塞）
|
||||
**状态**：✅ **已写入（2026-10-17，用户逐点裁按推荐案）——①入 architecture.md v1.8：新增「战斗域装配现状」（结算五段/RunLedger 四账）与「呈现层装配与会话生命周期」（三屏壳/装配合同/RunScope 九阶段×五引用面矩阵/ModalFlow tags）两节，呈现层 D1 行同步换代；②入 code-conventions.md §4 第 7–12 条（S9 三规则/`:= {}` 不算债/两豁免通道/禁裸 autoload/Variant 口径）。登记时「16 层」为现行 17 项（2026-10-16 追加 float 类）、「无收束函数」以 `_begin_session` 换会话实态为准。代拍板追认单十五项已追认（2026-10-17 用户令）；残留人闸=07 ㉖ 五件登记不阻塞**
|
||||
|
||||
---
|
||||
|
||||
@@ -684,13 +684,13 @@
|
||||
|
||||
**归属**：测试基建/工程债批（迭代 28；零玩法行为变更，装配顺序修复除外）
|
||||
|
||||
**状态**：✅ **已入库完成（2026-10-15，迭代 28 单会话交付——用户预批连做全批；T1 装配合同 `LAYER_CONTRACT` 单点化＋顺序修复＋V1a-d 断言重写／T2 `_smoke_boot_chain` 十断言／T3 `_smoke_lifecycle_matrix` 九阶段×五引用面／T4 渲染面三件（探针两自检＋墨色判据＋启动态菜单 golden）／T5 变异验证六次注入全见红并精确还原／T6 规范三处写入文档；冒烟 1086→1125/0〔+39＝新增 42−退役裸下标断言 3〕；run_all 全套＋probe_gate --click/--full＋render_gate 四闸全绿；MC 零跑〔零数值零行为变更〕；实现报告=design/qa/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕）**。本批立新硬规则「验收函数无变异红记录不算验收成立」，已落 CLAUDE.md 第 9 条＋code-conventions.md §3.6＋req-card 技能 §7 三处；GDD 反哺点三条见下条待用户逐点裁决
|
||||
**状态**：✅ **已入库完成（2026-10-15，迭代 28 单会话交付——用户预批连做全批；T1 装配合同 `LAYER_CONTRACT` 单点化＋顺序修复＋V1a-d 断言重写／T2 `_smoke_boot_chain` 十断言／T3 `_smoke_lifecycle_matrix` 九阶段×五引用面／T4 渲染面三件（探针两自检＋墨色判据＋启动态菜单 golden）／T5 变异验证六次注入全见红并精确还原／T6 规范三处写入文档；冒烟 1086→1125/0〔+39＝新增 42−退役裸下标断言 3〕；run_all 全套＋probe_gate --click/--full＋render_gate 四闸全绿；MC 零跑〔零数值零行为变更〕；实现报告=reports/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕）**。本批立新硬规则「验收函数无变异红记录不算验收成立」，已落 CLAUDE.md 第 9 条＋code-conventions.md §3.6（该内容现已独立成文于 test-conventions.md §6）＋req-card 技能 §7 三处；GDD 反哺点三条见下条，2026-10-17 用户逐点裁决已写入
|
||||
|
||||
---
|
||||
|
||||
#### 迭代 28 启动装配与生命周期验收补全批——GDD 反哺点三条（2026-10-15 顺带登记，待用户逐点裁决另批写入文档）
|
||||
#### 迭代 28 启动装配与生命周期验收补全批——GDD 反哺点三条（2026-10-15 顺带登记；2026-10-17 用户逐点裁决，已写入）
|
||||
|
||||
**现状**：六任务全量入库（单会话交付；变异验证六次注入全见红并精确还原；实现报告=design/qa/iter28-实现报告-2026-10-15.md）。实现与设计权威文档的差异/缺口如下，经裁决后另批写入文档——**机械面已顺带改动的有 roadmap/本条/07/active.md/CLAUDE.md/code-conventions.md/req-card 技能（仓外）**。**与迭代 27 反哺点①的关系**：迭代 27 只登记了「场景分层/会话生命周期陈述滞后于实态」的方向性缺口，本批把其中「层序＝谁说了算」「boot 后置条件是什么」「会话引用面何时活何时死」三件做成了代码级事实与可执行断言，本条是其**具体化承接**——写入文档时可合并处理。
|
||||
**现状**：六任务全量入库（单会话交付；变异验证六次注入全见红并精确还原；实现报告=reports/iter28-实现报告-2026-10-15.md）。实现与设计权威文档的差异/缺口如下，经裁决后另批写入文档——**机械面已顺带改动的有 roadmap/本条/07/active.md/CLAUDE.md/code-conventions.md/req-card 技能（仓外）**。**与迭代 27 反哺点①的关系**：迭代 27 只登记了「场景分层/会话生命周期陈述滞后于实态」的方向性缺口，本批把其中「层序＝谁说了算」「boot 后置条件是什么」「会话引用面何时活何时死」三件做成了代码级事实与可执行断言，本条是其**具体化承接**——写入文档时可合并处理。
|
||||
|
||||
**归属**：工程债/测试基建批完成反哺（不阻塞，不排期）
|
||||
|
||||
@@ -700,7 +700,24 @@
|
||||
| 2 | design/dev/architecture/architecture.md | **boot 链路后置条件**：本批以 `_smoke_boot_chain` 十断言把「启动后玩家该看到什么」成文（ConfigDB 就绪且表已载／系统设置已落引擎态／菜单层可见／续玩钮态＝断点在档态／闲时会话已在树／调试浮窗态＝DS_DEBUG 门控）；架构文档启动流程（:173）只有装配动作无后置条件——是否入册待裁 |
|
||||
| 3 | design/dev/architecture/architecture.md | **RunScope 生命周期存活性矩阵**：九阶段（闲时/开局停点/战斗中/结算后/选路页/终局面/回菜单收束/各模态开合后/两连局+续玩）× 五引用面（run_scope 在树／adventure／runner／settlement／四处回调句柄同源）的活死表；架构文档 :124 只登记了 RunScope 的存在——矩阵是否入册、阶段划分是否认账待裁 |
|
||||
|
||||
**状态**：备忘（反哺点三条待裁决；代拍板追认单见实现报告 §三；残留人闸=07 ㉗ 启动态菜单目检，登记不阻塞）
|
||||
**状态**：✅ **已写入（2026-10-17，用户逐点裁按推荐案）——三条合并入 architecture.md v1.8「呈现层装配与会话生命周期」节：①装配合同立条款、合同表不摘录（唯一事实源=`main.gd` `LAYER_CONTRACT`，登记时 16 层现为 17 项含 float 类）；②启动后置条件六条入「初始化顺序」节（登记时「十断言」现为六组 11 条——2026-10-16 角标令 V2f 拆两条）；③九阶段×五引用面存活性矩阵认账入册。代拍板追认单十三项已追认（第 14 项 req-card 双副本取齐仍待裁）；残留人闸=07 ㉗ 启动态菜单目检，登记不阻塞**
|
||||
|
||||
---
|
||||
|
||||
#### 迭代 29 测试分层与门禁语义修正批——GDD 反哺点三条＋一条建议（该批漏登本清单，2026-10-17 文档批补登记并已裁决写入）
|
||||
|
||||
**现状**：反哺三条与一条建议原只载于 `reports/iter29-实现报告-2026-10-16.md` §六第 2/4 项（该批未在 06 登记专条——属漏登）。2026-10-17 用户逐条裁决（全按推荐案）后写入——
|
||||
|
||||
| # | 文档 | 裁决结果与落点 |
|
||||
|---|---|---|
|
||||
| 1 | design/dev/test-conventions.md | 「三硬闸」与「新写测试件全类型标注」升格为纪律——写入新增 §7（闸承载三闸齐备义务＋负面套件仅豁免错误扫描一闸＋类型标注写法纪律，暂不机器闸） |
|
||||
| 2 | design/dev/test-conventions.md | 「判定可靠性优先于覆盖率」独立成节——写入新增 §8（绿≠能抓住；自证手段=变异验证/反例实证/零命中自检；覆盖率度量是否引入仍 06 在册待裁） |
|
||||
| 3 | design/gdd/07-体验验证清单.md | ㉖① 全流程走查**保留不注销**——屏壳切换正确性半由 `screen_flow_probe` 机检承接（入轻闸必跑段），节首加机检承接注记，版本历史加 v1.4 行 |
|
||||
| ＋ | design/dev/test-conventions.md | §六第 4 项建议（脚本错误静默中断所在函数剩余断言而套件仍报全绿，三处实证）——写入 §8 机制事实＋两条义务 |
|
||||
|
||||
**归属**：工程债/测试基建批完成反哺（不阻塞，不排期）
|
||||
|
||||
**状态**：✅ **已写入（2026-10-17，用户逐点裁按推荐案）——落点 test-conventions.md §7–§8、07 v1.4；本条为补登记，随本批留档不再待裁**
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -278,11 +278,14 @@
|
||||
| v1.1 | 2026-10-14 | 新增 ㉖ 代码架构技术债修复批全流程走查目检节（迭代 27 卡①随批登记：全流程观感零变化走查/续玩断点恢复/调试浮窗对局中可开不锁棋盘〔:407-408 事故回归〕/刷新余量显示一致/DS_DEBUG 启动浮窗+两屏角标——登记不阻塞；能力验证半=冒烟 V1-V9+parity 三变体逐位一致对拍五跑全同） |
|
||||
| v1.2 | 2026-10-15 | **冲突标记清理解（迭代 28 随批）**——本文件 v1.0/v1.1 两行处残留 `<<<<<<<`/`=======`/`>>>>>>>` 合并冲突标记（迭代 27 分支 iter27-techdebt-20261014 合并进 master 时漏解，两侧均有效故全留：qa 收尾批人闸核销行 + ㉖ 目检节登记行与正文节）；清理后两行内容照旧，仅版本号顺延。同批新增 ㉗ 启动态菜单目检节（迭代 28 卡①随批登记） |
|
||||
| v1.3 | 2026-10-15 | 简明技术中文用语规范（用户令）：词面修正 35 处（随批→顺带 25、收口→完成/合并进 master 5、台账→状态记录 1、销号→注销 2、报错→返回错误 1、对拍→与基线数据逐项比对 1；均系正文现役文本，版本历史既有行按豁免不动）＋失同步修复 0 处 |
|
||||
| v1.4 | 2026-10-17 | ㉖① 机检承接注记（迭代 29 GDD 反哺点经用户逐条裁决写入）：屏壳切换正确性已由 `screen_flow_probe` 机检承接（入轻闸必跑段）；该项**保留不注销**——承载机器抓不到的观感半（演出时序/文案/布局逐屏零漂移） |
|
||||
|
||||
|
||||
## ㉖ 代码架构技术债修复批——全流程走查（迭代 27 卡①顺带登记；能力验证半=冒烟 V1-V9+parity 三变体逐位一致、与基线数据逐项比对五跑全同）
|
||||
|
||||
> 场景拆分+会话物化+战斗域重构+账本完成+模态协议内聚后，玩家可见面唯一验收=观感零变化。登记不阻塞（2026-10-12 真人检测立规）。
|
||||
>
|
||||
> **机检承接注记（2026-10-17 用户裁，迭代 29 反哺点③）**：屏壳切换正确性半（六步主流程＋两条回退＋屏级互斥）已转机检 `screen_flow_probe` 入轻闸必跑段；第 1 项保留——其承载的是机检抓不到的观感半（逐屏演出时序/文案/布局零漂移）。
|
||||
|
||||
| # | 目检项 | 判据 |
|
||||
|---|---|---|
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 需求卡片：代码架构技术债修复批（场景拆分 · 局生命周期 · 战斗结算拆段 · 账本收口 · 类型闸 · 卫生件）
|
||||
|
||||
- 版本：v1.2（2026-10-14 成文 v1.0；同日用户令**编入迭代 27 卡①**——roadmap 迭代行已更新，M4 数值批顺延 28+。v1.1→v1.2：**§10 三点待裁全裁**（2026-10-14 用户三裁，全按推荐案：①第三个 autoload／②单类持四账／③审计五段）——零待裁点，卡片成立）
|
||||
- 来源：代码架构与实现质量审计报告-2026-10-14（双席审计，基线 master 97de02c；同日第三方逐条复核五处计数级瑕疵修正落文；**该报告已按退役规则于本批收口 git rm——吸收即死，修正后计数由本卡承载，收口结案=design/qa/iter27-实现报告-2026-10-14.md**）
|
||||
- 来源：代码架构与实现质量审计报告-2026-10-14（双席审计，基线 master 97de02c；同日第三方逐条复核五处计数级瑕疵修正落文；**该报告已按退役规则于本批收口 git rm——吸收即死，修正后计数由本卡承载，收口结案=reports/iter27-实现报告-2026-10-14.md**）
|
||||
- 归属：工程债/重构批（凭审计证据直接写卡，无设计定稿前置——2026-10-10 立规：缺陷修复/工程债/重构类工程需求无设计前置要求）
|
||||
- 排期：**已编入迭代 27 卡①**（2026-10-14 用户令；用户裁决记录：全部技术债修复允许放行单一大迭代，12-14 个工作日在允许时间范围内；**开工门=U0 已满足**——三点已裁（见版本行）＋用户 /goal+iter 27 发令，U0=2026-10-14 开工；M4 数值批顺延 28+）
|
||||
|
||||
|
||||
File renamed without changes.
File renamed without changes.
@@ -146,24 +146,24 @@
|
||||
|
||||
## 六、待裁与遗留
|
||||
|
||||
0. **【合回状态：本批暂不合回 master，等两个非本批红处理完】** 同步 master（`60449941`）后复跑重闸冒出两个红，
|
||||
已取证均与本批零关系：①**渲染闸** `menu_boot.png` changed=4.61%（超 2%容差）——在主区（不含本批任何改动）
|
||||
跑同一道闸，结果一模一样 4.61%，棋盘三张 golden 仍 0.00%；②**gdd_lint** `01-核心循环.md` R5
|
||||
「一场战斗的流程」节无流程图——master 提交 `272cc1ad` 的说明已自陈为并行会话 `9846a29f` 的既有问题。
|
||||
按「禁带红合并」纪律，2026-10-16 用户裁「不合回，等你处理」：本批九提交留在分支 `iter29-testlayers-20261016`，
|
||||
待这两条在 master 上处理完（菜单 golden 需核热区后按 Q6 口径显式重制；01-核心循环 R5 归其引入批补流程图），
|
||||
我重跑重闸后立即合回。**不代为刷新基线**——那样会把 4.61% 的真实视觉差异固化成存量，热区原因不再有人追。
|
||||
0. **【合回状态：已合并进 master（`fff4f120`，十提交，2026-10-16）】** 本项原文为「暂不合回，等两个非本批红处理完」
|
||||
（2026-10-16 用户裁），两个红其后各自结案：①渲染闸 `menu_boot.png` changed=4.61%（菜单 golden 热区漂移）
|
||||
——基线已在合并代码上显式重采（`dac9a94b`），现行菜单与棋盘三张 golden 均 0.00%；②gdd_lint
|
||||
`01-核心循环.md` R5 缺流程图——由引入批补流程图结案（提交 `fcb8c3f8`＋`8c18b52b`），基线 06 已回绿。
|
||||
本段为 2026-10-17 迁位批（`design/qa/` → `reports/`）改写，原待裁文字 git 历史可考。
|
||||
|
||||
1. **11 号闸的 parity 对拍要不要跑一次**（需你批准，我不能自行发起）：触面判定是机械的路径匹配，
|
||||
本批对 `battle_orchestrator.gd` 的改动实际只是加一个断言豁免常量（零玩法行为变更、零数值改动）。
|
||||
- 若按「MC 无数值改动零跑」红线 ⇒ 不跑，闸维持 NEED-APPROVAL（回执里留名，不判失败）；
|
||||
- 若要验证一次 ⇒ 批准后 `PARITY_APPROVED=1 tools/run_all_gates.sh`（三变体约 10–15 分钟）。
|
||||
2. **GDD 反哺点三条**（设计权威文档不随批改，待你裁决后另批落文）：
|
||||
- `design/dev/code-conventions.md` 测试纪律节：是否把「三硬闸」与「新写测试件全类型标注」写成硬纪律；
|
||||
- `design/dev/test-conventions.md`：是否补「判定可靠性优先于覆盖率」一节（本批的核心命题）；
|
||||
- `design/gdd/07-体验验证清单.md`：`screen_flow_probe` 已转机检，是否把对应的人工走查项销号。
|
||||
2. **GDD 反哺点三条**（2026-10-17 用户逐条裁决：三条全部写入）：
|
||||
- 「三硬闸」与「新写测试件全类型标注」→ **test-conventions.md §7**（code-conventions §3 已独立成文至此，故落此处）；
|
||||
- 「判定可靠性优先于覆盖率」→ **test-conventions.md §8**（本批核心命题成节）；
|
||||
- `screen_flow_probe` 转机检 → **07 v1.4**：㉖① 保留不注销，节首加机检承接注记。
|
||||
本条补登记为 06 专条（原漏登）。
|
||||
3. **06 已登记本批未收的七项**（不阻塞不排期）：余下 3 个 core 零指名模块、`render_gate` 的脚本错误扫描缺失、
|
||||
S7／S8（S6 亦仍在 TODO）、E 级卫生件、行覆盖率度量、`smoke_all` 拆分、parity 触面判定偏粗。
|
||||
4. **本批最有价值的副产品**（建议转设计侧裁决是否立规）：脚本错误会**静默中断所在函数的剩余断言**而
|
||||
4. **本批最有价值的副产品**（2026-10-17 用户裁决：写入）：脚本错误会**静默中断所在函数的剩余断言**而
|
||||
套件仍报「全绿」——本批至少三处实证（敌人表行集纪律 10 条零覆盖、`Callable` 形参类型写错让解析函数
|
||||
返回 null）。已由三硬闸之二机制性拦住，但是否把它写成 code-conventions 的硬纪律待裁。
|
||||
返回 null）。已由三硬闸之二机制性拦住；机制事实与「写验收函数须自证断言全数执行」义务已写入
|
||||
**test-conventions.md §8**。
|
||||
+10
-10
@@ -24,8 +24,8 @@
|
||||
## 当前位置（2026-10-16 刷新）
|
||||
|
||||
- **里程碑语义（2026-10-09 立规换代，详见下方里程碑表的换代注）**：现行里程碑 = **M3「Alpha 版本的完整实现」**——用户未明令宣布完成前停留 M3，迭代只排 M3 需求；M4=Beta 版本的完整实现，一律不排期。下文里程碑表的旧编号（M-3/M-4）保留作历史序列，语义以本节为准。
|
||||
- **迭代进度**：迭代 19 五卡全部已入库（2026-10-08）；**迭代 20=专长实装批 ✅ 已入库**（2026-10-11，出口闸全绿；残留人闸=实机目检五件+V20/V21/V22 人工核对半，07 在册）；**迭代 21=天赋树实装批 ✅ 已入库（2026-10-12 U0 开工单会话交付，T0-T7 全绿；残留人闸=实机目检四柜台）**；**迭代 22=秘宝体系实现重构落地批 ✅ 已入库（2026-10-12 单会话交付，T1-T7 全绿；残留人闸=实机目检秘宝解锁-装配流程）**；**迭代 23=锻造工坊实装批 ✅ 已入库（2026-10-12 单会话交付，T0-T7 全绿；残留人闸=实机目检工作间形态与购买交互）**；**迭代 24=敌人表内容修批（三关）✅ 已入库（2026-10-13 /goal+iter U0 开工单会话交付——N1 (1,2) 降档 hp22/ac2·N2 毒吐盾击两行六池·N3 敌方 attack_type 轴全填 normal+敌方结算克制消费点；冒烟 949/0+run_all 25 套+重闸全绿+MC 同种子配对 40 局×both 位移在带；实现报告=design/qa/iter24-实现报告-2026-10-13.md；残留人闸=实机目检三观测〔07 ㉓〕；代拍板追认单+GDD 反哺点五条待用户；**本迭代位仍预留后续追加卡——用户将把其他需求陆续编入本迭代**）；；**迭代 25=UI 全局主题批 ✅ 已入库**（2026-10-13 用户令编入，/goal+iter U0 单会话交付：全局主题资源 main_theme.tres 挂载+两处局部做法退役+冒烟 V1-V6 断言 38 条，冒烟 987/0+重闸全绿；实现报告=design/qa/iter25-实现报告-2026-10-13.md；残留人闸=实机目检全屏巡检〔07 ㉔〕）；**迭代 26=UI 交互与观感批已编入待开工**（2026-10-14 用户令；需求卡片 v1.2 零待裁点；开工门=U0——用户新会话 /iter 26 发令；本迭代位预留后续追加卡，同迭代 24 先例）；**迭代 27=代码架构技术债修复批 ✅ 已入库**（2026-10-14 /goal+iter U0 开工单会话交付：三屏场景化+会话物化+五段 Segment+RunLedger+ModalFlow+类型闸+卫生件五波全落；逐位一致对拍三变体五跑全同；实现报告=design/qa/iter27-实现报告-2026-10-14.md；残留人闸=实机目检五件〔07 ㉖〕；代拍板追认单十五项已追认（2026-10-17 用户令全同意）+GDD 反哺点两条待用户）；**迭代 28=启动装配与生命周期验收补全批 ✅ 已入库**（2026-10-15 用户令编入并预批连做全批，单会话交付：T1 装配语义合同 `LAYER_CONTRACT` 单点化＋冒险屏先挂/菜单屏后挂的顺序修复＋V1a-d 断言重写／T2 `_smoke_boot_chain` boot 链路十断言／T3 `_smoke_lifecycle_matrix` 九阶段×五引用面／T4 渲染面三件（shot_probe 两自检＋shot_checker 墨色判据＋启动态菜单 golden）／T5 变异验证六次注入全见红并精确还原／T6 规范三处落文；冒烟 **1086/0→1125/0**（+39＝新增 42−退役裸下标断言 3）；实现报告=design/qa/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕；代拍板追认单十三项已追认（含四条白名单外，2026-10-17 用户令全同意；第 14 项「req-card 双副本是否取齐」仍待裁）＋GDD 反哺点三条待用户裁决）；**迭代 29=测试分层与门禁语义修正批 ✅ 已入库**（2026-10-16 /iter U0 开工单会话交付：T1 三硬闸〔退出码／脚本错误扫描／断言数下限，三反例改前判绿改后判红〕／T2 术语订正＋CI 残留 8 处清除／T3 `tests/integration/` 建承载＋parity 收编为重闸 11 号条件闸件／T4 `screen_flow_probe` 入轻闸／T5 新增六套单测〔27→33 套〕／T6 S3 路径修正＋零命中自检＋补 S5／T7 游离脚本台账＋golden 判有效／T8 架构事实源三张表回写＋06 登记遗留七条；冒烟 1127/0 持平、重闸全绿存量红零新增；实现报告=design/qa/iter29-实现报告-2026-10-16.md；**无用户目检项**；代拍板追认单十二项已追认（2026-10-17 用户令全同意）＋GDD 反哺点三条待用户裁决；**遗留：11 号闸 parity 对拍判为触面，需用户批准才发起**）；**迭代 30=UI 呈现三卡批（徽章→样张→观感，迭代内串行）已编入·待开工**（2026-10-16 用户令编入——三卡待裁项同日用户令「按推荐方案」全部代拍板留痕、卡片均 v1.4，详见迭代 30 表行；开工门=U0 `/iter` 发令）；**迭代 31+ 位空·无批次**（原 M4 数值批已废——2026-10-16 用户删卡令「它就不是一个应该存在的东西」，禁止再以该名义立批/规划/引用已删卡；四项数值欠账归 06 在册、重新归属待用户裁）。
|
||||
- **近期主战场**：迭代 20/21/22/23/24/25/26 残留人闸（实机目检六批，07 在册）；**迭代 29 已入库；下一前沿=迭代 30 UI 呈现三卡批**（迭代 29 收口遗留=11 号闸 parity 对拍待批准发起＋GDD 反哺三条待裁；其后**迭代 30=UI 呈现三卡批**同日用户令编入·待开工〔三卡裁点已留痕，见迭代 30 表行〕；各批 provisional 终值的统一标定义务随 M4 数值批废除归 06 在册、重新归属待裁；迭代 20~28 残留人闸八批 07 在册）。
|
||||
- **迭代进度**：迭代 19 五卡全部已入库（2026-10-08）；**迭代 20=专长实装批 ✅ 已入库**（2026-10-11，出口闸全绿；残留人闸=实机目检五件+V20/V21/V22 人工核对半，07 在册）；**迭代 21=天赋树实装批 ✅ 已入库（2026-10-12 U0 开工单会话交付，T0-T7 全绿；残留人闸=实机目检四柜台）**；**迭代 22=秘宝体系实现重构落地批 ✅ 已入库（2026-10-12 单会话交付，T1-T7 全绿；残留人闸=实机目检秘宝解锁-装配流程）**；**迭代 23=锻造工坊实装批 ✅ 已入库（2026-10-12 单会话交付，T0-T7 全绿；残留人闸=实机目检工作间形态与购买交互）**；**迭代 24=敌人表内容修批（三关）✅ 已入库（2026-10-13 /goal+iter U0 开工单会话交付——N1 (1,2) 降档 hp22/ac2·N2 毒吐盾击两行六池·N3 敌方 attack_type 轴全填 normal+敌方结算克制消费点；冒烟 949/0+run_all 25 套+重闸全绿+MC 同种子配对 40 局×both 位移在带；实现报告已退役（git 历史可考）；残留人闸=实机目检三观测〔07 ㉓〕；代拍板追认单+GDD 反哺点五条待用户；**本迭代位仍预留后续追加卡——用户将把其他需求陆续编入本迭代**）；；**迭代 25=UI 全局主题批 ✅ 已入库**（2026-10-13 用户令编入，/goal+iter U0 单会话交付：全局主题资源 main_theme.tres 挂载+两处局部做法退役+冒烟 V1-V6 断言 38 条，冒烟 987/0+重闸全绿；实现报告已退役（git 历史可考）；残留人闸=实机目检全屏巡检〔07 ㉔〕）；**迭代 26=UI 交互与观感批已编入待开工**（2026-10-14 用户令；需求卡片 v1.2 零待裁点；开工门=U0——用户新会话 /iter 26 发令；本迭代位预留后续追加卡，同迭代 24 先例）；**迭代 27=代码架构技术债修复批 ✅ 已入库**（2026-10-14 /goal+iter U0 开工单会话交付：三屏场景化+会话物化+五段 Segment+RunLedger+ModalFlow+类型闸+卫生件五波全落；逐位一致对拍三变体五跑全同；实现报告=reports/iter27-实现报告-2026-10-14.md；残留人闸=实机目检五件〔07 ㉖〕；代拍板追认单十五项已追认（2026-10-17 用户令全同意）+GDD 反哺点两条已于 2026-10-17 用户逐条裁决写入）；**迭代 28=启动装配与生命周期验收补全批 ✅ 已入库**（2026-10-15 用户令编入并预批连做全批，单会话交付：T1 装配语义合同 `LAYER_CONTRACT` 单点化＋冒险屏先挂/菜单屏后挂的顺序修复＋V1a-d 断言重写／T2 `_smoke_boot_chain` boot 链路十断言／T3 `_smoke_lifecycle_matrix` 九阶段×五引用面／T4 渲染面三件（shot_probe 两自检＋shot_checker 墨色判据＋启动态菜单 golden）／T5 变异验证六次注入全见红并精确还原／T6 规范三处落文；冒烟 **1086/0→1125/0**（+39＝新增 42−退役裸下标断言 3）；实现报告=reports/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕；代拍板追认单十三项已追认（含四条白名单外，2026-10-17 用户令全同意；第 14 项「req-card 双副本是否取齐」仍待裁）＋GDD 反哺点三条已于 2026-10-17 用户逐条裁决写入）；**迭代 29=测试分层与门禁语义修正批 ✅ 已入库**（2026-10-16 /iter U0 开工单会话交付：T1 三硬闸〔退出码／脚本错误扫描／断言数下限，三反例改前判绿改后判红〕／T2 术语订正＋CI 残留 8 处清除／T3 `tests/integration/` 建承载＋parity 收编为重闸 11 号条件闸件／T4 `screen_flow_probe` 入轻闸／T5 新增六套单测〔27→33 套〕／T6 S3 路径修正＋零命中自检＋补 S5／T7 游离脚本台账＋golden 判有效／T8 架构事实源三张表回写＋06 登记遗留七条；冒烟 1127/0 持平、重闸全绿存量红零新增；实现报告=reports/iter29-实现报告-2026-10-16.md；**无用户目检项**；代拍板追认单十二项已追认（2026-10-17 用户令全同意）＋GDD 反哺点三条待用户裁决；**遗留：11 号闸 parity 对拍判为触面，需用户批准才发起**）；**迭代 30=UI 呈现三卡批（徽章→样张→观感，迭代内串行）已编入·待开工**（2026-10-16 用户令编入——三卡待裁项同日用户令「按推荐方案」全部代拍板留痕、卡片均 v1.4，详见迭代 30 表行；开工门=U0 `/iter` 发令）；**迭代 31+ 位空·无批次**（原 M4 数值批已废——2026-10-16 用户删卡令「它就不是一个应该存在的东西」，禁止再以该名义立批/规划/引用已删卡；四项数值欠账归 06 在册、重新归属待用户裁）。
|
||||
- **近期主战场**：迭代 20/21/22/23/24/25/26 残留人闸（实机目检六批，07 在册）；**迭代 29 已入库；下一前沿=迭代 30 UI 呈现三卡批**（迭代 29 入库后遗留=11 号闸 parity 对拍待批准发起＋GDD 反哺三条已裁决写入（2026-10-17）；其后**迭代 30=UI 呈现三卡批**同日用户令编入·待开工〔三卡裁点已留痕，见迭代 30 表行〕；各批 provisional 终值的统一标定义务随 M4 数值批废除归 06 在册、重新归属待裁；迭代 20~28 残留人闸八批 07 在册）。
|
||||
- **实时状态**：以根目录 [active.md](active.md) 顶部「当前状态快照」节为准（`stage.txt` 已定性为旧阶段开关，仅存档）。
|
||||
|
||||
## 主线路线（里程碑 × 迭代序列）
|
||||
@@ -76,15 +76,15 @@
|
||||
| 迭代 18 | **⑦新冒险种子随机化+调试浮窗升级（2026-10-07 用户令入迭代 18，同日两裁点全裁+浮窗目标态已定）**：**(a) 种子随机化**——现状考证 main.gd:1210 `_seed_value()` 调试种子框为空时硬编码返回 42=每次新冒险同一种子全程可复现；改法=玩家界面入口（主菜单开新冒险）默认分支随机生成；**✅ 裁点全裁（2026-10-07 用户令）：①首次冒险维持固定种子（教学态可复现）/②测试脚本与调试接口维持显式指定种子（冒烟·MC·探针全链显式传种子零影响，锚零作废）/③种子不进玩家 UI**；断点续玩零影响（存档已载 master_seed 回填，main.gd:447 现役）；与⑥收官批零耦合、排序自由。**(b) 调试浮窗升级**（承载「调试浮窗可查当局数据」裁点=种子的唯一查看位；**本项修订迭代 15 卡① P3 甲「仅开始菜单可开·对局不可达」裁决**）——目标态三件：独立于整体界面的**最高层浮窗**（对局中也可开）/DS_DEBUG=1 调试态下**默认打开**/新增**当局数据只读区块**（当前局种子/关卡/节点/HP/GP/钥石等——玩家 UI 不展示、调试浮窗可查）。考证在册（2026-10-07 实查）：现行=开始覆盖层角标入口〔main.gd:292-293，DS_DEBUG=1 点亮〕+main.gd:1189 门禁「仅开始菜单可开」+Dialog 形态走 ModalStack 模态栈登记〔非最高层〕+visible=false 初始非默认开+五区块（胜利演出/种子输入/数值滑条/批量模拟/两层调试）无当局数据面。需求卡片待裁点：最高层与模态栈登记制的关系〔置顶/登记序末+move_child 或独立层〕/输入吞噬边界〔浮窗矩形外透传游戏输入〕/对局发起「随开随收」逻辑改向/ui_tune_probe 断言面换代/入口形态（角标宿主迁移或热键）。需求卡片=`design/research/需求卡片-种子随机化与调试浮窗升级批-2026-10-07.md`（v1.0——实装级裁点 P1 遮挡语义〔荐甲=维持登记制〕/P2 入口形态〔荐甲=角标迁宿主〕/P3 默认打开范围〔荐甲=启动即开〕/P4 当局数据字段集〔荐甲=六项〕/P5 首局种子值〔荐甲=沿用 42〕待裁；估时勘误 1d→2.0d 含探针换代与收口） | **✅ 已落地（2026-10-07 worktree iter18-seed：C1 种子三分+浮窗升级 P1-P6 甲全落；批末重闸全绿=冒烟 811/0+四探针+run_all 17 套+doc 三闸/熵增闸零新增；MC 零跑；实机人闸挂账待用户〔不阻塞已入库与后续卡④〕）** | T0-T5≈2.0d |
|
||||
| 迭代 19 | **卡⓪主菜单开局缺陷修复批（原迭代 20 头卡A；2026-10-08 用户令并入本迭代、执行序第一）**：①**主菜单开新冒险+继续上局两入口补传同调三键**（attunement/attune_refresh_y/tree_rules——main.gd:510/:470，接收面 adventure_runner.gd:129-138/215-217 现成；静态考证缺陷成立：全仓无补偿路径、真实入口同调/X/Y 恒空、仅冒烟夹具喂值）；②**关卡开场行攻血改传当前生效值**（main.gd:519-521 现传初始表值，与战斗面板不一致=用户确认缺陷；「含面板加成」后缀判断同步改为认局外加成）；③冒烟补主菜单入口传参断言；④顺手删 adventure_runner.gd:129-134 三行重复赋值（零行为变化）。范围外=被动同调件呈现（用户令不动）、Fork 规则归因行（呈现层）、X/Y 刷新双源语义倒置（实现与用户口径镜像互换——X=刷新件源每节点重置不结转/Y=营地源整局持久/先扣 X，见 adventure_runner.gd:658-659/:706-709；用户口径=X 持久·Y 每节点重置·先扣 Y；真实局因①此前恒 0 未暴露——待用户裁定甲改实现/乙认现状，裁定落 GDD）。**卡①自动化验收补齐批（2026-10-07 用户令立项——全迭代两阶段验收盘点〔功能性+展示性，均自动化口径，不含人工目检〕的落地批）**：三件主内容——①**渲染闸自动化**：新增 `tools/render_gate.sh` 窗口化自动闸（shot_probe 四屏→shot_checker.py A-D 语义断言自动判定+fx_shot/board_shot 抓帧取证），棋盘 L1-L3 golden 逐像素基线入库 `game/tests/golden/`（测试资产入库先例，.gitignore 已核只挡 artwork/）；**probe_gate 头注释「渲染闸归真人目检」纪律句删除改写**（用户 2026-10-07 明示授权=历史偷懒标记），迭代 15③ 屏蔽挂账的机器补跑半随批核销〔07⑮ 目检半仍归用户不销号〕；②**探针收编**：ui_probe/ui_tune_probe/t17_defer_probe/fx_probe 四件游离探针（实测 17.4s/49.6s/63.0s/21.9s 全绿）收进 probe_gate `--full` 段挂重闸，轻闸默认段零改；damage_probe 出闸留盘标注诊断件、config_fatal_probe 删除（与 run_all 致命类单测重复）、零断言三件标注分析工具+ui_layout 补 1280/1920 最小断言；③**账务修正**：tests/README 套件数/断言数漂移（十五→17、752+→双口径说明）+integration 空目录处置（代拍板）。〔2026-10-07 范围改道：原「明示不收」的 B4/B5/B6 三缺口经用户令各立需求卡片并入本迭代，本卡改称卡①，新增卡②③④见后〕。需求卡片=`design/research/需求卡片-自动化验收补齐批-2026-10-07.md`（v1.1——**待裁点 0 项**，P1-P5+拷打轮一 Q1-Q8 全裁 2026-10-07〔重闸定义正式扩容 CLAUDE.md/过程截图即弃/shot_probe 扩屏三新屏/1280 单档/素材缺位 SKIP 而基线禁锚回退态/基线换代权限呈现批 agent/取证失败=闸红/integration 删空壳〕；🔴 契约 6 条含运行时代码零 diff/轻闸零删减/并行避让；停机点 S1 首跑存量 FAIL 全量呈报登记 06+S3 基线生成素材缺位停机；代拍板白名单四项）。**卡②旧界面呈现断言回补批（B5，2026-10-07 用户令立项）**：迭代 16 前落地旧屏追溯补 ui_contrast 测点对+ui_struct 契约——普查结论=对比度测点对旧屏 0 对（15 对现役全属 HUD/锚点/徽章/生涯）、专项契约仅 pause/career、legend/node 两屏从未过结构族；优先级=战斗结算框>商店>营地柜台+天赋树>设置面>三选一>迷雾锚定对；红线=只加断言零改旧屏、违例登记呈报不修（处置权归用户）；需求卡片=`design/research/需求卡片-旧界面呈现断言回补批-2026-10-07.md`（v1.1 grilling 三轮全裁——待裁点 0 项，WL 豁免边界/迷雾合成对最坏判据/时长闸 ≤2s/出口报告/06 遗留件登记全钉死；停机点 2〔对比度首跑存量违例/legend-node 结构首跑〕，T0-T4≈1.0d，worktree iter19-uibackfill）〔2026-10-08 施工已入库·**S1 停机态**——T1+T2 测点对 15→38 对（+23：battle_end 3/shop 5/camp 9/settings 2/curio 2/迷雾合成对 1，全 UiKit 常量实时求值）；**新对首跑暴露存量对比度违例 7 项**（结算 GP 账行 2.67:1/商店 legacy 行卡名 1.12:1/货架价签 1.46:1/营地铭牌副题 3.59:1/行价格 4.02:1/树分组头 2.67:1/工坊状态 3.00:1）——全量登记清单+修复建议案〔全现役常量换墨可落〕随出口报告呈用户裁，处置权归用户、批内零修（红线）；违例对在册=闸红登记存量形态，修复批落后自然转绿；T3 struct 13→15 根（legend/node 全真路径开合）首跑全绿 S2 未命中、WL 零新增；冒烟 840/0+run_all 17 套件持平；出口报告=`design/qa/iter19-uibackfill-exit-report-2026-10-08.md`；settlement_review 遗留件已在 06 登记落位〕。**卡③CI 预接线批Line truncated
|
||||
| 迭代 20 | **专长实装批（奇物）**——需求卡片=design/research/需求卡片-专长实装批-2026-10-11.md（v1.1）。范围：T0-T10（效果引擎词表扩签/池结构案D 实装/专长 27 件换代/凭证五件/Boss 兑付换代〔已裁换代〕/状态账/断点扩容/MC 新基线/迁出行删除/空配置验收闸）。候选 B-F 留档不变。**✅ 已入库（2026-10-11 goal 会话 U0 开工——A/B/C 三段 T0-T10 全落 master：T1 词表扩签 a57489e/T2 案D 池 0640b0c/T3 29 行换代 54ab330/T4 凭证五件 1387aed/V4 补齐 5ebd05d/C 段收尾 3333187；冒烟 864/0+run_all 21 套+MC 同种子重放逐位复现；29 行件数口径+四级配额 104+疼痛记忆同战消费放宽+时沙/弃图兑换落法映射系代拍板追认单待用户）** | ✅ 已入库（出口闸全绿+实机目检归用户 07 在册） | T0-T10 ✅ |
|
||||
| 迭代 21 | **天赋树实装批（2026-10-11 用户令编入——整卡不切分，迭代容量放宽容纳全卡）**：按 [天赋树](design/gdd/systems/跨局循环/天赋树.md) **v0.8** 设计权威文档实装——**33→12 节点**结构换代（三轮换代：攻防所有权切分 29→21〔树零攻防来源=红线，攻/AC 唯一入口=锻造工坊路线〕/一线一节点 21→15〔生命·命中淬炼各一节点×4 级、row 字段退役〕/Fork 一节点双态 15→12〔开局姿态·危险直觉·财富之道三组各一节点、购买解锁后 A/B 零币切换〕；schema=Fork 词表 4→3 组/规则键词表 2→6 键、「等级阈值前置」形态去留=R1 开放待裁点〔推荐裁撤，**不阻开工门**〕）+三组 Fork 真效果（开局姿态每关首轮窗/危险直觉与财富之道·限次计数随冒险持久按关重置）+营地统一案甲（树=营地主界面/属性升级唯一入口/工作间钥匙模型/图鉴常开/占位面板零副作用硬要求）+注入公式换代（基础值+树淬炼+锻造路线加值位预留+局内加算）+旧属性柜台退役+旧档废弃与旧逻辑删除（开发阶段无迁移，Q3 裁决）+同调位槽位判定源切树节点（旧条件删除随批清扫）+树上刷新升级接线（双入口并存写同账）。需求卡片=design/research/需求卡片-天赋树实装批-2026-10-11.md（**v1.7**——grilling 五裁+歧义扫描六裁+**2026-10-12 完备性/跨系统歧义审查十一裁**全落；零阻塞待裁点）；锻造工坊（原「武器锻造」）**17 裁点已清零**（2026-10-12 逐裁落文 v0.5，06 在册），Q5 排期前置已满足、默认本批先行；T0 的「标错机制存在性」与「boss_kill_count 消费面」两项**已预查结案**（标错机制查实存在且有代价，守侧 contingency 作废） | ✅ **已入库（2026-10-12，/goal+iter U0 开工令——T0-T7 全量交付；R1 按既定默认裁撤案执行；实现报告=design/qa/iter21-实现报告-2026-10-12.md；残留人闸=实机目检营地四柜台〔07 在册〕）** | T0-T7≈7.0-8.0d（整卡单迭代——实际 2026-10-12 单会话交付） |
|
||||
| 迭代 22 | **秘宝体系实现重构落地批**——需求卡片=design/research/需求卡片-秘宝体系实现重构落地批-2026-10-11.md（v1.3 C1-C6 全裁）；**2026-10-11 用户令编入**：新目录 12 件实装+解锁混合制（逐件分配锁定表在卡）+装配不可变（冒险中零更换）+旧数据行清理+效果引擎接入；槽位来源不在本批（树接口接缝——迭代 21 已实装树点亮数槽位源，本批直接消费）+装配档位格约束；估时 6d（区间 5-7d）——**✅ 已入库（2026-10-12，/goal+iter U0 开工单会话交付：T1 数据层 12 行换代+schema 扩签/T2 解锁服务+工坊面退役+档位格约束/T3 效果引擎接入+扩签+常时参数面+试炼镐积点口+充能周期/T4 呈现换代+呈现桥+试炼镐 HUD 入口/T5 替换子交互拆除+库存保留注记/T6 验收闸断言；冒烟 898/0+run_all 22 套+重闸全绿；实现报告=design/qa/iter22-实现报告-2026-10-12.md；残留人闸=实机目检秘宝解锁-装配正常流程〔07 ㉑〕）**
|
||||
| 迭代 21 | **天赋树实装批（2026-10-11 用户令编入——整卡不切分，迭代容量放宽容纳全卡）**：按 [天赋树](design/gdd/systems/跨局循环/天赋树.md) **v0.8** 设计权威文档实装——**33→12 节点**结构换代（三轮换代：攻防所有权切分 29→21〔树零攻防来源=红线，攻/AC 唯一入口=锻造工坊路线〕/一线一节点 21→15〔生命·命中淬炼各一节点×4 级、row 字段退役〕/Fork 一节点双态 15→12〔开局姿态·危险直觉·财富之道三组各一节点、购买解锁后 A/B 零币切换〕；schema=Fork 词表 4→3 组/规则键词表 2→6 键、「等级阈值前置」形态去留=R1 开放待裁点〔推荐裁撤，**不阻开工门**〕）+三组 Fork 真效果（开局姿态每关首轮窗/危险直觉与财富之道·限次计数随冒险持久按关重置）+营地统一案甲（树=营地主界面/属性升级唯一入口/工作间钥匙模型/图鉴常开/占位面板零副作用硬要求）+注入公式换代（基础值+树淬炼+锻造路线加值位预留+局内加算）+旧属性柜台退役+旧档废弃与旧逻辑删除（开发阶段无迁移，Q3 裁决）+同调位槽位判定源切树节点（旧条件删除随批清扫）+树上刷新升级接线（双入口并存写同账）。需求卡片=design/research/需求卡片-天赋树实装批-2026-10-11.md（**v1.7**——grilling 五裁+歧义扫描六裁+**2026-10-12 完备性/跨系统歧义审查十一裁**全落；零阻塞待裁点）；锻造工坊（原「武器锻造」）**17 裁点已清零**（2026-10-12 逐裁落文 v0.5，06 在册），Q5 排期前置已满足、默认本批先行；T0 的「标错机制存在性」与「boss_kill_count 消费面」两项**已预查结案**（标错机制查实存在且有代价，守侧 contingency 作废） | ✅ **已入库（2026-10-12，/goal+iter U0 开工令——T0-T7 全量交付；R1 按既定默认裁撤案执行；实现报告已退役（git 历史可考）；残留人闸=实机目检营地四柜台〔07 在册〕）** | T0-T7≈7.0-8.0d（整卡单迭代——实际 2026-10-12 单会话交付） |
|
||||
| 迭代 22 | **秘宝体系实现重构落地批**——需求卡片=design/research/需求卡片-秘宝体系实现重构落地批-2026-10-11.md（v1.3 C1-C6 全裁）；**2026-10-11 用户令编入**：新目录 12 件实装+解锁混合制（逐件分配锁定表在卡）+装配不可变（冒险中零更换）+旧数据行清理+效果引擎接入；槽位来源不在本批（树接口接缝——迭代 21 已实装树点亮数槽位源，本批直接消费）+装配档位格约束；估时 6d（区间 5-7d）——**✅ 已入库（2026-10-12，/goal+iter U0 开工单会话交付：T1 数据层 12 行换代+schema 扩签/T2 解锁服务+工坊面退役+档位格约束/T3 效果引擎接入+扩签+常时参数面+试炼镐积点口+充能周期/T4 呈现换代+呈现桥+试炼镐 HUD 入口/T5 替换子交互拆除+库存保留注记/T6 验收闸断言；冒烟 898/0+run_all 22 套+重闸全绿；实现报告已退役（git 历史可考）；残留人闸=实机目检秘宝解锁-装配正常流程〔07 ㉑〕）**
|
||||
| 迭代 23+ | **M4 数值批（**原 22+；迭代 21 已编入天赋树实装批、迭代 22 已编入秘宝实装批，均 2026-10-11 用户令**——**Alpha 收官位·未排期**〔2026-10-09 语义换代：M4=Beta 阶段、非 Alpha 收官位，M3 未由用户明令关闭前不排期维持〕——2026-10-05 用户令编入迭代 17 卡②；2026-10-06 用户令移出独立成批并定序「Alpha 阶段最后——内容补全先行、统一数值调整殿后」〔当日曾被编入迭代 18 为收官卡，2026-10-07 用户令撤回〕；**2026-10-07 用户令二次后移：后续新迭代（迭代 20 起）一律不先做 M4，除非用户明确要求启动 M4 批次**）**：四件数值欠账合一批——①削弱档位终值（weaken 现值 −65/duration 2/refresh 考证在册；叠层改续时语义已定案，差 duration 终值+当量锚复算）②调参批数值点评（06 条目现行登记五条——任务口径「八条」与条目五条不符，需求卡片 §2.2 已呈报差异以条目为准）③迭代 10 奖励重构联动欠账①②（钥石产出重标 boss_keystone 首杀 3/3/3·复杀 2/2/3 provisional + 通关率带重扫〔通关回血 20%+AP 件首轮 +1〕）④元进度定价剩余面（forge base 20/比 150 考证在册——06 条目文本「base 10」滞后于 2026-09-22 对齿批已呈报；Boss 两档终值）。读数义务随批=迭代 14 两件后置复算（T6 MC 四带复算+T7 技能池节奏重测，均挂 07）；顺路修复 damage_probe A1 改前既有红灯（判式换代批出口报告 §四.7 在册）。**硬约束：一切 MC/verifier 跑批发起前须用户批准；调参联动禁独立调参网络（β 带 [1.2,2.5] 逐 u 检算）**。需求卡片=`design/research/需求卡片-M4数值批-2026-10-05.md`（**v1.2 2026-10-06 案C 增补+联审修订**：v1.1 三事实与第五推算件照旧；联审=P3 转正顺延至重扫读数后/检算工具 WEAKEN_PCT 入同步面/F11 两句死文本全刷/T3·T5 四带复算并账一次跑批双认账/R5 改前锚=本批新立案C 锚/估时段一勘误 4.25d；案C 增补内容照旧=§2.6 三事实〔行为换代/锚全作废/难度预判〕+T0 推算稿第五件=对拍锚按新序重推导+T6 四带复算按案C 新行为首采；T0-T8≈6.25d，天然切分点 T4 末；🔴 契约 5 条含跑批批准制；**✅ 裁点全裁（2026-10-06 用户令：P1甲=维持 2 场·magnitude [60,85] 带内当量锚复算、具体值随出口 provisional 追认/P2甲 不对称有意/P3甲 3-3-3·2-2-3 维持、转正顺延至重扫读数到账且带内（Q4 二裁）/P4甲 不立直购价）；开工=U0**） | 迭代 18 全部内容卡（③④⑤⑦）出口+全部内容批行为变更落定+**用户发令（未排期）**——重锚窗口须收尽全部内容批行为变更 | T0-T8≈6.25d（超软盒预挂，段一 T0-T4≈4.25d〔v1.2 勘误，原 4.5 系加总错误〕/段二 T5-T8≈2.0d）。**⚠ 2026-10-16 作废注：本行所载「M4 数值批」需求卡片已由用户删除、批次名义废除（四项数值欠账归 06 在册·重新归属待用户裁）——本行仅作排期史保留，不再是任何在途批次；现行空位记录见「迭代 31+」行** |
|
||||
| 迭代 23 | **锻造工坊实装批（2026-10-12 用户令编入——设计面 v0.6 就绪）**：按 [锻造工坊](design/gdd/systems/跨局循环/锻造工坊.md) **v0.6** 设计权威文档实装——迁移面：①新建锻造路线行族（现役 `meta.tres` forge_products 已随迭代 21 T5 退役、无改造对象；钥石定价历史考古 20/150%、投值归 M4）②两根类型轴所有权移交（默认值归锻造工坊配置常驻持有、hero.tres 静态表两轴删除、选中态写存档域+冒险开始参数面注入）③存档域 forge_routes（已预登记存档序列化.md v7 计划行）④满级特效本期不实装（只留扩展位）⑤敌方 attack_type 填值归敌人系统/战斗结算侧（非本批——敌方定义数据、与名字血量同时读写、无独立时序）⑥术语登记（v0.6 已做完：术语表+registry）⑦数值验证义务=改前/改后同种子配对读数。解锁通道=并联双通道；一次冒险=一武器类型+一甲型。**✅ 已全批入库（2026-10-12，/goal+iter U0 开工单会话交付——worktree g-plan2-iter23-forge 七提交；T1 行族+T2 两轴移交+T3 写口族+T5 存档 v7（序调先行）+T4 注入链+T6 工作间 UI+T7 收口；冒烟 938/0+run_all 24 套+probe click/full+render_gate+doc 三闸/熵增对基线零新增+MC 同种子配对零漂移；实现报告=design/qa/iter23-实现报告-2026-10-12.md；残留人闸=实机目检工作间形态与购买交互〔07 在册〕；代拍板追认单+GDD 反哺点待用户）** | ✅ 已入库（出口闸全绿+实机目检归用户 07 在册） | 估时随需求卡片立项（实际单会话） |
|
||||
| 迭代 24 | **①敌人表内容修批（三关）（2026-10-13 用户令编入；**本迭代位预留后续追加卡**——用户将把其他需求陆续编入本迭代）**：需求卡片=`design/research/需求卡片-敌人表内容修批-2026-10-13.md`（**v1.1**——grilling 复核九问 Q1-Q9 已全裁、零待裁点、开工门=U0）。三件事合一：**N1** 第一关 (1,2) 降档（`enemy.tres:48` 改两值：`hp` 50→22、`armor_class` 3→2；**敌种 `bugbear` 不动**——`enemy.tres:594-600` 注释载明该行 50 血系 2026-09-24 用户裁决的设计而非填错，且 `hobgoblin` 无立绘，故「改敌种」案已否决；本批定性=阶名化解方案实机未达预期按 2026-10-13 体验反馈重裁）· **N2** 第二/三关普通敌技能投放（`skills.tres` 12→14 行：新增 `venom_spit` 毒吐 damage 1.6/CD2 挂 (2,5)/(2,6)/(2,7) 巨蜘蛛族、`shield_bash` 盾击 damage 1.7/CD3 挂 (3,0)/(3,5)/(3,7) 灰矮人族；**首遇教学位 (2,4) 池不动**，venom_spit 自 (2,5) 起投；两新行均不带 `rider_mult`——低 atk 下恒被 `damage_floor` 兜成 1 与 0.75 档等效）· **N3** 敌方 `attack_type` 加列并全填 `normal`（挂**敌种行**、20 行同值，不做差异化；`enemy_table.gd` 加枚举校验 + `unit_container.gd:119` 加单位快照 + `battle_orchestrator.gd:1406` 第 9 参由 `""` 改传值；全局平移=穿重甲受伤 −1 / 魔法护甲 +1 / 轻甲 0，使锻造甲路线首次具备战斗意义）。**契约要点**：池与敌种键属**契约级**，改必同步 `smoke_all.gd:3211` `expect_pools`（N1 因键值不变零改动、N2 同步 6 键）；节点图拓扑零触碰（A1 关卡节点图重构的地盘）；(1,1) 地精一伙不在本批范围（「第二个节点」字面偏差已登记 06）。**收口去向**：06「第一关遭遇表数值异常」「第二关技能池与投放」与锻造工坊条迁移面⑥ 三条一并销号；08「二·内容量」敌种池行注摘除 | ✅ 已入库（2026-10-13 单会话交付，出口闸全绿：冒烟 949/0+run_all 25 套〔485 批基线漂移 24→25 在案〕+探针 click/full+render_gate golden 0.00%+doc 三闸/熵增对基线零新增+MC 配对三组读数；实现报告=design/qa/iter24-实现报告-2026-10-13.md；残留人闸=实机目检三观测 07 ㉓） |
|
||||
| 迭代 25 | **①UI 全局主题批（引擎原生控件接管皮肤）（2026-10-13 用户令编入；UI 美化三层诊断 · 第一层第一条）**：**✅ 已全批入库（2026-10-13 /goal+iter U0 开工单会话交付，worktree g-plan2-iter25-theme 分支 iter25-theme-20261013）**——**T0 主题资源**：新建 `game/assets/theme/main_theme.tres` 挂 `project.godot` `gui/theme/custom`（15 类型全覆盖：V/HScrollBar·ScrollContainer·H/VSlider·TooltipPanel/Label·LineEdit·SpinBox·H/VSeparator + 预盖 CheckBox/CheckButton/OptionButton/PopupMenu 弹层；`default_font` 显式指向现役同字体文件=V6 中文字形防御；位图由 `tools/gen_theme_icons.py` 一次性生成落 `game/assets/art/ui/gen/`，色值溯源表落 `game/assets/theme/README.md`）· **T1 换代退役**：`ui_kit.gd` 的 `tooltip_theme()`/`_tip_theme` 与 `styled_slider()` 样式段、`ui_assembler.gd` 挂载行同批删除（禁新旧并存），settings_overlay 几何内联+debug_overlay `_slider_row` 双轨消隐· **T2 断言与文档同步闸**：冒烟新增 V1-V6 主题词条断言 38 条。**顺手销号**＝06 第三层「UI 元素细节修」之①（音量滑轨两段对比度重配＝已填充段 BG_ROOT #3A2E22 对暖石 #B8A582 实测 5.49:1）。**契约遵守**：🔴 Button 类型词条零接触（冒烟断言在闸）· 🔴 focus 族词条零定义（全主题扫描断言）· 🔴 零新增美术素材（位图=脚本生成纯色/几何）· 🔴 全局纹理过滤未动。**引擎事实订正（呈报追认）**：Godot 4.7.2 源码+默认主题链双查实证——①CheckButton 图标词条名与 CheckBox 同套 `checked`/`unchecked`（卡片 v1.2 注③「CheckButton 用 on/off」不成立，按引擎事实落位）②Slider 无 `grabber_pressed` 图标槽（冻结表「柄·按」值 GOLD_DEEP 留档未落位）③ScrollBar 柄是 StyleBox 非 Icon（无需位图）④4.7 导入参数已无逐贴图 filter 标志（位图原生尺寸消费无滤波伪影）。**闸**：冒烟 987/0（基线 949+本批 38 断言）+run_all 25 套+probe click/full+render_gate golden 0.00%+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）。**收口去向**：06「UI 全局主题资源缺失」条移除+「UI 元素细节修」①销号；08 升 v1.3（三·界面主题行→在役、五·表现细节修行注①销号）；07 ㉔ 全屏巡检登记；实现报告=design/qa/iter25-实现报告-2026-10-13.md。**待用户**：实机目检全屏巡检+专项观察点二（07 ㉔，登记不阻塞）+代拍板追认单（位图不入 git 政策口径/CheckButton 词条名订正等）+GDD 反哺点（组件规格是否立条款入 art-bible §7 等）。↓ 原任务登记：三件事合一——**T0** 新建 `game/assets/theme/main_theme.tres` 并挂 `project.godot` 的 `gui/theme/custom`，覆盖滚动条 / 滑轨 / 悬停气泡 / 输入件 / 分隔线等引擎原生控件，并预盖 CheckBox / CheckButton / OptionButton 及其弹层 PopupMenu（须在新主题内显式设 `default_font`＝现役同一字体文件；新增小位图落 `game/assets/art/ui/gen/`，色值溯源表落 `game/assets/theme/README.md`）· **T1** 退役 `ui_kit.gd` 的 `tooltip_theme()` 与 `styled_slider()` 两处局部做法、消 `debug_overlay._slider_row` 双轨（🔴 旧实现同批删除）· **T2** 断言与文档同步闸。契约要点：🔴 Button 类型词条零接触 · 🔴 focus 族词条零定义 · 🔴 不新增美术素材、不改美术圣经 §7 · 🔴 全局纹理过滤不动 | ✅ 已入库（出口闸全绿+实机目检归用户 07 ㉔ 在册） | T0-T2≈0.5–1d（实际单会话） |
|
||||
| 迭代 26 | **①UI 交互与观感批（2026-10-14 用户令编入；UI 美化三层诊断 · 第一层第二/三条＋第三层四件；本迭代位预留后续追加卡，同迭代 24 先例）**：需求卡片=`design/research/需求卡片-UI交互与观感批-2026-10-13.md`（**v1.2**——grilling 两轮八裁全落、零待裁点、卡片成立）。六项：**T1 按钮五态矩阵**（悬停=乙案 modulate 提亮〔与 primary_button 现行 `CANDLE.lightened(0.06)` 同纪律〕/禁用=本族底+α0.45 幽灵化/焦点=INK 2px 内缩 1px/危险钮补本族 pressed；走逐实例 override，迭代 25 两条主题红线断言维持不换代）· **T2 全局纹理过滤**（`project.godot` `default_texture_filter=0`＋vignette/gradient_base/beams 显式 LINEAR 白名单＋翻转面全枚举）· **T3 <4.5:1 换墨**（站桩顺位/护甲徽标换同族亮档＋RAP 行 STONE_DEEP，机检断言锚定）· **T4 光柱连续 alpha 渐变**（0→0.05→0 横向＋纵向衰减）· **T5 元素细节余②③**（BCard 图标槽明度差降档/商店卡片区垂直居中/营地四栏等高）· **T5b 诊断转储钮移调试浮窗**（`dump_diagnosis` 功能保留）。🔴 契约 5 条（主题层零新增词条/零新美术素材/棋盘零触碰/对比度 ≥4.5:1/旧实现同批清理）；验证闸 V1-V7；代拍板白名单八项；反哺点四条；**渲染闸 golden 面处置**=T6 第 4 步（徽标换墨落 board golden 裁剪区：闸红→核热区限预期面→显式重制基线+呈报→复闸，超预期=L3）。**范围订正**（grilling 实查，iter25 滑轨条同款先例）：②垫块仅三选一 BCard（商店卡实为纯文字行卡）/③仅商店+营地（三选一已居中）/危险钮「无按下态」订正为「在但皮肤错配」。估时 T0-T6≈2–2.5d | **✅ 已全批入库（2026-10-14 /goal+iter U0 开工单会话交付，worktree g-plan2-iter26-ui 分支 iter26-ui-20261014 七提交）**——T0 基线+枚举（含卡片 §2.2 枚举漏项勘误）/T1 按钮五态（悬停 modulate 提亮/禁用 α0.45 幽灵化/焦点 INK 2px 内缩 1px/危险钮本族按压态）/T2 全局 Nearest+平滑渐变件 LINEAR 白名单/T3 三处换墨（GOLD_BRIGHT/HERO_BLUE_BRIGHT/STONE_DEEP，6.47/5.88/5.98:1）/T4 光柱连续 alpha/T5 图标槽柔和档+商店居中+营地四栏等高/T5b 诊断钮迁调试浮窗；冒烟 987→1055/0（+68 断言）+run_all 25 套+probe click/full+render_gate golden 0.00%（登记即结未重制）+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）；实现报告=design/qa/iter26-实现报告-2026-10-14.md；残留人闸=实机目检五项（07 ㉕）；待用户=代拍板追认单十三项+GDD 反哺点四条 | T0-T6≈2–2.5d（实际单会话） |
|
||||
| 迭代 27 | **①代码架构技术债修复批（2026-10-14 用户令编入；来源=[代码架构与实现质量审计报告-2026-10-14](design/research/代码架构与实现质量审计报告-2026-10-14.md)，双席审计基线 97de02c，已逐条复核）**：需求卡片=`design/research/需求卡片-代码架构技术债修复批-2026-10-14.md`（**v1.2——三点全裁零待裁〔2026-10-14 用户三裁全按推荐案：①第三个 autoload／②单类持四账／③审计五段〕，卡片成立**）。五波：· **波一 场景拆分＋局生命周期物化（≈4-5d）**〔P0-1/P0-2：屏容器 .tscn 切分＝开始菜单根场景＋营地场景＋冒险场景〔内含 level_map/battle 两容器〕，视图代码原样搬、**40+ views 不转 .tscn**；SaveManager/MetaProgression 升格跨场景持有者；「一局」物化为可整体 `queue_free()` 的节点，`main.gd:647-657`/`:555-559` 手工清单消亡；13 个 smoke 探针挂载假设同批迁移〕· **波二 `_settle` 拆段（≈1.5d）**〔P1-1：五段 Segment 类 grant/aura/combat/decay/verdict，24 处 kind 分派随段归位，姊妹病灶 `damage_controller.gd:272` 148 行同批拆〕· **波三 账本收口（≈1.5d）**〔P1-4 共享四账 Ledger 类化＋P1-2 刷新双账删 main 副本＋P1-3 summary 增 `gp_final` 键、删 `gp_shadow_ledger.gd`〕· **波四 组合根可测化抽取＋模态协议内聚（≈1.5-2d）**〔P1-5/P2-7；**须在波一落地后重估抽取面再动**〕· **波五 类型闸收尾＋卫生件包（≈3d）**〔P1-6 拉闸＋存量 73 处收口，**须在其他重构全部落地后**；P2 七组顺手带〕。🔴 契约 6 条（**零行为变更·重构前后同种子完整局输出逐位一致**／只拆不重写／views 不转 .tscn／探针契约零破坏／信号纪律不变／执行顺序锁＋渲染零漂移）；**核心验收＝逐位一致对拍**（RngService 单盐流在役）；验证闸 V1-V9；代拍板白名单九项；反馈点两条（architecture／code-conventions）。 | **✅ 已全批入库（2026-10-14 /goal+iter U0 开工单会话交付，worktree g-plan2-iter27-techdebt 分支 iter27-techdebt-20261014 七提交）**——波一 三屏场景化+run_scope 会话物化+双 autoload（7a0d57d）/波二 _settle 五段 Segment+英雄攻击拆步（26301ba）/波三 RunLedger 单类四账+刷新双账删副本+gp_final 删影子账（6fd7d78）/波四 ModalFlow+互斥域 tags+双 context（8b9e556）/波五a 类型闸 368 参数化+审计器+warning 配置（b605022）/波五b 卫生件 13 死代码+FeatsEngine 退役+Callable 换装+状态机 enum 化+ConfigDB 归根+resolver 解耦（T6 笔）/T7 文档同步（本笔）。**闸**：逐位一致对拍三变体五跑全同（V1 核心验收）+冒烟 1055→1081/0（+V2 屏壳 11+V3 两连局 11+V4 段类 16+V6 模态 19+V5 快照 3+V7 2 断言）+run_all 25→27 套+probe click+render golden 0.00%+static_scan S1/S2/S4/S9 全绿（历史 cd 静默空转顺修）；MC 对拍=parity_anchor 三变体×40 局×RUNSUM+JSONL 双面（工具入库 tools/parity_anchor.py）；实现报告=design/qa/iter27-实现报告-2026-10-14.md（代拍板追认单十五项+GDD 反哺点两条）；残留人闸=实机目检五件（07 ㉖）；审计报告本体按退役规则 git rm | T0-T7≈12-14d（实际单会话） |
|
||||
| 迭代 28 | **①启动装配与生命周期验收补全批（2026-10-15 用户令编入）**：需求卡片=design/research/需求卡片-启动装配与生命周期验收补全批-2026-10-15.md（v1.0——零待裁点，用户预批连做全批）。六任务：T1 装配语义合同单点化+装配顺序修复+V2 断言重写/T2 boot 链路时序后置条件（_smoke_boot_chain 六断言）/T3 生命周期存活性矩阵（_smoke_lifecycle_matrix 十阶段×五引用面）/T4 渲染面内容断言（shot_probe 两自检+shot_checker 墨色占比+启动态菜单 golden）/T5 变异验证（横切随批）/T6 规范落文+文档同步闸+收口；修复坏事实三件（main.gd:207-210 装配序错致 F5 见战斗界面、smoke_all.gd:176 V2 断言保护 bug、菜单截图无内容断言）。🔴 契约 7 条（零玩法行为变更/合同单点化/断言禁裸下标/测试先行/变异验证门槛/只加不重构/闸机轮次纪律） | ✅ 已入库（2026-10-15 单会话交付：T0-T6 全绿；冒烟 1125/0、run_all 全套、probe_gate --click/--full、render_gate 四闸全绿；变异验证六次注入全见红；实现报告=design/qa/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕） | 实耗≈1 会话（原估 T0-T6≈5.25d） |
|
||||
| 迭代 23 | **锻造工坊实装批（2026-10-12 用户令编入——设计面 v0.6 就绪）**：按 [锻造工坊](design/gdd/systems/跨局循环/锻造工坊.md) **v0.6** 设计权威文档实装——迁移面：①新建锻造路线行族（现役 `meta.tres` forge_products 已随迭代 21 T5 退役、无改造对象；钥石定价历史考古 20/150%、投值归 M4）②两根类型轴所有权移交（默认值归锻造工坊配置常驻持有、hero.tres 静态表两轴删除、选中态写存档域+冒险开始参数面注入）③存档域 forge_routes（已预登记存档序列化.md v7 计划行）④满级特效本期不实装（只留扩展位）⑤敌方 attack_type 填值归敌人系统/战斗结算侧（非本批——敌方定义数据、与名字血量同时读写、无独立时序）⑥术语登记（v0.6 已做完：术语表+registry）⑦数值验证义务=改前/改后同种子配对读数。解锁通道=并联双通道；一次冒险=一武器类型+一甲型。**✅ 已全批入库（2026-10-12，/goal+iter U0 开工单会话交付——worktree g-plan2-iter23-forge 七提交；T1 行族+T2 两轴移交+T3 写口族+T5 存档 v7（序调先行）+T4 注入链+T6 工作间 UI+T7 收口；冒烟 938/0+run_all 24 套+probe click/full+render_gate+doc 三闸/熵增对基线零新增+MC 同种子配对零漂移；实现报告已退役（git 历史可考）；残留人闸=实机目检工作间形态与购买交互〔07 在册〕；代拍板追认单+GDD 反哺点待用户）** | ✅ 已入库（出口闸全绿+实机目检归用户 07 在册） | 估时随需求卡片立项（实际单会话） |
|
||||
| 迭代 24 | **①敌人表内容修批（三关）（2026-10-13 用户令编入；**本迭代位预留后续追加卡**——用户将把其他需求陆续编入本迭代）**：需求卡片=`design/research/需求卡片-敌人表内容修批-2026-10-13.md`（**v1.1**——grilling 复核九问 Q1-Q9 已全裁、零待裁点、开工门=U0）。三件事合一：**N1** 第一关 (1,2) 降档（`enemy.tres:48` 改两值：`hp` 50→22、`armor_class` 3→2；**敌种 `bugbear` 不动**——`enemy.tres:594-600` 注释载明该行 50 血系 2026-09-24 用户裁决的设计而非填错，且 `hobgoblin` 无立绘，故「改敌种」案已否决；本批定性=阶名化解方案实机未达预期按 2026-10-13 体验反馈重裁）· **N2** 第二/三关普通敌技能投放（`skills.tres` 12→14 行：新增 `venom_spit` 毒吐 damage 1.6/CD2 挂 (2,5)/(2,6)/(2,7) 巨蜘蛛族、`shield_bash` 盾击 damage 1.7/CD3 挂 (3,0)/(3,5)/(3,7) 灰矮人族；**首遇教学位 (2,4) 池不动**，venom_spit 自 (2,5) 起投；两新行均不带 `rider_mult`——低 atk 下恒被 `damage_floor` 兜成 1 与 0.75 档等效）· **N3** 敌方 `attack_type` 加列并全填 `normal`（挂**敌种行**、20 行同值，不做差异化；`enemy_table.gd` 加枚举校验 + `unit_container.gd:119` 加单位快照 + `battle_orchestrator.gd:1406` 第 9 参由 `""` 改传值；全局平移=穿重甲受伤 −1 / 魔法护甲 +1 / 轻甲 0，使锻造甲路线首次具备战斗意义）。**契约要点**：池与敌种键属**契约级**，改必同步 `smoke_all.gd:3211` `expect_pools`（N1 因键值不变零改动、N2 同步 6 键）；节点图拓扑零触碰（A1 关卡节点图重构的地盘）；(1,1) 地精一伙不在本批范围（「第二个节点」字面偏差已登记 06）。**收口去向**：06「第一关遭遇表数值异常」「第二关技能池与投放」与锻造工坊条迁移面⑥ 三条一并销号；08「二·内容量」敌种池行注摘除 | ✅ 已入库（2026-10-13 单会话交付，出口闸全绿：冒烟 949/0+run_all 25 套〔485 批基线漂移 24→25 在案〕+探针 click/full+render_gate golden 0.00%+doc 三闸/熵增对基线零新增+MC 配对三组读数；实现报告已退役（git 历史可考）；残留人闸=实机目检三观测 07 ㉓） |
|
||||
| 迭代 25 | **①UI 全局主题批（引擎原生控件接管皮肤）（2026-10-13 用户令编入；UI 美化三层诊断 · 第一层第一条）**：**✅ 已全批入库（2026-10-13 /goal+iter U0 开工单会话交付，worktree g-plan2-iter25-theme 分支 iter25-theme-20261013）**——**T0 主题资源**：新建 `game/assets/theme/main_theme.tres` 挂 `project.godot` `gui/theme/custom`（15 类型全覆盖：V/HScrollBar·ScrollContainer·H/VSlider·TooltipPanel/Label·LineEdit·SpinBox·H/VSeparator + 预盖 CheckBox/CheckButton/OptionButton/PopupMenu 弹层；`default_font` 显式指向现役同字体文件=V6 中文字形防御；位图由 `tools/gen_theme_icons.py` 一次性生成落 `game/assets/art/ui/gen/`，色值溯源表落 `game/assets/theme/README.md`）· **T1 换代退役**：`ui_kit.gd` 的 `tooltip_theme()`/`_tip_theme` 与 `styled_slider()` 样式段、`ui_assembler.gd` 挂载行同批删除（禁新旧并存），settings_overlay 几何内联+debug_overlay `_slider_row` 双轨消隐· **T2 断言与文档同步闸**：冒烟新增 V1-V6 主题词条断言 38 条。**顺手销号**＝06 第三层「UI 元素细节修」之①（音量滑轨两段对比度重配＝已填充段 BG_ROOT #3A2E22 对暖石 #B8A582 实测 5.49:1）。**契约遵守**：🔴 Button 类型词条零接触（冒烟断言在闸）· 🔴 focus 族词条零定义（全主题扫描断言）· 🔴 零新增美术素材（位图=脚本生成纯色/几何）· 🔴 全局纹理过滤未动。**引擎事实订正（呈报追认）**：Godot 4.7.2 源码+默认主题链双查实证——①CheckButton 图标词条名与 CheckBox 同套 `checked`/`unchecked`（卡片 v1.2 注③「CheckButton 用 on/off」不成立，按引擎事实落位）②Slider 无 `grabber_pressed` 图标槽（冻结表「柄·按」值 GOLD_DEEP 留档未落位）③ScrollBar 柄是 StyleBox 非 Icon（无需位图）④4.7 导入参数已无逐贴图 filter 标志（位图原生尺寸消费无滤波伪影）。**闸**：冒烟 987/0（基线 949+本批 38 断言）+run_all 25 套+probe click/full+render_gate golden 0.00%+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）。**收口去向**：06「UI 全局主题资源缺失」条移除+「UI 元素细节修」①销号；08 升 v1.3（三·界面主题行→在役、五·表现细节修行注①销号）；07 ㉔ 全屏巡检登记；实现报告已退役（git 历史可考）。**待用户**：实机目检全屏巡检+专项观察点二（07 ㉔，登记不阻塞）+代拍板追认单（位图不入 git 政策口径/CheckButton 词条名订正等）+GDD 反哺点（组件规格是否立条款入 art-bible §7 等）。↓ 原任务登记：三件事合一——**T0** 新建 `game/assets/theme/main_theme.tres` 并挂 `project.godot` 的 `gui/theme/custom`，覆盖滚动条 / 滑轨 / 悬停气泡 / 输入件 / 分隔线等引擎原生控件，并预盖 CheckBox / CheckButton / OptionButton 及其弹层 PopupMenu（须在新主题内显式设 `default_font`＝现役同一字体文件；新增小位图落 `game/assets/art/ui/gen/`，色值溯源表落 `game/assets/theme/README.md`）· **T1** 退役 `ui_kit.gd` 的 `tooltip_theme()` 与 `styled_slider()` 两处局部做法、消 `debug_overlay._slider_row` 双轨（🔴 旧实现同批删除）· **T2** 断言与文档同步闸。契约要点：🔴 Button 类型词条零接触 · 🔴 focus 族词条零定义 · 🔴 不新增美术素材、不改美术圣经 §7 · 🔴 全局纹理过滤不动 | ✅ 已入库（出口闸全绿+实机目检归用户 07 ㉔ 在册） | T0-T2≈0.5–1d（实际单会话） |
|
||||
| 迭代 26 | **①UI 交互与观感批（2026-10-14 用户令编入；UI 美化三层诊断 · 第一层第二/三条＋第三层四件；本迭代位预留后续追加卡，同迭代 24 先例）**：需求卡片=`design/research/需求卡片-UI交互与观感批-2026-10-13.md`（**v1.2**——grilling 两轮八裁全落、零待裁点、卡片成立）。六项：**T1 按钮五态矩阵**（悬停=乙案 modulate 提亮〔与 primary_button 现行 `CANDLE.lightened(0.06)` 同纪律〕/禁用=本族底+α0.45 幽灵化/焦点=INK 2px 内缩 1px/危险钮补本族 pressed；走逐实例 override，迭代 25 两条主题红线断言维持不换代）· **T2 全局纹理过滤**（`project.godot` `default_texture_filter=0`＋vignette/gradient_base/beams 显式 LINEAR 白名单＋翻转面全枚举）· **T3 <4.5:1 换墨**（站桩顺位/护甲徽标换同族亮档＋RAP 行 STONE_DEEP，机检断言锚定）· **T4 光柱连续 alpha 渐变**（0→0.05→0 横向＋纵向衰减）· **T5 元素细节余②③**（BCard 图标槽明度差降档/商店卡片区垂直居中/营地四栏等高）· **T5b 诊断转储钮移调试浮窗**（`dump_diagnosis` 功能保留）。🔴 契约 5 条（主题层零新增词条/零新美术素材/棋盘零触碰/对比度 ≥4.5:1/旧实现同批清理）；验证闸 V1-V7；代拍板白名单八项；反哺点四条；**渲染闸 golden 面处置**=T6 第 4 步（徽标换墨落 board golden 裁剪区：闸红→核热区限预期面→显式重制基线+呈报→复闸，超预期=L3）。**范围订正**（grilling 实查，iter25 滑轨条同款先例）：②垫块仅三选一 BCard（商店卡实为纯文字行卡）/③仅商店+营地（三选一已居中）/危险钮「无按下态」订正为「在但皮肤错配」。估时 T0-T6≈2–2.5d | **✅ 已全批入库（2026-10-14 /goal+iter U0 开工单会话交付，worktree g-plan2-iter26-ui 分支 iter26-ui-20261014 七提交）**——T0 基线+枚举（含卡片 §2.2 枚举漏项勘误）/T1 按钮五态（悬停 modulate 提亮/禁用 α0.45 幽灵化/焦点 INK 2px 内缩 1px/危险钮本族按压态）/T2 全局 Nearest+平滑渐变件 LINEAR 白名单/T3 三处换墨（GOLD_BRIGHT/HERO_BLUE_BRIGHT/STONE_DEEP，6.47/5.88/5.98:1）/T4 光柱连续 alpha/T5 图标槽柔和档+商店居中+营地四栏等高/T5b 诊断钮迁调试浮窗；冒烟 987→1055/0（+68 断言）+run_all 25 套+probe click/full+render_gate golden 0.00%（登记即结未重制）+doc 三闸/熵增对基线零新增；MC 零跑（零数值零行为=纯呈现）；实现报告已退役（git 历史可考）；残留人闸=实机目检五项（07 ㉕）；待用户=代拍板追认单十三项+GDD 反哺点四条 | T0-T6≈2–2.5d（实际单会话） |
|
||||
| 迭代 27 | **①代码架构技术债修复批（2026-10-14 用户令编入；来源=[代码架构与实现质量审计报告-2026-10-14](design/research/代码架构与实现质量审计报告-2026-10-14.md)，双席审计基线 97de02c，已逐条复核）**：需求卡片=`design/research/需求卡片-代码架构技术债修复批-2026-10-14.md`（**v1.2——三点全裁零待裁〔2026-10-14 用户三裁全按推荐案：①第三个 autoload／②单类持四账／③审计五段〕，卡片成立**）。五波：· **波一 场景拆分＋局生命周期物化（≈4-5d）**〔P0-1/P0-2：屏容器 .tscn 切分＝开始菜单根场景＋营地场景＋冒险场景〔内含 level_map/battle 两容器〕，视图代码原样搬、**40+ views 不转 .tscn**；SaveManager/MetaProgression 升格跨场景持有者；「一局」物化为可整体 `queue_free()` 的节点，`main.gd:647-657`/`:555-559` 手工清单消亡；13 个 smoke 探针挂载假设同批迁移〕· **波二 `_settle` 拆段（≈1.5d）**〔P1-1：五段 Segment 类 grant/aura/combat/decay/verdict，24 处 kind 分派随段归位，姊妹病灶 `damage_controller.gd:272` 148 行同批拆〕· **波三 账本收口（≈1.5d）**〔P1-4 共享四账 Ledger 类化＋P1-2 刷新双账删 main 副本＋P1-3 summary 增 `gp_final` 键、删 `gp_shadow_ledger.gd`〕· **波四 组合根可测化抽取＋模态协议内聚（≈1.5-2d）**〔P1-5/P2-7；**须在波一落地后重估抽取面再动**〕· **波五 类型闸收尾＋卫生件包（≈3d）**〔P1-6 拉闸＋存量 73 处收口，**须在其他重构全部落地后**；P2 七组顺手带〕。🔴 契约 6 条（**零行为变更·重构前后同种子完整局输出逐位一致**／只拆不重写／views 不转 .tscn／探针契约零破坏／信号纪律不变／执行顺序锁＋渲染零漂移）；**核心验收＝逐位一致对拍**（RngService 单盐流在役）；验证闸 V1-V9；代拍板白名单九项；反馈点两条（architecture／code-conventions）。 | **✅ 已全批入库（2026-10-14 /goal+iter U0 开工单会话交付，worktree g-plan2-iter27-techdebt 分支 iter27-techdebt-20261014 七提交）**——波一 三屏场景化+run_scope 会话物化+双 autoload（7a0d57d）/波二 _settle 五段 Segment+英雄攻击拆步（26301ba）/波三 RunLedger 单类四账+刷新双账删副本+gp_final 删影子账（6fd7d78）/波四 ModalFlow+互斥域 tags+双 context（8b9e556）/波五a 类型闸 368 参数化+审计器+warning 配置（b605022）/波五b 卫生件 13 死代码+FeatsEngine 退役+Callable 换装+状态机 enum 化+ConfigDB 归根+resolver 解耦（T6 笔）/T7 文档同步（本笔）。**闸**：逐位一致对拍三变体五跑全同（V1 核心验收）+冒烟 1055→1081/0（+V2 屏壳 11+V3 两连局 11+V4 段类 16+V6 模态 19+V5 快照 3+V7 2 断言）+run_all 25→27 套+probe click+render golden 0.00%+static_scan S1/S2/S4/S9 全绿（历史 cd 静默空转顺修）；MC 对拍=parity_anchor 三变体×40 局×RUNSUM+JSONL 双面（工具入库 tools/parity_anchor.py）；实现报告=reports/iter27-实现报告-2026-10-14.md（代拍板追认单十五项+GDD 反哺点两条）；残留人闸=实机目检五件（07 ㉖）；审计报告本体按退役规则 git rm | T0-T7≈12-14d（实际单会话） |
|
||||
| 迭代 28 | **①启动装配与生命周期验收补全批（2026-10-15 用户令编入）**：需求卡片=design/research/需求卡片-启动装配与生命周期验收补全批-2026-10-15.md（v1.0——零待裁点，用户预批连做全批）。六任务：T1 装配语义合同单点化+装配顺序修复+V2 断言重写/T2 boot 链路时序后置条件（_smoke_boot_chain 六断言）/T3 生命周期存活性矩阵（_smoke_lifecycle_matrix 十阶段×五引用面）/T4 渲染面内容断言（shot_probe 两自检+shot_checker 墨色占比+启动态菜单 golden）/T5 变异验证（横切随批）/T6 规范落文+文档同步闸+收口；修复坏事实三件（main.gd:207-210 装配序错致 F5 见战斗界面、smoke_all.gd:176 V2 断言保护 bug、菜单截图无内容断言）。🔴 契约 7 条（零玩法行为变更/合同单点化/断言禁裸下标/测试先行/变异验证门槛/只加不重构/闸机轮次纪律） | ✅ 已入库（2026-10-15 单会话交付：T0-T6 全绿；冒烟 1125/0、run_all 全套、probe_gate --click/--full、render_gate 四闸全绿；变异验证六次注入全见红；实现报告=reports/iter28-实现报告-2026-10-15.md；残留人闸=实机目检启动态菜单〔07 ㉗〕） | 实耗≈1 会话（原估 T0-T6≈5.25d） |
|
||||
| 迭代 29 | **①测试分层与门禁语义修正批（2026-10-16 用户令编入）**：把验收语义从「跑一遍没崩＝冒烟通过」扭转为「**三层完备＋判定可靠**」——兑现用户三条诉求（①最单元的逻辑代码有单元测试 ②整体模块有接口测试 ③整体系统有 UI 方面与场景切换相关的测试）且验收不止于冒烟。四件事：**①本地闸三硬闸**（退出码为唯一权威判据·PASS 串降级为日志；`SCRIPT ERROR`/`Parse Error` 扫描命中即红；断言数为零即红——`probe_gate.sh` 四探针判定改退出码优先、`test_kit.finish` 零断言判红、`run_all` 汇总校验实跑套件数，全部反例实证留档）；**②L2 接口层从零建承载**（建 `game/tests/integration/`＋`parity_anchor` 收编入闸表＋存档⇄RNG 快照往返首个集成用例）；**③L3 屏壳切换探针**（新建 `screen_flow_probe`：六步主流程＋三屏壳 `visible` 互斥＋放弃回退路径，入轻闸）；**④L1 补洞＋术语订正＋状态记录清理**（4 个 core 零指名模块＋呈现层风险前三补单测；「冒烟」唯一保留语义＝秒级存活检查；15 个游离脚本逐个定性、golden 基线时效判定、补 S5 扫描规则）。🔴 契约 7 条（零玩法行为变更／三硬闸不可绕过／现有断言面只增不减／不引入第三方测试框架／架构事实唯一源＝architecture.md／探针契约零破坏／测试执行两入口铁规）；验证闸 V1–V11；代拍板白名单 10 项；**无用户目检项（纯基建）**。需求卡片=`design/research/需求卡片-测试分层与门禁语义修正批-2026-10-15.md`（**v2.0**——三轮复查定稿、零待裁点；§2 事实面改指针归 architecture.md「测试与质量域」节，T2 吸收 CI 残留 8 处，T6 收 S3 路径修正＋零命中自检，T5 补洞选面换 board_generator；T0–T8≈6.0–7.5d） | ✅ 已入库（2026-10-16 /iter U0 发令；worktree `g-plan2-iter29-testlayers`，分支 `iter29-testlayers-20261016`；重闸全绿、存量红零新增；**遗留＝11 号闸 parity 对拍待用户批准发起**） | 实耗≈1 会话（原估 T0–T8≈6.0–7.5d） |
|
||||
| 迭代 30 | **①UI 呈现三卡批（2026-10-16 用户令编入——三卡待裁项同日用户令「按推荐方案」全部代拍板留痕，卡片均 v1.4；迭代内串行 ①→②→③，禁三线并行，依据=06/08/07/art-bible/roadmap/active 汇聚文件互踩〔grilling 审查记录 D3〕）**：**①未开格类型徽章批**——类型微光实装：英雄周界 8 格内未开格、组粒度五组色相（色相系既裁=art-bible 样张 v2 定稿，本批只补从未定义的组间明度档 provisional 值、复核转正义务移交②）、渲染路线裁丙=每格 CanvasItem shader 接触带柔光为主+程序绘制兜底（T0 原型帧先行件前置；视觉调优走「出帧→目检→改参」迭代，不承诺轮数）、开关裁丙=默认开+组合根布尔+调试浮窗可切（off 态逐位一致断言承接基线保护）、静态态（§2.1 既裁合规）、两套色带不并入本批（统一另登 06 条·批次出口写入文档）。卡片=`design/research/需求卡片-未开格类型徽章批-2026-10-16.md` → **②战斗一屏样张批**——裁丙「样张即设计目标图」：本批仅战斗屏（Q2 甲，余三屏登 06 排队）、引擎实拍+shader 为主路线（Q3 乙，半天试验件前置、证伪预设退甲案纯代码管线）、字重按目标效果示意（Q4 丙，字体补完批按样张补真件）、双口径两闸分跑（Q6 乙）、死指涉改指在盘最近稿注「指代稿」（Q5 甲）；交付含目标规格清单（尺寸档/色板/明度档逐件成文，反向给素材批）+徽章明度档复核转正。卡片=`design/research/需求卡片-战斗一屏样张批-2026-10-16.md`（≈5–6d）→ **③第二/三关棋盘观感批**——L2/L3 同批（Q3 甲）；T1 定性采样+归因报告过 06 既裁「素材轴/UI 轴」定性人闸（含 T1b 新建舞台底采样件）；素材轴默认甲案 recolor 换色候选样张先行，甲/乙（远程生图重产）裁点挂 T1 出口呈报硬步骤；若裁乙，瓦片规格随②目标规格清单、与徽章明度档同基线防互踩。卡片=`design/research/需求卡片-二三关棋盘观感批-2026-10-16.md`（5–7d）。验收共性=机检断言+用户目检（真人检测按 CLAUDE.md 既裁登记不阻塞、否决即回补）；08「五 · 表现」对应三行出口改写 | 迭代 29 完成（汇聚文件串行）＋**U0 开工门**：用户 `/iter` 发令（三卡裁点已全部留痕·无待裁残留） | 三批串行合计 ≈11–14d——超软盒 7d，按批次分会话逐个 U0 发令（各卡内部切分点见卡），禁单会话连做跨卡 |
|
||||
| 迭代 31+ | **（位空·无批次——原「M4 数值批」已废）**：2026-10-16 用户令删除需求卡片（原话「它就不是一个应该存在的东西」）⇒ **禁止再以「M4 数值批」名义立批、再规划、再引用已删卡片**。四件数值欠账本身仍在册——①削弱档位终值 ②调参批数值点评（06 条目现行五条）③钥石产出重标＋通关率带重扫（迭代 10 奖励重构联动欠账）④元进度定价剩余面（forge 定价·Boss 两档终值）——连同各批 provisional 终值标定义务，**一律归 `design/gdd/06-待办清单.md` 跟踪，重新归属待用户裁**；读数复算义务（迭代 14 两件后置）仍挂 07，damage_probe A1 既有红灯在册。M4=Beta 阶段口径不变（M3 未由用户明令关闭前不排期）；本迭代位留空待用户令编入 | 用户发令编入（未排期） | —— |
|
||||
|
||||
Reference in new issue
Block a user