agentic-flow-kit 0.8.0 → 0.9.0

package/templates/_agents/scripts/check-metric-claims.mjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+// check-metric-claims — 检查 16「量化断言指标签名对账」实现（2026-09-28 claim-exceeds-fix 引入；
+// 2026-09-28 check16-inline-debt 自 check-loop.mjs 原内联块迁出为独立模块——检查 16 自带三层子结构
+// （登记表解析 / 装户取数器载入 / 签名扫描），内联时与检查 1-15 的主扫描流搅在同一文件；
+// 迁出后 check-loop 只留判据摘要 + ctx 组装 + 调用，判据语义 / 消息文案 / exit 语义零变化）。
+// 判据（与 check-loop.mjs 头部检查项清单 16 同源）：
+//   活跃态文档（draft/approved/open）中的 `{{指标名}}`（小写点分）签名须替换为实时值，留签名=未回填=warning；
+//   只查显式签名、不全文扫数字（历史叙述假阳性恒 0）；未登记签名 / 取数器缺失 → fail-loud 出账；
+//   登记表缺失 → 静默跳过（未启用该检查的装户零噪声）；装户自有指标走 .agents/metric-derivers.cjs（CJS 契约，内置优先）。
+// 契约：runCheck16(ctx) 由 check-loop.mjs 调用（调用位置在检查 15 之后——warnings 按插入序输出，
+//   位置变化会改变输出行序）；ctx 显式携带本检查引用的外层符号（以代码实际引用集为准）：
+//   ROOT / ENUMS / docFiles / fmGet / inSet / isTracked / linesOf / readdirOrNull / warnings。
+//   不隐式读 check-loop 闭包——迁出前后行为逐字节一致（check-loop 全量输出 diff 基线验证）。
+//   docFiles / isTracked 使扫描面与取数面和检查 1-15 同口径（tracked 过滤链单源定义于 check-loop.mjs docFiles）。
+// 本文件只 import node:* 内置模块（无同目录依赖；先例：check-loop.mjs import 同目录 workflow-enums.mjs）。
+// 测试：node templates/_agents/scripts/check-loop.test.mjs（黑盒跑整脚本，场景组「检查 16」）
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export function runCheck16(ctx) {
+  const { ROOT, ENUMS, docFiles, fmGet, inSet, isTracked, linesOf, readdirOrNull, warnings } = ctx;
+  const mcFile = path.join(ROOT, '.agents', 'metric-claims.txt');
+  if (fs.existsSync(mcFile)) {
+    const ledgerLines = () => {
+      const p = path.join(ROOT, '.agents', 'confirmations.jsonl');
+      const ls = (linesOf(p) || []).filter((l) => l.trim());
+      return { total: ls.length, withBatch: ls.filter((l) => /"batch"/.test(l)).length };
+    };
+    // 内置取数器：全部本地确定性、零网络。**装户零配置即用**（不依赖任何装户文件）。
+    // **取数与扫描面同口径（复核 P2；2026-09-28 check16-inline-debt 起单源化）**：文档扫描与取数统计
+    //   统一走 ctx.docFiles()——过滤链（.md ∧ 数字前缀 ∧ tracked）全仓唯一定义于 check-loop.mjs 的
+    //   docFiles，本文件不再自持 countDocs 复刻。首版独立 readdir 数盘面曾把并行会话的**未跟踪**新档
+    //   算进取数（盘面 60 / HEAD 59），令「签名填对了」却是别的读者复现不出的数；单源后
+    //   「扫描看得到的文档集 == 取数统计的文档集」由构造保证，口径漂移在编译期即不可能。
+    const derivers = {
+      'ledger.lines': () => ledgerLines().total,
+      'ledger.linesWithBatch': () => ledgerLines().withBatch,
+      'ledger.linesWithoutBatch': () => ledgerLines().total - ledgerLines().withBatch,
+      'docs.count.intents': () => docFiles('intents').length,
+      'docs.count.specs': () => docFiles('specs').length,
+      'docs.count.plans': () => docFiles('plans').length,
+      'docs.count.incidents': () => docFiles('incidents').length,
+      'docs.count.all': () => docFiles('intents').length + docFiles('specs').length + docFiles('plans').length + docFiles('incidents').length,
+    };
+    // ---- 装户侧取数器（2026-09-28 adopter-derivers；修「owned 登记表配 managed 取数器」P1）----
+    // 背景：登记表是 owned（装户自增指标），取数器却曾硬编码在本文件（managed）——装户一新增指标
+    // 就报「无取数器」，唯一出路是改本文件，而那是 managed：sync 永久报「本地已改」+ doctor WARN
+    // + 本脚本因供应链防线**跳过执行**（门禁静默停摆）。故改为分层：
+    //   ① 内置优先（行为与今完全一致，装户零配置可用）；② 未命中则查装户模块 `.agents/metric-derivers.cjs`
+    // **必须是 CJS（`.cjs` + module.exports）**（2026-09-28 跨版本实测修正）：
+    //   首版约定 `.mjs` 并用 `createRequire` 载入，在 Node v24.12 上实测可用（**故本机没暴露问题**）；
+    //   但跨版本实测（真下 18.20.5 / 20.18.0 / 22.11.0 二进制跑）**三者全部 `ERR_REQUIRE_ESM`**——
+    //   `require(esm)` 只在 Node ≥20.19 / ≥22.12 默认可用，Node 18 从未支持。而本仓 engines 写
+    //   `>=18.0.0`、CI 矩阵跑 18/22 → **装户取数功能在 CI 目标版本上完全不可用**（fail-loud 正常、
+    //   不崩，但功能不工作）。故改用 CJS：`createRequire` 载入 `.cjs` 在 18/20/22/24 全线可用，
+    //   且**仍是同步**（无须把本脚本改成 async 主线）。契约要求同步函数也与本检查「零网络、
+    //   本地确定性」的前提一致（异步的唯一真实收益是网络/并发 IO，此处都不允许）。
+    // **失败一律响亮、绝不静默降级**（沿 claim-exceeds-fix「假绿比红危险」与本检查自身语法错教训）：
+    // 若载入失败就「只用内置指标」，装户会看到「引用了 my.metric → 未登记」，看起来像**自己忘了登记**，
+    // 而真因是模块坏了——他会去 registry 反复核对，问题永远查不到。故载入/调用失败均出明确 WARN。
+    const adopterModRel = '.agents/metric-derivers.cjs';
+    // 旧路径（首版 .mjs）：若存在则**明确提示已改用 .cjs**，避免装户对着「无取数器」查不出所以然
+    const adopterLegacyRel = '.agents/metric-derivers.mjs';
+    let adopterState = null; // { ok:true, derivers } | { ok:false, errors:[...] } —— 懒载入 + 单次运行内缓存
+    const loadAdopterDerivers = () => {
+      if (adopterState) return adopterState;
+      const abs = path.join(ROOT, adopterModRel);
+      if (!fs.existsSync(abs)) {
+        // 常见误写：仍用首版的 .mjs 路径 → 给出可操作的迁移指引（而非任其对着「无取数器」猜）
+        if (fs.existsSync(path.join(ROOT, adopterLegacyRel))) {
+          adopterState = {
+            ok: false,
+            errors: [`${adopterModRel} 不存在，但发现旧版路径 ${adopterLegacyRel}——该路径已于 2026-09-28 弃用（\`require(esm)\` 在 Node 18/22 不可用，实测 ERR_REQUIRE_ESM）。请改名为 ${adopterModRel} 并把写法改为 CommonJS：\`module.exports = { derivers: { ... } }\``],
+          };
+          return adopterState;
+        }
+        adopterState = { ok: true, derivers: {} }; // 缺失=正常态，零告警
+        return adopterState;
+      }
+      try {
+        const req = createRequire(import.meta.url);
+        const mod = req(abs);
+        // CJS / ESM 双兼容取导出：CJS 走 module.exports.derivers；若装户误用了 ESM 语法而环境恰好
+        // 支持（新 Node 的 require(esm)），default 里也可能挂 derivers——两处都认，避免假阴性。
+        const d = (mod && mod.derivers) || (mod && mod.default && mod.default.derivers);
+        if (!d || typeof d !== 'object' || Array.isArray(d)) {
+          adopterState = { ok: false, errors: [`${adopterModRel} 未导出 \`derivers\` 对象（实际导出形态：${d === undefined ? '无 derivers 键' : Array.isArray(d) ? 'array' : typeof d}）——载入失败不降级，请用 \`module.exports = { derivers: { ... } }\``] };
+          return adopterState;
+        }
+        adopterState = { ok: true, derivers: d };
+      } catch (e) {
+        const hint = /ERR_REQUIRE_ESM/.test(String(e && e.code)) ? `（该错误表示模块被当成了 ESM——本契约要求 CommonJS：文件后缀 .cjs 且用 \`module.exports = { derivers: {...} }\`）` : '';
+        adopterState = { ok: false, errors: [`${adopterModRel} 载入失败：${String(e && e.message ? e.message : e).split('\n')[0]}${hint}——载入失败不降级（静默降级会让你误以为「忘了登记」而非「模块坏了」）`] };
+      }
+      return adopterState;
+    };
+    // deriverCtx：注入给装户取数器的同步辅助（免其重复造轮子；2026-09-28 check16-inline-debt 迁出时
+    // 自 `ctx` 改名——runCheck16 的参数 ctx 已被外层符号注入契约占用，避免遮蔽混淆）
+    // **glob 逐字符转义**（自查修正）：首版用「先整体转义特殊字符、再 replace 星号」的写法，
+    // 实测 `src/**/*.ts` 匹配不到 `src/a/b/c.ts`、「**/*.md」匹配不到 `a/b/c.md`——因为 `**/`
+    // 在被替换前已被字符类转义破坏。改为逐字符状态机，语义明确：
+    //   `**/` → 任意层级（含零层）；`**` → 任意（可跨 /）；`*` → 段内任意（不跨 /）；`?` → 段内单字符
+    //   其余一律字面转义（故 `a.b.sql` 的点是字面点、`[`/`{` 也按字面处理——本 helper 不承诺
+    //   字符类 / 花括号展开，避免装户误以为支持完整 glob 语法；不支持即按字面匹配，行为可预测）
+    const globToRegExp = (p) => {
+      const s = String(p);
+      let re = '';
+      for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === '*' && s[i + 1] === '*') {
+          if (s[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } // `**/` 含零层
+          else { re += '.*'; i += 1; }                        // `**` 跨段
+        } else if (c === '*') re += '[^/]*';
+        else if (c === '?') re += '[^/]';
+        else re += c.replace(/[.+^${}()|[\]\\]/, '\\$&');
+      }
+      return new RegExp('^' + re + '$');
+    };
+    // 遍历时**跳过重目录 + 防环**（自查 + 复核 P2 修正）：
+    // · 剪枝 node_modules / .git / cache——无剪枝时 `deriverCtx.glob('**/*')` 会走进依赖树，既慢又会把
+    //   依赖文件算进取数（对「我项目有多少个 X」是错的数）。
+    // · **visited 集合防环**：复核实测软链接/junction 成环时递归到 depth 128、同一文件重复 64 份
+    //   才被 statSync 的 ELOOP 拦下；POSIX 无 MAX_PATH 时该递归无界。故按**真实路径**去重。
+    const WALK_SKIP = new Set(['node_modules', '.git', 'cache']);
+    const walkFiles = (dir, out = [], rel = '', visited = new Set()) => {
+      let real = dir;
+      try { real = fs.realpathSync(dir); } catch { /* 不可解析则按原路径处理 */ }
+      if (visited.has(real)) return out; // 环 → 剪枝
+      visited.add(real);
+      for (const e of readdirOrNull(dir) || []) {
+        if (WALK_SKIP.has(e)) continue;
+        const abs = path.join(dir, e);
+        const r = rel ? `${rel}/${e}` : e;
+        let st = null;
+        try { st = fs.statSync(abs); } catch { continue; }
+        if (st.isDirectory()) walkFiles(abs, out, r, visited);
+        else out.push(r);
+      }
+      return out;
+    };
+    const deriverCtx = {
+      root: ROOT,
+      read: (rel) => { try { return fs.readFileSync(path.join(ROOT, rel), 'utf8').replace(/\r\n/g, '\n'); } catch { return ''; } },
+      glob: (pattern) => { const re = globToRegExp(pattern); return walkFiles(ROOT).filter((r) => re.test(r)); },
+      countFiles: (dir, pred) => walkFiles(path.join(ROOT, dir)).filter((r) => (typeof pred === 'function' ? pred(r) : true)).length,
+    };
+    // resolveDeriver(name) → { fn } | { error }（**绝不抛出**：引擎不因装户代码崩溃）
+    const resolveDeriver = (name) => {
+      if (derivers[name]) return { fn: derivers[name], builtin: true };
+      const st = loadAdopterDerivers();
+      if (!st.ok) return { error: st.errors.join('；') };
+      const fn = st.derivers[name];
+      if (typeof fn !== 'function') {
+        if (fn !== undefined) return { error: `${adopterModRel} 的「${name}」不是函数（实际类型：${typeof fn}）` };
+        return { error: `无对应取数器——内置 8 个指标均不含该名，${adopterModRel} 亦未定义（登记了却没实现＝其实没查）` };
+      }
+      return { fn, builtin: false };
+    };
+    // 装户模块载入失败：**独立成条**（2026-09-28 adopter-derivers）。
+    // 关键设计（真绿 vs 假绿的分界）：载入失败若只表现为「该指标无取数器」，装户会看到
+    // 「引用了 my.metric → 未登记」，看起来像**自己忘了登记**，而真因是模块坏了——他会去 registry
+    // 反复核对，永远查不到。故此处单独出一条，明示文件与错误，与「真的没登记」可区分。
+    //
+    // **仅在真的需要装户指标时才报**（复核 P2 更正）：首版在解析登记表前无条件出账——若登记表只有
+    // 内置指标、而装户留了个半成品模块（或模块坏掉但没人用），会平白多一条不可消除的 advisory。
+    // 沿本仓红线「无判定依据的行不产出噪声」：先看登记表是否真的有**非内置**指标，再决定报不报。
+    const mcLines = (linesOf(mcFile) || []).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    const hasAdopterMetric = mcLines.some((l) => {
+      const mm = /^([A-Za-z][\w.]*)\s*=\s*([A-Za-z][\w.]*)$/.exec(l);
+      return mm && !derivers[mm[1]];
+    });
+    const adopterLoad = loadAdopterDerivers();
+    if (!adopterLoad.ok && hasAdopterMetric) {
+      for (const e of adopterLoad.errors) warnings.push(`- [WARN 装户取数器载入失败] ${e}`);
+    }
+    // 解析登记表：`<指标名> = <取数表达式>`（表达式须与指标名同形，二者不一致即登记笔误）
+    const declared = new Map();
+    const precedenceWarned = new Set(); // 同名 advisory 按指标去重（复核 P2 更正：首版按行重复出账）
+    for (const line of mcLines) {
+      const m = /^([A-Za-z][\w.]*)\s*=\s*([A-Za-z][\w.]*)$/.exec(line);
+      if (!m) { warnings.push(`- [WARN 指标登记] .agents/metric-claims.txt 行格式非法（应为 \`指标名 = 取数表达式\`）：${line}`); continue; }
+      if (m[1] !== m[2]) { warnings.push(`- [WARN 指标登记] 登记名与取数表达式不一致：${m[1]} ≠ ${m[2]}`); continue; }
+      const r = resolveDeriver(m[1]);
+      if (r.error) {
+        // 无取数器（内置无 + 装户模块无同名）或装户模块载入失败 → 明示可操作方向
+        const hint = adopterLoad.ok
+          ? `若为项目自有指标，请在 ${adopterModRel} 的 derivers 中实现（契约见 .agents/metric-claims.txt 头部）`
+          : `且 ${adopterModRel} 载入失败（见上方「装户取数器载入失败」条目——**这不是「忘了登记」**）`;
+        warnings.push(`- [WARN 指标登记] 指标「${m[1]}」无对应取数器（fail-loud：登记了却没实现＝其实没查）——内置 8 指标不含该名，${hint}`);
+        // **不 continue**：该指标在 registry 里确实登记过，故仍计入 declared——
+        // 否则引用它的文档会被误报为「未登记」（把「模块坏了」伪装成「忘了登记」，正是本单要防的假绿）。
+        // 取数失败在扫描阶段以「指标取数失败」单独出账，两条信息不互相掩盖。
+      } else if (r.builtin && adopterLoad.ok && typeof adopterLoad.derivers[m[1]] === 'function' && !precedenceWarned.has(m[1])) {
+        // 内置与装户同名：内置优先（保持本仓/存量行为稳定），并明示装户定义被忽略（**按指标去重**）
+        precedenceWarned.add(m[1]);
+        warnings.push(`- [WARN 指标登记] 指标「${m[1]}」由引擎内置提供，${adopterModRel} 中的同名定义**被忽略**（内置优先）——如需改用自有实现，请换一个指标名`);
+      }
+      declared.set(m[1], true);
+    }
+    // 扫活跃态文档（沿检查 4 现有尺度：终态件的历史数字是历史叙述，不扫）。
+    // tracked-only 口径（2026-09-28 check16-inline-debt T2，与检查 1-15 统一）：
+    //   子目录走 ctx.docFiles(sub)——过滤链（.md ∧ 数字前缀 ∧ tracked）全仓唯一处定义，首版独立
+    //   readdir 扫描不含 tracked 过滤，会把并行会话的**未跟踪**半成品也拖进对账面（别人的草稿不该
+    //   拦我的 push——沿仓库模式「只扫已提交(HEAD)内容」总口径）；
+    //   根级 workflow/*.md 滤 .md ∧ tracked（无数字前缀约束——README/INDEX/delegations 等本无前缀，
+    //   维持现状；根级本无 _TEMPLATE，无需显式排除）。
+    const activeSet16 = (sub) => (sub === 'incidents' ? ENUMS['incident.status.active'] : ENUMS['doc.status.active']);
+    const scanFiles16 = [];
+    for (const sub of ['intents', 'specs', 'plans', 'incidents']) {
+      for (const abs of docFiles(sub)) {
+        if (!inSet(fmGet(abs, '状态'), activeSet16(sub))) continue;
+        scanFiles16.push({ rel: path.relative(ROOT, abs).split(path.sep).join('/'), abs });
+      }
+    }
+    for (const f of readdirOrNull(path.join(ROOT, 'workflow')) || []) {
+      const abs = path.join(ROOT, 'workflow', f);
+      if (f.endsWith('.md') && isTracked(abs)) scanFiles16.push({ rel: `workflow/${f}`, abs });
+    }
+    for (const { rel, abs } of scanFiles16) {
+      const ls = linesOf(abs) || [];
+      ls.forEach((line, i) => {
+        // 签名形态收窄为**小写点分**（如 `{{ledger.lines}}`）：装户模板占位符是全大写 SCREAMING_CASE
+        // （构建命令 / 看板端口 / 项目名三类，由 init 渲染替换，非本检查对象）
+        // ——不收窄会对这些合法的模板占位符产生大量假阳性（实测：本仓 plans 内 11 处）。
+        // **转义（2026-09-28，本检查在自己的文档上抓到该需求）**：讲语法 / 举例 / 引用告警原文的
+        // 文档在签名前加反斜杠（`\{{ledger.lines}}`）表示「此处是示意、非断言」——否则本检查
+        // 会把「文档在教怎么用签名」误判为「作者忘了回填」。选显式转义而非「同句含『如/例』等标记词
+        // 即豁免」的启发式：后者会按措辞松紧漂移，且作者能无意中触发豁免而漏过真断言。
+        // **转义按「逐个出现」生效、不按整行**（复核自查 P1 更正）：首版实现是「行内出现任一 `\{{`
+        // 即整行跳过」，实测可被这样藏住真断言——`… \{{a.b}} 示意… {{ledger.lines}} 未回填` 整行静默
+        // 放过。故改为用带后顾的否匹配排除转义位，同行的真签名照常出账。
+        for (const m of line.matchAll(/(?<!\\)\{\{([a-z][a-z0-9]*(?:\.[a-z0-9]+)+)\}\}/g)) {
+          const name = m[1];
+          if (!declared.has(name)) {
+            warnings.push(`- [WARN 指标未登记] ${rel}:${i + 1} 引用 {{${name}}} 但 .agents/metric-claims.txt 未登记该指标（未登记＝无从对账）`);
+            continue;
+          }
+          const r = resolveDeriver(name);
+          if (r.error) {
+            // 取数器不可用（含装户模块载入失败 / 无该名 / 定义非法）——**响亮出账，绝不静默跳过**
+            warnings.push(`- [WARN 指标取数失败] ${rel}:${i + 1} {{${name}}} 无法取数：${r.error}`);
+            continue;
+          }
+          let real;
+          try {
+            real = r.fn(deriverCtx);
+          } catch (e) {
+            warnings.push(`- [WARN 指标取数失败] ${rel}:${i + 1} {{${name}}} 取数器抛异常：${String(e && e.message ? e.message : e).split('\n')[0]}`);
+            continue;
+          }
+          // 返回值必须是有限数字：Promise（误写 async）/ NaN / 字符串 / undefined 一律拦下并明示类型
+          if (typeof real !== 'number' || !Number.isFinite(real)) {
+            const kind = real && typeof real.then === 'function' ? 'Promise（本检查要求**同步**函数，请去掉 async/await）' : `${typeof real}${typeof real === 'number' ? `（${real}）` : ''}`;
+            warnings.push(`- [WARN 指标取数失败] ${rel}:${i + 1} {{${name}}} 取数器返回值不是有限数字：${kind}`);
+            continue;
+          }
+          // 判据：签名**必须**被替换为实时值——留有 `{{...}}` 即视为未回填（写作期占位，关单前须落实）
+          warnings.push(`- [WARN 指标待回填] ${rel}:${i + 1} {{${name}}} 实时值 = ${real}——请把签名替换为该数字（留签名＝未回填）`);
+        }
+        // **形态不符的签名也不静默放过（复核 P2 更正）**：首版只认严格小写点分形态，于是
+        // `{{Ledger.Lines}}` / `{{ ledger.lines }}`（含空格）这类**明显本意是签名**的写法
+        // 既不匹配、也不出账——静默漏过，且绕开了「未登记」的 fail-loud。此处补一道：
+        // 非转义的 `{{...}}` 中，凡**不是**严格形态、且**不是**装户模板占位符（全大写 SCREAMING_CASE）
+        // 的，一律提示形态不符（作者才能立刻发现笔误）。
+        for (const m of line.matchAll(/(?<!\\)\{\{([^{}]+)\}\}/g)) {
+          const raw = m[1];
+          if (/^[a-z][a-z0-9]*(?:\.[a-z0-9]+)+$/.test(raw)) continue; // 严格形态，上面已处理
+          if (/^[A-Z][A-Z0-9_]*$/.test(raw)) continue; // 装户模板占位符（init 渲染对象，非本检查面）
+          warnings.push(`- [WARN 指标形态] ${rel}:${i + 1} \`{{${raw}}}\` 不是合法签名形态（应为小写点分，如 {{ledger.lines}}）——若本意是量化断言，请改正形态；若只是举例，请加反斜杠转义`);
+        }
+      });
+    }
+  }
+}

