diff --git a/AGENTS.md b/AGENTS.md index e32a5bf6..cd6a56a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,11 +44,11 @@ | 批次开工 / 流程纪律 | `design/engineering/process-conventions.md`——车道铁律（一切改动走独立 worktree，主区只作合并落点）、合回后远端 CI、五段流水线、批次清单、改完即测与 MC/闸机细则、像素纪律 | | 流水线段入口 | 技能对照——doc-design=文档设计（兼任反哺点落文）／asset-ingest=美术录入／req-card=写卡／iter-plan=迭代编排／iter=实现（五者均装于项目 `.zcode/skills/`）；登记不立技能；批后收尾与中间文档退役=batch-closure（同一目录）；格式与状态机权威=`design/engineering/doc-conventions.md` §12 | | 定代码方案 / 写代码 / 改代码前 | `design/engineering/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） | -| 定测试方案 / 写测试 / 改测试前 | `design/engineering/test-conventions.md`——探针标配 / 回归断言 / 提交前验证 / 验收清单落码 | +| 定测试方案 / 写测试 / 改测试前 | `design/engineering/test-conventions.md`——探针标配 / 回归断言 / 提交前验证 / 验收清单落码；测试工具手册与闸机操作＝`game/tests/README.md` | | 定文档方案 / 写文档 / 改文档前 | `design/engineering/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 | | 概念切分与互链 | `design/engineering/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | | 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | -| 架构（唯一事实源） | `design/engineering/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 | +| 架构（唯一事实源） | `design/engineering/architecture/architecture.md`（只写约束面：分层/模块归属/数据流/API 边界；实现现状归代码与头注，闸清单归 `game/tests/README.md`）——历史决策沿革查 git commit log，不另设决策文档；修订须用户发令 | | 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则（概念面）= 各系统 owner 文档；取值域与字段契约 = `game/data/schemas/*.gd`。冲突须显式提出，禁默默改值 | | 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` | @@ -122,7 +122,7 @@ - 文件头 = `##` 文档注释，介绍本模块是什么；禁写变更叙事（改动史查 git log）；禁文档反向链接（code-conventions §1.4.1） - 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径 - RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流 -- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log +- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`（只写约束面：分层/模块归属/数据流/API 边界；实现现状归代码与头注）；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log；架构文档写权限＝用户专属，agent 与技能只读（2026-11-07 用户裁） - Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退 - spec-AC 一致性——规约与验收标准禁止在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离） - 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节） diff --git a/design/engineering/code-conventions.md b/design/engineering/code-conventions.md index 2bfbb738..3384eabc 100644 --- a/design/engineering/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -37,7 +37,7 @@ ### 1.6 拆分交接与封装边界 本节管拆分类改动的交接面与封装面，与 §1.1 拆分判据（职责轴）配合使用：§1.1 管怎么切，本节管切完之后件与件之间怎么往来。 -1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——架构文档「战斗编排域拆件定稿」节 BoardInstaller 行在册）。 +1. **拆分交接定义**：拆出一个新类时，交付物必须同时写明职责边界与交接定义——新类构造时需要哪些依赖，由拆出它的类在构造它时一次交给它；新类需要回调拆出它的类的哪些方法，以 Callable 形式交付。两者齐备才算拆分合格。为什么：只切职责不定义交接，新件会伸手回原类内部拿东西，封装从拆件那天起就破了。正面先例＝装板件的引用束注入（表数据、随机流、装板所需对象与出错回调一次性交付——先例本体＝`game/core/board_installer.gd` 构造面，沿革 git 历史可考）。 2. **封装边界**：任何代码不得访问其他对象的下划线成员；跨对象往来只走公开方法与属性。为什么：下划线只是命名约定，语言不设防、无编译期检查——此条是封装硬纪律，违者即红。 --- diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index 1d66a3ba..c52b162b 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -63,11 +63,11 @@ | 规则 | 内容 | |---|---| | 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` | -| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log | +| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界——只写约束面：难以改变的分层、依赖规则、边界契约与关键决策；实现现状归代码与代码头注，实现历史归 git commit log）；禁建第二份架构文档；**架构文档写权限＝用户专属**（2026-11-07 用户裁：agent 与技能只读，修订须用户发起） | | 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | | 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | -| 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（`.gd`／`.py`／`.sh` 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（`game/data/tables/*.tres` 与 `game/data/schemas/` 的表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归 `architecture.md`；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝`tools/run_all_gates.sh` 头部 | +| 禁实现内容 | 系统文档与概念文档全文禁写实现细节——代码路径（`.gd`／`.py`／`.sh` 与运行时文件路径）、测试文件名、断言名、类名／方法名／信号名／常量名／调试与遥测入口名、提交号一律不出现；唯一例外＝数据索引（`game/data/tables/*.tres` 与 `game/data/schemas/` 的表路径与表名、表字段名与表内枚值、存档键、封闭词表标签）。实现事实归代码与代码头注（2026-11-07 用户裁，架构文档只写约束面）；验收标准只写玩家或系统可观测面。本行由文档域闸的能力审计机检两个可判死的面（带后缀路径、反引号调用形态），其余靠写卡段人工核对；闸件清单与域划分的唯一出处＝`tools/run_all_gates.sh` 头部 | | 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）——此前半句全域适用；后半句（其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值）适用域＝`design/gdd/**`（GDD 设计文档；2026-11-07 用户裁收窄——美术圣经与 UX 呈现规格层为可带值参考层，不在后半句约束内）。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | | 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 | | 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | diff --git a/design/engineering/test-conventions.md b/design/engineering/test-conventions.md index 0550d090..ed7a6974 100644 --- a/design/engineering/test-conventions.md +++ b/design/engineering/test-conventions.md @@ -68,7 +68,7 @@ ## 6. 判定三硬闸——闸承载的构造义务 -任何**新增或改写的闸承载**（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归架构文档「测试与质量域」节（本文不另列闸件清单）： +任何**新增或改写的闸承载**（闸脚本／批跑编排／探针入口）必须三闸齐备；现行各闸状态登记归 `game/tests/README.md`（测试工具手册，本文不另列闸件清单）： 1. **退出码为唯一权威判据**——输出里的 PASS 串只作附加判据不作判据主体；打印 PASS 后 `quit(1)` 必须判红。 2. **SCRIPT ERROR / Parse Error 扫描面在位**——GDScript 脚本错误不改进程退出码、不计失败数（机制事实见 §7），错误标记必须扫输出，且判据必须覆盖「跑了但半途脚本错误」态——退出码 0 但输出缺预期签名同样判红（防静默退出）。 @@ -116,7 +116,7 @@ **判据出处行锚（2026-11-05 立，自 2026-11-05 起对文件名日期不早于该日的需求卡片生效；旧卡不回头改，被编入迭代开工前由写卡段按本粒度补挂）**：对照表「需求点」列每行必须带**判据出处行锚**——该行验收判据所依据的现行文档句子，格式「`<文档相对路径>:<行号>`」。现行文档＝`design/` 全域现行文档（含 `ux/` 交互规格与 art-bible 的判据行）；已退役的需求卡片不是现行文档，不得充当判据出处。作用＝断言预期值从规格句抄出，不从实现反推：实现行为与规格句冲突时断言红；规格缺席的行写不出锚，即停卡退回写卡段（那是需求澄清缺口，不是测试缺口）。机检＝`tools/pipeline_gate.py` 判据 C5（锚格式与指向存在性，按卡文件名日期分流）＋`tools/capability_audit.py` 链式锚检查（断言→套件→能力行→系统文档，见 §8.9）。 -**测试函数的判据出处注记（2026-11-06 立）**：`game/tests/**` 与 `game/probe/**` 内每个**验证函数**（函数体含 `check(`／`check_quiet(`／`_problems.append(`／`push_error(` 判定调用的函数——定义行与 `_check(` 前缀不作判定计）必须带至少一条**判据出处注记**，格式「`# oracle: :<行号> <判据一句>`」——指针在前、判据摘要句在后，断言预期值的出处随断言走：断言红时读注记即达出处文档句，零查表。指针空间＝`design/` 全域现行文档（行为测试锚 owner 系统文档「验收标准」句或 `ux/` 规格句；惯例类测试〔封装扫描、判定通道纪律、驱动契约〕锚规约条款行）；`game/sim/` 不进扫描面（测量面直构惯例）。与链式锚的分工：链式锚（断言→套件→能力行→系统文档）不变、属义务清单层；本注记属执行证据层、写在断言文件内，非独立账本（§8.9 法则 4 不变）。写新测试函数时当场挂注记；被指规格句改行号时随批维护指针——死指针即红。局限如实声明：注记是被动文本，句内容改而行数不变时机检抓不到（与卡片判据 C5 同限）。机检＝`tools/capability_audit.py` 判据出处注记道（覆盖检查＋指针存在性；扫描面零文件自检红）。规格缺席写不出锚＝发现规格缺口：记发现不造锚、收尾呈报，禁锚到非现行文档凑数。 +**测试函数的判据出处注记（2026-11-06 立）**：`game/tests/**` 与 `game/probe/**` 内每个**验证函数**（函数体含 `check(`／`check_quiet(`／`_problems.append(`／`push_error(` 判定调用的函数——定义行与 `_check(` 前缀不作判定计）必须带至少一条**判据出处注记**，格式「`# oracle: :<行号> <判据一句>`」——指针在前、判据摘要句在后；锚形态两档：行号锚（默认）与节锚（`「节名」<行关键词>`）——所指文档整节重排时同批把行号锚重锚为节锚，免行号漂移（2026-11-07 架构收窄批立），断言预期值的出处随断言走：断言红时读注记即达出处文档句，零查表。指针空间＝`design/` 全域现行文档（行为测试锚 owner 系统文档「验收标准」句或 `ux/` 规格句；惯例类测试〔封装扫描、判定通道纪律、驱动契约〕锚规约条款行）；`game/sim/` 不进扫描面（测量面直构惯例）。与链式锚的分工：链式锚（断言→套件→能力行→系统文档）不变、属义务清单层；本注记属执行证据层、写在断言文件内，非独立账本（§8.9 法则 4 不变）。写新测试函数时当场挂注记；被指规格句改行号时随批维护指针——死指针即红。局限如实声明：注记是被动文本，句内容改而行数不变时机检抓不到（与卡片判据 C5 同限）。机检＝`tools/capability_audit.py` 判据出处注记道（覆盖检查＋指针存在性；扫描面零文件自检红）。规格缺席写不出锚＝发现规格缺口：记发现不造锚、收尾呈报，禁锚到非现行文档凑数。 **验收档申报（2026-11-04 立，自 2026-11-05 起对文件名日期不早于该日的需求卡片生效；旧卡不回头改）**：每张需求卡片在头部信息区（与设计事实源声明同区）申报一个验收档，三档：高／中／低。判据＝失败代价单维——这条改动做错了，后果随存档或结算传播的（存档写读与迁移、RNG 流、战斗结算公式与乘区、经济入账、数值表结构校验）＝高；后果玩家可见但不损持久状态的（常规玩法逻辑、门控、交互逻辑、呈现数据面）＝中；后果即看即知且无状态残留的（文案、纯呈现样式、布局微调）＝低。一张卡触多档按最高档申报；申报由写卡段落笔，用户批卡（U0）时确认或改判。档位只调节 §8.7 审计深度——闸机与 CI 的域划分、选闸算法、全量强制档一概不因档位变化，真实入口、判据绑定面、禁削弱等验收闭合判据全部照旧。未申报档位的卡一律按高档全量审计。机检＝`tools/pipeline_gate.py` 判据 C4：卡内须含「验收档：高／中／低」申报行。 diff --git a/待办清单.md b/待办清单.md index 7a110d22..0c5ca214 100644 --- a/待办清单.md +++ b/待办清单.md @@ -2,6 +2,14 @@ 本清单是流水线的唯一登记处：以后才做的事在此登记一条，随流水线段推进改状态，做完整条删除（条目记进度，不是各段的开工前置）；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据含可选优先级，正文＝实况/缺口/改动面/状态四属性）与状态机以 [doc-conventions §12.1](design/engineering/doc-conventions.md) 为权威。 +#### 架构文档收窄批——实现事实迁出与写权限收为用户专属（2026-11-07 登记，来源=会话提及） + +**实况**：调研与四项决策定案在案（模块表瘦形态留架构文档／不另立登记文档／两图 JSON 同批更新／只重锚 32 处 architecture oracle 锚），方案经用户批准；规约根因＝doc-conventions「禁实现内容」条款曾把实现事实指定给架构文档，本批同步修订。证据＝design/engineering/doc-conventions.md:70（实现事实归处条款）。调研依据＝会话对照 arc42/C4/Fowler/ADR＋架构文档构成统计（449 行中约束面约 150 行）。 + +**改动面**：文档＋游戏代码＋工具代码 + +**状态**：待执行 + #### 封印动作改版——挖开与封印都揭示格子（2026-11-07 登记，来源=会话提及） **实况**：现行封印不揭示格子（格子保持未开、封印印记立在上面），封印后再挖开是合法动作；用户新方向＝棋盘上仍是挖开与封印两个动作，两者都揭示格子，墙体消失、展示地板，封印后再挖开这条路径不再存在，用户口径＝决策路径更直接。