game-group/gplan-2
2
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(规则修订): 改动四类＋卡片/迭代两层模型落规约（2026-10-25 用户裁定 12 项全执行）——AGENTS「两类批」改「改动四类」（需求改动=唯一走写卡+迭代；工程/文档设计/美术素材=无卡无迭代直改）＋五段铁律限定需求改动并补两层口径；process-conventions §2 首句改造＋两层口径＋工程直入拆分＋「低于5不得编」改「任何卡可编入、<5=冻结待凑批」；doc-conventions §12 状态机补待执行与直改类序列、通道表拆需求性/工程性、§12.2 补冻结待凑批与周期新规；test-conventions 头注补测试归属句；术语表术语替换；pipeline_gate 状态词表/状态五形态/周期校验同步（<5 未处冻结态才红）；三张违形卡（S9/S13/节点图换代收尾批）删除、结论回写条目、五条目状态改待执行；退役词四处顺带换代。全量域闸绿（回执 full 档，07 doc_link 较基线改善）；子代理审计过（四小修已落）。.zcode/.qoder 六技能（iter/iter-plan/req-card/batch-closure/doc-design/asset-ingest）同批换代，不入 git

Browse Source
This commit is contained in:
DKChan committed 2026-10-25 06:57:29 +08:00
1 parent e20eb90d56
commit 9fdacdebeb
10 files changed
+39 -547
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

