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
This commit is contained in:
DKChan committed
1 parent
e20eb90d56
commit
9fdacdebeb
10 files changed
+39
-547
No files matched your search
@@ -57,8 +57,8 @@
|
||||
- **仓库根禁止设会话状态文件**（`active.md` 已废除）——现状看 roadmap「当前位」，待办看待办清单，过程看 git 提交信息，产出物看 `reports/`；任何文档禁止另设「当前状态快照」节，两处记同一件事必然漂移（细则见 doc-conventions 第 10 节）
|
||||
- 测试执行两入口铁规——只有迭代 loop 开发与用户点名两个触发入口；其余会话零测试，需测试支撑先请示并注明未跑测
|
||||
- 交付前验收 = 跑 `tools/run_all_gates.sh` **按改动域**全绿（唯一入口、唯一闸清单、唯一域划分，禁在文档另列）；合回 master 由 worktree-guard 按 diff 推域校验回执强制（process-conventions §3）
|
||||
- **两类批**——**迭代批**（代码实现，`/iter` 发射）：**禁写 `design/` 整个目录与两份根流程清单（`待办清单.md`/`体验验证清单.md`）**（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；批末只跑代码域闸。**非迭代批**（工具/规则/文档改动）：不占 roadmap 迭代号，按改动域跑闸。文档内容的落地走五段流水线相应段（文档设计段入口=doc-design 技能；登记条目格式由流水线闸强制）
|
||||
- 五段流水线铁律——一切工作按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点，流水线闸 `tools/pipeline_gate.py` 强制（已注册进 run_all_gates.sh 文档域）；实现段零裁断——卡片没写清=上游缺陷，停该卡退回上游，禁内联求裁（process-conventions §2，格式与状态机=doc-conventions §12）
|
||||
- **改动四类**——**需求改动**（游戏代码，含随逻辑写/改的测试代码）：唯一走「写需求卡片＋编入迭代批次」通道；迭代实现批禁写 `design/` 整个目录与两份根流程清单（`待办清单.md`/`体验验证清单.md`）（含新增/修改/删除），设计文档对它只读、是写测试与实现代码的输入依据；两份流程清单的条目状态只由流水线各段推进，实现批禁止顺手改；产出物只准写 `reports/`；批末只跑代码域闸。**工程改动**（tools/、闸件、模拟测量工具、纯测试维护——不改变游戏行为的配套代码）、**文档设计改动**、**美术素材改动**：不写需求卡片、不编迭代批次，登记在案后由用户发令直接修改，按改动域跑闸，完成即删条目；文档设计类写入走 doc-design 技能（登记条目格式由流水线闸强制）
|
||||
- 五段流水线铁律——**需求改动**（游戏代码）按「登记 → 文档设计／美术设计 → 写需求卡片 → 迭代编排 → 实现」五段推进，段间不自动流转、每段转进由用户发令；编入迭代的卡片必须设计闭合＋零待裁点——需求卡片任何工作量皆可写、皆可编入迭代，工作量限制只属迭代层（迭代估时总量 <5 个工作日＝「冻结待凑批」、不可开工）；流水线闸 `tools/pipeline_gate.py` 强制（已注册进 run_all_gates.sh 文档域）；实现段零裁断——卡片没写清=上游缺陷，停该卡退回上游，禁内联求裁（process-conventions §2，格式与状态机=doc-conventions §12）。工程／文档设计／美术素材三类改动不走写卡与编排段：登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目
|
||||
- MC/模拟：无数值改动零跑；档位硬闸见 `sim-data/README.md`「MC 采集档位表」，一档只能由用户发起
|
||||
- 闸机轮次纪律：新码先孤立验证 → 出红只跑红件最小单元 → 长批先最小参数试车 → 开工扫坑册（process-conventions §6）
|
||||
- **验收闭合**——每个需求点与每个行为改动都要有从真实入口进入的验收断言，撤销该改动能让对应断言变红；禁删断言/放宽阈值换绿；合回前独立验收审计未过则禁止合并（细则=test-conventions §8＋iter 技能第 5 步）
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。
|
||||
|
||||
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由非迭代批写入，禁 agent 自行增词。
|
||||
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由工程/文档设计改动批写入，禁 agent 自行增词。
|
||||
|
||||
## 5. 结构纪律
|
||||
|
||||
@@ -158,6 +158,7 @@
|
||||
美术轨：待美术设计 → 美术设计中 → 美术设计已闭合
|
||||
进入下游段（待写卡及之后）的前置条件——双轨：两个设计轨闭合段都在场；单轨：本轨闭合段在场
|
||||
下游共用序列：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除
|
||||
直改类（工程/文档设计/美术素材改动）：登记 → 待执行 → 完成即整条删除（经设计讨论的可前置闭合段，如「文档设计已闭合＋待执行」）
|
||||
单轨累积示例（已编迭代）：文档设计已闭合＋待美术设计＋已写卡＋已编迭代 2
|
||||
```
|
||||
|
||||
@@ -167,7 +168,8 @@
|
||||
|
||||
| 设计面 | 通道规则 |
|
||||
|---|---|
|
||||
| 工程直入 | 缺陷修复／工程债／测试基建／重构四类工程条目：登记即「待写卡」，凭现状里指认的证据跳过设计轨 |
|
||||
| 工程直入（需求性） | 缺陷修复／重构等改游戏行为的条目＝需求改动：登记即「待写卡」，凭现状里指认的证据跳过设计轨 |
|
||||
| 工程直入（工程性） | 工程债／测试基建／工具维护等不动游戏行为的配套条目＝工程改动：登记即「待执行」，用户发令直改，不走写卡 |
|
||||
| 反哺点专条 | 待裁决 → 已写入 → 删除 |
|
||||
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |
|
||||
|
||||
@@ -175,7 +177,7 @@
|
||||
|
||||
### 12.2 roadmap 迭代行格式
|
||||
|
||||
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。迭代行六列：
|
||||
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝冻结不可开工。迭代行六列：
|
||||
|
||||
```
|
||||
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
|
||||
@@ -184,10 +186,10 @@ roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭
|
||||
| 列 | 规则 |
|
||||
|---|---|
|
||||
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |
|
||||
| 状态 | 待开工 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |
|
||||
| 状态 | 待开工 ／ 冻结待凑批 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |
|
||||
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） |
|
||||
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 |
|
||||
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 或超过 20 均判红（硬下限/硬上限，2026-10-21 用户裁定：特批标记也不放行）；历史迭代不可考填「—」 |
|
||||
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 的迭代行状态必须为「冻结待凑批」（2026-10-25 两层模型：小卡可编入，迭代总量不足即冻结、禁止处待开工/进行中）；超过 20 判红（硬上限，特批标记也不放行）；历史迭代不可考填「—」 |
|
||||
| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」；已完成迭代只许存在路径或退役保留字、禁「—」 |
|
||||
|
||||
迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。
|
||||
|
||||
@@ -16,14 +16,14 @@
|
||||
|
||||
## 2. 五段流水线
|
||||
|
||||
一切要做的东西按五段流水线走：**登记 → 文档设计／美术设计（双轨）→ 写需求卡片 → 迭代编排 → 实现**。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。
|
||||
**需求改动**（游戏代码，含随逻辑写/改的测试）按五段流水线走：**登记 → 文档设计／美术设计（双轨）→ 写需求卡片 → 迭代编排 → 实现**；工程／文档设计／美术素材三类改动不走写卡与编排段，走「登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目」。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝「冻结待凑批」，不可开工。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.zcode/skills/`：doc-design／asset-ingest／req-card／iter-plan／iter），登记不立技能（条目格式由流水线闸强制）。设计工作在会话内进行、用户主导、禁无监管自跑。
|
||||
|
||||
| 段 | 入口技能 | 产出 | 出入口铁律 |
|
||||
|---|---|---|---|
|
||||
| 一·登记 | 无（闸管格式） | 待办清单条目 | 条目=标题登记元数据＋正文四属性（现状/缺口/归属/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |
|
||||
| 二·文档设计／美术设计 | doc-design（文档轨，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从待办清单取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；轨闭合凭据记入待办清单现状清单（文档轨=文档路径+版本号，美术轨=art-bible 条款版本） |
|
||||
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程直入四类（缺陷修复/工程债/测试基建/重构）凭证据跳过设计轨；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入现状清单（防遗忘） |
|
||||
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程直入证据）③总估时三条线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：低于 5 个工作日不得编（硬下限，2026-10-21 用户立：不希望单迭代编太少）；5–10 个工作日为常规区间、直接编；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日不得编（硬上限，2026-10-21 用户立：用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
|
||||
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程直入中改游戏行为的条目（缺陷修复／重构）凭证据跳过设计轨；工程直入中的配套维护条目（工程债/测试基建/工具维护，不动游戏行为）＝工程改动，不走本段，登记后「待执行」直改；卡片必经 grilling 多轮复核、零待裁点才成立；写完在待办清单状态记「已写卡」，卡片路径记入现状清单（防遗忘） |
|
||||
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程直入证据）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（2026-10-25 用户立：工作量限制属迭代层、非卡片层）；编入后迭代总量 <5 个工作日＝迭代行状态「冻结待凑批」、不可开工，凑批 ≥5 后由编排段改「待开工」（迭代体量偏好，2026-10-21 用户立、2026-10-25 改冻结制）；5–10 个工作日为常规区间；超过 10 个工作日须经用户确认（确认前呈报整批/拆批两案等裁，禁自行拆分或塞入），确认后迭代行随带日期特批标记；超过 20 个工作日禁止编（硬上限，用户确认也不放行，必须拆批）④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
|
||||
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
|
||||
|
||||
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。
|
||||
@@ -51,7 +51,7 @@
|
||||
8. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过（iter 技能第 5 步），未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 与 `dirty_game` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（六况拦截：缺回执／quick 模式／回执未覆盖分支尖＝回执 commit 之后 `game/` 又有改动、或跑闸时 `game/` 带着未提交改动（`dirty_game`）／域不覆盖本次改动／含新增红／master HEAD 非回执 commit 祖先＝合并将产出未测内容）。回执与分支尖的对齐判据是**代码面**不是 commit 号：回执之后只追加 `reports/`、`design/` 等非 `game/` 提交，回执照样有效，不构成复跑理由。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时人工确认闸可跑通且判据口径未变，闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底
|
||||
9. **合并后主区零复跑**（2026-10-24 用户裁：合回重跑验的是与回执同一份字节，零信息）——合回落地后 code 批只做两件秒级事：`--editor --quit` 重刷类名缓存（在册坑：.godot 缓存不入 git，与合并后代码失配会假红假绿）＋冒烟启动确认可开机（合计约 1 分钟）；docs 批零动作。全量验证**每批跑一次**＝worktree 批末按域闸，顺序是「先并入 master、再跑闸」（§1 第 2 条）；只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`，② 闸已开跑后 master 又被推进（合并将产出未测内容，由合回闸祖先判定拦下，§3.9 第六况）。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由；master 上永不跑全量
|
||||
10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`）实现批禁写，见 §12
|
||||
11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter<N>-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由非迭代批（工具/规则/文档批）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注
|
||||
11. **文档同步闸（实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter<N>-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由工程/文档设计改动批（直改类）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注
|
||||
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置
|
||||
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
|
||||
14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
> 约束范围：`game/probe/ 与 game/sim/`、`game/tests/` 与一切场景探针的编写与验收。
|
||||
> 分工：测试**执行许可**（什么时候允许跑测试）归 AGENTS.md「硬性红线·测试执行两入口铁规」；**跑什么闸、什么顺序**归 `tools/run_all_gates.sh`（脚本即清单，本文与 AGENTS.md 均不另列）；本文管测试怎么写、怎么算合格。每件测试工具**是什么、判什么、怎么单独跑、什么时候适合单独用**——见 `game/tests/README.md`（测试工具手册），本文不重复工具介绍。
|
||||
> 归属：随游戏逻辑写/改的测试＝需求改动的一部分（随需求卡片同批落地）；不伴随逻辑改动的纯测试维护＝工程改动（不写卡，用户发令直改）。
|
||||
|
||||
**写任何测试前必须通读本文。**
|
||||
|
||||
|
||||
+1
-1
@@ -106,7 +106,7 @@
|
||||
|
||||
词面纪律的登记处。通用禁用词与选词以**简明技术中文（STC）词表**为权威：外部技能文件 `C:\Users\DK\.zcode\skills\simplified-technical-chinese\词表.md`，约 170 条，配检查脚本 check.py。
|
||||
|
||||
本仓库的机器闸 = `tools/doc_term_audit.py`，已吸收本节项目裁项。**词表冻结**：本节与该闸的禁用词表不再扩充，扩表唯一入口＝用户实读反馈并经用户裁决（由非迭代批写入，agent 禁自行增词）。本节只登记两类裁项：A 已裁替换、B 豁免条款。历史退役词（雷格/正主/落籍等 7 组）见下方「退役词对照」节，不与 A 表重复。
|
||||
本仓库的机器闸 = `tools/doc_term_audit.py`，已吸收本节项目裁项。**词表冻结**：本节与该闸的禁用词表不再扩充，扩表唯一入口＝用户实读反馈并经用户裁决（由工程/文档设计改动批写入，agent 禁自行增词）。本节只登记两类裁项：A 已裁替换、B 豁免条款。历史退役词（雷格/正主/落籍等 7 组）见下方「退役词对照」节，不与 A 表重复。
|
||||
|
||||
### A. 已裁替换（写新文本必须用「用」列）
|
||||
|
||||
|
||||
@@ -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. 刷新自检＝**加对账＋骤降守卫**（淘汰不加、仅靠人工发起纪律——误跑一次即把新债静默洗进基线）
|
||||
@@ -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 故无害（实现期知晓项）。零阻断零应修，卡进可编排态。
|
||||
@@ -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「迁移断言全体」描述句随动列反哺点呈报）
|
||||
@@ -3,8 +3,8 @@
|
||||
r"""pipeline_gate.py — 工作流程流水线闸（待办清单条目状态机＋roadmap 迭代总表＋需求卡片口径＋一次交叉核）。
|
||||
|
||||
职责：机检待办清单条目（标题元数据/属性齐备/状态词白名单/条件凭据/状态段累积制在场约束/特批/
|
||||
零命中）与 roadmap 迭代总表（六列/状态四形态/卡片与报告存在性/编入时间与预计周期的
|
||||
历史行「—」豁免/周期三条线（<5 与 >20 判红、超 10 须带日期特批标记）/单元格白名单/零命中）；「已编迭代↔已写卡段↔迭代行
|
||||
零命中）与 roadmap 迭代总表（六列/状态五形态/卡片与报告存在性/编入时间与预计周期的
|
||||
历史行「—」豁免/周期校验（>20 判红、超 10 须带日期特批标记、<5 须处「冻结待凑批」态）/单元格白名单/零命中）；「已编迭代↔已写卡段↔迭代行
|
||||
卡片列」交叉核只此一处。2026-10-18 卡片冲突修订批补两条卡片机检：C1 关联文档同步面的
|
||||
文档义务口径（生效 2026-10-17）、C2 设计事实源声明（生效 2026-10-18）——两条都按文件名
|
||||
日期只追新规生效日之后的卡，旧卡属 git 历史留档不回头改。2026-10-21 验收闭合批补 C3：
|
||||
@@ -28,7 +28,7 @@ FACE_WORDS = ("文档轨", "美术轨", "双轨", "工程直入", "反哺点")
|
||||
STATUS_WORDS = (
|
||||
"待文档设计", "文档设计中", "文档设计已闭合",
|
||||
"待美术设计", "美术设计中", "美术设计已闭合",
|
||||
"待写卡", "已写卡", "已编迭代", "待裁决", "已写入",
|
||||
"待写卡", "已写卡", "已编迭代", "待裁决", "已写入", "待执行",
|
||||
)
|
||||
# 这些状态 = 设计未闭合，条目必须带「**缺口**」属性；其余状态不得带
|
||||
GAP_REQUIRED = ("待文档设计", "文档设计中", "待美术设计", "美术设计中")
|
||||
@@ -67,7 +67,7 @@ ATTR_LINE_RE = re.compile(r"^\*\*(现状|缺口|归属|状态)\*\*\s*[：:]\s*(.
|
||||
HEADING_RE = re.compile(r"^(#{1,4})\s+")
|
||||
SEP_ROW_RE = re.compile(r"^\|[\s\-|:]+$")
|
||||
STATUS_COL_RE = re.compile(
|
||||
r"^(待开工|进行中|已完成\(\d{4}-\d{2}-\d{2}\)|已终止\(\d{4}-\d{2}-\d{2}\))$")
|
||||
r"^(待开工|冻结待凑批|进行中|已完成\(\d{4}-\d{2}-\d{2}\)|已终止\(\d{4}-\d{2}-\d{2}\))$")
|
||||
PERIOD_RE = re.compile(r"^≈(\d+(?:\.\d+)?)\s*个工作日$")
|
||||
ITER_CODE_COL_RE = re.compile(r"^迭代\s*(\d+)")
|
||||
|
||||
@@ -337,7 +337,7 @@ def check_iter_table(block, issues, where, root):
|
||||
status_n = norm_parens(status)
|
||||
if not STATUS_COL_RE.match(status_n):
|
||||
issues.append((where, ln, "总表状态列",
|
||||
"「%s」不在四形态（待开工/进行中/已完成（YYYY-MM-DD）/已终止（YYYY-MM-DD））" % status))
|
||||
"「%s」不在五形态（待开工/冻结待凑批/进行中/已完成（YYYY-MM-DD）/已终止（YYYY-MM-DD））" % status))
|
||||
# 需求卡片列：路径逐卡查存在性；退役保留字与历史行「—」（无卡片制时期）豁免
|
||||
if norm_parens(cards) not in (norm_parens(RESERVED_RETIRED), "—"):
|
||||
for part in CARD_SEP_RE.split(cards):
|
||||
@@ -347,7 +347,7 @@ def check_iter_table(block, issues, where, root):
|
||||
"需求卡片列 %s 相对仓库根不存在" % part))
|
||||
if date != "—" and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", date):
|
||||
issues.append((where, ln, "编入时间", "「%s」须为 YYYY-MM-DD（历史迭代不可考填「—」）" % date))
|
||||
# 预计周期：≈N 个工作日（估时中值精确值）；<5/>20 硬判红（特批标记不放行）；10<x≤20 须格内带日期特批标记（§12.2/§12.4）；历史行「—」跳过
|
||||
# 预计周期：≈N 个工作日（估时中值精确值）；>20 硬判红（特批不放行）；10<x≤20 须格内带日期特批标记（§12.2/§12.4）；<5 ⇒ 行状态须为「冻结待凑批」（2026-10-25 两层模型：卡片无门槛、迭代层冻结线）；历史行「—」跳过
|
||||
per_marks = APPROVAL_RE.findall(period)
|
||||
per_core = APPROVAL_RE.sub("", period).strip()
|
||||
pm = None if per_core == "—" else PERIOD_RE.match(per_core)
|
||||
@@ -356,9 +356,9 @@ def check_iter_table(block, issues, where, root):
|
||||
"「%s」须为「≈N 个工作日」形态（精确值不取整；历史迭代不可考填「—」）" % period))
|
||||
elif pm is not None:
|
||||
wd = float(pm.group(1))
|
||||
if wd < 5:
|
||||
if wd < 5 and "冻结待凑批" not in status:
|
||||
issues.append((where, ln, "预计周期",
|
||||
"「%s」低于 5 个工作日硬下限，不得编入" % period))
|
||||
"「%s」低于 5 个工作日且未处「冻结待凑批」态——小卡可编入，迭代总量不足须冻结待凑批" % period))
|
||||
elif wd > 20:
|
||||
issues.append((where, ln, "预计周期",
|
||||
"「%s」超过 20 个工作日硬上限，特批标记不放行，须拆批" % period))
|
||||
|
||||
@@ -30,62 +30,59 @@
|
||||
|
||||
#### S9 类型闸正则失灵修复——R2 恒零命中＋static 函数漏网（2026-10-24 登记，来源=审计发现，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C1（已独立复现）：tools/audit_type_hints.py:29 的 FUNC_DECL 正则两洞——①无返回类型声明按 GDScript 语法必然以 `:` 结尾，正则要求 `)` 后只跟 `->`/注释/行尾，R2 目标形态 100% 失配（R2 从上线起恒零命中恒绿）；②`^(\s*)func` 不认 `static ` 前缀，static 函数对 R2/R3 整体漏网。实证存量（闸当前退出码 0）：core/level_runner.gd:632、core/attunement.gd:10、presentation/main.gd:565、presentation/views/hud_presenter.gd:10-11、core/reward_economy.gd:104/119/131/146、core/unit_container.gd:275（写卡会话路径订正：hud_presenter 实址 game/presentation/hud_presenter.gd，非 views/）。属架构文档测试域自警的「规则扫描面为空＝恒绿」静默失效模式（零命中自检因 R1/R3 仍有命中能力未拦住）。
|
||||
**现状**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C1（已独立复现）：tools/audit_type_hints.py:29 的 FUNC_DECL 正则两洞——①无返回类型声明按 GDScript 语法必然以 `:` 结尾，正则要求 `)` 后只跟 `->`/注释/行尾，R2 目标形态 100% 失配（R2 从上线起恒零命中恒绿）；②`^(\s*)func` 不认 `static ` 前缀，static 函数对 R2/R3 整体漏网。实证存量（闸当前退出码 0）：core/level_runner.gd:632、core/attunement.gd:10、presentation/main.gd:565、presentation/views/hud_presenter.gd:10-11、core/reward_economy.gd:104/119/131/146、core/unit_container.gd:275（写卡会话路径订正：hud_presenter 实址 game/presentation/hud_presenter.gd，非 views/）。属架构文档测试域自警的「规则扫描面为空＝恒绿」静默失效模式（零命中自检因 R1/R3 仍有命中能力未拦住）。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）。执行口径＝修 `tools/audit_type_hints.py:29` FUNC_DECL 正则两洞（①无返回类型声明的声明形态恒失配；②`^(\s*)func` 不认 `static ` 前缀），存量以开工时盘面清点（实证九址为已知下限），验收走撤销证明。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 546e5113）。
|
||||
|
||||
关联文档清单：
|
||||
- 需求卡片 reports/需求卡片-S9类型闸正则修复批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），非迭代批，零待裁点；存量清单以开工时盘面清点，实证九址为已知下限）
|
||||
**归属**：tools/ 静态扫描域（闸件修复，工程改动直改类——gdstyle 引入批 2026-10-24 已按同款形态完成：先摸存量、闸改动配撤销证明）
|
||||
|
||||
**归属**：tools/ 静态扫描域（闸件批，非迭代批——gdstyle 引入批 2026-10-24 已按同款形态收口：先摸存量、闸改动配撤销证明）
|
||||
|
||||
**状态**：待写卡＋已写卡
|
||||
**状态**：待执行
|
||||
|
||||
#### S13 gdstyle 免名单把数字当身份——存量债改小也报「基线外新违规」（2026-10-25 登记，来源=批次移交，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝迭代 35 卡② 合回前后实测（master 合回笔 `5499eb9c`）。闸件 `tools/gdstyle_gate.py:82` 把每条违规登记成三元组「文件|规则|消息全文」，而 gdstyle 的消息文本里带具体数字（如 `function 'resume_adventure' is 104 lines long (max 50)`），基线 `tools/gdstyle_baseline.txt`（241 行）按整句逐字比对——**只要某函数的行数/分支数/变量数发生变化，老违规就匹配不上，被判「基线外新违规」并判红，改小也算新增**。卡② 一批即因此冒出 12 项假新增，逐条对基线旧值核实全是存量债的计数漂移：`config_db_cross_validator.cross_validate` 159→107 行／31→21 分支／39→24 局部／嵌套 6→5（本批按卡片删除跨表校验④整段所致，债变小）、`level_runner` 类变量 40→38 且其「文件 1013 行超长」违规已消失（债被还掉）、`start_level_external` 参数 8→7、`main.gd` 1509→1507、`adventure_runner` 类变量 43→42／文件 1050→1051／`resume_adventure` 104→108 行（本批加断点代差标记键拒绝检查多 4 行）。本批真正新写的超标仅 1 处（新函数 `validate_graph` 72 行／20 分支），已当场拆成四段修掉。**盘面后果**：卡② 按用户令零复跑合回，master 尖 5499eb9c 从未整套跑绿过代码域闸；下一次任何批跑代码域闸都会看到 S13 红这 12 项（不处理则每批重复一次「要么重生成基线、要么被红挡在合回前」）。已写卡（2026-10-25，卡片＝reports/需求卡片-S13基线键治本-2026-10-25.md）：四待裁点已拍板——稳定身份键／恶化判据超登记值即红／本批治本＋批内刷新基线／refresh 加对账自检与骤降守卫；验收按 2026-10-24 撤销证明口径执行。
|
||||
**现状**：工程债证据＝迭代 35 卡② 合回前后实测（master 合回笔 `5499eb9c`）。闸件 `tools/gdstyle_gate.py:82` 把每条违规登记成三元组「文件|规则|消息全文」，而 gdstyle 的消息文本里带具体数字（如 `function 'resume_adventure' is 104 lines long (max 50)`），基线 `tools/gdstyle_baseline.txt`（241 行）按整句逐字比对——**只要某函数的行数/分支数/变量数发生变化，老违规就匹配不上，被判「基线外新违规」并判红，改小也算新增**。卡② 一批即因此冒出 12 项假新增，逐条对基线旧值核实全是存量债的计数漂移：`config_db_cross_validator.cross_validate` 159→107 行／31→21 分支／39→24 局部／嵌套 6→5（本批按卡片删除跨表校验④整段所致，债变小）、`level_runner` 类变量 40→38 且其「文件 1013 行超长」违规已消失（债被还掉）、`start_level_external` 参数 8→7、`main.gd` 1509→1507、`adventure_runner` 类变量 43→42／文件 1050→1051／`resume_adventure` 104→108 行（本批加断点代差标记键拒绝检查多 4 行）。本批真正新写的超标仅 1 处（新函数 `validate_graph` 72 行／20 分支），已当场拆成四段修掉。**盘面后果**：卡② 按用户令零复跑合回，master 尖 5499eb9c 从未整套跑绿过代码域闸；下一次任何批跑代码域闸都会看到 S13 红这 12 项（不处理则每批重复一次「要么重生成基线、要么被红挡在合回前」）。卡片裁决留档（卡片已违形退役，git 历史可考）：四待裁点已拍板——稳定身份键／恶化判据超登记值即红／本批治本＋批内刷新基线／refresh 加对账自检与骤降守卫；验收按 2026-10-24 撤销证明口径执行。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）——原卡片按违形退役，结论已回写本条目，卡片删除，全稿查 git 历史（提交 36b444eb）；执行口径＝治本档（四待裁点已拍板项照录上文），用户发令直改。
|
||||
|
||||
**预计改动面（两档，第一条只治标）**：① 治标＝人工跑一次 `python tools/gdstyle_gate.py --refresh` 重生成基线＋一笔提交，约 5 分钟，但键形态未改，下一批再动这些文件还会重演；② 治本＝改 `tools/gdstyle_gate.py` 的键构造段（:77-90，约 10–20 行）为「文件|规则|函数名」——函数名从消息里正则提取 `function 'x'`，无函数名的条目（类变量数/文件长度）退化为「文件|规则」，并**另加一条恶化判据**防新键吞掉真问题（同一函数当前指标较基线登记值恶化超阈值即判红，纯规范化数字会把 104→300 行的恶化也放过去，不可只靠数字抹平）；随动＝重生成 `tools/gdstyle_baseline.txt`（241 行按新键重排）、`tools/run_all_gates.sh` 头注与 `game/tests/README.md` 工具速查表的 S13 描述各一行、撤销证明四项（新增一处真超标必红／同函数改小改大的数字漂移禁止再冒新／恶化超阈值必红／禁闸内自动重生成清基线换绿的自检仍绿——各配撤销该判据见红＋还原复绿）。合计约 **0.5 个工作日**，非迭代批（tools/ 闸机与文档面），零待裁点即可写卡。
|
||||
**预计改动面（两档，第一条只治标）**：① 治标＝人工跑一次 `python tools/gdstyle_gate.py --refresh` 重生成基线＋一笔提交，约 5 分钟，但键形态未改，下一批再动这些文件还会重演；② 治本＝改 `tools/gdstyle_gate.py` 的键构造段（:77-90，约 10–20 行）为「文件|规则|函数名」——函数名从消息里正则提取 `function 'x'`，无函数名的条目（类变量数/文件长度）退化为「文件|规则」，并**另加一条恶化判据**防新键吞掉真问题（同一函数当前指标较基线登记值恶化超阈值即判红，纯规范化数字会把 104→300 行的恶化也放过去，不可只靠数字抹平）；随动＝重生成 `tools/gdstyle_baseline.txt`（241 行按新键重排）、`tools/run_all_gates.sh` 头注与 `game/tests/README.md` 工具速查表的 S13 描述各一行、撤销证明四项（新增一处真超标必红／同函数改小改大的数字漂移禁止再冒新／恶化超阈值必红／禁闸内自动重生成清基线换绿的自检仍绿——各配撤销该判据见红＋还原复绿）。合计约 **0.5 个工作日**，工程改动（tools/ 闸机面）直改类。
|
||||
|
||||
**归属**：tools/ 静态扫描域（闸件批，非迭代批）——与「S9 类型闸正则失灵修复」「S6/S7/S8 静态规则落地」两条同族：规则扫描面自身失灵/失准，防线不可信即等于没有防线
|
||||
**归属**：tools/ 静态扫描域（闸件修复，工程改动直改类）——与「S9 类型闸正则失灵修复」「S6/S7/S8 静态规则落地」两条同族：规则扫描面自身失灵/失准，防线不可信即等于没有防线
|
||||
|
||||
**状态**：已写卡
|
||||
**状态**：待执行
|
||||
|
||||
#### S6/S7/S8 静态规则落地——编排唯一性/禁 await/信号纪律三闸（2026-10-24 登记，来源=审计发现，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝reports/审计-game代码结构审查-2026-10-24.md §二 C2：三规则 static_scan.sh TODO 在案（架构文档静态扫描表自认未落地）——S6 core↔core 信号禁 lambda 捕获 self、S7 B2/B3/B4 API 符号命中文件 ⊆ B1 文件集、S8 结算路径 await 零命中。2026-10-24 审查人工 grep 结论干净（core 零 await、A2/B3/B4 零相互直调），但防线缺位＝回归无闸。S7 前置：须先在架构文档成文 B1 文件集边界（含 core/settlement/ 五段类与 damage_controller——现归属表零条目，见「架构与规范对齐批」条目①）。**2026-10-24 用户裁：条目整条冻结待④（「架构与规范对齐批」）裁决后再写卡**——写卡会话核对结论：S6（core 信号禁 lambda）与 S8（结算路径禁 await，文件集可按现行结算文件直接枚举）与④零依赖、技术上可先行，但按「先裁④再动③」整条冻结不先行。
|
||||
|
||||
**归属**：tools/ 静态扫描域（非迭代批）；S7 依赖「架构与规范对齐批」先裁 B1 文件集
|
||||
**归属**：tools/ 静态扫描域（工程改动直改类）；S7 依赖「架构与规范对齐批」先裁 B1 文件集
|
||||
|
||||
**状态**：待写卡
|
||||
|
||||
#### 验证集清单快照重生成——断言索引含退役措辞与旧行号（2026-10-25 登记，来源=审计发现，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝迭代 35 卡② 验收审计申报（git 历史可考：合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md，该产出物已按吸收即死退役）：game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引，只由 tools/extract_checks.py 手工重生成、不进任何闸；卡② 断言面换代后十余行仍含 first_script／template_pick 等退役措辞与过期行号（实测 first_script 8 处、template_pick 2 处），与宿主现文不符。已写卡（2026-10-25，卡片＝reports/需求卡片-节点图换代收尾批-2026-10-25.md，与「测试宿主改名」「level.tres 表尾注释」两件合卡；写卡实测漂移＝清单 1067 条 vs 现提取 1544 条〔消失 67／新增 539／字面变更 14 对〕，template_pick 实测 3 处——登记句「2 处」少数一行；路线裁重生成＋缺省三宿主全量口径，依据见卡 §12）。
|
||||
**现状**：工程债证据＝迭代 35 卡② 验收审计申报（git 历史可考：合回提交 5499eb9c 内的 reports/iter35-卡②-验收审计-2026-10-24.md，该产出物已按吸收即死退役）：game/tests/验证集清单.md 是批 B 迁移时的断言文本快照索引，只由 tools/extract_checks.py 手工重生成、不进任何闸；卡② 断言面换代后十余行仍含 first_script／template_pick 等退役措辞与过期行号（实测 first_script 8 处、template_pick 2 处），与宿主现文不符。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝走重生成：tools/extract_checks.py 两小改（头注模板数据驱动化＋新增 --carry-from 按同指纹承接「白话释义／处置」两列、承接文本内旧宿主文件名映射为新名）后 --extract --force 重生成（缺省三宿主全量口径；实测漂移＝清单 1067 条 vs 现提取 1544 条〔消失 67／新增 539／字面变更 14 对〕，template_pick 实测 3 处——登记句「2 处」少数一行），--diff 须 PASS；重生成后 grep node_map_templates／first_script／template_pick 预期零命中（若命中须全为反向断言）。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 1fb44cf4）。
|
||||
|
||||
**归属**：game/tests/验证集清单.md＋tools/extract_checks.py（重生成或清单头注记两路，写卡时定）
|
||||
**归属**：game/tests/验证集清单.md＋tools/extract_checks.py（重生成路线，2026-10-25 定）
|
||||
|
||||
**状态**：待写卡＋已写卡
|
||||
**状态**：待执行
|
||||
|
||||
#### 测试宿主改名——node_map_templates_test.gd 已承载生成图确定性断言（2026-10-25 登记，来源=审计发现，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝迭代 35 卡② 反哺点⑧：game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」，文件名中的 templates 是模板时代遗留；manifest 登记行＝game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。已写卡（2026-10-25，卡片＝reports/需求卡片-节点图换代收尾批-2026-10-25.md，与「验证集清单快照重生成」「level.tres 表尾注释」两件合卡）。
|
||||
**现状**：工程债证据＝迭代 35 卡② 反哺点⑧：game/tests/integration/node_map_templates_test.gd 现承载「生成图确定性断言套」，文件名中的 templates 是模板时代遗留；manifest 登记行＝game/tests/run_all.gd:90。改名为 node_map_determinism_test.gd 须同批改 manifest 路径行。2026-10-25 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝git mv 宿主两件（.gd＋.uid）＋改 run_all.gd:90 路径行＋文件内 4 处自引用字面量（:1/:10/:26/:31），断言判据零改动，直跑新名退出码 0 为验收。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。
|
||||
|
||||
**归属**：game/tests/integration/＋game/tests/run_all.gd manifest
|
||||
|
||||
**状态**：待写卡＋已写卡
|
||||
**状态**：待执行
|
||||
|
||||
#### level.tres 表尾注释含迭代叙事（2026-10-25 登记，来源=审计发现，设计面=工程直入）
|
||||
|
||||
**现状**：工程债证据＝迭代 35 卡② 反哺点⑨：game/data/tables/level.tres 表尾注释写「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出」，与 doc-conventions §5 禁写变更叙事有张力；卡② 卡片 T3 明令表尾写模板去向注记，故处置面限于叙事形态（删迭代号、保留图源换代事实句），不删去向事实。已写卡（2026-10-25，卡片＝reports/需求卡片-节点图换代收尾批-2026-10-25.md，与「验证集清单快照重生成」「测试宿主改名」两件合卡）。
|
||||
**现状**：工程债证据＝迭代 35 卡② 反哺点⑨：game/data/tables/level.tres 表尾注释写「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出」，与 doc-conventions §5 禁写变更叙事有张力；卡② 卡片 T3 明令表尾写模板去向注记，故处置面限于叙事形态（删迭代号、保留图源换代事实句），不删去向事实。2026-10-25 规则修订（改动四类）：本件属工程改动（数据表注释维护，直改类），执行口径＝条目原裁（删迭代号、保留去向事实句、表内零改动）。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。
|
||||
|
||||
**归属**：game/data/tables/level.tres
|
||||
|
||||
**状态**：待写卡＋已写卡
|
||||
**状态**：待执行
|
||||
|
||||
#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移（2026-10-24 登记，来源=审计发现，设计面=文档轨）
|
||||
|
||||
**现状**：审计报告＝reports/审计-game代码结构审查-2026-10-24.md（§二 C3/C4/C5＋§三 漂移清单）。漂移与待裁件七件：①架构文档「模块归属」多行 API 清单与实现不符（A2 try_* 便捷形/B2 ambush_grant_plan/B4 equivalence_supply 不存在；实有 grant_reserve_ap/finish_round_stop/check_skill_unlocks 未登记；damage_controller 与 settlement/ 五段类零条目——S7 落地的前置）；②code-conventions §1.3 核心写调用位置——三拆件控制器（presentation/curio_interact_controller.gd、camp_shop_presenter.gd、treasure_interact_controller.gd）持写调用 vs 规范「只允许在组合根出现」的 spec-AC 冲突，须裁「改规范成文组合根家族」vs「调用收回 main」；③A3→EffectEngine 反向依赖（core/action_economy.gd:43-49）——真违约或事实源失真二选一（effect_engine 降层登记基础层 vs B1 代发 vs 仅补登记）；④架构文档 :149/151 层合同计数写死 17 项 vs LAYER_CONTRACT 实 18 项；⑤明细行协议三处三个数（头注 9/实发 13/架构文档 15）；⑥§1.3 例举 submit_window_selection 符号已退役；⑦core/effect_engine.gd:360 校验文案「9 项」实为 18 项。
|
||||
|
||||
**缺口**：一次 doc-design 会话逐点裁决（②③有方案取舍须用户拍板，①④⑤⑥⑦为机械对齐）；裁决后走非迭代批落文 design/engineering/。
|
||||
**缺口**：一次 doc-design 会话逐点裁决（②③有方案取舍须用户拍板，①④⑤⑥⑦为机械对齐）；裁决后走文档设计改动直改写入 design/engineering/。
|
||||
|
||||
**归属**：design/engineering/（architecture.md「模块归属」节＋「呈现层装配」节、code-conventions §1.3）
|
||||
|
||||
|
||||
Reference in new issue
Block a user