rules(规则审阅落地批): 十条评审意见落地——呈报四问/文件头缩窄/禁词表冻结/lean死条文退役/日期批注清除/AGENTS瘦身/分域闸口径/状态栏纯化
- AGENTS.md: 呈报六问改读后自检四问；文件头红线删行数上限与白名单；日期批注清除；回执五况细则挪 process-conventions §3.10；流水线闸过时状态句改事实句 - process-conventions: §1.2 非迭代批改按改动域跑闸；§3.10 承接五况；两处日期批注清除；§2 表格凭据落点改现状清单 - code-conventions: §1.4.1 重写（删 8 行上限/两类白名单/90 文件清偿义务）；§2.1 联动；两处日期批注清除 - test-conventions: 三处日期批注清除（三处实证日期属证据保留） - doc-conventions: §1 lean 死条文删除；§4 词表冻结条款；§12.1 重写（状态行只写状态词；现状=关联文档清单；删括号凭据全部条款）；三处日期批注清除；§5 重复词修复 - 术语表: 用语规范节加词表冻结句 - 06-待办清单: 11 条带括号状态行迁移（括号证据移入现状关联文档清单；待裁决说明并入现状；每条状态行只留状态词） - tools/audit_file_headers.py: 删 R1 行数上限（R0 载体/R2 日期/R3 变更叙事保留） - tools/gdd_lint.py: R2 表格占比判据与 R2_EXEMPT 整体退役（lean 解读对象已亡，只产存量噪音） - tools/doc_term_audit.py: 词表冻结注释 - tools/pipeline_gate.py: 状态栏括号凭据核对废止，新增状态行禁括号判据（点名病因短路）；闭合证据改现状正文核对（卡片路径磁盘存在性+交叉核、文档路径+版本、art-bible+版本） - game/tests/static_scan.sh: S10 注释同步 变异验证（test-conventions §6）：pipeline_gate 注入括号→状态行含括号内容红 exit1；删正文卡片路径→正文缺卡片路径+交叉核红 exit1；audit_file_headers 注入变更叙事→R2/R3 红 exit1、头注 12 行纯说明→0 红（上限停用实证）。坑册新增：未提交工作区禁 git checkout 变异还原（会连带回滚在途改动），须备份文件法。 全批净变化 +155/−146（12 文件）。
This commit is contained in:
DKChan committed
1 parent
880ee91b20
commit
811f988032
12 files changed
+155
-146
No files matched your search
@@ -21,17 +21,13 @@
|
||||
### 1.4 命名 = 领域命名，禁止系统 ID 前缀
|
||||
文件名与类名禁止 `a1_`/`b1_`/`c1_` 等系统 ID 前缀（`a1_board_generator.gd` → `board_generator.gd`）。设计追溯不靠前缀：代码↔设计的追溯由 GDD 文档承担，系统 ID 只作为文档的追溯锚；文件头注不承担追溯职责，不写任何文档链接（§1.4.1）。豁免：D2 schema 类与 autoload；文档/夹具登记名（如 b4_golden）属文档层。
|
||||
|
||||
### 1.4.1 文件头 = `##` 文档注释，介绍本模块，≤8 行，两类白名单制
|
||||
### 1.4.1 文件头 = `##` 文档注释，介绍本模块
|
||||
|
||||
头注的存在性与内容范围以 Python 规范为权威（GDScript 语法近 Python，官方风格指南对文件头零条款，不自造标准）：Google Python Style Guide §3.8.2 明文要求——"Files should start with a docstring describing the contents and usage of the module"（文件应以描述模块内容与用法的 docstring 开头）；PEP 257——模块一般都应有 docstring，摘要压一行。
|
||||
头注以 Python 规范为权威（GDScript 语法近 Python，官方风格指南对文件头零条款，不自造标准）：Google Python Style Guide §3.8.2——文件应以描述模块内容与用法的 docstring 开头；PEP 257——模块一般都应有 docstring，摘要压一行。载体只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），头注以说清模块为度，长度不设硬限。
|
||||
|
||||
载体与上限：只用 `##` 文档注释（Godot 官方载体，进编辑器 F1 帮助），总行数 ≤8（不含空行，从文件首个非空行到首个非注释代码行）。
|
||||
黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读迭代实现报告；与其他文档或其他文件头重复的内容——零新信息不写；一切文档反向链接——「实现 GDD：xxx」「指路：架构见 xxx」一类全部废止，代码↔设计追溯由 GDD 文档承担。
|
||||
|
||||
白名单（只许两类）：①职责摘要——这是什么，一句话；项目语境（垂直切片状态/验证目标）以括号并入本行。②使用约束——使用本文件前必须知道的禁令与边界，每条一行。
|
||||
|
||||
黑名单（出现即违规）：日期与变更叙事——改动史查 `git log`/`git blame`，变更背景读迭代实现报告；与其他文档或其他文件头重复的内容——零新信息不写（pyguide §3.8.2.1）；场景结构、生命周期等代码机制描述——"Never describe the code"（pyguide §3.8.5）；一切文档反向链接——「实现 GDD：xxx」「指路：架构见 xxx」一类全部废止，代码↔设计追溯由 GDD 文档承担。
|
||||
|
||||
机器闸：`tools/audit_file_headers.py`（static_scan S10：行数上限+黑名单机械可判子集）。存量头注按白名单清偿（约 90 文件，清偿批进行中）；清偿落地后闸增补「头注必须 `##` 开头」锁死载体；此间新增/改动的文件头必须即合规。
|
||||
机器闸：`tools/audit_file_headers.py`（static_scan S10：变更叙事黑名单机械可判子集）。行数上限与类别白名单已停用。
|
||||
|
||||
### 1.5 禁止事实约定
|
||||
任何"大家默认这么做"的惯例必须成文进本文件（或 AGENTS.md）才算存在。写代码时发现未成文但必须遵守的约定 → 当场补条文，不许靠惯性延续。
|
||||
@@ -41,7 +37,7 @@
|
||||
## 2. 契约纪律——跨层/跨类调用的语义
|
||||
|
||||
### 2.1 信号与事件契约成文
|
||||
每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行；计入 §1.4.1 的 8 行上限，装不下时迁契约文档。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
|
||||
每个跨类信号：参数语义、发送时点、消费方依赖，必须在发送方 `##` 文档注释成文，每信号一行；装不下时迁契约文档。状态机的每次迁移路径都必须发出对应事件——**缺一条路径的事件 = 消费方永久等待 = 软锁**。
|
||||
|
||||
### 2.2 跨层标识符语义单一且成文
|
||||
位置（index）/ 句柄（handle）/ 键（key）是三种不同的东西。跨类传递标识符时，传递方的语义必须与接收方契约逐字一致，禁止凭"当前恰好相等"传值。
|
||||
@@ -68,7 +64,7 @@
|
||||
4. **lambda 捕获循环变量按创建时值**——循环内先落地局部变量再捕获，或用 `bind`。
|
||||
5. **重命名脚本必须同步 `.uid` 文件**；新增 `class_name` 后必须跑一次编辑器扫描刷新全局类缓存，否则 `--headless --script` 模式解析失败。
|
||||
6. **`print` 格式占位符与实参类型必须匹配**（`%d` 配 String = 静默输出字面量）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**（迭代 27——2026-10-17 用户裁写入）——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码（`game/core`+`game/data`+`game/presentation`；smoke/tests 豁免——测量面容器直构是既有惯例）。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
7. **语言纪律已机器化为 S9 类型闸**——`tools/audit_type_hints.py`，执行载体=静态扫描域 S9（`game/tests/static_scan.sh`），退出码 0=归零。扫描面=产品码（`game/core`+`game/data`+`game/presentation`；smoke/tests 豁免——测量面容器直构是既有惯例）。三规则：R1 无类型容器（显式非参数化 `Dictionary`/`Array` 注解）／R2 有值返回缺返回类型（纯副作用缺 `-> void` 属写法面不入闸）／R3 参数缺类型（`_init` 豁免——构造注入面形态自由）。
|
||||
8. **`:= {}` 推断形态不算债**——`var x := {}` 类赋值推断属类型推断合法面，不入 R1 扫描；只有显式写的非参数化容器注解才算无类型容器。
|
||||
9. **行级白名单通道 `# type-hint: ignore`**——豁免该行不入 S9；豁免理由必须随行注明（现行例：`board_generator` 四函数的 db 参鸭子型——typed 参拒冒烟夹具 `_BoardRowStub` 注入）。
|
||||
10. **`# rng-seed-exempt` 标记豁免通道**——S1/S2 随机函数扫描对该行豁免；限定用途=非玩法 RNG 消费面的引擎熵（现行例：组合根种子编辑框空态取 `randi()`——建种子不进玩法封闭流）。
|
||||
@@ -96,5 +92,5 @@
|
||||
## 6. 流程纪律
|
||||
|
||||
1. **大改动三段走**：设计稿/伪代码 → 用户审阅 → 实现；实现禁止先于审阅。改动明细只进 git 提交信息，README 与代码内不写修改记录（doc-conventions 第 5 节「禁写变更记录」）。
|
||||
2. **实现批完成后的登记义务**：06 条目按 doc-conventions §12.1 推进状态，批次过程与结论进 git 提交信息与 `reports/`（2026-10-18 用户裁：根目录会话状态文件已废除，禁止再在其中登记条目）。
|
||||
2. **实现批完成后的登记义务**：06 条目按 doc-conventions §12.1 推进状态，批次过程与结论进 git 提交信息与 `reports/`（根目录会话状态文件已废除，禁止再在其中登记条目）。
|
||||
3. **呈现层缺陷的教训回写 D1 GDD 设计输入**（信号载荷 schema / 场景级测试 / 时点状态可见性）。
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
**读者测试是每个小节的验收标准**：只读这一节，回答三个问题——这节管的是谁/什么？在什么情况下？会发生什么？答不出来，就重写这一节，而不是给看不懂的地方补注释。
|
||||
|
||||
旧体系 lean 格式六条硬规则已停用（其解读对象 `design/archive/` 旧档已删除，现无适用文档；原表格占比 30% 口径随之作废）。`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性仍是第一内容质量门，lint 是格式机检面，两者并行。
|
||||
`tools/gdd_lint.py` 现为现行文档机检三闸之一（gdd_lint / doc_link_audit / doc_term_audit，分级周期口径见 AGENTS.md）；可读性是第一内容质量门，lint 是格式机检面，两者并行。
|
||||
|
||||
## 2. 白话写作规则
|
||||
|
||||
@@ -56,6 +56,8 @@
|
||||
|
||||
**通行检验标准**：读者是业内人但没读过项目历史——需要作者解释才懂的词不合格，必须展开成完整白话句（换新名词不算改，展开才算改）。**写后自查**：凡自己都要停顿才能想起意思的词，一律展开。
|
||||
|
||||
**词表冻结**：doc_term_audit 与术语表「用语规范」节的禁用词表不再扩充；扩表唯一入口＝用户实读反馈并经用户裁决，由非迭代批写入，禁 agent 自行增词。
|
||||
|
||||
## 5. 结构纪律
|
||||
|
||||
| 规则 | 内容 |
|
||||
@@ -70,10 +72,10 @@
|
||||
|
||||
**数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。
|
||||
|
||||
**登记处唯一性（2026-10-19 用户裁）**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：
|
||||
**登记处唯一性**：`design/registry/`（`entities.yaml`／`architecture.yaml`）已注销删除，禁再建第二处事实登记——术语进 术语表、数值进 `.tres`、架构进 架构文档、影响面靠全仓搜索概念规范名得出。强制收口条款：
|
||||
|
||||
1. **双写失同步禁止**——任何数值变更必须同时同步引用该数值的 GDD 表格正文、`data/tables/` 行值与 schema 校验域、相关待办清单现状——三类之一未更新即视为变更未完成。
|
||||
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，只留 schema 模板与取值域，指针指向 `.tres` 对应行键。
|
||||
2. **调参表锁数后删现行值列**——仅留 schema 模板与取值域，指针指向 `.tres` 对应行键。
|
||||
3. **覆盖范围** = 奖励/状态/敌人/技能/充能/护甲等级/区间掷点/难度曲线/D_ref 等所有数值字段。
|
||||
4. **维护通道** = 「设计批 → 同步批」两段式；数值表改完不等于修订完成。
|
||||
5. **压缩/换装批** = 「`.tres` 落批 + 切片 smoke 跑通 + GDD 表格改为只留取值域与 `.tres` 指针 + 待办清单刷新」四步全收才记版本号。
|
||||
@@ -101,7 +103,7 @@
|
||||
|
||||
## 10. 会话状态——仓库根不设状态文件
|
||||
|
||||
**2026-10-18 用户裁：根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。
|
||||
**根目录 `active.md` 连同「会话状态唯一状态源」这条规矩一起废除。** 判据来自对 869 个历史会话的读写统计：整文件被读 448 次、平均每次 14 KB 进上下文，但会话里关于它的思考九成花在「追加条目前先查尾部编号防撞号」与「并行会话同时改它导致的合并冲突与丢弃」上，明确写「从它所载内容得知某事实」的只有 20 个会话；文件 45 KB 里约 95% 是别处已有权威源的重复说法、已失真陈述或已完结批次的历史叙述。体量闸只能测条目数与死链，测不出语义失真：10-15 清到 8.6 KB／3 条，10-17 已回到 40 KB，用户为「只写不删」连续三次发火，规矩照样失效。
|
||||
|
||||
废除后的分工：**现在做什么**看根目录 `roadmap.md` 顶部「当前位」节；**待办与待裁**看 [06-待办清单](../gdd/06-待办清单.md)（唯一登记处）；**批次过程与结论**看 git 提交信息与 `reports/`；**跨会话教训**看记忆库。禁止在仓库根新建同类状态文件，也禁止在任何文档里另设「当前状态快照」节——两处记同一件事必然漂移，这正是本次统计查出七条失实陈述的成因。
|
||||
|
||||
@@ -120,7 +122,7 @@
|
||||
| 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 |
|
||||
| 暂存地非档案库 | 中间文档有两处暂存地，入内文件默认到期即死：`reports/`（需求卡片＋迭代产出物）、`design/research/`（调研/提案/评估/历史验收）。`design/` 各子目录不留验证截图——截图属一次性凭据，结论写进 06 或需求卡片后图像即弃（在途图放 `artwork/`，整目录不入 git）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` |
|
||||
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`06-待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 |
|
||||
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（2026-10-17 用户裁：实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |
|
||||
| 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 |
|
||||
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 |
|
||||
|
||||
**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。
|
||||
@@ -142,37 +144,34 @@
|
||||
正文四属性模板：
|
||||
|
||||
```
|
||||
**现状**：现在缺什么、为什么是问题（关键处带 file:line 或文档指针）。工程直入条目必须在现状里指认证据（bug 证据或工程债条目）。
|
||||
**现状**＝关联文档清单，一行一件：它是什么（设计定稿／需求卡片／相关文档）＋文件路径＋版本号与日期（闭合类文件必带）；必要时在清单前配一句现状说明。机制解释与论证过程不写在这里，归权威文档。路径用普通文本或行内代码书写，机器可搜索。工程直入条目必须在现状里指认证据（bug 证据或工程债条目）。
|
||||
**缺口**：还差哪一次设计讨论／哪份设计产物才能写卡。尚有未闭合的设计轨时此属性必须存在；全部设计轨闭合后删除。
|
||||
**归属**：主责系统文档或线别。
|
||||
**状态**：按状态机取词。
|
||||
```
|
||||
|
||||
状态机按标题里的设计面分轨，状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；已过去的段一律保留、禁删——闭合凭据要留在行内，编排四查与开工核验拿它比对。每段各自按状态词白名单与凭据规则校验，＋号只作状态段连接符。
|
||||
状态机按标题里的设计面分轨，状态一律取下例用词。状态行按**状态段累积制**书写：条目每推进一段，就把新状态段接在状态行末尾，段与段用＋号连接，书写顺序=推进顺序；已过去的段一律保留、禁删——状态履历供编排四查与开工核验比对。每段各自按状态词白名单校验，＋号只作状态段连接符。
|
||||
|
||||
```
|
||||
各轨推进序列（双轨条目设计阶段两段并列推进，一文档轨一美术轨）：
|
||||
文档轨：待文档设计 → 文档设计中 → 文档设计已闭合（凭据=文档路径+版本号，
|
||||
例：文档设计已闭合（design/gdd/systems/xxx.md v1.2））
|
||||
美术轨：待美术设计 → 美术设计中 → 美术设计已闭合（凭据=样张过审、art-bible 条款版本，
|
||||
例：美术设计已闭合（样张过审、art-bible v3.x））
|
||||
双轨条目设计阶段示例：文档设计已闭合（design/gdd/systems/xxx.md v0.6）＋美术设计中
|
||||
进入下游段（待写卡及之后）的前置条件——双轨：两个设计轨段都在场且都已闭合（带凭据）；单轨：本轨闭合段（带凭据）在场
|
||||
下游共用序列：待写卡 → 已写卡（reports/ 下的需求卡片路径）→ 已编迭代 N → 完成即整条删除
|
||||
单轨累积示例（已编迭代）：文档设计已闭合（design/gdd/systems/xxx.md v1.2）＋已写卡（reports/需求卡片-xxx.md）＋已编迭代 2
|
||||
文档轨：待文档设计 → 文档设计中 → 文档设计已闭合
|
||||
美术轨：待美术设计 → 美术设计中 → 美术设计已闭合
|
||||
进入下游段（待写卡及之后）的前置条件——双轨：两个设计轨闭合段都在场；单轨：本轨闭合段在场
|
||||
下游共用序列：待写卡 → 已写卡 → 已编迭代 N → 完成即整条删除
|
||||
单轨累积示例（已编迭代）：文档设计已闭合＋待美术设计＋已写卡＋已编迭代 2
|
||||
```
|
||||
|
||||
凭据括号内禁用＋号——＋只作状态段连接符，凭据内需要并列多项时用顿号（如上例「样张过审、art-bible v3.x」），用＋会被流水线闸误判为状态段。已编迭代 N 段的交叉核依据=同状态行内「已写卡」段括号里的卡片路径。
|
||||
状态行只写状态词：去掉特批标记与「（备选）」后缀后，残留任何括号即违规。闭合类状态词（文档设计已闭合／美术设计已闭合／已写卡／已写入）的证据——设计定稿路径+版本、art-bible 条款版本、需求卡片路径、落点文档+版本——一律写在现状的关联文档清单里，由流水线闸到正文核对；已编迭代 N 段的交叉核依据＝现状清单里的需求卡片路径。
|
||||
|
||||
三条特殊通道：
|
||||
|
||||
| 设计面 | 通道规则 |
|
||||
|---|---|
|
||||
| 工程直入 | 缺陷修复／工程债／测试基建／重构四类工程条目：登记即「待写卡」，凭现状里指认的证据跳过设计轨 |
|
||||
| 反哺点专条 | 待裁决 → 已写入（落点=文档+版本）→ 删除 |
|
||||
| 反哺点专条 | 待裁决 → 已写入 → 删除 |
|
||||
| 备选库条目 | 暂不排期、留在备选库的条目：状态词后缀「（备选）」 |
|
||||
|
||||
「已闭合」不带凭据不算合法状态词。特批标记见 12.4。
|
||||
特批标记见 12.4。
|
||||
|
||||
### 12.2 roadmap 迭代行格式
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
主工作区（master 检出）只作合并落点，一切开发/设计改动禁止直接发生在主工作区：
|
||||
|
||||
1. **开工**：每批次先建独立 worktree：`git worktree add ../g-plan2-<任务名> -b <任务分支>`；所有改动与验证都在 worktree 内进行（未跟踪文件不会出现在新 worktree，需手工搬运）
|
||||
2. **收尾**：迭代 loop 批次验证全绿（冒烟+场景探针）后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支；合回前若 master 已被别的批次推进，先在分支里 `git merge master` 解冲突、重跑本域闸再合回。非 loop 批次默认完成不跑闸（两入口铁规），用户点名或当场问
|
||||
2. **收尾**：迭代 loop 批次验证全绿（冒烟+场景探针）后在主工作区 `git merge --no-ff <任务分支>`，再 `git worktree remove`+删分支；合回前若 master 已被别的批次推进，先在分支里 `git merge master` 解冲突、重跑本域闸再合回。非 loop 批次合回前同样按本批改动域跑闸（见 §3.10：纯文档批跑 `--docs`）；游戏类测试（冒烟/单测/MC/探针）对它默认零执行（两入口铁规，见 §4），用户点名或当场问才跑
|
||||
3. **豁免面**：仅 `.zcode/`（钩子与配置）与 `.qoder/`（本机 harness 配置）允许主工作区直改——两份实测均不入 git（走 worktree 反而带不进去，改动只对本机生效）；其余一律走 worktree，主工作区 git commit 被钩子拦截
|
||||
4. 本铁律由 PreToolUse 钩子 `.zcode/hooks/worktree-guard.sh` 强制兜底；钩子只约束 agent，用户手工改动不受限
|
||||
|
||||
@@ -21,14 +21,14 @@
|
||||
| 段 | 入口技能 | 产出 | 出入口铁律 |
|
||||
|---|---|---|---|
|
||||
| 一·登记 | 无（闸管格式） | 06-待办清单条目 | 条目=标题登记元数据＋正文四属性（现状/缺口/归属/状态）；标题登记后不再变，正文随进程演进。格式与状态机权威=doc-conventions 第 12 节 |
|
||||
| 二·文档设计／美术设计 | doc-design（文档轨，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从 06 取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；轨闭合凭据记入 06 状态（文档轨=文档路径+版本号，美术轨=样张过审+art-bible 条款版本） |
|
||||
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程直入四类（缺陷修复/工程债/测试基建/重构）凭证据跳过设计轨；卡片必经 grilling 多轮复核、零待裁点才成立；写完在 06 状态记「已写卡」＋卡片路径（防遗忘） |
|
||||
| 二·文档设计／美术设计 | doc-design（文档轨，兼任反哺点写入）／asset-ingest（美术录入；样张素材由用户主导产出） | GDD 文档或 art-bible／过审样张素材 | 用户提起或从 06 取出；会话内进行、用户主导、禁无监管自跑；经用户点头确认心智一致才许写入文档；完成判据=待裁点清零，带未裁点的是讨论稿；轨闭合凭据记入 06 现状清单（文档轨=文档路径+版本号，美术轨=art-bible 条款版本） |
|
||||
| 三·写需求卡片 | req-card | 需求卡片 | 轨闭合后用户发令；新玩法/新系统/新内容必须有设计定稿前置，例外=工程直入四类（缺陷修复/工程债/测试基建/重构）凭证据跳过设计轨；卡片必经 grilling 多轮复核、零待裁点才成立；写完在 06 状态记「已写卡」，卡片路径记入现状清单（防遗忘） |
|
||||
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查：①每卡卡片文件存在 ②每卡设计闭合凭据齐（或工程直入证据）③总估时 ≤2 周 ④写完 roadmap 行后跑流水线闸确认绿；编入未完成迭代，新开迭代行经用户确认 |
|
||||
| 五·实现 | iter | 代码与配置，可运行的游戏 | 需求卡片永不单独施工，统一由用户指定迭代号触发（=U0 开工令），按 iter 技能与本文 §3 执行；**本段是代码实现批：禁写 `design/` 与根规则文件，产出物只落 `reports/`（见 §3 第 13 条）**；设计权威文档（GDD/art-bible）批内一律不更新；完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
|
||||
|
||||
**实现段零裁断**：实现段的输入在编排段出口已锁死（卡片零待裁点＋设计闭合凭据齐＋编排四查过）。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、06 状态回退＋缺口补记，退回上游；禁自答、禁内联提问求裁断；该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级（自救重试／记录继续／停机呈报）。代拍板白名单保留：授权发生在卡片审问阶段，实现只执行预授权；批后追认单=备案确认。
|
||||
|
||||
**流水线闸**：`tools/pipeline_gate.py` 机检 06-待办清单与 roadmap 两文件的格式与互相引用；将注册进 `run_all_gates.sh` 文档域（注册归第二批，本批不注册）。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
|
||||
**流水线闸**：`tools/pipeline_gate.py` 机检 06-待办清单与 roadmap 两文件的格式与互相引用；已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
|
||||
|
||||
## 3. 批次工作流标准清单
|
||||
|
||||
@@ -50,10 +50,10 @@
|
||||
9. **验收函数变异验证**——新增/改写的验收函数（冒烟断言/探针自检/闸机判据）必须配一次变异验证：故意把被测件改坏成该类缺陷形态 → 跑最窄那道闸确认变红 → `git checkout` 精确还原；变异点/跑的闸/红输出摘要/还原结论四件记入实现报告变异验证记录表；**无变异红记录的断言不写「已验收」，只写「已实现，拦截能力未证」**（细则见 test-conventions §6）
|
||||
|
||||
**完成**
|
||||
10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时的变异验证（test-conventions §6），闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底
|
||||
10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验（五况拦截：缺回执／quick 模式／回执 commit ≠ HEAD／域不覆盖本次改动／含新增红）。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时的变异验证（test-conventions §6），闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底
|
||||
11. **合并后主区按域复跑**——合并可能引入冲突或环境差异，落回 master 后按本批改动域复跑：触及 `game/` 的批＝全量复跑（维持）；纯文档域批＝复跑文档域档（秒级），不再全量
|
||||
12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（2026-10-18 用户裁，见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`）实现批禁写，见 §13
|
||||
13. **文档同步闸（2026-10-17 改口径：实现批禁写文档）**——实现批**禁写 `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/` 与 06；需求卡片必列「关联文档同步面」按两层标注
|
||||
12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`）实现批禁写，见 §13
|
||||
13. **文档同步闸（实现批禁写文档）**——实现批**禁写 `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/` 与 06；需求卡片必列「关联文档同步面」按两层标注
|
||||
14. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置
|
||||
15. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
|
||||
|
||||
|
||||
@@ -66,7 +66,7 @@
|
||||
|
||||
**判据强弱分层**：同一缺陷面往往需要多件配合——**可见性／状态源类**缺陷由 `is_visible_in_tree`、树序、状态源取值的**运行期断言**抓；**内容／观感类**缺陷由 **golden 逐像素比对**抓；**占比／统计类**判据（墨色占比、纹理幅度）只能兜「整框空白／整框糊／压 busy 纹理」，是补充不是主力。写卡时按此分层配齐，别指望一条断言包打。
|
||||
|
||||
## 7. 判定三硬闸——闸承载的构造义务（迭代 29 三硬闸 2026-10-17 用户裁升格为纪律）
|
||||
## 7. 判定三硬闸——闸承载的构造义务（迭代 29 起）
|
||||
|
||||
任何**新增或改写的闸承载**（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归架构文档「测试与质量域」节（本文不另列闸件清单）：
|
||||
|
||||
@@ -76,9 +76,9 @@
|
||||
- 负面套件（测试目标就是产生错误输出）仅可豁免第 2 闸，且须在 manifest 显式标记，其余两闸照判。
|
||||
- 子进程输出须经系统命令解释器重定向落盘再读——`OS.execute` 的输出管道在本机恒空。
|
||||
|
||||
**新写测试件全类型标注**（2026-10-17 用户裁写法纪律）——新写的测试件（冒烟断言／探针／单测）参数、返回值、容器一律带类型标注，与 S9 对产品码的要求同型；存量不强制清扫，被批次触碰时顺带换代。暂不机器闸（S9 扫描面=产品码，smoke/tests 豁免是测量面直构惯例的既有裁量）。
|
||||
**新写测试件全类型标注**——新写的测试件（冒烟断言／探针／单测）参数、返回值、容器一律带类型标注，与 S9 对产品码的要求同型；存量不强制清扫，被批次触碰时顺带换代。暂不机器闸（S9 扫描面=产品码，smoke/tests 豁免是测量面直构惯例的既有裁量）。
|
||||
|
||||
## 8. 判定可靠性优先于覆盖率（迭代 29 核心命题 2026-10-17 用户裁成节）
|
||||
## 8. 判定可靠性优先于覆盖率（迭代 29 核心命题）
|
||||
|
||||
- 「跑一遍没崩＝通过」无效：测试绿只证明**当前代码没犯这个错**，不证明**犯了这个错会被抓住**；断言存在不等于断言执行。
|
||||
- **脚本错误会静默中断所在函数的剩余断言，而套件仍报全绿**（机制事实）：GDScript 无脚本错误陷阱 API，错误不改进程退出码、不计失败数。三处实证：①2026-09-19「309 项 0 失败」实为断言未跑全（状态记录 83）；②敌人表行集纪律 10 条断言因定型数组赋值错误从未执行（迭代 29 修复后两条正向见红＝夹具本缺锚行）；③`Callable` 形参类型写错致解析函数返回 null、后续断言整段蒸发。
|
||||
|
||||
Reference in new issue
Block a user