package/templates/_agents/scripts/commit-check-trigger.test.mjs

@@ -37,7 +37,7 @@ const mkfix = () => {
     ],
     checks: [],
   }));
-  return { root, marks };
+  return { root, marks, cmd };
 };
 
 // stage：写文件并暂存，跑 hook（extraArgs 透传如 --full），返回 { status, out, ran }
@@ -87,6 +87,69 @@ stage(f.root, 'unrelated.txt', 'x');
 r = runHook(f.root, ['--full']);
 check('S5 --full 无条件全跑全部 builds', ran(f.marks, 'extbuild') && ran(f.marks, 'prefixbuild') && r.status === 0, r.out);
 
+// 场景 6：builds.when = pkg:scripts.build。无脚本则 SKIP 且不执行；文件型 when 缺失仍跳过。
+f = mkfix();
+fs.writeFileSync(path.join(f.root, '.agents', 'hooks', 'commit-check.config.json'), JSON.stringify({
+  knownPatterns: [],
+  builds: [{ name: 'build', command: f.cmd('build'), ext: ['.js'], when: ['pkg:scripts.build'] }],
+  checks: [{ name: 'lint', command: f.cmd('lint'), ext: ['.js'], when: ['eslint.config.js'] }],
+}));
+fs.writeFileSync(path.join(f.root, 'package.json'), JSON.stringify({ name: 't', scripts: {} }));
+stage(f.root, 'src/a.js', 'console.log(1)\n');
+r = runHook(f.root);
+check('S6 无 scripts.build → 构建 SKIP、命令不跑、退出 0',
+  r.status === 0 && !ran(f.marks, 'build') && r.out.includes('pkg:scripts.build') && r.out.includes('SKIP')
+  && !r.out.includes('无匹配的源码变更'), r.out);
+check('S6 文件型 when 缺失仍跳过（eslint.config.js）', !ran(f.marks, 'lint') && r.out.includes('eslint.config.js'), r.out);
+
+// 场景 7：scripts.build 为非空字符串 → 构建命令执行；补上 eslint 配置后质量检查也执行。
+f = mkfix();
+fs.writeFileSync(path.join(f.root, '.agents', 'hooks', 'commit-check.config.json'), JSON.stringify({
+  knownPatterns: [],
+  builds: [{ name: 'build', command: f.cmd('build'), ext: ['.js'], when: ['pkg:scripts.build'] }],
+  checks: [{ name: 'lint', command: f.cmd('lint'), ext: ['.js'], when: ['eslint.config.js'] }],
+}));
+fs.writeFileSync(path.join(f.root, 'package.json'), JSON.stringify({ name: 't', scripts: { build: 'node -e 0' } }));
+fs.writeFileSync(path.join(f.root, 'eslint.config.js'), 'export default [];\n');
+stage(f.root, 'src/a.js', 'console.log(1)\n');
+r = runHook(f.root);
+check('S7 有 scripts.build 且 eslint 配置存在 → 构建与质量检查都执行',
+  r.status === 0 && ran(f.marks, 'build') && ran(f.marks, 'lint'), r.out);
+
+// 场景 8：--full 也不越过 pkg: when（没有脚本就不跑）
+f = mkfix();
+fs.writeFileSync(path.join(f.root, '.agents', 'hooks', 'commit-check.config.json'), JSON.stringify({
+  knownPatterns: [],
+  builds: [{ name: 'build', command: f.cmd('build'), ext: ['.js'], when: ['pkg:scripts.build'] }],
+  checks: [],
+}));
+fs.writeFileSync(path.join(f.root, 'package.json'), JSON.stringify({ name: 't' }));
+stage(f.root, 'src/a.js', 'console.log(1)\n');
+r = runHook(f.root, ['--full']);
+check('S8 --full 仍尊重 pkg:scripts.build',
+  r.status === 0 && !ran(f.marks, 'build') && r.out.includes('SKIP') && !r.out.includes('无匹配的源码变更'), r.out);
+
+// 场景 9：pkg:scripts.build 四种不满足都不执行（空白、非字符串、非法 JSON、没有 package.json）
+const unsatisfied = [
+  ['空白字符串', (root) => fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 't', scripts: { build: '   ' } }))],
+  ['非字符串', (root) => fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 't', scripts: { build: 1 } }))],
+  ['非法 JSON', (root) => fs.writeFileSync(path.join(root, 'package.json'), '{')],
+  ['缺少 package.json', () => {}],
+];
+for (const [label, writePkg] of unsatisfied) {
+  f = mkfix();
+  fs.writeFileSync(path.join(f.root, '.agents', 'hooks', 'commit-check.config.json'), JSON.stringify({
+    knownPatterns: [],
+    builds: [{ name: 'build', command: f.cmd('build'), ext: ['.js'], when: ['pkg:scripts.build'] }],
+    checks: [],
+  }));
+  writePkg(f.root);
+  stage(f.root, 'src/a.js', 'console.log(1)\n');
+  r = runHook(f.root);
+  check(`S9 ${label} → SKIP、命令不跑、不报无匹配`,
+    r.status === 0 && !ran(f.marks, 'build') && r.out.includes('pkg:scripts.build') && !r.out.includes('无匹配的源码变更'), r.out);
+}
+
 for (const d of fs.readdirSync(os.tmpdir()).filter((x) => x.startsWith('cc-trigger-test-'))) {
   fs.rmSync(path.join(os.tmpdir(), d), { recursive: true, force: true });
 }

