merge master（改动四类与两层模型）＋手工合四文件：格式换代与新状态词并轨
This commit is contained in:
DKChan committed
commit
c550654896
10 files changed
+440
-933
No files matched your search
@@ -51,22 +51,47 @@
|
||||
| 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则与取值域 = 各系统 owner 文档。冲突须显式提出，禁默默改值 |
|
||||
| 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` |
|
||||
|
||||
## 回答风格规则（只管对话输出；文档写作归 doc-conventions §2–§4）
|
||||
|
||||
### 三条核心原则（按优先级）
|
||||
|
||||
1. 不自造黑话、不自创词语。用已有的词；必须引入新词，当场一句白话定义（三形态表与判据见 doc-conventions 第 4 节）。
|
||||
2. 简洁。同一意思只说一遍；能用一句不说两句。
|
||||
3. 介绍一个物体、一个概念、一个问题，多角度讲清楚；每角度一两句，禁止违背第 2 条。
|
||||
|
||||
### 简洁细则
|
||||
|
||||
- 禁换说法重复：同一判断换个措辞再说一遍 = 违规。
|
||||
- 禁铺垫、过渡句、客套话、总结句。
|
||||
- 禁填充句式：其实／说白了／本质上来说——直接给结论。
|
||||
- 短句为主，一行一个意思。
|
||||
- 答完即止，不追加「还需要我……吗」。
|
||||
|
||||
### 多角度细则
|
||||
|
||||
- 触发：解释概念、评估方案、回答「X 好不好」。事实型小问题一句话直答，不硬凑角度。
|
||||
- 角度池（按问题选 2～5 个）：现状（现在是什么、缺什么）· 本质（是什么、解决什么）· 代价（要什么前提）· 边界（何时不成立）· 对比（与替代方案差异）· 风险（最常见失败方式）。
|
||||
- 每个角度 = 关键词 + 一个判断 + 至多一句理由。
|
||||
- 角度之间用编号，不用「另外、此外、同时」串联。
|
||||
|
||||
### 格式优先级
|
||||
|
||||
列表 > 表格 > 关键词＋一句话。大段散文是最后手段。
|
||||
|
||||
## 硬性红线（勿违反；操作细则在 process-conventions.md 与各规约）
|
||||
|
||||
- 主工作区禁止直接改动与提交——一切改动走独立 worktree（豁免：`.zcode/` 与 `.qoder/` 两份本机 harness 配置，实测均不入 git）
|
||||
- **仓库根禁止设会话状态文件**（`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 步）
|
||||
- 规则评估——没在真实任务上评估过的规则修订，不算完成。
|
||||
- 中间产物吸收即死——结论先吸收进权威文档、未决先迁待办清单，文件即删且永不提交（doc-conventions 第 11 节）
|
||||
- **禁写变更记录**——文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁写「本版改了哪些条款」式逐版本叙述与 `# 2026-xx-xx 缺陷修批——` 式行内修订注记；沿革只进 git commit log。版本号可作文档现行身份标记留在文首状态行与正文引用中（doc-conventions 第 5 节，机检闸 gdd_lint R4 反转拦截）
|
||||
- 用语红线——一切对用户输出禁自造黑话，需要作者解释的词必须展开成完整白话句（doc-conventions 第 4 节三形态表）
|
||||
- 呈报四问（读后自检制）——向用户首次完整呈报一件事（需求／缺陷／方案／结论）时，写完先自查：读者只读这一段，能否不看原文答出——① 现状差在哪：现在是什么、缺什么；② 你建议做什么：做完预期什么效果、会动到哪些面；③ 为什么选这个做法：考虑过、放弃过哪些别的路；④ 做完怎么验证：哪些还有把握不足。哪问答不出就补哪问，禁靠加小标题凑数；三句话能说清的小件合并为三句：现状一句、建议与验证一句、没把握的一句；后续追问与推进不必重跑全框架
|
||||
- 真人检测只登记不阻塞——登记进体验验证清单/实现报告即完成义务，禁以等目检为停工理由或当作合回的前置条件
|
||||
- 文件头 = `##` 文档注释，介绍本模块是什么；禁写变更叙事（改动史查 git log）；禁文档反向链接（code-conventions §1.4.1）
|
||||
- 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径
|
||||
|
||||
@@ -1,239 +1,241 @@
|
||||
# 文档写作规范（写文档前必读）
|
||||
|
||||
> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。
|
||||
> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。
|
||||
|
||||
## 0. 总纲
|
||||
|
||||
默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。
|
||||
|
||||
## 1. 可读性第一（最高纪律）
|
||||
|
||||
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。
|
||||
|
||||
`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。
|
||||
|
||||
## 2. 白话写作规则
|
||||
|
||||
写文档像向朋友当面解释你的游戏：
|
||||
|
||||
1. **完整句子优先**：一段只说一件事，长句拆短句。
|
||||
2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。
|
||||
3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。
|
||||
4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。
|
||||
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。
|
||||
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。
|
||||
|
||||
## 3. 表达分工：散文、表格、字符画、公式
|
||||
|
||||
| 内容 | 载体 | 纪律 |
|
||||
|---|---|---|
|
||||
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |
|
||||
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 |
|
||||
| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 |
|
||||
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 |
|
||||
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 |
|
||||
|
||||
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。
|
||||
|
||||
## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）
|
||||
|
||||
**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。
|
||||
|
||||
文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语：
|
||||
|
||||
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。
|
||||
- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。
|
||||
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。
|
||||
|
||||
**自造词的三种固定形态（全部禁止）**：
|
||||
|
||||
| 形态 | 反例 | 正确写法 |
|
||||
|---|---|---|
|
||||
| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 |
|
||||
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） |
|
||||
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |
|
||||
|
||||
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。
|
||||
|
||||
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由非迭代批写入，禁 agent 自行增词。
|
||||
|
||||
## 5. 结构纪律
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |
|
||||
| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |
|
||||
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |
|
||||
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |
|
||||
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |
|
||||
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |
|
||||
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |
|
||||
|
||||
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。
|
||||
|
||||
**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：
|
||||
|
||||
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。
|
||||
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。
|
||||
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
|
||||
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。
|
||||
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。
|
||||
|
||||
## 6. 文档类型与骨架
|
||||
|
||||
**顶层文档**：
|
||||
|
||||
| 文档 | 管什么 |
|
||||
|---|---|
|
||||
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |
|
||||
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |
|
||||
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |
|
||||
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |
|
||||
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |
|
||||
| `05-不做清单.md` | 明确写：这些我不要 |
|
||||
| `待办清单.md`（仓库根） | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 |
|
||||
| `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） |
|
||||
|
||||
**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）。
|
||||
|
||||
**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。
|
||||
|
||||
## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/engineering/concept-conventions.md`
|
||||
|
||||
## 10. 会话状态——仓库根不设状态文件
|
||||
|
||||
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。
|
||||
|
||||
废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。
|
||||
|
||||
## 11. 文档生命周期：吸收即死
|
||||
|
||||
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。
|
||||
|
||||
| 规则 | 内容 |
|
||||
|---|---|
|
||||
| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 |
|
||||
| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 |
|
||||
| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 |
|
||||
| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 |
|
||||
| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 |
|
||||
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 |
|
||||
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
|
||||
| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` |
|
||||
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 |
|
||||
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |
|
||||
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |
|
||||
|
||||
**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。
|
||||
|
||||
## 12. 流程文档格式
|
||||
|
||||
五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。
|
||||
|
||||
### 12.1 待办清单条目格式与状态机
|
||||
|
||||
待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。
|
||||
|
||||
标题格式（尖括号处按实际填写，方括号内为可选段）：
|
||||
|
||||
```
|
||||
#### <条目名>（<YYYY-MM-DD>登记，来源=<playnote／会话提及／审计发现／批次移交>[，优先级＝<P0／P1／P2>]）
|
||||
```
|
||||
|
||||
`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。
|
||||
|
||||
正文四属性模板：
|
||||
|
||||
```
|
||||
**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程形态条目必须在实况里指认证据（bug 证据或工程债条目）。
|
||||
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。
|
||||
**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。
|
||||
**状态**：按状态机取词。
|
||||
```
|
||||
|
||||
`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）：
|
||||
|
||||
| 档 | 覆盖范围 |
|
||||
|---|---|
|
||||
| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） |
|
||||
| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 |
|
||||
| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 |
|
||||
| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） |
|
||||
|
||||
只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。
|
||||
|
||||
状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。
|
||||
|
||||
```
|
||||
各设计线推进序列（同条目两条线并列推进时，两段各写各的）：
|
||||
文档线：待文档设计 → 文档设计中 → 文档设计已闭合
|
||||
美术线：待美术设计 → 美术设计中 → 美术设计已闭合
|
||||
下游共用序列：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除
|
||||
累积示例：文档设计已闭合＋待美术设计＋已写卡
|
||||
```
|
||||
|
||||
设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。
|
||||
|
||||
状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。
|
||||
|
||||
两种条目形态与一种后缀：
|
||||
|
||||
| 形态 | 规则 |
|
||||
|---|---|
|
||||
| 工程形态 | 缺陷修复／工程债／测试基建／重构四类工程条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线 |
|
||||
| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 |
|
||||
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |
|
||||
|
||||
特批标记见 12.4。
|
||||
|
||||
### 12.2 roadmap 迭代行格式
|
||||
|
||||
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。迭代行六列：
|
||||
|
||||
```
|
||||
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |
|
||||
```
|
||||
|
||||
| 列 | 规则 |
|
||||
|---|---|
|
||||
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |
|
||||
| 状态 | 待开工 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |
|
||||
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） |
|
||||
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 |
|
||||
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 或超过 20 均判红（硬下限/硬上限，2026-10-21 用户裁定：特批标记也不放行）；历史迭代不可考填「—」 |
|
||||
| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」；已完成迭代只许存在路径或退役保留字、禁「—」 |
|
||||
|
||||
迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。
|
||||
|
||||
### 12.3 美术工作区目录与命名
|
||||
|
||||
美术素材走两条目录线：在途工作在 `artwork/`（整目录不入 git），定稿进 `game/assets/art/`（入包被游戏加载）。图片永不进 `design/`。
|
||||
|
||||
| 位置 | 规则 |
|
||||
|---|---|
|
||||
| `artwork/<YYYY-MM-DD-主题>/` | 批次工作区，一次美术批一个目录，整目录不入 git |
|
||||
| `artwork/<批次工作区>/samples/` | 样张子目录 |
|
||||
| `artwork/archive/<主题>-<日期>/` | 批次完结归档 |
|
||||
| `game/assets/art/<用途子目录>/` | 终稿，入包被游戏加载 |
|
||||
|
||||
命名总则：全小写英文＋下划线，禁中文／空格／大写。
|
||||
|
||||
| 对象 | 文件名规则 |
|
||||
|---|---|
|
||||
| 终稿 | 三段式 `<对象>_<部位或状态>_<规格>.png`；终稿文件名=代码消费名——先定 ui_kit／资源路径常量，素材名跟它走，防断链 |
|
||||
| 样张 | `sample_<屏名>_<版本>.png` |
|
||||
| 同名迭代 | 直接覆盖，不留 v2 副本 |
|
||||
|
||||
美术内容不做机检，只保留命名与目录检查。
|
||||
|
||||
### 12.4 特批标记
|
||||
|
||||
特批标记是流程格式例外的唯一放行凭证：`〔用户特批 YYYY-MM-DD 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。
|
||||
|
||||
执行技能一律两段式：
|
||||
|
||||
1. 对象已有内容 → 直接写入标记。
|
||||
2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。
|
||||
|
||||
标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。
|
||||
# 文档写作规范（写文档前必读）␍
|
||||
␍
|
||||
> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。␍
|
||||
> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。␍
|
||||
␍
|
||||
## 0. 总纲␍
|
||||
␍
|
||||
默认读者没读过项目历史——可能是半年后的你自己。先让人读懂，再谈结构整齐。␍
|
||||
␍
|
||||
## 1. 可读性第一（最高纪律）␍
|
||||
␍
|
||||
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。␍
|
||||
␍
|
||||
`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。␍
|
||||
␍
|
||||
## 2. 白话写作规则␍
|
||||
␍
|
||||
写文档像向朋友当面解释你的游戏：␍
|
||||
␍
|
||||
1. **完整句子优先**：一段只说一件事，长句拆短句。␍
|
||||
2. **禁止碎片笔记体**：不写压缩碎片，不把 `A→B→C` 箭头链当叙述（流程交给字符画，见第 3 节），不用只有作者自己懂的缩略语。␍
|
||||
3. **每节人话开头**：每小节第一段先用白话说清"这是什么、为什么需要它"；只读各节第一段就能看懂全文故事线。␍
|
||||
4. **术语首现即解释**：专业术语或项目概念首次出现用一句话解释；玩家可见专属名词（如"显影尘"）同样要说清。␍
|
||||
5. **叙述优先于引用**：AC-x、F-x 等编号引用不进正文叙述，只出现在验收标准与附录。␍
|
||||
6. **反面基准**：数据库条目、会议纪要、只有评审工具能"读懂"的表格堆。␍
|
||||
␍
|
||||
## 3. 表达分工：散文、表格、字符画、公式␍
|
||||
␍
|
||||
| 内容 | 载体 | 纪律 |␍
|
||||
|---|---|---|␍
|
||||
| 规则的来龙去脉、行为逻辑 | 散文段 | 每段 ≤240 字，一段一件事 |␍
|
||||
| 枚举、数值、边界、依赖 | 表格 | 表格只放可列举的事实；禁把需要解释的内容塞进单元格让读者自己拼 |␍
|
||||
| 流程、状态流转 | 字符画（代码块） | 禁用散文逐步描述流程 |␍
|
||||
| 公式 | 结论先行 | 先一行加粗结论，再放公式代码块、变量表与验算表 |␍
|
||||
| 体验锚点 | 关键词表 | 支柱/关键词/机制承诺 三列表，禁长篇情绪描述 |␍
|
||||
␍
|
||||
节点内顺序：先人话，再表格枚举，再字符流程图，最后公式举证。**规则两段式**：先写"人话阶段"（作用于哪个系统、什么情况下、谁触发、触发后发生什么），再写"举证阶段"（逐效果给出计算方法；纯流程规则明写"无计算"）。规则名禁止纯名词短语（反面例："获取路由"）。␍
|
||||
␍
|
||||
## 4. 用语纪律（见名知意 · 所见即所得 · 禁自造黑话）␍
|
||||
␍
|
||||
**正面总则**：见名知意——每个名字（概念名、术语、文档与目录名）本身就说清所指，起不出这样的名字多半是概念还没想清；所见即所得——字面意思就是规则的完整意思，有隐含前提就写进句子。两句管语义透明，不与第 8 节指路存根冲突。␍
|
||||
␍
|
||||
文档、评审输出、日志与一切沟通中**禁止自造黑话**——比喻性生造词、只有作者自己懂的缩略语：␍
|
||||
␍
|
||||
- 只能使用：（a）人人可懂的直白语言，或（b）游戏行业通用术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。␍
|
||||
- 指代新概念用直白描述性短语（正例："实测可推理率"）；确需命名时：首现处附一句白话定义，并登记进 `design/gdd/术语表.md`。␍
|
||||
- 唯一例外：玩家在游戏里也会看到的专属名词（道具名、界面用语）。文档内部的机制概念不得造词。␍
|
||||
␍
|
||||
**自造词的三种固定形态（全部禁止）**：␍
|
||||
␍
|
||||
| 形态 | 反例 | 正确写法 |␍
|
||||
|---|---|---|␍
|
||||
| 给工作包起代号 | "样张批""八型批" | 叙述名 = 日期 + 做什么 |␍
|
||||
| 给机制、检查、基线、区域造名词 | "形象锚""判读口径""变异纹带" | 用行业通用词；长期复用的概念走登记通道（正常名字+白话定义+登记进 术语表） |␍
|
||||
| 给流程步骤造动词 | "收口""落籍""在飞""随批""对拍""销账""正主""台账" | 用日常动词：完成 / 合并进 master / 执行中 / 顺带 / 与基线数据逐项比对 / 注销 / 定义所属的那份文档 / 状态记录 |␍
|
||||
␍
|
||||
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。␍
|
||||
␍
|
||||
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由工程/文档设计改动批写入，禁 agent 自行增词。␍
|
||||
␍
|
||||
## 5. 结构纪律␍
|
||||
␍
|
||||
| 规则 | 内容 |␍
|
||||
|---|---|␍
|
||||
| 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` |␍
|
||||
| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log |␍
|
||||
| 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 |␍
|
||||
| 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 |␍
|
||||
| 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 |␍
|
||||
| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" |␍
|
||||
| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 |␍
|
||||
␍
|
||||
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。␍
|
||||
␍
|
||||
**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：␍
|
||||
␍
|
||||
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。␍
|
||||
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。␍
|
||||
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。␍
|
||||
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。␍
|
||||
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。␍
|
||||
␍
|
||||
## 6. 文档类型与骨架␍
|
||||
␍
|
||||
**顶层文档**：␍
|
||||
␍
|
||||
| 文档 | 管什么 |␍
|
||||
|---|---|␍
|
||||
| `00-游戏概念.md` | 一句话概念、目标受众、世界观命名、术语层级 |␍
|
||||
| `01-核心循环.md` | 玩家醒来→做什么→得到什么→又想做什么，一条线讲清 |␍
|
||||
| `02-系统清单.md` | 根索引：循环 × 子系统总表 + 文档树导航 |␍
|
||||
| `03-内容规模.md` | 几个关卡、几种敌人、几种道具——做多少砍多少 |␍
|
||||
| `04-美术音频方向.md` | 参考图、参考游戏、风格关键词 |␍
|
||||
| `05-不做清单.md` | 明确写：这些我不要 |␍
|
||||
| `待办清单.md`（仓库根） | 流水线唯一登记处：条目=登记元数据标题＋四属性正文，状态随流水线段推进（格式与状态机见第 12.1 节）；各系统文档「待办」节只留指路存根 |␍
|
||||
| `roadmap.md`（根目录） | 里程碑表＋迭代总表，一行一迭代，记录编排与实现进度（六列格式见第 12.2 节） |␍
|
||||
␍
|
||||
**系统文档骨架**（`systems/` 下统一采用）：文首引言（一句话定位+状态）／设计目的（2-4 句白话）／系统范围（负责/不负责两表）／在核心循环中的位置（字符画一行+两句白话）／核心规则（领域章节 ×2–6，每节一页纸）／依赖与输出（表格；引用纪律见 concept-conventions）／P0 最小闭环与 P1·P2 后置／调参表（取值域+provisional 标注）／验收标准（可验证判据）／待办（指路存根）。␍
|
||||
␍
|
||||
**命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。␍
|
||||
␍
|
||||
## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/engineering/concept-conventions.md`␍
|
||||
␍
|
||||
## 10. 会话状态——仓库根不设状态文件␍
|
||||
␍
|
||||
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。␍
|
||||
␍
|
||||
废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [待办清单](../../待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。␍
|
||||
␍
|
||||
## 11. 文档生命周期：吸收即死␍
|
||||
␍
|
||||
**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、退役内容留底（`design/content-archive/`，2026-10-20 用户裁新立：只装「内容已退役、留底供日后重新过准入」的档案，落内文件须在文档头写明所属线）、本规范、待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片（死期=所属迭代实现批合回 master 那一刻；roadmap 对应行的卡片/报告列改填「已退役（git 历史可考）」保留字，凭据语义从文件指针换代为状态标记）、机检/验收过程报告、调研/审计/提案/需求澄清过程稿、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。␍
|
||||
␍
|
||||
| 规则 | 内容 |␍
|
||||
|---|---|␍
|
||||
| 吸收即死 | 中间文档结论写进权威文档（GDD 对应节/art-bible/术语表）那一刻，文件即删 |␍
|
||||
| 未决先迁再死 | 未决内容先迁现行事实源（待办清单/roadmap 卡/GDD 对应节），然后文档即死 |␍
|
||||
| 永不入库 | 迭代出口后中间产物一律删除且不许提交；迭代进行中可暂存工作区，出口批一并清 |␍
|
||||
| 引用面口径 | 活文档对中间文档的指路阻塞删除：先改写指路句为结论内联或 git 提交号再删 |␍
|
||||
| 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 |␍
|
||||
| sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 |␍
|
||||
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |␍
|
||||
| 暂存地非档案库 | 中间文档唯一暂存地＝`reports/`（需求卡片＋迭代产出物＋调研/审计/提案/需求澄清过程稿）。**`design/research/` 已退役（2026-10-21 用户裁）**：`design/` 全目录只放持久化设计文档与规范，过程件一律不进，禁止再在 `design/` 下另设过程件目录（熵增闸退役路径清单已收 `design/research`，目录再现即判红）。禁止文件在自身页眉自称「常驻／已追认／不受吸收即死约束」之类的豁免——豁免只写进规约正文，本条就是不给；确实要长期留用的退役内容走 `design/content-archive/`（活文档身份，落内文件头部写明所属线）。跨会话交接文件（会话提示/handoff/任务书/试运行报告）禁止入库——给另一个会话的开工输入在会话里交付即可（与仓库根禁设会话状态文件同族判据，见第 10 节）。根目录 `playnote.md`=用户本人试玩随手记，只由用户本人增删，不属于任何文档族、不受吸收即死管辖，不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`（2026-09-27 用户裁「审图只看一处」），结论写进待办清单或需求卡片后图像即弃；`.html`／`.json` 这类报告渲染件允许作为报告的一种（2026-10-21 用户裁）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` |␍
|
||||
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 |␍
|
||||
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |␍
|
||||
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |␍
|
||||
␍
|
||||
**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。␍
|
||||
␍
|
||||
## 12. 流程文档格式␍
|
||||
␍
|
||||
五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查待办清单与 roadmap 两文件格式及互相引用的机检闸）的判据依据。␍
|
||||
␍
|
||||
### 12.1 待办清单条目格式与状态机␍
|
||||
␍
|
||||
待办清单是流水线的唯一登记处：要做的事先登记一条，随流水线段推进改状态，做完整条删除。一条条目分两层——**标题=登记元数据**（何时登记、从哪来、紧急度，登记后不再变），**正文=四个属性**（随进程演进）。四个属性各管一件事：`实况` 管凭据，`缺口` 管这条的**输入**（还缺哪一次设计），`改动面` 管这条的**产出**（要动哪些面），`状态` 管这条走到流水线哪一段。␍
|
||||
␍
|
||||
标题格式（尖括号处按实际填写，方括号内为可选段）：␍
|
||||
␍
|
||||
```␍
|
||||
#### <条目名>（<YYYY-MM-DD>登记，来源=<playnote／会话提及／审计发现／批次移交>[，优先级＝<P0／P1／P2>]）␍
|
||||
```␍
|
||||
␍
|
||||
`优先级` 是紧急度标记，可选，规则三条：不写＝默认档 P2；只有用户明示才写，会话不得自行给任何条目定档；P0 最高、P2 最低。它只服务阅读时的排序，不参与开工门、编排四查与状态机。`P0/P1/P2` 这组记号在本仓库只指待办紧急度，新文档禁另立别义。␍
|
||||
␍
|
||||
正文四属性模板：␍
|
||||
␍
|
||||
```␍
|
||||
**实况**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句实际情况说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程形态条目必须在实况里指认证据（bug 证据或工程债条目）。␍
|
||||
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合设计段时此属性必须存在；设计线全部闭合后删除。␍
|
||||
**改动面**＝文档／美术素材／游戏代码／工具代码 四档取多，多档用＋连接、禁重复、按上表次序排列。登记时即写，随进程若产出面变宽要补档。␍
|
||||
**状态**：按状态机取词。␍
|
||||
```␍
|
||||
␍
|
||||
`改动面` 四档的划线判据（按被改对象的路径归属，与闸的分域同口径）：␍
|
||||
␍
|
||||
| 档 | 覆盖范围 |␍
|
||||
|---|---|␍
|
||||
| 文档 | 本仓库的 .md 权威文档：`design/` 设计文档与 `design/engineering/` 规约、`design/art/art-bible`、根流程件（roadmap／待办清单／体验验证清单） |␍
|
||||
| 美术素材 | 本条目要出的图：`artwork/` 在途样张与 `game/assets/art/` 终稿 |␍
|
||||
| 游戏代码 | `game/` 全部：脚本与场景、`data/tables/*.tres` 数值表、`tests/`、`probe/`、`sim/`——表值直接改变游戏运行结果，归本档 |␍
|
||||
| 工具代码 | `tools/` 与仓库根 python 脚本（含各验证闸件）＋流水线技能件 `.zcode/skills/`、`.qoder/skills/`（技能改的是流水线行为，与闸件同类） |␍
|
||||
␍
|
||||
只写本条目自己交付的产出面，不预写下游实现批要动的面。`reports/` 下的需求卡片与批次产出物属过程件（第 11 节管辖），不计入 `文档` 档。四档与 AGENTS.md 硬红线的「改动四类」对应关系：`游戏代码`＝需求改动（走写卡与编排段）、`工具代码`／`文档`／`美术素材` 三档各自对应工程改动／文档设计改动／美术素材改动三类直改通道；一条条目可以同时含多档。␍
|
||||
␍
|
||||
状态段用词自带所属设计线——`待文档设计`／`文档设计中`／`文档设计已闭合` 是文档线，`待美术设计`／`美术设计中`／`美术设计已闭合` 是美术线，不需要在标题另行声明走哪条线。状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；跨线的段一律保留、禁删（同一设计线内只留最新一段），下游段一旦写下不回收——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。␍
|
||||
␍
|
||||
```␍
|
||||
各设计线推进序列（同条目两条线并列推进时，两段各写各的）：␍
|
||||
文档线：待文档设计 → 文档设计中 → 文档设计已闭合␍
|
||||
美术线：待美术设计 → 美术设计中 → 美术设计已闭合␍
|
||||
下游共用序列（需求改动）：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除␍
|
||||
直改序列（工程改动／文档设计改动／美术素材改动）：登记 → 待执行 → 完成即整条删除（经设计讨论的可前置闭合段，如「文档设计已闭合＋待执行」）␍
|
||||
累积示例：文档设计已闭合＋待美术设计＋已写卡␍
|
||||
```␍
|
||||
␍
|
||||
设计线段与下游段同条并存是合法形态：状态行里出现过的**每条设计线各自留最新一段**，跨线依赖不阻塞本条推进（文档线闭合后写卡、美术线仍未出图，就把 `文档设计已闭合` 与 `待美术设计` 并写）。「写卡前本条要落的那条设计线必须已闭合」是实现侧的执行义务，由编排段查卡片凭据核对，不靠标题声明——闸只查同线并现多段。␍
|
||||
␍
|
||||
状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在实况的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝实况清单里的需求卡片路径。␍
|
||||
␍
|
||||
三种条目形态与一种后缀：␍
|
||||
␍
|
||||
| 形态 | 规则 |␍
|
||||
|---|---|␍
|
||||
| 需求性工程条目（需求改动） | 缺陷修复／重构等改游戏行为的条目：状态首段直接落「待写卡」、整行不含设计段，凭实况里指认的证据跳过设计线；改动面必含 `游戏代码` |␍
|
||||
| 直改类条目（工程改动／文档设计改动／美术素材改动） | 不动游戏行为的配套改动：登记即「待执行」，用户发令直改，不走写卡与编排段；改动面取 `工具代码`／`文档`／`美术素材` 三档 |␍
|
||||
| 反哺点专条 | 状态取 待裁决 → 已写入 → 删除，不走设计线也不走下游序列 |␍
|
||||
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |␍
|
||||
␍
|
||||
特批标记见 12.4。␍
|
||||
␍
|
||||
### 12.2 roadmap 迭代行格式␍
|
||||
␍
|
||||
roadmap 由顶部里程碑表＋迭代总表组成，迭代总表一行一个迭代，回答一个问题：这个迭代编入了哪些卡、做到哪一步。两层口径（2026-10-25 用户立）：需求卡片＝需求单位的实施文档，任何工作量皆可写、皆可编入迭代；工作量限制只属迭代层——迭代估时总量 <5 个工作日＝冻结不可开工。迭代行六列：␍
|
||||
␍
|
||||
```␍
|
||||
| 迭代号 | 状态 | 需求卡片 | 编入时间 | 预计周期 | 实现报告 |␍
|
||||
```␍
|
||||
␍
|
||||
| 列 | 规则 |␍
|
||||
|---|---|␍
|
||||
| 迭代号 | 写「迭代 N」形态（N 为阿拉伯数字）；这是流水线闸交叉核匹配的依据 |␍
|
||||
| 状态 | 待开工 ／ 冻结待凑批 ／ 进行中 ／ 已完成（YYYY-MM-DD）／ 已终止（YYYY-MM-DD） |␍
|
||||
| 需求卡片 | 只写文件路径；一格内一行一卡，格内排列顺序=执行顺序；已退役填保留字「已退役（git 历史可考）」；历史迭代不可考填「—」（早期无卡片制的迭代） |␍
|
||||
| 编入时间 | YYYY-MM-DD（该迭代最近一次编入卡片的日期）；历史迭代不可考填「—」 |␍
|
||||
| 预计周期 | 所选卡估时区间**中值**求和，单位工作日，写精确值不取整，形态「≈N 个工作日」（1 周＝5 个工作日）；5–10 为常规区间；超过 10 须随带日期的用户特批标记（格式见 12.4），流水线闸见标记放行、无标记判红；低于 5 的迭代行状态必须为「冻结待凑批」（2026-10-25 两层模型：小卡可编入，迭代总量不足即冻结、禁止处待开工/进行中）；超过 20 判红（硬上限，特批标记也不放行）；历史迭代不可考填「—」 |␍
|
||||
| 实现报告 | `reports/iterN-实现报告-YYYY-MM-DD.md`；未完成=「—」；退役=「已退役（git 历史可考）」；已完成迭代只许存在路径或退役保留字、禁「—」 |␍
|
||||
␍
|
||||
迭代行禁入内容：事项说明、卡序叙述、T 段明细、读数、闸数字、裁点记录、门依赖。卡间依赖写在卡片自身，行内只放上表六列的事实。特批标记同样可用于 roadmap 格（须带日期，见 12.4）。␍
|
||||
␍
|
||||
### 12.3 美术工作区目录与命名␍
|
||||
␍
|
||||
美术素材走两条目录线：在途工作在 `artwork/`（整目录不入 git），定稿进 `game/assets/art/`（入包被游戏加载）。图片永不进 `design/`。␍
|
||||
␍
|
||||
| 位置 | 规则 |␍
|
||||
|---|---|␍
|
||||
| `artwork/<YYYY-MM-DD-主题>/` | 批次工作区，一次美术批一个目录，整目录不入 git |␍
|
||||
| `artwork/<批次工作区>/samples/` | 样张子目录 |␍
|
||||
| `artwork/archive/<主题>-<日期>/` | 批次完结归档 |␍
|
||||
| `game/assets/art/<用途子目录>/` | 终稿，入包被游戏加载 |␍
|
||||
␍
|
||||
命名总则：全小写英文＋下划线，禁中文／空格／大写。␍
|
||||
␍
|
||||
| 对象 | 文件名规则 |␍
|
||||
|---|---|␍
|
||||
| 终稿 | 三段式 `<对象>_<部位或状态>_<规格>.png`；终稿文件名=代码消费名——先定 ui_kit／资源路径常量，素材名跟它走，防断链 |␍
|
||||
| 样张 | `sample_<屏名>_<版本>.png` |␍
|
||||
| 同名迭代 | 直接覆盖，不留 v2 副本 |␍
|
||||
␍
|
||||
美术内容不做机检，只保留命名与目录检查。␍
|
||||
␍
|
||||
### 12.4 特批标记␍
|
||||
␍
|
||||
特批标记是流程格式例外的唯一放行凭证：`〔用户特批 YYYY-MM-DD 跳过××〕`。只有用户明示才能给，用于待办清单条目状态与 roadmap 格（见 12.1、12.2）。␍
|
||||
␍
|
||||
执行技能一律两段式：␍
|
||||
␍
|
||||
1. 对象已有内容 → 直接写入标记。␍
|
||||
2. 对象没有任何内容 → 必须回呈实况，经用户再次确认后才写标记。␍
|
||||
␍
|
||||
标记必须带日期，无日期=非法。流水线闸见合法特批标记放行对应判据。␍
|
||||
@@ -1,92 +1,92 @@
|
||||
# 流程规范（Dungeon Sweeper）
|
||||
|
||||
> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。
|
||||
> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。
|
||||
|
||||
**开工任何批次前必须通读本文。**
|
||||
|
||||
## 1. 分支纪律（worktree 铁律）
|
||||
|
||||
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：
|
||||
|
||||
1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）
|
||||
2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑
|
||||
3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截
|
||||
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限
|
||||
|
||||
## 2. 五段流水线
|
||||
|
||||
一切要做的东西按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**。段间不自动流转，每段转进由用户发令；每段一个技能入口（五者均装于项目 `.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 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
|
||||
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 12 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
|
||||
|
||||
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。
|
||||
|
||||
**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
|
||||
|
||||
## 3. 批次工作流标准清单
|
||||
|
||||
每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：
|
||||
|
||||
**开工前**
|
||||
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑
|
||||
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺
|
||||
3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工
|
||||
|
||||
**环境与基线**
|
||||
4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）
|
||||
5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟
|
||||
|
||||
**实施**
|
||||
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并
|
||||
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/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注
|
||||
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置
|
||||
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
|
||||
14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8
|
||||
|
||||
## 4. 测试执行两入口铁规（细则）
|
||||
|
||||
测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。
|
||||
|
||||
**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。
|
||||
|
||||
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。
|
||||
|
||||
## 5. MC 采集档位细则
|
||||
|
||||
四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）：
|
||||
|
||||
| 档 | 用途 | 上限 | 触发权 |
|
||||
|---|---|---|---|
|
||||
| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 |
|
||||
| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 |
|
||||
| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 |
|
||||
| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 |
|
||||
|
||||
配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。
|
||||
|
||||
## 6. 闸机轮次纪律
|
||||
|
||||
1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验
|
||||
2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可
|
||||
3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批
|
||||
4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）
|
||||
|
||||
## 7. 像素结构件工作纪律
|
||||
|
||||
1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）
|
||||
2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感
|
||||
3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错
|
||||
4. **修复默认附前后对比图+像素审计**，不等用户索要
|
||||
# 流程规范（Dungeon Sweeper）␍
|
||||
␍
|
||||
> 约束范围：一切批次的流程纪律——分支与 worktree、五段流水线、批次工作流、测试执行细则、像素件工作纪律。␍
|
||||
> 分工：硬性红线的一句话索引在 AGENTS.md「硬性红线」；本文承载其操作细则；批次开工前通读本文。␍
|
||||
␍
|
||||
**开工任何批次前必须通读本文。**␍
|
||||
␍
|
||||
## 1. 分支纪律（worktree 铁律）␍
|
||||
␍
|
||||
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：␍
|
||||
␍
|
||||
1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）␍
|
||||
2. **收尾**：批次收口顺序固定为**冻结 → 件核 → 并 master → 跑一次域闸 → 合回**——代码与断言改完即冻结，全仓件核 grep 查残留；master 已被别的批次推进时先 `git merge master` 解冲突（必须在跑闸之前，闸跑完再并＝那次闸白跑），然后按本批改动域跑**一次** `tools/run_all_gates.sh`（见 §3.9：纯文档批跑 `--docs`），全绿后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支。闸后 `game/` 面不得再改一个字节（回执作废须重跑），只允许追加 `reports/`、`design/` 等非 `game/` 提交。非 loop 批次同此顺序；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑␍
|
||||
3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截␍
|
||||
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限␍
|
||||
␍
|
||||
## 2. 五段流水线␍
|
||||
␍
|
||||
**需求改动**（游戏代码，含随逻辑写/改的测试）按五段流水线走：**登记 → 文档设计／美术设计（两条设计线）→ 写需求卡片 → 迭代编排 → 实现**；工程／文档设计／美术素材三类改动不走写卡与编排段，走「登记 →（如需设计讨论）→ 用户发令直改 → 按改动域跑闸 → 完成删条目」。两层口径（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 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或需求性工程条目的证据指认）③估时与冻结线——所选卡估时按区间**中值**求和（单位工作日、写精确值不取整）：**卡片任何工作量均可编入**（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）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |␍
|
||||
␍
|
||||
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。␍
|
||||
␍
|
||||
**流水线闸**：`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。␍
|
||||
␍
|
||||
## 3. 批次工作流标准清单␍
|
||||
␍
|
||||
每个批次按以下链路执行（本清单是总索引，细则散见各规约；冲突以细则为准，发现清单过时须同批修订）：␍
|
||||
␍
|
||||
**开工前**␍
|
||||
1. **先检索后提问**——先查在册记忆与权威文档，禁把已裁决事项当新问题重问或重踩在册坑␍
|
||||
2. **需求卡片全列备选案**——每个待拍板点列全部备选方案与代价交用户裁决，禁卡片内自行定夺␍
|
||||
3. **用户发开工令才动手**——需求卡片经用户批准（U0）后方开工␍
|
||||
␍
|
||||
**环境与基线**␍
|
||||
4. **独立 worktree+拷导入缓存**——按 §1 建 worktree；先拷主区 `.godot/` 目录与字体 `.import` 边车再跑测试，否则全量重导入资源近似卡死。检出工作区零测试，直接开工（2026-10-22 频率规则）␍
|
||||
5. **涉数值改动先采改前读数**——与改后同随机种子配对比较并写明逐项比对口径；无数值改动禁跑模拟␍
|
||||
␍
|
||||
**实施**␍
|
||||
6. **新功能必配新测试**——新增玩法/机制必须配套新测试套件进 `tests/run_all`；没有对应测试的变更不许合并；并按 test-conventions §8 挂进改动—验收对照表，没有对照表行的行为改动同样不许合并␍
|
||||
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/` 与待办清单；需求卡片必列「关联文档同步面」按两层标注␍
|
||||
12. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置␍
|
||||
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节␍
|
||||
14. **改动级验收闭合**——写卡期列需求侧对照表，实现期补实际对照表（测试文件:行），每个行为改动做撤销证明；合回前独立验收审计。细则=test-conventions §8␍
|
||||
␍
|
||||
## 4. 测试执行两入口铁规（细则）␍
|
||||
␍
|
||||
测试类执行——冒烟、单元测试（tests/run_all）、模拟验证（MC/verifier/调参批量工具）、场景探针等一切跑游戏的验证——只有两个触发入口：①**迭代 loop 开发**（冒烟挂迭代出口/入库闸，loop 内过程性验证属开发工作本身）；②**用户主动点名**。其余会话（问答/调研/文档/审查/零散小改）一律零测试；确需测试支撑结论时先请示，以静态阅读/推理作答并注明未跑测。␍
|
||||
␍
|
||||
**MC/verifier 触发细则**：仅在数值验证场景触发（改数值前后取证）；normal 档为主、perfect 按需；**无数值改动的会话禁跑 MC**；结构位移类「存档锚」须先向用户请示定性再跑；需求卡片预设步骤的前提消失时（如「带值裁定后重锚」实际未投值）停问勿照字面执行。␍
|
||||
␍
|
||||
**分级周期口径**：全部验证闸收编在 `tools/run_all_gates.sh` 一个入口下（**脚本即清单，且即域划分的唯一出处**），分三档——`--code`／`--docs` 按本批改动域只跑该域闸（闸件清单与域划分只写在脚本头部注释，本文不重列）；`--quick` 是全量档的中段自检形态（跳过渲染闸与静态扫描）；**不带参数＝两域全量**，用于一次改动同批混触 `game/` 与文档面。完成出库按所选域全绿，回执由合回闸按 diff 推域强制校验。真人实机目检归用户不进自动闸。␍
|
||||
␍
|
||||
## 5. MC 采集档位细则␍
|
||||
␍
|
||||
四档硬闸（全表与统计精度见 `sim-data/README.md`「MC 采集档位表」）：␍
|
||||
␍
|
||||
| 档 | 用途 | 上限 | 触发权 |␍
|
||||
|---|---|---|---|␍
|
||||
| 一档·调研 | 调研/数值分析 | 总量 >40 | **只能由用户发起**——需求卡片/计划书/agent 均无权授权 |␍
|
||||
| 二档·数值修改验证 | 改数值前后取证 | 总量 ≤40、每档 ≤20 | 数值验证场景 |␍
|
||||
| 三档·小调 | 只测不判 | 总量 ≤20、每档 ≤10 | 数值验证场景 |␍
|
||||
| 四档·微量 | sanity 门，零统计判读 | 总量 ≤5 | 数值验证场景 |␍
|
||||
␍
|
||||
配套纪律：超档=停机呈报，窗口不足如实挂起，禁在二/三/四档下带值结论；改前/改后锚同 seed0 配对、改前锚留盘禁补跑；逐项比对断言零新跑（复验用锚内子集 ≤20）；读数缺陷（零 gameplay/RNG 触碰）禁整套重跑、走事件流重构补算；≥60 局采集先 N=5 pilot 校验字段；二/三/四档会话累计 ≤20 分钟；零数值改动=零 MC；四档仅承接数值验证场景，两入口铁规不变。␍
|
||||
␍
|
||||
## 6. 闸机轮次纪律␍
|
||||
␍
|
||||
1. **孤立验证先行**——新代码/新工具/新断言进全套闸之前，先走通最小可运行路径的 standalone 验证（30 秒级：新断言=单独驱动函数直跑；新工具=最小参数全路径试车含产出落盘；新探针=单 .tscn 直跑）；禁以全套闸首跑充当新码首验␍
|
||||
2. **调试期最窄确认**——出红→修复→确认只跑出红的最小单元（单探针/单套件/单函数）；全套闸每个里程碑步（波/T 段）出口最多一次，红灯补跑只跑红件；修的是全部探针/套件共用的共享件（冒烟包装器、闸机脚本本身）时全套即最小充分单元，注记说明即可␍
|
||||
3. **长批试车**——≥2 分钟的跑批（逐位逐项比对冻结/MC 批/批量模拟）发起前，先用最小参数把工具完整路径（含解析/落盘/写锚全链）跑通一遍再放长批␍
|
||||
4. **开工坑册扫描**——每波/T 段开工前，按要触碰的面扫一遍在册坑（worktree 缓存三件套、--script 模式无 autoload、守卫文本匹配等）␍
|
||||
␍
|
||||
## 7. 像素结构件工作纪律␍
|
||||
␍
|
||||
1. **先抄后造**——画像素结构件前，先从参考素材裁同类结构放大逐像素描述，再实现同款；禁凭印象/第一性原理发明像素结构（art-bible §8.5 参考核验的执行口径）␍
|
||||
2. **验完成径写成像素级视觉判据**——开工前把合格标准写成"X 与 Y 同列收尾/无悬空/无突出"式句子；自检放大最差交界处逐行核像素，不只看整板观感␍
|
||||
3. **±1px 一律坐标推导**——单像素级结构先写坐标推导（哪条线在哪列、谁与谁齐平）留档再写码；禁蒙数试错␍
|
||||
4. **修复默认附前后对比图+像素审计**，不等用户索要␍
|
||||
@@ -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,171 +0,0 @@
|
||||
# 需求卡片——节点图换代收尾批（宿主改名＋验证集清单重生成＋表尾叙事清偿）
|
||||
|
||||
- 批名：节点图换代收尾批｜日期：2026-10-25｜批次性质：非迭代批（测试基建＋数据表注释面；改动面＝game/tests/＋game/data/＋tools/，批末含待办清单条目删除——域档判定按 run_all_gates.sh 自身规则执行）
|
||||
- 估时：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 三条来源条目 | 状态推进＋批完结整条删除 | 写卡段回写「已写卡」；批完结由执行批整条删除（非迭代批可写根清单，做完即删） |
|
||||
|
||||
## 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 卡②」叙事段；表内零改动）
|
||||
- [ ] 里程碑步：按改动域选档跑全套闸——本批 diff 将混触 game/、tools/ 与根清单（批末三条目删除），按 run_all_gates.sh 用法说明的混触规则定档，禁止误选单域档跳过流水线闸；全绿
|
||||
- [ ] 验收对照表 R1–R7 逐条执行，撤销证明记录（变更点／命令／红输出摘要／还原结论）落实现报告
|
||||
- [ ] 产出物落位：`reports/节点图换代收尾批-实现报告-<日期>.md`（含承接计数、退役措辞枚举、直跑条数对拍）、`reports/节点图换代收尾批-代拍板追认单-<日期>.md`、`reports/节点图换代收尾批-反哺点清单-<日期>.md`（≥1 条：test-conventions §8.3 描述句随清单全量化失准）——三份齐方算本卡完结
|
||||
- [ ] 待办清单三条目（验证集清单快照重生成／测试宿主改名／level.tres 表尾注释）整条删除
|
||||
|
||||
## 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/节点图换代收尾批-验收审计-<日期>.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「迁移断言全体」描述句随动列反哺点呈报）
|
||||
+13
-21
@@ -3,13 +3,7 @@
|
||||
r"""pipeline_gate.py — 工作流程流水线闸（待办清单条目状态机＋roadmap 迭代总表＋需求卡片口径＋一次交叉核）。
|
||||
|
||||
职责：机检待办清单条目（标题元数据与可选优先级档名/四属性齐备与旧属性名防回潮/状态词白名单/
|
||||
改动面四档白名单/条件凭据/工程形态证据指认/状态段累积制/特批/零命中）与 roadmap 迭代总表（六列/状态四形态/卡片与报告存在性/编入时间与预计周期的
|
||||
历史行「—」豁免/周期三条线（<5 与 >20 判红、超 10 须带日期特批标记）/单元格白名单/零命中）；「已编迭代↔已写卡段↔迭代行
|
||||
卡片列」交叉核只此一处。2026-10-18 卡片冲突修订批补两条卡片机检：C1 关联文档同步面的
|
||||
文档义务口径（生效 2026-10-17）、C2 设计事实源声明（生效 2026-10-18）——两条都按文件名
|
||||
日期只追新规生效日之后的卡，旧卡属 git 历史留档不回头改。2026-10-21 验收闭合批补 C3：
|
||||
改动—验收对照表的结构检查（生效 2026-10-21）——只查节/列/行/必填格非空，不判断覆盖真假；
|
||||
覆盖真假由独立验收审计判。
|
||||
改动面四档白名单/条件凭据/无设计线段条目的证据指认/状态段累积制/特批/零命中）与 roadmap 迭代总表（六列/状态五形态/卡片与报告存在性/编入时间与预计周期的
|
||||
约束：每红项一行「文件:行号 判据名 一句白话说明」，exit 0=全绿 / 1=有红 / 2=输入件缺失；
|
||||
卡片与报告存在性相对 --repo-root 解析（缺省=本文件上两级）；待办清单与 roadmap 均已为新格式
|
||||
（2026-10-18 数据整改批），本闸已注册进 tools/run_all_gates.sh 文档域（08c 流水线闸）。
|
||||
@@ -29,7 +23,7 @@ SURFACE_WORDS = ("文档", "美术素材", "游戏代码", "工具代码")
|
||||
STATUS_WORDS = (
|
||||
"待文档设计", "文档设计中", "文档设计已闭合",
|
||||
"待美术设计", "美术设计中", "美术设计已闭合",
|
||||
"待写卡", "已写卡", "已编迭代", "待裁决", "已写入",
|
||||
"待写卡", "已写卡", "已编迭代", "待裁决", "已写入", "待执行",
|
||||
)
|
||||
# 这些状态 = 设计未闭合，条目必须带「**缺口**」属性；其余状态不得带
|
||||
GAP_REQUIRED = ("待文档设计", "文档设计中", "待美术设计", "美术设计中")
|
||||
@@ -38,6 +32,7 @@ DOWNSTREAM_WORDS = ("待写卡", "已写卡", "已编迭代")
|
||||
DOC_DESIGN_WORDS = ("待文档设计", "文档设计中", "文档设计已闭合")
|
||||
ART_DESIGN_WORDS = ("待美术设计", "美术设计中", "美术设计已闭合")
|
||||
DESIGN_WORDS = DOC_DESIGN_WORDS + ART_DESIGN_WORDS
|
||||
FANBU_WORDS = ("待裁决", "已写入") # 反哺点专条用词，不走设计线也不走下游序列
|
||||
# 工程形态条目的证据指认形态：审计报告路径／文件:行号址／「证据＝」句／审计 P 编号
|
||||
EVIDENCE_RE = re.compile(r"reports/\S+|[\w/.\-]+:\d{2,}|证据\s*[＝=]|审计\s*P\d")
|
||||
ROADMAP_HEADER = ("迭代代号", "状态", "需求卡片", "编入时间", "预计周期", "实现报告")
|
||||
@@ -73,7 +68,7 @@ SURFACE_SEP_RE = re.compile(r"＋|\+")
|
||||
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+)")
|
||||
|
||||
@@ -189,7 +184,6 @@ def check_status(raw, line, issues, where):
|
||||
words.append(w)
|
||||
if it is not None:
|
||||
iter_no = it
|
||||
downstream = [w for w in words if w in DOWNSTREAM_WORDS]
|
||||
# 同一设计线只留最新一段：并现两段说明推进时忘了收旧段，或把另一条线的段
|
||||
# 误写进本线条目；跨条设计线的未闭合依赖（如文档线已闭合写卡、美术线仍待设计）合法。
|
||||
for track, name in ((DOC_DESIGN_WORDS, "文档线"), (ART_DESIGN_WORDS, "美术线")):
|
||||
@@ -197,9 +191,6 @@ def check_status(raw, line, issues, where):
|
||||
if len(hit) > 1:
|
||||
issues.append((where, line, "设计线段并现",
|
||||
"%s同时出现 %s（同线只留最新一段，§12.1）" % (name, "、".join(hit))))
|
||||
if not downstream and not any(w in DESIGN_WORDS for w in words) and "待裁决" not in words and "已写入" not in words:
|
||||
issues.append((where, line, "状态词非法",
|
||||
"状态行既无设计线段、也不在下游序列、也不是反哺点用词"))
|
||||
return words, iter_no
|
||||
|
||||
|
||||
@@ -291,12 +282,13 @@ def check_todo(text, issues, where, root):
|
||||
issues.append((where, live_line, "正文缺美术凭据",
|
||||
"状态段「美术设计已闭合」在场，但实况清单里没有 "
|
||||
"art-bible 版本凭据（§12.1：证据写正文）"))
|
||||
# 工程形态证据指认：整行无设计段且已进下游段 → 实况必须给得出证据
|
||||
# 无设计线段条目的证据指认：需求性工程条目（待写卡及以后）与直改类条目（待执行）
|
||||
# 都跳过设计线，实况必须给得出证据；反哺点专条不在此列。
|
||||
if (words and not any(w in DESIGN_WORDS for w in words)
|
||||
and any(w in DOWNSTREAM_WORDS for w in words)
|
||||
and not any(w in FANBU_WORDS for w in words)
|
||||
and not EVIDENCE_RE.search(live)):
|
||||
issues.append((where, live_line, "工程形态缺证据指认",
|
||||
"状态无设计段且已进下游段＝工程形态条目，实况须指认证据"
|
||||
issues.append((where, live_line, "无设计线段缺证据指认",
|
||||
"状态整行无设计线段（需求性工程条目或直改类条目），实况须指认证据"
|
||||
"（reports/ 路径／文件:行号址／「证据＝」句／审计 P 编号，§12.1）"))
|
||||
need_gap = any(w in GAP_REQUIRED for w in words)
|
||||
if need_gap and "缺口" not in attrs:
|
||||
@@ -362,7 +354,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):
|
||||
@@ -372,7 +364,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)
|
||||
@@ -381,9 +373,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))
|
||||
|
||||
@@ -28,70 +28,66 @@
|
||||
␍
|
||||
**状态**：待写卡＋已写卡＋已编迭代 37␍
|
||||
␍
|
||||
#### 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/需求卡片-S9类型闸正则修复批-2026-10-24.md（2026-10-24 v1.2（grilling 两轮复核通过），非迭代批，零待裁点；存量清单以开工时盘面清点，实证九址为已知下限）␍
|
||||
␍
|
||||
**改动面**：工具代码␍
|
||||
␍
|
||||
**状态**：待写卡＋已写卡␍
|
||||
␍
|
||||
#### 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 撤销证明口径执行。␍
|
||||
␍
|
||||
**预计改动面（两档，第一条只治标）**：① 治标＝人工跑一次 `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/ 闸机与文档面），零待裁点即可写卡。␍
|
||||
␍
|
||||
**改动面**：文档＋工具代码␍
|
||||
␍
|
||||
**状态**：已写卡␍
|
||||
␍
|
||||
#### 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，文件集可按现行结算文件直接枚举）与④零依赖、技术上可先行，但按「先裁④再动③」整条冻结不先行。（本批为非迭代批）␍
|
||||
␍
|
||||
**改动面**：工具代码␍
|
||||
␍
|
||||
**状态**：待写卡␍
|
||||
␍
|
||||
#### 验证集清单快照重生成——断言索引含退役措辞与旧行号（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）。␍
|
||||
␍
|
||||
**改动面**：游戏代码＋工具代码␍
|
||||
␍
|
||||
**状态**：待写卡＋已写卡␍
|
||||
␍
|
||||
#### 测试宿主改名——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 表尾注释」两件合卡）。␍
|
||||
␍
|
||||
**改动面**：游戏代码␍
|
||||
␍
|
||||
**状态**：待写卡＋已写卡␍
|
||||
␍
|
||||
#### 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，与「验证集清单快照重生成」「测试宿主改名」两件合卡）。␍
|
||||
␍
|
||||
**改动面**：游戏代码␍
|
||||
␍
|
||||
**状态**：待写卡＋已写卡␍
|
||||
␍
|
||||
#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移（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/。␍
|
||||
- 相关文档：design/engineering/（architecture.md「模块归属」节＋「呈现层装配」节、code-conventions §1.3）␍
|
||||
␍
|
||||
**改动面**：文档␍
|
||||
␍
|
||||
**状态**：待文档设计␍
|
||||
␍
|
||||
#### 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 仍有命中能力未拦住）。2026-10-25 规则修订（改动四类）：本件属工程改动（闸件修复，直改类）。执行口径＝修 `tools/audit_type_hints.py:29` FUNC_DECL 正则两洞（①无返回类型声明的声明形态恒失配；②`^(\s*)func` 不认 `static ` 前缀），存量以开工时盘面清点（实证九址为已知下限），验收走撤销证明。原需求卡片按违形退役：结论已回写本条目，卡片删除，全稿查 git 历史（提交 546e5113）。
|
||||
|
||||
**改动面**：工具代码
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### 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 项（不处理则每批重复一次「要么重生成基线、要么被红挡在合回前」）。卡片裁决留档（卡片已违形退役，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/ 闸机面）直改类。
|
||||
|
||||
**改动面**：文档＋工具代码
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### 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，文件集可按现行结算文件直接枚举）与④零依赖、技术上可先行，但按「先裁④再动③」整条冻结不先行。
|
||||
|
||||
**改动面**：工具代码
|
||||
|
||||
**状态**：待写卡
|
||||
|
||||
#### 验证集清单快照重生成——断言索引含退役措辞与旧行号（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 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝走重生成：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）。
|
||||
|
||||
**改动面**：游戏代码＋工具代码
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### 测试宿主改名——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 规则修订（改动四类）：本件属工程改动（测试基建维护，直改类）。执行口径＝git mv 宿主两件（.gd＋.uid）＋改 run_all.gd:90 路径行＋文件内 4 处自引用字面量（:1/:10/:26/:31），断言判据零改动，直跑新名退出码 0 为验收。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。
|
||||
|
||||
**改动面**：游戏代码
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### level.tres 表尾注释含迭代叙事（2026-10-25 登记，来源=审计发现）
|
||||
|
||||
**实况**：工程债证据＝迭代 35 卡② 反哺点⑨：game/data/tables/level.tres 表尾注释写「旧 15 张模板池（3 关 × 5）随迭代 35 卡② 清出」，与 doc-conventions §5 禁写变更叙事有张力；卡② 卡片 T3 明令表尾写模板去向注记，故处置面限于叙事形态（删迭代号、保留图源换代事实句），不删去向事实。2026-10-25 规则修订（改动四类）：本件属工程改动（数据表注释维护，直改类），执行口径＝条目原裁（删迭代号、保留去向事实句、表内零改动）。原需求卡片按违形退役（结论已回写本条目，卡片删除，git 历史可考）。
|
||||
|
||||
**改动面**：游戏代码
|
||||
|
||||
**状态**：待执行
|
||||
|
||||
#### 架构与规范对齐批——代码结构审查发现的文档-实现漂移（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/。
|
||||
|
||||
**改动面**：文档
|
||||
|
||||
**状态**：待文档设计
|
||||
|
||||
#### 死断言候选三条处置——照迁禁删断言的退役或改判待裁（2026-10-25 登记，来源=批次移交）␍
|
||||
␍
|
||||
**实况**：批 B 断言迁移施工验出三条死断言候选（照迁禁删，宿主在座、结构复核通过、拦截能力未证——执行序遮断或执行前提在本机不可达）：① V2-s4 旧单档迁移不变式 `game/tests/system_test.gd:185`（本机磁盘态已固化，可红面「旧档在而槽 1 缺」在生产码变异下不可达；补审 A-2 已补结构例外标签——迁移逻辑本体由 save_manager_domain v0 迁移链断言覆盖）；② V3g 营地入口缺失 `game/tests/system_test.gd:481`（menu campbtn 置 null 后 boot 信号接线先崩，护栏在执行序上被遮断不可达，拦截语义由 boot 崩与前置断言代偿）；③ 区间行上下阶实际流动 `game/tests/unit/core/board_gen_reward_test.gd:297`（守面 `samples` 与 `seen[rid].size()` 为同一字典同引用恒假，系源码自带的测试侧死逻辑、非生产缺陷）。证据＝批B迁移账本 :238/:241/:273（账本已退役，考古＝git 历史——删除批 53075baa，删除前全稿见历史版本 5644d30c）＋冻结基点 `game/tests/验证集清单.md` 头注（commit 1aea9397）。另：核代码补审 C-2～C-6 五件测试增强候选原登记备查于账本 §十五，随账本退役并入本条备查——C-2 计数闸残缝（visible 标志位≠渲染面，隐藏匿名旧钮接回双闸漏过）、C-3 _stage_faces extra 静默吞键（match 无默认臂）、C-4 顺序耦合无守卫（boot_chain 须先于驱动执行；lifecycle_matrix 永久改写槽模板不还原）、C-5 camp 残留档使 V3g 红的原因标注误导（不静默）、C-6 V1a 候选表与 LAYER_CONTRACT 双维护（新增层忘登则漏检盖顶回归）。␍
|
||||
@@ -107,7 +103,7 @@
|
||||
**依赖（单向）**：**强依赖卡④**（场景图素材定稿 + 五界面入口改挂）完成；卡④不依赖本条 ⇒ 排序在卡④之后。**与「营地美术素材怎么生成」无关联**（不影响出图／分层／提示词）。␍
|
||||
␍
|
||||
**缺口**：① 窗口形态与叠层规则定稿（独立全屏页＝场景根隐藏／单一内页切换＝场景根留底）；② **窗口化＝场景根留底 ⇒ 会引出「背景要不要压暗／虚化」**，而该点撞上 art-bible §2（2026-10-22 缩窄后**仍禁情绪表达**，背景压暗属氛围表达仍在禁区）与卡④「缩放虚化禁批内自选」——**须在该批开工前一并裁掉**；③ 五界面各自的返回／关闭钮（卡④ v1.1 已承诺各带一个）。␍
|
||||
- 相关文档：卡④ §9 代拍板域 → 独立成批（呈现层 + 文档轨）；窗口形态与叠层规则写入 `LAYER_CONTRACT` 与 [camp](design/gdd/ux/camp.md)「叠层与开合」节␍
|
||||
- 相关文档：卡④ §9 代拍板域 → 独立成批（呈现层＋文档线）；窗口形态与叠层规则写入 `LAYER_CONTRACT` 与 [camp](design/gdd/ux/camp.md)「叠层与开合」节␍
|
||||
␍
|
||||
**改动面**：文档␍
|
||||
␍
|
||||
@@ -653,7 +649,7 @@
|
||||
- 卡④：reports/需求卡片-营地场景图新建批-2026-10-18.md（v2.3，**2026-10-21 用户令退回美术设计段，非有效卡**，美术设计闭合后重立卡，见缺口）␍
|
||||
- 卡⑤：reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md␍
|
||||
␍
|
||||
**缺口**：卡④（营地场景图）**已退回美术设计段**（2026-10-21 用户令）——美术轨未闭合，按 req-card 第〇步不具写卡资格，现卡 v2.3 为非有效卡，五项前置销号后方可重立卡：P1 美术渠道（**2026-10-22 已裁＝B 插画级新产**，✦ 渠道作者自跑远程生图管线；规格沿用 art-bible §8.1/§8.2 既有裁决）；P2 像素规格（Q6 甲过渡口径已裁，执行归用户线）；P3 点选反馈设计稿（用户线，未受命开工；Agent 曾越权起草 v0.1，已按用户令撤回删除）；P4 参照物（用户后续找）；P5 GDD/art-bible 落文（定稿后用户发令）。销号完毕且美术定稿（样张过审＋art-bible 条款版本）后卡④方可进代码实现波次。␍
|
||||
**缺口**：卡④（营地场景图）**已退回美术设计段**（2026-10-21 用户令）——美术线未闭合，按 req-card 第〇步不具写卡资格，现卡 v2.3 为非有效卡，五项前置销号后方可重立卡：P1 美术渠道（**2026-10-22 已裁＝B 插画级新产**，✦ 渠道作者自跑远程生图管线；规格沿用 art-bible §8.1/§8.2 既有裁决）；P2 像素规格（Q6 甲过渡口径已裁，执行归用户线）；P3 点选反馈设计稿（用户线，未受命开工；Agent 曾越权起草 v0.1，已按用户令撤回删除）；P4 参照物（用户后续找）；P5 GDD/art-bible 落文（定稿后用户发令）。销号完毕且美术定稿（样张过审＋art-bible 条款版本）后卡④方可进代码实现波次。␍
|
||||
␍
|
||||
**改动面**：文档＋游戏代码＋美术素材␍
|
||||
␍
|
||||
@@ -726,7 +722,7 @@
|
||||
␍
|
||||
#### L3 屏壳切换探针的判定被仓库外存档状态污染，跑批绿红不可复现（2026-10-18 登记，来源=审计发现）␍
|
||||
␍
|
||||
**实况**：2026-10-18 卫生批跑全量档时 03 探针 --click 与 04 探针 --full 双双「基线绿→现红」，唯一失效单元是 `game/probe/screen_flow_probe.gd` 的第④步（菜单开新冒险进不去，⑤⑥⑦三条随之因前置不满足连带红）。根因已钉死且与本批及任何代码改动无关：`user://save.json`（主区与所有 worktree 共用同一份、不入 git）里现存一个 `breakpoint` 断点，而 `game/presentation/main.gd:476-482` 按「二轮修改批 A」的用户目检裁决，在 `save_manager.has_breakpoint()` 时弹实底确认框「已有未完冒险（第 N 关）——开新冒险将覆盖旧断点」并直接返回、不开冒险；探针第④步只用前缀匹配找「▶ 开始冒险」并按下、等 3 帧就断言进冒险屏，它隐含假设「存档里没有断点」。三条判据：主区那份未受本批影响的 master（`ea69670c`）单跑同一探针复现完全一样的 7 处；同一 worktree 同一代码把 save.json 临时移开再跑立刻 `PASS — 六步主流程＋回退路径全绿`（跑完存档逐字节还原，sha1 `dd67444c35be` 与移开前一致）；`game/**/*.gd` 自 10-17 那次绿回执 `7ffd1dc0` 之后零改动。断点来源＝上一轮 `ui_click_probe` 或任一会话跑到中途留下的未完冒险（存档账目已累积到 `adventure_total=6`、`level_clear_counts={1:18,2:7,3:4}`）。后果是验证闸的绿红取决于「这台机器上谁最后跑过」，正是 test-conventions §8「判定可靠性优先于覆盖率」所管的同一类缺陷。修复方向两条，均待写卡时定：探针侧自救（第④步前先走弃断点通道，或在确认框上按「开新冒险」再断言）＝改 `game/`；跑批侧隔离（给探针配独立 user 目录）＝改 `tools/probe_gate.sh`，⚠ 此路有一条未验障碍——本日用 `--user-dir` 指到空目录跑该探针，Godot 挂住零输出、超时未出结论，走这条要先查明成因。证据已指认，按 §12.1 工程直入通道跳过设计轨。␍
|
||||
**实况**：2026-10-18 卫生批跑全量档时 03 探针 --click 与 04 探针 --full 双双「基线绿→现红」，唯一失效单元是 `game/probe/screen_flow_probe.gd` 的第④步（菜单开新冒险进不去，⑤⑥⑦三条随之因前置不满足连带红）。根因已钉死且与本批及任何代码改动无关：`user://save.json`（主区与所有 worktree 共用同一份、不入 git）里现存一个 `breakpoint` 断点，而 `game/presentation/main.gd:476-482` 按「二轮修改批 A」的用户目检裁决，在 `save_manager.has_breakpoint()` 时弹实底确认框「已有未完冒险（第 N 关）——开新冒险将覆盖旧断点」并直接返回、不开冒险；探针第④步只用前缀匹配找「▶ 开始冒险」并按下、等 3 帧就断言进冒险屏，它隐含假设「存档里没有断点」。三条判据：主区那份未受本批影响的 master（`ea69670c`）单跑同一探针复现完全一样的 7 处；同一 worktree 同一代码把 save.json 临时移开再跑立刻 `PASS — 六步主流程＋回退路径全绿`（跑完存档逐字节还原，sha1 `dd67444c35be` 与移开前一致）；`game/**/*.gd` 自 10-17 那次绿回执 `7ffd1dc0` 之后零改动。断点来源＝上一轮 `ui_click_probe` 或任一会话跑到中途留下的未完冒险（存档账目已累积到 `adventure_total=6`、`level_clear_counts={1:18,2:7,3:4}`）。后果是验证闸的绿红取决于「这台机器上谁最后跑过」，正是 test-conventions §8「判定可靠性优先于覆盖率」所管的同一类缺陷。修复方向两条，均待写卡时定：探针侧自救（第④步前先走弃断点通道，或在确认框上按「开新冒险」再断言）＝改 `game/`；跑批侧隔离（给探针配独立 user 目录）＝改 `tools/probe_gate.sh`，⚠ 此路有一条未验障碍——本日用 `--user-dir` 指到空目录跑该探针，Godot 挂住零输出、超时未出结论，走这条要先查明成因。证据已指认，按 §12.1 属需求性工程条目，跳过设计线。␍
|
||||
␍
|
||||
**改动面**：游戏代码＋工具代码␍
|
||||
␍
|
||||
|
||||
Reference in new issue
Block a user