reports/需求卡片-S13基线键治本-2026-10-25.md
-161
View File
@@ -1,161 +0,0 @@
# 需求卡片——S13 基线键治本（稳定身份键＋恶化判据＋刷新对账自检）
- 批名：S13 基线键治本｜日期：2026-10-25｜批次性质：非迭代批（tools/ 闸机面；改动面＝tools/＋game/tests/ → 代码域档）
- 估时：0.4–0.6 工作日（T0 0.2／T1 0.15／T2 0.15；软盒上限 0.6，超出按异常分级 L3 停机呈报）
- 来源：待办清单「S13 gdstyle 免名单把数字当身份——存量债改小也报『基线外新违规』」（2026-10-25 登记，来源=批次移交，设计面=工程直入）
- 验收证明口径：按 2026-10-24 用户裁定，一切验收走撤销证明。待办条目原文写「变异验证四项」，本卡以撤销证明等价覆盖同四判据（新增必红＝R2／漂移不冒新＝R1／恶化必红＝R3／禁闸内自动重生成自检＝R5＋R6），不另做变异类测试。
## 1 目标与完成定义
**做什么**：三件套治本——① `tools/gdstyle_gate.py` 的违规匹配键从「文件|规则|消息全文」改为稳定身份键「文件|规则|函数名」（无函数名条目退化为「文件|规则」；解析不出数值的条目退化为现行全文键）；② 新增恶化判据——同身份当前值大于基线登记值即判红（X=0，不分规则，2026-10-25 用户裁）；③ `--refresh` 加对账自检（打印新旧两向清单＋骤降守卫）。批内人工重生成基线（239 条→234 条），两处文案随动。
**完成定义**：验收对照表 R1–R8 全过＋按改动域选档跑闸全绿＋基线 234 条落盘＋`reports/` 三份产出物（实现报告／代拍板追认单／反哺点清单）齐＋待办清单 S13 条目状态由流水线推进。
## 2 设计事实源
工程直入证据指认（与待办条目一致，写卡会话 2026-10-25 已实查复核）：
- `tools/gdstyle_gate.py:82`——`keys.add("%s|%s|%s" % (file_path, f["rule"], f.get("message", "")))`，消息全文入键，而消息文本自带具体数字（如 `function 'resume_adventure' is 104 lines long (max 50)`），数字一变即匹配失败、被判「基线外新违规」
- master 尖 `a913ad44` 实测（2026-10-25）：扫描面 100 个 .gd、命中 234 条、基线内 222 条、基线外新违规 12 条（红）；基线 241 行＝2 行头注＋239 条
- gdstyle v0.4.0（钉版）JSON 输出字段＝`file/rule/message/severity/span`，无结构化指标字段——函数名与数值只能从 message 正则提取
## 3 现状事实
（全部实查，开工自行复核）
- 键构造：`tools/gdstyle_gate.py:82`（引文见上）；判定段 `:103-111` 只做 `keys - base` 差集判 NEW
- `--refresh` 现状：`tools/gdstyle_gate.py:84-92`——直接覆盖写基线、零对账输出；头注 `:11-13` 自述「基线键＝文件|规则|消息 三元组」
- 基线：`tools/gdstyle_baseline.txt` 241 行（2 行头注＋239 条），行格式＝`文件|规则|消息全文` 逐字存原句
- 调用链：`tools/run_all_gates.sh:251`（09 静态扫描段）→ `game/tests/static_scan.sh:247` → `tools/gdstyle_gate.py`；static_scan.sh `:239-246` 段头注描述三元组口径；`game/tests/README.md:64` 速查表 S13 行同口径。`tools/run_all_gates.sh` 全文无 S13 直述（待办条目预计改动面所写「run_all_gates.sh 头注随动」据此订正为 static_scan.sh 头注）
- master 尖 12 条假新增（2026-10-25 闸输出原样）：`adventure_runner.gd` 5 条（分支 11／类变量 42／文件 1051 行／`_start_current_level` 53 行／`resume_adventure` 108 行）＋`config_db_cross_validator.gd` 4 条（`cross_validate`：分支 21／107 行／局部变量 24／嵌套 5）＋`level_runner.gd` 2 条（类变量 38／`start_level_external` 参数 7）＋`main.gd` 1 条（1507 行）
- 239 条旧基线对账（写卡会话差集脚本实测）：222 条现键仍命中＋12 条漂移旧值（即上列 12 条的前身，如 `resume_adventure' has 10 branches`、`cross_validate' is 159 lines`）＋5 条已还真债（`level_runner` 文件 1013 行、`level_table.gd` `_validate_graph` 3 条＋`_validate_level_nodes` 1 条——迭代 35 当场拆四段修掉）
- 刷新后基线应＝234 条：当前 234 条命中的身份全部能在旧基线中找到同身份；其中 3 条较登记值恶化（`resume_adventure` 分支 10→11、行数 104→108；`adventure_runner` 文件 1050→1051）、9 条改善（其余漂移全为改小，如 `_start_current_level` 55→53、`cross_validate` 159→107）
- 消息形态实证（数值提取依据）：函数级五规则消息均含 `function '名字'`＋当前值＋`(max N)`（行数／分支／局部变量／参数／嵌套）；类级 `class has N variables (max 15)` 与文件级 `file is N lines long (max 1000)` 无名字
## 4 设计契约（违反即返工）
- 🔴 身份键＝文件|规则|函数名：函数名从消息提取 `function '([^']+)'`；类级/文件级无名字条目退化为「文件|规则」；消息解析不出「当前值＋max 值」的条目退化为现行「文件|规则|消息全文」键（保守路径：任何文本变化即新违规）。基线文件行格式不变（仍存原消息全文——保持可人读、登记值可解析）
- 🔴 恶化判据 X=0（2026-10-25 用户裁）：同身份「当前值＞基线登记值」→ 判 WORSE 红；当前值≤登记值＝基线内绿（改善可打印计数，禁止判红）
- 🔴 `--refresh` 对账自检：刷新时打印旧→新条数＋逐条「新登记／消失」清单；新条数＜旧条数×0.8 或旧基线文件缺失 → 拒绝写盘、退出非零，除非显式 `--allow-shrink`；闸正常判定路径零写基线文件；`--refresh` 仍只允许人工发起
- 🔴 禁动口径面：gdstyle.toml 规则与阈值、扫描面三目录（game/core、game/data、game/presentation）、钉版 v0.4.0 一律不动；12 条假新增涉及的 game/ 源文件零改动（它们的数字漂移是合法编辑的结果，不是缺陷）
## 5 范围边界
做：`gdstyle_gate.py` 三段改造（键构造／判定／refresh）＋自身头注；基线重生成；`static_scan.sh:239-246` 与 `game/tests/README.md:64` 两处文案随动。
不做（去向）：
- 不还 234 条存量债——免名单继续豁免，还债属后续迭代批按卡处理
- 不新增 python 单测件——tools/ 下 39 个 .py 闸件各自独立、无单测先例，验收走撤销证明，闸件自身即断言载体；若日后要求持久回归件，登记待办清单再议
- 不动 `run_all_gates.sh`（实测全文无 S13 直述，无需随动）
- 不处理其他闸（S6/S7/S8 落地等另有条目）
## 6 关联文档同步面
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| `game/tests/static_scan.sh:239-246` | S13 段头注自述「文件|规则|消息 三元组……基线外新违规才红」 | 批内直改（game/tests/ 属本批改动面） |
| `game/tests/README.md:64` | 速查表 S13 行「存量基线外新违规才红」 | 批内直改（同上） |
| `tools/gdstyle_gate.py:11-13` | 闸件头注自述三元组键 | 批内直改（本批主改文件自身头注） |
| `待办清单.md` S13 条目 | 状态推进「已写卡」→ 批完结整条退役 | 流水线状态机推进（写卡段回写、批后收尾退役），实现批禁顺手改 |
design/ 全树对 gdstyle/S13 零提及（2026-10-25 grep 实证）→ 本批无设计文档反哺点，反哺点清单如实写零条。
## 7 文件结构图与落位预检
### 7.1 文件结构图
| 文件 | 职责 | 行为改动 |
|---|---|---|
| `tools/gdstyle_gate.py` | 闸件本体：键构造段改稳定身份键＋数值解析（:77-90 区域）；判定段加 WORSE 分支（:103-111 区域）；refresh 段加对账与骤降守卫（:84-92 区域）；头注随动（:11-13） | 行为改动——对照表 R1–R6 |
| `tools/gdstyle_baseline.txt` | 存量基线数据件，`--refresh` 重生成 239→234 条 | 非行为改动（数据件重排）——R7 验收 |
| `game/tests/static_scan.sh` | S13 调用段头注文案随动（:239-246） | 非行为改动——R8 |
| `game/tests/README.md` | 速查表 S13 行文案随动（:64） | 非行为改动——R8 |
### 7.2 落位与可复用性预检
- 复用面：本批零新增文件；闸件内新增两个纯函数（`build_identity`／`parse_metric`）——tools/ 39 个 .py 无共享解析模块（无 common/util 件，闸件自含是仓库现行形态），无既有件可复用
- 唯一面：身份键构造与恶化比对只落 `gdstyle_gate.py` 一处；static_scan.sh 与 README 的文案只述口径、禁止复写规则细节（口径唯一出处＝闸件头注）；基线登记值唯一事实源＝基线行内消息文本
- 分层与交互面：纯 python 闸件，零游戏层交互；调用链＝run_all_gates.sh（代码域档 09 段）→ static_scan.sh:247 → gdstyle_gate.py → gdstyle.exe（GDSTYLE_BIN 可覆盖）→ 基线读写；正常判定路径只读基线，唯 `--refresh` 写
## 8 任务卡
### T0 身份键与恶化判据（估时 0.2 工作日）
- 取用：无（首卡）
- 产出：`parse_metric(message: str) -> tuple[int, int] | None`（当前值与 max 值，解析不出返回 None）；`build_identity(file_path: str, rule: str, message: str) -> str`（稳定身份键，含两级退化）；判定输出新增 WORSE 行与改善计数（T2 与验收依赖）
步骤：
- [ ] 在 `gdstyle_gate.py` 落 `parse_metric` 与 `build_identity`（签名见产出块，落点＝键构造段 :77-90 区域），两级退化路径齐备：无函数名退化「文件|规则」、解析不出数值退化全文键
- [ ] 判定段改为身份比对：基线行解析出身份与登记值 → 基线外身份判 NEW（现行语义不变）；基线内身份且当前值＞登记值判 WORSE；≤登记值判绿并计改善条数
- [ ] 闸件头注 `:11-13` 随动改写（身份键口径＋恶化判据＋退化路径）
- [ ] 窄确认：`PYTHONIOENCODING=utf-8 python tools/gdstyle_gate.py` → 必须得到「基线外新违规 0 条」＋ WORSE 恰 3 条（`resume_adventure` 分支 11>10、`resume_adventure` 行数 108>104、`adventure_runner` 文件 1051>1050）＋退出码 1（基线未刷新前恶化在红是预期态）；数字不符＝L3 停机
### T1 `--refresh` 对账与骤降守卫（估时 0.15 工作日）
- 取用：基线行格式约定（＝现行「文件|规则|消息全文」，T0 不改格式）
- 产出：`--refresh` 对账输出（旧→新条数＋逐条新登记/消失清单）；骤降守卫（新＜旧×0.8 或旧基线缺失 → 拒绝；`--allow-shrink` 放行）
步骤：
- [ ] refresh 段加对账：与旧基线逐行差集，打印新登记/消失两向清单与条数
- [ ] 加骤降守卫与 `--allow-shrink` 参数（用法说明行随动；拒绝状态下基线文件保持不变）
- [ ] 窄确认（夹具）：临时 stub（GDSTYLE_BIN 指向一个应答 `--version` 为 0.4.0、扫描输出仅 1 条固定 JSON 的脚本）跑 `--refresh` → 拒绝、退出非零、`git diff` 基线为空；加 `--allow-shrink` → 写盘且对账打印「新登记 1／消失 239」级清单；`git checkout -- tools/gdstyle_baseline.txt` 还原（stub 为临时件，禁止入库）
### T2 基线重生成＋文案随动＋产出物落位（估时 0.15 工作日）
- 取用：T0 判定逻辑与预期读数；T1 refresh 对账
- 产出：基线 234 条落盘；两处文案；三份产出物
步骤：
- [ ] 正式刷新：`PYTHONIOENCODING=utf-8 python tools/gdstyle_gate.py --refresh` → 对账必须为「新登记 12／消失 17／总条数 239→234」；不符＝L3 停机
- [ ] 窄确认：`python tools/gdstyle_gate.py` → 退出码 0
- [ ] 文案随动：`static_scan.sh:239-246` 头注与 `game/tests/README.md:64` 行（口径＝稳定身份键＋恶化判据＋对账自检；禁止复写规则细节）
- [ ] 里程碑步：按改动域选档跑全套闸（本批只碰 tools/ 与 game/tests/ → 代码域档）全绿
- [ ] 验收对照表 R1–R8 逐条执行，撤销证明记录（变更点／命令／红输出摘要／还原结论）落实现报告
- [ ] 产出物落位：`reports/S13基线键治本-实现报告-<日期>.md`（含对账留档与撤销证明记录）、`reports/S13基线键治本-代拍板追认单-<日期>.md`、`reports/S13基线键治本-反哺点清单-<日期>.md`（零 design/ 反哺点＋同步面四条去向闭环）——三份齐方算本卡完结
## 9 验证闸（改动—验收对照表）
证明口径＝撤销证明（2026-10-24 用户裁定）：变更被测面（回退改动段或更换基线夹具）→ 跑最窄闸 → 对应断言必须红 → 还原复绿。
| # | 需求点 | 改动（文件/行为） | 验收测试 | 层级 | 真实入口 | 撤销证明 |
|---|---|---|---|---|---|---|
| R1 | 数字漂移禁止再冒新违规 | gdstyle_gate.py 键构造改 build_identity | 刷新后闸跑「基线外新违规 0」 | 闸 | `python tools/gdstyle_gate.py` | 回退 T0 键构造改动段 → 12 条 NEW 复现红，还原复绿 |
| R2 | 名单外新违规仍必红 | 同上（身份匹配依赖基线在场） | 临时删基线一行无漂移条目（action_economy 类变量行）→ 该条 NEW 红、退出 1；还原复绿 | 闸 | 同上 | 删行夹具复红/还原复绿；回退 T0 改动段后同夹具仍红＝拦截力保持的对照 |
| R3 | 恶化必红（X=0） | 判定段新增 WORSE 分支 | 临时把基线 `resume_adventure` 行数行的登记值 108 改 104 → WORSE 红、退出 1；还原复绿 | 闸 | 同上 | 回退 WORSE 判据改动段 → 同夹具不再红 |
| R4 | 改善禁止判红 | 同判定段 | T0 窄确认输出中 `_start_current_level`（55→53）与 `cross_validate` 四条等 9 条无 NEW 无 WORSE | 闸 | 同上 | 回退 T0 改动段后这 9 条变 NEW 红＝改善判定系于 T0 |
| R5 | 骤降守卫＋对账 | refresh 段 | stub 夹具：`--refresh` 拒绝且基线 git diff 为空；`--allow-shrink` 放行并打印两向清单 | 闸 | `GDSTYLE_BIN=<stub> python tools/gdstyle_gate.py --refresh` | 回退守卫改动段 → 同夹具直接写盘（不再拒绝） |
| R6 | 判定路径零写基线 | 判定段无写盘调用 | 跑闸后 `git diff --stat tools/gdstyle_baseline.txt` 为空 | 闸 | `python tools/gdstyle_gate.py` | 结构性（判定段零写调用，代码审读＋行为验证双证） |
| R7 | 基线重排 234 条 | `--refresh` 正式跑 | wc -l＝236（2 行头注＋234 条）＋对账「新 12／失 17」 | 闸 | `--refresh` | `git checkout` 基线 → 闸回到 WORSE 3 红态（绿态确实来自 234 条新基线的互证） |
| R8 | 文案两处随动 | static_scan.sh:239-246＋README:64 | 人工核对与闸件口径一致，代码域档 09 段跑绿 | 文档面 | 按改动域选档跑闸 | 非行为改动，人工核对兜底 |
测试削弱申报：本批不删不放宽任何既有断言（闸自身判定逻辑更换内核，判据强度只升不降：NEW 拦截保持＋新增 WORSE）。
独立验收审计：审计入口＝未参与实现的会话按本表逐条抽查撤销证明记录；报告落 `reports/S13基线键治本-验收审计-<日期>.md`，未过禁合并。
## 10 异常分级
- L1 自救：对账/计数行的打印格式、排序、措辞问题——自助修
- L2 记录继续：未知规则消息形态触发全文键退化路径（设计内行为）——记进实现报告继续
- L3 停机呈报：任何窄确认预期数字不符（T0 非「NEW 0／WORSE 3」、T1 守卫未拒、T2 对账非「新 12／失 17／234 条」）——停机写呈报等用户
## 11 代拍板白名单
- 正则具体写法与转义细节（`function '([^']+)'`、当前值/max 值提取的容错）
- WORSE／改善／对账各行的输出措辞与排序
- 头注与 README 行的具体措辞（语义与判据不变）
- stub 夹具脚本的实现形态（临时件，禁止入库）
超出以上范围＝呈报，禁自行拍板。
## 12 待裁点
零待裁点，开工门＝U0。四点已于 2026-10-25 用户拍板（全案并列与淘汰依据留档）：
1. 键形态＝**B 稳定身份键**（淘汰 A 数字规范化——104→300 行的恶化被一并放过；淘汰 C 结构化输出——钉版二进制 JSON 无指标字段已实证，fork 超本批规模）
2. 恶化判据＝**超登记值即红，X=0 不分规则**（淘汰 20% 宽容量——留温水通道、登记值缓慢失真；淘汰分规则给值——多一套参数面要维护）
3. 存量处置＝**本批治本＋批内人工刷新**（淘汰只刷新不改键——下一批再动这些文件必然重演；淘汰先冻结 S13 段——防线空窗＋二次批成本）
4. 刷新自检＝**加对账＋骤降守卫**（淘汰不加、仅靠人工发起纪律——误跑一次即把新债静默洗进基线）
reports/需求卡片-S9类型闸正则修复批-2026-10-24.md
-177
View File
@@ -1,177 +0,0 @@
# 需求卡片：S9 类型闸正则修复批（R2 恒零命中＋static 漏网＋跨行签名盲区·存量归零）
- 版本：**v1.2**（2026-10-24 v1.0 成文→2026-10-25 grilling 第一轮修订 v1.1〔两阻断＋三应修折入〕→第二轮复核**通过**（B-1 定界链经独立核实成立：iter36 禁令文＋gdstyle 禁令后在库先例 01774323＋登记口径三证据齐），一条建议级修正折入定稿；复核结论见 §12）
- 来源：[待办清单](../待办清单.md)「S9 类型闸正则失灵修复——R2 恒零命中＋static 函数漏网」（2026-10-24 登记，来源=审计发现，设计面=工程直入，状态=待写卡＋已写卡）（唯一事实源：工程直入证据指认＝审计报告 [reports/审计-game代码结构审查-2026-10-24.md](审计-game代码结构审查-2026-10-24.md) §二 C1〔已独立复现〕＋本写卡会话逐处实查〔本卡 §3〕；规约依据＝[test-conventions](../design/engineering/test-conventions.md) §8.4〔一切改动的撤销证明义务〕＋2026-10-24 用户全项目 P0 禁令〔变异类测试全项目禁用、闸件改动无豁免——见 §4 契约 3 与 D4〕）
- 归属：`tools/audit_type_hints.py`（正则修复）＋ `game/core/`、`game/presentation/` 存量注解/豁免补齐（闸件批，**非迭代批**——gdstyle 批同款执行形态）
- 排期：非迭代批不占迭代号，独立 worktree 批；估时 ≈0.75–1 工作日
- 开工门：U0（用户发令）＋ grilling 复核门过（§12）；与卡①先后皆可（§0）
## 0. 前置依赖与并行性
- **第〇步核对（2026-10-24 写卡会话）**：来源条目设计面=工程直入、状态=待写卡，条目现状带行号级证据（审计 §二 C1，正则两洞经 python 逐条对拍独立复现）→ **放行写卡**。
- **与卡①（game 行为缺陷定点修批，同批写卡）**：零 hunk 交叠（grilling 实查确认：main.gd:565 vs :712/:1486、level_runner:632 vs :779/:895、unit_container:275 vs :55/:257/:270 皆同文件不同 hunk）；卡① d18 已替本批消掉 `board_view.gd:998` 一件存量红——本批 T0 存量清点以**本批开工时盘面**为准（两卡先后皆可；若本批先行，卡①新增代码须全类型，其卡 §0 已注记）。
- **与 gdstyle S13（2026-10-24 已落地，commit 01774323/8cdeb180）**：gdstyle 配置只开 quality/*、format/naming/order 全关——与 S9 类型面零重叠（其条目预告口径已兑现）；本批产品码注解改动落在 S13 扫描面，禁产生基线外新违规。
- **改动域**：本批混触 `tools/`（文档域路径）与 `game/`（代码域路径）——批末闸档按 `tools/run_all_gates.sh` 自身域划分判定执行（域划分唯一出处＝脚本头注 :10-15；卡内不另列清单）；闸件自身改动的质量义务＝撤销证明（§4 契约 3／§7 T2；2026-10-24 用户全项目禁令，闸件改动无豁免）。
## 1. 目标与完成定义
**目标**：修复 `audit_type_hints.py` 的 `FUNC_DECL` 识别面三个洞，使 R2/R3 对「无返回类型带 `:` 尾的声明」「`static ` 前缀函数」「参数表折行的跨行签名」恢复命中能力；随后把浮出的全部存量红清零（补类型注解优先、`# type-hint: ignore` 带理由豁免兜底），闸退出码归 0；闸改动配撤销证明（test-conventions §8.4）。
**改动单元清单**（钉值表，🔴 契约 1）：
| # | 位置 | 现状（实查） | 改法 |
|---|---|---|---|
| g1 | `tools/audit_type_hints.py:25` `FUNC_DECL` | 三洞：①正则要求 `)` 后只跟 `->`/注释/行尾——无返回类型声明按 GDScript 语法必然以 `:` 结尾，**R2 目标形态 100% 失配**（R2 上线起恒零命中恒绿）；②`^(\s*)func` 不认 `static ` 前缀——static 函数 R2/R3 双漏；③**逐行匹配不认参数表折行**（`\((.*)\)` 不能跨行）——首行无闭括号的跨行签名永不进入扫描面（grilling 静态证明：实证址 hud_presenter 不修此洞则永不浮出） | 三洞修复：接受 `:` 尾形态（返回类型组与 `:` 尾并存）；声明头认 `static ` 前缀；**续行拼接预处理**（声明行括号不平衡时并入续行直至平衡再匹配——写卡会话发现的第三洞，超出审计 C1 两洞原文，§11 呈报）。规则语义（R1/R2/R3 判据、`_init` 豁免、`# type-hint: ignore` 行级豁免）零变化 |
| g2 | 存量红清零（浮出即清） | 审计实证存量（闸当前退出码 0 全绿）：`game/core/level_runner.gd:632`（`current_battle()` 无 `->`）、`game/core/attunement.gd:10`（`static func slots(db, save)`）、`game/presentation/main.gd:565`（`build_adventure_params` 两参）、`game/presentation/hud_presenter.gd:12-13`（refresh 跨行签名内 untyped 参——**行号订正**：审计与 v1.0 写 :10-11 实为注释行）、`game/core/reward_economy.gd:104/119/131/146`（query_identity/query_full_snapshot 等无 `->`）、`game/core/unit_container.gd:275`（`default_target()`）；本会话补证 `game/presentation/tune_sim_controller.gd:24`（`func _autoplay():` 无 `->` 返回值） | T0 修复后全量清点红清单（实证址为已知下限，非全集）→ 逐处补返回类型/参数类型注解；确不适型处 `# type-hint: ignore`＋行内理由；清零后 `python tools/audit_type_hints.py` 退出码 0 |
**完成定义**（全部满足才算本批完成）：
1. g1 三洞修复落地，规则语义零变化（R1 用独立正则 R1A/R1B 不受影响——T0 记改前 R1 读数、T2 对拍同值）；
2. g2 存量红全量清点并归零：退出码 0、逐处红清单与处置（注解/豁免＋理由）成表落实现报告；
3. 撤销证明记录齐（§7 T2——闸件改动的拦截钉面自证）；撤销后仍绿＝断言没钉在这个改动上，判缺漏；
4. 批末按 `run_all_gates.sh` 域口径选档全绿（S9 段 PASS 归零；S13 基线零新增）＋改前改后读数对拍；产出物写齐（T3）。
## 2. 设计事实源
| # | 出处 | 取用条款 |
|---|---|---|
| D1 | 工程直入证据指认＝审计报告 §二 C1（正则行为经 python 逐条对拍独立复现；实证存量清单）＋本写卡会话实查（§3） | 两洞机理与存量下限 |
| D2 | [test-conventions](../design/engineering/test-conventions.md) §8.4 | 闸机判据改写必须配撤销证明钉住改动：只撤销该判据改动→最窄闸见红→精确还原→复绿记录——**gdstyle 闸件批在库先例**（commit 01774323「重复 load 红令→还原绿」同款形态） |
| D3 | [architecture](../design/engineering/architecture/architecture.md) 测试与质量域节 S9 行＋static_scan 头注 | S9 载体＝`tools/audit_type_hints.py`（R1/R2/R3 判据文字＝现行规则语义，本批零变化）；「规则扫描面为空＝恒绿」静默失效模式自警在案 |
| D4 | 2026-10-24 用户全项目 P0 禁令（变异类测试全项目禁用，**闸件改动无豁免**；一切验收只走撤销证明） | 本卡一切验证面（含闸件判据改动）一律撤销证明：只撤销该改动→最窄闸见红→`git checkout` 精确还原→复绿记录；撤销后仍绿＝判据没钉在改动上，判缺漏。旧「闸件豁免」定界句作废 |
| D5 | [code-conventions](../design/engineering/code-conventions.md) §4（语言纪律——类型闸为其机器闸） | 注解补齐的产品面纪律依据 |
## 3. 现状事实（2026-10-24 写卡会话实查＋2026-10-25 grilling 独立补查；开工日 T0 复核）
| # | 事实 | 出处 |
|---|---|---|
| G1 | `FUNC_DECL = re.compile(r"^(\s*)func\s+(_?\w+)\s*\((.*)\)\s*(->\s*.+)?\s*(#.*)?$")`——①无返回类型声明（`func f():` 形态）不匹配（`:` 不在允许尾集）→ R2 体扫描对该形态永不启动；②`static func` 头不匹配 → static 函数 R2/R3 双漏；③逐行匹配，参数表折行（首行无闭括号）永不匹配——**grilling 静态证明**：实证址 hud_presenter.gd:12-13（static 前缀＋折行双形态）不修第三洞则永不浮出 | `tools/audit_type_hints.py:25`；`game/presentation/hud_presenter.gd:12-13` |
| G2 | R2 判据链：`FUNC_DECL.match` → 无 ret 且非 `_init` → 收集更深缩进连续体 → `RETURN_VALUE` 命中即红；R3：参数按 `PARAM_SPLIT` 拆分逐参查 `:`；`_init` 参数豁免；行内 `# type-hint: ignore` 整行跳过（:43-44）；R1 用独立正则（R1A/R1B）与 FUNC_DECL 无关——带 `->` 的普通函数声明现行确在命中面（`->\s*.+` 贪婪吞尾） | `tools/audit_type_hints.py:22-27/42-74` |
| G3 | 实证存量（审计列＋本会话与 grilling 双重抽核形态一致）：`level_runner.gd:632`／`attunement.gd:10`／`main.gd:565`（static 洞）；`reward_economy.gd:104/119/131/146`／`unit_container.gd:275`（`:` 尾洞）；`hud_presenter.gd:12-13`（static＋折行——第三洞唯一实证址）；`tune_sim_controller.gd:24`（`:` 尾洞，本会话补证）。grilling 独立判定：两洞修复后除 hud_presenter 外全部浮出，hud_presenter 须第三洞 | 上列 file:line |
| G4 | 既有豁免先例：`board_generator.gd:281/331` 行内 `# type-hint: ignore（同 generate——测量面 stub 注入）`——豁免带理由的格式先例 | `game/core/board_generator.gd:281/331` |
| G5 | 闸机承载：static_scan.sh S9 段直跑 `python tools/audit_type_hints.py`（fail 聚合）；闸头注自述三条规则与白名单——g1 修复后头注规则语义描述不变（实现到位非规则增删）。**S13 gdstyle 段已在役**（static_scan.sh 新增段，01774323）——本批产品码注解改动须 S13 基线零新增 | `game/tests/static_scan.sh` S9/S13 段；`tools/audit_type_hints.py:3-14` |
| G6 | 闸现状＝退出码 0 全绿（R1/R2/R3 现行命中皆零——「R1/R3 仍有命中能力」指判据可达非在册命中，G2）；audit_type_hints.py 内无逐规则零命中自检（static_scan 的 require_scan_face 只查扫描面文件数）——本批 g1 修复后，红清单浮出本身即扫描面非空的实证 | `python tools/audit_type_hints.py` 现状读数；`game/tests/static_scan.sh:27-36` |
## 4. 设计契约（红线，违反 = L3 停机呈报）
🔴 **契约 1 · 规则语义零变化**：g1 只修识别面到位——R1/R2/R3 判据文字、`_init` 豁免、`# type-hint: ignore` 白名单、扫描面（game/core+game/data+game/presentation）、退出码协议全部不变；第三洞（续行拼接）是实现面扩展非规则增删（§11 呈报）；新洞再发现走 L3 呈报，禁批内自裁扩面。
🔴 **契约 2 · 存量清零双通道纪律**：补类型注解优先（产品码可注解处一律注解——duck-typed 注入面如 `db_ref`/`panel_ref` 可注真实类型或以 `# type-hint: ignore（理由）` 豁免）；每处豁免行内带理由（G4 格式）；禁用「删参数/改签名」替代注解（那是行为改动，越本批权——本批产品码面**零行为差**，与 P0 令的定界依据）。
🔴 **契约 3 · 撤销证明义务（闸件改动）**：g1 为改写闸机判据——撤销证明记录齐（§7 T2，gdstyle 批同款形态），撤销后仍绿＝「断言未钉在改动上」判缺漏，不得写「已验收」；**回退实验只在闸件与本批注解面上做**（回退该判据改动→闸红→还原），禁在生产行为面上做。
🔴 **契约 4 · 实证址全覆盖**：T1 清点后 G3 所列实证址（含 hud_presenter:12-13 与 tune_sim_controller:24）必须全部出现在红清单或已注解命中——任一实证址未浮出即 L3 停机呈报（第三洞拼接实现有缺陷的第一信号），禁静默放过。
## 5. 范围边界
**做**：g1 三洞＋g2 存量清零＋撤销证明＋产出物。
**不做**（明示去向）：
- 第四类新洞（如 lambda 函数体、多行返回类型）——本批三洞为审计 C1 两洞＋写卡会话静态证明必需的第三洞；再有发现走 L3 呈报；
- S6/S7/S8 落地——条目③整条冻结待④（2026-10-24 用户裁）；
- gdstyle 引入——已另行落地（S13，8cdeb180），本批零触碰其配置与基线（仅产品码改动遵守基线零新增）；
- 顺带改任何产品码行为（注解与豁免注释除外——GDScript 类型注解零运行时行为差）。
## 6. 关联文档同步面
> 本批是闸件批（非迭代批），可写面＝`tools/`＋`game/` 注解＋`reports/`；`design/` 与根规则文件零触碰。
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| [architecture](../design/engineering/architecture/architecture.md) 测试与质量域节 S9 行 | 「S9 在位」陈述不变（修复是实现到位非规则增删）——写卡会话核对该节无「正则形态」级陈述 | 无关联文档（查讫） |
| [test-conventions](../design/engineering/test-conventions.md) §6（旧条款） | 规则文本修正已由 2026-10-24 文档批完成——§6 退役、验收一律撤销证明（§8.4），闸件改动无豁免 | 已销号（随禁令落地，无需再裁） |
| `game/tests/README.md` 工具速查表 audit_type_hints 行 | 描述为规则语义级则零改动（T0 核） | 无关联文档（预期查讫，T0 复核） |
| `tools/audit_type_hints.py` 头注 | 规则语义未变零改动；若头注含正则形态级描述则随 g1 订正（T0 核） | 实施本体（可写） |
## 7. 任务卡
> 估时按 Claude 工作日口径；回归措辞：里程碑步出口跑一次全套闸；波内修复只做最窄确认。
### 卡前 · 文件结构图
| 文件 | 职责 | 行为改动 |
|---|---|---|
| `tools/audit_type_hints.py` | g1 三洞修复（复用既有·修改） | 闸件改动 → wg1 |
| `game/core/*.gd`、`game/presentation/*.gd` 存量位点 | g2 注解/豁免补齐（复用既有·修改；位点全集＝T1 清点） | 非行为改动（注解面）→ wg2 |
| `reports/实现报告-S9类型闸正则修复批-<完成日>.md` 等 | 产出物落位 | 非行为改动 → wg3 |
### 接口块
- g1 修复后 `FUNC_DECL` 行为规格（断言与撤销证明引用以此为准）：①`func f():`（无返回类型 `:` 尾）进入 R2/R3 扫描面；②`static func f(...)` 同普通函数进入；③参数表折行（首行 `(` 未闭合）经续行拼接后进入——hud_presenter:12-13 形态必浮出；④既有匹配面不回退（带 `->` 的普通函数声明改后仍匹配——T2③ 对拍）。
- 最窄闸＝`python tools/audit_type_hints.py`（直接退出码判读）；全套闸＝`tools/run_all_gates.sh` 按域划分选档（混触 `tools/`＋`game/`）。
### 落位与可复用性预检
- **g1 改 `FUNC_DECL` 与预拼一段**——复用面：闸内单点常量与逐行循环，无第二处正则（G2）；不新增文件不新增函数（续行拼接并入既有行循环）。唯一面：函数声明识别的唯一入口，修复即全局生效。分层：纯工具件零产品码依赖。
- **g2 注解补齐**——零新增文件零新增函数；豁免格式复用 G4 先例；为什么不另立白名单文件：现行行级豁免通道即成文白名单，增第二通道＝双源。
### T0 事实坐实＋改前读数（≈0.25d）
- [ ] 复核 §3 全部位点＋头注/README 是否含正则形态级描述＋跑改前读数（退出码 0、R1/R3 命中数对拍基线——G6 预期皆零）。可核查结果：改前读数表在案。
### T1 正则修复＋存量清点归零（≈0.25–0.5d）
- [ ] 实装 g1 三洞。可核查结果：临时注入探针（任选产品码文件加 `func _probe_r2():`＋`return 1`、`static func _probe_r3(a):`＋`return a`、跨行签名探针 `func _probe_ml(x,\n\ty):`＋体）→ `python tools/audit_type_hints.py` 输出含三探针红（探针随后删除——探针件随写随删，不留在库）。
- [ ] 全量清点红清单（G3 实证址齐全性核对——契约 4，hud_presenter:12-13 与 tune_sim_controller:24 必须浮出）→ 逐处注解/豁免 → 退出码 0。可核查结果：红清单处置表（file:line＋处置＋豁免理由）落实现报告。
### T2 撤销证明（≈0.25d）
- [ ] 四步撤销证明（test-conventions §8.4；最窄闸直跑；实验面＝闸件＋本批注解）：
①**`:` 尾修复半**：只回退 g1 的 `:` 尾修复半 → `_probe_r2` 探针不再命中（红清单消失）→ 还原——证明 R2 命中钉在该修复半上；
②**static 修复半**：单独回退 `static ` 前缀半 → `_probe_r3` 探针不再命中 → 还原；
③**既有面回归**：带 `->` 普通函数声明的匹配形态改前改后对拍同命中（防修复吞旧面）＋R1 读数改前改后同值（R1 独立正则不受影响的实证）——**「改前」载体写死**＝临时回退 g1 全量复现改前读数再还原；
④**真实存量红**：T1 红清单任取一址临时去掉新注解 → 该址复红 → 还原。
可核查结果：撤销点（文件:行）、闸输出摘要、还原结论四行记录表进实现报告。
- [ ] 验收步骤：全套闸按域划分选档跑一次，期望全绿（S9 段 PASS 归零读数＋S13 基线零新增）。
### T3 产出物落位卡（≈0.25d，末卡）
- [ ] 写齐产出物：`reports/实现报告-S9类型闸正则修复批-<完成日>.md`（两单元状态＋红清单处置表＋撤销证明记录表＋改前改后读数对拍）＋`reports/代拍板追认单-S9类型闸正则修复批-<完成日>.md`（§10 白名单内代拍项留痕）＋`reports/反哺点-S9类型闸正则修复批-<完成日>.md`（§6 各条落点——查讫项写「无」）。可核查结果：三文件在 `reports/` 且逐条有落点。
- [ ] 合并前置：**独立验收审计**（test-conventions §8.7——未参与实现的会话/子代理；只读本卡、实现报告、diff 与闸件，自跑最窄抽查不采信「已全绿」）完成且报告 `reports/S9类型闸正则修复批-验收审计-<完成日>.md` 逐行「通过」——审计面＝撤销证明记录表四步齐、实证址覆盖核对齐（含 hud_presenter/tune_sim 两补证址）、退出码 0 读数在案，缺任一项不通过；未通过不得合并。
**估时合计 ≈0.75–1d**。切分预案：无超软盒预挂面（实证址未浮出→L3 呈报即停，不吞工时）。
## 8. 验证闸
### 改动—验收对照表
| 需求点 | 改动 | 验收测试（名称＋落点） | 层级 | 真实入口 | 撤销证明 |
|---|---|---|---|---|---|
| wg1 `:` 尾洞 | `audit_type_hints.py:25` | 探针 `_probe_r2` 命中〔wg1〕T1 | 闸机 | 闸真实跑批路径（static_scan S9 段同命令） | T2① 单独回退 → 探针漏网 |
| wg1 static 洞 | 同行 `static ` 前缀 | 探针 `_probe_r3` 命中〔wg1〕T1 | 闸机 | 同上 | T2② 单独回退 → 探针漏网 |
| wg1 跨行洞 | 续行拼接预处 | 跨行探针 `_probe_ml` 命中＋hud_presenter:12-13 浮出〔wg1-ml〕T1 | 闸机 | 同上 | 回退拼接段 → 跨行探针与 hud_presenter 址双双漏网 |
| wg1 回归线 | 既有匹配面 | `->` 形态对拍＋R1 读数同值〔wg1-reg〕T2③ | 闸机 | 同上 | 对拍差异即红 |
| wg2 存量归零 | `game/` 各存量位点注解/豁免 | `python tools/audit_type_hints.py` 退出码 0〔wg2〕 | 闸机 | 同上 | T2④ 去注解 → 复红 |
| wg3 产出物 | T3 三份 | 件核对〔wg3〕 | — | — | 缺项红 |
**闸口径**：批末全套闸按 `run_all_gates.sh` 域划分选档（混触 `tools/`＋`game/`，域划分唯一出处＝脚本头注）；S9 段归零 PASS 为本批主判据。**测试削弱申报**：零（闸判据只收紧到位、未放宽任何规则；产品码改动全部为注解/注释零行为差）。
## 9. 异常分级
- **L1（自救）**：注解 vs 豁免的逐址取舍；探针注入的临时落位选择；续行拼接的实现细节（括号计数 vs 续行缩进判）。
- **L2（记录继续）**：存量清单超出实证址的量级波动（正负皆记）。
- **L3（停机呈报）**：任一实证址未浮出（拼接实现缺陷第一信号）；修复导致既有匹配面回退（T2③ 对拍红）；正则修复需触碰 R1 正则（超钉值表）；第四类新洞出现。
## 10. 代拍板白名单（超清单必呈报）
1. 逐址注解 or 豁免的取舍（豁免必须带行内理由）。
2. 探针注入的临时文件与清理时机。
3. 续行拼接的实现写法。
4. 提交切分与 worktree 分支命名。
## 11. 待裁点
**零待裁点，开工门=U0。**
三处灰色地带已推导定值（用户可否决，随 T3 反哺点呈报）：
- **第三洞（续行拼接）扩收**——超出审计 C1 两洞原文；依据＝hud_presenter 实证址不修则永不浮出、契约 4 九址全覆盖必然停机（grilling 静态证明）；备选「该址单行重排」淘汰依据＝格式迁就闸而非闸达意；备选「移出实证址按未覆盖呈报」淘汰依据＝明知的盲区留闸＝再养恒绿面。
- **闸件改动同样只走撤销证明（2026-10-24 用户全项目禁令，无豁免）**——旧「闸件豁免」定界作废；行为与闸件改动的验收口径统一为撤销证明（test-conventions §8.4），旧 §6 条款已随禁令退役。
- **存量清零以注解优先、豁免兜底**——依据＝code-conventions §4 类型纪律本意；备选「全豁免快速归零」淘汰依据＝闸修复后第一轮即全豁免＝把 S9 再养回恒绿摆设。
## 12. 自审六查与 grilling 复核记录
**自审六查（2026-10-24 写卡会话）**：①规格覆盖——g1/g2 挂 T0–T3、指到 wg1–wg3；②步骤扫描——一步一动作一可核查结果；③类型一致性——探针形态与 G1/G2 正则行为逐字对齐；④审查焦点＋改动覆盖——补挂：回归线对拍（T2③）、实证址全覆盖契约（契约 4，含两补证址）、豁免滥用防线（§11）；⑤篇幅比例——两单元小卡不膨体；⑥落位与复用——零新增文件，豁免复用 G4 先例、白名单单通道。
**grilling 第一轮复核记录（2026-10-25，独立子代理对抗复核）**：判回炉两阻断——B-1 验证面与 2026-10-24 P0 令冲突未呈裁；B-2 hud_presenter 跨行签名静态证明永不浮出、契约 4「九址全覆盖」＝预排必然停机。随同三应修（B-3 G6「R1 存量命中在役」失实——闸现状全绿零命中；B-4 hud_presenter 行号 :10-11→:12-13；B-5 tune_sim_controller:24 升实证）＋三建议（含域档引用脚本行号）。v1.1 折入：B-1 曾按当时在库证据拟定「闸件豁免」定界（gdstyle 先例 01774323）；**该定界后经用户 2026-10-24 全项目禁令推翻**——闸件改动无豁免，卡面验证义务已全量改写为撤销证明（D4/契约 3/T2 现行口径）；B-2 扩第三洞续行拼接（g1/契约 4/T1 探针/T2 对应全链落位，§11 呈报超出 C1 原文）；G3/G6 事实按 grilling 订正；域档引用钉脚本头注 :10-15。复核结论：两阻断闭合、三应修落位（v1.1）。
**grilling 第二轮复核记录（2026-10-25，同代理续核）**：总判**通过**——B-1 定界链经独立核实成立（①iter36 纪律变更段原文全域禁令无闸件豁免＝冲突真实；②commit 01774323 系 gdstyle 闸件批在库先例（同形态回退实验）；③gdstyle/S9 两条目登记原文同款口径——复核时点证据齐，B-1 当时撤回；**其定界结论后经用户 2026-10-24 全项目禁令最终裁定推翻**（禁令在后、口径以此为准）；B-2 第三洞全链落位（探针/契约 4/撤销证明联动）。余两条建议级：T2③ 改前载体写死（v1.2 已折入）、续行拼接后 R2 体收集含参数续行但无 return 故无害（实现期知晓项）。零阻断零应修，卡进可编排态。
reports/需求卡片-节点图换代收尾批-2026-10-25.md
-170
View File
@@ -1,170 +0,0 @@
# 需求卡片——节点图换代收尾批（宿主改名＋验证集清单重生成＋表尾叙事清偿）
- 批名：节点图换代收尾批｜日期：2026-10-25｜批次性质：迭代批（测试基建＋数据表注释面；改动面＝game/tests/＋game/data/＋tools/ → 代码域档）
- 估时：0.25–0.4 工作日（T0 0.1／T1 0.05／T2 0.1／T3 0.05；软盒上限 0.4，超出按异常分级 L3 停机呈报）
- 来源：待办清单三条工程直入条目（均 2026-10-25 登记，来源=审计发现，设计面=工程直入）——「验证集清单快照重生成」「测试宿主改名 node_map_templates_test.gd」「level.tres 表尾注释含迭代叙事」。三件同源（迭代 35 卡② 断言面换代的收尾欠账）且第①件依赖第②件先行（清单重生成自动带新宿主路径），合一张卡执行
- 验收证明口径：按 2026-10-24 用户裁定，一切验收走撤销证明，不做变异类测试
## 1 目标与完成定义
**做什么**：四件——① 集成宿主改名 `game/tests/integration/node_map_templates_test.gd` → `node_map_determinism_test.gd`（manifest 登记行与文件内自引用字面量同批改，断言判据零改动）；② `tools/extract_checks.py` 两处小改（清单头注模板数据驱动化＋新增 `--carry-from` 回填列承接）；③ 用工具重生成 `game/tests/验证集清单.md`（缺省三宿主全量口径，同指纹行承接旧清单「白话释义／处置」两列）；④ `game/data/tables/level.tres:16` 表尾注释删迭代叙事词、保留去向事实句。
**完成定义**：验收对照表 R1–R7 全过＋按改动域选档跑闸全绿＋`reports/` 三份产出物（实现报告／代拍板追认单／反哺点清单）齐；待办清单三条目的整条删除归批后收尾段履行（实现批禁写根清单）。
## 2 设计事实源
工程直入证据指认（与三条待办条目一致，写卡会话 2026-10-25 在 master 尖实查复核）：
- `game/tests/run_all.gd:90`——manifest 登记行 `res://tests/integration/node_map_templates_test.gd`；宿主文件在位，文件内 4 处文件名自引用（:1 头注、:10 运行说明、:26 push_error 前缀、:31 finish 标签）
- `game/tests/验证集清单.md`——`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --diff`（缺省三宿主源）2026-10-25 实测：现提取 63 个源文件、清单 1067 条 vs 现提取 1544 条、消失 67／新增 539／标签字面变更 10 对／cond 字面变更 4 对，退出码 1；退役措辞实测 first_script 8 行（177/215/233/237/242/254/263/1168）、template_pick 3 行（138/882/1406）
- `game/data/tables/level.tres:16`——表尾注释「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出，历史查 git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档。」（两个留档工具实查在位）
- `game/tests/验证集清单.md:147/148`——#84/#85 两行（收束置位与幂等）指纹与现宿主 `node_map_templates_test.gd:110/112` 逐字一致，其「处置」列文本含旧宿主路径——承接不做映射则旧名随回填列进入新清单（grilling 复核 2026-10-25 指认）
## 3 现状事实
（全部实查，开工自行复核）
- 宿主与引用面：node_map_templates_test.gd 在 `game/tests/integration/`（.gd＋.uid 两件）；全仓引用＝`run_all.gd:90` 一处＋文件内自引用 4 处＋验证集清单行文 15 处（冻结列随 R3 重生成清偿；其中 #84/#85 两行的「处置」列文本会经承接进入新清单，须映射改名——见 T0/T2）；design/ 与 game/tests/README.md 零提及（grep 实证）；`tools/gdstyle_baseline.txt` 零条目（S13 扫描面只含产品码三目录，改名无基线耦合）
- 清单机制：`tools/extract_checks.py` 缺省源＝`game/tests/unit/**`＋`game/tests/integration/**`＋`game/tests/system_test.gd` 三宿主遍历；`--extract --force` 重生成（已存在拒写防误覆）；`render_list`（:329-369）头注模板写死批 B 叙事（标题「迁移参照物」与「批 B 基点实测 smoke_all.gd 调用点 1065 处」等句），直接重生成会把全部回填列抹成（待填）——实测当前清单 1067 行、0 行待填、白话释义/处置全部已回填
- 漂移构成：清单基点＝批 B 迁移对象（smoke_all 1065 处，提案 §五.7 明示「unit/integration 现役断言收录为后续可选项」）；新增 539＝批 B 未收录的既有套件断言＋迭代 35 卡② 换代新增（player_copy_sweep_test 等新宿主与 level_shop_economy 扩段等）；消失 67＋字面变更 14＝卡② 退役/改判的迁移面断言（first_script/template_pick 措辞行在其中）。承接理论值＝1067−67−14≈986 行，承接不上的新行≈558 行落（待填）
- level.tres 表尾：:14-15 两行为现行图源事实句（不动）；:16 一行含「随迭代 35 卡② 清出」迭代叙事。处置口径待办条目已裁：删迭代号、保留「旧 15 张模板池」「git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档」去向事实、表内数值零改动
## 4 设计契约（违反即返工）
- 🔴 宿主改名零判据改动：断言内容、检查条数、quiet 档位一律不动；只改文件名（.gd＋.uid 同迁）、manifest 路径行、文件内 4 处自引用字面量
- 🔴 清单冻结列只由机器提取：标签/cond/quiet/行号/序号禁手写改行；「白话释义／处置」两列＝同指纹承接旧行（指纹与 `entry_key` 同构：cond 折叠＋标签字面量＋后缀折叠），承接文本内的旧宿主文件名一律映射为新名（node_map_templates_test.gd→node_map_determinism_test.gd），承接不上的新行落（待填），禁止手工编造释义；重生成后 grep 清单 node_map_templates／first_script／template_pick 预期零命中（template_pick 若命中须全为反向断言）
- 🔴 头注模板数据驱动：标题与口径行由当次提取数据生成（基点 commit、源文件数、实测条数），禁止出现批次专名与写死计数
- 🔴 清单重生成后对账必须 PASS：`--diff`（缺省源）标签/cond/计数三对齐零差异
- 🔴 level.tres 只动 :16 注释文字，表内数值零改动（MC 零跑）
- 🔴 本批不删不改任何宿主断言判据（清单 67 行消失＝宿主侧已不存在断言的账面同步，非断言删除——测试削弱申报见 §9）
## 5 范围边界
做：上列四件＋工具与注释随动。
不做（去向）：
- 不回填新行白话释义（≈558 行；既有套件断言释义回填＝提案 §五.7 既定「后续可选项」，清单头注注明回填属后续维护即可；如需立项另登待办）
- 不动 `design/engineering/test-conventions.md` §8.3 维护锚的「迁移断言全体」描述句（清单改全量口径后该句失准——列反哺点呈报用户裁决，归文档批落文；本批保持不触 design/）
- 不动 game/tests/README.md（实测对本批三件零提及）
- 不动 run_all.gd:90 行尾注释的「批 B 自 smoke_all 迁入」字样（已知留存量，行级注释清偿如需另登待办）
- 不处理 game/.godot 编辑器缓存（改名后自刷新，不入 git）
- 不清偿 gdstyle/S6/S7/S8 等其他闸件族欠账（另有条目在册）
## 6 关联文档同步面
| 文档 | 关联点 | 同步义务 |
|---|---|---|
| design/engineering/test-conventions.md §8.3（:98） | 「验证集清单…迁移断言全体的冻结参照清单」描述句——清单改三宿主全量口径后「迁移断言全体」失准 | 反哺点清单呈报用户裁决，归文档批落文（本批不触 design/） |
| 待办清单.md 三条来源条目 | 状态推进＋批完结整条删除 | 写卡段回写「已写卡」＋编排段记「已编迭代 38」；批完结后由批后收尾段整条删除（实现批禁写根清单） |
## 7 文件结构图与落位预检
### 7.1 文件结构图
| 文件 | 职责 | 行为改动 |
|---|---|---|
| tools/extract_checks.py | 头注模板数据驱动（render_list :329-369 区域）＋`--carry-from` 承接（复用 parse_list 读旧清单，按 entry_key 同构指纹承接回填两列） | 行为改动——R4/R5/R6 |
| game/tests/integration/node_map_templates_test.gd → node_map_determinism_test.gd（＋.uid） | 模板时代遗留名退役；内容零改动 | 行为改动（装载路径）——R1/R2 |
| game/tests/run_all.gd:90 | manifest 路径行改指新名（行尾注释不动） | 行为改动——R1 |
| game/tests/验证集清单.md | 冻结列重生成＋回填列承接（数据件） | 非行为改动——R3/R4 |
| game/data/tables/level.tres:16 | 表尾注释叙事词清偿 | 非行为改动——R7 |
### 7.2 落位与可复用性预检
- 复用面：零新增文件；工具改造复用自身 `parse_list`／`entry_key`／`fold`（承接逻辑不另立解析）；改名复用既有宿主与 manifest 机制。工具新增一个 argparse 参数与一个承接函数，落点唯一＝extract_checks.py（grep 全仓无同职责第二实现）
- 唯一面：断言静态提取与清单生成/对账唯一落点＝extract_checks.py；宿主 manifest 唯一登记处＝run_all.gd；level 表尾注释唯一落点＝level.tres；清单头注口径唯一出处＝工具模板（README 禁复写）
- 分层与交互面：纯测试基建与数据件，零游戏层交互；装载链＝run_all_gates 02 段 → run_all.gd（manifest）→ 宿主；extract_checks.py 独立运行、不进任何闸（清单「不进任何闸」现状维持）
## 8 任务卡
### T0 工具两小改（估时 0.1 工作日）
- 取用：无（首卡）
- 产出：`render_list` 数据驱动头注（标题、基点 commit、源文件数、实测条数由当次数据生成）；`--carry-from <旧清单>`（--extract 模式参数；承接函数 `carry_cells(frozen_rows) -> dict[指纹, (白话释义, 处置)]`，指纹与 entry_key 同构；承接文本旧宿主文件名映射为新名）
步骤：
- [ ] 头注模板改数据驱动：删「批 B 基点实测 smoke_all.gd…1065 处」「迁移参照物」等批次专名与写死计数（模板存量「test-conventions §9.3 锚」错号一并改指 §8.3），标题改「验证集清单（断言快照·冻结）」语义；口径说明保留通用部分（双口径解释、单元格转义规则、维护义务指 test-conventions §8.3、「白话释义／处置」新行（待填）属后续维护——固定模板文案，生成后零手改）
- [ ] 落 `--carry-from`：按指纹承接旧清单行「白话释义／处置」两列（quiet 不承接，以现提取为准）；承接不上的行落（待填）
- [ ] 窄确认（不动正式清单）：`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --extract --out <临时件> --carry-from game/tests/验证集清单.md` → 头注含当前 `git rev-parse --short HEAD` 短哈希与实测 1544 条；抽 3 条未漂移行核对释义承接；`python tools/extract_checks.py --diff <临时件>` PASS
- [ ] 撤销证明 R5/R6 留档：回退头注模板段重试生成→批次专名句复现；回退承接段重试生成→承接计数 0（记录后还原，临时件禁止入库）
### T1 宿主改名（估时 0.05 工作日）
- 取用：无
- 产出：`res://tests/integration/node_map_determinism_test.gd`（.gd＋.uid 同迁，内容零改动）
步骤：
- [ ] 改名前基线：`"D:/code/godot/Godot_v4.7.2-stable_win64_console.exe" --headless --path game --script res://tests/integration/node_map_templates_test.gd` 直跑旧名 → 记录摘要行检查条数与 0 失败（R2 对拍基线）
- [ ] `git mv` 两件到 node_map_determinism_test.gd（.gd＋.uid）；文件内 4 处自引用字面量（:1/:10/:26/:31）换新名，其余零改动
- [ ] run_all.gd:90 路径改 `res://tests/integration/node_map_determinism_test.gd`（行尾注释不动）
- [ ] 孤立验证：同命令直跑新名 → 退出码 0、摘要行 0 失败、检查条数＝基线条数
- [ ] 撤销证明 R1 留档：仅回退 run_all.gd:90 一行 → 直跑 `--script res://tests/run_all.gd` 退出码非 0（宿主路径不存在；若引擎对缺路径宿主退 0 且输出无错误标记致不红＝L3 停机呈报）；还原复绿
### T2 清单重生成（估时 0.1 工作日）
- 取用：T0 工具（头注模板＋承接）；T1 新宿主名（重生成自动带新路径）
- 产出：现行口径验证集清单（1544 条、承接≈986 行回填列）
步骤：
- [ ] 备份旧清单到仓库外临时件 → `PYTHONIOENCODING=utf-8 python tools/extract_checks.py --extract --force --carry-from <临时备份>` 重生成
- [ ] 对账：`PYTHONIOENCODING=utf-8 python tools/extract_checks.py --diff game/tests/验证集清单.md`（缺省源）→ PASS 零差异、清单条数 1544
- [ ] 退役措辞与旧名核点：grep 清单 node_map_templates／first_script／template_pick → 预期零命中；template_pick 若命中须逐条判读为反向断言（断言旧键缺位类；现宿主唯一键名引用在 breakpoint_resume_test.gd:159 的 check_quiet 通道，提取器不收），非反向命中＝L3 停机；判读结果落实现报告
- [ ] 撤销证明 R3 留档：`git checkout game/tests/验证集清单.md` → `--diff` 复现 FAIL（消失 67／新增 539）→ 重生成还原复绿
### T3 表尾注释＋批末收尾（估时 0.05 工作日）
- 取用：T2 完成（批面定格）
- 产出：level.tres 表尾新注释；三份产出物
步骤：
- [ ] level.tres:16 改「旧 15 张模板池（3 关 × 5）已清出，历史查 git 提交史与 tools/t5_build_templates.py、t17_fanout2_rebuild.py 留档。」（删「随迭代 35 卡②」叙事段；表内零改动）
- [ ] 里程碑步：按改动域选档跑全套闸（本批只碰 game/ 与 tools/ → 代码域档）全绿
- [ ] 验收对照表 R1–R7 逐条执行，撤销证明记录（变更点／命令／红输出摘要／还原结论）落实现报告
- [ ] 产出物落位：`reports/iter38-实现报告-<日期>.md`（含承接计数、退役措辞枚举、直跑条数对拍）、`reports/iter38-代拍板追认单-<日期>.md`、`reports/iter38-反哺点清单-<日期>.md`（≥1 条：test-conventions §8.3 描述句随清单全量化失准）——三份齐方算本卡完结
## 9 验证闸（改动—验收对照表）
证明口径＝撤销证明（2026-10-24 用户裁定）：撤销该改动（回退对应 hunk）→ 跑最窄验证 → 对应断言必须红 → 还原复绿。
| # | 需求点 | 改动（文件/行为） | 验收测试 | 层级 | 真实入口 | 撤销证明 |
|---|---|---|---|---|---|---|
| R1 | 改名后 manifest 装载新宿主 | run_all.gd:90＋git mv | run_all 全宿主跑绿（全套闸 02 段） | 集成 | run_all.gd manifest 装载 | 仅回退 :90 一行→run_all 直跑红（路径不存在）；还原复绿 |
| R2 | 宿主内容零改动 | git mv 本体 | 直跑新名退出码 0、0 失败、条数＝改名前基线条数 | 集成 | `--script` 直跑宿主 | 结构性（git diff 仅文件名与 4 处字面量＋条数同值双证） |
| R3 | 清单与宿主同口径 | 验证集清单重生成 | `--diff`（缺省源）PASS 零差异、条数 1544 | 工具 | extract_checks.py --diff | `git checkout` 旧清单→`--diff` 复现 FAIL（消失 67／新增 539）→重生成还原 |
| R4 | 退役措辞与旧宿主名清偿 | 重生成＋承接映射 | grep 新清单 node_map_templates／first_script／template_pick 预期零命中；template_pick 若命中须全为反向断言并逐条枚举 | 文档面 | grep＋判读 | 回退 T0 承接映射段重生成→node_map_templates 2 格复现（#84/#85 处置列）→红→还原；判读部分人工核对兜底 |
| R5 | 头注数据驱动 | render_list 模板段 | 试生成头注含当前短哈希＋实测条数，零批次专名 | 工具 | `--out` 试生成＋grep | 回退模板段→重试生成→批次专名句复现 |
| R6 | 回填列承接 | --carry-from 段 | 承接计数≈986（以改前 `--diff` 读数 1067−67−14 为理论值）＋抽 3 行释义一致 | 工具 | 试生成＋抽查 | 回退承接段→重试生成→承接计数 0（全量待填） |
| R7 | 表尾叙事清偿 | level.tres:16 | 注释零「迭代」字样＋保留「15 张模板池」「留档」去向句；表加载随全套闸绿 | 文档面 | 人工核对＋闸兜底 | 非行为改动，人工核对兜底 |
测试削弱申报：本批不删不改任何宿主断言判据；清单消失 67 行＝宿主侧已不存在断言的账面同步，非断言删除。
独立验收审计：审计入口＝未参与实现的会话按本表逐条抽查撤销证明记录；报告落 `reports/iter38-验收审计-<日期>.md`，未过禁合并。
## 10 异常分级
- L1 自救：头注/注释措辞、表格排序、打印格式
- L2 记录继续：承接计数略低于理论值 986（字面变更 14 对按设计不承接；同指纹重复行折叠）；未知新行待填
- L3 停机呈报：重生成后 `--diff` 不 PASS／退役措辞命中含非反向断言／run_all 因改名红且非 manifest 行所致／直跑条数与基线不一致／任何撤销步未见红（含 R1 缺路径宿主不红）
## 11 代拍板白名单
- 新头注与标题具体措辞（语义＝断言快照·冻结·数据驱动）
- 承接指纹实现形态（与 entry_key 同构即可）与承接计数打印格式
- （待填）行头注说明句措辞
- level.tres 新注释句读法（语义钉死：删叙事保去向）
- 自引用字面量改写形式（保持既有注释风格）
- 旧清单备份临时件位置（仓库外，禁止入库）
超出以上范围＝呈报，禁自行拍板。
## 12 待裁点
零待裁点，开工门＝U0。两处路线选择依据留档（全案并列与淘汰依据）：
1. 清单路线＝**重生成**（淘汰「清单头注记」——test-conventions §8.3 维护锚〔2026-10-22 用户裁〕要求断言改动必须同步清单、清单没跟上的断言改动视同未完成；头注记等于宣告永久不同步，须先改该规则才能走，非本卡可裁）
2. 重生成口径＝**缺省三宿主全量**（淘汰迁移面显式 `--src` 清单——迁移宿主集合随断言重排漂移〔迭代 35 卡② 已在迁移宿主内整段重写并新落宿主〕，显式清单需人工维护且与缺省对账口径分叉；清单基点本就缺既有套件面〔提案 §五.7「后续可选项」〕，全量化一次到位；test-conventions §8.3「迁移断言全体」描述句随动列反哺点呈报）