package/templates/_agents/scripts/confirm-doc.mjs

@@ -23,15 +23,23 @@
 // 指纹：内容 CRLF 归一 → 剔除「确认指纹:」行（防自引用）→ sha256；frontmatter 存前 16 位，台账存全量。
 // 用法：node .agents/scripts/confirm-doc.mjs <workflow/intents|x.md> [<doc2>...] [--root <仓库根>]
 //       node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<用户对话原话>"（委托代录）
+//       node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<原话>" --batch（协作道批量：L0/L1 多份一次代录）
 //       node .agents/scripts/confirm-doc.mjs <doc...> --to superseded|cancelled（放弃态：取代/取消，留指纹与台账）
-//   多文档一次传入：仅 TTY 模式（用户亲手逐份过目键入——天然逐件）；--delegated 一次仅一份
-//   （2026-09-27 confirm-gate-one-per-call：多份并录曾系统性塌掉 build.md「逐件确认」三道门）。
+//   多文档一次传入：TTY 模式天然逐份过目键入；--delegated 默认一次仅一份（2026-09-27
+//   confirm-gate-one-per-call：多份并录曾系统性塌掉 build.md「逐件确认」三道门），L0/L1 协作道可
+//   `--batch` 多份一次代录（2026-09-30 hybrid-governance-risk-lanes）：逐份读「级别」，L2/L3 逐份拒绝
+//   （防御道不批量）；台账行带 `brief:true` 简洁审计标记（quote 原话仍入账供对质），check-loop 检查 15
+//   并录审计对全行带标记的批次豁免「确认并录」告警。--auto 一次仍仅一份（自治放行不批量）。
+// 逐阶段前置门（2026-09-30 stage-gate-machine）：specs/plans 的 draft→approved 须同主题入口已确认
+//   （plan 另须入口级别 L2/L3 时同名 spec 已确认；判定口径见 stage-gates.mjs）——未过拒绝落账：
+//   不写盘、不 append 台账、该份计为「拒绝」，任一被拒进程 exit 2。
 // 测试：node templates/_agents/scripts/confirm-doc.test.mjs（纯函数逐项 + 非 TTY spawn 拒绝断言 + 委托场景）
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { confirmGateFor, doneGateFor } from './stage-gates.mjs';
 
 // computeFingerprint(text)：CRLF 归一 → 剔指纹行 → sha256 hex（64 位）
 export function computeFingerprint(text) {
@@ -97,17 +105,31 @@ export function appendLedger(root, entry) {
 
 const DOC_RE = /^workflow\/(intents|specs|plans|incidents)\/[^/]+\.md$/;
 
+// fmLevel(nl)：frontmatter「级别:」值（无 frontmatter / 无该键 → ''）——AI 自治门与协作道批量门共用
+export function fmLevel(nl) {
+  if (!/^---\s*$/.test(nl[0] || '')) return '';
+  for (let i = 1; i < nl.length && !/^---\s*$/.test(nl[i]); i++) {
+    const m = nl[i].match(/^级别:\s*(.*)$/);
+    if (m) return m[1].trim();
+  }
+  return '';
+}
+
 const isMain = process.argv[1] && process.argv[1].endsWith('confirm-doc.mjs');
 if (isMain) {
   const argv = process.argv.slice(2);
   let root = process.cwd();
   let delegatedQuote = null; // null = TTY 模式；字符串 = 委托代录的用户对话原话
   let toTarget = null; // null = 默认前向跳转；superseded|cancelled = 放弃态显式目标
+  let autoMode = false; // AI 自治模式（信任等级授权，2026-09-30 ai-autonomy-trust）
+  let batchMode = false; // 协作道批量代录（--batch，2026-09-30 hybrid-governance-risk-lanes：仅 --delegated + L0/L1）
   const docs = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--root') root = path.resolve(argv[++i]);
     else if (argv[i] === '--delegated') delegatedQuote = argv[++i] ?? '';
     else if (argv[i] === '--to') toTarget = argv[++i] ?? '';
+    else if (argv[i] === '--auto') autoMode = true;
+    else if (argv[i] === '--batch') batchMode = true;
     else docs.push(argv[i].replace(/\\/g, '/'));
   }
   if (toTarget !== null && !ABANDON_TARGETS.includes(toTarget)) {
@@ -115,6 +137,40 @@ if (isMain) {
     process.exit(1);
   }
   const delegated = delegatedQuote !== null;
+  if (delegated && autoMode) {
+    console.error('❌ --auto 与 --delegated 互斥：自治模式是用户预先授权的机器放行，委托代录是单次对话确认');
+    process.exit(1);
+  }
+  if (batchMode && autoMode) {
+    console.error('❌ --batch 与 --auto 互斥：批量代录是协作道的对话委托形态，自治放行不批量（一次一份）');
+    process.exit(1);
+  }
+  if (batchMode && toTarget) {
+    console.error('❌ --batch 不支持 --to 放弃态——放弃须逐份显式确认，不批量');
+    process.exit(1);
+  }
+  // AI 自治门（2026-09-30 ai-autonomy-trust；2026-09-30 hybrid-governance-explore-hardening 加隐式形态）：
+  // 读 .agents/trust-mode.json。除显式 --auto 外，Trusted（level=2）下的非 TTY 单份调用在 TTY 门处
+  // 免旗标自动转入本分支（见「Trusted 自动泳道」）——L0/L1 门 / incidents 排除 / 逐阶段与 done 门照常执行。
+  let trustConfig = null;
+  if (autoMode) {
+    try {
+      trustConfig = JSON.parse(fs.readFileSync(path.join(root, '.agents', 'trust-mode.json'), 'utf8'));
+    } catch { trustConfig = { enabled: false, level: 0 }; }
+    if (!trustConfig.enabled || ![1, 2].includes(trustConfig.level)) {
+      console.error('❌ AI 自治未开启或等级非法（.agents/trust-mode.json enabled=false 或 level∉[1,2]）——跑 node .agents/scripts/trust-mode.mjs --enable --level <1|2> 开启');
+      process.exit(1);
+    }
+    if (toTarget) {
+      console.error('❌ AI 自治模式不支持 --to 放弃态（放弃态必须由用户显式确认）');
+      process.exit(1);
+    }
+    if (docs.length > 1) {
+      console.error('❌ AI 自治模式一次仅接受一份文档（与 --delegated 同口径，逐件放行）');
+      process.exit(1);
+    }
+    console.error(`⚠️  AI 自治模式（Trust L${trustConfig.level}）：仅限 L0/L1 文档；Level 1 只放行 draft→approved，Level 2 放行至 done`);
+  }
   if (delegated && !String(delegatedQuote).trim()) {
     console.error('用法：--delegated 须带用户对话原话（node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<用户原话>"）——原话入台账供事后对质，不可缺省');
     process.exit(1);
@@ -122,25 +178,51 @@ if (isMain) {
   // TTY 门（仅 TTY 模式；先于文档参数校验）：AI 会话内非委托调用一律拒绝
   // CONFIRM_DOC_TEST_TTY：**仅测试用**逃生门——本测试环境无 TTY，而 TTY 多文档分支
   // （batch 相同 / seq 递增 / of=N）是并录审计的判别基础，必须可测（复核 P2-2）。
-  // 该变量只影响 isTTY 判定，不改动任何落态/记账语义；生产路径不设置该变量。
-  const ttyForced = process.env.CONFIRM_DOC_TEST_TTY === '1';
-  if (!delegated && !ttyForced && (!process.stdin.isTTY || !process.stdout.isTTY)) {
-    console.error('确认门须由用户在终端亲手运行（node .agents/scripts/confirm-doc.mjs <workflow/文档>...）——AI 会话内不可代确认；用户对话内明确确认后可用 --delegated "<用户原话>" 委托代录（台账如实记来源）');
-    process.exit(1);
+  // 双条件（2026-09-28 check16-inline-debt）：须同时 NODE_ENV === 'test' 才放行——单看
+  // 「TEST」字样的变量名不构成机器约束，AI 会话可能「顺手」在生产路径设置它绕过 TTY 门；
+  // 加 NODE_ENV 双条件后，生产路径（不设 NODE_ENV=test）即便误设 CONFIRM_DOC_TEST_TTY 也不生效。
+  // **信任边界声明（沿 check8-git-anchor 口径）**：本地信任边界内不可机器防——环境变量终究可被
+  // 本机进程任意设置，刻意伪造 `NODE_ENV=test CONFIRM_DOC_TEST_TTY=1` 仍可绕过，与伪造 git 时间戳 /
+  // 手改台账同属事后对质（git 历史与台账）兜底的范畴；此处只把「顺手设置单变量」的成本抬到
+  // 「主动伪造双变量组合」，不宣称「通道已关闭」。
+  // 两变量只影响 isTTY 判定，不改动任何落态/记账语义；生产路径不设置这两个变量。
+  const ttyForced = process.env.CONFIRM_DOC_TEST_TTY === '1' && process.env.NODE_ENV === 'test';
+  if (!delegated && !autoMode && !ttyForced && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+    // Trusted 自动泳道（2026-09-30 hybrid-governance-explore-hardening）：trust-mode.json 为 Trusted
+    // （enabled 且 level=2）时，非 TTY 调用（AI 会话）对文档**免手工触发**（无需 --delegated 原话 /
+    // --auto 旗标）自动转入 AI 自治放行——单份、非放弃态才可隐式（与 --auto 同口径，L0/L1 门与
+    // incidents 排除由主循环自治门照常执行）；不满足则维持原拒绝（fail-closed，Standard/Strict 不隐式）。
+    let implicitTrust = null;
+    try {
+      implicitTrust = JSON.parse(fs.readFileSync(path.join(root, '.agents', 'trust-mode.json'), 'utf8'));
+    } catch { implicitTrust = { enabled: false, level: 0 }; }
+    if (implicitTrust.enabled && implicitTrust.level === 2 && docs.length === 1 && !toTarget) {
+      autoMode = true;
+      trustConfig = implicitTrust; // 主循环自治门（L0/L1 与 incidents 排除）直读本配置——顶部 if (autoMode) 块先于 TTY 门执行，须在此补装
+      console.error('⚠️  Trusted 自动泳道（隐式）：单份 L0/L1 文档按 AI 自治放行（Level 2 全闭环，台账 source=ai-auto-trust-L2）；L2/L3 与 incidents 仍须人工确认');
+    } else {
+      console.error('确认门须由用户在终端亲手运行（node .agents/scripts/confirm-doc.mjs <workflow/文档>...）——AI 会话内不可代确认；用户对话内明确确认后可用 --delegated "<用户原话>" 委托代录（台账如实记来源）');
+      process.exit(1);
+    }
   }
   if (!docs.length) {
-    console.error('用法：node .agents/scripts/confirm-doc.mjs <workflow/intents|specs|plans/x.md> [...]  [--root <仓库根>] [--delegated "<用户原话>"]');
+    console.error('用法：node .agents/scripts/confirm-doc.mjs <workflow/intents|specs|plans/x.md> [...]  [--root <仓库根>] [--delegated "<用户原话>" [--batch]]');
     process.exit(1);
   }
   if (delegated) {
     console.error('⚠️  委托代录模式：确认语义 = 用户已在对话中明确放行；台账行将如实记 source=chat-delegated 与原话，不伪装 TTY 确认');
     console.error(`   用户原话：「${delegatedQuote}」`);
-    // 单文档强制（2026-09-27 confirm-gate-one-per-call）：delegated 没有TTY「逐份过目」的天然机制——
+    // 单文档默认（2026-09-27 confirm-gate-one-per-call）：delegated 没有TTY「逐份过目」的天然机制——
     // 多文档并录曾系统性塌掉三道阶段门（build.md「逐件确认不得并作一次」）。逐件调用：一次一份、
     // 每次带当次用户原话。TTY 形态不受限（用户亲手逐份过目键入，天然逐件）。
+    // 协作道批量（2026-09-30 hybrid-governance-risk-lanes）：L0/L1 可 `--batch` 多份一次代录——
+    // 逐份读「级别」，L2/L3 逐份拒绝（见主循环协作道门）；台账行带 brief:true，检查 15 据此豁免并录告警。
     if (docs.length > 1) {
-      console.error(`❌ --delegated 一次仅接受一份文档（现 ${docs.length} 份：${docs.join(' ')}）——逐件确认口径（build.md）：每份一次调用、每次带当次用户原话`);
-      process.exit(1);
+      if (!batchMode) {
+        console.error(`❌ --delegated 一次仅接受一份文档（现 ${docs.length} 份：${docs.join(' ')}）——逐件确认口径（build.md）：每份一次调用、每次带当次用户原话；L0/L1 协作道批量可加 --batch`);
+        process.exit(1);
+      }
+      console.error(`   批量代录（--batch）：${docs.length} 份，仅受理 L0/L1（协作道，异步审计兜底）；L2/L3 逐份拒绝`);
     }
   }
   // 调用事实（2026-09-28 batch-ledger-audit）：本次进程调用的批次标识与件序——
@@ -164,6 +246,7 @@ if (isMain) {
     return rl.question(q, res);
   });
   let confirmed = 0;
+  let refused = 0; // 逐阶段前置门拒绝数（exit 2 信号；2026-09-30 stage-gate-machine）
   for (const doc of docs) {
     if (!DOC_RE.test(doc)) {
       console.error(`跳过 ${doc}：路径须匹配 workflow/{intents,specs,plans,incidents}/<文件>.md`);
@@ -183,20 +266,81 @@ if (isMain) {
       }
     }
     const target = resolveTransition(st, toTarget);
+    const lvl = fmLevel(nl); // 级别（AI 自治门 / 协作道批量门共用；缺 = ''）
     if (!target) {
       console.error(`跳过 ${doc}：当前状态「${st || '缺失'}」无合法跳转（前向：docs draft→approved / approved→done；incidents open→fixed / fixed→closed；放弃 --to：cancelled 自 draft/approved/open/fixed，superseded 自 approved/done/fixed/closed）`);
       continue;
     }
+    // 逐阶段前置门（2026-09-30 stage-gate-machine）：specs/plans 的 draft→approved 须前置已确认
+    // （plan 另须入口级别 L2/L3 时同名 spec 已确认）——未过拒绝落账（不写盘、不 append 台账）。
+    if (target === 'approved' && (doc.startsWith('workflow/specs/') || doc.startsWith('workflow/plans/'))) {
+      const gate = confirmGateFor(root, doc);
+      if (!gate.ok) {
+        console.error(`❌ ${doc} 未过逐阶段前置门（stage-gates）：${gate.reason}`);
+        console.error(`   ${gate.hint}（本份未落账、未写盘）`);
+        refused++;
+        continue;
+      }
+    }
+    // done 前置门（2026-09-30 confirm-gate-approved-history）：→done 须 git 历史已留 approved 态
+    // （先 done 后提交 / 两跳同批提交 → 拒绝；防「确认态缺失」缺陷复发；判据单源见 stage-gates.doneGateFor）。
+    if (target === 'done') {
+      const gate = doneGateFor(root, abs, doc);
+      if (!gate.ok) {
+        console.error(`❌ ${doc} 未过 done 前置门（approved 历史）：${gate.reason}`);
+        console.error(`   ${gate.hint}（本份未落账、未写盘）`);
+        refused++;
+        continue;
+      }
+    }
     const fp = computeFingerprint(text);
+    // AI 自治放行分支（2026-09-30 ai-autonomy-trust）：
+    // ① 仅 L0/L1（读 frontmatter「级别」，缺级别按不可自治处理——fail-closed）；
+    // ② Level 1：仅 draft→approved；Level 2：draft→approved 与 approved→done；
+    // ③ incidents 永不自治（open→fixed/fixed→closed 必须人工）。
+    if (autoMode) {
+      const isLowLevel = lvl === 'L0' || lvl === 'L1';
+      const stageAllowed = trustConfig.level === 2
+        ? (target === 'approved' || target === 'done')
+        : target === 'approved';
+      if (!isLowLevel || !stageAllowed || doc.startsWith('workflow/incidents/')) {
+        console.error(`❌ ${doc} 未过 AI 自治门（级别「${lvl || '缺失'}」/ 目标态「${target}」/ 类型）：Level ${trustConfig.level} 仅授权 L0/L1 的 ${trustConfig.level === 2 ? 'approved/done' : 'approved'} 且不含 incidents`);
+        refused++;
+        continue;
+      }
+      fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
+      appendLedger(root, {
+        ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
+        source: `ai-auto-trust-L${trustConfig.level}`, quote: `AI 自治放行 (Trust Level ${trustConfig.level})`,
+        batch, seq, of: docs.length,
+      });
+      console.log(`✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，AI 自治已记账：source=ai-auto-trust-L${trustConfig.level}）`);
+      confirmed++;
+      seq++;
+      continue;
+    }
     if (delegated) {
+      // 协作道门（2026-09-30 hybrid-governance-risk-lanes）：--batch 批量仅受理 L0/L1——L2/L3（或缺级别，
+      // fail-closed）逐份拒绝落账；不带 --batch 的单份代录不限级别（既有口径不变）。
+      const low = lvl === 'L0' || lvl === 'L1';
+      if (batchMode && !low) {
+        console.error(`❌ ${doc} 级别「${lvl || '缺失'}」不在协作道（L0/L1）——--batch 批量代录仅限 L0/L1，L2/L3 防御道须逐份确认（本份未落账、未写盘）`);
+        refused++;
+        continue;
+      }
       fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
       appendLedger(root, {
         ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
         source: 'chat-delegated', quote: String(delegatedQuote),
         // 调用事实（batch-ledger-audit）：seq=本次调用内件序（从 1），of=本次调用总份数
         batch, seq, of: docs.length,
+        // 简洁审计标记（hybrid-governance-risk-lanes）：L0/L1 协作道行带 brief（quote 仍入账供对质），
+        // 检查 15 并录审计对全 brief 批次豁免「确认并录」告警
+        ...(low ? { brief: true } : {}),
       });
-      console.log(`✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，代录已记账：source=chat-delegated）`);
+      console.log(low
+        ? `✓ ${doc} ${st} → ${target} [${lvl} 协作道/异步审计]（指纹 ${fp.slice(0, 16)}）`
+        : `✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，代录已记账：source=chat-delegated）`);
       confirmed++;
       seq++;
       continue;
@@ -222,7 +366,7 @@ if (isMain) {
     seq++;
   }
   if (rl) rl.close();
-  console.log(`\n完成：确认 ${confirmed} 份 / 跳过 ${docs.length - confirmed} 份${delegated ? '（委托代录）' : ''}`);
-  process.exit(0);
+  console.log(`\n完成：确认 ${confirmed} 份 / 跳过 ${docs.length - confirmed - refused} 份 / 拒绝 ${refused} 份${delegated ? '（委托代录）' : ''}`);
+  process.exit(refused ? 2 : 0);
 }
-export default { computeFingerprint, nextStage, applyTransition, appendLedger };
+export default { computeFingerprint, nextStage, applyTransition, appendLedger, fmLevel };