diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 570e2bc..4e91fe5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ "name": "dev-standards-bootstrap", "description": "AI agent development governance skill: five quality gates, AGENTS.md entry, Git/CI enforcement for any repo.", "source": "./", - "version": "3.88.0", + "version": "3.92.2", "category": "documentation", "keywords": [ "ai-agents", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b73e114..83e53a0 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-standards-bootstrap", "description": "AI agent development governance skill: five quality gates, AGENTS.md entry, Git/CI enforcement for any repo.", - "version": "3.88.0", + "version": "3.92.2", "author": { "name": "geekma" }, diff --git a/MAINTAINER.md b/MAINTAINER.md index 34029dd..1675762 100644 --- a/MAINTAINER.md +++ b/MAINTAINER.md @@ -72,11 +72,17 @@ ```bash bash scripts/selfcheck.sh # v3.87.0:单一入口 = 委托 verify-all(载体 → 私有台账 → 源层审计 → 套件)+ 评测派生校验;参数透传(--fresh / --skip-suite …) -bash tests/run-tests.sh # 通用层:golden cases,断言 agent-gate 的退出码与输出 +bash tests/run-tests.sh # 通用层全量:golden cases,断言 agent-gate 的退出码与输出(≈25 min / 1377 断言) +bash tests/run-tests.sh -T auto # 按 git diff 选节(未映射文件回落全量)——改文档/模板/单脚本用这个(秒~分钟) +bash tests/run-tests.sh -l # 列全部节名(T1 … T81) bash tests/audit-standards-src.sh # 源层:版本链 / 关键词落点 / §3↔§4 同源 / 树↔磁盘 … ``` -- **改脚本 → 必须先跑通 `run-tests.sh`**(§2.17.4 硬性要求)。 +- **改脚本 → 必须先跑通 `run-tests.sh`**(§2.17.4 硬性要求)。**但跑法分层,不要一律全量**: + - 改**被测核心**(`resources/templates/agent-gate.sh`、`tests/run-tests.sh`、`agent-governance.yml`)→ 全量,且**收口跑一次**; + - 改**其他脚本 / 文档 / 模板** → `-T auto`(按 `git diff` 选节)或 `-T <节[,节]>`。 + - 实证代价:同一会话裸跑 11 次 ≈ **4.6 小时**;`-T auto` 在同等覆盖面下为秒级到分钟级。 + - `_auto_map()`(`tests/run-tests.sh` 内)是选节映射表;**未映射的文件一律回落全量**(映射是优化,不是正确性依赖)。新增可映射文件时同步扩表,改完用 `-T T75` 自测映射,并先 `AGENT_GUARD_SUITE_AUTO_RESOLVE_ONLY=1 bash tests/run-tests.sh -T auto` 看解析结果。 - **改规范正文 / 模板 / README → 必须先跑通 `audit-standards-src.sh`**。 - **CHG-115 起源层审计不再内嵌整跑**:A3 消费 `tests/.suite-baseline`(上一次真实绿跑计数的入库件),纯读/比,A3 改造当时实测 9.0s;本批 A56 边界段一度付到 ≈20s(受跟踪面措辞扫描 + 夹具实跑),R4 删去载荷专用措辞环后收口实跑 15s——这个数的机器真值是 verify 收据 `audit` 步的 duration_s,不要把任何复述当常量。旧写法(`update-assertion-count.sh --check`)会在同树收据过期(30min TTL)时隐式跑整套——620 条断言的审计曾因此付 300.984s(占墙钟 97.2%)。**运行期真值只有一个落点**:CI 的那一次全量跑,跑完由 `scripts/ci-summary.sh --check` 把基线与收据 `passed` 硬对齐;本地基线过期就会在 CI 响亮地红。本地同理:`bash scripts/verify-all.sh --fresh` 是唯一会跑整套的入口。 - **两道自测试并行是安全的**(v3.87.0):audit 侧不再有隐式整跑,工作区锁(`lib-suite-lock.sh`)只约束"同一工作区同时只有一次全量套件";`-T` 过滤跑不取锁(子用例靠它)。收据/红档/verify 产物路径全部可 `AGENT_GUARD_*` 覆盖,自测不污染真实台账。**CI 侧同样并行**:`source-audit` 已去掉 `needs: golden-case`(它只读入库基线,对套件运行无依赖),串行那一头曾是白等的 4 分钟,而且套件一红就完全不报审计发现。 @@ -159,26 +165,19 @@ bash scripts/update-assertion-count.sh --check --require-receipt ### 5.1 规范体量上界(A11)与它的重校准 -`A11` 断言 `resources/DEVELOPMENT_STANDARDS.md` 不超过一个硬上界(当前 **164 KB / 167,936 字节**,v3.70.0 自 172KB 回转——CHG-045 下沉后兑现配对减法)。它不是"防内容变多",而是**防无序回弹**——上界一旦失效,规范就会无声地膨胀下去。 +`A11` 断言 `resources/DEVELOPMENT_STANDARDS.md` 不超过一个硬上界(当前 **168 KB / 172,032 字节**,v3.89.0 自 164KB 按 +4KiB 步进重校准——CHG-117)。它不是"防内容变多",而是**防无序回弹**——上界一旦失效,规范就会无声地膨胀下去。 **重校准是设计内的动作,不是破例**,但必须满足两个条件: v3.43.0 重校准记录(CHG-053):156KB 上界被 §2.17.2b 缺陷发现入口(三信号双通道 + 频控 + 自主权,160,160 字节)吃到负值 → 按 KiB 步进(+8KB,跨 4KB 档取整)重设 **164KB**(余量约 7.5KB),有 CHANGELOG v3.43.0 行对应。 v3.68.0 重校准记录(CHG-043 同版本收尾,2026-10-12 用户裁定"校准"):164KB 上界的余量先被 v3.67.0 UX 体系压到 455B,再被 v3.68.0 三维对照门禁族(G13/G14,5 条款)吃到 **170,735 字节**(破线 2,799B)→ 按 KiB 步进(+8KB)重设 **172KB**,有 CHANGELOG v3.68.0 行勘误注对应。**配对减法纪律**:下次触软警线(171,008B)必须走结构性减法,禁止连续重校准;减法低垂果实 v3.61.0(FU-911)已摘尽,再减须动硬结构(权威锚点全量重验),另立 CHG。 v3.70.0 回转记录(CHG-045,2026-10-13 用户"体积要控制"+配对纪律兑现):172KB 上界被存量法下沉(FU-936,形状迁 entry 模板×4+工具头注释+playbook 瘦身)减至 **167,610 字节** → 上界**回转 164KB**(软警 163,840B 即时常亮=下次结构增长的减法触发器)。**注**:盘点估值 13KB 偏高,无语义损失可移出的形状实为 ~3.2KB——剩余内容均为机校语义/权威定义(L 类),进一步减法须动硬结构。 +v3.89.0 重校准记录(CHG-117,2026-10-24):164KB 上界(167,936B)被 §2.17.2b 信号③专句 + §2.16.2 阶段门执法点 + §2.17 阶段门/无账门专段(REQ-1199~1203,含设计门补齐 03.5)吃到 **165,937 字节**(软警 163,840B 之上、硬上界之下,A11s 先亮)→ 按 **+4KiB 步进**重设 **168 KB(172,032 字节)**(余量 6,095B;独立评审指出 +8KiB 放宽过多,已按 +4KiB 收敛),有 CHANGELOG v3.89.0 行对应;软警线随上界 −4KiB = 167,936B。**配对减法纪律**:下次触软警线必须走结构性减法,禁止连续重校准。 1. **有 CHANGELOG 条目对应**(新条款必须登记); 2. **先压缩再抬高**:把重复条款合并、把机制细节下沉到脚本头部注释(渐进披露),能省多少先省多少。 -v3.31.0 的重校准记录(前次,供下次参照;最近一次为上方 v3.43.0 记录——当时 §5.1「当前」句漏同步 144KB 口径,CHG-057 修正):§2.1 规则 10(角色单一职责)+ §5 反模式行把 140 KB 上界的余量吃到 **-220 字节**(先压缩两处措辞仍压线),按 **KiB 步进(+4 KB)**重设到 144 KB。 - -v3.29.0 的重校准记录:§2.1 九专家行 + §2.2 评审矩阵把 132 KB 上界的余量吃到 **3 字节**(v3.25 同型——上界事实上再次失效);先做两轮措辞压缩(仍超 136 KB 约 1.6 KB),再按 **KiB 步进(+4 KB)**重设到 140 KB。 - -v3.25.0 的重校准记录:v3.24.0 的表达成本条款把 128 KB 上界的余量吃到 **3 字节**,按同协议重设到 132 KB。 - -v3.21.2 的重校准记录:v3.21.1 + v3.21.2 两轮对齐修正把 124 KB 上界的余量吃到 **193 字节**;先做压缩(删除规范正文里的变更日志式括注、把派生资产判定口径收成一句),再按 **KiB 步进(+4 KB)**重设到 128 KB,余量 **4,289 字节**——同样不按当前体量贴合。 - -v3.17.0 的重校准记录:v3.16.0 的改动已把 120 KiB 上界的余量吃到 **53 字节**,上界事实上已失效;本版先做压缩(合并三条重复条款 + 机制下沉)把净增压到 **1,035 字节**,再按 **KiB 步进(+4 KiB)**重设——**不按当前体量贴合**,否则下一次任何实质新增又会立刻撞墙。 +> **历史重校准记录**(v3.31.0 / v3.29.0 / v3.25.0 / v3.21.2 / v3.17.0)见 `resources/STANDARDS_CHANGELOG.md` 对应版本行。**五次的教训完全一致**:每次都是上一版把余量吃到几字节(最低 3 字节),所以必须按 KiB 步进重设,**不得贴合当前体量**。 **顺序坑**:抬高上界后必须重跑审计,确认 A11 通过且没有掩盖别的失败。 @@ -195,6 +194,8 @@ v3.17.0 的重校准记录:v3.16.0 的改动已把 120 KiB 上界的余量吃 3. **优先减法序**:合并重复条款 > 机制细节下沉脚本注释(渐进披露)> 删除未命中条款 > 抬上界。前三条走不通才允许上界重校准(§5.1 两条件仍适用)。 4. 预算执行情况为 **B 层**核对项(评审角色逐版本核对 CHANGELOG 条目的加/减平衡),不做条款计数机校(M2 未命中即启用 = 过度设计)。 +> **v3.89.0 预算豁免登记(CHG-117,2026-10-24)**:新增 5 条 REQ(REQ-1199~1203——无账源码改动信号③双层执法、SKIP_VERIFY 收窄、G16 披露面、无状态阶段门、check 阶段感知),均为新执法能力面,同版本内无可对等裁剪的既有条款——预算豁免登记于此(先例 v3.43.0「4 REQ + 2 模板件」同形态);体量侧处置见 §5.1 v3.89.0 重校准记录。 + > v3.45.0 注:断言层的预算与退役流程见 **§5.3 断言生命周期**(soft 桶 + 近两版捕获评审阶梯);本节保持条款级,不与断言级混算。 ### 5.3 断言生命周期(v3.45.0 CHG-055,Top3 装牙) @@ -223,7 +224,7 @@ audit(源层)与 golden(通用层)断言只进不出 = 维护税复利 ## 7. 逐版本升级推送清单 -已经接入过的项目**不会自动更新**——需要用户再次调用本 Skill,走"检测已有文件 → 展示版本差异 → 询问是否升级"流程,或直接 `bash scripts/bootstrap.sh --upgrade <目标仓库>`。各版本新增/变更的补复制动作如下(**新条目置顶**;**口径(v3.58.0 统一):每行必含 CHG 号 + REQ 号(REQ 引用多个逗号列出)**;**TC 注册口径(v3.58.0)**:T 块号即注册单位,TC-xxxx 为用例名——v3.56.0 的 TC-1061/1062=T46(E85 三断言),此后新 TC 在 SLOG 行内点名): +已经接入过的项目**不会自动更新**——需要用户再次调用本 Skill,走"检测已有文件 → 展示版本差异 → 询问是否升级"流程,或直接 `bash scripts/bootstrap.sh --upgrade <目标仓库>`。各版本新增/变更的补复制动作如下(保留**原有最近 5 行**,即 v3.83.0~v3.79.0;更早版本见下节手工表与 CHANGELOG)(**新条目置顶**;**口径(v3.58.0 统一):每行必含 CHG 号 + REQ 号(REQ 引用多个逗号列出)**;**TC 注册口径(v3.58.0)**:T 块号即注册单位,TC-xxxx 为用例名——v3.56.0 的 TC-1061/1062=T46(E85 三断言),此后新 TC 在 SLOG 行内点名): | 版本 | 升级后需要补什么 | |---|---| @@ -232,74 +233,21 @@ audit(源层)与 golden(通用层)断言只进不出 = 维护税复利 | **v3.80.0** | **批次产物 scaffold + 分阶段最小读集(CHG-107,REQ-1152~1154,DES-1917~1918,TC-1400~1405)**:`agent-gate begin --scaffold` 一条命令生成 8 件批次产物骨架——形状契约单源化到生成器(目录落位/五要素/确认状态 fail-closed/预期结果/开放问题/业务影响/风险/回滚/延伸/检索/编号自动续接台账),幂等 fail-closed,端到端钉锁死(scaffold→填充→begin 一次过);分阶段最小读集(纪律 15 + R65 + DS §2.9.6 指针:begin §1.1/§2.5、编码 R 行锚点、测试 §2.13/§2.17.4、stop §2.13/§1.3,规范文档永不整读)。**升级后无手工动作**;批次文档成本 ~14 轮→1-2 轮。 | | **v3.79.1** | **全项目 review 措辞修复(CHG-105,REQ-1148~1150,DES-1914~1915,TC-1389~1396)**:DS 术语单名化(§2.13 证据行「同树快照」→「同树指纹」)+ UAC 空指纹拒采子标签双因表述(源层私有件)。零行为变更——收据 schema/采信语义/下发清单不变,**目标仓升级无动作**;DS 等长替换 167,928 B 不变,A48 棘轮不重校准,断言 1052/审计基线 543 不变。 | | **v3.79.0** | **suite receipt 树指纹(CHG-103,REQ-1142~1147,DES-1909~1913,TC-1378~1388)**:收口快路径采信由「同 HEAD + TTL」收紧为「同 HEAD + **同树指纹** + TTL」——收据增 `tree_fingerprint`(临时索引全树快照,单源 `scripts/lib-suite-tree-fingerprint.sh`,emitter/consumer 同源;声明文件 README×2/`tests/.audit-baseline` 排除——UAC 自身改写面,计入则同步后恒失配),旧 schema 收据/指纹为空/不等一律回落内嵌整跑(反向兼容 fail-closed,永不 fail-open 到错数);DS 采信句与 05 `reused` 标注规则入文。**`--upgrade` 补复制**:`tests/run-tests.sh` + **`/lib-suite-tree-fingerprint.sh`(新增下发件,随 --guard 同包)**、`/DEVELOPMENT_STANDARDS.md`;**agent-gate 治理工具白名单已同步 lib**(首装 commit 不死锁)。**动作**:目标仓升级后 emitter 即生效(绿全跑收据含真指纹);UAC 收口工具不下发,收据消费按 DS 语义自接线;无配置项。 | -| **v3.78.0** | **治理面口径纠偏 + 下发面缺口收口(CHG-102,REQ-1129~1141,DES-1897~1908,TC-1358~1377)**:全版修"声称覆盖面 ≠ 实际覆盖面"类静默失效——①`eval-rescore` 治理面清单改**安装落点**(根 `AGENTS.md` + `/{DEVELOPMENT_STANDARDS,CLAUSE_REGISTRY,METHODOLOGY,STAGE_PLAYBOOK}.md` + `/{methodologies,templates}/**`;`` = `AGENT_GUARD_DOCS_DIR`→`paths.docs`→`docs`,装点缺失回落源仓路径),目标仓漂移告警由恒不触发变为真实触发;②`github-reviewer-rescore.yml` push `paths` 死链改安装落点;③DS 与注册表去源仓私有指针(`MAINTAINER §` 归零;源层脚本引用补"不随 Skill 下发"限定)、DS:832 模板路径改 `templates/entry/00-intent.md`;④SKILL 脚本名去 `.sh`、agent-gate 帮助册号 `P00..P12`、bootstrap usage 补 `bug-autointent`/`generate-reading-pack.sh`/`regression-to-bug.yml`;⑤UAC 内嵌全跑 `-j "${AGENT_GUARD_SUITE_JOBS:-4}"`(套件自身默认 `JOBS=1` 不变);⑥`.github/workflows/agent-governance.yml` 拆 `governance`+`verify` 并行 + 聚合 job 保名 `agent-governance`;⑦新增 T63 hook golden + T48 label 去版本字面量;⑧P10 缺口说明与回填 / P09 回溯 FU-902~945;⑨DS §2.2 + AGENTS.md 纪律 14 增「冻结树并行派发」许可,注册表 R64;DS 167,888→167,882 B(净 −6 B)。**`--upgrade` 补复制**:`resources/DEVELOPMENT_STANDARDS.md`、`resources/AGENTS.md`、`resources/CLAUSE_REGISTRY.md`、`resources/METHODOLOGY.md`、`resources/methodologies/*.md`、`tests/run-tests.sh`、`/agent-gate`、`/session-gate.sh`、`/eval-rescore`、`.github/workflows/agent-governance.yml`【结构变更】(`SKILL.md`/`README×2` 为**源仓自身版本载体,不下发**,仅本仓同步 bump)。**动作**:①分支保护必检项保持 job 名 `agent-governance`(现为聚合 job,改名 = 静默失效);②`stale` 首次翻红属预期语义,处置 = 复核 → `--update-baseline`;③低内存可 `AGENT_GUARD_SUITE_JOBS=2`。 | -| **v3.77.0** | **工具调用批处理与尾部增量读(CHG-101,REQ-1124~1128)**:token 实证驱动(单会话 476 请求/60M cache_read)——AGENTS.md 纪律增 12(调用批处理:命令合并/同文件一次多段 edit/静态基线按需)与 13(尾部增量读:`cat >>`/定点写禁全量重读);DS §2.9.6 新增对应条(细则唯一权威=AGENTS.md,配对减法净 −6 B);session-gate 新 `edits` 软黄灯(edit/write 族计数,`AGENT_GUARD_EDIT_LIMIT` 默认 40,超限登记 09;旧 stats 文件缺键自动兼容);注册表 R63;golden T62。 | -| **v3.76.0** | **验证通道方言修复 + 四态可见(CHG-100,REQ-1115~1123)**:`--upgrade` 覆盖 `/agent-gate`、`/session-gate.sh`;`.agent-governance.yml` 属 **LIVE_SKIP**(不覆盖)——请按模板 ci 段注释自检方言(单引号/裸值/块标量 `\|`·`>` 现均可用),并用 `/agent-gate verify-channel` 现测通道态;值或**位置**畸形(空值/未闭合引号/非法块指示符/多行裸标量/不在 `ci:` 段内)**不再静默跳过**,以 `GATE-E118` 拒。新增 `.agent-state/verify-channel.json`(运行时生成,勿入库);`stop` 会向活跃变更 05 写入「通道自检证据」/「通道未验证(reason)」行(**单行受控覆盖**,保持 05 mtime 不变);`.agent-state/last-suite-red.txt` 改为"最近一次运行结果"(全量绿跑清档)。 | -| **v3.75.0** | **评测资产派生 + 重打分 + 来源维 + 复盘汲取(CHG-099,REQ-1108~1114)**:新增 `/eval-cases`(缺陷组 → `.agent-state/eval-cases.tsv` 派生视图,运行时生成物禁入库)+ `/eval-rescore`(覆盖比打分 + `.agent-state/eval-score-receipt.json` 收据 + 治理面内容哈希漂移即 `stale` rc1)+ `.github/workflows/github-reviewer-rescore.yml` 模板(schedule + 治理面 push;告警语义不阻断合入);07「发现处置」表末位增「来源」列 + GATE-E117(缺列软提示=升级兼容)+ metrics 增 `findings_introduced`/`findings_pre_existing`(缺列=null);事故/回归缺陷组 01-diagnosis 必填「应捕获层」+ 补强落点(bug-diagnosis 模板增节);§2.17.4 入文「真缺陷召回优先于轮次下降」;`resources/AGENTS.md` 增「本仓评审要点」区块(禁另建按仓评审文件);DS 167,914→167,894 B(净 −20 B);注册表增 R59~R61 + GATE-E117;audit A46;golden T60。**`--upgrade` 补复制**:`scripts/eval-cases`、`scripts/eval-rescore`、`.github/workflows/github-reviewer-rescore.yml`、`resources/templates/bug-diagnosis.md`(新版含「应捕获层」节)。 | -| **v3.74.0** | **评审闭环三缺口(CHG-098,REQ-1104~1107)**:E114/E115(发现处置未闭环)+ E116(轮次超限缺处置行);07 增「发现处置」表 + 「评审轮次/超限处置」行;metrics 增 5 字段;`.agent-state/review-rounds.tsv` 运行时账(幂等、fail-open)。T59(TC-1307~1314)注册。**`--upgrade` 带走** agent-gate/SKILL/README×2/DS/AGENTS/METHODOLOGY/methodologies×5/CLAUSE_REGISTRY/entry-07/tests。**回填义务:存量仓新变更的 07 须含「发现处置」节(无发现写单行声明),超轮次上限须补「超限处置」行** | -| **v3.73.0** | **条文+遥测四门执法扩展(CHG-096,REQ-1100~1102)**:纪律第 10 条长任务等待(session-gate 计 `sleep_polls`,`AGENT_GUARD_SLEEP_POLL_LIMIT` 默认 2 亮黄灯)+ 纪律第 11 条环境归因续跑(B 层)+ 纪律第 7 条定向验证执法(governance 声明 `full_test_patterns` 后计 `full_suite`,`AGENT_GUARD_FULL_TEST_LIMIT` 默认 2);`count tool` 增命令片段抽取(env/argv/stdin 三级,stats schema 增两键向后兼容)。T58(TC-1281~1284/1286)+ TC-1285 audit pin 注册。**`--upgrade` 带走 DS/AGENTS/agent-governance 模板/session-gate/install-hook-adapter/SKILL/README×2 版本行**。**回填义务:升级后需重跑 install-hook-adapter 重生成插件接线,否则两计数器仅 Claude/cursor hook 生效(OpenCode 插件 name-only 降级)** | -| **v3.72.0** | **begin 前产物预检探针(CHG-094,REQ-1095/1096)**:`agent-gate preflight <变更号>` collect-all 只读探针——begin 前一次报全部产物缺锚(exit 0=全过/1=违规/2=usage;零副作用,会话态门不在其面)+ DS 执行主线/AGENTS 入口第 2 步指针半句;T56(TC-1267~1271)注册。**`--upgrade` 带走 agent-gate/SKILL/README×2/DS/AGENTS 版本行**。**回填义务:无(纯新增探针)**。**erratum(CHG-095)**:套件 -j 节级并行 + 红归档/FORCE_RED 测试缝 + preflight 探针 unset bypass env(REQ-1099)+ 源层 label/噪声卫生;install-hook-adapter 数值收紧,升级仓须重跑 install-hook-adapter --force(CHG-095) | -| **v3.71.0** | **交付四门族(CHG-046,REQ-1087~1092)**:E110 还原度断言门 / E111 基建冒烟门(fail-closed)/ E112 换挡盲区执法 / E113 TC 落点强制 + C/F 条款两条。**`--upgrade` 带走 DS/AGENTS/STAGE_PLAYBOOK/CLAUSE_REGISTRY/agent-gate/pre-commit/agent-governance.yml 模板/entry-04 模板/SKILL/README×2/methodologies 版本行**。**回填义务:见 STANDARDS_CHANGELOG v3.71.0 行(首个 ui_change 变更 05 补还原度断言行;同会话重复交付需 handoff/换挡声明;基建面 diff 先声明 smoke_command 或落豁免声明)**;**erratum(CHG-093)**:E111 扫描面收敛活跃变更 05(指针缺失 fail-open)+ smoke_paths 非法正则即拦(fail-closed);FU-943 勘误留观;FU-944 关闭(CHG-093) | -| **v3.70.0** | **形状移出法分层减法 + entry 形状件(CHG-045,REQ-1082~1086)**:DS/STAGE_PLAYBOOK 模板形状与机制细节移出到承接点(entry 形状件 ×4:01.5/05/07/09;既有模板与工具头注释承接面见 STANDARDS_CHANGELOG 顶行);FU-932/933/934/937 收口。**`--upgrade` 带走 DS/AGENTS/STAGE_PLAYBOOK/agent-gate/new-change/audit/bootstrap/session-gate/install-hook-adapter/SKILL/README×2/entry×6/methodologies 版本行**。**回填义务:无** | -| **v3.69.0** | **G14e 元素对等清单 + 分层瘦身(CHG-044,REQ-1077~1081)**:behavior-extract.sh 增交互元素枚举(kind=element,词表唯一权威=工具头注释);DS 条 9 +6 字;playbook 细则瘦身为指针(登记簿 schema/否定测试形状/证据行格式移入 entry 模板条件注释块与 agent-gate 头注释);A43 分层单源 tripwire;T54(TC-1234~1238);版本链 v3.69.0。**`--upgrade` 带走 DS/AGENTS/STAGE_PLAYBOOK/CLAUSE_REGISTRY/agent-gate/behavior-extract/audit/bootstrap/SKILL/README×2/entry 模板×2/methodologies 版本行**。**回填义务:无(枚举扩展对既有清单向后兼容)** | -| **v3.68.0** | **三维对照门禁族 G13/G14(CHG-043,REQ-1067~1076)**:源维(origin_artifact 锚点白名单+hash 防腐+behavior-extract.sh 机械抽取+三方对账+剧本回放+豁免传递禁令)/流维(chain_change 事件流切分+数据流规格表)/运行维(否定测试+评审走旅程+逐 UJ 运行痕迹硬门+上游错误计数全零危险信号);GATE-E99~E109 挂 begin/stop;audit G13/G14;T53 节(TC-1128~1135/1231~1233)。**`--upgrade` 带走 DS/AGENTS/STAGE_PLAYBOOK/CLAUSE_REGISTRY/agent-gate/behavior-extract/audit/bootstrap/SKILL/README×2/methodologies 版本行**。**回填义务:无(声明触发,不追溯既往)**(详 STANDARDS_CHANGELOG v3.68.0) | -| **v3.67.0** | **用户体验体系(CHG-090,REQ-1052~1066)**:阶段 1 项目上下文包 10 域 + UJ 用户任务(业务专家子 Agent 强制先于 REQ;项目级落新册 P12,总册 12→13);阶段 3 条件产物 `03.6-ui-spec.md`(`ui_change: true` 必需)+ 禁裸主键作用户入口 + 03.5 任务类型列强制 UX 行;阶段 4 用户旅程 E2E(阈值 L0/L1=1、L2/L3=3);阶段 8 产品可用性专家 UAT 阻塞门(绑定项目代码背景/行业/系统/业务)+ 四方证据→五方 + 人类 UAT 可选提醒;机器化 GATE-E90/E92–E98 + 审计 G11/G12 + §2.8 埋点强制 + §5 反模式 3 条。T52(TC-1212~1222)+ A39 锚点组。**`--upgrade` 带走 DS/AGENTS/methodologies×2/STAGE_PLAYBOOK/CLAUSE_REGISTRY/entry·project·docs-readme·PR 模板/agent-gate/audit/new-change/bootstrap**。**回填义务:目标仓复制 `templates/project/P12-product-context.md` 到 `/project/` 并回填现状(缺则 begin 拒);不追溯既往;在途变更软告警一次**(详 STANDARDS_CHANGELOG v3.67.0)。**勘误(CHG-091,2026-10-11,同版本不 bump):上下文包 10 域与 UJ 条件化——无 UX/UI 需求的变更不强加**。**勘误(CHG-092,2026-10-11,同版本不 bump):mtime 读取探测序 GNU-first 修复(gate_mtime/收据新鲜度;GNU `stat -f %m` 输出 `?m` rc=0,Linux 上 BSD-first 回落不可达)——Linux CI T49 E89 state3 + T51 TC-1121 转绿,macOS 行为不变** | -| **v3.66.0** | **suite 收口收据机制(CHG-088,REQ-1049~1051)**:绿全跑收尾写 `.agent-state/last-suite-receipt.json`(红全跑即删;语义=「该 HEAD 最近一次完整跑为绿」;收据=工作树最近一次绿跑的本地代理、非 commit 内容证明;`-T`/`-l` 过滤运行不触收据);消费端 `update-assertion-count.sh` 五条件秒级采信(head==当前 HEAD + failed==0 + mtime ≤ `AGENT_GUARD_SUITE_RECEIPT_MAX_AGE_MIN` 默认 30、0=禁用),否则照旧内嵌全跑(fail-open 到现状);同 HEAD 连续收口 2×全量→1×全量+消费端秒级。T51 自测 TC-1121~1127。**⑧同版本收尾(CHG-089)**:agent-gate `validate_master_backfill` 裸 `grep\|head` 赋值在 pipefail 下静默死(GATE-E60 不可达+摩擦账盲区)→ `grep -m1 … \|\| true` 修复(payload 落点 `resources/templates/agent-gate.sh`);T23 缺行 red case。**`--upgrade` 带走 resources/templates/agent-gate.sh 与 tests/run-tests.sh**。**回填义务:无(agent-gate 随 --upgrade 自愈)**(本行回填于 2026-09-30,CHG-088 交付时漏登 §7) | -| **v3.65.0** | **套件节过滤 + 收尾耗时行(CHG-087,REQ-1046~1048)**:`tests/run-tests.sh` 增 `-T <节名[,节名]>` 节过滤(节体函数化纯插入 + `SECTIONS` 源序注册表;双 T22 重号节键 `T22a`/`T22b` 消歧)与 `-l` 节清单;未知节/未知 flag die rc=2;收尾恒定 wall-time 行(summary 行格式逐字节不变,计数提取改全量捕获取尾匹配行);T50 自测 TC-1115~1120。golden 660→666。**`--upgrade` 带走 tests/run-tests.sh**。**回填义务:无**(本行回填于 2026-09-30,CHG-087 交付时漏登 §7) | -| **v3.64.0** | **opencode 插件契约发现与真加载验证(CHG-084,REQ-1038, 1039)**:四段式(探测 runtime 清单与版本→实时检索官方插件文档→形状候选→逐 runtime 沙箱真加载仲裁)+ 功能级判据(客户端 `failed to load plugin` 行 + session-gate 功能标记双条件)+ fail-closed(ADAPTER-E11 探测不可执行/E12 全候选被拒或终验失败还原备份/E13 多 runtime 互斥主用择形显式告警)+ dual-active 生成形状(`default { id, setup: v2实现, server: v1实现 }`,CLI 跑 server、Desktop 跑 setup 各执行其一);ADAPTER-E09/E10 静态形状断言废止(T49 块重写,TC-1103~1108,SC-997~999);进程组杀固化(`oc_spawn_bg`/`oc_kill_bg`,CLI fork 子服务孤儿写手教训)。**`--upgrade` 带走 install-hook-adapter/session-gate/new-change/agent-governance.yml 模板与规范文档**。**回填义务:目标仓升级后重跑 `scripts/install-hook-adapter --client opencode`(v3.63.0 生成物在 Desktop 端失效不自愈;验证=客户端日志无 failed-to-load + `.agent-state/session-gate-last.md` mtime 前进)** | -| **v3.63.0** | **换挡执法事件化 + adapter 活性治理(CHG-083,REQ-1032, 1033, 1034, 1035, 1036, 1037)**:事件型换挡触发(commit/交付宣言后收尾=handoff 文档+显式换挡声明,GATE-E89 begin 兜底)+ bootstrap auto_wire 目录证据化 + 阈值 `-ge` 口径统一 + 五客户端 adapter 漂移排查(ADAPTER-E09/E10 结构断言、gemini/codex 如实声明)+ 遥测活性自检(YELLOW 失联可见化)。T48/T49 块(TC-1093~1101)。**`--upgrade` 带走 agent-gate/session-gate/install-hook-adapter 模板、bootstrap.sh 与规范文档**。**回填义务:存量仓升级后重跑 install-hook-adapter --force(本行回填于 v3.64.0 收尾时补记,CHG-083 交付时漏登 §7)** | -| **v3.62.2** | **并批执法双向化 + stamp 栅栏感知/CRLF 归一(CHG-082,REQ-1028~1031)**:E86 双向化(L0/L1 声明独立目录一律拒,escape 通用)+ E58 缺陷轨反向 + 栅栏感知四处(stamp 写入/--check/门禁抽取/trace-derive,评审 D1/D2 加固:兜底 rc 信号 + inskip toggle 守卫)+ CRLF 归一 + T17/T27 比对口径审视(10 档)。**`--upgrade` 带走 agent-gate/stamp-provenance 模板与规范文档**。golden 588→614。**回填义务:无** | -| **v3.62.1** | **溯源盖章写入幂等 + 剔章回填复活(CHG-081,REQ-1025~1027)**:stamp 写入单趟 awk(块邻空行吞净,块尾累积根除)、pre-commit 剔章比对空行归一(回填复活)、docs 历史空行清理+源层 A41 canary。**`--upgrade` 带走 stamp-provenance/pre-commit 模板与规范文档**。golden 583→588;源层 406(baseline 405→406)。**回填义务:无** | -| **v3.62.0** | **E 码索引互锁 + NC-E11 拆分 + 溯源 commit 真值(CHG-080,REQ-1021~1024)**:CLAUSE_REGISTRY 增「GATE-E 码映射索引」节(88 码,源层 A39 计数互锁)+ new-change NC-E10/NC-E11 拆分(文案单源)+ stamp-provenance 点号 id 拒盖 + commit 字段改逐文件 last-touch(--check 增一致性比对)。**`--upgrade` 带走 stamp-provenance/new-change/audit-docs-consistency/CLAUSE_REGISTRY**。golden 568→583;源层 407(baseline 405→同步)。**回填义务:无** | -| **v3.61.1** | **时区统一 + 批次/最低线收口(CHG-078,REQ-1013~1016)**:批次日期统一 UTC(E73/new-change 改 `date -u`;DS §1.1 口径句);E83 批成员判定改 roster(FU-913 关闭);GATE-E87 扁平批锚段 roster 差集校验;L0/L1 `review_owner` 必填(GATE-E88)+ E34/E35 恒查(DS §0.5.2 补执法句);entry/00-governance 模板补双 owner 占位。TC-1069(T18d)。golden 546;源层 405(baseline 403→同步)。**回填义务:升级后首个 L0/L1 变更的 governance 填 test_owner/review_owner(E88 拦截提醒)** | -| **v3.61.0** | **DS 结构性下沉 STAGE_PLAYBOOK + E86 fail-closed 收口(CHG-077,FU-911/912)**:新建 `resources/STAGE_PLAYBOOK.md`(DS §2.5/§2.16.2/§2.16.6 叙事细则载体,镜像章节;DS 162,730→~157,2xxB,A11 余量 ≥10KB)+ bootstrap 分发行 + SKILL/README×2 枚举 + audit 三断言;GATE-E86 批成员缺自锚段 die(fail-closed 对齐 E83,独立单成员回落保留)+ check-confirm help 串如实化;FU-913 登记(E83 多成员批回落残留);DS §1.1 落位声明句补 fail-closed 语义;SKILL 三处 MAINTAINER 引用加"源仓维护者文件,不随 Skill 下发"限定(目标仓可达性修正);FU-915 登记(源仓专有历史号在目标仓悬空的注记清理候选)。TC-1067/1068(T47)。golden 544;源层 405(baseline 403)+ 0 soft。**回填义务:无** | -| **v3.60.0** | **目录落位声明机校 + 沟通稿五要素锚点(CHG-076,REQ-1009)**:GATE-E86(00-intent 落位声明↔实际目录/风险级一致性,批次锚点感知)+ GATE-E83 五要素锚点扩展(非 L0)+ 旁路 friction 台账;DS §1.1/§2.17.2d/§2.17.3 条款(含四主体互异口径修正对齐 E32/E33)+ 配对减法净 -14B(162,730B);entry 模板「目录落位」节占位 fail-closed(独立目录;批次角 FU-912)。TC-1063..1066(T47)。golden 541;源层 402 + 0 soft。**回填义务:无** | -| **v3.59.0** | **A11s 减法 + FU 裁定批 + A10/A11s 交互缺陷修复(CHG-074/075)**:DS 165,377→162,744B(A11s 熄灯,FU-911 登记 §2.5/§2.16 结构性下沉);FU-906/907/909 关闭落地、FU-910(report_soft pass 排除 A10 分母)修复;死指针 21 处改 resources/ 前缀。golden 537;源层 401(baseline 400)+ 0 soft。**回填义务:无** | -| **v3.58.0** | **全项目 review 收口 + handoff 工具级硬拦 + 持续减法制度化(CHG-072,REQ-1008)**:bug×3(AGENTS L44 限定词/根 AGENTS.md 自述改真 FU-905 关闭/§7 口径)+ DS 九巨行指针化 + A11s 软预警档(≥163,840B soft warn)+ session-gate `check` 模式 + install-hook-adapter claude/opencode 工具级硬拦接线 + 持续减法条款/体量台账 + intent.md 删除 + A35 墓碑 + stamp ANCHOR PIN + FU-906~909。**`--upgrade` 带走规范/AGENTS/session-gate/install-hook-adapter/stamp-provenance**。**回填义务(一次性)**:重跑 install-hook-adapter。golden 537;源层 401(baseline 400)+1 soft(A11s 预警区) | -| **v3.57.0** | **R3 TOP13 减法余项(CHG-071,REQ-1007,纯减法零语义变化)**:tests 双 helper(entry 模板七参数化/T44 批次循环)+ gate help 段指针化 + E85/E82 `sig_head` 共享 + AGENTS/DS/模板叙事指针化;延伸发现并入 R26-R28 注册表路径纠偏(CHG-070 根 AGENTS.md 指针壳遮蔽 T39 解析)。`--upgrade` 零行为变化。**回填义务:无**。golden 537/源层 401 不变 | -| **v3.56.1** | **A6 族 CI soft 化(CHG-070,REQ-1006,用户裁定方案 b)**:CI 恒红根因=docs/* 忽略裁定 vs A6 断言结构性冲突;A6a/b/c 并入 soft 桶(本地恒硬),docs/ 忽略保持。**`--upgrade` 零分发变化**。**回填义务:无**。golden 537/源层 401(baseline 400)不变 | -| **v3.56.0** | **07 评审署名/溯源机校(CHG-069,REQ-1005)**:GATE-E85(07 必含 §2.1.7 签名+task- 可追溯子任务 id;07 缺席不外溢)——自评冒充评审的机制化闭环(本轮执行违规实证)。**`--upgrade` 带走 agent-gate**。**回填义务(一次性)**:升级后首个交付变更 07 补签名+task id。golden 534→537(T46×3 断言),源层 401(baseline 400);A11 166,111B(余量 1,825B,09 勘误节为准) | -| **v3.55.0** | **治理脚本单源化批(CHG-068,REQ-1001~1004,FU-904 全做)**:require_section_or_decl(E80/81/84 形状单源)+check-confirm 子命令(E83 语义单源 exit 0/1/2,NC-E10)+append_diag_lines(夹具收敛)+adapter gitignore 提示行。**`--upgrade` 带走 agent-gate/new-change/install-hook-adapter**。**回填义务:无**。golden 530→534,源层 400;FU-904 全闭合 | -| **v3.54.0** | **历史相似检索机校+防回归补测+减法收尾+FU-903 关闭(CHG-067,用户裁定)**:GATE-E84(02/01-diagnosis 历史相似检索 A 层机校)+TC-1050/1051(F5 豁免执法面+自锚点空记录防回归)+DS 减法 −~900B;FU-903 关闭(SLOG 追加式冻结政策)。**`--upgrade` 带走 agent-gate**。**回填义务(一次性)**:升级后首个新变更 02/01-diagnosis 补节或声明行。golden 521→528(T44×8),源层 400(baseline 399);A11 165,727B(余量 2,209B);收口再审计:P2×2(confirm_ok 外溢 bug+解析顺序指针落空)修复+P3 对齐×5+FU-904 登记(helper 合并等候选待裁定) | -| **v3.53.0** | **分阶段评审留痕 + 减法批(CHG-065/066,用户裁定"全部执行")**:阶段 1-5 B 层评审必须独立子代理+07「分阶段评审」节留痕(L0/L1 单行声明合并评);FU-902 方案 b(缺陷轨机校点=绑定 CHG begin);SKILL −5.6KB/gate −1.9KB/DS 批次行 −2.3KB/AGENTS −1.3KB(pin 全存活);A36×4+T43×5+baseline 398。**`--upgrade` 带走规范/AGENTS/SKILL/agent-gate**。**回填义务(一次性)**:升级后首个新变更 07 补分阶段节或声明。golden 516→521,源层 399(baseline 398);A11 166,099B(余量 1,837B);FU-903 登记(SLOG 政策门延后) | -| **v3.52.0** | **沟通先行门(CHG-064,用户指令 2026-09-25,三轮沟通裁定方案 B 独立产物)**:第 15 件契约产物 `00.5-communication.md`(Round-1 沟通稿+用户整体确认记录,§2.17.2d)——顺序铁律=深挖→沟通→**用户确认**→批量文档→编码→测试;begin required_docs 7→8+GATE-E83(批次按本变更锚点小节校验跑到下一兄弟锚点;L0 单行声明豁免;`AGENT_GUARD_ALLOW_UNCONFIRMED=1` 显式越);new-change 两段式(wave1 三件→确认后补齐五件,NC-E09/`--allow-unconfirmed`);CLAUSE_REGISTRY +R43;契约枚举 14→15 全链。**`--upgrade` 带走规范/AGENTS/两模板+entry 8 件/gate/new-change/bootstrap/注册表**。**回填义务(一次性)**:升级后首个新变更 begin 前补 00.5(L0 可单行声明)。golden 492→514(T42 新增+T25 适配+F2 负例),源层断言 395(pin 名更新:A25 八件/A26 15 件/主线串);A11 167,089B(余量 847B——收尾 review 减法后;下版继续加一删一) | -| **v3.51.0** | **安装清单全文件保留(CHG-063,用户指令追问→通用化)**:`.dev-standards-manifest`(cksum 基线)+--upgrade 逐文件归因(版本漂移=updated/用户改=kept--force 越/legacy=kept+采纳提示);四层叠加(LIVE_SKIP/AGENTS 合并/清单/CONFLICT);golden 485→492+A34×2(393→395)。**`--upgrade` 带走 bootstrap+规范**。**回填义务:无**;A11 165,247B(DS 零改动,余量 2,689B) | -| **v3.50.0** | **安装/升级用户内容保留(CHG-062,用户指令)**:AGENTS.md 托管标记块+bootstrap `merge_managed`——agents-md 键 merge-or-keep(有标记只换托管区用户区块保留;无标记差异 kept,--force 不越,删除重装刷新);通用 conflict/--force 不变;golden 480→485+A33×2(391→393)。**`--upgrade` 带走 bootstrap/install/规范**。**回填义务:无**;A11 165,247B(余量 2,689B,DS 零改动) | -| **v3.49.0** | **版本载体全链清单条款(CHG-061,CHG-059 可否决点③批准)**:DS §2.14 新增载体全链唯一权威条款(页脚×9+元数据×2+README×2×3 处+升级记录×2,入链/出链同版本修订)+注册表 R42 universal 行(41→42)+§5.2 对等减法=§2.16.5「标准升级」行退役+die 码域 `[0-9]+`(T30×3+T41,P3-1 收口);A32×2(源层 389→391)、T39 计数 42。**`--upgrade` 带走规范/注册表**。**回填义务:无**。golden 480 不变,源层断言 389→391(基线 updater 同步);A11 165,247B(余量 2,689B) | -| **v3.48.1** | **gate 检查码重编号(CHG-060,CHG-058 P3-6 遗留)**:E15→E80(stop 轨 02 延伸发现)、E16→E81(begin bug_ref 轨 01-diagnosis 延伸发现)、签名检查 E52→E82(执行期延伸发现并入;stub E52 保留)——检查逻辑零变化;gate die 码唯一性 golden T41(479→480);fresh A/B 实测数据落账(FU-106⑦ 全闭合,CHG-060 09 节引用 CHG-059)。**`--upgrade` 带走 agent-gate/run-tests**。**回填义务:无**。golden 479→480,源层断言 389 不变(基线 388) | -| **v3.48.0** | **缺陷/变更闭环三落点(CHG-058,CHG-057 裁定方案 A)**:延伸发现即时落盘(阶段 2/6 节+§2.12 发现即登记+gate E15/E16)+历史相似检索步(阶段 2/6 节+entry 骨架,无命中写"未命中(检索词)"防假检索)+历史关联必填(七要素⑦+bugfix-log 模板字段+§2.16.5 勘误引用原号+G4 增量执法:最新 BUG 条目须含历史相似,存量不追)。**执法面**:golden +5、源层 +A30×6+A31×4(G10 枚举面 pin=README/SKILL G10 漏更复发防线)。**`--upgrade` 带走规范/agent-gate/audit/bugfix-log 模板/entry 骨架**。**回填义务:无**。A11 164,797B(余量 3,139B)。golden 474→479,源层断言 379→389(基线 388) | -| **v3.47.0** | **注册表类型扩面(CHG-057 批 2,Top1 规范倒置第二步)**:CLAUSE_REGISTRY 28→41 行——L1-standards 全集 +6(§1.1/§1.2/§2.5/§2.14/§2.16.5/§4)、L2-architecture 全集 +5(§2.7/§2.8/§2.9/§2.10/§2.13)、L3-critical +2(§2.7.3/§0.5.1),骨架行 R21-R25 保留,锚点写行前 grep 验真=1;L1/L2/L3 变更取包从 1-3 条款骨架变为全集。golden T39 计数 28→41+五类型最小集下限、T40 fixture 扩三类型正常态。§5.1「当前」上界句 144→164KB 口径修正(v3.43.0 重校漏同步,A28 防复发)。A11 评估:DS 163,218B/上界 167,936B 余量 4,718B——本批 DS 正文零改动,减法留批 3+(A/B 实测数据裁决)。§5.2 预算:+3 REQ 对等减法=L1/L2/L3 手工锚点对照阅读路径被注册表包替代延续。**`--upgrade` 无新分发物**(注册表为既有分发件数据行增量)。**回填义务:无**。golden 463→474(T39+5/T40+6),源层断言 376→379(A28+A29×2 SKILL 清单枚举面,基线 378) | -| **v3.46.0** | **条款注册表与阅读包(CHG-056 批 1,Top1 规范倒置第一步)**:新增 `CLAUSE_REGISTRY.md`(条款机器索引层:Rxx 行 ID + `文件名::唯一锚点串` + 类型封闭词表 + 生命周期四类;DS 仍是正文唯一权威)与 `generate-reading-pack.sh`(按类型生成阅读包,锚点 fail-closed 防漂移,`--verify` 可入 CI);DS §2.17.2c 新条款 + AGENTS 锚点表路由行。**`--upgrade` 带走 CLAUSE_REGISTRY.md(→ `/`)+ generate-reading-pack.sh(→ `/`)+ 规范/AGENTS/agent-gate 豁免**。**回填义务:无**——不跑生成命令=零行为变化;A11 减重留批 2+(本版 DS 仅增 §2.17.2c)。golden 463,源层断言 376(基线 375)。 | -| **v3.45.0** | **断言预算制(CHG-055,Top3)**:audit soft 桶(`AGENT_GUARD_AUDIT_SOFT`,A3/A3c/A10 CI 降 warn)+ 断言退役净减 3(双形状/自指 pin)+ MAINTAINER §5.3 断言生命周期(近两版捕获评审→降 soft→退役阶梯)+ DS §2.1 规则 8 歧义分级裁定(bus factor 1 解法)。**`--upgrade` 带走规范/AGENTS/MAINTAINER**(audit/ci.yml/run-tests 源层件)。**回填义务:无**。golden 441,源层断言 366(基线 365)。 | -| **v3.44.0** | **维护税装牙批(CHG-054,Top2)**:L0 最小不可占位集 5→3(04.5/05 轻量声明 + GATE-E52 拦越道空壳);08-supplement 并入 09「补充说明」节(产物 15→14 件,存量合法);audit A25 改 SLOG 派生组 + PART B 快照转正脱版本化(升级零审计手改)。**`--upgrade` 带走 agent-gate + 规范/AGENTS**(audit-standards-src 为源层件)。**回填义务:无**——L0 声明仅新变更生效;存量 08 文件合法。golden 436,源层断言 369(基线 368)。 | -| **v3.43.0** | **缺陷发现入口扩展(CHG-053,FU-106④ + FU-111 闭合)**:新增 `bug-autointent`(信号→完整六件套骨架+指纹频控)与 `regression-to-bug.yml` workflow;session-gate 红灯交互三选项提示;gate die 摩擦账 + metrics 聚合;A6c 编号集并入批次锚点成员。**`--upgrade` 带走 bug-autointent/regression workflow/session-gate/agent-gate/audit-standards-src + 规范/AGENTS**。**回填义务:无**——workflow 按仓测试名改 `workflows:` 列表后才生效;不启用=零影响。golden 431,源层断言 366(基线 365)。 | -| **v3.42.0** | **追踪矩阵单源派发切片(CHG-051,FU-106③)**:`stamp-provenance.sh` 增 `--trace` 派生(并入 `--all`)、audit G5 扩「01.5 REQ ⊆ 01-spec」第二断言。**`--upgrade` 带走 stamp-provenance.sh + audit + 规范/AGENTS 四件**。**存量仓回填义务:无**——手写 §4 行保持合法;新变更 pre-commit 自动获得派生块。golden 419,源层断言 359(基线 358)。 | -| **v3.37.1** | **FU-105 闭合(CHG-037)**:audit G9 面内新增功能目录表外 `reviews/` sweep(信号判据+结构/隐藏目录豁免+空集 VACUOUS)+ golden 三断言 + A25 双 pin。**存量仓回填义务:无**——存量表外 reviews/ 由升级后首跑审计显式亮红(删除/迁移或登记理由)。golden 335,源层断言 320(基线 319)。 | -| **v3.37.0** | **总册命名分层 + P01 瘦身 + 评审落点明文 + 文档地图(CHG-036)**:12 总册+评审配对文件改 P 前缀(`P01-requirements-master.md` 等);P01 需求全景索引改统计+指针形态(禁逐 REQ 行展开);评审唯一落点=变更轨 07+总册 reviews/(§1.3 第 6 条,表外默认禁止);bootstrap `--core` 安装一页文档地图 `/README.md`。**存量仓回填义务(下一变更 begin 前)**:12 册+12 评审按 P 前缀改名(G9 显式红即清单)、P01 实册瘦身。golden 332,源层断言 318(基线 317)。 | -| **v3.36.0** | **缺陷批次扁平化(BUG-006)**:`docs/bugs/BATCH-YYYYMMDD/` 扁平形态(六件套同名文件 + `## BUG-xxx` 锚点、当天同文件追加);v3.35.0 嵌套子目录形态历史合法不回改;gate `bug_group_dir`/`validate_bug_groups`、stamp `--bug`、audit G8/A21 三形态统一解析——`--upgrade` 带走 agent-gate/stamp-provenance/audit + 两模板。**存量仓回填义务:无**(嵌套存量合法;旧"单文件日文件夹"被判红时按 §2.14 补锚点或登记 `.gate-allowlist`)。 | -| **v3.35.0** | **项目级总册体系 + 缺陷三条款(CHG-035/BUG-005)**:`docs/project/` 12 册+逐册评审、09「项目总册回填清单」机校(stop/CI)、begin 强制初始化、缺陷六件套按天入批(v3.36.0 扁平化为 `docs/bugs/BATCH-YYYYMMDD/` 同名文件 + `## BUG-xxx` 锚点)+ 诊断必读总册 + TC 覆盖强制——`--upgrade` 带走 agent-gate/stamp-provenance/audit/project-masters.md/**templates/project(13)**。**存量仓回填义务**:升级后下一变更 begin 前初始化 `/project/`(复制骨架+回填现状+逐册初评)。golden 324,源层断言 309。 | -| **v3.34.0** | **四项打包**:gate L0/L1 评审独立机校(FU-042 闭环)+ metrics `expert_sessions` 观测字段 + session-gate 规则 10 自查表注入 + 能力卡合规样例——`--upgrade` 带走 agent-gate/session-gate/expert-capabilities 三件。**无回填义务**。golden 310。 | -| **v3.33.0** | **gate 执法收紧(FU-039/041 闭环)**:`scripts/agent-gate` 升级即得——治理记录必填 `spec_author`(全等级)、L2/L3 四主体互异、01/03 的「专家评审记录」节强制 §2.1.7 署名(stop/CI)。golden 308。**存量仓唯一动作**:升级后首个新变更的 00-governance.json 按模板声明 `spec_author`(模板已含)。 | -| **v3.32.0** | **对齐+两批制条款**:规范 §2.2 两批制/规则 10 补锚/DoD 补项、`agent-governance.yml`+`stamp-provenance.sh` 注释计数修正(v3.29.1 未落盘缺陷)、`resources/AGENTS.md` 门禁 1 与锚点表、bootstrap --help、能力卡索引补行——`--upgrade` 一次带走。**无回填义务**。FU-041 登记(gate 硬校验,与 FU-039 合并承载)。 | -| **v3.31.0** | **新规范性条款**:§2.1 规则 10(角色单一职责,作者/实现/测试/评审四主体互异)+ `governance-state.json` 模板增 `spec_author` 字段 + §5 "一人多角色"反模式行 + `expert-capabilities.md` 理论出处索引节——`--upgrade` 一次带走。**回填义务:无**(`spec_author` 只约束新变更)。源层:A11 重校准 140→144 KB(协议步进)。 | -| **v3.30.0** | **新方法论层文件**:`resources/methodologies/expert-capabilities.md`(专家能力卡)——`--upgrade` 自动带走(复制清单已扩);规范 §2.2 新增能力卡条款(组合表不变)。**无回填义务**。源层:audit methodologies 动态遍历自动纳入新文件页脚断言(断言 279→282,生成器重写 .audit-baseline)。 | -| **v3.29.1** | **对齐续修(无新规范条款、无行为变更、无回填义务)**:规范正文(计数 15 件、§2.2 措辞与钩子、§3/§5 补行)、`resources/AGENTS.md`(角色段 §2.2 衔接)、`resources/METHODOLOGY.md`(双视角行)随 `--core`/`--upgrade` 下发;双 README 能力表补 2 行;CHANGELOG 补 3.28/3.29 节。门禁/golden 零改动。 | -| **v3.29.0** | **新规范条款(§2.2 分阶段专家评审矩阵)**:`resources/DEVELOPMENT_STANDARDS.md`(§2.1 +9 专家行 + §2.2 新节 + §0.5.2 联动注 + §2.5 阶段 1/2/3/4/5/8 验收行补句)、`resources/AGENTS.md`(锚点表 §2.2 行)随 `--core`/`--upgrade` 下发即可,**无回填义务**(新条款只约束新变更;存量产物不含「专家评审记录」节属合法空转)。门禁/golden 零改动。源仓侧:源层审计 **A11 上界 132KB→140KB 重校准**(v3.29.0 依据:§2.1/§2.2 专家条款演进,两轮措辞压缩后仍超 136KB 约 1.6KB,按 KiB 步进)——`tests/audit-standards-src.sh` 为源层工具不下发,目标仓零影响。§5.1 的"当前上界"句一并更新。 | -| **v3.22.0** | **唯一载荷变更**:`resources/templates/stamp-provenance.sh`(新增 `--all` 全量盖章,默认行为逐字节不变)。已接入项目 `--upgrade` 带过去即可,**无回填义务**——`--all` 是可选加强,不跑它行为与升级前一致。源仓侧同步:`scripts/install.sh`(新增,源层不下发)、双 README 重写 + 新增 `CHANGELOG.md`、`SKILL.md`(一句话安装路径 + `--all` 溯源行 + 版本载体)、源层审计 A19 语义修正(溯源块 ⊆ 活跃∪已闭合)+ A23 锚点组、golden T17b/T21。另修复 `resources/templates/stamp-provenance.sh` 未入库缺陷(此前全新 clone 后 `--guard` 安装必失败)。 | -| **v3.21.2** | **同上——纯对齐续修,无新规范条款、无行为变更、无回填义务**(10 条,逐条见 `resources/STANDARDS_CHANGELOG.md` 顶部行)。承接 v3.21.1 的独立复核发现:规范正文删去派生 Skill 名举例、校正 01.5 边界句措辞;`SKILL.md` 补上"仅当现值仍是内置默认"的条件;`agent-governance.yml` 的 `required_before_merge` 与门禁对齐(3 → 5 件);`scripts/bootstrap.sh` 的派生改三态判定(消掉自定义根安装时的假 NOTE);`MAINTAINER.md` §8 口径按"面"收敛。**建议同步**:`resources/DEVELOPMENT_STANDARDS.md`、`resources/templates/agent-governance.yml`、`SKILL.md`、`scripts/bootstrap.sh`(`--upgrade` 一次带过去即可)。**无回填义务**——历史产物与目录布局逐条不变。 | -| **v3.21.1** | **纯对齐修正——无新规范条款、无行为变更、无回填义务**(15 条,逐条见 `resources/STANDARDS_CHANGELOG.md` 顶部行)。门禁判定强度、产物文件名、目录布局逐条不变,已闭合的历史产物保持原样即合规。**建议同步的副本**(拿对齐后的版本即可):`scripts/check-standards-compliance.sh`(自定义 `` 不在 `/` 下时不再假红)、`.agent-governance.yml`(读取方清单补 `stamp-provenance.sh`)、`resources/templates/` 下的 `06-delivery-summary.md` / `06.5-deployment-config.md` / `PULL_REQUEST_TEMPLATE.md` / `github-artifact-pipeline.yml`(骨架任务号统一为 `TASK-`)。**曾用自定义根部署过的仓库**另需重跑 `bash scripts/bootstrap.sh --all --upgrade <目标仓库>`:本版修掉了 `--docs-dir` 会把显式 pin 的 `change_root` / `bugs_root` 静默改写成派生值的问题(升级不会改动你已 pin 的值)。 | -| **v3.21.0** | 同步 `tests/audit-docs-consistency.sh` **即可**(本版只改通用层审计;`scripts/agent-gate` 与 `scripts/stamp-provenance.sh` 本版未改)。**产物落功能目录 `docs//` 的仓库零影响**——G2/G3/G5/G6 的覆盖与判定逐条不变。**受影响的仓库**:产物落**变更目录** `docs/changes/<变更号>/`(即启用了变更管线的仓库)→ 升级前审计对这四组**完全空转**:`docs/changes` 被当成"子目录",于是"没有产物目录"的空转分支不触发,G2/G3/G5/G6 **一条断言都不执行、也不打印任何行**,而操作者读到的是 "4 passed"。升级后 G2 真正覆盖变更轨(管线态跳号会被判红),未覆盖的组会被点名声明。**升级后会看到一行 `G3/G5/G6 VACUOUS SKIP`**——那是**如实告知未覆盖**,不是失败(变更轨的 §3/§4 一致性由门禁 `--stage stop` 在创建时兜住)。**不要用"把 G3/G5/G6 扩到变更目录"来消灭这行提示**:冻结的历史变更目录按 §2.15 硬性规则 4 / §2.16.5 不可回填,那样只会得到永久无法清除的红。 | -| **v3.20.0** | 同步 `scripts/agent-gate` **即可**(本版只改门禁的"治理记录怎么读";`stamp-provenance.sh` 与 `tests/audit-docs-consistency.sh` 本版未改)。**一直写单行记录的仓库零影响**——行为逐字节不变。**受影响的仓库**:`00-governance.json` 写成**多行格式化**的(即照 `resources/templates/governance-state.json` 模板生成的默认形状)→ 升级前 `begin` 报 `must declare risk_level L0, L1, L2, or L3`(字段其实就在 `change_id` 下面两行)、`metrics` 对每条记录报 `"risk_level":null`;升级后立即恢复通过。**这是 v3.18.0 引入的静默回归**(为支持批次把读取器从整文件改成行式),凡升过 v3.18.0 / v3.19.0 **且记录是多行**的仓库都中招——本仓自己的账本 16/16 条全中。**不要用"把记录压成单行"来绕过**:升级门禁才是正解。 | -| **v3.19.0** | 同步 `scripts/agent-gate` 与 `tests/audit-docs-consistency.sh` **两者**(`stamp-provenance.sh` 本版未改)。**不用批次的仓库零影响**——独立 `<变更号>/` 目录永远优先,新增的 `gov_ids()` 只在 `BATCH-*/` 分支被调用。**采用批次的仓库**:本版修掉"批次被它自己强制的内容卡住"——门禁与审计曾把**每一个** `## <标题>` 都当变更号,于是 §2.16.2 强制的 `## Observation` 会让 `--stage staged` / CI **拒掉一个完全合法的批次**,并给 `metrics` 加一行幽灵变更。升级后原先被误拒的批次交付立即恢复通过。 | -| **v3.18.0** | **无需补复制动作、无需回填**——批次是**可选**布局,不建 `BATCH-*/` 的仓库行为与升级前逐字节等价(独立 `<变更号>/` 目录永远优先)。同步 `scripts/agent-gate`(批次解析 + 行式治理记录 + 批次闭环判定 + 每变更一行 metrics)、`scripts/stamp-provenance.sh`(批次感知 + `batch_changes:`)、`tests/audit-docs-consistency.sh`(新增 G7 批次自洽组)**三者**。**只有想用批次的仓库需要动作**:把同一天的 L0/L1 变更放进 `/changes/BATCH-YYYYMMDD/`,产物**沿用原名**(不要改名),同批变更用 `## <变更号>` 小节分开,`00-governance.json` 改为**一行一个 JSON 对象**。**注意 L2/L3 不得入批**(门禁会按记录拒绝)。另本版修掉一个 bash 3.2 潜伏缺陷(`local a="$1" b="...$a"` 在 `set -u` 下报 unbound variable,只在 `--stage staged` / CI 路径现形)——同步 `agent-gate` 即修复。 | -| **v3.17.0** | 补 `scripts/stamp-provenance.sh` 到 `/`(随 `--guard` 层落地);`.agent-governance.yml` 新增 `provenance:` 段(默认 `include_email: true`);`04.5-coding-record.md` 模板新增占位溯源块与验收勾选项;同步 `scripts/agent-gate`(新增溯源校验)。**这是一次交付门禁收紧**:`--stage stop` 与 branch 模式 CI 现在要求 `04.5-coding-record.md` 携带**由脚本生成**的溯源块。**老项目升级后下一次变更收尾前须跑一次 `scripts/stamp-provenance.sh <变更号>`,不跑即被拦下**。**不要回填历史变更**——门禁只校验活跃变更,回填会把 `generated_at` 伪造成今天(审计 A19 有反向断言)。仅装了 core 层未装 guard 层的项目不受影响。 | -| v3.16.0 | 补 `MAINTAINER.md`(仅本仓库,**不随分发**);`.agent-governance.yml` 无变化。**无需补复制动作**——本版改的是 Skill 自身的分发与升级行为(`--check` / `--self-update` / `--derived-report` 三个新 flag、`--upgrade` 不再覆盖显式层选择、派生资产跳过保护、`docs/STANDARDS_CHANGELOG.md` 归属声明)。升级**仅当**目标仓曾在本仓 `docs/STANDARDS_CHANGELOG.md` 追加过本地行时会拒绝,需显式 `--force` 或先移出本地行。 | -| **v3.15.0** | `.agent-governance.yml` 新增 `paths:` 段(`docs`/`scripts`/`tests`/`githooks`)与 `bugs_root`;`scripts/agent-gate`、`scripts/check-standards-compliance.sh`、`tests/audit-docs-consistency.sh` **三者必须一起升级**(只升其一即静默错位)。**默认值即历史写死值,老项目不配置 `paths:` 时行为与升级前完全一致 → 升级本身不要求任何回填**;想换根的项目再跑一次 `bash scripts/bootstrap.sh --all --docs-dir <新根> <目标仓库>`。 | -| v3.7.0 修订(CHG-004) | 补 `06.5-deployment-config.md` 与 `06-delivery-summary.md` 到 `/`,并同步 `scripts/agent-gate`。**这是一次交付门禁收紧**:此前 `--stage stop` 只校验 `04.5`/`05`/`09`,现在 `06.5` 与 `06-delivery-summary` 同样必检,老项目升级后需补齐这两份文档(未命中也要显式声明"未命中,不适用")才能通过。规范正文 §1.1 早已声明"八类缺一即未完成",本修订只是让实现与已声明的语义对齐,故**不升规范版本号**。 | -| v3.7.0 | 缺陷模板扩为**六件套**(补 `bug-matrix.md`/`bug-config.md`/`bug-tasks.md`);补编码记录模板 `coding-record.md`(变更起编时落 `/changes/<变更号>/04.5-coding-record.md`);同步更新 `scripts/agent-gate` 与 `tests/run-tests.sh`。 | -| v3.6.0 | 补缺陷文档组模板 `bug-diagnosis.md`/`bug-impact.md`/`bug-test-plan.md` 到 `/bugs/_templates/`。 | -| v3.5.0 | 补 `commit-msg` 模板到 `/`,并更新 `pre-push` 与 `scripts/agent-gate`。 | -| v3.3.0 / v3.4.0 | 补 `METHODOLOGY.md`、`methodologies/`(v3.4.0 含 `state-trigger-audit.md`)与 `bugfix-log.md` 到 `/`。 | + +**历史版本(v3.78.0 及更早)的逐版动作不再在此罗列**——那是会过时的信息,且与 `resources/STANDARDS_CHANGELOG.md` 重复(该文件才是权威)。下面这张表只收**`--upgrade` 不会自动处理、必须人动手**的项;其余由 `--upgrade` 覆盖,逐版细节查 CHANGELOG 对应行: + +| 版本 | 必须手工做 | +|---|---| +| v3.78.0 | 分支保护必检项**保持 job 名 `agent-governance`**(该版起为聚合 job,改名 = 静默失效) | +| v3.76.0 | `LIVE_SKIP` 方言自检:升级后确认 `bugfix-log`/`delivery-summary`/`06.5` 未被覆盖 | +| v3.67.0 | 总册 P12 产品上下文册需**人工回填**(模板可生成,内容不可代填) | +| v3.37.0 | 总册册号 `P` 前缀改名:旧仓需按 CHANGELOG 行重命名 `docs/project/` 下文件 | +| v3.15.0 | `agent-gate` / `check-standards-compliance.sh` / `audit-docs-consistency.sh` **三者必须一起升**(只升其一即静默错位) | +| v3.7.0 修订 | 补齐 `06.5-deployment-config.md` 与 `06-delivery-summary.md`(未命中也要显式声明) | +| v3.7.0 | 补缺陷六件套模板 + `coding-record.md` | +| v3.6.0 | 补缺陷三件模板(`bug-diagnosis`/`bug-impact`/`bug-test-plan`) | +| v3.5.0 | 补 `commit-msg` 模板 | +| v3.3.0 / v3.4.0 | 补 `METHODOLOGY.md` + `methodologies/` + `bugfix-log.md` | > 更细的"本版改了什么、对既有文档有什么回填义务",以 `resources/STANDARDS_CHANGELOG.md` 为准——**本表只是升级动作的速查,不复制变更条款**。 diff --git a/README.md b/README.md index cde89db..e358ceb 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![CI](https://github.com/geekma/dev-standards-bootstrap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/geekma/dev-standards-bootstrap/actions/workflows/ci.yml) -[![Standards Version](https://img.shields.io/badge/Standards-v3.88.0-green.svg)](resources/DEVELOPMENT_STANDARDS.md) +[![Standards Version](https://img.shields.io/badge/Standards-v3.92.2-green.svg)](resources/DEVELOPMENT_STANDARDS.md) [![AGENTS.md](https://img.shields.io/badge/Entry_Point-AGENTS.md-orange.svg)](resources/AGENTS.md) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](../../pulls) @@ -87,7 +87,7 @@ Not theory — a three-way contribution analysis measured on 11 real working ses | **Bug Fix Log + Same-Family Scan + Root-Cause Classification** | Repo-level append-only `bugfix-log.md` index; root-cause tables carry a **same-family** scan row and a mutually-exclusive classification anchored at the earliest unrecovered failure point (AgentRx-derived; §2.5 Stage 6) — fix without family scan is rejected | | **Deterministic Gate + Pipeline Automation** | One dependency-free validator shared by write-time hooks, Git hooks, and CI; spec merge auto-dispatches skeletons, changelog merge auto-opens a release checklist, incidents auto-create `BUG-` intent PRs; autonomy capped at A2 (§2.17) | | **Release Integrity + Evidence Reuse** | One version authority (`scripts/release.sh check\|bump`) verifies every carrier and rewrites only declared sites; CI runs the full suite once, uploads a tree-keyed receipt, and reuses it for hard audit gates; a workspace suite lock admits one full run at a time and reclaims dead owners | -| **Golden-Case Self-Tests** | `tests/run-tests.sh` regression-tests the gate and the installer (1308 golden-case assertions) in throwaway git repos — bash + git only (§2.17.4) | +| **Golden-Case Self-Tests** | `tests/run-tests.sh` regression-tests the gate and the installer (1594 golden-case assertions) in throwaway git repos — bash + git only (§2.17.4) | `agent-gate metrics` emits read-only JSON Lines pipeline metrics from git history — observation only, never a substitute for DoD (§2.17.5). Specialized standards cover deployment/config/DB changes, AI/LLM pipelines, test data isolation, emergency hotfixes, release, monitoring, and supply chain (§2.6–§2.13). The single version history is [`resources/STANDARDS_CHANGELOG.md`](resources/STANDARDS_CHANGELOG.md) (shipped to target repos, machine-pinned by audit G1). @@ -201,13 +201,18 @@ Command reference (invoked by the above; manual runs are for debugging): | Command | Purpose | |---|---| -| `begin ` / `end` | Activate or clear the active change; requires the eight change artifacts and validates governance state (risk level, distinct execution owners; L3 additionally the three `release_authorized_by`-family authorization fields) plus A-layer content markers | +| `begin ` / `end` | Activate or clear the active change; the **entry gate** validates the three entry artifacts (00-intent / 00-governance / 00.5) plus governance state (risk level, distinct execution owners; L3 additionally the three `release_authorized_by`-family authorization fields) and A-layer markers; the 01–04 artifact checks run at the stateless stage gates | +| `--stage spec\|design\|testplan` | Stateless stage gates read disk anchors only — spec: 01 REQ anchors + gap-free numbering; design: 02 three-dimensional impact/rollback + 03 option comparison/existing-paradigm + 03.5 tasks; testplan: 04 TC matrix + TC landing list. Idempotent, no stage-state file; `AGENT_GUARD_STAGE_GATES=0` restores the legacy full begin check (default on = new semantics) | | `--stage pre-write` | Validates the active change before an agent writes source code; fails closed if the target path cannot be parsed from hook input | | `--stage staged` | Staged source changes must ship with matching change artifacts, otherwise the commit is rejected | | `--stage commit-msg ` | Attribution gate: a code-bearing commit must reference a valid change id (merge / revert / docs-only exempt) | | `--stage stop` | Ending a turn after source edits requires `04.5-coding-record.md`, `05-test-results.md`, `09-changelog.md` (with ReAct Observation records), plus a passing verification command (L0: 04.5/05 may be §1.1 single-line declarations, v3.44.0); changelog REQ ids must be backfilled in `01.5-rtvm-matrix.md` (Gate 4 closure) | | `--stage ci [--base ]` | Rechecks the branch/PR diff and runs the real verification command | -| `metrics` | Read-only pipeline metrics as JSON Lines — observations only; aggregates the gate-friction ledger (die codes → counts, v3.43.0) | +| `plan [--explain\|--dry-run]` / `plan --refresh-profile` | Read-only adaptive decision engine (v3.90.2+, hardened in v3.91.0): reads the profile + diff + cost ledger and writes `decision` into `00-governance.json` (sections, predicted seconds, CAB `deferred`/`wasted`, nested artifacts/stages/masters, `must`, TC resolution rate). The decision is a **proposal**: the agent must show the card plus three options (adopt / up / down) and the user chooses; a narrowed AI scope is only valid with `AGENT_GUARD_SCOPE_CONFIRM` recorded as `decision.scope_confirmed`. `--explain` prints the cost/coverage account; `--refresh-profile` reports missing profile keys. Off switch: `AGENT_GUARD_ADAPT=0` | +| `status` | Prints the effective enforcement face — runtime, hook-protocol family, layers, `enforcement=hook\|handshake`, handshake presence and the current model/context window (v3.91.0) | +| `resume ` | Restores a shifted session from `handoff.md` + `decision` and prints the next steps; read-only, usage error is `GATE-E149` | +| `baseline [--write]` / `tc-index [--write]` | P0-0 five-number baseline snapshot and P1-2 three-source TC index (04 matrix + script self-declarations + RTVM); the index is a target-repo cache, never a contract artifact | +| `metrics` | Read-only pipeline metrics as JSON Lines — observations only; aggregates the gate-friction ledger (die codes → counts, v3.43.0) and, since v3.91.0, adoption/wasted/stale/handshake/review-independence columns | **File provenance**: the coding record must carry a `` block produced by `scripts/stamp-provenance.sh ` — author, committer, commit, host, platform and UTC time are read from the running environment, so they cannot be typed by hand. `--all` stamps every `*.md` artifact of the change directory (the governance JSON is deliberately excluded); since v3.41.0 the pre-commit hook runs it automatically, and v3.42.0 adds `--trace` — the changelog's §4 traceability ids are derived from the `01.5-rtvm-matrix.md` instead of hand-typed. The gate checks block shape and producer; truthfulness of `author` itself is *not* machine-verifiable, and the design says so. No retroactive stamping: history is never back-filled, because back-filling would forge `generated_at` — the very thing the block exists to prevent. @@ -314,12 +319,12 @@ Any change that fails any gate is **blocked from merge to main**. ## Governance Details -- **Execution-side token discipline (v3.24.0/v3.25.0; recalibrated to 15 rules in this version)**: the shipped `AGENTS.md` carries a **15-rule** "Agent execution resource discipline" section (piped filtering / single-pass grep / locate-then-window reads / delegated exploration / no-match ≠ pass / parallel batches / targeted verification / stateful mock isolation / no parallel integration tests / long-task waiting / environment-attribution resume / call batching / tail-incremental reads / frozen-tree parallel dispatch / phased minimal read set); §2.9.6 session-context discipline (one topic per session, handoff beyond 50 turns or on topic switch); §2.5 minimal-expression artifact shapes with a ≤40-line soft cap — targeting cache_read (= context level × turns). **Read-set rule**: DS is never read in full; read it in phases per discipline 15 (this version removes the old rule 1 vs rule 15 contradiction). +- **Execution-side token discipline**: the shipped `AGENTS.md` carries a **15-rule** "Agent execution resource discipline" section, plus §2.9.6 session-context discipline and §2.5 minimal-expression shapes with a ≤40-line soft cap — targeting cache_read (= context level × turns). **Sole authority for the rule text, numbering and read-set rule: the shipped `AGENTS.md` section**; this README deliberately does not restate it. - **Same-day change batches (v3.18.0; defaulted in v3.24.0; sequence clarified in v3.61.2)**: the **first L0/L1** change (or defect) of the day creates `/changes/BATCH-YYYYMMDD/` immediately; later same-day L0/L1 changes join it via section anchors instead of opening their own directories. Only the directory is relaxed — artifact filenames are unchanged, bundled changes are told apart by a `## ` section anchor, and the batch's change set is read from the authoritative roster in `00-governance.json` (never inferred from headings). The risk ceiling is not relaxed: **L2/L3 must live in their own directory**, and the gate refuses an L2/L3 record found inside a batch (per the governance roster). - **Defect groups join daily batches by default (v3.35.0, flat since v3.36.0)**: the first same-day defect creates one flat `docs/bugs/BATCH-YYYYMMDD/` directory and later same-day defects join it — six files named exactly as before, told apart by `## BUG-xxx` section anchors, same-day appends land in the same files (per-defect subdirectories remain a legal legacy form). The append-only `docs/bugfix-log.md` index (one dated row per bug) stays the day-level retrieval layer, and a defect's change-track entry (`BUG-*`) may still join a change batch like any other change. -- **Methodology selection (M0–M3)**: `docs/METHODOLOGY.md` is the sole authority for which methodologies are allowed at which level; `docs/methodologies/development.md`, `docs/methodologies/data-structures.md`, `docs/methodologies/state-trigger-audit.md`, `docs/methodologies/expert-capabilities.md` and `docs/methodologies/project-masters.md` carry the per-item engineering rationale (SOLID/DRY applicability, weak-typing ban, implicit state/trigger-link three-way traversal, expert theory toolboxes). `docs/STAGE_PLAYBOOK.md` carries the operational detail migrated from DS §2.5 / §2.16.6 (clause authority stays in DS, v3.61.0). +- **Methodology selection (M0–M3)**: `docs/METHODOLOGY.md` is the sole authority for which methodologies are allowed at which level; `docs/methodologies/development.md`, `docs/methodologies/data-structures.md`, `docs/methodologies/state-trigger-audit.md`, `docs/methodologies/expert-capabilities.md`, `docs/methodologies/project-masters.md` and `docs/methodologies/review-intelligence.md` carry the per-item engineering rationale (SOLID/DRY applicability, weak-typing ban, implicit state/trigger-link three-way traversal, expert theory toolboxes, AI review intelligence + runtime/model selection). `docs/STAGE_PLAYBOOK.md` carries the operational detail migrated from DS §2.5 / §2.16.6 (clause authority stays in DS, v3.61.0). - **Self-evolution**: skills derived from this one (declaring `derived_from: dev-standards-bootstrap`) live and evolve independently, and every installer/upgrade write path skips them; `--force` does not override that. `bash scripts/bootstrap.sh --derived-report` lists them. -- **Cross-document consistency audit**: `bash tests/audit-docs-consistency.sh` (G1 version chain / G2 numbering continuity + globally unique change UID / G3 archive sync / G4 bugfix cross-registration / G5 RTVM backfill / G6 required sections / G7 batch self-consistency / G8 defect six-file existence / G9 project masters presence+self-attestation+backfill ledger+out-of-table feature-dir reviews sweep / G10 deprecation-marker sweep — a deprecation marker must carry its replaced-by version pointer (v3.41.0) / G11 UJ↔REQ coverage / G12 five-party evidence / G13 three-dimensional cross-check / G14 source cross-check / G15 source-artifact mapping closure / A-group provenance cross-checks) runs in CI or locally; failed items are the backfill list. +- **Cross-document consistency audit**: `bash tests/audit-docs-consistency.sh` runs the **G1–G16** invariant groups plus the A-group provenance cross-checks (definition authority: the script header; human index: the anchor table in `resources/AGENTS.md`) in CI or locally; failed items are the backfill list. This README does not re-enumerate the groups. ## Repository Structure @@ -359,6 +364,7 @@ dev-standards-bootstrap/ │ ├── mutation-check.sh # Source-layer only (NOT shipped): checker self-test — four fixed mutations must turn the fast checkers red, inside throwaway copies only │ ├── ci-summary.sh # Source-layer only (NOT shipped): renders the CI run summary and hard-gates tests/.suite-baseline against the receipt's passed count │ ├── batch-metrics.sh # Source-layer only (NOT shipped): per-batch cost ledger (turns / edits / polls / full-suite runs / wall time) in .agent-state +│ ├── replay-plan.sh # Source-layer only (NOT shipped): read-only replay of historical change diffs through today's `-T auto` resolver vs the sections 05 records — reports FULL-fallback rate and false negatives │ ├── lib-source-facts.sh # Source-layer only (NOT shipped): shared read-only fact helpers used by the six tools above │ ├── setup-branch-protection.sh # Source-layer only (NOT shipped): prints the gh api payload for the required check (dry run); `--apply` mutates the remote │ ├── lib-suite-tree-fingerprint.sh # Shared library: suite tree fingerprint used by receipt keying (installed with tests/run-tests.sh by --guard) @@ -375,7 +381,7 @@ dev-standards-bootstrap/ └── resources/ ├── AGENTS.md # Entry point for AI agents (copied to target repo root) ├── CLAUSE_REGISTRY.md # Clause registry: machine index of standards clauses (Rxx id + filename::anchor + type vocab); DS stays the sole prose authority; feeds reading-pack generator (v3.46.0) - ├── DEVELOPMENT_STANDARDS.md # Full standards document v3.88.0 (copied to docs/) + ├── DEVELOPMENT_STANDARDS.md # Full standards document v3.92.2 (copied to docs/) ├── STANDARDS_CHANGELOG.md # Standards upgrade history (sole home of §2.14 upgrade log, v3.8.0; copied to docs/) ├── METHODOLOGY.md # Methodology selection guide: M0-M3 levels + stage x methodology x applicable / not-applicable table (copied to docs/) ├── STAGE_PLAYBOOK.md # Stage playbook: operational detail carried over from DS §2.5 / §2.16.6 (clause authority stays in DS; copied to docs/) @@ -385,11 +391,12 @@ dev-standards-bootstrap/ │ ├── state-trigger-audit.md # State/trigger-link audit: 6 lessons + 6-step checklist + 3 anti-patterns (v3.4.0) │ ├── expert-capabilities.md # Expert capability profiles: 9 core + product-usability expert + 3 conditional experts (theory / breadth / experience / adaptation; v3.67.0 adds the UX/UAT card) │ └── project-masters.md # Project master set detail layer: 13 masters, sections, backfill/annotation semantics (v3.35.0; v3.67.0 adds P12 product-context master) + │ └── review-intelligence.md # AI review contract: project context, domain capability, runtime detection, model-cost consent, independence └── templates/ ├── docs-readme.md # One-page docs map (v3.37.0): five layers, roles, update timing (→ /README.md) ├── communication.md # Communication-first gate artifact (v3.52.0): round-1 communication draft + user overall confirmation record (→ docs/changes//00.5-communication.md) ├── project # Project master set (v3.67.0): 13 SDLC masters P00–P12 + review-record template (→ docs/templates/project/) - ├── entry # Change-entry skeletons (v3.67.0): the eight begin-required artifacts + conditional 03.6-ui-spec.md + shape templates 01.5/05/07/09 (v3.70.0 CHG-045, → docs/templates/entry/) + ├── entry # Change-entry skeletons (v3.67.0): the eight entry templates (begin validates the three entry artifacts; 01–04 are checked by the stage gates) + conditional 03.6-ui-spec.md + shape templates 01.5/05/07/09 (v3.70.0 CHG-045, → docs/templates/entry/) ├── new-change.sh # Change-entry scaffolder (v3.43.0): dedicated-dir vs same-day-batch resolution (→ scripts/new-change) ├── CLAUDE.md # One-line import for Claude Code ├── PULL_REQUEST_TEMPLATE.md # GitHub PR template with gate self-check @@ -403,6 +410,7 @@ dev-standards-bootstrap/ ├── bug-diagnosis.md, bug-impact.md, bug-test-plan.md, bug-matrix.md, bug-config.md, bug-tasks.md # Six-file defect document set (→ docs/bugs/_templates/) ├── 06.5-deployment-config.md # Deployment/config/DB record template (→ docs/; must declare "未命中,不适用" when not hit) ├── 06-delivery-summary.md # Delivery summary + FU ledger template (→ docs/; four mandatory sections per §2.5 stage 9.5) + ├── review-models.json # Review-model catalog example (→ .agent-review-models.example.json; rename to .agent-review-models.json to activate tiers/consent) ├── audit-docs-consistency.sh # Cross-doc consistency audit: version chain / numbering continuity / checklist sync / bugfix cross-registration / RTVM backfill / change-batch self-consistency (copied to tests/) ├── governance-state.json # Template for each change's 00-governance.json (NOT shipped — the agent writes it per change) ├── agent-governance.yml # Team-reviewable governance config record (copied to .agent-governance.yml) @@ -456,8 +464,8 @@ This repo's own CI (`.github/workflows/ci.yml`, not shipped as a template) runs | Job | What it does | |---|---| -| **Source-layer audit** | `tests/audit-standards-src.sh` — audits the standards text itself: version chain, keyword matrix, checklist uniqueness, numbering, tautology-proof greps (assertions: 641) | -| **Golden-case self-tests** | `tests/run-tests.sh` — regression-tests the gate and the installer (1308 golden-case assertions) in throwaway git repos; bash + git only | +| **Source-layer audit** | `tests/audit-standards-src.sh` — audits the standards text itself: version chain, keyword matrix, checklist uniqueness, numbering, tautology-proof greps (assertions: 659) | +| **Golden-case self-tests** | `tests/run-tests.sh` — regression-tests the gate and the installer (1594 golden-case assertions) in throwaway git repos; bash + git only | | **agent-governance** | Aggregate required-check context: fails unless both jobs above succeed (stable name for branch protection) | **There is no soft mode and no double run in CI.** golden-case runs the suite once with `-j 4` under a 600s wall budget (`AGENT_GUARD_CI_WALL_BUDGET_S`, so a regression fails loudly instead of drifting into the job timeout) and uploads `.agent-state/last-suite-receipt.json` for human forensics. source-audit no longer consumes that artifact: A3/A3c/A10 read the **committed baselines** and run as hard gates (no `AGENT_GUARD_AUDIT_SOFT`), which is also why it needs no dependency on the suite job and runs in parallel with it. **The two real jobs are bounded by `timeout-minutes: 15`; the aggregate `agent-governance` gate by 5.** A workspace suite lock (`lib-suite-lock.sh`, shipped with `--guard`) admits one full run per workspace and reclaims dead owners; receipt and red-report paths are env-overridable (`AGENT_GUARD_SUITE_RECEIPT_PATH` / `AGENT_GUARD_SUITE_RED_PATH`) so parallel self-tests never touch live ledgers. A workflow-level `concurrency` group cancels superseded runs on the same ref. @@ -496,7 +504,7 @@ This project is licensed under the [MIT License](LICENSE).
-**Standards Version:** v3.88.0 | **Last Updated:** 2026-10-21 | **Maintainer:** [geekma](https://x.com/geekma) | **Email:** geekma@gmail.com +**Standards Version:** v3.92.2 | **Last Updated:** 2026-10-27 | **Maintainer:** [geekma](https://x.com/geekma) | **Email:** geekma@gmail.com [Report Bug](../../issues) | [Request Feature](../../issues) | [Read the Standards](resources/DEVELOPMENT_STANDARDS.md) | [Changelog](resources/STANDARDS_CHANGELOG.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index c9d93a6..28b1d35 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -7,7 +7,7 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![CI](https://github.com/geekma/dev-standards-bootstrap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/geekma/dev-standards-bootstrap/actions/workflows/ci.yml) -[![Standards Version](https://img.shields.io/badge/规范版本-v3.88.0-green.svg)](resources/DEVELOPMENT_STANDARDS.md) +[![Standards Version](https://img.shields.io/badge/规范版本-v3.92.2-green.svg)](resources/DEVELOPMENT_STANDARDS.md) [![AGENTS.md](https://img.shields.io/badge/Entry_Point-AGENTS.md-orange.svg)](resources/AGENTS.md) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](../../pulls) @@ -87,7 +87,7 @@ | **缺陷日志 + 同族推演 + 根因分类** | 仓库级追加式 `bugfix-log.md` 索引;根因表必含**同族推演**行与互斥根因分类,锚定最早未恢复失败点(AgentRx 依据;§2.5 阶段 6)——不做同族扫描的修复被拒 | | **确定性门禁 + 管线自动化** | 一个零依赖校验器被写入时 Hook、Git Hook 与 CI 共享;spec 合入自动派发骨架 PR、changelog 合入自动开发布检查单、事故自动生成 `BUG-<时间戳>` 意图 PR;自主权上限 A2(§2.17) | | **发布完整性 + 证据复用** | 单一版本权威(`scripts/release.sh check\|bump`)校验全部载体、只重写声明位点;CI 只跑一次全量套件并上传树指纹收据,硬审计复用同一收据;工作区套件锁同一时刻只允许一次全量运行并回收死锁主 | -| **golden case 自测试** | `tests/run-tests.sh` 在临时 Git 仓库里回归测试门禁与安装器(1308 项 golden-case 断言)——只需 bash + git(§2.17.4) | +| **golden case 自测试** | `tests/run-tests.sh` 在临时 Git 仓库里回归测试门禁与安装器(1594 项 golden-case 断言)——只需 bash + git(§2.17.4) | `agent-gate metrics` 从 git 历史输出只读 JSON Lines 管线度量——仅作观察,永不替代 DoD 判定(§2.17.5)。专项规范覆盖部署/配置/DB、AI/LLM 管线、测试数据隔离、紧急热修复、发布、监控与供应链(§2.6–§2.13)。唯一版本历史是 [`resources/STANDARDS_CHANGELOG.md`](resources/STANDARDS_CHANGELOG.md)(随 --core 下发,audit G1 机校)。 @@ -201,13 +201,18 @@ bash dev-standards-bootstrap/scripts/bootstrap.sh --all <目标仓库> | 命令 | 用途 | |---|---| -| `begin <变更号>` / `end` | 激活或清除活跃变更;要求八件变更产物并校验治理状态(风险等级、互异的执行主体;L3 另须三个 `release_authorized_by` 系列授权字段)与 A 层内容标记 | +| `begin <变更号>` / `end` | 激活或清除活跃变更;**入口门**只校验入口三件(00-intent / 00-governance / 00.5)与治理状态(风险等级、互异的执行主体;L3 另须三个 `release_authorized_by` 系列授权字段)及 A 层内容标记;01–04 产物校验由无状态阶段门承接 | +| `--stage spec\|design\|testplan` | 无状态阶段门只读磁盘锚点——spec:01 REQ 表+编号连续;design:02 三维影响/回滚 + 03 选型比较/既有范式关系 + 03.5 任务拆解;testplan:04 用例矩阵+TC 落点清单。幂等、不写阶段状态文件;`AGENT_GUARD_STAGE_GATES=0` 恢复旧 begin 全查(默认开=新语义) | | `--stage pre-write` | Agent 写源码前校验活跃变更;无法从 Hook 输入解析目标路径即 fail-closed | | `--stage staged` | 暂存的源码变更必须随带匹配的变更产物,否则提交被拒 | | `--stage commit-msg ` | 归因闸门:含代码的提交必须引用有效变更号(合并/回退/纯文档豁免) | | `--stage stop` | 源码改动后收尾要求 `04.5-coding-record.md`、`05-test-results.md`、`09-changelog.md`(含 ReAct Observation)及验证命令通过(L0:04.5/05 可按 §1.1 单行声明,v3.44.0);changelog 引用的 REQ 须回填 `01.5-rtvm-matrix.md`(门禁 4 闭环) | | `--stage ci [--base ]` | 复查分支/PR diff 并运行真实验证命令 | -| `metrics` | 只读管线度量(JSON Lines)——仅观察;聚合 gate 摩擦事件账(die 错误码→计数,v3.43.0) | +| `plan <变更号> [--explain\|--dry-run]` / `plan --refresh-profile` | 只读自适应判定引擎(v3.90.2 起,v3.91.0 加固):读画像 + diff + 成本台账,把 `decision` 写进 `00-governance.json`(选节、预计秒数、CAB `deferred`/`wasted`、嵌套 artifacts/stages/masters、`must`、TC 解析率)。判定是**议案不是判决**:AI 必须把判定卡与三选一(采纳/升档/降档)交给用户选;AI 收窄必须带 `AGENT_GUARD_SCOPE_CONFIRM` 并落 `decision.scope_confirmed`。`--explain` 打印成本/覆盖账;`--refresh-profile` 报 profile 缺键。总开关 `AGENT_GUARD_ADAPT=0` | +| `status` | 打印生效执法面——runtime、hook 协议家族、层、`enforcement=hook\|handshake`、握手是否存在、当前模型/上下文窗口(v3.91.0) | +| `resume <变更号>` | 从 `handoff.md` + `decision` 恢复换挡会话并打印下一步;只读,缺参报 `GATE-E149` | +| `baseline <变更号> [--write]` / `tc-index <变更号> [--write]` | P0-0 五数基线与 P1-2 三源 TC 索引(04 矩阵 + 脚本自声明 + RTVM);索引是目标仓缓存,不是契约产物 | +| `metrics` | 只读管线度量(JSON Lines)——仅观察;聚合 gate 摩擦事件账(die 错误码→计数,v3.43.0),v3.91.0 起增采纳/wasted/stale/握手/评审独立性列 | **文件溯源**:编码记录必须携带由 `scripts/stamp-provenance.sh <变更号>` 生成的 `` 块——作者、提交者、提交哈希、主机、平台、UTC 时间全部从运行环境读出,手写编不出来。`--all` 可给变更目录全部 `*.md` 产物盖章(治理 JSON 刻意排除);v3.41.0 起 pre-commit Hook 自动执行,v3.42.0 增 `--trace`——changelog §4 的追踪矩阵编号从 `01.5-rtvm-matrix.md` 确定性派生,不再手抄。门禁校验块形状与生产者;`author` 值本身是否属实**不可机器验证**——设计如实说明而非假装已解决。不追溯既往:历史永不回填,因为回填会把 `generated_at` 伪造成"今天"——那正是溯源块要防的事。 @@ -314,12 +319,12 @@ bash dev-standards-bootstrap/scripts/bootstrap.sh --all <目标仓库> ## 治理细节 -- **执行侧 token 纪律(v3.24.0/v3.25.0;本版校准为 15 条)**:下发的 `AGENTS.md` 内置「Agent 执行资源纪律」**十五条**(管道过滤/一次拉全/先定位后小窗/勘探下放/无匹配≠通过/并行批量/定向验证/有状态 mock 隔离/禁并行集成测试/长任务等待/环境归因续跑/调用批处理/尾部增量读/冻结树并行派发/分阶段最小读集);规范 §2.9.6 会话与上下文纪律(单会话单主题,>50 轮或主题切换即 handoff);§2.5 产物最小表达形态 + 单产物 ≤40 行软上限——目标:压 cache_read(= 上下文水位 × 轮数)。**读集口径**:DS 永不整读,按纪律 15 分阶段定点读(本版消除规则 1 与规则 15 的旧矛盾)。 +- **执行侧 token 纪律**:下发的 `AGENTS.md` 内置「Agent 执行资源纪律」**十五条**,另有规范 §2.9.6 会话与上下文纪律、§2.5 产物最小表达形态(单产物 ≤40 行软上限)——目标:压 cache_read(= 上下文水位 × 轮数)。**规则正文、编号与读集口径的唯一权威 = 随包 `AGENTS.md` 该节**;本 README 刻意不复述。 - **同日变更批次(v3.18.0;v3.24.0 默认化;v3.61.2 时序澄清)**:当天**首个 L0/L1** 变更/缺陷**即建** `/changes/BATCH-YYYYMMDD/`,后续同日变更/缺陷以锚段小节并入,而不是各建一个。放宽的只有目录——产物文件名一字不改,同批变更用 `## <变更号>` 小节锚点区分,批次变更集合从 `00-governance.json` 的权威名单读取(绝不从标题反推)。风险上限不放宽:**L2/L3 必须独立目录**,门禁按治理记录拒绝批次内的 L2/L3(以 `00-governance.json` 名单为准)。 - **缺陷六件套默认按天入批(v3.35.0;v3.36.0 扁平化)**:当天首个缺陷即建扁平 `docs/bugs/BATCH-YYYYMMDD/`、后续同日缺陷并入——六件套文件名一字不改,用 `## BUG-xxx` 小节锚点区分,当天的追加/回填落在同一套文件里(逐缺陷子目录为历史合法形态,存量不回改);追加式 `docs/bugfix-log.md` 索引(每缺陷一行、带日期)保持天级检索层;缺陷的**变更轨入口**(`BUG-*`)仍可像普通变更一样入批。 -- **方法论选型(M0–M3)**:`docs/METHODOLOGY.md` 是哪一级允许哪些方法论的唯一权威;`docs/methodologies/development.md`、`docs/methodologies/data-structures.md`、`docs/methodologies/state-trigger-audit.md`、`docs/methodologies/expert-capabilities.md` 与 `docs/methodologies/project-masters.md` 提供逐条工程依据(SOLID/DRY 适用性、弱类型禁令、隐式状态/触发链路三向遍历、专家理论工具箱)。`docs/STAGE_PLAYBOOK.md` 承载自 DS §2.5/§2.16.6 迁移的操作性细则(条款权威仍在 DS,v3.61.0)。 +- **方法论选型(M0–M3)**:`docs/METHODOLOGY.md` 是哪一级允许哪些方法论的唯一权威;`docs/methodologies/development.md`、`docs/methodologies/data-structures.md`、`docs/methodologies/state-trigger-audit.md`、`docs/methodologies/expert-capabilities.md`、`docs/methodologies/project-masters.md` 与 `docs/methodologies/review-intelligence.md` 提供逐条工程依据(SOLID/DRY 适用性、弱类型禁令、隐式状态/触发链路三向遍历、专家理论工具箱、AI 评审智能与运行时/模型选择)。`docs/STAGE_PLAYBOOK.md` 承载自 DS §2.5/§2.16.6 迁移的操作性细则(条款权威仍在 DS,v3.61.0)。 - **自进化**:从本 Skill 派生(声明 `derived_from: dev-standards-bootstrap`)的 Skill 独立演进,安装/升级的每条写入路径都会跳过它们;`--force` 也不越过。`bash scripts/bootstrap.sh --derived-report` 可列出派生清单。 -- **跨文档一致性审计**:`bash tests/audit-docs-consistency.sh`(G1 版本链 / G2 编号连续 + 变更 UID 全局唯一 / G3 归档同源 / G4 缺陷双登记互证 / G5 RTVM 回填 / G6 必填节 / G7 批次自洽 / G8 缺陷六件套存在性 / G9 项目总册存在+自证+回填清单+功能目录表外 reviews/ 拦截 / G10 废弃条款 sweep——废止标记须带被替代版本指向(v3.41.0) / G11 UJ↔REQ 覆盖 / G12 五方证据 / G13 三维对照 / G14 源对照 / G15 来源物映射闭合 / A 组盖章互证)可在 CI 或本地运行;失败项即回填清单。 +- **跨文档一致性审计**:`bash tests/audit-docs-consistency.sh` 运行 **G1–G16** 不变量组 + A 组盖章互证(逐组定义以脚本头注释为唯一权威,人类索引 = `resources/AGENTS.md` 锚点表),可在 CI 或本地运行;失败项即回填清单。本 README 不再逐组展开。 ## 仓库结构 @@ -359,6 +364,7 @@ dev-standards-bootstrap/ │ ├── mutation-check.sh # 源层专用(不下发):检查器自证——四类固定变异必须让快检查器变红,且只发生在一次性副本里 │ ├── ci-summary.sh # 源层专用(不下发):渲染 CI 运行汇总,并把 tests/.suite-baseline 与收据 passed 数硬对齐 │ ├── batch-metrics.sh # 源层专用(不下发):每批次成本台账(轮次 / 编辑 / 轮询 / 整跑 / 墙钟)落到 .agent-state +│ ├── replay-plan.sh # 源层专用(不下发):只读回放历史变更 diff 过今天的 `-T auto` 解析器,对照 05 记录的实测节——报 FULL 回落率与假阴 │ ├── lib-source-facts.sh # 源层专用(不下发):上述六个工具共用的只读事实助手 │ ├── setup-branch-protection.sh # 源层专用(不下发):打印必需检查的 gh api 载荷(默认 dry-run);`--apply` 才改远端 │ ├── lib-suite-tree-fingerprint.sh # 共享库:套件树指纹,收据键控用(由 --guard 随 tests/run-tests.sh 安装) @@ -375,7 +381,7 @@ dev-standards-bootstrap/ └── resources/ ├── AGENTS.md # AI Agent 入口(复制到目标仓根) ├── CLAUSE_REGISTRY.md # 条款注册表:规范条款机器索引(Rxx 行号 ID + 文件名::锚点 + 类型封闭词表);DS 仍是正文唯一权威;供阅读包生成器消费(v3.46.0) - ├── DEVELOPMENT_STANDARDS.md # 完整规范文档 v3.88.0(复制到 docs/) + ├── DEVELOPMENT_STANDARDS.md # 完整规范文档 v3.92.2(复制到 docs/) ├── STANDARDS_CHANGELOG.md # 规范升级历史(§2.14 升级日志唯一落点,v3.8.0 起;复制到 docs/) ├── METHODOLOGY.md # 方法论选型指南:M0-M3 分级 + 阶段×方法论×适用/不适用表(复制到 docs/) ├── STAGE_PLAYBOOK.md # 阶段执行手册:DS §2.5/§2.16.6 叙事细则载体(条款权威仍在 DS,复制到 docs/) @@ -385,11 +391,12 @@ dev-standards-bootstrap/ │ ├── state-trigger-audit.md # 状态/触发链路审计:6 条教训 + 6 步清单 + 3 个反模式(v3.4.0) │ ├── expert-capabilities.md # 专家能力卡:9 核心 + 产品可用性专家 + 3 条件命中专家(理论工具箱/广度/经验/自适应;v3.67.0 加 UX/UAT 卡) │ └── project-masters.md # 项目级总册细节层:13 册清单/必含章节/回填注记语义(v3.35.0;v3.67.0 加 P12 产品上下文册) + │ └── review-intelligence.md # AI 评审契约:项目背景/专业能力/运行时探测/模型成本确认/独立性 └── templates/ ├── docs-readme.md # 一页文档地图(v3.37.0):五层职责+更新时机(→ /README.md) ├── communication.md # 沟通先行门产物(v3.52.0):Round-1 沟通稿+用户整体确认记录(→ docs/changes//00.5-communication.md) ├── project # 项目级总册(v3.67.0):SDLC 13 册 P00–P12 + 评审记录模板(→ docs/templates/project/) - ├── entry # 变更入口骨架(v3.67.0):begin 必检八件模板 + 条件件 03.6-ui-spec.md + 形状件 01.5/05/07/09(v3.70.0 CHG-045,→ docs/templates/entry/) + ├── entry # 变更入口骨架(v3.67.0):入口八件模板(begin 只校验入口三件;01–04 由阶段门校验)+ 条件件 03.6-ui-spec.md + 形状件 01.5/05/07/09(v3.70.0 CHG-045,→ docs/templates/entry/) ├── new-change.sh # 变更入口脚手架(v3.43.0):专用目录/当日批次自动判定(→ scripts/new-change) ├── CLAUDE.md # Claude Code 一行导入 ├── PULL_REQUEST_TEMPLATE.md # 带门禁自检的 GitHub PR 模板 @@ -403,6 +410,7 @@ dev-standards-bootstrap/ ├── bug-diagnosis.md、bug-impact.md、bug-test-plan.md、bug-matrix.md、bug-config.md、bug-tasks.md # 缺陷文档组六件套(→ docs/bugs/_templates/) ├── 06.5-deployment-config.md # 部署/配置/DB 记录模板(→ docs/;未命中须显式声明"未命中,不适用") ├── 06-delivery-summary.md # 交付总结 + FU 台账模板(→ docs/;§2.5 阶段 9.5 四个必含节) + ├── review-models.json # 评审模型清单示例(→ .agent-review-models.example.json;改名 .agent-review-models.json 后启用档位/确认) ├── audit-docs-consistency.sh # 跨文档一致性审计:版本链 / 编号连续 / 清单同步 / 缺陷双登记 / RTVM 回填 / 变更批次自洽(复制到 tests/) ├── governance-state.json # 每次变更 00-governance.json 的模板(不下发——由 Agent 按变更生成) ├── agent-governance.yml # 团队可复核的治理配置记录(复制到 .agent-governance.yml) @@ -456,8 +464,8 @@ dev-standards-bootstrap/ | Job | 职责 | |---|---| -| **Source-layer audit** | `tests/audit-standards-src.sh`——审计规范文本自身:版本链、关键词矩阵、清单唯一性、编号、防恒真 grep(断言:641) | -| **Golden-case self-tests** | `tests/run-tests.sh`——在一次性 git 仓库里回归门禁与安装器(1308 条 golden-case 断言);仅依赖 bash + git | +| **Source-layer audit** | `tests/audit-standards-src.sh`——审计规范文本自身:版本链、关键词矩阵、清单唯一性、编号、防恒真 grep(断言:659) | +| **Golden-case self-tests** | `tests/run-tests.sh`——在一次性 git 仓库里回归门禁与安装器(1594 条 golden-case 断言);仅依赖 bash + git | | **agent-governance** | 聚合必需检查上下文:上面两个 job 任一未成功即失败(供分支保护使用的稳定名称) | **CI 内不再软门、不再双跑**:golden-case 先以 `-j 4` 跑一遍(600s 墙钟预算 `AGENT_GUARD_CI_WALL_BUDGET_S`,超过即显式失败,不会拖到 job 上限才超时),并上传 `.agent-state/last-suite-receipt.json` 供人工取证;source-audit **不再消费该 artifact**——A3/A3c/A10 直接读**已提交的基线**做硬校验(不再设 `AGENT_GUARD_AUDIT_SOFT`),因此它对套件 job 没有任何依赖,可与之并行。**两个真实 job 受 `timeout-minutes: 15` 约束,聚合门 `agent-governance` 为 5 分钟。** 工作区套件锁(`lib-suite-lock.sh`,随 `--guard` 下发)同一时刻只允许一次全量运行并回收死锁主;收据/红档路径可用 `AGENT_GUARD_SUITE_RECEIPT_PATH` / `AGENT_GUARD_SUITE_RED_PATH` 覆盖,自测不会污染真实台账。workflow 级 `concurrency` 组会取消同 ref 被取代的 run。 @@ -496,7 +504,7 @@ bash scripts/setup-branch-protection.sh --repo / --apply # 真正
-**规范版本:** v3.88.0 | **最后更新:** 2026-10-21 | **维护者:** [geekma](https://x.com/geekma) | **邮箱:** geekma@gmail.com +**规范版本:** v3.92.2 | **最后更新:** 2026-10-27 | **维护者:** [geekma](https://x.com/geekma) | **邮箱:** geekma@gmail.com [报告缺陷](../../issues) | [功能建议](../../issues) | [阅读规范](resources/DEVELOPMENT_STANDARDS.md) | [更新日志](resources/STANDARDS_CHANGELOG.md) diff --git a/SKILL.md b/SKILL.md index 0feffd5..b0396d2 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,18 +1,18 @@ --- name: dev-standards-bootstrap -version: 3.88.0 -description: 在任意代码仓库中一键初始化"全局软件开发与变更规范"体系(AGENTS.md 唯一入口 + 五道门禁 + 风险分级 + Agent 独立性矩阵 + PR/CI 兜底)。当用户说"给这个项目接入开发规范"、"初始化 dev standards"、"这个仓库还没有 AGENTS.md,帮我加上"、或新建项目/新仓库首次配置时使用。当前携带规范版本 v3.88.0,低于此版本即需升级。 +version: 3.92.2 +description: 在任意代码仓库中一键初始化"全局软件开发与变更规范"体系(AGENTS.md 唯一入口 + 五道门禁 + 风险分级 + Agent 独立性矩阵 + PR/CI 兜底)。当用户说"给这个项目接入开发规范"、"初始化 dev standards"、"这个仓库还没有 AGENTS.md,帮我加上"、或新建项目/新仓库首次配置时使用。当前携带规范版本 v3.92.2,低于此版本即需升级。 --- # dev-standards-bootstrap -> **当前携带版本:v3.88.0**(与 `resources/DEVELOPMENT_STANDARDS.md` 页脚、`resources/STANDARDS_CHANGELOG.md` 顶部条目同源) +> **当前携带版本:v3.92.2**(与 `resources/DEVELOPMENT_STANDARDS.md` 页脚、`resources/STANDARDS_CHANGELOG.md` 顶部条目同源) > > **自查是不是最新版**:在本 Skill 目录执行 `git fetch --quiet && git log -1 --date=short --format='%h %ad %s'` 看本地副本是否落后;或比对仓库 README 的 `Standards Version` 徽章。低于上方版本号就该升级——对已接入的目标仓库说"更新 dev-standards-bootstrap"(步骤 4.5)。也可直接 `bash scripts/bootstrap.sh --check <目标仓库>` 看三处版本比对。 ## 这个 Skill 做什么 -把一套团队开发治理规范(文档先行、测试先行、五道门禁、四维追踪矩阵、Agent 角色独立性、分阶段专家评审(§2.2 九专家)、风险分级、防遗漏防跳过)**一次性**接入任意代码仓库。自 v3.67.0 起含**用户体验体系**:阶段 1 项目上下文包(10 域)+ UJ 用户任务、阶段 3 条件产物 `03.6-ui-spec.md`(`ui_change: true` 时必需)、阶段 4 用户旅程 E2E 阈值、阶段 8 产品可用性专家 UAT 阻塞门。 +把一套团队开发治理规范(文档先行、测试先行、五道门禁、四维追踪矩阵、Agent 角色独立性、分阶段专家评审(§2.2 九专家)、风险分级、防遗漏防跳过)**一次性**接入任意代码仓库。自 v3.67.0 起含**用户体验体系**:阶段 1 项目上下文包(10 域)+ UJ 用户任务、阶段 3 条件产物 `03.6-ui-spec.md`(`ui_change: true` 时必需)、阶段 4 用户旅程 E2E 阈值、阶段 8 产品可用性专家 UAT 阻塞门。自本版起含**评审智能**:评审必须装载项目背景与专业能力、先探测目标仓被打开的 Agent 客户端再选执行体、高成本模型必须由用户确认(`scripts/agent-gate review-plan`;契约=`resources/methodologies/review-intelligence.md`)。 `AGENTS.md` 是向 Agent 提供统一上下文的**上下文层**;可选的 `agent-gate` 在支持 Hook 的客户端写入前阻断,并由 Git / CI 对所有客户端兜底。装一次,以后每个新项目只需说一句"用 dev-standards-bootstrap 初始化这个仓库"。 @@ -37,10 +37,10 @@ description: 在任意代码仓库中一键初始化"全局软件开发与变更 - `--all` 是"用户说初始化"的**一条完成路径**(默认全量自动注入)。分层 flag(`--core` / `--claude` / `--ci` / `--guard` / `--pipeline`)**只在用户明确要求最小化安装或排障时**使用。 - **各层的精确文件清单以 `bash scripts/bootstrap.sh --help` 为唯一权威源**,本文件不复制——同一份清单维护两处必然腐烂。 - 安装器**幂等**、**失败即拒绝(fail-closed)**、目标已有不同内容时展示 diff 并要求 `--force` 才覆盖——这是"检测已有文件、绝不静默覆盖"红线的机器化兜底。`--all` 还会**自动接线**(`core.hooksPath` / 客户端适配器 / 验证命令探测),零手工。 - - 核心层含跨文档一致性机器审计 `/audit-docs-consistency.sh`(十四组不变量 G1–G14 + A 组盖章互证,逐组定义以脚本头部注释与 `resources/AGENTS.md` 锚点表为唯一权威;支持 `--only-fail` 只打 FAIL 行与空转声明,存量红仓复跑免全量重放);文档变更后或接入 CI 时运行,失败项即 §2.14 存量回填清单。核心层还含 `METHODOLOGY.md` 与 `methodologies/`(`development.md` / `data-structures.md` / `state-trigger-audit.md` / `expert-capabilities.md` / `project-masters.md`,v3.35.0 起含项目总册细节层)与项目总册骨架 `/templates/project/`(13 册+评审模板,v3.67.0)与阶段执行手册 `/STAGE_PLAYBOOK.md`(DS §2.5/§2.16.6 叙事细则载体,条款权威仍在 DS,v3.61.0)与一页文档地图 `/README.md`(五层职责+更新时机,v3.37.0)与条款注册表 `/CLAUSE_REGISTRY.md`(条款机器索引层,DS 仍是条款正文唯一叙事权威,v3.46.0)。 - - 强制包层含 Git Hook 归因闸门(`pre-commit` / `pre-push` / `commit-msg`)、`/agent-gate`(含 `check-confirm` 确认门探针与 `metrics` 只读度量)、`/behavior-extract.sh`(HTML/JS 原型行为抽取器,G13/G14 源对照数据源,v3.68.0)、**评测资产层(实验性,依赖本地缺陷台账,未接外部评测框架)`/eval-cases` + `/eval-rescore` 与 `.github/workflows/github-reviewer-rescore.yml`(事故/回归派生评测集 + 覆盖比重打分 + 治理面哈希漂移即重跑,v3.75.0)**、**会话内执法 `/session-gate.sh` + `/install-hook-adapter`(按当前客户端自适应接线,v3.34.0;`check` 模式轮次超 `AGENT_GUARD_SESSION_TURN_LIMIT` 即工具级硬拦,v3.58.0;opencode 适配改四段式真加载验证 + dual-active 双 runtime 形状,v3.64.0)**、`.agent-governance.yml`、`.github/workflows/agent-governance.yml`(required-check 名 `agent-governance`)、阅读包生成器 `/generate-reading-pack.sh`(按变更类型从条款注册表生成阅读切片,锚点 fail-closed,v3.46.0)与治理自测试 `/run-tests.sh`。 + - **核心层**:跨文档审计 `/audit-docs-consistency.sh`(**G1–G16** + A 组盖章互证;逐组定义以脚本头注释为唯一权威、`resources/AGENTS.md` 锚点表为人类索引;`--only-fail` 只打 FAIL 与空转声明)、`03.6-ui-spec.md` 为条件产物(`ui_change: true` 时必需,v3.67.0)、`METHODOLOGY.md` + `methodologies/`(6 册:`development` / `data-structures` / `state-trigger-audit` / `expert-capabilities` / `project-masters` / `review-intelligence`)、项目总册骨架 `/templates/project/`、阶段手册 `/STAGE_PLAYBOOK.md`、文档地图 `/README.md`、条款注册表 `/CLAUSE_REGISTRY.md`。 + - **强制包层**:Git Hook 三闸门(`pre-commit`/`pre-push`/`commit-msg`)、`/agent-gate`(含 `preflight` 预检与 `metrics` 度量)、`/session-gate.sh` + `/install-hook-adapter`(按客户端自适应接线)、`/behavior-extract.sh`、评测资产(`eval-cases`/`eval-rescore`,实验性)、阅读包生成器 `/generate-reading-pack.sh`(按变更类型从条款注册表生成阅读切片,v3.46.0)、`.agent-governance.yml`、`.github/workflows/agent-governance.yml`、治理自测 `/run-tests.sh`。**精确清单与版本标记以 `bash scripts/bootstrap.sh --help` 为唯一权威**,本节只给能力地图。 - **缺陷文档组**模板为**六件套**(`bug-diagnosis.md` / `bug-impact.md` / `bug-test-plan.md` / `bug-matrix.md` / `bug-config.md` / `bug-tasks.md`),落 `/bugs/_templates/`;编码记录模板 `coding-record.md` 在变更起编时落 `/changes/<变更号>/04.5-coding-record.md`。 - - **变更起编时**(非安装期)再从模板生成 per-change 产物:`00-intent.md` → `/changes/<变更号>/00-intent.md`、`governance-state.json` → `00-governance.json`(须由用户/编排者填真实风险等级与执行主体)。同一天的多个 L0/L1 变更可改落 `/changes/BATCH-YYYYMMDD/`(见「变更批次」节)。00-intent 必填目录落位声明(GATE-E86),非 L0 的 00.5 沟通稿须含五要素锚点(v3.60.0,权威见 DS §1.1/§2.17.2d)。入口八件之外,**`03.6-ui-spec.md` 为条件产物**——`01-spec` 声明 `ui_change: true` 时必需(v3.67.0);**形状件 4**(`01.5-rtvm-matrix.md` / `05-test-results.md` / `07-review-report.md` / `09-changelog.md`,v3.70.0 CHG-045)同落 `templates/entry/`——DS 对应节的模板形状唯一权威,作者按交付阶段复制,new-change 不默认脚手架。 + - **变更起编时**(非安装期)再从模板生成 per-change 产物:`00-intent.md` → `/changes/<变更号>/00-intent.md`、`governance-state.json` → `00-governance.json`(须由用户/编排者填真实风险等级与执行主体)。同一天的多个 L0/L1 变更可改落 `/changes/BATCH-YYYYMMDD/`(见「变更批次」节)。00-intent 必填目录落位声明(GATE-E86),非 L0 的 00.5 沟通稿须含五要素锚点(v3.60.0,权威见 DS §1.1/§2.17.2d)。入口八件之外,**`01.5-rtvm-matrix.md` 由 `new-change` 脚手架一并生成**(占位行不豁免填写:spec/design/tasks/testplan 各自交付时回填对应维度,阶段门机检),**`03.6-ui-spec.md` 为条件产物**——`01-spec` 声明 `ui_change: true` 时必需(v3.67.0);**形状件 05/07/09**(v3.70.0 CHG-045)同落 `templates/entry/`——DS 对应节的模板形状唯一权威,作者按交付阶段复制。 4. **仍需用户在托管平台完成的事**(安装器会打印指引,但改不了平台设置):把 `agent-governance` 与项目测试设为 Required Check、禁止直推受保护分支、为 L3 配置 CODEOWNERS / 人工审批。本地 Hook 可被绕过——**受保护分支的 CI 才是跨客户端的最终信任边界**。 4.5 **Skill 版本更新**(用户说"更新 / 升级 dev-standards-bootstrap",或检测到目标仓规范页脚版本低于本 Skill 携带版本): @@ -52,7 +52,7 @@ description: 在任意代码仓库中一键初始化"全局软件开发与变更 5. **初始化第一个功能目录骨架**(可选,询问用户是否现在就开始第一个变更):若用户已有具体功能,按规范 §1.1 在 `//` 下创建空的 `01-spec.md` 骨架(仅标题与章节占位,**不臆造需求内容**);变更管线入口 `00-intent.md`(§2.17)同样只创建骨架。 -6. **完成后回执**:列出本次实际写入 / 跳过的文件清单、启用的客户端适配器、以及仍需用户在托管平台配置的 Required Checks。**不得声称"所有工具均在改前强制受控"**——应说明 `AGENTS.md` 是上下文层,受保护分支的 CI 才是最终信任边界。若装了管线自动化,提示 `scripts/agent-gate metrics` 可输出管线度量(§2.17.5,仅作观察,不替代 DoD)。 +6. **完成后回执**:列出本次实际写入 / 跳过的文件清单、启用的客户端适配器、以及仍需用户在托管平台配置的 Required Checks。**不得声称"所有工具均在改前强制受控"**——应说明 `AGENTS.md` 是上下文层,受保护分支的 CI 才是最终信任边界。若装了管线自动化,提示 `scripts/agent-gate metrics` 可输出管线度量(§2.17.5,仅作观察,不替代 DoD);按需可用 `scripts/agent-gate baseline <变更号> [--write]`(P0-0 五数基线)与 `tc-index <变更号> [--write]`(P1-2 三源 TC 索引)。**自适应判定默认在 `begin` 自动产出**(`scripts/agent-gate plan <变更号> [--explain|--dry-run]`,结果写 `00-governance.json` 的 `decision` 并由 `stop/preflight` 消费);**判定默认不是判决**:AI 必须把判定卡(建议节 / 预计秒数 / 覆盖缺口 / 风险)展示给用户并给三选一(采纳 / 升档 / 降档),用户选定后以 `AGENT_GUARD_SCOPE_CONFIRM='<用户>@'` 重新 plan 落 `scope_confirmed`;AI 不得代替用户决定耗时动作。`status` 打印生效执法层与当前模型/窗口,换挡后用 `resume <变更号>` 从 handoff 续接。 ## 路径根可配置 @@ -76,17 +76,20 @@ derived_from_version: <派生时本 Skill 携带版本> ## 会话内执法 -执法点不只锚 commit:产物长期停在工作区时 pre-commit/CI 永不点火(本 Skill 源仓实证:CHG-071/BUG-040~055)。`scripts/session-gate.sh` 由客户端**会话事件**调用——`start`:跑 `tests/audit-docs-consistency.sh --only-fail` 亮存量红灯(落 `.agent-state/session-gate-last.md`);`idle`:跑 stop 等价检查(软执法,`AGENT_GUARD_SKIP_VERIFY=1` 跳全量回归;无活跃变更但有源码改动=红灯"修完不留痕")。接线由 `scripts/install-hook-adapter` 按客户端自适应生成,`--detect` 打印矩阵。**opencode 适配为四段式(v3.64.0,CHG-084)**:①探测 runtime 清单与版本(PATH CLI + Desktop 内置 CLI,`--version` 各自落盘)→ ②实时检索官方插件文档定契约(来源 URL 记入生成物契约头,不做版本→形状静态映射)→ ③生成形状候选 → ④**逐 runtime 沙箱真加载探测 + session-gate 功能标记仲裁,装毕对最终文件复验**——客户端自身 `failed to load plugin` 行 + 功能标记是唯一裁决,形状永不写死;无法确证契约即 fail-closed 拒装(ADAPTER-E11/E12),同机多 runtime 契约互斥时以主用 runtime 择形并显式告警(E13)。硬阻断仍由 Claude Stop hook 与 Git hooks/CI 承担。 +执法点不只锚 commit:产物长期停在工作区时 pre-commit/CI 永不点火(本 Skill 源仓实证:CHG-071/BUG-040~055)。`scripts/session-gate.sh` 由客户端**会话事件**调用——`start` 跑审计亮存量红灯(落 `.agent-state/session-gate-last.md`);`idle` 跑 stop 等价检查(软执法,`AGENT_GUARD_SKIP_VERIFY=1` 跳全量回归;无活跃变更但有源码改动=红灯"修完不留痕")。接线由 `scripts/install-hook-adapter` 按客户端自适应生成,`--detect` 打印矩阵。**适配器契约(探测→文档→候选→真加载验证、失败码 ADAPTER-E11/E12/E13、opencode dual-active 形状)的唯一权威是 `resources/templates/install-hook-adapter` 头注释**;硬阻断仍由 Claude Stop hook 与 Git hooks/CI 承担。 ## 变更批次(同日合并) **同一天**的多个 **L0/L1** 变更**默认共用** `/changes/BATCH-YYYYMMDD/`(v3.24.0 默认化): -- **只有目录被放宽,产物文件名一字不改**——仍是 15 件同名文件;同批变更用 `## <变更号>` 小节锚点分开。**L2/L3 不得入批**(削弱逐变更证据边界,门禁按记录逐条拒绝)。 -- **解析顺序**:独立 `/changes/<变更号>/`(永远优先)→ `AGENT_GUARD_CHANGE_DIR` → 含该锚点的 `BATCH-*/`。 -- **变更集合一律从权威名单读**(`00-governance.json` 的 `change_id`),**不从 `## <标题>` 反推**(v3.19.0 实测:反推会造幽灵变更、拒整批);**批次小节标题一律写 `## <变更号>`**。 -- **治理记录格式无关**(v3.20.0):`00-governance.json` 任意合法 JSON 写法等价(单行/多行/格式化皆可),读取器先压平再按顶层对象切分;记录须**扁平**(L3 三个 `release_authorized_*` 为扁平字符串字段)。 -- **闭环判定细一档**:共享 `09-changelog.md` 下"文件存在"≠"本变更已关闭",改判本变更自己的锚点小节是否存在;`metrics` 每变更一行;审计 G7 逐批次核对(记录 ⊆ 锚点、风险 ∈ {L0,L1}、跨批次唯一)。 +- **只有目录被放宽**,产物文件名一字不改;同批变更用 `## <变更号>` 小节锚点分开;**L2/L3 不得入批**(门禁按治理记录逐条拒绝)。 +- **解析顺序与变更集合口径**(独立目录优先 → `AGENT_GUARD_CHANGE_DIR` → 批次;集合从 `00-governance.json` 的 `change_id` 读,**不从标题反推**)**唯一权威 = DS §1.1**。 +- **闭环判定**("文件存在"≠"本变更已关闭",改为本变更自己的锚点小节;`metrics` 每变更一行;记录 ⊆ 锚点、风险 ∈ {L0,L1}、跨批次唯一)**唯一权威 = 审计 G7**。 +- **治理记录格式无关**(任意合法 JSON 写法等价;读取器先压平再按顶层对象切分;记录须扁平)**唯一权威 = DS §1.1 与 `governance-state.json` 模板**。 + +## 治理自测怎么跑 + +`/run-tests.sh` 支持按变更选节(`-T auto` / `-T <节>`)、并行(`-j N`)、列节(`-l`)。**跑法分层的唯一权威**:目标仓见 `/AGENTS.md` 纪律 7,源仓见 `MAINTAINER.md` §3。一句话:改文档/模板/单脚本用 `-T auto`,只有改被测核心(`agent-gate` / `run-tests.sh` / `.agent-governance.yml`)才全量且收口一次。 ## 红线 @@ -97,6 +100,6 @@ derived_from_version: <派生时本 Skill 携带版本> ## 版本同步 -- **当前携带版本 v3.88.0**(见规范页脚,页脚是唯一权威源)。 +- **当前携带版本 v3.92.2**(见规范页脚,页脚是唯一权威源)。 - **版本号三载体**:frontmatter `version:`、`description` 尾注、正文顶部横幅——升级规范时**页脚 + 三处一起改**,漏改即审计红;平台事实论证(frontmatter 无 `version` 字段等)以 `MAINTAINER.md` §6 为权威(源仓维护者文件,不随 Skill 下发,目标仓无此文件),本文件不复述。 - **改本 Skill 本身的人**(改脚本 / 改规范 / 改模板 / 动断言)请读 **`MAINTAINER.md`**(源仓维护者文件,不随 Skill 下发,目标仓无此文件):文件角色表、改哪里必须同时改哪里的联动表、两道自测试的用法与顺序、断言数生成器、审计的 PART A/B 分区、逐版本升级推送清单。**装规范的人不需要读它。** diff --git a/resources/AGENTS.md b/resources/AGENTS.md index 81c3272..fd89299 100644 --- a/resources/AGENTS.md +++ b/resources/AGENTS.md @@ -20,8 +20,11 @@ - 严禁未经 `00.5-communication.md` 用户整体确认生成批量变更文档正文或修改源码(§2.17.2d 沟通先行门;豁免仅限自动化入口显式越过+09 登记)。 - 严禁用"已按规范完成"这类总结句代替逐条清单勾选。 - 严禁未经 Thought(全局影响分析:当前状态/目标/波及的调用方、流程与业务,引用 02 三维影响分析)直接修改代码或文档——必须 Thought → Action → Observation 三段式推进,Observation 须附验证命令与关键输出并归档 09「执行记录(ReAct)」(§2.16.2 铁律)。 +- 严禁阶段产物缺「交付触发点 / 背景输入」两行即开动下一阶段:PMP 要求下阶段输入=上阶段产出,AI 必须先读业务/需求背景并写入产物;`agent-gate --stage spec|design|testplan` 缺即 GATE-E126(§2.16.2 阶段输入契约)。 - 严禁因为大部分完成就整体标记完成;任一清单项缺失即视为未完成,必须继续执行或明确报告阻塞原因。 - 高风险变更(命中 §0 门禁5 清单)必须获得人类 Release Owner 明确授权,AI 不得替代该授权。 +- 严禁 AI 自行选择高成本/`deep` 档模型做评审:只能列候选、能力与成本档位,由用户确认后执行(§2.1 规则 11,`agent-gate review-plan`);未确认即用=门禁违规。 +- 严禁同一执行主体/同一会话既生产又评审,或编排 Agent 代签评审结论;评审必须先探测**目标仓被打开的 Agent 客户端**运行时再选执行方案(在目标仓根执行 `install-hook-adapter --detect`,不是编辑 Skill 的源仓客户端),且必须装载项目背景与专业能力(`resources/methodologies/review-intelligence.md`)。 - 写入文件后必须用 shell 命令(`grep -c` / `wc -l` / `git diff --stat`)在磁盘层验证落盘;不得以编辑工具的“成功”返回作为完成依据,不得用 Read 工具验证落盘(其可能返回缓存内容)。 - 上下文被压缩或总结后,对话记忆不可信:磁盘产物(`docs/changes/`、git 状态、文件内容)是唯一权威状态,必须重新从磁盘读取活跃变更与本红线后再继续,不得依据记忆中的“已完成”声明推进。 - 长输出命令(构建、测试、日志检索、JSON 解析等)必须接管道过滤,关键输出进对话与产物、完整输出归档到文件并给落点;禁止把原始输出整段贴入上下文(细则见下方「Agent 执行资源纪律」第 1 条)。 @@ -34,10 +37,10 @@ 4. **勘探下放(v3.39.0 起默认强制,非建议)**:预计读 >2 文件或 >100 行日志/代码定位、或 >2 pattern 的检索,**必须**合并单次调用或委派只读子代理执行,只回结论与行号,原始输出不进主上下文;子代理超出派发输入清单的读盘动作须在结论中声明原因(§2.2 输入契约)。 5. **无匹配 ≠ 通过**:过滤后无输出不等于校验通过——以命令退出码与 FAIL 汇总行为准,FAIL 汇总行不得被过滤吞掉。 6. **并行批量**:写产物、相互独立的编辑必须单消息并行批量调用;仅内容依赖前序输出时才拆轮。 -7. **定向验证**:模块/单测级验证命令先行;全量回归仅由门禁(stop/staged/CI)统一触发,禁止随手裸跑全量。执法(v3.73.0,CHG-096/REQ-1102):`.agent-governance.yml` 声明 `full_test_patterns`(锚定全量形态 ERE)后,session-gate 对 LLM bash 命中调用计数,≥阈值(默认 2,`AGENT_GUARD_FULL_TEST_LIMIT`)亮黄灯;不声明不执法;门禁/CI 触发的全量不经 LLM bash turn 天然豁免。 +7. **定向验证**:模块/单测级验证命令先行;全量回归仅由门禁(stop/staged/CI)统一触发,禁止随手裸跑全量。执法(v3.73.0,CHG-096/REQ-1102):`.agent-governance.yml` 声明 `full_test_patterns`(锚定全量形态 ERE)后,session-gate 对 LLM bash 命中调用计数,≥阈值(默认 2,`AGENT_GUARD_FULL_TEST_LIMIT`)亮黄灯;不声明不执法;门禁/CI 触发的全量不经 LLM bash turn 天然豁免。**治理自测按变更选节(2026-10-25 接线补充,§2.17.4 执行细则)**:`tests/run-tests.sh` 具备 `-T auto`(按 `git diff` 自动选节,未映射文件回落全量)、`-T <节[,节]>`、`-j N`(节级并行,N≥2)、`-l`(列节)四种跑法;**改文档/模板/单个工具脚本一律 `-T auto` 或 `-T <节>`,禁止裸跑全量**——实证同一会话裸跑 11 次 ≈4.6 h,而 `-T auto` 同等覆盖面为秒级到分钟级。**全量范围 = AI 出议案 + 用户拍板(2026-10-27 二次裁定,取代"AI 单方面决定")**:改动**被测核心**(`resources/templates/agent-gate.sh`、`tests/run-tests.sh`、`.agent-governance.yml`)时,AI 先给判定卡(建议节 / 预计秒数 source / 覆盖缺口 / 风险),再向用户提供三选一——①采纳建议 ②升档全量 ③降档并说明理由;用户选定后才执行,并把 `AGENT_GUARD_SCOPE_CONFIRM='<用户>@'` 与 `AGENT_GUARD_SUITE_AI_SECTIONS/BASIS/REVIEWER` 一并传给 `plan`(写入 `decision.scope_confirmed`)。AI 不得替用户决定耗时动作;`judgment=ai` 无用户确认时 strict `E148` 拒。`T50` 恒跑,全量只在收口一次。**被 Kill 的处置**:先归因 `env_error`,最多一次自适应重试(分片或交 CI);再次被 Kill 即停止,带"已耗时 / 覆盖缺口 / 风险"重新请用户决策——禁止无限重试与盲等。**测试范围 AI 判断(v3.90.4,FU-126-1)**:`tests/run-tests.sh` 自改默认回落 FULL **不是写死结论**——AI 可基于 diff 证据**提议**收窄,但必须先向用户展示三选一并取得确认(`AGENT_GUARD_SCOPE_CONFIRM`),同时给出 `AGENT_GUARD_SUITE_AI_SECTIONS`(节列表)+ `AGENT_GUARD_SUITE_AI_BASIS`(≥20 字符证据)+ `AGENT_GUARD_SUITE_AI_REVIEWER`(`platform / model / task- 或 ses-`);缺证据、缺确认、评审签名不合规或未知节一律回落 FULL,`T50` 恒跑;判断来源与依据写入 `plan.decision` 的 `judgment/judgment_reviewer/judgment_basis/scope_confirmed`,门禁只验证据,不写死结论。**final-plan 收口(v3.90.5,CHG-126)**:`agent-gate baseline [--write]`(P0-0 五数基线)与 `tc-index [--write]`(P1-2 三源 TC 索引)按需调用;`stop`/`preflight` 消费 `decision`——硬项缺失 `E143`、strict 缺 decision `E142`、覆盖差集 `E144`(默认 WARN);`--stage close ` 管 `filled-at stage=N change= [at=]` 时序(E145/E146);`AGENT_GUARD_ADAPT=0` / `PLAN_STRICT=0` / `STAGE_CLOSE=0` 分别退出判定、严格消费、阶段时序门。收口前若不确定选节是否正确,用 `-T auto` 的 `AGENT_GUARD_SUITE_AUTO_RESOLVE_ONLY=1` 先看解析结果再执行。**本机全量已证实不可行(2026-10-27,CHG-127)**:本机全量被系统 `Killed: 9`(`-j2/-j4/-j6`、sandbox/非 sandbox、nohup 分离均复现);`.agent-state/full-suite-kill.` 标记存在时 `run-tests.sh` 对全量直接 `rc3` 拒绝,**只准 `--shard i/6` 分片(确定性划分全部 93 节)或交 CI,禁止第二次全量尝试**。**开工前 2 分钟既有红体检**:`tests/run-tests.sh -T T14,T26,T64,T67 -j 4`(高频失效钉),红先修再开工;收尾只跑改动相关节 + 分片,避免收尾时才暴露既有红并串行返工。**fresh clone / 无 CI 仓必须全绿(v3.92.2,CHG-127)**:断言不得依赖未跟踪件(`docs/` 私有面、`scripts/agent-gate`、`scripts/stamp-provenance.sh`、`.agent-state/`)——缺则按**具体夹具路径**显式 SKIP,禁止用 `-d docs` 一类代理判定(套件自身会创建 `docs/`,代理会翻转为"docs 在场"的假象);大输出断言用 herestring(`grep -Eq <<< "$out"`)而非 `printf | grep -q`——`pipefail` 下 grep 提前退出会让 printf 收到 SIGPIPE,把**命中**判成失败。**T82 墙钟 ≤1s** 只在串行档断言,`-j N` 档显式记"not asserted"(并行争用下的墙钟不是产品时延)。**交付质量门(v3.92.2,CHG-128)**:命中被测核心时,`staged/stop` 依次消费 `E153`(fresh-clone receipt:`tests/fresh-clone-check.sh`,tracked-only 快照的 audit+目标节绿)、`E150`(05 的 `red_repro:` / `green_after:` 两行,占位不算)、`E151`(`verification_owner` ≠ `implementation_owner`)、`E152`(`scope_overrun=over` 且无用户确认);显式自查用 `--stage core` / `--stage scope`。三个降级开关(`AGENT_GUARD_FRESH_CLONE=0`、`AGENT_GUARD_ALLOW_SELF_VERIFY=1`、`AGENT_GUARD_SCOPE_OVERRUN=0`)均须在 09「重要上下文」登记理由;无 CI / 非 GitHub 仓以 G-ENV 为每批验收面。**G-ENV 收据只在收口前生成一次(v3.92.2)**:中间验证只跑受影响单节(`-T <节>`);每次生成都会追加 `.agent-state/fresh-clone-history.tsv`,同一变更多次生成且 09 无 `- fresh-clone re-run: <理由>` 时脚本告警(`--ledger-check` 可查)——**重复付费必须可见**。**未验证 REQ 清单(v3.92.2)**:本变更 scope 内存在 RTVM 非 ✅ 的 REQ 时,09 必含该节并逐条列出(全部 ✅ 则无需);缺/漏列即 `E154`;显式自查 `--stage rtvm`——静默降级从此是签名声明。 8. **有状态 mock 隔离**:跨两次调用的有状态依赖(会话/游标/水位类)每用例隔离重建;"第二次调用被跳过"类失败优先查共享 mock 内部状态。 9. **禁并行集成测试(v3.71.0,CHG-046/REQ-1092)**:共享远程 DB 期间禁止并行代理同时跑集成测试(实证:连接池抖动→伪红/资源争抢);调度并行任务前核对目标库共享态,共享即串行或各自独立库;细则=STAGE_PLAYBOOK 阶段 7 节。 -10. **长任务等待纪律(v3.73.0,CHG-096/REQ-1100)**:禁止把"等待长命令完成"做成独立 LLM 轮(`sleep N` 后再探测类调用算一次 bash 预算且无进展——每轮询烧一个 LLM turn)。合法三式:①前台单次执行+充足 timeout;②单 shell 内 `while ! 判据; do sleep 30; done` 一次等到;③后台启动+完成通知续接。执法:session-gate 对首 token 为 `sleep` 的 bash 调用计数,`idle/status` ≥阈值(默认 2,`AGENT_GUARD_SLEEP_POLL_LIMIT`)亮黄灯,要求 09「重要上下文」登记;判定口径与降级路径唯一权威=session-gate.sh 头注释。 +10. **长任务等待纪律(v3.73.0,CHG-096/REQ-1100)**:禁止把"等待长命令完成"做成独立 LLM 轮(`sleep N` 后再探测类调用算一次 bash 预算且无进展——每轮询烧一个 LLM turn)。合法三式:①前台单次执行+充足 timeout;②单 shell 内 `while ! 判据; do sleep 30; done` 一次等到;③后台启动+完成通知续接。执法:session-gate 对首 token 为 `sleep` 的 bash 调用计数,`idle/status` ≥阈值(默认 2,`AGENT_GUARD_SLEEP_POLL_LIMIT`)亮黄灯,要求 09「重要上下文」登记;判定口径与降级路径唯一权威=session-gate.sh 头注释。**进度文件(v3.90.3,CHG-123/P0-2)**:套件逐节输出 `[done] Tnn Ns` 并写 `.agent-state/suite-progress.json`;等待改「读进度文件 + 短轮询」,**禁止** `TaskOutput block:true timeout>60s`(一次阻塞超 1 分钟即盲等)。 11. **环境归因续跑(v3.73.0,CHG-096/REQ-1101,B 层)**:子代理/长任务失败先归因再处置——环境类(网络/凭证/超时/基建)恢复后按已落盘产物续跑或增量重启,不从零重启;任务类(方案错/理解错)才推倒重来;归因结论与续跑起点登记 09。 12. **调用批处理(v3.77.0,CHG-101/REQ-1124)**:独立 shell 命令合并为单次调用(`&&` 链或并行工具调用);同文件多处改动合并为一次多段 edit,禁止小步高频读写同一文件——**每次工具调用重付整个上下文前缀,请求数 × 上下文水位才是 token 乘数**(单次 edit 在高水位会话约合十万级 token);未用到的 MCP/扩展能力不挂载(静态基线按需)。执法(v3.77.0,CHG-101/REQ-1127):session-gate 对 edit/write 族调用计数,`idle/status` ≥阈值(默认 40,`AGENT_GUARD_EDIT_LIMIT`)亮黄灯,要求 09「重要上下文」登记;判定口径与降级路径唯一权威=session-gate.sh 头注释。 13. **尾部增量读(v3.77.0,CHG-101/REQ-1125)**:追加类更新用 `cat >>` 或定点 Edit 落盘,禁止为追加而全量重读回灌上下文;read 大文件沿用纪律 3 小窗口径,换挡重建状态时只读 handoff 与增量区段(§2.9.6),禁止整文件重读。 @@ -49,10 +52,10 @@ 若仓库存在 `scripts/agent-gate`,在首次改动源码前必须: -1. 在 `docs/changes/<变更号>/` 创建并完成入口八件 `00-intent.md`、`00-governance.json`、`00.5-communication.md`、`01-spec.md`、`02-code-impact-analysis.md`、`03-modification-plan.md`、`03.5-tasks.md`、`04-test-scripts.md`(**骨架可由 `scripts/new-change <变更号> --risk Lx` 两段式生成(v3.52.0):确认记录在位后才补齐 01-spec 起五件,`--allow-unconfirmed` 供自动化入口显式越过;骨架不豁免填写,PENDING 执行主体被 begin 拒绝**)。各件必含节与机校语义——00-intent 为管线入口且 begin 硬校「预期结果/开放问题」(§2.17)、00.5 沟通先行门 GATE-E83 硬校确认记录非空 + L0 单行声明豁免、确认落盘前禁止生成后续产物正文与源码编辑(§2.17.2d)、02 先分析后方案三维 + 回滚(§2.5 阶段 2)、JSON 风险等级与四主体互异(L2/L3 强制互异;全等级最低线=作者≠评审)含 `spec_author`(§2.1 规则 10)、RTVM 回填门禁 4——**唯一权威见 DS 对应节,本入口不复制其细则**。**当天 L0/L1 变更/缺陷首个即建 `docs/changes/BATCH-YYYYMMDD/`(`## <变更号>` 锚点分节,后续同日变更/缺陷并入;L2/L3 独立目录;细则 §1.1)**;00-intent 必填**目录落位声明**(`- **目录落位**:BATCH-YYYYMMDD | 独立目录(<理由>)`,GATE-E86 硬校,v3.60.0),非 L0 的 00.5 沟通稿须含五要素锚点(§2.17.2d 第 4 条)。**命中 `ui_change: true` 的界面/体验变更**:`03.6-ui-spec.md`(条件件)与 E2E/UAT 条件门生效(GATE-E92–E98,v3.67.0)、07 增「业务合理性终审」节(GATE-E124)与来源物映射(GATE-E123/G15)(v3.84.0);**全部变更 begin 另必含 03「既有范式关系」节(GATE-E122,未命中声明放行,v3.84.0)**;未命中触发面时上下文包/UJ 一行「未命中(理由)」即合规,不强加(CHG-091)。 -2. 执行 `scripts/agent-gate begin <变更号>`(begin 前可先 `agent-gate preflight <变更号>` 一次预检全部产物缺锚,v3.72.0;v3.82.0 起并收 stop 侧交付形状面——E85/E114/E115/E117/E46 秒级格式反馈,写台账的 E116 不在探针面);未通过不得开始源码编辑。**begin 同时机校项目总册 13 册在位(§1.3)**:`docs/project/` 缺失或不全时,先复制 `/templates/project/` 骨架、回填现状并完成逐册初评,再 begin(豁免 `AGENT_GUARD_ALLOW_NO_PROJECT_MASTERS=1` 须在 09「重要上下文」登记理由)。begin 同时执法**会话红灯门(v3.41.0)**:`.agent-state/session-gate-last.md` 含 `GATE RED` 且新于最后交付 changelog 时拒绝(带病开工拦截;豁免 `AGENT_GUARD_ALLOW_OVER_RED=1` 并登记 09「重要上下文」)。 +1. 在 `docs/changes/<变更号>/` 创建入口件与后续产物(**九件模板**):`00-intent.md`、`00-governance.json`、`00.5-communication.md`、`01-spec.md`、`01.5-rtvm-matrix.md`、`02-code-impact-analysis.md`、`03-modification-plan.md`、`03.5-tasks.md`、`04-test-scripts.md`(**骨架可由 `scripts/new-change <变更号> --risk Lx` 两段式生成(v3.52.0):确认记录在位后才补齐 01-spec 起五件,`--allow-unconfirmed` 供自动化入口显式越过;骨架不豁免填写,PENDING 执行主体被 begin 拒绝**)。各件必含节与机校语义——00-intent 为管线入口且 begin 硬校「预期结果/开放问题」(§2.17)、00.5 沟通先行门 GATE-E83 硬校确认记录非空 + L0 单行声明豁免、确认落盘前禁止生成后续产物正文与源码编辑(§2.17.2d)、02 先分析后方案三维 + 回滚(§2.5 阶段 2)、JSON 风险等级与四主体互异(L2/L3 强制互异;全等级最低线=作者≠评审)含 `spec_author`(§2.1 规则 10)、RTVM 回填门禁 4——**唯一权威见 DS 对应节,本入口不复制其细则**。**当天 L0/L1 变更/缺陷首个即建 `docs/changes/BATCH-YYYYMMDD/`(`## <变更号>` 锚点分节,后续同日变更/缺陷并入;L2/L3 独立目录;细则 §1.1)**;00-intent 必填**目录落位声明**(`- **目录落位**:BATCH-YYYYMMDD | 独立目录(<理由>)`,GATE-E86 硬校,v3.60.0),非 L0 的 00.5 沟通稿须含五要素锚点(§2.17.2d 第 4 条)。**命中 `ui_change: true` 的界面/体验变更**:`03.6-ui-spec.md`(条件件)与 E2E/UAT 条件门生效(GATE-E92–E98,v3.67.0)、07 增「业务合理性终审」节(GATE-E124)与来源物映射(GATE-E123/G15)(v3.84.0);**全部变更 03 必含「既有范式关系」节(GATE-E122;设计门与交付全查,未命中声明放行,v3.84.0)**;未命中触发面时上下文包/UJ 一行「未命中(理由)」即合规,不强加(CHG-091)。 +2. 执行 `scripts/agent-gate begin <变更号>`(begin 前可先 `agent-gate preflight <变更号>` 一次预检全部产物缺锚,v3.72.0;v3.82.0 起并收 stop 侧交付形状面——E85/E114/E115/E117/E46 秒级格式反馈,写台账的 E116 不在探针面);未通过不得开始源码编辑。**v3.89.0 起 begin 为入口门 + 阶段门序列**:begin 只校验入口件(00-intent 预期结果/开放问题 + 00-governance.json + 00.5 确认记录),随后按序过**无状态阶段门**——阶段 3 开动前 `agent-gate --stage spec`、阶段 4 前 `--stage design`、阶段 5 前 `--stage testplan`(幂等可重入,不写阶段状态文件;九件齐的存量习惯全门自然绿);未过对应阶段门不得进入该阶段(staged/stop/ci 交付全查不变,收窄≠弱化;`AGENT_GUARD_STAGE_GATES=0` 平滑关闭,默认开)。**阶段门 = 交付完整性门(v3.91.5,用户硬指令)**:`--stage design` 前 `01-spec` 必须已有 REQ 编号且 `01.5` 已有 REQ 行(**需求未写不得开始设计**);`--stage testplan` 前 `02/03/03.5` 必须已交付且 `01.5` 已有 DES 与 TASK 行;`--stage close ` 校验本阶段维度(2=REQ、3=DES+TASK、4=TC)。缺任一即 `E126`,禁止"先做后补文档/RTVM 最后统一填"。**begin 同时机校项目总册 13 册在位(§1.3)**:`docs/project/` 缺失或不全时,先复制 `/templates/project/` 骨架、回填现状并完成逐册初评,再 begin(豁免 `AGENT_GUARD_ALLOW_NO_PROJECT_MASTERS=1` 须在 09「重要上下文」登记理由)。begin 同时执法**会话红灯门(v3.41.0)**:`.agent-state/session-gate-last.md` 含 `GATE RED` 且新于最后交付 changelog 时拒绝(带病开工拦截;豁免 `AGENT_GUARD_ALLOW_OVER_RED=1` 并登记 09「重要上下文」)。 3. 提交前执行 `scripts/agent-gate --stage staged`;交付前补全测试证据与 Changelog(含「执行记录(ReAct)」Observation 记录,§2.16.2)与**「项目总册回填清单」节**(P00–P12 逐册勾选/未命中,§1.3)。**交付前变更目录全部 `*.md` 产物盖章(pre-commit 自动,v3.41.0)**:hook 自动执行 `scripts/stamp-provenance.sh --all <活跃变更>`(幂等、真值读 git/主机/UTC、**禁手写**;§4 追踪矩阵由 `--all` 从 01.5 矩阵派生 fail-open;`bug_ref` 六件套由 hook 逐一 `--bug`;无 pre-commit 环境手动执行同命令;gate stop 逐一校验缺一不可交付;只校验当前活跃变更,**历史产物不得回填**,§1.1/§4)。**`bug_ref` 绑定的缺陷六件套同样盖章**:`scripts/stamp-provenance.sh --bug `(六件不齐 staged/stop/CI 与审计 G8 拦截;豁免须 `/bugs/.gate-allowlist` 登记理由;**v3.35.0 起六件套按天入批、v3.36.0 扁平化:`docs/bugs/BATCH-YYYYMMDD/` 同名文件 + `## BUG-xxx` 锚点分节**,嵌套子目录为历史合法形态,§1.1)。启用 Stop Hook / 会话内执法(v3.34.0)时自动检查上述产物与门禁 4 RTVM 回填(细则 §2.17.1)。 -4. 传动与事故重入(§2.17.1/§2.17.2):`01-spec.md` 合入会自动派发 02/03/03.5/04 骨架 PR,`09-changelog.md` 合入会自动开发布检查单 issue;生产事故经 incident 事件自动生成 `BUG-<时间戳>` 的 `00-intent.md` 骨架,接手者须走完整变更流程,禁止"修完不留痕"。**缺陷发现入口(§2.17.2b v3.43.0)**:主干回归红经 `bug-autointent` 自动建完整六件套骨架(频控窗口内同指纹只追加复现行);会话内 audit 红灯/gate 摩擦须**交互三选项**(建骨架/登记 FU/忽略须 09 理由),不得静默跳过。启用会话内执法时,会话开始自动注入规则 10 四主体自查表(§2.1 规则 10,冲突点名)。 +4. 传动与事故重入(§2.17.1/§2.17.2):`01-spec.md` 合入会自动派发 02/03/03.5/04 骨架 PR,`09-changelog.md` 合入会自动开发布检查单 issue;生产事故经 incident 事件自动生成 `BUG-<时间戳>` 的 `00-intent.md` 骨架,接手者须走完整变更流程,禁止"修完不留痕"。**缺陷发现入口(§2.17.2b v3.43.0;v3.89.0 起三类信号)**:①主干回归红经 `bug-autointent` 自动建完整六件套骨架(频控窗口内同指纹只追加复现行);②会话内 audit 红灯/gate 摩擦须**交互三选项**(建骨架/登记 FU/忽略须 09 理由),不得静默跳过;③**会话内无账源码改动**在编辑时刻被 session-gate `check` 硬拦(exit 2)、交付边界被 `agent-gate --stage staged/stop` fail-closed(`GATE-E125`)——豁免 `AGENT_GUARD_ALLOW_UNACCOUNTED=1` 须 09「重要上下文」登记理由(v3.89.0,CHG-117)。启用会话内执法时,会话开始自动注入规则 10 四主体自查表(§2.1 规则 10,冲突点名)。 5. `scripts/agent-gate metrics` 只读输出管线度量(§2.17.5),不得用度量数值替代 DoD 判定。 不得删除、禁用或修改 Hook、CI workflow、Required Check、`scripts/agent-gate` 以绕过本规范。无法通过门禁时,必须报告阻塞原因并等待授权;不得以“仅是小改动”为由绕过。 @@ -63,6 +66,7 @@ |---|---| | 判断这次改动风险等级、要不要跨平台交叉验证 | §0.5 | | 分阶段专家评审、九专家职责映射与上下文贴近契约(防泛泛而谈);评审/测试子代理派发必须附**输入契约**(变更文件清单+diff 摘要+待核对产物路径+行号锚点,§2.2 v3.39.0);专家能力卡见 `resources/methodologies/expert-capabilities.md` | §2.2 | +| 做各环节评审 / 派发评审子代理 / 选评审模型:项目背景装载、专业能力匹配、批判性质询、目标仓运行时探测、成本确认 | §2.1 规则 11 + §2.2 + `resources/methodologies/review-intelligence.md`(候选命令 `scripts/agent-gate review-plan <变更号>`) | | 确认本次变更作者/实现/测试/评审四主体互异(能否兼任) | §2.1 规则 10 | | 执行中遇到歧义怎么裁定(何时必须问用户、何时可自裁) | §2.1 规则 8「歧义分级裁定」 | | 只加载本次任务需要的规范层(宪法/流程/操作/历史) | §头部「分层阅读路由」 | @@ -78,7 +82,7 @@ | 怎么压会话/输出 token 成本 | 本文件「Agent 执行资源纪律」节 + §2.9.6 会话与上下文纪律 + §2.5 表达成本条款 | | 只是改 bug | §2.5 阶段 6(`docs/bugfix-log.md` 双登记 + 根因表「同族推演」行 + 「Bug 修复回填清单」;三条款——诊断前必读总册 / TC 覆盖强制新增防回归 / 六件套按天入批 `docs/bugs/BATCH-YYYYMMDD/` 扁平化——与 **P3 缺陷轻量通道**(文案类:`01-diagnosis.md` 行首 `severity: P3` 免 02/05/06 三件,未声明=全六件)细则唯一权威见 §2.5 阶段 6 与 §1.1)+ `resources/methodologies/state-trigger-audit.md`(同族推演与反模式细则)+ §0 门禁 | | 按变更类型取阅读包(阅读税路由,v3.46.0) | `bash scripts/generate-reading-pack.sh `(type∈`L0-bugfix|L1-standards|L2-architecture|L3-critical|universal`)——从 `CLAUSE_REGISTRY.md`(机器索引层)按需生成内容切片,锚点 fail-closed 防漂移;本表为路由入口、阅读包为切片、DS 为正文唯一权威(§2.17.2c) | -| 交付前文档互证(CI/本地均可跑) | `bash tests/audit-docs-consistency.sh`(G1 版本链 / G2 编号连续 / G3 归档清单↔§3 同源 / G4 bugfix 双登记互证 / G5 RTVM 回填一致 / G6 §4 必填节 / G7 变更批次自洽 / G8 六件套存在性 / **G9 项目总册存在+自证+回填清单+功能目录表外 reviews/ 拦截(§1.3 第 6 条,v3.37.1)** / **G10 废弃条款 sweep——废止标记须带 v3.x 被替代指向(减法机制,v3.41.0)** / **G11 UJ↔REQ 覆盖 + G12 五方证据——仅 `ui_change:true` 变更参与(v3.67.0)** / **G13 三维对照族 + G14 源对照族——`origin_artifact`/`chain_change` 声明触发,agent-gate begin/stop 执法(v3.68.0)** / **G15 来源物映射闭合——「外部来源物」声明触发(v3.84.0)** / A20 变更目录盖章互证 / A21 六件套盖章;失败项即 §2.14 回填清单,§2.13.4) | +| 交付前文档互证(CI/本地均可跑) | `bash tests/audit-docs-consistency.sh`(**G1–G16** + A 组盖章互证;逐组定义以脚本头注释为唯一权威、本文件锚点表为人类索引;`--only-fail` 只打 FAIL 与空转声明)。**组标签**:G1 版本链 / G2 编号连续+UID / G3 归档同源 / G4 缺陷双登记 / G5 RTVM / G6 必填节 / G7 批次自洽 / G8 六件套 / G9 总册+表外 reviews / G10 废弃条款 / G11–G12 UI 条件组 / G13–G14 三维+源对照 / G15 来源物 / G16 无账改动;A20/A21 盖章。失败项即 §2.14 回填清单,§2.13.4 | | 项目级总册(总体需求/架构/接口/数据/任务/测试/部署/风险/决策) | §1.3 + `resources/methodologies/project-masters.md`(十三册清单与必含章节唯一权威;首次变更初始化,每次变更逐册回填+变更注记) | | 涉及配置文件/数据库变更 | §2.6 | | 要发布上线 | §2.7、§2.8 | @@ -102,5 +106,5 @@ --- -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/CLAUSE_REGISTRY.md b/resources/CLAUSE_REGISTRY.md index d66b0a8..40a6a27 100644 --- a/resources/CLAUSE_REGISTRY.md +++ b/resources/CLAUSE_REGISTRY.md @@ -27,7 +27,7 @@ | R03 | 缺陷六件套必含清单 | DEVELOPMENT_STANDARDS.md::复现步骤、完整调用链 | L0-bugfix | 硬 | 结构 | | R04 | 根因表与同族推演 | DEVELOPMENT_STANDARDS.md::**根因·同族推演(v3.4.0)** | L0-bugfix | 硬 | 结构 | | R05 | Bug 修复记录七要素 | DEVELOPMENT_STANDARDS.md::Bug 修复记录七要素 | L0-bugfix | 硬 | 结构 | -| R06 | 缺陷发现入口(bug-autointent/交互三选项) | DEVELOPMENT_STANDARDS.md::#### 2.17.2b 缺陷发现入口扩展 | L0-bugfix | 硬 | 结构 | +| R06 | 缺陷发现入口(bug-autointent/交互三选项/无账源码改动信号③——编辑时刻硬拦+交付边界 fail-closed+阶段感知谓词,v3.89.0) | DEVELOPMENT_STANDARDS.md::#### 2.17.2b 缺陷发现入口扩展 | L0-bugfix | 硬 | 结构 | | R07 | 诊断前必读总册 | DEVELOPMENT_STANDARDS.md::诊断前必读总册 | L0-bugfix | 硬 | 行为 | | R08 | TC 覆盖强制(修复必被 TC 覆盖) | DEVELOPMENT_STANDARDS.md::TC 覆盖强制 | L0-bugfix | 硬 | 行为 | | R09 | Bug 修复回填清单 | DEVELOPMENT_STANDARDS.md::#### Bug 修复回填清单 | L0-bugfix | 硬 | 结构 | @@ -209,6 +209,36 @@ | GATE-E118 | 验证通道 `ci.verification_command` 有值但形态非法(空值/未闭合引号/非法块指示符/多行裸标量/不在 `ci:` 段内)——fail-closed,不静默跳过 | agent-gate.sh::yml_scalar()/validate_stop()(v3.76.0) | | GATE-E120 | scaffold 拒绝非空专用目录——existing 产物会被同 id 遮蔽,换新变更号重跑(fail-closed,幂等保护) | agent-gate.sh::scaffold_change()(v3.80.0,CHG-107,REQ-1152) | | GATE-E121 | scaffold 拒绝对已携带本变更成员锚的产物重入——id 已物化,防双节污染(fail-closed) | agent-gate.sh::scaffold_change()(v3.80.0,CHG-107,REQ-1152) | +| GATE-E125 | staged/stop 面存在源路径改动但无活跃变更、无同日缺陷批锚、无豁免 env(无账门 fail-closed) | agent-gate.sh::validate_unaccounted_changes()(v3.89.0,CHG-117) | +| GATE-E126 | 阶段门(spec/design/testplan)未满足对应产物锚——无状态、幂等、按阶段补产物后复跑 | agent-gate.sh::stage_gate_fail()(v3.89.0,CHG-117) | +| GATE-E132 | cost-line 子命令缺变更号或变更目录不存在(诊断入口参数错误) | agent-gate.sh::cost-line 分支(v3.90.1,CHG-123,P0-15) | +| GATE-E133 | 治理记录 JSON 括号/引号不配对 | agent-gate.sh::validate_governance_state()(v3.90.1,CHG-123,P0-7) | +| GATE-E134 | 治理记录 JSON 同行 `}{` 拼接(缺逗号) | agent-gate.sh::validate_governance_state()(v3.90.1,CHG-123,P0-7) | +| GATE-E135 | 治理记录 change_id 无法回读成完整对象(截断/重叠) | agent-gate.sh::validate_governance_state()(v3.90.1,CHG-123,P0-7) | +| GATE-E136 | `plan` 子命令用法错误(缺变更号 / 变更目录不存在 / 未知选项) | agent-gate.sh::plan 分支(v3.90.2,CHG-124,P1-1) | +| GATE-E137 | 评审计划要求 deep/高成本模型但无用户确认(AI 不得自行选择) | agent-gate.sh::review_consent_check()(v3.90.4) | +| GATE-E138 | `review-plan` 子命令用法错误(缺变更号 / 未知选项) | agent-gate.sh::review-plan 分支(v3.90.4) | +| GATE-E139 | `review-plan --approve` 缺模型 id | agent-gate.sh::review-plan 分支(v3.90.4) | +| GATE-E127 | 阶段关闭前置缺失(00.5 无确认 / 09 无子 Agent 放行) | agent-gate.sh::stage_close_check()(v3.90.3,CHG-125,P2-1) | +| GATE-E128 | 09 声称阶段复核但 `reviews/P*.review.md` 缺失或为空 | agent-gate.sh::reviews_pair_check()(v3.90.3,CHG-125,P2-2) | +| GATE-E129 | L2/L3 无用户整体确认却进入 staged 证据面 | agent-gate.sh::confirm_required_check()(v3.90.3,CHG-125,P2-3) | +| GATE-E130 | L2/L3 无用户整体确认即 preflight | agent-gate.sh::confirm_required_check()(v3.90.3,CHG-125,P2-3) | +| GATE-E131 | 09 缺自举两行(`[dogfood]` / `[dogfood-next]`) | agent-gate.sh::e131_dogfood_check()(v3.90.3,CHG-125,P2-4) | +| GATE-E140 | `baseline` 子命令用法错误(缺变更号 / 变更目录不存在 / 未知选项) | agent-gate.sh::baseline 分支(v3.90.5,CHG-126,P0-0) | +| GATE-E141 | `tc-index` 子命令用法错误(缺变更号 / 变更目录不存在 / 未知选项) | agent-gate.sh::tc-index 分支(v3.90.5,CHG-126,P1-2) | +| GATE-E142 | stop/preflight 缺引擎 decision 且 `PLAN_STRICT=1`(存量默认只 WARN) | agent-gate.sh::plan_consume_check()(v3.90.5,CHG-126,P2-2) | +| GATE-E143 | decision 的 artifacts/stages 硬项或 masters/reviews 软项缺失 | agent-gate.sh::plan_consume_check()(v3.90.5,CHG-126,P2-2) | +| GATE-E144 | `decision.chosen` 的测试节在 05 无证据且未声明 coverage gap(strict) | agent-gate.sh::coverage_gap_check()(v3.90.5,CHG-126,P2-3) | +| GATE-E145 | 总册 `filled-at stage=M` 晚于当前关闭阶段或晚于该阶段关闭时间(迟到回填) | agent-gate.sh::stage_close_check()(v3.90.5,CHG-126,P2-5) | +| GATE-E146 | 下一阶段首条 Observation 未引用上一阶段回填的总册锚点(漏读) | agent-gate.sh::stage_close_check()(v3.90.5,CHG-126,P2-5) | +| GATE-E147 | decision 的 `diff_hash` 与现算 diff 不一致且 `PLAN_STRICT=1`(stale 判定) | agent-gate.sh::plan_consume_check()(v3.91.0,CHG-127,G3) | +| GATE-E148 | `decision.must[]` 非空但 `chosen` 不是 FULL 且 `PLAN_STRICT=1`(硬规则未覆盖) | agent-gate.sh::plan_consume_check()(v3.91.0,CHG-127,G12) | +| GATE-E150 | 被测核心变更的 05 缺 `red_repro:`/`green_after:` 两行(或占位) | agent-gate.sh::core_gate_check()(v3.92.0,CHG-128,REQ-1279) | +| GATE-E151 | `verification_owner` 缺失或等于 `implementation_owner`(被测核心变更) | agent-gate.sh::core_gate_check()(v3.92.0,CHG-128,REQ-1280) | +| GATE-E152 | `scope_overrun=over` 且无用户确认的 scope(变更范围预算) | agent-gate.sh::scope_overrun_check()(v3.92.0,CHG-128,REQ-1281) | +| GATE-E154 | 09 缺「未验证 REQ 清单」或漏列 01.5 验证状态非 ✅ 的 REQ(静默降级) | agent-gate.sh::unverified_req_check()(v3.92.2,CHG-128,REQ-1284) | +| GATE-E153 | 被测核心变更缺 fresh-clone receipt 或 receipt 陈旧/红(环境等价) | agent-gate.sh::core_gate_check()(v3.92.0,CHG-128,REQ-1278) | +| GATE-E149 | `resume` 子命令用法错误(缺变更号) | agent-gate.sh::resume 分支(v3.91.0,CHG-127,G17) | | GATE-E75 | 会话审计红灯未清(红报告新于最后交付 changelog) | agent-gate.sh::命令分发(case "$command") | | GATE-E76 | hook 输入无法确定目标文件 | agent-gate.sh::命令分发(case "$command") | | GATE-E77 | --stage commit-msg 用法错误(缺 message 文件) | agent-gate.sh::命令分发(case "$command") | diff --git a/resources/DEVELOPMENT_STANDARDS.md b/resources/DEVELOPMENT_STANDARDS.md index e67c881..4274ee4 100644 --- a/resources/DEVELOPMENT_STANDARDS.md +++ b/resources/DEVELOPMENT_STANDARDS.md @@ -91,7 +91,7 @@ - **纯重构**(行为不变)→ 复用既有 TC 全量回归,可不新增;若重构暴露新边界,补用例。 - **删除**逻辑 → 删除对应 TC 须在 `09-changelog.md` 记录,禁止静默删。 - **断言完整性**:修改的调用点打点(如可观测记录)必须**断言其内容**(执行≠覆盖),禁止只"跑到"不断言。 - - **全量回归强制**:任何代码变更合入前必须跑全量测试套件(如 `mvn -pl -am test`),禁止只跑受影响用例(防副作用/回归盲区)。 + - **全量回归触发面**:全量回归由门禁(stop / staged / CI)统一触发(§2.9.6);本地内循环按影响面**定向验证**(定向集合 = `04` 的 TC→脚本映射 ∩ `git diff`;执行细则见 AGENTS.md 纪律 7),定向通过不替代门禁的全量。 ### 门禁 3:完工证据验证门禁(Evidence-Before-Assertions Gate) @@ -181,9 +181,9 @@ > > **编号规则唯一引用**:连续递增、不跳号、不重号、历史不重排(详见 §1.2,不再重复)。**机校**:G2 查连续性,G2b 查 `change_uid` 全局唯一与历史重号别名。 > -> **路径根可配置(v3.15.0)**:全文出现的 `docs/`、`scripts/`、`tests/`、`.githooks/` 均为**默认目录根**,可按仓库习惯在 `.agent-governance.yml` 的 `paths:` 段改写(安装参数 `--docs-dir` 等会同步写入该段,并改写模板**内部**的路径引用)。解析优先级:`AGENT_GUARD__DIR` 环境变量 > 配置文件 > 内置默认;**不配置即等于默认,行为与本版之前逐字节一致**。机器读取方:`scripts/agent-gate`、`scripts/check-standards-compliance.sh`、`tests/audit-docs-consistency.sh`、`scripts/bootstrap.sh`。 +> **路径根可配置(v3.15.0)**:全文出现的 `docs/`、`scripts/`、`tests/`、`.githooks/` 均为**默认目录根**,可按仓库习惯在 `.agent-governance.yml` 的 `paths:` 段改写(安装参数 `--docs-dir` 等会同步写入该段,并改写模板**内部**的路径引用)。解析优先级:`AGENT_GUARD__DIR` 环境变量 > 配置文件 > 内置默认;**不配置即等于默认,行为与本版之前逐字节一致**。机器读取方:`scripts/agent-gate`、`scripts/check-standards-compliance.sh`、`tests/audit-docs-consistency.sh`,以及安装器(源仓维护者工具,不随 payload 下发)。 > -> **不可配置项(v3.15.0)**:①`.github/`——平台只从 `.github/workflows/` 与 `.github/`/仓库根读 workflow 与 PR 模板,换名即流水线静默失效,做成旋钮是假的;②**契约名**——`AGENTS.md` 文件名、`scripts/agent-gate` 落点名、变更 15 件产物名(`00-intent.md`…`09-changelog.md`;条件件 `03.6-ui-spec.md`,`ui_change: true` 时必需)、缺陷六件套名、required-check 名 `agent-governance`。它们一旦随仓库而异,跨仓逐文件比对与"装一次、迁移到任意仓库"的能力即失效。**参数化目录根是便利,参数化契约名是解体。** +> **不可配置项(v3.15.0)**:①`.github/`——平台只从 `.github/workflows/` 与 `.github/`/仓库根读 workflow 与 PR 模板,换名即流水线静默失效,做成旋钮是假的;②**契约名**——`AGENTS.md` 文件名、`scripts/agent-gate` 落点名、变更 15 件契约产物名(+ 条件件 `handoff.md` = 16;另 `03.6-ui-spec.md` 在 `ui_change: true` 时必需)、缺陷六件套名、required-check 名 `agent-governance`。它们一旦随仓库而异,跨仓逐文件比对与"装一次、迁移到任意仓库"的能力即失效。**参数化目录根是便利,参数化契约名是解体。** > > **规范升级日志的归属(v3.16.0)**:`resources/STANDARDS_CHANGELOG.md` 是**规范自带文件的升级历史**,**归 Skill 所有**(`--core` 下发、`--upgrade` 整体更新),**目标仓库不在此追加本地条目**——你自己的历史写 `docs/changes/<变更号>/09-changelog.md`(§4)与 `docs/bugfix-log.md`,三者互不替代。已追加则 `--upgrade` **检测到即拒绝**(fail-closed,`--force` 可越过):既不静默覆盖、也不做追加式合并——合并会让"这行归谁维护"失去唯一答案。 > @@ -191,7 +191,7 @@ > > **文件溯源(v3.17.0)**:变更的 `04.5-coding-record.md` 必须携带 `scripts/stamp-provenance.sh <变更号>` 生成的 `` 块,**禁手写**——溯源块从**运行环境**读真值,手写块过不了形状校验。**门禁校验形状**(§2.16.2):块存在、四字段非空、ISO-8601 时间、`generated_by` 指向该脚本;`author` 属实性不可机验,缺口显式承认。**不追溯既往**:只校验当前活跃变更,历史产物不得回填(审计 A19 反向断言)。字段来源、隐私开关、幂等与降级细则见脚本头部注释。**全量盖章强制(v3.22.0 `--all`,v3.26.0 交付必跑)**:`--all <变更号>` 把同一溯源块盖到活跃变更全部 `*.md` 产物(幂等、批感知;00-governance.json 不盖——JSON 注入破坏机读),gate stop/CI 逐一校验,缺一件不可交付。 > -> **变更批次(v3.18.0 起)**:**当天 L0/L1 变更/缺陷首个即建** `<变更根>/BATCH-YYYYMMDD/`(UTC 日),后续同日变更/缺陷以 `## <变更号>` 锚段并入;**放宽的只有目录**——15 件同名产物仍齐、`00-governance.json` 一行一个变更;L2/L3 必须独立目录。**缺陷轨**:变更轨入口 `BUG-xxx`(L0/L1)与缺陷六件套自 v3.35.0 起同样按天入批;**v3.36.0 扁平化**为 `docs/bugs/BATCH-YYYYMMDD/` 内六件套各一文件、`## ` 锚点分节,嵌套子目录为历史合法形态。**P3 缺陷轻量通道**:`01-diagnosis.md` 行首 `severity: P3` 时 02/05/06 可缺省或单行声明,01/03/04 恒必查。**闭环语义**:共享 `09-changelog.md` 下"文件存在"≠"本变更已关闭",改判本变更自己的锚点小节(FU-015);**变更集合从权威名单读**(`00-governance.json` 的 `change_id`,不从标题反推);溯源块证明批次并列成员,风险取批次最高值。**目录落位声明(GATE-E86)**:00-intent 须含 `- **目录落位**:BATCH-YYYYMMDD | 独立目录(<理由>)`,**GATE-E86** 硬校声明与实际目录、风险级一致;批次成员缺自己的锚点小节时 begin 拒(FU-912:兄弟声明不可替过;独立目录整文件回落保留)。**批次日期一律取 UTC 日**(v3.61.1)。目录解析与实现细节(三形态解析、豁免 env、`__DATE__` 口径、溯源自动章)**唯一权威=`agent-gate` 头注释**。 +> **变更批次(v3.18.0 起)**:**当天 L0/L1 变更/缺陷首个即建** `<变更根>/BATCH-YYYYMMDD/`(UTC 日),后续同日变更/缺陷以 `## <变更号>` 锚段并入;**放宽的只有目录**——产物名集与 §1.1「两档不可占位集」判定逐条不变、`00-governance.json` 一行一个变更;L2/L3 必须独立目录。**缺陷轨**:变更轨入口 `BUG-xxx`(L0/L1)与缺陷六件套自 v3.35.0 起同样按天入批;**v3.36.0 扁平化**为 `docs/bugs/BATCH-YYYYMMDD/` 内六件套各一文件、`## ` 锚点分节,嵌套子目录为历史合法形态。**P3 缺陷轻量通道**:`01-diagnosis.md` 行首 `severity: P3` 时 02/05/06 可缺省或单行声明,01/03/04 恒必查。**闭环语义**:共享 `09-changelog.md` 下"文件存在"≠"本变更已关闭",改判本变更自己的锚点小节(FU-015);**变更集合从权威名单读**(`00-governance.json` 的 `change_id`,不从标题反推);溯源块证明批次并列成员,风险取批次最高值。**目录落位声明(GATE-E86)**:00-intent 须含 `- **目录落位**:BATCH-YYYYMMDD | 独立目录(<理由>)`,**GATE-E86** 硬校声明与实际目录、风险级一致;批次成员缺自己的锚点小节时 begin 拒(FU-912:兄弟声明不可替过;独立目录整文件回落保留)。**批次日期一律取 UTC 日**(v3.61.1)。目录解析与实现细节(三形态解析、豁免 env、`__DATE__` 口径、溯源自动章)**唯一权威=`agent-gate` 头注释**。 > > **项目级总册(v3.35.0;v3.67.0 起 13 册)**:`docs/project/` 下 13 册 + `reviews/` 逐册评审记录(册号 P00–P12 见上表)——SDLC 全环节的项目级聚合视图,**每次变更强制回填**、每册独立完整、被更新章节留变更注记、**首次变更 begin 强制初始化**。定义与执法条款唯一落点 **§1.3**;十三册清单与必含章节唯一权威 `resources/methodologies/project-masters.md`(本节不重复展开)。 @@ -281,6 +281,7 @@ 8. **分歧升级机制**:测试 Agent 或 Review Agent 对同一 CHG 连续 2 次退回仍未达成一致时,编排 Agent 必须停止重复分派,转为升级人类介入仲裁(不得由编排 Agent 自行裁决对错);仲裁过程与结论记入 07,并在 09「重要上下文」注明升级原因。**评审收敛(v3.74.0)**:轮次由 `.agent-state/review-rounds.tsv` 派生(= 校验点观测到的 07 不同内容哈希数;手填无效),超 `AGENT_GUARD_REVIEW_ROUND_LIMIT`(默认 3)亮黄灯且 07 须含「超限处置」行(未填写即拒 GATE-E116);首轮后只复审增量 diff、已报发现不重复入表。**歧义分级裁定(v3.45.0,bus factor 1 解法)**:①门禁语义/证据边界/高风险清单(§0 门禁 5)歧义=**必须升级用户裁定**,执行方不得自裁;②表达、落点、措辞、实施细节类歧义=执行方按**「最保守可逆」**原则自裁,并在 09「开放问题」登记**可否决点**(变更号 + 自裁内容一行),用户后续会话可否决、否决走勘误新开组;禁止①类自裁、禁止②类悬置等裁(事事问用户=bus factor 1 反模式)。**业务上下文装载(v3.84.0,CHG-111,N5)**:命中业务功能变更时,架构/开发/测试/评审批子代理输入契约必含业务上下文装载段(P12 相关域+上下文包增量+UJ 清单),产出必含一行「业务合理性自检」(业务动作/预期结果/依据;细则=`expert-capabilities.md` §0.2)。 9. **完成状态原子化**:未产出本节"必须交付/签署"物前不得标记环节"完成";编排 Agent 汇总时逐环节核对交付物存在性(不采信口头汇报),方式见 §2.16.6。 10. **角色单一职责(v3.34.0,一人一角色)**:同一 CHG 内**作者、实现、测试、评审**四主体 §2.1.7 标识互异(L2+ 四互异;`00-governance.json` 声明 `spec_author`——填 01-spec 作者(需求 Agent)标识,03 方案作者核对走签署表"方案评审"行;签署表核对);**最低线适用于全部等级**:评审独立且作者≠评审(L0/L1 的其余合并按 §0.5.2 矩阵留痕);生产批/评审批按 §2.2 两批制;编排 Agent 不得兼任任一签署;同标识无豁免=门禁 5 不通过,打回重派。 +11. **评审智能与执行体选择(v3.90.4)**:评审必须带项目背景、专业能力与批判性(契约唯一权威=`resources/methodologies/review-intelligence.md`);评审执行体**先探测目标仓被打开的 Agent 客户端运行时再选方案**(不是编辑 Skill 的源仓客户端),禁止默认子 Agent 或默认外部 CLI;**高成本模型必须由用户确认**——AI 只能列候选与成本档位,不得自行选择 `deep`/高成本档,未确认即用即门禁违规;同一模型/同一会话不得既生产又评审。执行入口:`scripts/agent-gate review-plan <变更号>`(在目标仓根只读列出候选;确认后写 `.agent-state/review-plan.json`)。 | 开发阶段 | 核心目标 | 强制加载 Skill 组合(≥2 个) | 交叉验证机制 | 门禁输出产物 | |---|---|---|---|---| @@ -297,8 +298,10 @@ ### 2.2 分阶段专家评审矩阵(Stage-Gated Expert Review Matrix) -> **上下文贴近契约(防泛泛而谈)**:专家就位前必须加载项目上下文(项目速览、功能目录与 RTVM 通读、行业合规与历史教训调研,§2.16.1),未完成调研不得签署;每条结论须引用 **≥1 条项目具体证据**(`路径:行号`/技术栈特征/行业约束/REQ/TC 编号),**纯模板泛评按 B 层退回(等同未评审)**。**评审/测试子代理输入契约**:上下文由**主 Agent 供给**而非子代理自采——派发 prompt 必须携带变更文件清单+diff 摘要、待核对产物路径清单、相关行号锚点;子代理超出清单的读盘动作须在结论中声明原因;`03.5-tasks.md`「评审输入」字段承载(begin 机校字段存在性)。评审记录落各阶段产物「专家评审记录」节,单行/条(主体+结论+标识+依据),并入 §2.5 ≤40 行预算;须由对应专家子 Agent 署名(§2.1.7),开发主体禁代签(A 层署名机校)。**成本护栏**:同阶段双专家可合并单子 Agent 双视角会话;L2 每变更专家评审会话 ≤3。**bugfix 适用**:阶段 6/§2.11 走缺陷六件套,复用测试/验收视角,角色合并按 §0.5.2 判定天然放宽(§0.5.2 为独立性唯一权威)。 +> **上下文贴近契约(防泛泛而谈)**:专家就位前必须加载项目上下文(项目速览、功能目录与 RTVM 通读、行业合规与历史教训调研,§2.16.1),未完成调研不得签署;每条结论须引用 **≥1 条项目具体证据**(`路径:行号`/技术栈特征/行业约束/REQ/TC 编号),**纯模板泛评按 B 层退回(等同未评审)**。**评审/测试子代理输入契约**:上下文由**主 Agent 供给**而非子代理自采——派发 prompt 必须携带变更文件清单+diff 摘要、待核对产物路径清单、相关行号锚点;子代理超出清单的读盘动作须在结论中声明原因;`03.5-tasks.md`「评审输入」字段承载(begin 机校字段存在性)。评审记录落各阶段产物「专家评审记录」节,单行/条(主体+结论+标识+依据),并入 §2.5 ≤40 行预算;须由对应专家子 Agent 署名(§2.1.7),开发主体禁代签(A 层署名机校)。**成本护栏**:同阶段双专家可合并单子 Agent 双视角会话;评审轮次上限与超限处置见 §2.1 规则 8(v3.74.0)。**bugfix 适用**:阶段 6/§2.11 走缺陷六件套,复用测试/验收视角,角色合并按 §0.5.2 判定天然放宽(§0.5.2 为独立性唯一权威)。 +> **评审智能契约(v3.90.4)**:评审必须装载项目背景(P12/P01–P04/bugfix-log/FU)与系统特点,按环节匹配专业能力,并给出有证据的批判性发现。**AI 判断不写死**:门禁只校验结构、证据、独立性与成本确认,禁止固定分数/关键词替代判断。**执行体先探测目标仓客户端运行时**再定方案;**高成本模型必须用户确认**。契约全文=`resources/methodologies/review-intelligence.md`。 +> > **专家两批制(生产-评审分离)**:每阶段专家分**生产批**(产出阶段产物)与**评审批**(B 层评审);评审批 ≥1 名**未参与生产**的专家 + Review Agent 签署,**专家不得评审自己参与生产的产物**。L0/L1 最低线=作者≠评审,其余合并按 §0.5.2 留痕。 > > **分阶段评审留痕(v3.53.0,REQ-993)**:阶段 1-5 各阶段的评审批结论**必须派发独立子代理**执行(契约见上段),并在 `07-review-report.md`「分阶段评审」节逐阶段留痕(三列:**阶段 / 独立评审主体 / 结论**),随批次交付;L0/L1 轻量通道可单行声明合并评:`- **分阶段评审**:未命中,不适用(<理由>,合并至阶段 8 终审)`(形状对齐 §1.1)。未留痕且未声明 = 阶段 8 评审退回项(B 层)。**缺陷轨确认机校点见 §2.17.2d 第 3 条**(绑定 CHG 的 begin)。 @@ -331,7 +334,7 @@ > - **B 层(角色判定)**:质量与正确性判断项,由对应独立角色(测试 Agent / Review Agent,§2.1/§0.5.2)逐条核对并勾选、留 Agent 标识(§2.1.7);**开发 Agent 不得自评 B 层通过**。 > - **勾选格式与落点**:每个阶段"声明完成"前,AI 必须按 §2.16.6 第 1 条**逐项引用该阶段验收标准条目号并勾选** `[x]`/`[ ]`(不要求抄录原文),随 §3 清单归档 `09-changelog.md`「变更执行检查清单」;只写"已验收 / 已按规范产出"而不逐项引用列出,视为未验收,该阶段判定为未完成(§5 拦截)。 > -> **表达成本条款(v3.24.0)**:跨产物引用制(根因/影响以 `02-code-impact-analysis.md` 为唯一权威,其余产物一行索引,禁止跨产物复制长文)+ 单产物软上限 ≤40 行(`05`/`09` 累积型豁免;超行须头部说明理由,无理由按 B 层未过,典型合法承载=02/04 实证件,不裁必含清单规格下限)+ 产物最小表达形态(v3.25.0:`00-intent.md` 3-5 行摘要——gate 硬校验节「预期结果/开放问题」必须保留;`03` 对比每案 ≤2 行——保 DES 编号与"选型/备选"关键字;`03.5` 免拆单行声明;形态裁剪不改变任何 gate A 层结构标记要求)——三款完整细则见 `resources/STAGE_PLAYBOOK.md` §2.5 总则。 +> **表达成本条款(v3.24.0)**:跨产物引用制(根因/影响以 `02-code-impact-analysis.md` 为唯一权威,其余产物一行索引,禁止跨产物复制长文)+ 单产物软上限 ≤40 行(`05`/`09` 累积型、`07`/`01.5` 结构型豁免;超行须头部说明理由,无理由按 B 层未过,典型合法承载=02/04 实证件,不裁必含清单规格下限)+ 产物最小表达形态(v3.25.0:`00-intent.md` 3-5 行摘要——gate 硬校验节「预期结果/开放问题」必须保留;`03` 对比每案 ≤2 行——保 DES 编号与"选型/备选"关键字;`03.5` 免拆单行声明;形态裁剪不改变任何 gate A 层结构标记要求)——三款完整细则见 `resources/STAGE_PLAYBOOK.md` §2.5 总则。 ### 阶段验收 A 层命令速查表(唯一命令权威,v3.8.0) @@ -726,7 +729,7 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 1. 读 `AGENTS.md`(本规范强制入口)。 2. 核对**标准当前版本**(页脚 vX.Y.Z)与**标准升级日志**(`STANDARDS_CHANGELOG.md`,§2.14)——最近升级是否影响本功能文档(须回填的条款)。 3. 读目标功能目录 `docs//` 全部文档 + `git status/log` 基线(确认批次编号、CHG 号、REQ/DES/TC 号现状,新编号继续递增)。 -4. **背景与业务上下文调研(v2.20.0)**:通读相关 01-spec/03-plan 的业务场景与历史决策(含 ADR)、近期关联 CHG(教训/未动项/FU)、业务域约束(行业/合规/SLA 如适用)。**未调研不得出方案**——只看改动文件的方案一律打回(§5)。 +4. **背景与业务上下文调研(v2.20.0)**:通读相关 01-spec/03-plan 的业务场景与历史决策(含 ADR)、近期关联 CHG(教训/未动项/FU)、业务域约束(行业/合规/SLA 如适用)。**未调研不得出方案**——只看改动文件的方案一律打回(§5)。调研结论必须写入当前产物的「背景输入」行(§2.16.2 阶段输入契约,机校缺失即 E126)。 5. **风险分级(§0.5)**:判定 L0-L3,确定 §0.5.2 独立性与平台要求,作为分派依据。 6. **执行能力自评(§2.16.6 第 5 条)**:预估预算是否足以完成全部适用阶段,不足提前声明分批。 7. **总册核对(v3.35.0,§1.3)**:确认 `docs/project/` 13 册在位(缺失则本次变更先初始化,begin 机校;豁免见 §1.3 第 5 条),并通读本次变更涉及册的相关章节(需求→P01、架构/流程/时序→P02、接口→P03、数据→P04、任务→P05、测试→P06/P07、部署→P08、风险→P09、决策→P11、产品上下文→P12)——**禁止只看代码不看总册**。 @@ -738,9 +741,9 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 前置(§2.16.1);**新变更先取新号建目录(§2.15 规则 4)**;先落 00-intent.md / 00-governance.json / 00.5-communication.md(§2.17,变更目录)→ **沟通先行门(§2.17.2d):00.5 用户整体确认记录落盘后方可生成后续产物正文与源码编辑** → begin 前可跑 agent-gate preflight <变更号>一次报全缺锚(v3.72.0,REQ-1095)→ gate begin(**begin 机校项目总册 13 册在位,§1.3**;Bug 另建缺陷组并声明 bug_ref,§2.5 阶段 6) → 阶段1(门禁1) 01-spec:REQ 追加式 + 来源/评审(专家评审 §2.2) → 阶段2 02:三维影响(先分析后方案)、时点快照、回滚必含;命中状态/触发链路含「隐式链路三向遍历」 - → 阶段3(门禁1) 03(DES+选型≥2候选)+03.5(T 任务或 CHG 豁免)(专家评审 §2.2) - → 阶段4(门禁2) 测试 Agent:04 覆盖维度矩阵 + SC 清单(≥80%) + 复用/新增判定 + 打点断言 - → 阶段5 开发 Agent:源码(CHG-xxx/WHY/契约/降级) + 04.5 编码记录 + 供应链(项目管理专家漏项检测 + 安全/性能专家,§2.2) + → 阶段3(门禁1) 03(DES+选型≥2候选)+03.5(T 任务或 CHG 豁免)(专家评审 §2.2)——开动前 `agent-gate --stage spec` 须绿(G-规格门,v3.89.0) + → 阶段4(门禁2) 测试 Agent:04 覆盖维度矩阵 + SC 清单(≥80%) + 复用/新增判定 + 打点断言——开动前 `agent-gate --stage design` 须绿(G-设计门,v3.89.0) + → 阶段5 开发 Agent:源码(CHG-xxx/WHY/契约/降级) + 04.5 编码记录 + 供应链(项目管理专家漏项检测 + 安全/性能专家,§2.2)——开动前 `agent-gate --stage testplan` 须绿(G-测试门,v3.89.0;源码编辑另受 §2.17.2b 信号③编辑时刻硬拦) → [命中] 配置/DB §2.6 · AI/LLM §2.9 · 隔离 §2.10 · 发布 §2.7 → 阶段6(Bug) 缺陷组六件套 + 根因表(「同族推演」行) + BUG 双登记 → 阶段7(门禁3) 05 新批次 §N(绑 CHG+四要素+覆盖率),历史不可覆盖 @@ -752,6 +755,8 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 每步更新按 §2.15 语义,违反即覆盖丢历史(§5);每步完成按 §2.16.6 逐项引用条目号并勾选该阶段 §2.5「验收标准」(不要求抄录原文)——A 层附命令与关键输出,B 层独立角色核对(只写"已验收"=未完成,§5)。 ``` +**阶段输入契约(PMP 交付触发点/背景输入,v3.91.6,CHG-127)**:每件阶段产物头部必须有两行:`> 交付触发点:<何时产出>;下游输入:<哪一阶段/产物消费>` 与 `> 背景输入:<已读的上游产物 + 业务/需求背景>`。`agent-gate --stage spec|design|testplan` 机检(占位符 `FILL/待填/<...>` 不算数):01-spec 背景须引 P01/P12/业务;02/03/03.5 背景须引 01-spec/REQ;04 背景须引 02/03/DES。缺即 GATE-E126 拒绝开工——**下阶段输入必须是上阶段已交付的产出物**,禁止"先做后补"。 + **ReAct 执行铁律(v2.21.0,全局分析强制)**:主线每一步、阶段 5 的每次源码/文档修改,必须 **Thought → Action → Observation** 三段式,禁止跳过 Thought 直接改("上来就改代码");三行细则与落点(09「执行记录(ReAct)」A 层归档、stop/CI 拦截)见 `resources/STAGE_PLAYBOOK.md` §2.16.2。 ### 2.16.3 变更完成判定(合入前全部为真,DoD) @@ -840,6 +845,8 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 > **本地 Git Hook 强制面(v3.5.0)**:`commit-msg` 归因闸门(`agent-gate --stage commit-msg `,模板 `resources/templates/commit-msg`)——暂存区代码提交的消息须引用有效变更号,豁免阶梯:合并提交、`Revert` 开头、纯文档/纯产物提交(无代码文件);branch 模式(`--stage ci --base `)对 diff 触及的变更追加 delivery 证据核验(05+09 与 Observation,§2.17.5);`pre-push` 模板接线 `--stage ci`(base=upstream,无则 HEAD)。**安装器自动接线(v3.11.0)**:`bootstrap --guard` 自动配置 `core.hooksPath`(不覆盖已有值)、自动生成客户端适配器、自动探测测试命令预填 `.agent-governance.yml`;gate 验证通道四态 absent/placeholder/tampered/unparsable(stop 车道;unparsable→`GATE-E118`);方言与在途维护见模板注释。 +> **无状态阶段门与无账源码改动门(v3.89.0,CHG-117,REQ-1199~1203)**:`agent-gate --stage spec|design|testplan` 为**无状态锚点校验**(G-规格=01 REQ 表+编号连续;G-设计=02 三维+回滚 + 03 选型/既有范式节 + 03.5 任务拆解在位;G-测试=04 用例矩阵+TC 落点清单)——从磁盘产物推断完成度,不写阶段状态文件,幂等可重入(八件齐的存量习惯全门自然绿)。`begin` 相应收窄为**入口门**(00-intent 预期结果/开放问题 + 00-governance.json + 00.5 确认,E83/E86 语义不变),01-04 校验由阶段门承接——**收窄≠弱化**:staged/stop/ci 交付全查不变,覆盖面不减;`AGENT_GUARD_STAGE_GATES=0` 整体关闭阶段门与 check 阶段谓词(存量平滑开关,默认开;显式 `--stage <门>` 调用不受开关影响)。session-gate `check` 模式同步**阶段感知**:源码编辑需 G-测试门在场**或** bug 凭证(当日缺陷组骨架锚点 + bugfix-log 登记行);02/03 编辑需 G-规格门;04 编辑需 G-设计门;00-intent/00-governance/00.5/01、缺陷组目录与模板骨架为流程动作不拦;取不到 hook 入参路径的客户端降级不拦(staged/audit 兜底)。**会话内无账源码改动**(§2.17.2b 信号③)双层执法:编辑时刻(check exit 2)+ 交付边界(staged 扫暂存面、stop 扫 `git status` 合并面,`GATE-E125`);`AGENT_GUARD_SKIP_VERIFY` 仅豁免全量回归**不豁免**无账检查(idle 经进程环境注入内部标记 `AGENT_GUARD_SKIP_VERIFY_CONTEXT=idle` 仅声明语义,外部手工设置同值无越权效果)。 + #### 2.17.1 传动机制(Artifact Pipeline) 0. **入口件脚手架(v3.38.0)**:`scripts/new-change <变更号> --risk Lx`(随 `--guard` 安装)从 `/templates/entry/` 生成 begin 必检八件骨架,自动判定专用目录/当日批次归并(语义同 gate);骨架只含章节标题与待填注释,治理 JSON 执行主体占位 `PENDING` 由 begin 占位符校验拒绝——**脚手架不消除任何门禁,只消除"入口件无模板"的空白**。 @@ -858,9 +865,9 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 4. **自主权上限**:本管线只创建文档骨架与 PR(A2 级,见 §2.17.3),不自动修复、不自动合入、不触碰生产环境。 5. **复盘义务(v3.75.0,CHG-099,REQ-1112)**:处置闭合前,缺陷组 `01-diagnosis.md` 必须写「应捕获层」行(枚举 `需求|设计|编码前置|测试|门禁|运行监控|无`,`无` 须给理由)并给出该层检查落点或本次补齐的检查——只修不汲取不算闭环(形状见 `bug-diagnosis.md` 模板,审计 A46)。 -#### 2.17.2b 缺陷发现入口扩展(Regression/Signal -> Bug,v3.43.0,REQ-958/959,FU-106④) +#### 2.17.2b 缺陷发现入口扩展(Regression/Signal -> Bug,v3.43.0,REQ-958/959,FU-106④;v3.89.0 增信号③,REQ-1199/1200) -1. **三类信号、双通道分流**:①**主干合入后测试回归红**(无人值守,无对话对象)→ `scripts/bug-autointent` 自动建**完整缺陷六件套**骨架(`docs/bugs/BATCH-/` 扁平 `## BUG-` 锚点,失败元数据预填,severity 不声明=六件全查 fail-closed)+ bugfix-log 双登记;workflow 参考实现 `github-regression-to-bug.yml`(workflow_run 监听测试 workflow,failure 且默认分支)。②**audit 红灯 / gate 摩擦**(会话内,有对话对象)→ Agent **交互三选项**动态处置:建骨架 / 登记 FU(P09)/ 忽略(须 09「重要上下文」理由);session-gate start 红灯时输出交互提示行(软执法 fail-open,v3.43.0)。 +1. **三类信号、双通道分流**:①**主干合入后测试回归红**(无人值守,无对话对象)→ `scripts/bug-autointent` 自动建**完整缺陷六件套**骨架(`docs/bugs/BATCH-/` 扁平 `## BUG-` 锚点,失败元数据预填,severity 不声明=六件全查 fail-closed)+ bugfix-log 双登记;workflow 参考实现 `github-regression-to-bug.yml`(workflow_run 监听测试 workflow,failure 且默认分支)。②**audit 红灯 / gate 摩擦**(会话内,有对话对象)→ Agent **交互三选项**动态处置:建骨架 / 登记 FU(P09)/ 忽略(须 09「重要上下文」理由);session-gate start 红灯时输出交互提示行(软执法 fail-open,v3.43.0)。③**会话内无账源码改动**(v3.89.0,CHG-117,REQ-1199/1200):编辑/暂存源码路径文件时无活跃变更、无当日缺陷组、非纯文档改动 → 与②同走**交互三选项**(建变更骨架 / 缺陷组绑定 / 豁免须 09 理由),且为**双层执法**:编辑时刻硬拦(session-gate `check` 模式 exit 2)+ 交付边界 fail-closed(agent-gate `--stage staged/stop`,`GATE-E125`);豁免 `AGENT_GUARD_ALLOW_UNACCOUNTED=1` 越权放行打印 WARN 并入 friction 台账,理由须 09 登记;审计 **G16** 披露面兜底(无 hook 仓不静默)。 2. **频控闸门(防重复建组)**:失败指纹 = 规范化失败项集合的 cksum;同指纹在 `AGENT_GUARD_AUTOBUG_WINDOW`(默认 86400 秒,env 可覆)内**不新建**,仅向原 01-diagnosis「复现记录(自动)」节追加复现行(追加式);指纹台账 `docs/bugs/.autofingerprint.tsv`(隐藏非 md,不入 G8 扫描面;指纹/窗口/台账机制细则见 `scripts/bug-autointent` 头注释)。 3. **自主权上限**:同 §2.17.2 第 4 条——只建骨架/追加复现行与 PR(A2 级),处置与修复永远走 §2.5 阶段 6 + 门禁。**复盘义务同 §2.17.2 第 5 条**(本通道建组的缺陷同样须写「应捕获层」)。 @@ -894,13 +901,16 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 1. 门禁脚本(`agent-gate.sh`)与 hooks/CI 模板属"治理配置",必须可回归:`tests/run-tests.sh` 在临时 Git 仓库构造合规/违规状态(begin 缺产物、L2 角色不独立、占位符与 L3 授权字段缺失、bug_ref 缺陷组缺失/为空/非法 id、pre-write fail-closed、staged/stop/ci 各门禁、commit-msg 归因与豁免阶梯、度量词边界匹配),断言退出码与输出。套件支持 `-T <节名[,节名]>` 单/多节定向回归(节体函数化 + `SECTIONS` 源序注册表定节序)与 `-l` 节清单(v3.65.0);收尾恒定输出 wall-time 行,`N passed, M failed` 行格式不变(计数提取链 sed 锚)。绿全跑收尾落地 `.agent-state/last-suite-receipt.json` 收据(head/树指纹/计数/UTC 戳;红删、过滤不触),二次收口按同 HEAD+同树指纹+新鲜窗采信免重跑,异 HEAD/树变/缺指纹/过期/缺失回落内嵌(v3.66.0/v3.79.0)。 -2. 修改 `agent-gate.sh`、hooks 或 CI 模板的变更必须先跑通全部用例再合入;用例与实现同仓同版本。 +2. 修改 `agent-gate.sh`、hooks 或 CI 模板的变更:**是否跑全量由 AI 判断**(须给 diff 证据,缺证据回落全量);用例与实现同仓同版本。 3. 测试套件零依赖(bash 3.2+ 与 git),macOS/Linux、任意 IDE 终端均可运行,作为 §2.13.4 自动化门禁对治理配置自身的适用。 -4. **评测资产与重打分(v3.75.0,CHG-099,REQ-1108~1110)**:事故与回归缺陷经 `scripts/eval-cases` 派生为**评测集**(运行时生成物,禁入库、禁手编),由 `scripts/eval-rescore` 打分(口径=已沉淀防回归用例的用例占比),收据绑定治理面内容哈希——漂移(治理面或用例集变更)即旧分作废、复核后经 `--update-baseline` 重建基线。**优先级序**:真缺陷召回优先于轮次下降,噪声与轮次是次优目标。 +4. **评测资产与重打分(v3.75.0,CHG-099,REQ-1108~1110)**:事故/缺陷经 `scripts/eval-cases` 派生为**评测集**(运行时生成物,禁入库、禁手编),由 `scripts/eval-rescore` 打分,收据绑定治理面内容哈希——漂移即旧分作废、复核后经 `--update-baseline` 重建基线。**优先级序**:真缺陷召回优先于轮次下降。 +5. **判定消费与回填时序**:stop/preflight 消费 `plan.decision`——嵌套 `artifacts/stages/project_masters` + `change.type` 路由(只收窄风险下限)+ `must` 非空且 AI 未判定收窄即 FULL;硬项缺失 `E143`、strict 缺 decision `E142`、`chosen` 与 05 差集 `E144`、stale `diff_hash` `E147`、`must` 未覆盖且无 AI 判定 `E148`;软项默认 WARN + 09 `[adapt]`/`decision-gap`;总册 `filled-at stage=N chg=` 须等于 §5.5 映射阶段(`revision` 豁免):未来阶段/`at` 晚于关闭 `E145`,下阶段首条 Observation 未引用回填锚点 `E146`。 + +6. **环境等价与交付质量门(v3.92.2,CHG-128,REQ-1278~1282)**:①**G-ENV**:命中被测核心(套件/审计/门禁/安装器/计数器的实现文件;清单唯一权威=`agent-gate` 的 `gate_core_paths`,可用 `AGENT_GUARD_CORE_PATHS` 覆盖)时,`staged/stop` 必须消费 `.agent-state/fresh-clone-receipt.json`(由 `tests/fresh-clone-check.sh` 在 tracked-only 快照上产生:`head==HEAD`、`audit_rc=0`、`suite_rc=0`),缺/陈旧/红即 `E153`;`AGENT_GUARD_FRESH_CLONE=0` 降级须在 09「重要上下文」登记理由。②**G-CORE**:05 须含 `red_repro:` 与 `green_after:` 两行(占位符不算),缺即 `E150`。③**G-IND**:`verification_owner` 须存在且 ≠ `implementation_owner`,缺/相同即 `E151`;`AGENT_GUARD_ALLOW_SELF_VERIFY=1` 须登记理由。④**G-SCOPE**:`plan.decision.scope_overrun` 记录批次数与核心文件数(事实,不由门替用户决定);`verdict=over` 且无 `scope_confirmed` 即 `E152`;阈值 `AGENT_GUARD_SCOPE_MAX_BATCHES/CORE_FILES`(默认 5/10),`AGENT_GUARD_SCOPE_OVERRUN=0` 降为 WARN。⑤**G-FEED**:`pre-push` 对非 main 的 GitHub 分支打印 draft PR 提示(不阻塞、不联网)。显式自查入口:`agent-gate --stage core`(E150/E151/E153)与 `--stage scope`(E152)。**时序(v3.92.2)**:receipt 的 `tree_sha` 与代码同源,**收口前生成一次**即可;中途改动只跑定向节;确需重生成须在 09 记 `- fresh-clone re-run: <理由>`(`tests/fresh-clone-check.sh --ledger-check` 校验;台账 `.agent-state/fresh-clone-history.tsv` 记录每次生成的时间/节/墙钟/rc)——重复付费只告警、不阻断。**verify 通道降级(v3.92.2)**:先探测 `caffeinate`,不可用或 `AGENT_GUARD_CAFFEINATE=0` 时直跑并告警(禁止让坏的 caffeinate 拖死验证)。⑥**未验证 REQ 清单(v3.92.2)**:本变更 01-spec 的 REQ 中、01.5 验证状态非 ✅(⬜/空/待验证)者存在时,09 必含该节并逐条列出(原因与去向);全部已验证则无需该节(01.5 的 ✅ 已是证据)。缺节或漏列即 `E154`(`AGENT_GUARD_RTVM_UNVERIFIED=0` 降级须登记 09)。显式自查:`--stage rtvm`。**无 CI / 非 GitHub 仓**:G-ENV 即为每批验收面,不依赖远端。 #### 2.17.5 管线度量(metrics) -1. `agent-gate metrics` 以 JSON Lines 输出每个变更的时序(`intent_ts`…`changelog_ts` 六点与 `intent_to_*` 五段间隔)、`delivery_ready`(05+07+09 三件齐备才为 true)、`expert_sessions`/`expert_sessions_over_guardrail`(署名节任务 ID 去重计数;L2/L3 >3 超标标记)、`artifact_files`/`artifact_bytes`(变更目录 `*.md` 件数与字节量,治理 JSON 不计;批次内各成员同值,**跨成员不得求和**)、`review_rounds`/`review_rounds_over_limit`/`findings_total`/`findings_dismissed`/`dismissal_rate`(v3.74.0,读自 `.agent-state/review-rounds.tsv` 与 07「发现处置」表)、`findings_introduced`/`findings_pre_existing`(v3.75.0,读 07「来源」列;缺列=null)。用于规范瘦身决策数据化(§2.17 引言);**字段全集与口径唯一权威=`agent-gate` 头注释**。 +1. `agent-gate metrics` 以 JSON Lines 输出每个变更的时序(`intent_ts`…`changelog_ts` 六点与 `intent_to_*` 五段间隔)、`delivery_ready`(05+07+09 三件齐备才为 true)、`expert_sessions`(署名节任务 ID 去重计数,只观测)、`artifact_files`/`artifact_bytes`(变更目录 `*.md` 件数与字节量,治理 JSON 不计;批次内各成员同值,**跨成员不得求和**)、`review_rounds`/`review_rounds_over_limit`/`findings_total`/`findings_dismissed`/`dismissal_rate`(v3.74.0,读自 `.agent-state/review-rounds.tsv` 与 07「发现处置」表)、`findings_introduced`/`findings_pre_existing`(v3.75.0,读 07「来源」列;缺列=null)。用于规范瘦身决策数据化(§2.17 引言);**字段全集与口径唯一权威=`agent-gate` 头注释**。 2. 度量为 A0 只读观察,纯 git 历史与磁盘推导、零第三方依赖;任一端点缺失输出 `null`,禁止推测补值。token 级成本(cache_read_per_turn / 工具调用数)为平台运行时数据,不进本契约;需要时由平台侧 adapter 另行导出(v3.38.0 裁定)。 3. 用途:识别管线瓶颈(如 `spec_to_plan_s` 过长 = 方案阶段积压)与交付就绪状态;**禁止用度量数值替代 DoD 判定(§2.16.3)**。 @@ -1006,6 +1016,9 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 #### 变更执行检查清单(§3 归档落点;唯一权威在 §3) [必填] 此处**逐字复制 §3 清单全部条目原文**并逐条勾选;禁止另维护副本(v3.8.0 起 §3 唯一权威);任务状态同步 `03.5-tasks.md`;合入前过 §2.16.3 DoD;DoD 与 §2.16.4 自检条目同样逐字复制,禁止摘要或"已通过"代替。 +#### 未验证 REQ 清单 +[必填] 本变更 01-spec 的 REQ 中、01.5 验证状态非 ✅(⬜/空/待验证)者逐条列出(原因与去向);全部已验证写「无」。缺/漏列即 `E154`(v3.92.2)。 + #### 未动项 [必填] 有意未改内容与技术理由(防重复分析/误改);遗留去向 FU-xxx;形状见模板。 @@ -1031,7 +1044,7 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 | **只更新 changelog 追踪矩阵、不回填独立 RTVM 矩阵文件** | 🟡 中度违规 | 触发【门禁 4】拦截,要求回填 `docs//01.5-rtvm-matrix.md`(§1.2),含验证状态、编号顺序核对与四维链路。 | | **RTVM 四维链路断环(REQ→DES→TASK→TC 任一环缺失)** | 🔴 严重违规 | 需求必须有设计、设计必须落任务、任务必须产出测试;断环即回填补齐,禁止跳环。 | | **改动调用点打点未断言(执行≠覆盖)** | 🟡 中度违规 | 违反门禁 2 断言完整性,要求补充断言(如可观测记录事件/里程碑/终止原因)。 | -| **只跑受影响用例、跳过全量回归** | 🟡 中度违规 | 违反门禁 2 全量回归强制,要求跑 `mvn -pl -am test` 全套件再合入。 | +| **跳过门禁触发的全量回归(stop/staged/CI)而宣称交付** | 🟡 中度违规 | 违反门禁 2 全量回归触发面(定向验证合法,但不得替代门禁全量),要求补跑门禁全量再合入。 | | **测试报告覆盖/改写历史批次结果** | 🔴 严重违规 | 违反门禁 3 批次保留:`05-test-results.md` 历史批次原文/状态不得覆盖,须追加独立小节(§N);修订须加「修订说明」。 | | **标准升级未回填存量文档** | 🟡 中度违规 | 违反 §2.14:标准新条款必须回填所有既有功能文档,未回填视为未落地。 | | **CHG 未回写方案正文 / 未拆任务(无豁免标注)** | 🟡 中度违规 | 违反阶段 3/9:CHG 必须回写 `03-modification-plan.md` 正文并拆 T 任务(或显式豁免标注),禁止只登记。 | @@ -1082,4 +1095,4 @@ RTVM(§1.2)在此场景**扩展第五维度**。以下映射表与 RTVM 并 --- -*规范版本:v3.88.0 | 更新时间:2026-10-21 | 全局维护责任人:geekma (geekma@gmail.com)* +*规范版本:v3.92.2 | 更新时间:2026-10-27 | 全局维护责任人:geekma (geekma@gmail.com)* diff --git a/resources/METHODOLOGY.md b/resources/METHODOLOGY.md index 01a6ee4..1a802d0 100644 --- a/resources/METHODOLOGY.md +++ b/resources/METHODOLOGY.md @@ -123,4 +123,4 @@ --- -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/STAGE_PLAYBOOK.md b/resources/STAGE_PLAYBOOK.md index ea86476..18e6483 100644 --- a/resources/STAGE_PLAYBOOK.md +++ b/resources/STAGE_PLAYBOOK.md @@ -7,7 +7,7 @@ > 条欈权威(一句话口径)在 DS「表达成本条款(v3.24.0)」,本节承载三款的完整细则: - **跨产物引用制**:根因 / 影响以 `02-code-impact-analysis.md` 为唯一权威,`00-intent.md` / `09-changelog.md` 一行索引引用("见 02 §业务影响"),禁止跨产物复制长文(同 §4 短引用制)。 -- **单产物软上限**:变更目录单产物默认 ≤40 行(`05-test-results.md` / `09-changelog.md` 累积型豁免);超行须头部一行说明理由,无理由按 B 层未过。只裁表达冗余,**不裁必含清单规格下限**。超行的典型合法承载 = 02 / 04(实证内容)。 +- **单产物软上限**:变更目录单产物默认 ≤40 行(`05-test-results.md` / `09-changelog.md` 累积型、`07-review-report.md` / `01.5-rtvm-matrix.md` 结构型豁免);超行须头部一行说明理由,无理由按 B 层未过。只裁表达冗余,**不裁必含清单规格下限**。超行的典型合法承载 = 02 / 04(实证内容)。 - **产物最小表达形态(v3.25.0)**:`00-intent.md` 3-5 行摘要 + "详见 02"(gate 硬校验节「预期结果 / 开放问题」必须保留);`03` 候选对比每案 ≤2 行(保 DES 编号 + "选型/备选"关键字,gate A 层兼容);`03.5` 免拆时单行声明 + 里程碑两行。形态裁剪不改变任何 gate A 层结构标记要求(验收框勾选形态细则见 `entry/00-intent.md` 模板,v3.70.0 CHG-045 微粒移出)。 ## 2.5 阶段 1·项目上下文包与 UJ 细则(v3.67.0) @@ -33,6 +33,8 @@ > 必含清单条目名与验收标准(唯一权威)在 DS 阶段 3;条 2/3/4 形状细则自 v3.70.0(CHG-045)移入 `entry/03-modification-plan.md` 模板注释块(形状唯一权威),条 9 UI 十节形状移入 `entry/03.6-ui-spec.md` 模板——本节只留机校依据与硬规则指针: +- **阶段门执法点(v3.89.0,CHG-117,REQ-1202)**:本阶段开动前 `agent-gate --stage spec` 须绿(G-规格门:01 REQ 表在位 + REQ 编号无跳号);幂等无状态,可重入。 + 5. **技术选型与决策记录(多方案强制对比,v2.20.0)细则**:对比矩阵维度=复杂度/性能/可维护性/熟悉度/成熟度与前沿性/风险与回退成本,结论论证「为何最适配当前业务」(规模、团队、演进路径);前沿技术标注试验风险与回退路径;背景入 ADR。**M0–M3 分级与适用对照以 `resources/METHODOLOGY.md` 为唯一权威**——越级选型按其 §4 判过度设计。 8. **总册联动(v3.35.0,§1.3)细则**:按 `resources/methodologies/project-masters.md` §2「回填触发面」逐册判定并回填(方案类通常触及 P02/P03/P04/P05/P11),未触及册在 09 回填清单标"未命中(理由)";实文回填处留变更注记。 9. **UI/交互设计(v3.67.0,条件件 `03.6-ui-spec.md`)细则**:十节产出序、四态/主数据选择器/禁用态提示细则唯一权威=`entry/03.6-ui-spec.md` 模板注释块(v3.70.0 CHG-045 移出);本节留机校依据与硬规则:E90(REQ 挂靠 UJ)/E92(03.6 缺失)/E94(缺显示名↔主键映射)/E97(裸主键入口)——领域实体选择必须走列表/搜索/上下文带出,禁止 DB 主键(`*Id`/`tenantId` 等)作为用户主入口输入;`03.5-tasks.md` 任务表含`类型`列,UI 变更必须拆出 `UX`/`UI` 任务行(设计实现/E2E/埋点),否则任务拆解未完成。 @@ -40,6 +42,7 @@ ## 2.5 阶段 4·覆盖维度与场景枚举细则 +- **阶段门执法点(v3.89.0,CHG-117,REQ-1202)**:本阶段开动前 `agent-gate --stage design` 须绿(G-设计门:02 三维影响+回滚、03 选型比较+既有范式关系节 与 03.5 任务拆解在位——先分析后方案的机器化执法点)。 - **变更动态约束(v3.10.0)**:从本变更 spec 与**前序产物**合成的不变量——类型参考 SCHEMA/协议/关系型/溯源型/时序型/能力型(arXiv:2602.02475 附录 F);每条含检查方式与**显式失败路径**;step-by-step 合成优于 one-shot(arXiv:2602.02475 §4.4 实证)。 - **覆盖维度矩阵(v2.20.0;v3.2.0 扩为十一类)枚举细则**:功能正常流 / **业务场景**(端到端旅程,按 01-spec 用户故事)/ **逻辑分支** / 边界值与空值 / **异常与降级兜底**(依赖故障注入,覆盖 LLM 与非 LLM)/ **数据组合与状态** / **并发与竞态**(引入共享可变状态或并发原语时**必须**,方法见 `resources/methodologies/development.md` §3.6;未引入方可标"不适用")/ **安全**(越权/注入/敏感数据,如适用)/ **兼容性**(接口前后兼容、多端)/ **性能与容量**(命中 01-spec 非功能指标时**必须**;未命中显式标注)/ **回归**(受影响既有功能)。L0/L1 可裁剪但**逐维显式标注"不适用,理由"**,禁止静默裁剪(§2.16.6 第 3 条);**风险联动(v3.2.0)**:L3 安全维度强制(命中 PII/认证授权/对外接口不得标"不适用")、命中性能指标时性能维度强制;复用 vs 新增按门禁 2 判定(打点必须断言内容,合入前跑全量回归)。 - **业务场景全景枚举与覆盖率(v3.3.0,业务专家视角)细则**:从用户故事按**五维**枚举——①角色/权限 ②状态与迁移 ③端到端链路(含跨模块)④时序与并发 ⑤异常业务路径——**隐含场景必须入清单**。落 04「业务场景清单」节(SC-xxx + 描述 + 关联 REQ + 覆盖 TC,追加式,每条 SC 至少映射一个 TC);**覆盖率 = 已覆盖/枚举 ≥80%**(L3 ≥90%,未覆盖登记 FU-xxx)并逐条标注理由,禁止静默裁剪(§2.16.6 第 3 条);`begin` 校验 SC- 编号;L0 纯文档变更可单条 SC 标"无业务场景影响"——禁止留空。 @@ -52,6 +55,7 @@ ## 2.5 阶段 5·注释与编码细则 +- **阶段门执法点(v3.89.0,CHG-117,REQ-1202/1203)**:本阶段开动前 `agent-gate --stage testplan` 须绿(G-测试门:04 用例矩阵 + TC 落点清单在位);源码编辑另受 §2.17.2b 信号③编辑时刻硬拦(session-gate check)与 bug 凭证通道约束——先文档后代码的机器化执法点。 - **中文注释规格(强制)**:① 类/接口:`@author` + 职责一句话;② 方法:公共 API/复杂逻辑/契约变化说明职责、`@param`/`@return`/`@throws` 与业务约束(简单私有方法不强制 Javadoc),改动处最小范围标 `CHG-xxx`;③ 关键逻辑 **WHY 注释**:解释"为什么"(业务原因/边界取舍/防坑),非 WHAT;④ 契约字段:DTO/VO 新字段注释含义与可空性;⑤ 降级/兜底路径:异常分支注明触发条件与降级行为。 - **ReAct 微循环(v2.21.0,每次源码修改强制)**:每次改动前后按三段式走(铁律句在 DS §2.16.2;细则唯一承载=本册 §2.16.2);**禁止"上来就改代码"**(§5 严重违规)。 - **删改符号全引用面(v3.84.0,CHG-111)**:删除/更名函数、字段、常量前 grep 全部引用面(模板绑定/watch/import/字符串动态引用/配置键)——build 只查语法,不查运行时悬空绑定。 @@ -63,7 +67,7 @@ - **根因分类(互斥单选,v3.10.0)**:需求缺陷 / 设计缺陷 / 实现缺陷 / 集成环境故障 / 数据缺陷 / 流程缺陷(检查缺口/文档漂移);判定用各类**消歧问题**(含否定判别)并**引用证据行**(无证据时分类塌缩到泛化类,arXiv:2602.02475 Table 5);无法归类须给自定义类名(禁空);可扩展。 - **最早未恢复失败点(v3.10.0 三步扫描)**:定位首失败 → 查是否已被既有防线恢复 → 未恢复即根因点;**晚期显著症状可能只是下游表现**,分类须在最早未恢复点做(arXiv:2602.02475 §2.1/§4.7)。 - **BUG 与 CHG 不双建(v3.26.0)**:缺陷处置默认**只**落 `docs/bugs//` 六件套 + `bugfix-log.md` 双登记,**禁止为同一缺陷同时新建 CHG/变更目录**(两套承载同一事实 = 漂移温床)。仅当满足升级条件之一才开变更轨:①修复引入需求/功能行为变化(需 REQ/RTVM 链);②跨系统契约/结构变更;③L2/L3 修复需独立签署。升级时变更目录号用 `BUG-xxx`(L0/L1 可入 BATCH,§1.1),`00-governance.json` 的 `bug_ref` 指向六件套;**诊断/根因正文以六件套为唯一权威,变更目录只引用不复制**。 -- **六件套执法闭环(v3.34.0)**:`bug_ref` 支持扁平字符串**或字符串数组**(声明但不可解析即 die,fail-closed——数组曾被 `json_field` 静默跳过校验);gate staged/stop/CI 逐组扫描 `/BUG-*/` 六件齐(豁免 = `/.gate-allowlist` 登记理由);审计 **G8** 接管六件套存在性、**A21** 校验其盖章;六件套交付前跑 `scripts/stamp-provenance.sh --bug `。**门禁校验一次报全(v3.84.0,CHG-111)**:E56/E57 累计全部不完整组单次 die——逐个迭代暴露=多轮返工(外部实证:14 缺陷逐组迭代 6 轮)。**红测试归因顺序**:单点测试红且表现异常时,先归因测试脚本自身(选择器/夹具/环境/目标行取错)再归因产品代码——反直觉归因浪费返工轮次。 +- **六件套执法闭环(v3.34.0)**:`bug_ref` 支持扁平字符串**或字符串数组**(声明但不可解析即 die,fail-closed——数组曾被 `json_field` 静默跳过校验);gate staged/stop/CI 逐组扫描 `/BUG-*/` 六件齐(豁免 = `/.gate-allowlist` 登记理由);审计 **G8** 接管六件套存在性、**A21** 校验其盖章;六件套交付前跑 `scripts/stamp-provenance.sh --bug `。**门禁校验一次报全(v3.84.0,CHG-111)**:E56/E57 累计全部不完整组单次 die——逐个迭代暴露=多轮返工(外部实证:14 缺陷逐组迭代 6 轮)。**红测试归因顺序**:单点测试红且表现异常时,先归因测试脚本自身(选择器/夹具/环境/目标行取错)再归因产品代码——反直觉归因浪费返工轮次。**无账源码改动闭环(v3.89.0,CHG-117)**:§2.17.2b 信号③的执法主体=编辑时刻 session-gate `check` 硬拦 + 交付边界 `agent-gate --stage staged/stop`(`GATE-E125`)fail-closed,审计 **G16** 为披露层(工作树无账源码面 FAIL 点名,干净树显式 VACUOUS SKIP 防假绿);修 bug 先诊断后修复——当日缺陷组骨架锚点 + bugfix-log 登记行即 bug 凭证,check 凭其放行修复编辑,齐备性仍归 G8/staged。 - **邻接面走查(v3.84.0,CHG-111,REQ-1166/N3)**:同族推演的横向扫描扩展到**邻接面**——同容器/同流程内相邻交互面与相邻处理分支(修 A 控件必走查同屏其余交互面;修分区 A 必遍历全部同族分区);UI 类修复的根因表「同族推演」行须含邻接面清单与逐面结论(bug-diagnosis 模板同步)。**用户反馈轮次超 2 强制全量遍历一次**(B 层:多轮返工=系统性迭代欠账,反应式修复成本指数律)。 ## 2.5 阶段 7·运行时证据细则(v3.68.0,CHG-043) diff --git a/resources/STANDARDS_CHANGELOG.md b/resources/STANDARDS_CHANGELOG.md index c58864c..ab9025e 100644 --- a/resources/STANDARDS_CHANGELOG.md +++ b/resources/STANDARDS_CHANGELOG.md @@ -9,6 +9,26 @@ | 版本 | 日期 | 变更条款 | 影响既有文档(须回填) | |---|---|---|---| +| v3.92.2 | 2026-10-27 | **未验证 REQ 清单:静默范围缩减必须签名(CHG-128 第三批,用户漏洞复盘)**:①09 新增「未验证 REQ 清单」——本变更 01-spec 的 REQ 中、01.5 验证状态非 ✅(⬜/空/待验证)者存在时必含该节并逐条列出(原因与去向);全部已验证则无需该节;②`stop/staged` 新增 **`E154`**(单 die 站点)+ 显式自查 `--stage rtvm`;③`AGENT_GUARD_RTVM_UNVERIFIED=0` 降级须在 09 登记理由;④模板承载 + A58h + T84 四条断言;⑤断言 1590→1594、审计 658→659。**动机**:外部项目实证「REQ 缩水 → RTVM 留 ⬜ → 09 勾『无静默省略』→ stop 放行」;本门把说谎成本从"没人看"变成"签名清单"。评级 L2;9 项不变量与 15 件产物结构不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/09 模板/DS/AGENTS/README×2/本行;存量进行中变更在下一次 stop 需补该节(无未验证 REQ 写「无」)。 | +| v3.92.1 | 2026-10-27 | **G-ENV 收据时序:杜绝重复付费(CHG-128 第二批)**:①纪律:receipt 只在**收口前生成一次**,中间验证只跑受影响单节(`-T <节>`);②`tests/fresh-clone-check.sh` 每次生成追加 `.agent-state/fresh-clone-history.tsv`(时间/变更/head/tree/节/墙钟/rc),同一变更多次生成且 09 无 `- fresh-clone re-run: <理由>` 时告警(`--ledger-check` 只读校验);③A58g + T84 三条断言(台账告警/指向理由/登记后干净);④断言 1587→1590、审计 657→658。⑤verify 通道先探测 `caffeinate`:不可用或 `AGENT_GUARD_CAFFEINATE=0` 时直跑并告警(macOS 27 beta 的 caffeinate SIGABRT 会拖死整个会话)。评级 L1(文档 + 测试工具),结构不变量不变。 | 目标仓 `--upgrade` 带走 `tests/fresh-clone-check.sh`/DS/AGENTS/本行;台账为本地 `.agent-state` 件,不入库。 | +| v3.92.0 | 2026-10-27 | **五道交付质量门(用户裁定「五条全做」,CHG-128)**:①**G-ENV**:命中被测核心时,`staged/stop` 必须消费 `tests/fresh-clone-check.sh` 在 `git archive HEAD` tracked-only 快照上产生的 `.agent-state/fresh-clone-receipt.json`(`head==HEAD`、`audit_rc=0`、`suite_rc=0`),缺/陈旧/红即 **`E153`**;`AGENT_GUARD_FRESH_CLONE=0` 降级须登记 09。②**G-CORE**:05 须含 `red_repro:` / `green_after:` 两行(占位不算),缺即 **`E150`**。③**G-IND**:`verification_owner` 须存在且 ≠ `implementation_owner`,缺/相同即 **`E151`**;`AGENT_GUARD_ALLOW_SELF_VERIFY=1` 须登记 09。④**G-SCOPE**:`plan.decision` 增 `scope_overrun`(批次数/核心文件数/阈值/verdict,事实呈现),`verdict=over` 且无 `scope_confirmed` 即 **`E152`**;阈值 `AGENT_GUARD_SCOPE_MAX_BATCHES/CORE_FILES`(默认 5/10),`AGENT_GUARD_SCOPE_OVERRUN=0` 降 WARN。⑤**G-FEED**:`pre-push` 对非 main 的 GitHub 分支打印 draft PR 提示(不阻塞、不联网)。新增显式自查入口 `--stage core|scope`;T84(28 断言)+ 源审计 A58(6 断言);断言数 1559→1587、审计 651→657。评级 L2;9 项质量不变量与 15 件产物结构不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/`pre-push`/`run-tests`/`tests/fresh-clone-check.sh`/DS/AGENTS/README×2/本行;被测核心变更首次需要 fresh-clone receipt;无 GitHub / 无 CI 的仓以 G-ENV 为每批验收面(不依赖远端)。 | +| v3.91.9 | 2026-10-27 | **CI 权威面转绿:fresh clone / 无 CI 仓也能全绿(用户裁定,本变更内修)**:①**根因**:PR #1 CI `golden-case` **1539/13**、`source-audit` **647/4**,全部为 `docs/` 不入库(CHG-017)与平台差异,非本轮断言引入——T30 直调未跟踪的 `scripts/agent-gate`;T82/T83 依赖 `docs/changes/CHG-960/CHG-124` 私有夹具;T65 用 BSD-first `stat -f %m`(GNU 语义不同 → Linux 不告警);T26c/T82/T83 大输出走 `printf \| grep -Eq`,命中即 EPIPE,被 `pipefail` 判成失败;源审计 A6a/b/c 因 **bootstrap 把 `/templates` 建到调用方 cwd** 而误判 docs 在场(本应 SKIP);A10b 因环境变体断言名报假漂移。②**修复**:`check_output` 改 herestring(根除 EPIPE 假红);T30 改用 `GATE_SRC`;T83 以 `seed_artifacts` 自造 CHG-124 夹具;`agent-gate` liveness mtime 改用 `gate_mtime`(GNU-first);bootstrap 删除两处 cwd 相对 `mkdir`(`install_file` 已建父目录);审计在脚本启动时快照 `A6_DOCS_ABSENT`;A10b 与 `update-assertion-count --check` 对 4 条环境变体名归一化;完成态断言名文件按 **repo root** 分键(同机多仓不再互相污染);套件启动 `mkdir -p .agent-state`。③**验证**:tracked-only 检出(`git archive HEAD`,等价 CI/无 CI 仓)下源审计 **651/0**、15 节并行 **375/0**、T82 串行 **56/0**;断言数不变(1559)。④T82 墙钟 ≤1s 仅在串行档断言(并行档显式记"not asserted",断言数不变)。评级 L2;结构不变量不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/`bootstrap`/`run-tests`/`update-assertion-count`/审计/AGENTS/DS/README×2/本行;未接 GitHub / 无 CI 的仓同样受益(fresh clone 即可全绿);无需重装 hook adapter。 | +| v3.91.8 | 2026-10-27 | **handoff 不再可被 push 绕过(用户质询)**:①**根因**:E112 换挡门只在 `--stage stop`;pre-commit 按设计只做软提醒(T55 TC-1257 钉"不阻塞"),而源仓 `.githooks/` 根本没有 pre-push——于是"已交付无 handoff"仍可 push。②**`--stage shift`**:把 E112 从 `validate_dimensional_stop` 抽成 `shift_gate_check` 单一 die 站点,stop 与新的 `--stage shift` 共用;无套件、无交付形状,耗时 <1s。③**pre-push 接线**:`resources/templates/pre-push` 在 `--stage ci` 前调用 `--stage shift`;源仓同步安装 `.githooks/pre-push`(此前缺失)。④**行为**:已交付变更无 `handoff.md` 且无 09「换挡声明」且 `AGENT_GUARD_ALLOW_NO_SHIFT!=1` → push 被 `E112` 拒绝;未交付/其它变更 fail-open。⑤**测试**:T55 两条既有断言改为复合(`--stage shift` 红→绿;pre-commit 提醒 + pre-push 带 shift 门),断言数不变(1559);源审计 651。评级 L2;结构不变量不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/pre-push 模板/本行;已装仓需重跑 `install-hook-adapter` 或手动安装 pre-push 才生效;紧急继续会话仍可用 `AGENT_GUARD_ALLOW_NO_SHIFT=1`(09 登记理由)。 | +| v3.91.7 | 2026-10-27 | **耗时治理:禁止重复全量尝试(用户质询后实测复盘)**:①**根因**:本机全量自 v3.91.2 起即被系统 `Killed: 9`(~10 min),上轮仍重试 4 次(`-j2/-j4/-j6`、sandbox/非 sandbox、nohup 分离)≈36 min 纯等待;另有既有红(T14/T26/T64/T67)在收尾才暴露,串行返工 ≈30 min。②**`--shard i/N`**:按 `SECTIONS` 确定性连续划分(93 节);N=6 时保持 `SERIAL_CHAIN`(T5,T22a,T16 / T50,T51)相邻;`AGENT_GUARD_SUITE_SHARD_RESOLVE_ONLY=1` 只解析不执行。③**本机 kill 标记**:`.agent-state/full-suite-kill.` 存在时全量直接 `rc3` 并指向 `--shard`/CI(`AGENT_GUARD_FULL_SUITE_FORCE=1` 才可越过);标记本地 gitignored,不随 Skill 下发。④**AGENTS 纪律 7**:禁止第二次全量尝试;开工前 2 分钟既有红体检 `-T T14,T26,T64,T67 -j 4`;收尾只跑改动相关节 + 分片。⑤**测试**:T68 两条既有断言改为复合(分片不抢锁且保留串行链邻接;标记主机全量 rc3 并点名 `--shard`),断言数不变(1559);源审计 651 不变。评级 L2;结构不变量不变。 | 目标仓 `--upgrade` 带走 `run-tests`/`AGENTS.md`/本行;`--shard` 为纯增量旗标(无参行为不变);kill 标记只在本地 `.agent-state`,目标仓不受影响。 | +| v3.91.6 | 2026-10-27 | **阶段输入契约:交付触发点 + 背景输入(用户硬指令)**:①每件产物头部两行——`> 交付触发点:<何时产出>;下游输入:<谁消费>` 与 `> 背景输入:<已读上游产物 + 业务/需求背景>`;占位符(`FILL/待填/<...>`)不算数。②**PMP 上下游机检**:`--stage spec` 要求 01-spec 两行齐全且背景引 P01/P12/业务;`--stage design` 要求 01.5/02/03/03.5 两行齐全且背景引 01-spec/REQ;`--stage testplan` 要求 02/03/03.5/04 两行齐全且 04 背景引 02/03/DES;缺即 **E126**(既有单 die 站点),禁止"先做后补"。③`scaffold` 为 8 个 md 产物输出两行(背景留 `待填`,填后才过门)。④**40 个模板全覆盖**:全部带交付触发点,entry/project/bug 共 32 件另带背景输入;新增 5 条源审计断言(模板计数 + DS/agent-gate 锚);DS 增 ~717B,A11/A48 ratchet 167,933→168,650(显式重校准,仍在 172,032 硬上界内)。⑤测试:夹具(单变更/批次)与 T80 裸 01 写入同步带两行;T80 三条既有断言改为"缺标记红→恢复后绿"复合(TC-1491c/1492b/1493b,不新增断言数);修正 T64 三条因 01.5 扩件后失真的计数钉(`created 9`/`8 md`/`member-appended 9`);修复两处既有红——T14(`.agent-governance.yml` 的 profile 块使二次安装误判 CONFLICT,`same_as_src` 比较时剥离 profile)与 T26(token 诚实化要求 in/out 同时可测)。⑥**基线**:本机全量被系统 `Killed: 9`(`-j2/-j4/-j6` 均复现),以 6 组互斥分片覆盖 93 节实测 **1559 passed / 0 failed**,`.suite-baseline` 1557→1559(旧值本身已失真),源审计 646→651。评级 L2;结构不变量不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/模板/`AGENTS.md`/DS/README×2/本行;存量进行中变更在下次阶段门被拦时按报错补两行即可;`00-governance.json` 无注释位,豁免。 | +| v3.91.5 | 2026-10-27 | **阶段即交付:禁止后补文档 / RTVM 最后统一填(用户硬指令)**:①`--stage design` 要求 `01-spec` 已有 REQ 编号且 `01.5` 已有 REQ 行——**需求未写不得开始设计**;②`--stage testplan` 要求 `02/03/03.5` 已交付且 `01.5` 已有 DES 与 TASK 行;③`--stage close 2/3/4` 分别校验 REQ / DES+TASK / TC 维度;缺任一即 `E126`(单 die 站点),不再有"最后统一补矩阵"的路径。④`new-change/--scaffold` 增 `01.5-rtvm-matrix.md` 模板(占位行**不**满足阶段门,必须在对应阶段回填);测试夹具(单变更/批次)同步带完整链。⑤`AGENTS.md` 由"八件模板"改"九件模板(含 01.5)",SKILL 同步;新增 **3** 条 T83 断言(design 门与 close 2 在缺 RTVM 行时 E126)。⑥**FULL 决策跳过 TC 三源扫描**(结果不影响 FULL,N4 复测 0.81–1.09 s,中位 0.99 s);基线/README **1557**。评级 L2;结构不变量不变。 | 目标仓 `--upgrade` 带走 `AGENTS.md`/`SKILL.md`/`agent-gate`/README×2/本行;存量进行中变更若缺 01.5 行,会在下一次 design/testplan/close 被拦——按新规当场补,不允许拖到交付。 | +| v3.91.4 | 2026-10-27 | **全量/耗时决策:AI 出议案 + 用户拍板(2026-10-27 二次裁定)**:①`plan.decision` 增 **`scope_confirmed`**;`plan` 接受 `AGENT_GUARD_SCOPE_CONFIRM='<用户>@'`,AI 收窄必须带用户确认。②`judgment=ai` 无 `scope_confirmed` → strict **`E148`** 拒(复用既有单 die 站点);FULL 决策不需要确认。③**AGENTS 纪律 7/10、SKILL 安装回执、双 README** 同步:判定卡(建议节/预计秒/缺口/风险)+ 三选一(采纳/升档/降档);**被 Kill** 先归因 `env_error`,最多一次自适应重试(分片/CI),再失败即停止并带耗时/缺口/风险重新请用户决策,禁止无限重试与盲等。④新增 3 条 T83 断言(记录确认 / 有确认可收窄 / 无确认 E148);基线/README 1554。评级 L2;无结构变更。 | 目标仓 `--upgrade` 带走 `AGENTS.md`/`SKILL.md`/`agent-gate`/README×2/本行;旧 decision 无 `scope_confirmed` 时按 `judgment=engine` 处理(向后兼容)。 | +| v3.91.3 | 2026-10-27 | **v3.91.2 勘误(用户质询后实测)**:①**Token 诚实化真正生效**:成本行原读旧 stats 标签,仍显示 `0/0(estimated)`;改为"stored=estimated 且 used=0 → `unavailable`",现打印"已用≈不可测 / tokens=不可测"。②**台账轮转保留 `run-full` 行**:首版 500 行轮转把唯一全量行删掉,导致 `plan` 的全量 p50 丢失、回落 300 s 先验;现轮转始终保留所有 `run-full` 行(历史已丢,待下一次真实全量重建)。③**采纳指标不再空转**:FULL 决策此前让 `accepted` 永远为 `-`;现 FULL 记 `yes`,采纳率可计算。④另登记:本轮会话 ≈4h23m(L2 >2× = 异常,主因全量被系统 Kill + 盲等轮询)、无单进程全量收据(1551 为两片真实执行相加)、AI 判断未交互发生(decision=`engine`,待用户裁定后重写)。评级 L2;无结构变更。 | 目标仓 `--upgrade` 带走 `agent-gate`/`session-gate`/`audit-docs-consistency`/`run-tests` 与本行;台账旧行只读前 8 列;`run-full` 行永不轮转删除。 | +| v3.91.2 | 2026-10-27 | **未闭合项收口(CHG-127 复核第二批)**:①**判定 ≤1 s(N4)**:节成本改单趟 awk、判定器改单次读文件、变更清单省一次 git,`plan` 3.0 s→0.95 s(实测 0.94–1.02 s)。②**四要素错误消息(P0-7)**:为 120/146 个 E 码补专用 `expected/allowed/fix/ref` 分组;其余变量消息码保留兜底并把消息自带的条款引用作为 `ref`。③**台账保留期(§2.2)**:`ledger_append` 与 audit 写入点"表头 + 最近 500 行"轮转(T82 两条断言)。④**G3 stale 补洞**:`diff_hash` 覆盖未跟踪文件(T83 两条断言)。⑤**Token 计量诚实化(§17.2)**:无实测且无上下文字符时输出 `unavailable`/"不可测",不再伪造 `estimated` 0/0(T83 一条断言)。⑥**回放工具(§9)**:新增源层只读 `scripts/replay-plan.sh`(历史 diff → 今日解析器 vs 05 实测节),当前 90 个可用变更中 40 为 FULL、0 个具体样本,**"假阴=0" 仍未证**(样本缺失,如实登记,不宣称达标)。⑦**`-T auto` 覆盖面(P0-12)**:非治理资产(截图/许可证/编辑器配置/根叙事文档)改判"无关",减少无意义的 FULL 回流。⑧**全量回归与陈旧钉**:本机单进程全量在 ~21 min 被系统 `Killed: 9`(串行/并行均复现),改以互斥分片真实执行全部 90 节——T1..T54 820/0 + T55..T83 731/0 = **1551/0**,`.suite-baseline` 与双 README 同步;同批修掉四处"久未跑全量"留下的失真钉(T57 计时行/陈旧计数、T61 夹具缺真实测试、T63 依赖私有总册、T73 README 版本字面破坏 release 计数)。评级 L2;结构与质量不变量不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/`session-gate`/`run-tests` 与双 README/本行;回放脚本为源层专用、不下发;台账旧行仍只读前 8 列。 | +| v3.91.1 | 2026-10-27 | **CHG-127 全量核对修正(final-plan 逐条复核)**:①**口径纠错**:`cost-ledger.tsv` 实为 **14 列**(历史 8 列原位 + 追加 `asserts/rc/outcome/repo_key/model_id/ctx_window` 6 列),修正 v3.91.0 行与 REQ-1259 的"13 列"笔误。②**判定时延(final-plan N4 ≤1 s)**:TC 索引 S1/S3 改为单趟 awk(预置节集合与文件集合,省去 300 行 × 4 进程),`tc-index` 1.96 s→0.39 s;`wasted` 改单趟聚合;`plan` 3.0 s→1.2 s,实测记录在 05。③**stale 判定补洞(G3)**:`diff_hash` 纳入未跟踪文件路径 + blob 摘要——此前 `git diff HEAD` 看不到新建文件,`plan` 后新增文件可静默逃过 E147。④**CPI 回归真实耗时(G18)**:`actual_s` 改读成本台账最近一次 `run/run-full` 墙钟(限定本会话),无台账才回落 `SECONDS` 并标 `elapsed`——原实现只测 stop 调用(≈1 s vs 120 s 预测,CPI 永不触发),等于空转指标。⑤**G13 可落地**:`change_type` 进 `governance-state.json` 模板与 `begin --scaffold`,此前无任何模板写该键,路由恒回落 `feature`。⑥**文档接线**:双 README 命令表补齐 `plan/status/resume/baseline/tc-index` 与 `metrics` 新列(final-plan §7 三件套之"文档")。评级 L2;结构与质量不变量不变。 | 目标仓 `--upgrade` 带走 `agent-gate`/`governance-state.json`/双 README/本行;旧 `change_type` 缺省仍回落 `feature`(向后兼容);台账旧行仍只读前 8 列。 | +| v3.91.0 | 2026-10-26 | **自适应治理 final-plan 设计级收口(CHG-127,G1–G19)**:①**台账 13 列(G1)**:`cost-ledger.tsv` 保留历史 8 列原位并追加 `asserts/rc/outcome/repo_key/model_id/ctx_window`,三处写入点(套件/审计/verify)统一并原地迁移旧 8 列表;`asserts=0 && rc=0` 标 `wasted`(G6),连续 3 次从推荐剔除并写 `decision.wasted`。②**判定 schema 与消费(G2/G3/G5/G11/G12/G13)**:`plan.decision` 增嵌套 `artifacts{universe,depth,conditional}`、`stages{path,skipped}`、`project_masters{fill,na}`、`review_roles`、`must`、`deferred`、`wasted`,扁平 `artifact_list/stage_list` 兼容且旧字符串键仍被读取;CAB 按 `value=覆盖 TC 数 / cost` 装填,超预算进 `deferred`,value=0 不可选(全 0 保底);`change.type` 结构路由(feature/fix/hotfix/refactor/docs/config/deps/migration/security)只收窄风险下限(L0/L1 轻量通道保留);`must` 非空默认 FULL(AI 判定可收窄,见⑦)。③**stale 与严格模式(G3/G12)**:consume 比对 `diff_hash`,默认自动重算并留痕,`PLAN_STRICT=1` 时 stale `GATE-E147`、`must` 未覆盖 FULL `GATE-E148`。④**回填时序(G4/G14)**:09 接受 `- [adapt] 项 :: reason :: 替代证据`;总册标记统一 ``,`stage` 必须等于 §5.5 映射阶段,`revision` 豁免。⑤**profile 与自检(G7/G8/G9)**:profile 增 `schema_version` + 九维场景键(ai_project/architecture/ui/runtime_env/repo_topology/assets 探测,business_complexity/delivery/org 缺省 unknown),旧块只补缺键不覆盖用户值;`plan --refresh-profile` 报缺键。⑥**运行时可观测(G10/G15/G16/G17/G18/G19)**:`agent-gate status` 打印 runtime/family/layers/enforcement/handshake/model/window;adapter `--canary` 写收据;`metrics` 增吸纳四列 + wasted 率/stale 数/握手覆盖/review 独立性;`resume ` 读 handoff/decision/下一步(缺参 `GATE-E149`);实际超预测或 CPI<0.7 写 `.agent-state/retro/`;session-gate H1/H2/H3 给出 handoff 动作。⑦**全量范围由 AI 判断(2026-10-27 用户裁定)**:改动被测核心时由 AI 以 diff 证据决定全量或定向(`AGENT_GUARD_SUITE_AI_SECTIONS/BASIS/REVIEWER` + `plan.decision.judgment`),缺证据才回落 FULL;`must` 非空同理,`GATE-E148` 只拦“无 AI 判定又非 FULL”。评级 L2;无新增契约产物。 | 目标仓 `--upgrade` 带走 DS/AGENTS/CHANGELOG/CLAUSE_REGISTRY/agent-gate/bootstrap/session-gate/install-hook-adapter/audit 与 09 模板。**回填义务**:旧 `cost-ledger.tsv` 首次写入自动迁移(只增列);旧 `profile` 块由 `--upgrade` 补齐 `schema_version/files/budgets`;旧 `decision` 仍按 `artifacts/stages` 字符串消费。**行为变化**:`stop/preflight` 开始消费嵌套判定;`PLAN_STRICT=0` 下 stale/must 只 WARN,`ADAPT=0` 仍整体退出。 | +| v3.90.5 | 2026-10-26 | **final-plan 剩余项收口(CHG-126,P0-0/P0-9U-6/P1-2/P2-1/P2-2/P2-3/P2-5)**:①**基线快照(P0-0)**:`agent-gate baseline [--write]` 从既有 `cost-ledger.tsv` + 套件收据读 5 个数(stop p50 / 全量次数 / audit p50 / 全量断言数 / 全量墙钟),缺数据标 `null`,`--write` 落变更私有 `baseline.json` + 09 一行(幂等);`GATE-E140`。②**三源 TC 索引(P1-2)**:`agent-gate tc-index [--write]` 并集 **04 矩阵 + 测试脚本自报 TC + 01.5 RTVM**,输出 `tests/tc-index.tsv`(目标仓派生物,不下发)与 `ok|dangling|unresolved`、解析率;`plan.resolution_rate` 复用同一实现;`GATE-E141`。③**四判定器(P2-1)**:`plan.decision` 增 `artifacts/reviews/stages/masters/judges_source/judges_reviewer/judges_basis`;引擎只编码**结构下限**(risk + 是否动代码路径 + profile 规模),不写死业务关键词;AI 覆盖须 `AGENT_GUARD_PLAN_AI_*` + `AI_BASIS`(≥20 字符)+ `AI_REVIEWER`(platform / model / task-|ses-)。④**gate 消费判定(P2-2)**:stop/preflight 读 decision;缺 decision 默认 WARN、`AGENT_GUARD_PLAN_STRICT=1` → `GATE-E142`;artifacts/stages 硬项缺失 → `GATE-E143`;masters/reviews 软项默认 WARN + 要求 09 `decision-gap`。⑤**覆盖对账(P2-3)**:`decision.chosen` 的测试节须在 05 有证据;差集默认 WARN、strict → `GATE-E144`,结果回写 `adapt-decisions.tsv` 的 `accepted` 列。⑥**迟到回填(P2-5)**:总册可选 `filled-at stage=N change= [at=]`(必须带 change,否则不归属本变更);`--stage close ` 写阶段历史并把回填清单入 `stage-close.json`;未来阶段/`at` 晚于该阶段关闭 → `GATE-E145`;下一阶段首条 Observation 未引用上一阶段回填锚点 → `GATE-E146`。⑦**安装升级(P0-9/U-6)**:已有 `profile:` 块只补缺失键(`files`/`budgets`),已有值 0 覆盖,`schema: 2` 视为用户自管。评级 L2;新增文件仅目标仓 `tests/tc-index.tsv` 与变更私有 `baseline.json`,均非契约产物、均不下发。P3/P4/P5 按 CHG-125/09 **永久不做**。 | 目标仓 `--upgrade` 带走 agent-gate/bootstrap/CHANGELOG/README×2/SKILL/DS/AGENTS/CLAUSE_REGISTRY/METHODOLOGY/methodologies×6 版本行。**回填义务:无**——decision 新键旧读者忽略,`AGENT_GUARD_ADAPT=0` 完全退出,`PLAN_STRICT=0` 仅 WARN。**行为变化**:stop/preflight 多一层判定消费;`--stage close` 多写阶段历史与 09 一行;老 profile 块升级时补两个缺键。 | +| v3.90.4 | 2026-10-26 | **评审智能与运行时适配(AI 判断不写死 + 专业独立评审 + 贵模型用户确认)**:①**评审智能契约**:新增 `resources/methodologies/review-intelligence.md`——评审必须装载项目背景(P12/P01–P04/bugfix-log/FU)与系统特点,按环节匹配专业能力(架构=先进性与覆盖面;代码=安全/性能/缺陷/业务合理性;UI=UX/UE/可达性;衔接=追踪一致性),并给出有证据的批判性发现;**门禁只校验结构/证据/独立性/成本确认,专业结论由评审 AI 判断**,禁止固定分数/关键词替代判断。②**运行时适配**:评审执行体先探测**目标仓被打开的 Agent 客户端**(目标仓根执行 `install-hook-adapter --detect`,不是编辑 Skill 的源仓客户端),再选方案——json-hooks/plugin-api 用同客户端独立子 Agent+独立会话;git+ci(codex/gemini)优先外部独立 CLI 或人类/CI;无独立执行体即阻塞,不得自评。③**贵模型用户确认**:`agent-gate review-plan <变更号>` 输出运行时、所需专家、候选模型/CLI 与成本档位;`deep`/`approval:true` 必须用户设置 `AGENT_REVIEW_USER_APPROVED=1` 后 `--approve ` 才写入 `.agent-state/review-plan.json`;未确认在 staged/stop/ci 交付面 `GATE-E137`;`review-plan` 用法错误 `GATE-E138`、`--approve` 缺模型 `GATE-E139`。`begin` 自动 seed(无配置=economy,零确认成本)。④**模板**:07 增「评审输入契约与专业能力」「模型选择与成本确认」「独立性声明(生产 vs 评审)」三节;新增 `.agent-review-models.example.json`(复制为 `.agent-review-models.json` 生效)。⑤**AI 判断不写死**:DS §2.1 规则 11、§2.2 评审智能契约、AGENTS 红线与锚点表同步;自适应判定由 AI 给证据与复核,引擎建议只作输入。⑥**测试范围 AI 判断(FU-126-1)**:`-T auto` 对 runner 自改不再只有写死 FULL——AI 可用 `AGENT_GUARD_SUITE_AI_SECTIONS` + `AGENT_GUARD_SUITE_AI_BASIS`(≥20 字符)+ `AGENT_GUARD_SUITE_AI_REVIEWER`(platform / model / task-|ses-)覆盖;缺证据/未知节回落 FULL,T50 恒跑;`agent-gate plan` 把 `judgment/reviewer/basis` 写入 decision。评级 L2;无新增契约产物(plan 在 `.agent-state/`)。 | 目标仓 `--upgrade` 带走 DS/AGENTS/CHANGELOG/CLAUSE_REGISTRY/METHODOLOGY/methodologies×6/07 模板/agent-gate/bootstrap 与示例模型清单。**回填义务:无**——未复制 `.agent-review-models.json` 即默认 economy,旧行为不变;`.agent-state/review-plan.json` 不被旧读者依赖。**行为变化**:新变更 begin 自动写评审计划;配置了 deep 模型的仓在用户确认前 staged/stop/ci 会 `E137`。 | +| v3.90.3 | 2026-10-26 | **R3 收尾班车:硬门 + 遗留清零(CHG-125,REQ-1244~1252,DES-1999~2007,TC-1547~1555)**:①**阶段关闭(P2-1)**:`--stage close` 要求 `00.5` 确认记录 + 09「子 Agent 放行」行,缺任一 → `GATE-E127`;齐备写 `.agent-state/stage-close.json`(唯一新增写点,非契约产物);`AGENT_GUARD_STAGE_CLOSE=0` 可关。②**复核成对(P2-2)**:09 声称「阶段复核」而 `reviews/P*.review.md` 缺失/空 → `GATE-E128`。③**确认硬门(P2-3)**:L2/L3 无用户整体确认 → staged `GATE-E129`、preflight `GATE-E130`(preflight 按 collect-all 计入 violations,不改 0/1 契约)。④**自举硬拒(P2-4)**:E131 从 WARN 升 **rc 2**(`AGENT_GUARD_ADAPT=0` 仍可显式放弃)。⑤**遗留清零**:`bootstrap --guard` 末段引擎自检 + runtime 重探测(FU-958);audit 写 `kind=audit` 台账行、verify 缓存命中写 `kind=verify cache=hit cost_s=0`(FU-959);`run-tests --dual-run` 断言面方言扫描 + `PORTABILITY-WHITELIST` 块,CI OS 矩阵为双跑执行面(FU-960);夹具 `setup_s` 记账(FU-961,共享模板收益不足,永久接受);三 runtime 结论定案为「安装侧可证 + 目标仓自检」,客户端加载不可证 → **永久关闭**(FU-962);`plan.resolution_rate` 改 `tc=/` 三段匹配(FU-963);整轮 p50 只读 `kind=run-full`(FU-964)。⑥**终结**:本行发布后 `adaptive-governance` 方案(R1~R3)终结;P3 自学习 / P4 规范正文回写 / P5 单源收敛**永久不做**,理由见 CHG-125 09。评级 L2;无新增契约产物。 | 目标仓 `--upgrade` 带走 agent-gate/bootstrap/audit-docs-consistency/run-tests/CHANGELOG/README×2/SKILL/DS/AGENTS/METHODOLOGY/methodologies×5 版本行。**回填义务:无**——新门只作用活跃变更;`.agent-state/stage-close.json` 与 `reviews/` 不被旧读者依赖。**行为变化**:L2/L3 交付前多三道理性门;`stop` 缺自举两行将 **rc 2**;`--dual-run` 为纯增量旗标。 | +| v3.90.2 | 2026-10-26 | **R2 引擎 v0:判定只读建议(CHG-124,REQ-1237~1243,DES-1992~1998,TC-1540~1546)**:①**`agent-gate plan `(P1-1/P1-2)**:读 `git diff` + `.agent-state/cost-ledger.tsv` + 复用 `tests/run-tests.sh -T auto` 的解析 seam(**不写第 4 份"文件→节"映射**),产出 `decision`(engine_version / decided_at / diff_hash / budget_s / chosen / predicted_s / source / resolution_rate / gaps),**只追加**进既有 `00-governance.json`,同时在 `00-intent` 尾部留 4 行人读块、`.agent-state/adapt-decisions.tsv` 记一行;`--dry-run` 零写入、`--explain` 打印成本账;`begin` 默认自动跑一次(否则判定永远没人读)。写盘前做括号/引号配对 + `decision` 唯一性 + 回读校验(有 python3 时追加真实 JSON 解析),失败只 WARN 不写。②**stop 建议行 + 三选一(P1-3)**:`stop` 打印「建议 节=… predicted_s=… 预算=…」;`AGENT_GUARD_SUITE_MODE=adopt\|up\|down` 决定并落 05(`suite_mode` / `chosen` / `predicted_s` / `actual_s`),`down` 缺 `AGENT_GUARD_SUITE_DOWN_REASON` 时**回退 adopt + WARN**;同一会话同一变更的 05 段只写一次。③**profile 段(P1-4)**:`bootstrap --guard` 在目标 `.agent-governance.yml` **没有任何 `profile:` 键**时补写(language / size / files / tests / ci / budgets),已有键永不改写;重复安装不重复追加。④**升级行为变更报告(P1-5)**:`--upgrade` 打印 4 行「判定默认变化 + `AGENT_GUARD_ADAPT=0` 保持旧行为」,只打印不写盘。⑤**自举机校(P1-6)**:`stop` 对 09 缺 `[dogfood]` / `[dogfood-next]` 出 `WARN GATE-E131`(**R2 只警告,rc 不变**;R3 才硬拒)。⑥**单开关**:`AGENT_GUARD_ADAPT=0` 关闭 plan / 建议行 / E131,行为回到 v3.90.1。新错误码 **E136**(plan 用法错误)。评级 L2;无新增契约产物(decision 写既有 JSON,账本在 `.agent-state/`)。 | 目标仓 `--upgrade` 带走 agent-gate/bootstrap/CHANGELOG/README×2/SKILL/DS/AGENTS/METHODOLOGY/methodologies×5 版本行,并打印行为变更报告。**回填义务:无**——`decision` 是新增键,旧读者忽略;`AGENT_GUARD_ADAPT=0` 可完全退出。**行为变化**:`begin` 多一行 plan 输出;`stop` 多一行建议与 05 的一段 suite-mode;`--guard` 首次安装补 `profile:` 段(用户可自由编辑,之后不再覆盖)。 | +| v3.90.1 | 2026-10-25 | **R1 止血班车:执行成本传感器 + 观测面取信(CHG-123,REQ-1219~1236,DES-1974~1991,TC-1522~1539)**:①**计量(P0-15)**:`session-tool-stats.json` 只**追加** 9 键(`tokens_in/tokens_out/context_chars/wall_s/stage/change/model_id/ctx_window/exec_source`,旧 8 键名与顺序不变、旧文件缺键读 0);`session-gate start` 按 **env > 同模型缓存画像 > 保守 128000(assumed+WARN)** 解析窗口并落 `.agent-state/model-profile.json`;`model_id` 变化即按新窗口重算 H 级(60/75/90%)并追加 `model-transitions.tsv`;`agent-gate cost-line ` 向 09 追加一行(变更+会话起点幂等),`--stage stop` 通过后自动调用。估算值标 `estimated`,**不进任何 exit 2 判定**。②**计时与台账(P0-2/P0-3/P0-14)**:`run-tests.sh` 逐节 `[done] Tnn Ns` + 单个 `suite-progress.json`(run_id/head/mode/wall/sections),每节/每次运行写 `.agent-state/cost-ledger.tsv`(8 列),`setup_s` 由夹具起止实测。③**runtime 可见(P0-1)**:`install-hook-adapter` 增**协议家族**归类(json-hooks/plugin-api/git+ci)、`.agent-state/runtime.json` 与 `runtime-transitions.tsv`;`--detect` 无任何 runtime 时 **exit 3** 并打印生效层/缺失层(此前 exit 0 静默成功);`agent-gate session-start` 写会话握手 `.agent-state/runtime/.json`,`begin` 缺握手出 YELLOW。④**full_suite 语义(P0-11)**:计数排除治理自测形态(`run-tests.sh`/`audit-*`/`verify-all`),只数"全量业务回归"。⑤**审计增量(P0-4)**:`audit-docs-consistency --since ` 三分支显式——无 diff 声明 no-op;diff 未触审计面声明 no-op 并列出未覆盖面;触面则**跑全量**(增量绝不静默收窄)。⑥**等待纪律(P0-6)**:AGENTS 纪律 10 增「读进度文件 + 短轮询、禁 `TaskOutput block:true timeout>60s`」。⑦**错误消息四要素(P0-7)**:`gate_hint()` 单表为每个 `GATE-E` 码补 `expected/allowed/fix/ref`(失败时才打印,零常驻;E132 起新码自带四要素);同时拆掉 CHG-121 遗留的 **E126 重号**(结构校验 → E133/E134/E135,T41 码唯一性恢复绿)。⑧**锁与可移植(P0-5/P0-8)**:套件锁 owner 改为 **pid + lstart + 仓库物理路径**三元组,PID 复用/异仓锁自动回收;断言可移植**基线已建立**(`\|` 共 57 处,逐条区分 ERE 字面量 vs BRE 方言属机械大改,本轮未清零,登记 FU-960)。⑨**自动选节(P0-12/P0-13)**:`_auto_map` 增 agent-gate/session-gate/lib/tests 与文档/方法论组;未映射的治理面路径回落 **同域节**(T19/T30/T41)而非全量;T75/T76 的 SKIP 判据由"有无 `facts.sh`"改为**源仓布局**判定。⑩**payload 边界(P0-16)**:DS 路径根段删去源仓私有安装器路径(改为"安装器(源仓维护者工具,不随 payload 下发)"),并在套件加 payload 扫描断言(P 层文档命中 S 路径 = 0)。**已交付但本轮无代码面**:P0-10 验证通道体检在 CHG-121 已落地(探测排除治理自测 + 四态可见),本轮仅回归;**未达成本轮:P0-9(bootstrap U-1/2/3/5/6 接线)、P0-8 的 CI 双跑入口、P0-3 的 TC 级/audit 行**,已在 09「遗留与未达成」逐条登记 FU。评级 L2。 | 目标仓 `--upgrade` 带走 agent-gate/session-gate.sh/install-hook-adapter/audit-docs-consistency/run-tests.sh/lib-suite-lock.sh/DS/AGENTS/SKILL/README×2/CHANGELOG 版本行。**回填义务:无**——新增键只追加、新增账本在 `.agent-state/`;旧 `session-tool-stats.json` 自动兼容。**行为变化(可见降级)**:未知 runtime 的 `install-hook-adapter --detect` 由 exit 0 改 **exit 3**;`full_suite` 不再统计治理自测;`session-gate status` 多一行成本。 | +| v3.90.0 | 2026-10-25 | **消六处内部矛盾 + 观测口径收敛(CHG-122,REQ-1213~1218,DES-1968~1973,TC-1516~1521)**:①**全量回归触发面(§0 门禁 2 末条)**:删「禁止只跑受影响用例」,改为「全量由门禁(stop/staged/CI)统一触发 + 内循环定向验证(定向集合 = `04` TC→脚本 ∩ `git diff`)」;②**批次产物口径**:删「15 件同名产物仍齐」,改按 §1.1 两档不可占位集判定;③**删 §2.2「L2 每变更专家评审会话 ≤3」**(与「阶段 1-5 各派独立子代理」必然冲突),成本护栏改指向 §2.17.4 轮次上限;④**metrics 字段收敛(§2.17.5)**:删 `expert_sessions_over_guardrail`(对应上限已不存在),agent-gate 同步删字段,golden 断言改钉 `expert_sessions` 紧邻 `artifact_files`;⑤**表达成本豁免扩容**:单产物 ≤40 行豁免集加 `07`/`01.5`(结构型),STAGE_PLAYBOOK 同步;⑥**契约口径统一**:「15 件契约产物 + 条件件 `handoff.md` = 16」。评级 L2;体量净下降(A11 上界 168KB 不变)。 | 目标仓 `--upgrade` 带走 DS/STAGE_PLAYBOOK/agent-gate/SKILL/README×2/AGENTS/METHODOLOGY/methodologies×5 版本行;metrics 消费方若读 `expert_sessions_over_guardrail` 需改读 `expert_sessions`(只观测字段,无执法面)。**回填义务:无**——新口径只约束新变更;在途变更产物件数不受影响。 | +| v3.89.0 | 2026-10-24 | **缺陷入口执法点前移 + 无状态阶段门(CHG-117,REQ-1199~1203,DES-1955~1961,TC-1483~1495)**:①**§2.17.2b 信号③(REQ-1199,DES-1955/1957)**:会话内无账源码改动(编辑/暂存源码路径文件时无活跃变更、无当日缺陷组、非纯文档改动)与②同走交互三选项,执法面双层——编辑时刻硬拦(session-gate `check` 模式 edit/write 族谓词 exit 2,复用 v3.58.0 轮次硬拦管线;取不到 hook 入参路径的客户端降级不拦,staged/audit 兜底)+ 交付边界 fail-closed(REQ-1200,DES-1956:agent-gate staged 扫 `git diff --cached`、stop 扫 `git status --porcelain` 合并面,`is_code_path` 排除面同源复用,`GATE-E125`;豁免阶梯=活跃变更/当日缺陷组/`AGENT_GUARD_ALLOW_UNACCOUNTED=1`——豁免打印 WARN 并入 friction 台账,理由须 09 登记);审计新增 **G16** 披露面(DES-1959:本地工作树源码面无账即 FAIL 点名,干净/非 git 显式 VACUOUS SKIP 防假绿沿 G9 形态,`--only-fail` 下 SKIP 态不打印;排除面与 gate `is_code_path`/session-gate `sg_is_code_path` 三处互钉同表同源)。②**SKIP_VERIFY 收窄(REQ-1200,DES-1958)**:`AGENT_GUARD_SKIP_VERIFY` 语义收窄为仅豁免全量回归——无账检查照跑照红;session-gate idle 的 stop 等价调用另注入内部标记 `AGENT_GUARD_SKIP_VERIFY_CONTEXT=idle`(仅声明语义非开关,外部手工设置同值无越权效果,防伪装)。③**无状态阶段门(REQ-1202,DES-1960)**:`agent-gate --stage spec\|design\|testplan` 从磁盘产物锚点推断完成度(spec=01 REQ 表+编号连续;design=02 三维+回滚+03 选型/既有范式节+03.5 任务拆解;testplan=04 用例矩阵+TC 落点清单,E113 单源抽出 `tc_landing_check` 双调用点),不写阶段状态文件、幂等可重入;**begin 收窄为入口门**(00-intent 预期结果/开放问题/目录落位 E86 + 00-governance.json + 00.5 确认 E83)——**收窄≠弱化:staged/stop/ci 交付全查不变,01-04 检查只是分布到阶段门,覆盖面不减**;`AGENT_GUARD_STAGE_GATES=0` 恢复旧 begin 全查并关闭 check 阶段谓词(存量平滑开关,默认开;显式 `--stage <门>` 调用不受开关影响)。④**check 阶段感知(REQ-1203,DES-1961)**:编辑拦截谓词升级为路径→前置门映射——源码编辑需 G-测试门(04 用例矩阵+TC 落点清单)**或** bug 凭证(当日缺陷组骨架锚点+bugfix-log 登记行,齐备性仍归 G8/staged,凭证只放行编辑不豁免交付);02/03 编辑需 G-规格门;04 编辑需 G-设计门(02+03+03.5);00-intent/00-governance/00.5/01、缺陷组目录、模板骨架为流程动作不拦;报文指明缺哪道门+补什么产物+关闭法。⑤**测试(TC-1483~1495)**:T77 gate 无账三态(含 staged 删除面与「空缺陷目录不算凭证」)/T78 check 两态+idle 收窄(含绝对路径归一)/T79 G16 三态/T80 阶段门红→绿+开关(含 BATCH 成员与入口级 preflight 同口径)/T81 check 阶段感知全组(含绝对路径归一、BATCH 成员目录解析与 bug 凭证);T50 尾钉与 A56 尾钉随 SECTIONS 注册表 T76→T81 重校准;本行不复述套件断言数——唯一真值是受跟踪的 `tests/.suite-baseline`。⑥**条款收口(DES-1955)**:DS §2.17.2b 三类信号补③、§2.16.2 阶段 3/4/5 开动句插阶段门执法点、§2.17 阶段门/无账门专段、AGENTS 门禁 2 重写(入口门+阶段门序列)与门禁 4 三类信号、锚点表 G16 行、CLAUSE_REGISTRY R06 描述、STAGE_PLAYBOOK 阶段门执法点行;A11 重校准 164→168KiB(+4KiB 步进,DS 实测 165,937B、余量 6,095B;独立评审批 F5 收敛,MAINTAINER §5.1/§5.2 登记)。评级 L2。 | 目标仓 `--upgrade` 带走 **agent-gate/session-gate.sh/audit-docs-consistency/run-tests.sh/DS/AGENTS/CLAUSE_REGISTRY/STAGE_PLAYBOOK/SKILL/README×2/CHANGELOG** 版本行与载体。**回填义务:无**——新门随新变更生效;在途变更对新阶段门幂等绿(八件齐自然全过);已装仓升级后重跑 `install-hook-adapter` 非必需(check 模式接线面零变化)。`AGENT_GUARD_STAGE_GATES=0` 提供给依赖 begin 批量全查习惯的仓平滑过渡;SKIP_VERIFY 消费面收窄仅影响 idle 无账检查路径。 | | v3.88.0 | 2026-10-22 | **声称链对账机检 + `-T auto` 变更集裁剪 + 部分收据 fail-closed(CHG-116,REQ-1194~1198,DES-1950~1954,TC-1466~1482)**:①**声称链对账器(REQ-1194,DES-1950)**:`pre-review-check.sh` 增声称链节——TC **双向对账**(机器面=`run-tests.sh` report 行的 TC 号;声称面=04 映射表+落点清单+01.5 矩阵;未登记=机器号 ≥ 声称面最小号而缺登记——CHG-115 的 TC-1465 事故正是 min 后下一号;幻影=声称有机器无,全量查;连续性表述不携带裸 TC 字面量)+ **01.5 锚点新鲜度**(`file:line(token)` 逐条实测行内容,dangling/失配即 FAIL 点名;非括注形态不进机检面——时间戳会伪装成 `T13:25` 形锚点);对账对象在 gitignored `docs/`,只在本地 pre-review 存在,CI 的 not-checked-here 边界不变;F5/N6 两母题(CHG-115 复发 3 次)的机检闭环,PD-6 买前清单①②的可执行化。②**A56 环扩 PD-6(REQ-1195,DES-1951)**:私有措辞环 12→14 token(新增 PD-6 对应中英措辞;环词表内容不在此复述——复述即泄漏,A56 钉并当场抓获本行初稿的复述),PD-6 与 PD-1~5 同权。③**套件自记 full_suite(REQ-1196,DES-1952)**:全量运行(含 auto 回落)原子自增 `.agent-state/session-tool-stats.json` 的 `full_suite`(`AGENT_GUARD_SESSION_STATS_PATH` 隔离;`FAKE_FULL` seam 在分发前捕获并 unset——nested 调用继承 seam 曾致 3 次假计数,实测自纠);`-T` 部分节与 verify-all 收据复用均不计;写失败 WARN 不改判;`batch-metrics` 的 full_suite 列从此有真值,跨客户端 hook 接入面继续不做。④**`-T auto`(REQ-1197,DES-1953)**:`git diff --name-only` 经内建映射表推节,并集恒含 T50 注册表钉;**无映射命中 / runner 自改一律回落全量**(映射是优化不是正确性依赖,宁可慢不可漏);`--base` 可换基线;空 diff 即 0;`AGENT_GUARD_SUITE_AUTO_DIFF` / `AUTO_RESOLVE_ONLY` 双 seam 可测;映射引用节由 A57 钉 ∈ SECTIONS 防表腐烂。⑤**部分收据 fail-closed(REQ-1198,DES-1954)**:全量收据增 `"kind":"full"`;auto 部分运行只写 `last-suite-partial.json`(kind:"partial",绿写红删与全量对称);`ci-summary --check` 对 kind 缺失(v3.87 旧收据)或 partial 一律 rc1 点名 `not full authority`——部分收据从此进不了任何权威消费面;`sf_receipt_fresh` 不改(HEAD+指纹与 kind 正交)。⑥**测试(TC-1466~1482)**:T74 声称链(双向差集/锚点漂移/dangling 全负例)、T75 auto(映射命中/回落/权威路径零污染/自举全量)、T76 自记数(+1/部分不计/写失败降级)、T73b kind 三态(partial 红/缺失红/full 绿);**A57** 五面钉(kind 双写者/全量门控条件/消费端拒绝/映射引用节 ∈ SECTIONS/T50 恒跑+自改回落);`--base` 尾随无值 rc2 入 CHG-115 R4 的 arity 族。本行不复述套件断言数——唯一真值是受跟踪的 `tests/.suite-baseline`。评级 L1 复核:无参行为零变化、收紧面不下发(同面先例 CHG-115)。 | 目标仓 `--upgrade` 同步版本载体,无新增动作、无配置变更、无 CI 模板变更;下发的 `run-tests.sh` 增 `-T auto` 纯增量旗标(无参行为零变化,A57 钉);源仓维护者迭代默认 `-T auto`、收口 `-j 4` 一次,收口前跑 `scripts/pre-review-check.sh`(现含声称链节)。 | | v3.87.0 | 2026-10-22 | **源审计去隐式套件执行 + 源层验证工具链(CHG-115,REQ-1184~1193,DES-1940~1949,TC-1439~1465)**:①**提交式套件基线(REQ-1184/1185,DES-1940/1941)**:新增受跟踪 `tests/.suite-baseline`(**源仓维护者文件,与下列七个源层工具一样不随 Skill 下发**;目标仓装完看不见它们,本行的工具路径在目标仓不存在)(生成器唯一写、审计只读,沿用 `tests/.audit-baseline` 的 CHG-009/FU-022 范式);`update-assertion-count.sh` 增 `--from-baseline` 与 `--require-receipt` 两个**绝不执行套件**的显式证据来源模式,缺基线/非数字/互斥参数/无收据一律 exit 2,写模式同步 README×2 与基线。②**A3 改造(REQ-1184)**:源审计 A3 由 `--check`(收据过期即回落全量套件)改为 `--check --from-baseline`,实测该断言 300.984s→秒级、占源审计总墙钟 97.2% 的单点消失;生成器 stderr 不再被 `2>&1` 吞掉。③**源层工具链(REQ-1186~1188/1190~1192,均不下发)**:`lib-source-facts.sh`(共享只读原语,含唯一一份收据信任判定 `sf_receipt_fresh`)、`facts.sh`(秒级 JSON 事实快照 + `--write`)、`verify-all.sh`(release→ledger→audit→suite→gate 五步 collect-all + 单收据 + 前后树指纹稳定门 + `--fresh`/同树收据复用/阶段缝合 env;`gate` = `ci-summary.sh --check`,R4 前这道"基线==收据"硬门只在 CI 存在,本地入口声称自己是真值却不含它)、`pre-review-check.sh`(16 件产物/FILL/确认/证据/责任人独立性/provenance/版本载体/镜像/数字对基线/空 glob 陷阱)、`mutation-check.sh`(四类变异在临时副本上必须使对应检查器转红,前后对全部 git 可见路径做内容哈希比对以自证活树零副作用,空清单即拒绝运行)、`ci-summary.sh`(CI Markdown 汇总 + 基线/收据硬门)、`batch-metrics.sh`(TSV 权威账本 + JSON 镜像,采 sleep_polls/full_suite/wall);`selfcheck.sh` 改为委托 `verify-all.sh`,消除第二套自检编排。④**CI(REQ-1191,DES-1947)**:golden-case 跑套件前校验基线在位且为十进制、跑后 `ci-summary.sh --check` 硬门 `baseline == receipt.passed`、再 `if: always()` 输出汇总;source-audit 仍不重跑套件。⑤**边界机器守卫(REQ-1193,DES-1949)**:A56 钉「新工具存在且带 source-layer-only 头」「`bootstrap.sh` 复制清单不含新工具」「T69–T73b 有源工具缺失即 SKIP 分支,且断言必须排在分支之后(否则目标仓拿到的六节会因守卫前置而红)」「基线文件受跟踪」「A3 使用基线模式」「CI 拓扑按 job 切片钉死:source-audit 不得 `needs:` 任何 job、聚合 job 必须带 `if: always()`(缺了它一红就整检查消失)、needs 清单必须含两个真实 job、汇总步骤必须 `if: always()`」「基线数字在只读消费者与 CI 里只有 `sf_baseline_num` 一份解析配方」「SECTIONS 尾钉 T73b」;R4 另删去载荷专用措辞环——其扫描集与词表都是"全受跟踪面措辞环"的真子集,不可能独立变红却每次多付 ≈10s grep;公开载荷语义零变化。⑥**测试与基线**:`tests/run-tests.sh` 新增 T69/T70/T71/T72/T73/T73b 六节(`-j 4` 全量跑;本行**不复述套件断言数**——唯一真值是受跟踪的 `tests/.suite-baseline`,由 A3/A3c 与 CI 硬门对齐,复述即造第二真值源);套件基线上调至本次实测数,源审计基线 620→640(A56 段 20 条)。⑦**会话成本约束(REQ-1189,DES-1945)**:本批把维护会话的开销约束下沉到仓库本地私有配置(不入库、不随 Skill 下发);受跟踪面只记录工具用法与边界判定,A56 反向钉该私有措辞不出现在任何受跟踪面(含源层文件,扫描集为受跟踪∪未跟踪全集)。⑧**同族补刀(R3/R4 闭合核验)**:随 `bootstrap --guard` 下发的 `tests/run-tests.sh` 自身在 `-T` 尾随无值时 `shift 2` 不推进 → 死循环(实测挂住),现改为参数缺失即 rc2 并打印用法,T70 增看门狗式回归断言把「挂住」本身判为失败;**但 `-T ""` 是合法的全量运行**(T68 靠它证明全量运行拒绝被占用的工作区锁),只有"操作数缺失"才是用法错误——R3 的第一版修复把两者混判 rc2,静默废掉了 T68 的锁断言,R4 按"缺失 vs 空值"分开并加反真空断言。同一族在六个源层工具与 CI 里全部收口:`--root/--path/--jobs/--change/--only/--batch` 尾随无值一律 rc2 并点名选项,不再静默沿用默认值(`facts --path`、`verify-all --jobs`、`pre-review --change`、`mutation-check --only`、`batch-metrics --batch` 各有一条夹具实跑钉)。`verify-all` 同时收 `-j` 作为 `--jobs` 的别名——它转发的套件就叫 `-j`,而文档里写的正是 `-j 4`;别名缺席时这条常见调用会以"未知参数"rc2 失败(本次实测自己踩到),T71 钉「`--jobs` 尾随无值 rc2 且 `-j 4` 被接受」。本地单入口补第五步 `gate`(`ci-summary --check`),与 CI 用同一条硬门;`--skip-gate` 记 `skip` 不算 pass,红门必红整跑——T71 三条实跑钉(顺序含 gate / skip 语义 / 红门转红)。信任判定收口到一条规则:`ci-summary --check` 现在与 `sf_receipt_fresh` 同样要求"同 HEAD + 同树指纹"(此前只有复用面判指纹,CI 门接受错树收据),`verify-all` 的树稳定门改为指纹不可计算即判失败(拿不到证据不等于证据是稳定)。A56 新增「六节断言必须排在 SKIP 分支之后」守卫——此前只 grep `SKIP Txx:` 字符串,T69 两条断言写在守卫之前、目标仓实测 `0 passed, 2 failed` 却检测不到(同族扫描确认 `new-change.sh --risk` 已有 arity 检查、`bug-autointent.sh`/`agent-gate.sh` 的 8 处 `shift 2` 受 `set -euo pipefail` 保护,无同类挂死;`stamp-provenance.sh --bug` 的尾随无值仍属既有面,本批未动,登记 09 未动项)。另收一处最终实测自查到的账本假阴:`batch-metrics` 用通用 JSON 读取器取 verify 收据的 `status`,而该收据在每个 step 内**也带** `status`,通用读取器取最后一个匹配——audit 转红的批次被记成 `pass`(成本台账自己造了第二个假绿)。现由 `sf_verify_status` 按两空格缩进锚定顶层字段(step 行内联,缩进即边界),两个消费者(`batch-metrics` 台账列、`ci-summary` 汇总行)同时接入;T73b 四条夹具实跑钉(TC-1464)住「红步骤必须记 fail / 绿收据仍记 pass / 无收据记 none / 汇总行取顶层」,防止守卫本身退化成常量。同族扫描确认:verify 收据里唯一重复出现的键就是 `status`,其余读取点(`rc` 未被任何人读、治理件的 `change_id` 单键、套件收据平铺)无同类风险。评审收尾又核出 `pre-review-check --change` 只按 `00-governance.json` 的 `change_id` 匹配——传批次目录名(`BATCH-YYYYMMDD`,其 `change_id` 是内部编号)解析不到,16 项产物检查被静默跳过;改为**单段目录名优先、再回落 `change_id`**(含 `/` 与 `..` 的遍历形排除),T72 增 6 条断言(TC-1465)钉住目录名命中/解析落点/双面均不匹配 rc1/发现信息点名两个解析面/遍历形拒绝不被当路径。 | 目标仓 `--upgrade` 仅同步版本载体,无新增动作、无配置变更、无 CI 模板变更;源仓维护者改用 `scripts/verify-all.sh` 为单一验证入口,收口前跑 `scripts/pre-review-check.sh`。 | | v3.86.1 | 2026-10-21 | **DS §4 压缩 + 09 模板一致化 + README 信任能力前移(CHG-114,REQ-1180~1183,DES-1936~1939,TC-1434~1438)**:①**§4 模板副本下沉(REQ-1180,DES-1936)**:删除 DS §4 内嵌的 9,224 B 完整 09 模板副本,改为十四节名称 + 三条机校不变量 + Bug 十项口径(名目/勾选行只在模板,DS 无副本);完整形状唯一权威=`entry/09-changelog.md`。DS 体量 167,933→163,348 B,低于 A11s 软预警线 163,840 B(余 492 B)。②**模板可用性修复(REQ-1181,DES-1937)**:`entry/09` 补 P12 产品上下文册,形成 P00–P12 十三行(原 12 行会被 gate stop 逐册机校拦截);补「§3/DoD 从 DS 逐字复制、模板不内嵌副本」说明。③**A55 防回潮(REQ-1183,DES-1939)**:源审计新增 7 条断言——§4 无内嵌任意缩进/样式围栏或任意勾选行副本(P/Bug 双检)、唯一权威命名、DS↔模板十四节规范标题名单钉、模板 13 行、模板 Bug 十项、DS 十三行口径;另有 DS 无 Bug 副本专检;基线 613→620。④**README 信任能力前移(REQ-1182,DES-1938)**:双 README 的 RTVM 行补 `change_uid`,新增「Release Integrity + Evidence Reuse」行(release check、CI 收据复用、套件锁),修正「每个 job 15 分钟」为「两个真实 job 15 / 聚合门 5」。⑤**审计空转修复(延伸发现)**:`audit-docs-consistency.sh` 的 G9「最新变更回填清单」检查因 `ls -d` 尾斜杠恒 VACUOUS SKIP,模板与源层镜像同步加 `cd2=${cd2%/}` 修复;A55 无内嵌断言扩为任意缩进/样式围栏(```/~~~)+ 任意勾选行(P/Bug,`-`/`*`,`[ ]`/`[x]`),并增加 P00→P12 顺序钉(仍 7 条,基线 620)。 | 目标仓 `--upgrade` 更新 DS 与 09 模板;新变更按 P00–P12 十三行回填,历史 09 条目按 §2.15 不回填。 | diff --git a/resources/methodologies/data-structures.md b/resources/methodologies/data-structures.md index 3ed0c1e..4ba9c3a 100644 --- a/resources/methodologies/data-structures.md +++ b/resources/methodologies/data-structures.md @@ -114,4 +114,4 @@ public Either analyze(String sessionId) { --- -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/methodologies/development.md b/resources/methodologies/development.md index 1a79b77..de1473e 100644 --- a/resources/methodologies/development.md +++ b/resources/methodologies/development.md @@ -109,4 +109,4 @@ --- -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/methodologies/expert-capabilities.md b/resources/methodologies/expert-capabilities.md index 4a0dbab..97bf84b 100644 --- a/resources/methodologies/expert-capabilities.md +++ b/resources/methodologies/expert-capabilities.md @@ -184,4 +184,4 @@ 学理细节以上述原著为唯一权威;本卡只定义"何时动用"(绑定关系),不复制学理内容。 -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/methodologies/project-masters.md b/resources/methodologies/project-masters.md index f3afdba..0153ee1 100644 --- a/resources/methodologies/project-masters.md +++ b/resources/methodologies/project-masters.md @@ -100,4 +100,4 @@ > 模板骨架**不得预置**回填清单的可勾选结论或"独立完整声明"以外的结论性文字——与 `03.5` 骨架同纪律:空骨架必须填,不许绕过(§2.17.1)。 -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/methodologies/review-intelligence.md b/resources/methodologies/review-intelligence.md new file mode 100644 index 0000000..18f091d --- /dev/null +++ b/resources/methodologies/review-intelligence.md @@ -0,0 +1,90 @@ +# 评审智能契约(Review Intelligence Contract) + +> 文档编号:methodologies/review-intelligence.md(方法论层;随 `bootstrap --core` 下发) +> 定位:规范 §2.2 管"谁必须评审、独立性到哪一级";本文件管"评审怎么带着项目背景、专业能力与批判性去判断,以及评审执行体/模型怎么选"。 +> 唯一权威关系:风险分级与四主体互异仍以 §0.5 / §2.1 规则 10 为唯一权威;本文件不另立等级、不替代门禁。 + +## 0. 铁律(不可协商) + +1. **生产与评审分离**:同一变更内,作者、实现、测试、评审四主体互异;评审不得与生产同会话、同执行主体,更不得自签。编排 Agent 不得兼任任一签署(§2.1 规则 10)。 +2. **评审必须带项目背景**:评审前装载项目快览、P12 领域上下文、P01–P04 相关章节、bugfix-log 同族教训、FU 台账与本变更产物;禁止脱离项目实际做模板泛评。 +3. **评审必须专业对口**:架构评审看架构先进性与覆盖面;代码评审看安全、漏洞、性能、缺陷与业务合理性;UI 变更另看 UX/UE 与可达性。能力不匹配的评审视为无效。 +4. **评审必须批判**:至少给出 1 条有证据的发现或显式达标确认,并给出 1 条可执行改进;零发现零建议 = 泛评,退回(§2.2 增量承诺)。 +5. **高成本模型必须用户确认**:AI 只能列出候选、能力与成本档位,不得自行选择高成本模型;用户确认后才可进入评审。未确认即用高成本档 = 门禁违规。 + +## 1. AI 判断原则(不写死) + +- 门禁只校验**结构、证据、独立性、成本确认**;专业结论由评审 AI 基于证据判断,禁止用固定分数/固定关键词替代判断。 +- 每个判断必须可追溯到证据:`路径:行号`、REQ/DES/TC 编号、日志片段、项目背景条目或 bugfix-log 教训。 +- 评审 AI 可以推翻引擎建议/前序结论,但必须在 `07-review-report.md` 写明「推翻对象 + 证据 + 复核主体」;无证据的推翻无效。 +- 自适应判定(测试选节、预算、换挡、是否加严)由 AI 给出判断与依据,引擎建议只作输入;判断记录落 `00-intent.md`「AI 判断记录」或 09「重要上下文」。 + +## 2. 评审派发输入契约(主 Agent 必须供给) + +派发评审子 Agent / 外部评审 CLI 时,prompt 必须包含: + +| 输入 | 必含内容 | +|---|---| +| 项目背景 | 项目速览、P12 领域域/行业约束、P01–P04 相关章节结论、系统特点与关键链路 | +| 变更上下文 | 变更号、风险等级、`ui_change`、变更文件清单、diff 摘要、受影响 REQ/DES/TC | +| 待核对产物 | 01/02/03/03.5/04/05/07/09 路径 + 行号锚点;缺陷六件套路径(bug 轨) | +| 历史教训 | bugfix-log 同族条目、06-delivery FU、既有评审结论 | +| 专业能力 | 本环节需要的专家能力(见 §3)与禁止越权范围 | +| 独立性约束 | 生产主体标识、评审主体标识、会话/模型/厂商分离要求 | +| 成本约束 | 候选模型/CLI、成本档位、用户确认状态 | + +子 Agent 超出输入清单的读盘动作须在结论中声明原因;未携带项目背景的评审直接退回。 + +## 3. 专业能力矩阵 + +| 评审环节 | 必须具备的能力 | 判断要点(非穷举) | +|---|---|---| +| 架构评审 | 强推理、系统设计、演进性 | 边界与耦合、失败模式、容量与伸缩、可观测、回滚、与既有架构范式是否一致、是否先进合理、覆盖面与深度 | +| 代码评审 | 安全、性能、缺陷分析、业务合理性 | 注入/越权/敏感数据、并发与资源、性能红线、空值/异常/边界、业务语义是否成立、可维护性 | +| UI 评审(`ui_change: true`) | UX、UE、可达性、业务合理性 | 用户任务闭环、信息架构、交互反馈、错误恢复、一致性、WCAG/可达性、真实业务场景 | +| 业务合理性终审 | 领域专家、业务现实 | 逐 UJ 质询成品行为在业务现实中是否成立;禁引本变更加工件作判定依据(§2.5 阶段 8) | +| 环节衔接评审 | 追踪矩阵、一致性 | 上游产物是否完整/自洽、下游是否具备开工条件、偏差与遗漏、返工风险 | +| 缺陷评审 | 根因分析、同族推演 | 最早未恢复失败点、排除其他假设、同族/邻接面、防回归 TC 覆盖 | + +## 4. 评审执行体与运行时适配(先探测目标仓,再选方案) + +评审开始前必须探测**目标仓被打开的 Agent 客户端运行时**(即安装本 Skill 的项目当前使用的客户端,不是编辑 Skill 的源仓客户端),再选执行方案;禁止默认"一定用子 Agent"或"一定用外部 CLI"。 + +| 探测到的目标仓运行时 | 建议评审执行方案 | +|---|---| +| `claude` / `cursor`(json-hooks) | 同客户端独立子 Agent + 独立会话;hook 负责遥测与停等检查;L2+ 换模型/厂商复核 | +| `opencode`(plugin-api) | 同客户端独立子 Agent + 独立会话;插件负责遥测;必要时用 `opencode run` 起独立评审进程 | +| `gemini` / `codex`(git+ci,无仓级 hook) | 优先:外部独立 CLI(`claude` / `codex` / `opencode` 等已安装者)起独立评审会话;次选:人类评审或 CI 独立 job;不得用同会话自评 | +| 多运行时共存 | 选能力/成本匹配的一个作评审执行体,其余仅作候选;不得同一模型既生产又评审 | +| 无可用独立执行体 | 显式阻塞:登记 FU/等待用户提供评审环境;不得降级为自评 | + +探测命令:在**目标仓根**执行 `scripts/install-hook-adapter --detect`(只读,输出 runtime/family/layers)——它读的是目标仓的 `.claude/` / `.opencode/` / `.cursor/` 等客户端配置,不是源仓。`scripts/agent-gate review-plan <变更号>` 会在目标仓根自动执行该探测,并把结果、所需专家、候选模型与成本档位一并输出。 + +## 5. 模型选择与成本确认 + +- 配置文件:仓库根 `.agent-review-models.json`(可选)。声明模型 `id/provider/cli/tier/strengths` 与角色 `min_tier`。 +- 档位语义:`economy`(低)/`standard`(中)/`deep`(高)。`deep` 或配置 `approval: true` 的模型必须用户确认。 +- 流程:`agent-gate review-plan <变更号>` 输出候选 → 用户选择 → 用户设置 `AGENT_REVIEW_MODEL_APPROVED=`(或显式批准记录)→ 再次运行 `review-plan` 写入 `.agent-state/review-plan.json`。 +- 禁止:AI 自行把档位从 economy 升到 deep;AI 以"效果更好"为由绕过用户确认;同模型同会话自评后补签名。 + +## 6. 评审输出契约 + +`07-review-report.md` 必须包含: + +1. `## 评审输入契约与专业能力`:装载了哪些项目背景/历史教训、所需能力、批判性质询清单、AI 判断依据。 +2. `## 模型选择与成本确认`:评审执行体(客户端/CLI)、模型、档位、候选清单、用户确认引用;未命中经济档写"未命中(经济档,无需确认)"。 +3. `## 独立性声明(生产 vs 评审)`:生产主体与评审主体的 `平台/模型/会话` 三元组,逐项证明分离;L2+ 证明跨模型/厂商。 +4. `## 发现处置`:逐条发现 + 严重度 + 证据 + 处置 + 来源;无发现写单行声明。 +5. `## 评审结论`:通过/有条件通过/退回;有条件通过必须列出整改项与闭环证据。 + +## 7. 反模式(一律退回) + +- 同一会话/同一模型先实现再自评,或编排 Agent 代签。 +- 只写"已按规范评审/未发现问题"而无证据、无项目背景引用。 +- 用模板勾选代替判断;用固定阈值代替专业评估。 +- 未探测运行时就直接假定执行体;未告知成本就选用高成本模型。 +- 评审结论与 05 证据、01 RTVM、09 回填清单相互矛盾而不说明。 + +--- + +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/methodologies/state-trigger-audit.md b/resources/methodologies/state-trigger-audit.md index bfd3b32..a9c2139 100644 --- a/resources/methodologies/state-trigger-audit.md +++ b/resources/methodologies/state-trigger-audit.md @@ -60,4 +60,4 @@ --- -_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.88.0_ +_本文件随 `docs/DEVELOPMENT_STANDARDS.md` 版本同步维护,当前对应规范版本:v3.92.2_ diff --git a/resources/templates/06-delivery-summary.md b/resources/templates/06-delivery-summary.md index 52ff1e6..24f0ca8 100644 --- a/resources/templates/06-delivery-summary.md +++ b/resources/templates/06-delivery-summary.md @@ -1,5 +1,7 @@ # 06 交付总结与遗留项台账(delivery-summary) +> 交付触发点:阶段 9.5(收口前);下游输入:发布评审、09 补充说明与下一变更背景 + > **定位**:规范 §2.5 **阶段 9.5** 必含产物/FU 遗留项的唯一落点(§1.1 编号主表「遗留项 (Follow-up)」行;**注意:它不在「最低文档集八类」内**——八类=01-spec/02+03/03.5/04.5/04/05/06.5/01.5)。 > **落点**:功能目录 `docs//06-delivery-summary.md`;本仓库无功能目录时落变更目录 `docs/changes/<变更号>/06-delivery-summary.md`,或仓库级 `docs/06-delivery-summary.md`。 diff --git a/resources/templates/06.5-deployment-config.md b/resources/templates/06.5-deployment-config.md index 365ae52..f1d9221 100644 --- a/resources/templates/06.5-deployment-config.md +++ b/resources/templates/06.5-deployment-config.md @@ -1,5 +1,7 @@ # 06.5 部署与配置变更记录(deployment-config) +> 交付触发点:配置/DB 变更进入发布时(阶段 9.5 前);下游输入:P08 部署总册与发布检查单 + > **定位**:规范 §1.1 最低文档集八类之一(配置变更)/§2.6.2 必含产物。 > **落点**:功能目录 `docs//06.5-deployment-config.md`;本仓库无功能目录时落变更目录 `docs/changes/<变更号>/06.5-deployment-config.md`,或仓库级 `docs/06.5-deployment-config.md`。 diff --git a/resources/templates/CLAUDE.md b/resources/templates/CLAUDE.md index 43c994c..0af4308 100644 --- a/resources/templates/CLAUDE.md +++ b/resources/templates/CLAUDE.md @@ -1 +1,3 @@ @AGENTS.md +> 交付触发点:安装器生成/升级时;下游输入:Claude Code 会话的 AGENTS.md 入口 + diff --git a/resources/templates/PULL_REQUEST_TEMPLATE.md b/resources/templates/PULL_REQUEST_TEMPLATE.md index cf7347c..50859d0 100644 --- a/resources/templates/PULL_REQUEST_TEMPLATE.md +++ b/resources/templates/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,5 @@ +> 交付触发点:发起 PR 时;下游输入:评审、CI 门禁与 P10 变更总日志 + ## 变更编号 CHG-xxx(关联 `docs//09-changelog.md`) diff --git a/resources/templates/agent-gate.sh b/resources/templates/agent-gate.sh index c2ec6df..b33af7f 100755 --- a/resources/templates/agent-gate.sh +++ b/resources/templates/agent-gate.sh @@ -4,14 +4,81 @@ # agent's natural-language claim that a check has run. set -euo pipefail +# CHG-121 (batch 0): the friction ledger used to carry only (code, timestamp). +# 1037 such rows cannot be attributed to any change, so "is this friction +# concentrated in E86/E122?" was unanswerable. Extra columns are APPENDED, so +# the metrics aggregation (`awk -F'\t' '{c[$1]++}'`) and the `^GATE-E` row pins +# keep working byte-for-byte. +friction_cid() { # current change id, "-" when unknown + local c="" f + [[ -n "${AGENT_GUARD_CHANGE:-}" ]] && { printf '%s' "$AGENT_GUARD_CHANGE"; return 0; } + f=$(git rev-parse --git-path agent-governance/active-change 2>/dev/null || true) + [[ -n "$f" && -f "$f" ]] && c=$(head -n 1 "$f" 2>/dev/null || true) + printf '%s' "${c:--}" +} +friction_sanitize() { # -> one TSV-safe cell (no tabs/newlines, <=160 chars) + printf '%s' "$1" | tr '\t\n\r' ' ' | cut -c1-160 +} +friction_append() { # + printf '%s\t%s\t%s\t%s\t%s\n' "$1" "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)" \ + "$(friction_cid)" "$2" "$(friction_sanitize "$3")" \ + >> ".agent-state/gate-friction.tsv" 2>/dev/null || true +} + +# v3.90.2 (CHG-123, P0-7): error messages are the documentation — four elements +# (expected / allowed / fix / ref) live in ONE hint table instead of being +# copy-pasted into 100+ die sites. Only failure time pays the tokens; a message +# that already carries its own four elements keeps them untouched. +gate_hint() { # -> four-element hint block + case "$1" in + GATE-E03) printf 'expected: every required artifact exists at the exact path above\nallowed: /changes//{00-intent.md,00-governance.json,00.5-communication.md}\nfix: create the missing file (scripts/new-change --risk Lx) and re-run begin\nref: standards §1.1 / §2.5 stage 1' ;; + GATE-E83) printf 'expected: 00.5 carries a non-empty user-overall-confirmation record\nallowed: a conclusion line + a status line (L0 may use the single-line exemption)\nfix: present the communication draft to the user, record the confirmation, then re-run begin\nref: standards §2.17.2d' ;; + GATE-E86) printf 'expected: the change directory placement is declared inside its own section\nallowed: "**目录落位**:BATCH-YYYYMMDD" or "独立目录(理由)"\nfix: add the placement line under the breakdown section named above, then re-run begin\nref: standards §1.1 / v3.60.0' ;; + GATE-E122) printf 'expected: 03 declares its relation to existing same-family implementations\nallowed: a "既有范式关系" section (reuse + anchor, or why different)\nfix: add that section to 03-modification-plan.md and re-run\nref: standards §2.5 stage 3 / v3.84.0' ;; + GATE-E10|GATE-E16) printf 'expected: the plan compares alternatives before choosing one\nallowed: a 候选方案/选型 table with at least two options and a verdict\nfix: add the comparison to 03-modification-plan.md, then re-run\nref: standards §2.5 stage 3' ;; + GATE-E47|GATE-E48) printf 'expected: the work lands in the directories declared by the governance file\nallowed: paths.* roots from .agent-governance.yml (defaults doc/scripts/tests/.githooks)\nfix: move the artifact to the declared root or fix paths.*, then re-run\nref: standards §1.1 / path-root clause' ;; + GATE-E60) printf 'expected: every project-master row starts with its Pxx id at line start\nallowed: "- [x] P01 ..." / "- [ ] P07 未命中"\nfix: rewrite the row with the P id first, then re-run\nref: standards §1.3' ;; + GATE-E85|GATE-E115|GATE-E117) printf 'expected: 07 carries the delivery shape rows the checker names\nallowed: signature with platform/model/task id; findings table >=5 columns; source column values from the enum\nfix: patch 07-review-report.md exactly at the named row, then re-run\nref: standards §2.1.7 / §2.5 stage 8' ;; + GATE-E125) printf 'expected: every source-path change is accounted for by an active change or a same-day defect batch\nallowed: begin a change first, or set AGENT_GUARD_ALLOW_UNACCOUNTED=1 with a 09 justification\nfix: run scripts/agent-gate begin (or register the bypass in 09), then re-run\nref: standards §2.17.2b signal 3' ;; + GATE-E04|GATE-E05|GATE-E06|GATE-E07|GATE-E08|GATE-E09|GATE-E10|GATE-E11|GATE-E12|GATE-E13|GATE-E14|GATE-E15|GATE-E16|GATE-E17|GATE-E80|GATE-E84|GATE-E122) printf 'expected: the named artifact carries its A-layer section/numbering\nallowed: the section keywords or REQ-/DES-/TC-/SC- numbering named above\nfix: add that section/numbering to the named artifact, then re-run\nref: standards §2.5 stage 1-4 / §2.2' ;; + GATE-E19|GATE-E20|GATE-E21|GATE-E22|GATE-E23) printf 'expected: every artifact carries a script-generated provenance block\nallowed: with author/committer/commit/host/platform/generated_at\nfix: scripts/stamp-provenance.sh --all (never hand-write), then re-run\nref: standards §1.1 / §2.15' ;; + GATE-E18|GATE-E29|GATE-E30|GATE-E31|GATE-E32|GATE-E33|GATE-E34|GATE-E35|GATE-E88) printf 'expected: real, distinct execution subjects (no placeholders)\nallowed: platform/model + session-or-task id; L2/L3 four subjects pairwise distinct\nfix: edit 00-governance.json owners; keep spec_author != review_owner at minimum\nref: standards §2.1 rule 10 / §0.5.2' ;; + GATE-E25|GATE-E26|GATE-E27|GATE-E28) printf 'expected: one governance record per change id with a valid risk level\nallowed: change_id == dir id; risk_level L0|L1|L2|L3; batches only L0/L1\nfix: fix 00-governance.json (or move an L2/L3 change to its own directory)\nref: standards §0.5.1 / §1.1' ;; + GATE-E36|GATE-E37|GATE-E38) printf 'expected: L3 carries human release authorization (three fields)\nallowed: release_authorized_by / _at / _evidence, all non-empty\nfix: obtain the human authorization, record the three fields, re-run\nref: standards §2.7 / §0.5.2' ;; + GATE-E39|GATE-E40|GATE-E41|GATE-E42|GATE-E81|GATE-E87) printf 'expected: bug_ref points at a complete, uniquely anchored defect group\nallowed: BUG-xxx under bugs/ (standalone or BATCH-YYYYMMDD/ with a ## BUG anchor)\nfix: fix the id, add the missing six-file piece, or de-duplicate the batch, then re-run\nref: standards §2.5 stage 6 / §1.1' ;; + GATE-E44|GATE-E45|GATE-E46|GATE-E47|GATE-E48|GATE-E49|GATE-E52|GATE-E59|GATE-E60|GATE-E61) printf 'expected: the delivery document set is complete and filled (no template markers)\nallowed: real content or an explicit 未命中(理由) declaration per row\nfix: fill/remove markers in the named 04.5/05/09/Pxx row, then re-run stop\nref: standards §1.1 / §1.3 / §2.5 stage 7-8' ;; + GATE-E50|GATE-E51) printf 'expected: 09 carries ReAct Observations and every cited REQ is backfilled\nallowed: "- **Observation**: …" and the REQ ids present in 01.5-rtvm-matrix.md\nfix: add the Observation / backfill the REQ row, then re-run\nref: standards §2.16.2 / §4' ;; + GATE-E53|GATE-E54|GATE-E55|GATE-E57|GATE-E58) printf 'expected: a defect group lives once, in one legal layout\nallowed: standalone bugs// or one BATCH-YYYYMMDD/ with its anchor\nfix: merge/remove the duplicate; independent layout needs AGENT_GUARD_ALLOW_INDEPENDENT=1 + 09 reason\nref: standards §1.1' ;; + GATE-E62|GATE-E63) printf 'expected: all thirteen project masters exist under docs/project/\nallowed: P00..P12 with the documented names\nfix: copy /templates/project/* then fill, or set AGENT_GUARD_ALLOW_NO_PROJECT_MASTERS=1 with a 09 reason\nref: standards §1.3' ;; + GATE-E64|GATE-E118) printf 'expected: the configured verification_command passes\nallowed: a command that exits 0 (see .agent-governance.yml ci.verification_command)\nfix: run it yourself, fix the failure, or correct the command; re-run stop\nref: standards §2.17.4 / §2.13' ;; + GATE-E66|GATE-E125) printf 'expected: every source-path change is accounted for by an active change\nallowed: begin first (or a same-day defect batch); bypass only with a 09 justification\nfix: create the change artifacts and run begin, then re-run staged/stop\nref: standards §2.17.2b' ;; + GATE-E67|GATE-E68) printf 'expected: the commit message names its change id\nallowed: "type(scope): summary (CHG-xxx)" (merge/revert/docs-only exempt)\nfix: amend the message file or the commit message, then re-run\nref: standards §4 / commit-msg gate' ;; + GATE-E71|GATE-E72) printf 'expected: a closed change is never reopened\nallowed: a NEW change id (one change = one document set)\nfix: create the next change id and run begin on it\nref: standards §2.15 rule 4' ;; + GATE-E73|GATE-E74|GATE-E75|GATE-E89|GATE-E112) printf 'expected: session hygiene holds (batch placement / water level / red list / shift)\nallowed: join BATCH-YYYYMMDD for L0/L1; write handoff.md + a shift declaration\nfix: follow the named action; bypass keys need a 09「重要上下文」 entry\nref: standards §1.1 / §2.9.6' ;; + GATE-E76|GATE-E77|GATE-E78|GATE-E79|GATE-E69|GATE-E120) printf 'expected: a valid command form\nallowed: see scripts/agent-gate help (begin/preflight/--stage/metrics/plan …)\nfix: correct the arguments; scaffold needs a fresh empty change id\nref: standards §2.17.1' ;; + GATE-E82|GATE-E85|GATE-E96|GATE-E98|GATE-E114|GATE-E115|GATE-E116|GATE-E117|GATE-E123|GATE-E124) printf 'expected: 07 carries signatures, dispositions and the required verdict sections\nallowed: platform / model / task-id signatures; ≥5-column finding table; 来源 = 本次引入|既有存量\nfix: patch the named 07 section/row, then re-run\nref: standards §2.1.7 / §2.5 stage 8' ;; + GATE-E83|GATE-E86) printf 'expected: communication-first and directory-placement declarations\nallowed: 00.5 confirmation record; "- **目录落位**:BATCH-… | 独立目录(理由)"\nfix: add the record/line before generating artifacts, then re-run begin\nref: standards §2.17.2d / §1.1' ;; + GATE-E90|GATE-E92|GATE-E93|GATE-E94|GATE-E95|GATE-E97|GATE-E99|GATE-E101|GATE-E102|GATE-E103|GATE-E104|GATE-E106|GATE-E109) printf 'expected: UI / behaviour-inventory conditional evidence is present\nallowed: UJ anchors, 03.6-ui-spec, E2E cases, runtime evidence rows, waiver lines\nfix: add the conditional artifact/evidence the message names, or declare the waiver\nref: standards §2.5 stage 1-4 / v3.67.0' ;; + GATE-E126|GATE-E127|GATE-E128|GATE-E129|GATE-E130) printf 'expected: the stage-gate preconditions hold for this change\nallowed: required artifacts + confirmation + one non-empty reviews/Pxx.review.md per claim\nfix: backfill the named stage artifacts, then re-run the same stage command\nref: standards §2.5 / §2.17.2d' ;; + GATE-E132|GATE-E136|GATE-E138|GATE-E139|GATE-E140|GATE-E141|GATE-E149) printf 'expected: a valid read-back subcommand form\nallowed: cost-line|plan|baseline|tc-index|resume|review-plan [flags]\nfix: pass an existing change id and a documented flag, then re-run\nref: standards §2.17 / CHG-126/127' ;; + *) printf 'expected: the condition named on the line above holds\nallowed: see the clause in ref; the command is idempotent and safe to re-run\nfix: address the named condition, then run the same command again\nref: standards §2.17 / this change 09-changelog' ;; + esac +} + die() { echo "agent-gate: $*" >&2 + # v3.90.2 (CHG-123, P0-7): append the four elements unless the message already + # carries them (new codes like E132/E134 do). Zero standing cost: only a + # FAILING gate prints these lines. + local _code4="${1%%:*}" + case "$_code4" in + GATE-E[0-9]*) case "$*" in *expected:*) : ;; *) gate_hint "$_code4" >&2 ;; esac ;; + esac # v3.43.0 (REQ-960): gate 摩擦事件账(append-only TSV,metrics 侧聚合)。 # fail-open:缺 .agent-state 或写失败不影响拒绝语义;TSV 而非 JSON——bash 零依赖。 local _code="${1%%:*}" _re='^GATE-E[0-9]+$' if [[ -d ".agent-state" && "$_code" =~ $_re ]]; then - printf '%s\t%s\n' "$_code" "$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)" \ - >> ".agent-state/gate-friction.tsv" 2>/dev/null || true + friction_append "$_code" DIE "$*" fi exit 2 } @@ -417,25 +484,29 @@ scaffold_body() { # esac case "$doc" in 00-intent.md) - printf '# %s Intent\n\n- **目录落位**:%s\n- **来源**:\n- **范围**:① ② \n- **不做**:\n\n### 预期结果\n\n- \n\n### 开放问题\n\n- \n' "$id" "$placement" ;; + printf '# %s Intent\n\n> 交付触发点:变更立项时(00.5 确认前);下游输入:00.5 沟通稿与 01-spec\n> 背景输入:待填(已读 P12 产品上下文 / P01 需求册 / 相关历史 09 教训)\n\n- **目录落位**:%s\n- **来源**:\n- **范围**:① ② \n- **不做**:\n\n### 预期结果\n\n- \n\n### 开放问题\n\n- \n' "$id" "$placement" ;; 00.5-communication.md) - printf '# %s Communication(00.5)\n\n### 影响范围\n\n\n\n### 风险\n\n\n\n### 候选方案与取舍\n\n- 方案 A(采纳):\n- 方案 B(否):\n\n### 测试思路\n\n- \n\n### 用户整体确认记录\n\n- \n- 确认状态:待确认\n' "$id" ;; + printf '# %s Communication(00.5)\n\n> 交付触发点:Round-1 沟通完成、用户整体确认前;下游输入:01-spec 起的全部产物正文\n> 背景输入:待填(00-intent + 目标功能目录既有文档 + P01/P12)\n\n### 影响范围\n\n\n\n### 风险\n\n\n\n### 候选方案与取舍\n\n- 方案 A(采纳):\n- 方案 B(否):\n\n### 测试思路\n\n- \n\n### 用户整体确认记录\n\n- \n- 确认状态:待确认\n' "$id" ;; 00-governance.json) - printf '{"change_id": "%s", "change_uid": "%s", "risk_level": "%s", "spec_author": "FILL-spec-author(人/代理,须≠review_owner)", "implementation_owner": "FILL-implementation-owner", "test_owner": "FILL-test-owner", "review_owner": "FILL-review-owner(须独立,≠spec_author)", "bug_ref": "", "release_authorized_by": "", "release_authorized_at": "", "release_authorization_evidence": ""}\n' "$id" "$cuid" "$risk" ;; + printf '{"change_id": "%s", "change_uid": "%s", "risk_level": "%s", "change_type": "feature", "spec_author": "FILL-spec-author(人/代理,须≠review_owner)", "implementation_owner": "FILL-implementation-owner", "test_owner": "FILL-test-owner", "review_owner": "FILL-review-owner(须独立,≠spec_author)", "bug_ref": "", "release_authorized_by": "", "release_authorized_at": "", "release_authorization_evidence": ""}\n' "$id" "$cuid" "$risk" ;; 01-spec.md) - printf '# %s Spec\n\n## %s <标题:一句话>\n\n- **DES**:%s\n- **规则**:\n- **理由**:\n- **验收**:\n' "$id" "$nxt_req" "$nxt_des" ;; + printf '# %s Spec\n\n> 交付触发点:spec 阶段交付;下游输入:design(02/03)与 testplan(04)\n> 背景输入:待填(已读 P01 需求册 / P12 业务上下文,写结论与依据)\n\n## %s <标题:一句话>\n\n- **DES**:%s\n- **规则**:\n- **理由**:\n- **验收**:\n' "$id" "$nxt_req" "$nxt_des" ;; 02-code-impact-analysis.md) - printf '# %s Code Impact Analysis\n\n### 改动面\n\n| 文件 | 层 | 影响 |\n|---|---|---|\n| | | |\n\n### 业务影响\n\n\n\n### 历史相似检索\n\n- 检索词:——命中:\n\n### 风险 + printf '# %s Code Impact Analysis\n\n> 交付触发点:design 阶段交付;下游输入:03(选型)与 04(测试计划)\n> 背景输入:待填(01-spec 的 REQ-xxx + P12 业务上下文)\n\n### 改动面\n\n| 文件 | 层 | 影响 |\n|---|---|---|\n| | | |\n\n### 业务影响\n\n\n\n### 历史相似检索\n\n- 检索词:——命中:\n\n### 风险 ### 延伸发现\n\n- \n\n### 回滚策略\n\n- \n' "$id" ;; 03-modification-plan.md) - printf '# %s Modification Plan\n\n### 改动清单\n\n| # | 文件 | 改动 | REQ |\n|---|---|---|---|\n| 1 | | | %s |\n\n### 设计决策\n\n- **%s <名>**:;备选 被否——\n\n### 既有范式关系(v3.84.0,gate E122)\n\n- \n\n### 顺序\n\n1. \n' "$id" "$nxt_req" "$nxt_des" ;; + printf '# %s Modification Plan\n\n> 交付触发点:design 阶段交付;下游输入:03.5(任务拆解)与 04(测试计划)\n> 背景输入:待填(01-spec 的 REQ-xxx + 02 的业务影响/风险/回滚)\n\n### 改动清单\n\n| # | 文件 | 改动 | REQ |\n|---|---|---|---|\n| 1 | | | %s |\n\n### 设计决策\n\n- **%s <名>**:;备选 被否——\n\n### 既有范式关系(v3.84.0,gate E122)\n\n- \n\n### 顺序\n\n1. \n' "$id" "$nxt_req" "$nxt_des" ;; 03.5-tasks.md) - printf '# %s Tasks\n\n依赖:。无外部阻塞。\n\n里程碑:M1=。\n\n评审输入:\n' "$id" ;; + printf '# %s Tasks\n\n> 交付触发点:design 阶段交付;下游输入:开发实施顺序与 04(测试计划)\n> 背景输入:待填(01-spec + 02 + 03 的 DES-xxx)\n\n依赖:。无外部阻塞。\n\n里程碑:M1=。\n\n评审输入:\n' "$id" ;; + 01.5-rtvm-matrix.md) + # v3.91.5: the RTVM is scaffolded (the matrix is a contract artifact), but + # placeholders do NOT satisfy the stage gates — each stage must fill its row. + printf '# %s RTVM 矩阵(四维闭环总表)\n\n> 交付触发点:随阶段交付逐维回填(spec=REQ/design=DES+tasks=T/testplan=TC);下游输入:阶段门与收口审计\n> 背景输入:待填(01-spec 的 REQ 行 + P01 需求册)\n\n| REQ | 需求简述 | DES | 核心设计方案 | TASK | CHG/位置 | TC | 测试方法 / 脚本 | 验证状态 |\n|---|---|---|---|---|---|---|---|---|\n| | | | | | / | | | |\n\n> 回填时机(v3.91.5 机检):spec 交付填 REQ;design 交付填 DES;tasks 交付填 TASK;testplan 交付填 TC。后补即被阶段门拒绝。\n' "$id" ;; 04-test-scripts.md) - printf '# %s Test Scripts\n\n场景:%s 。\n\n| 编号 | TC | SC | 覆盖维度 | 命令 | 期望 | REQ | 来源 |\n|---|---|---|---|---|---|---|---|\n| T1 | %s | %s | | | | %s | 本次引入 |\n\n## TC 落点清单(REQ-1091,v3.71.0)\n\n- %s → \n' "$id" "$nxt_sc" "$nxt_tc" "$nxt_sc" "$nxt_req" "$nxt_tc" ;; + printf '# %s Test Scripts\n\n> 交付触发点:testplan 阶段交付;下游输入:开发(TDD)与 05/07\n> 背景输入:待填(02 业务影响 + 03 的 DES-xxx + 01.5 的 DES/T 行)\n\n场景:%s 。\n\n| 编号 | TC | SC | 覆盖维度 | 命令 | 期望 | REQ | 来源 |\n|---|---|---|---|---|---|---|---|\n| T1 | %s | %s | | | | %s | 本次引入 |\n\n## TC 落点清单(REQ-1091,v3.71.0)\n\n- %s → \n' "$id" "$nxt_sc" "$nxt_tc" "$nxt_sc" "$nxt_req" "$nxt_tc" ;; esac } @@ -453,7 +524,7 @@ scaffold_change() { # — generate the eight begin-stage artifacts fi mkdir -p "$d" local created=0 appended=0 - for doc in 00-intent.md 00-governance.json 00.5-communication.md 01-spec.md 02-code-impact-analysis.md 03-modification-plan.md 03.5-tasks.md 04-test-scripts.md; do + for doc in 00-intent.md 00-governance.json 00.5-communication.md 01-spec.md 01.5-rtvm-matrix.md 02-code-impact-analysis.md 03-modification-plan.md 03.5-tasks.md 04-test-scripts.md; do target="$d/$doc" body=$(scaffold_body "$doc" "$id" "$risk" "$placement") t121="" @@ -602,7 +673,85 @@ is_code_path() { [[ "$path" =~ \.(c|cc|cpp|cs|go|java|js|jsx|kt|kts|php|py|rb|rs|scala|sh|sql|swift|ts|tsx|vue)$ ]] } -# v3.55.0 (CHG-068): single source for the 延伸发现/历史相似检索 check family — +# v3.89.0 (CHG-117, REQ-1199/1200, DES-1956): unaccounted source-change gate — +# signal class ③ of §2.17.2b (three signal classes). A source-path diff with +# NO active change, NO same-day defect batch, and a non-docs-only face is +# unaccounted work (修完不留痕). The exclusion face is is_code_path above — +# ONE source for "what is source" (session-gate.sh and the G16 audit lane keep +# byte-compatible replicas with a pinned sync duty; changing one side obliges +# the other two). +# Exemption ladder (fail-closed, never silent): +# 1. active-change pointer present (git-path, same resolution as stop); +# 2. same-day defect batch WITH its identity piece (/BATCH-/ +# 01-diagnosis.md carrying at least one `## BUG-` anchor) — an empty +# directory is not a batch (independent review F2); full anchor +# completeness stays with G8 / the existing group validators; +# 3. AGENT_GUARD_ALLOW_UNACCOUNTED=1 — same ladder as ALLOW_NO_SHIFT / +# ALLOW_OVER_RED: the bypass prints a WARN line and appends a +# GATE-E125BYPASS row to the friction ledger; the justification is owed +# to 09「重要上下文」. +# SKIP_VERIFY judgment (DES-1958): this check NEVER consults +# AGENT_GUARD_SKIP_VERIFY — that env only ever waived the verification_command +# run (v3.28.0) and keeps meaning exactly that. session-gate idle passes the +# internal marker AGENT_GUARD_SKIP_VERIFY_CONTEXT=idle (parent-process +# injection only) purely as a stated contract that the unaccounted check must +# run regardless of any skip semantics; setting both variables by hand has NO +# bypass effect — the only bypass keys are the three exemptions above. +day_bug_batch_present() { # -> 0 when /BATCH-/01-diagnosis.md carries a BUG anchor + local d + d="$bugs_root/BATCH-$(date -u +%Y%m%d)/01-diagnosis.md" + [[ -s "$d" ]] && grep -qE '^##[[:space:]]+BUG-[0-9A-Za-z_-]+' "$d" 2>/dev/null +} + +unaccounted_exempt() { # -> 0 when the diff face is accounted for + local af + af=$(git rev-parse --git-path agent-governance/active-change 2>/dev/null || true) + [[ -n "$af" && -s "$af" ]] && return 0 + day_bug_batch_present +} + +validate_unaccounted_changes() { # + local mode="$1" files f hits="" + case "$mode" in + staged) files=$(git diff --cached --name-only --diff-filter=ACMRD 2>/dev/null || true) ;; + # deletions included: removing source with no account is still 修完不留痕 + worktree) + # stop-lane merged face: porcelain covers staged + unstaged + untracked + # (-uall lists untracked DIRECTORY CONTENTS individually — the collapsed + # `?? dir/` form would hide a fresh source file inside a new directory). + # Cut the XY status pair, keep the rename's NEW path; quoted paths are + # unquoted best-effort (core.quotePath names stay an accepted gap — the + # same gap changed_files has always had). + files=$(git status --porcelain -uall 2>/dev/null | cut -c4- | sed -E 's/.* -> //; s/^"//; s/"$//' || true) ;; + *) return 0 ;; + esac + while IFS= read -r f; do + [[ -n "$f" ]] || continue + is_code_path "$f" && hits+="$f"$'\n' + done <<< "$files" + [[ -n "$hits" ]] || return 0 + unaccounted_exempt && return 0 + if [[ "${AGENT_GUARD_ALLOW_UNACCOUNTED:-}" == "1" ]]; then + echo "agent-gate: WARN — AGENT_GUARD_ALLOW_UNACCOUNTED=1 bypassed the unaccounted source-change check; the justification is owed to 09「重要上下文」(standards §2.17.2b, v3.89.0 CHG-117)" >&2 + friction_append "GATE-E125BYPASS" BYPASS "AGENT_GUARD_ALLOW_UNACCOUNTED=1" + return 0 + fi + die "GATE-E125: source-path changes with no active change and no same-day defect batch ($mode face: $(printf '%s' "$hits" | head -3 | tr '\n' ' ')...) — standards §2.17.2b signal ③, three options: ① open the change (scripts/agent-gate begin / new-change scaffold), ② bind the defect batch (bug-autointent / same-day /BATCH-/ anchors), ③ skip only with AGENT_GUARD_ALLOW_UNACCOUNTED=1 recorded in 09「重要上下文」 (v3.89.0 CHG-117)" +} + +# v3.90.3 (CHG-125, P2-3): L2/L3 may not accumulate code evidence before the +# user's overall confirmation is on disk (the §2.17.2d gate extended to staged). +validate_confirmed_work() { # + local cid + cid=$(active_change_quiet) + [[ -n "$cid" ]] || return 0 + case "$1" in + staged) confirm_required_check "$cid" E129 ;; + preflight) confirm_required_check "$cid" E130 ;; + esac +} + +# v3.67.0 (CHG-090, REQ-1056): single source for the 延伸发现/历史相似检索 check family — # a section heading (bare substring; declaration lines self-carry it) OR an # explicit 未命中(…检索…) declaration line. Callers own their die messages. require_section_or_decl() { # [decl_regex] @@ -703,6 +852,201 @@ validate_dimensional_begin() { # return 0 } +# v3.89.0 (CHG-117, DES-1960): E113 TC-landing extracted from +# validate_dimensional_stop — same scan, same single die literal (T41), two +# callers: the stop lane (require-section=0 keeps the legacy soft warn for 04 +# files without the section) and the testplan stage gate (require-section=1 +# demands the section before source edits). +tc_landing_check() { # <04-file> + local f="$1" req="$2" tcl tc_path tc_id e113 + if grep -q '^## TC 落点清单' "$f" 2>/dev/null; then + while IFS= read -r tcl; do + [[ -n "$tcl" ]] || continue + case "$tcl" in *"自动化"*) ;; *) continue ;; esac + tc_id=$(printf '%s\n' "$tcl" | sed -E 's/^[[:space:]]*-[[:space:]]*(TC-[A-Za-z0-9_-]+)[[:space:]]*:[[:space:]].*/\1/') + tc_path="${tcl#*:}"; tc_path="${tc_path%%(*}"; tc_path="${tc_path%%(*}" + tc_path="$(printf '%s' "$tc_path" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')" + e113="" + if [[ -z "$tc_path" || ! -f "$tc_path" ]]; then + e113="TC landing '$tc_id' points at '$tc_path' which does not exist — every automated TC must land an executable file (standards §2.5 stage 7)" + elif ! grep -qE 'describe\(|\bit\(|\btest\(|expect\(|assert|def test_|@Test' "$tc_path" 2>/dev/null; then + e113="'$tc_id' landing '$tc_path' carries no recognizable test assertion marker" + fi + [[ -z "$e113" ]] \ + || die "GATE-E113: $e113 (v3.71.0; escape review: 人工-typed rows are skipped)" + done < <(sed -n '/^## TC 落点清单/,/^## /p' "$f" | grep -E '^[[:space:]]*-[[:space:]]*TC-') + elif [[ "$req" == "1" ]]; then + stage_gate_fail "G-测试门 (testplan)" \ + "$f lacks the 「TC 落点清单」 section" \ + "04 用例矩阵 (TC-xxx + 覆盖维度) plus a TC 落点清单 (every automated TC → real executable test file); then agent-gate --stage testplan" + else + echo "agent-gate: TC landing soft warning: $f has no 「TC 落点清单」 section (legacy shape passes unblocked; new changes must land TC→file mappings, REQ-1091, v3.71.0)" >&2 + fi +} + +# v3.89.0 (CHG-117, REQ-1202, DES-1960): stateless stage gates. `--stage +# spec|design|testplan` re-derives stage completion from disk anchors only — +# no stage-state file, idempotent and re-entrant, so the legacy "all eight +# artifacts before begin" habit passes every gate for free. begin narrows to +# the ENTRY gate (00-intent + 00-governance.json + 00.5 confirmation); the +# 01-04 checks this used to duplicate at begin live here, and the delivery +# face (staged/stop/ci) keeps its full artifact checks unchanged — 收窄≠弱化. +# AGENT_GUARD_STAGE_GATES=0: begin restores the legacy full eight-artifact +# check and the session-gate check-mode stage predicates skip; an explicit +# `--stage ` invocation still validates (opt-in action). +stage_gates_enabled() { [[ "${AGENT_GUARD_STAGE_GATES:-1}" != "0" ]]; } + +stage_gate_fail() { # — single E126 die site (T41) + die "GATE-E126: stage gate $1 not satisfied: $2 — backfill $3, then re-run (stateless/idempotent; standards §2.16.2, §2.17; v3.89.0 CHG-117; AGENT_GUARD_STAGE_GATES=0 restores the legacy full begin check)" +} + +unknown_stage() { # — single E78 die site (T41) + die "GATE-E78: unknown stage '$1'" +} + +req_seq_gaps() { # -> gap count inside the file's own min..max + # Definition-form rows only (G2 audit audit-docs-consistency.sh DEF_RE, same + # rule and rationale: prose references must not inflate the numbering set). + local re nums + re=$(printf '^#{1,6}[[:space:]]*%s-[0-9]+|^\\|[[:space:]]*`?%s-[0-9]+`?[[:space:]]*\\||^-[[:space:]]*`?%s-[0-9]+' "$2" "$2" "$2") + nums=$(grep -ohE "$re" "$1" 2>/dev/null \ + | grep -oE '[0-9]+' | awk '{printf "%d\n", $1}' | sort -n | uniq || true) + [[ -z "$nums" ]] && { printf 0; return; } + printf '%s\n' "$nums" \ + | awk -v mn="$(printf '%s\n' "$nums" | head -1)" -v mx="$(printf '%s\n' "$nums" | tail -1)" \ + '{a[$1+0]=1} END{n=0; for(i=mn;i<=mx;i++) if(!(i in a)) n++; print n}' +} + +entry_gate_docs_present() { # — narrowed begin face (v3.89.0, DES-1960) + # One die site per code (T41): the entry subset is the SAME loop and the + # SAME content checks as the legacy full gate, just scoped to three docs. + required_docs_present "$1" entry +} + +# v3.91.5 (2026-10-27 user directive): stage delivery, not post-hoc backfill. +# A stage gate may only open when the PREVIOUS stage's deliverables are actually +# on disk — including the RTVM row it owes. Placeholder shapes () do +# not count; only numbered ids do. +rtvm_has() { # -> 0 when a numbered id of that dimension exists + local f="$1" dim="$2" + [[ -s "$f" ]] || return 1 + case "$dim" in + REQ) grep -qE '(^|[|`[:space:]])`?REQ-[0-9]+' "$f" 2>/dev/null ;; + DES) grep -qE '(^|[|`[:space:]])`?DES-[0-9]+' "$f" 2>/dev/null ;; + T) grep -qE '(^|[|`[:space:]])`?T-[0-9]+([^A-Za-z0-9]|$)' "$f" 2>/dev/null ;; + TC) grep -qE '(^|[|`[:space:]])`?TC-[0-9]+' "$f" 2>/dev/null ;; + *) return 0 ;; + esac +} + +# v3.91.6 (CHG-127, user directive 2026-10-27): every artifact declares BOTH its +# delivery trigger (when it is produced + which stage consumes it) and its +# background input (which upstream artifact + business/requirement context was +# actually read before the stage started). PMP chain rule — the next stage's +# input IS the previous stage's output — is enforced here, not narrated. +marker_text() { #