diff --git a/reports/工程改动报告-能力清单改版-2026-10-29.md b/reports/工程改动报告-能力清单改版-2026-10-29.md new file mode 100644 index 00000000..38c273c6 --- /dev/null +++ b/reports/工程改动报告-能力清单改版-2026-10-29.md @@ -0,0 +1,46 @@ +# 工程改动报告——能力清单改版（验证账本改实现指导地图） + +2026-10-29 · 文档设计改动批（用户裁决定稿后发令执行）· worktree 分支 `caplist-20261029` 合回 +接收方：待办清单.md「能力清单改版——验证账本改实现指导地图」条（本批完成即整条删除，条目内容 git 历史可考） + +## 定位换代（用户裁定，本批不改设计） + +能力清单从「覆盖索引＋验证账本」改为**实现指导＋阅读导航＋义务声明**：只宣布「要验证什么」，不记「是否已验证／是否跑过」；落地账归现行验收闭合链（卡片改动—验收对照表逐条挂断言＋合回前独立验收审计），那套机制本批不动。废「滞后一个迭代」：写需求卡片时本批新增能力行当场入表，计划测试文件名与函数名卡里定死；实现照单落名，名实不符＝卡片没写清＝停卡退回；收尾只核对表上名字与实际落地一致（改名则回表），不刷任何批次字段。 + +## 改动面 + +| 文件 | 改动 | +|---|---| +| `game/tests/README.md` | 八张能力表（七旅程段＋跨域条件闸）瘦身四列：能力｜系统｜真实入口｜代表用例（文件:函数）——删「最后验证批次」「缺口」两列，存量行内容保留、不回溯验证；引区块改写（义务清单定位、维护规则、代表用例口径），删「最后验证批次」整段说明；覆盖域表（含其「缺口」列）按用户裁保留现状不动 | +| `design/engineering/test-conventions.md` | §8.3「能力清单维护锚」整段改写（新定位＋四列＋写卡当场入表＋实现照单落名＋收尾核对）；§8.9 三层模型中层「覆盖索引」改「义务清单」，法则 3「覆盖守恒」改「承接守恒」并同步措辞，维护时序段删滞后与批次刷新表述，机器闸句改四列＋双通道口径 | +| `tools/capability_audit.py` | CAP_COLS 收窄四列（「系统」列纳入非空机检）；删「最后验证批次＝真实 commit」检查（check_hash／commit_ok／HASH_RE 随删，subprocess 导入随之移除）；代表用例与真实入口判据改双通道（见下表）；条件闸行豁免保留（按「代表用例」含「条件闸」字样）；头部判据清单同步 | +| `tools/pipeline_gate.py` | 对照表「能力行」判据收紧：「新增：<能力名>」同样要求该能力行已在 game/tests/README.md 能力表在场（写卡与入表同 commit；改版前仅核「既有：」） | +| `.zcode/skills/req-card/SKILL.md`（主区直改，不入 git） | 验证闸节增「能力行当场入表」义务：本批新增能力写卡时增行（真实入口取自设计文档已定入口；代表用例＝卡内定死的计划测试 `文件:函数` 名）；受影响存量行同批更新；能力退役删行；实现照单落名、收尾核对 | +| `.zcode/skills/iter/SKILL.md`（主区直改，不入 git） | 批性质注记更新（能力行增删归写卡段当场入表，「最后验证批次」列已废除）；第 5 步账面随批增「能力清单核对」：核对表上名字与实际落地一致、退役能力行已删，名实不符＝停卡退回，本批禁代改 README | +| `待办清单.md` | 「能力清单改版——验证账本改实现指导地图」条整条删除（完成即删） | + +## 判据变更前后对照 + +| 判据点 | 改版前 | 改版后 | +|---|---|---| +| 能力表列 | 六列（能力｜真实入口｜代表用例｜最后验证批次｜缺口；「系统」列不在机检列） | 四列（能力｜系统｜真实入口｜代表用例），四格全非空机检 | +| 最后验证批次 | 须为可解析 commit（git cat-file），条件闸行豁免 | 列删除、检查随之删除——清单不记「是否已验证／是否跑过」 | +| 代表用例可核 | 单通道：文件在 run_all.gd 套件 manifest 内且文件有 `func 函数名(` | 双通道：代码在（同左）或卡在（文件名或函数名见于 reports/需求卡片*.md——写卡当场入表的计划用例锚）；两头都无＝红 | +| 真实入口可核 | 单通道：产品码有 `func 方法(` | 双通道：产品码有 `func 方法(` 或方法名见于需求卡片（计划入口锚）；两头都无＝红。※延伸申报见下 | +| 对照表「能力行」 | 仅「既有：<能力名>」须在能力表可查，「新增：」不核 | 「既有：」与「新增：」都须在场——新增不在表＝「写卡须同批把能力行写入能力清单」红 | +| 维护时序 | 清单滞后一个迭代：本批实现的代表用例与批次由下次写卡补齐 | 写卡时当场入表（新增行＋受影响存量行更新＋退役删行）；收尾只核对名字与落地一致，不刷批次字段 | +| 条件闸行豁免 | 「代表用例」或「缺口」含「条件闸」即豁免 | 仅「代表用例」含「条件闸」（缺口列已删） | + +**※延伸申报（超出任务清单原文的一处判据延伸，显式呈报待用户追认）**：任务原文只要求「代表用例」改双通道；「真实入口」按原文保持单通道（产品码 `func` 在场）。但用户裁定 ③「受影响存量行（入口／用例名变更）同批更新」与「新增系统的能力行」都在**写卡 commit 点**生效——彼时入口代码尚未落地，单通道必被闸拦（写卡提交被自家闸机拦死，与裁定 ③ 直接矛盾）。故按同一已裁口径「两头都无＝红」把卡片通道延伸到入口列：产品码有定义或需求卡片载名，其一即绿。若裁回退，只需还原 `check_entry` 单通道判断（约两行）。 + +## 验证 + +- 闸件新判据孤立验证（造红探针，未触库内文件）：代表用例双通道两头无＝红／卡在＝绿／代码在＝绿（3/3）；对照表「既有：」不在表＝红、「新增：」不在表＝红（2/2）。 +- 文档域闸（`tools/run_all_gates.sh --docs`，提交点钩子与收口跑批同判据各一遍）：06 gdd_lint／06b 变更记录节／07 doc_link／08 doc_term／08c 流水线闸／08d 引用可核／08e 能力审计／10 熵增闸全绿无新增红；08e 能力审计读数＝系统文档 25 篇 · 能力行 59 · 套件 65 · 覆盖域表 25 行 · 红项 0。 +- 收口回执 `game/tests/.gates/receipt.json`：domain=docs、all_green=true、tree＝分支尖内容树（不入 git，合回闸按树哈希校验）。 + +## 边界与遗留 + +- 本批零游戏代码面改动（未跑代码域闸，符合批令）；存量 59 行的代表用例全部经代码通道锚定，行内容未动。 +- 全库「最后验证批次」引用面已清零（test-conventions／README／iter 技能三处随本批改写）；待办清单另一条「验证与清单体系整改」实况中的「最后验证批次」字样为历史叙述留档，不在本批改写面。 +- 主区两个未跟踪旧报告（reports/工程改动报告-存量断言精简C档-2026-10-28.md、reports/盘点-验证与清单体系-2026-10-28.md）按批令未触碰。 diff --git a/待办清单.md b/待办清单.md index 8ae0fdb1..3ba15bd5 100644 --- a/待办清单.md +++ b/待办清单.md @@ -18,16 +18,6 @@ **状态**：待执行 -#### 能力清单改版——验证账本改实现指导地图（2026-10-29 登记，来源=会话提及） - -**实况**：用户裁推翻「验证与清单体系整改」阶段 1 定稿中的滞后条款（清单滞后一个迭代属设计后果）。新定位＝实现指导＋阅读导航，不是验证账本：清单只宣布「要验证什么」，是义务声明，不记「是否已验证／是否跑过」（账归现行验收闭合链——卡片对照表逐条挂断言＋合回前独立审计抓「写了没落」）。设计要点：①四列制：能力｜系统｜真实入口｜代表用例（测试文件:函数）——删「最后验证批次」与「缺口」两列（没落地的验证需求不进地图，进待办清单）；②废滞后：写需求卡片时本批新增能力行当场入表，计划测试文件名与函数名卡里定死；③实现照单落名：测试函数名以清单为唯一依据，名实不符＝卡片没写清，停卡退回；④收尾只核对表上名字与实际落地一致、退役能力删行。改写面：test-conventions §8.3 维护锚与 §8.9 三层模型、game/tests/README.md 能力清单四列重构、req-card／iter 技能同步、pipeline_gate 对照表机检口径（「能力行」列与 capability_audit 口径随本条复核）。 - -**缺口**：无待裁点；试点＝下一张真卡试运行一轮再定稿（规则修订须真实任务评估）。 - -**改动面**：文档 - -**状态**：待文档设计 - #### 验证与清单体系整改——四方向分阶段推进（2026-10-28 登记，来源=会话提及） **实况**：用户裁「验证及清单不合理」，经调研定四方向全做、分阶段推进：A 粒度整改（清单从断言级升到能力/行为级，逐断言账本退役）→ B 精简裁断（在新粒度上规则驱动删并）→ C 流程风险分级（P0/P1/P2 验收强度、审计抽样）→ D 文档减肥（待办条目限长、历史归 git）；测试有效性度量暂不处理。阶段 0 盘点已毕：验证集清单零机器闸依赖（run_all_gates／hooks／五技能均不引用，仅 test-conventions §8.3 维护锚＋2 份过程报告引用），退役无闸改动；但测试名尾缀仅覆盖 28/47 个有断言文件（19 个零尾缀，含 seal_polarity 69 条、variant_placement 42 条、roll_multiplier 35 条），故能力清单只能按「能力→代表用例」建，不要求逐断言尾缀。对照表列改动触 pipeline_gate＋req-card／iter 两技能；待办正文压缩不触机检（无长度判据）。盘点明细见 reports/盘点-验证与清单体系-2026-10-28.md。**阶段 1 设计已闭合（2026-10-28 用户四裁点）**：能力清单 v1 落 `game/tests/README.md`——按系统归属与玩家旅程排序，首期核心四域（存档与随机、冒险循环、战斗结算、奖励与经济）29 行＋跨域条件闸 1 行，共 30 行，每行真实入口＋2–3 个代表用例（`文件:函数`），维护规则为每批收口核对本批受影响行并刷新「最后验证批次」；`design/engineering/test-conventions.md` §8.3 维护锚改写为「验证集清单整册冻结、能力清单承接覆盖索引、阶段 2 精简后删除」；`game/tests/验证集清单.md` 头注同步冻结声明，冻结快照（基点 `b9260138`／1587 条）留作阶段 2 对账基准；`tools/extract_checks.py` 保留为审计工具，不再承担常态同步。**阶段 2 已执行闭合（2026-10-28 C 档合回）**：存量断言精简 C 档 6 组手写断言族并为 7 个表驱动站点（33→7），冻结清单对账 1587→1561，验证集清单随阶段 2 完成退役（覆盖索引归能力清单，维护锚 test-conventions §8.3），删并申报与件核见 reports/工程改动报告-存量断言精简C档-2026-10-28.md；阶段 3–4 待各自设计推进：风险分级与审计抽样规则、条目限长是否入 pipeline_gate 均未定。**2026-10-29 阶段 1 落地定稿（用户三裁）**：①能力清单与覆盖域表落 `game/tests/README.md`，独立成表、不与 GDD 验收标准合并；②GDD 纯度判红——系统与概念文档全文禁写实现细节（代码路径／测试文件名／断言名），唯一例外＝配置文件索引（`game/data/tables/*.tres` 表路径与表名）；③能力清单维护归写卡段——写需求卡片时增删能力行并刷新「最后验证批次」，实现批禁写该文件（清单按规则滞后一个迭代，属设计后果）。三层模型（验收意图／覆盖索引／执行证据）与四法则落 test-conventions §8.9；落地分五批：①三份规约＋AGENTS.md 红线＋本条实况（本批）；②README 覆盖域表＋三域能力行补齐；③`tools/capability_audit.py` 文档域新闸（3a 普通工具入库／3b 接闸＋基线，worktree）；④pipeline_gate 对照表加「能力行」列＋req-card／iter 两技能同步；⑤GDD 存量实现细节清理（28 篇约 98 处，逐处去向表过用户目后落笔）。**2026-10-29 阶段 1 五批全部落地**：①032d923c；②5377b2ce；③`tools/capability_audit.py` 入库 ae3c99e3＋接闸上电 915222fa（文档域闸 08e 能力审计，纯度红清零后才上电）；④f3263444；⑤GDD 清理 00312e12（30 篇去 124 处实现指证，纯度红 124→0）。阶段 1 收口；阶段 3–4 待各自设计推进。