agentic-flow-kit 1.5.0 → 1.7.0

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

@@ -38,8 +38,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
+import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeDigest } from './policy.mjs';
 
 // hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
 // policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
@@ -65,6 +66,33 @@ function docRelOf(root, doc) {
   }
 }
 
+// gitDirtyFiles(root)：机器实测的「工作树处于改动态的文件集合」（已跟踪改动 + 未跟踪新件，gitignore 项天然排除）。
+//   解析 `git status --porcelain`（-z 不用，逐行解析足够；重命名行取 `->` 后段）。
+//   非 git 仓库 / git 不可用 / 命令失败 → []（**静默降级为「无额外改动面」而非假装有**——scope 退化成
+//   只含被确认文档本身，仍然自洽可验；不因探测失败而拒绝关单）。
+function gitDirtyFiles(root) {
+  try {
+    const r = spawnSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8', timeout: 10_000 });
+    if (r.status !== 0 || !r.stdout) return [];
+    return r.stdout.split(/\r?\n/).filter(Boolean).map((line) => {
+      const p = line.slice(3).trim();
+      const arrow = p.lastIndexOf(' -> ');
+      const rel = arrow >= 0 ? p.slice(arrow + 4) : p;
+      return rel.replace(/^"(.*)"$/, '$1');
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+// machineScope(root, doc)：落账用的改动面事实（2026-10-09 审查 A1 干净版）。
+//   **AI 无输入面**——files 全部由机器派生（被确认文档 + git 实测工作树改动集），不是调用方能填的参数。
+//   这正是相对旧设计的核心改进：旧的 quote 是 AI 自填的自由文本（可复用、可伪造、机器不可校验）；
+//   scope 是机器事实，AI 填不了假，对质时问的是「这 N 个文件」而非「一句说过的话」。
+//   归一/摘要计算单源在 policy.scopeDigest（check-loop 检查 15 侧校验复用同一实现）。
+export function machineScope(root, doc) {
+  return scopeDigest([docRelOf(root, doc), ...gitDirtyFiles(root)]);
+}
 // computeFingerprint(text)：CRLF 归一 → 剔指纹行 → sha256 hex（64 位）
 export function computeFingerprint(text) {
   const norm = String(text).replace(/\r\n/g, '\n').split('\n')
@@ -120,10 +148,25 @@ export function applyTransition(text, targetStage, fingerprint16) {
 }
 
 // appendLedger(root, entry)：追加一行 JSON（目录不存在自动建；只 append 不重写）
+// 哈希链（2026-10-09 engine-quality-round2 D）：每行追加 prevHash（末行 hash，末行无 hash/空文件 → ''）
+//   与 hash（ledgerChainHash 单源计算，check-loop 15 同函数验链）——「就地改/删中间行」必留断链痕迹；
+//   历史行零回填（无 hash 行后链重启），整文件重写不可机器防（边界声明见 policy.ledgerChainHash）。
 export function appendLedger(root, entry) {
   const p = path.join(root, '.agents', 'confirmations.jsonl');
   fs.mkdirSync(path.dirname(p), { recursive: true });
-  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  let prevHash = '';
+  try {
+    if (fs.existsSync(p)) {
+      const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+      if (lines.length) {
+        const last = JSON.parse(lines[lines.length - 1]);
+        prevHash = last && typeof last.hash === 'string' ? last.hash : '';
+      }
+    }
+  } catch { /* 末行不可解析 → prevHash ''（链从本行重启；断裂由 check-loop 15 出账） */ }
+  const { hash: _h, prevHash: _p, ...rest } = entry;
+  const row = { ...rest, prevHash, hash: ledgerChainHash(rest, prevHash) };
+  fs.appendFileSync(p, JSON.stringify(row) + '\n');
   return p;
 }
 
@@ -345,6 +388,9 @@ if (isMain) {
       }
     }
     const fp = computeFingerprint(text);
+    // 改动面事实（2026-10-09 审查 A1 干净版）：机器派生，三形态（TTY / 委托代录 / AI 自治）一律记入——
+    // TTY 形态同样需要（事后对质问的是「放行时盘面上哪些文件在动」，与谁点的确认无关）。
+    const scope = machineScope(root, doc);
     // AI 自治放行分支（2026-09-30 ai-autonomy-trust）：
     // ① 仅 L0/L1（读 frontmatter「级别」，缺级别按不可自治处理——fail-closed）；
     // ② Level 1：仅 draft→approved；Level 2：draft→approved 与 approved→done；
@@ -363,7 +409,7 @@ if (isMain) {
       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,
+        batch, seq, of: docs.length, scope,
       });
       console.log(`✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，AI 自治已记账：source=ai-auto-trust-L${trustConfig.level}）`);
       confirmed++;
@@ -386,6 +432,9 @@ if (isMain) {
         source: 'chat-delegated', quote: String(delegatedQuote),
         // 调用事实（batch-ledger-audit）：seq=本次调用内件序（从 1），of=本次调用总份数
         batch, seq, of: docs.length,
+        // 改动面事实（A1 干净版）：quote 降级为「人类可读摘要」，分辨力改由 scope（机器派生）+ fingerprint
+        // （文档内容）承担——「不复用同句」纪律据此退役（复用一句摘要不再削弱任何判据）。
+        scope,
         // 简洁审计标记（hybrid-governance-risk-lanes）：L0/L1 协作道行带 brief（quote 仍入账供对质），
         // 检查 15 并录审计对全 brief 批次豁免「确认并录」告警
         ...(low ? { brief: true } : {}),

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

@@ -13,7 +13,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { computeFingerprint, nextStage, applyTransition, appendLedger, resolveTransition } from './confirm-doc.mjs';
+import { computeFingerprint, nextStage, applyTransition, appendLedger, resolveTransition, machineScope } from './confirm-doc.mjs';
+import { scopeDigest, scopeMatches } from './policy.mjs';
 
 let pass = 0;
 let fail = 0;
@@ -104,6 +105,23 @@ const readLedgerOf = (root) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S8b 哈希链（2026-10-09 engine-quality-round2 D）：链字段写入 + 接续 + 重算自洽 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-chain-'));
+  // 先写一行无 hash 的「存量」行（模拟 v1.5.0 前台账）——新行 prevHash 应为 ''（链重启）
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: 'T0', doc: 'workflow/plans/old.md', stage: 'done', fingerprint: 'e'.repeat(64), prev: 'approved' }) + '\n');
+  appendLedger(root, { ts: 'T1', doc: 'workflow/plans/a.md', stage: 'approved', fingerprint: 'f'.repeat(64), prev: 'draft' });
+  appendLedger(root, { ts: 'T2', doc: 'workflow/plans/a.md', stage: 'done', fingerprint: 'g'.repeat(64), prev: 'approved' });
+  const rows = fs.readFileSync(path.join(root, '.agents', 'confirmations.jsonl'), 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  check('S8b 存量行后首链行 prevHash 为空（链重启，历史零回填）', rows[0].hash === undefined && rows[1].prevHash === '');
+  check('S8b 第二链行 prevHash 接续第一链行 hash', rows[2].prevHash === rows[1].hash);
+  const { ledgerChainHash } = await import('./policy.mjs');
+  const recompute = (row) => { const { hash, prevHash, ...rest } = row; return ledgerChainHash(rest, prevHash) === hash; };
+  check('S8b 两链行 hash 重算自洽（CRLF/键序规范化单源）', recompute(rows[1]) && recompute(rows[2]));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 // ---- S9【核心】非 TTY spawn（AI 调用路径）必须被拒 ----
 {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-tty-'));
@@ -771,5 +789,37 @@ const writeTrust = (root, cfg) => {
     r43.status === 0 && /无测试绿凭证/.test(r43.stderr), String(r43.stderr).slice(0, 200));
 }
 
+// ---- S41 台账 scope：机器派生改动面（2026-10-09 审查 A1 干净版）----
+// 背景：委托代录的授权凭据原是 `--delegated` 的用户原话——自由文本机器不可校验、AI 可零成本复用。
+// 干净版把分辨力换成机器派生的 scope{files,sha256}：写入侧机器派生（AI 无输入面），校验侧重算比对。
+// ① 归一与摘要单源（反斜杠 / 前导 ./ / 重复项 / 顺序无关 → 同一摘要）；② scopeMatches 抓「改了 files
+//    没改摘要」；③ 委托落账行带 scope 且含被确认文档；④ 非 git 夹具降级不崩（scope 退化为仅含 doc）。
+{
+  const d = scopeDigest(['b.md', 'a.md', './a.md', 'x\\y.md']);
+  check('S41① scopeDigest 归一：反斜杠→posix、去重、排序无关，摘要自洽',
+    d.files.join(',') === 'a.md,b.md,x/y.md' && d.sha256 === scopeDigest(['x/y.md', 'a.md', 'b.md']).sha256
+      && scopeMatches({ scope: d }), JSON.stringify(d));
+  check('S41② scopeMatches：files 被改而摘要未同步 → 判否',
+    !scopeMatches({ scope: { files: [...d.files, 'zz.md'], sha256: d.sha256 } })
+      && !scopeMatches({}) && !scopeMatches({ scope: { files: d.files } }));
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-scope-'));
+  const docP = path.join(root, 'workflow', 'intents'); // 用 intents：无逐阶段前置门，本用例只验 scope 落账
+  fs.mkdirSync(docP, { recursive: true });
+  fs.writeFileSync(path.join(docP, '2026-10-09-s.md'), '---\n状态: draft\n---\n# I\n');
+  const r = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-09-s.md', '--delegated', '放行'], { cwd: root, encoding: 'utf8' });
+  const led = readLedgerOf(root);
+  const j = led[led.length - 1];
+  check('S41③ 委托落账行带机器派生 scope：含被确认文档 + 摘要自洽',
+    r.status === 0 && j && j.scope && Array.isArray(j.scope.files)
+      && j.scope.files.includes('workflow/intents/2026-10-09-s.md') && scopeMatches(j),
+    JSON.stringify({ status: r.status, stderr: r.stderr, scope: j && j.scope }));
+  check('S41④ 非 git 夹具降级：machineScope 不崩且仍含 doc（静默退化为无额外改动面，不拒绝关单）',
+    (() => { const s = machineScope(root, 'workflow/intents/2026-10-09-s.md');
+      return Array.isArray(s.files) && s.files.includes('workflow/intents/2026-10-09-s.md') && scopeMatches({ scope: s }); })(),
+    JSON.stringify(machineScope(root, 'workflow/intents/2026-10-09-s.md')));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/edit-face-check.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// edit-face-check — 常驻面编辑时快检（2026-10-09 engine-quality-round2 B2）
+// 动机：常驻面（AGENTS.md 等）的机器约束此前只在 git 钩子层生效——check-loop 仓库模式只扫 HEAD，
+//   工作树编辑期零反馈（实测：常驻面重构砍掉阶段索引，到提交才被检查 7 报警）。本脚本把判定左移到编辑时。
+// 判定零复刻铁律：闭环判定**单源**复用 check-loop——以 CHECK_LOOP_ROOT=<root>（全扫模式，扫工作树
+//   非 HEAD）子进程消费其裁决，本脚本不实现任何门判定；唯一自算是常驻面字节预算 advisory（工作树
+//   LF 字节 vs rule-budgets.txt 上限——提交门口径走 git index/HEAD（rule-budget.sh），两者判据不同面，
+//   此处为编辑时 advisory，冲突时以提交门为准）。
+// exit 语义：check-loop hard（exit≠0）→ 2；预算 advisory 超限 → 1；其余 → 0。
+//   WARN **不进 exit**（打印明细供 AI/人对照）——绝对 WARN 计数会让带存量 advisory 的仓库恒非零
+//   （本仓即有用户拍板保留的存量 WARN），工具就不可用了；编辑破坏的表现（如阶段索引漂移 WARN）
+//   在输出里一眼可见，由编辑者处置。
+// 用法：node .agents/scripts/edit-face-check.mjs [--root <仓库根>]（缺省 cwd；测试注入 EDIT_FACE_CHECK_SPAWN）
+// 测试：node templates/_agents/scripts/edit-face-check.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// LF 归一字节数（编辑时口径——工作区文件可能 CRLF，预算表口径注释声明「比较用 LF 归一」）
+export function lfBytes(text) {
+  return Buffer.byteLength(String(text).replace(/\r\n/g, '\n'), 'utf8');
+}
+
+// globToRe：rule-budgets.txt 行首路径 → 正则（支持 `*` 段内通配与结尾 `/` 目录前缀；其余字面）
+export function globToRe(pattern) {
+  const dir = pattern.endsWith('/');
+  let src = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+  if (dir) src += '.*';
+  return new RegExp(`^${src}${dir ? '' : '$'}`);
+}
+
+// budgetAdvisory：常驻面预算 advisory（编辑时口径）。files: Map<rel, 工作树文本>；budgetsText: 表原文。
+// 返回超限行 [{ rel, limit, actual }]；表缺失/行非法 → 空数组（advisory 层 fail-open）。
+export function budgetAdvisory(files, budgetsText) {
+  const out = [];
+  if (!budgetsText) return out;
+  for (const line of budgetsText.split(/\r?\n/)) {
+    const t = line.replace(/\r$/, '').trim();
+    if (!t || t.startsWith('#')) continue;
+    const m = t.match(/^(\S+)\s+(\d+)$/);
+    if (!m) continue;
+    const [, pattern, limitStr] = m;
+    const limit = Number(limitStr);
+    const re = globToRe(pattern);
+    for (const [rel, text] of files) {
+      if (!re.test(rel)) continue;
+      const actual = lfBytes(text);
+      if (actual > limit) out.push({ rel, limit, actual });
+    }
+  }
+  return out;
+}
+
+// runCheck：工作树面 check-loop（CHECK_LOOP_ROOT 全扫）。返回 { code, output, ms }。
+function runCheck(root, scriptDir) {
+  const t0 = Date.now();
+  const r = spawnSync(process.execPath, [path.join(scriptDir, 'check-loop.mjs')], {
+    cwd: root, encoding: 'utf8', windowsHide: true,
+    env: { ...process.env, CHECK_LOOP_ROOT: root },
+  });
+  return { code: r.status ?? 1, output: `${r.stdout || ''}${r.stderr || ''}`, ms: Date.now() - t0 };
+}
+
+export function main(root = process.cwd(), scriptDir = path.dirname(fileURLToPath(import.meta.url))) {
+  // ① 闭环判定（单源 check-loop，工作树全扫）
+  const ck = runCheck(root, scriptDir);
+  const warnCount = (ck.output.match(/\[WARN /g) || []).length;
+  // ② 常驻面预算 advisory（AGENTS.md + 预算表内文件的工作树字节）
+  let over = [];
+  try {
+    const budgetsPath = path.join(root, '.agents', 'rule-budgets.txt');
+    const budgetsText = fs.existsSync(budgetsPath) ? fs.readFileSync(budgetsPath, 'utf8') : null;
+    const files = new Map();
+    const agentsPath = path.join(root, 'AGENTS.md');
+    if (fs.existsSync(agentsPath)) files.set('AGENTS.md', fs.readFileSync(agentsPath, 'utf8'));
+    over = budgetAdvisory(files, budgetsText);
+  } catch { /* advisory 层 fail-open：预算读不到不阻断编辑时反馈 */ }
+
+  console.log(`▶ edit-face-check → ${root}（工作树面）`);
+  console.log(`  check-loop：${ck.code === 0 ? '通过' : `exit ${ck.code}`}，WARN ${warnCount} 条（${ck.ms}ms）——与本仓存量 advisory 对照看新增`);
+  // WARN 明细透传（编辑破坏的判读面——如删阶段索引会在此点名「阶段索引漂移」）
+  for (const line of ck.output.split(/\r?\n/)) {
+    if (/\[WARN /.test(line)) console.log('  ' + line.trim().slice(0, 200));
+  }
+  for (const { rel, limit, actual } of over) {
+    console.log(`  ⚠️ 预算 advisory：${rel} 工作树 ${actual}B > 上限 ${limit}B（编辑时口径；提交门以 rule-budget.sh 为准）`);
+  }
+  if (ck.code !== 0) {
+    console.error('❌ 闭环判定 hard 未过——先修复再提交（判定单源 check-loop，详见上方输出）');
+    return 2;
+  }
+  if (over.length > 0) {
+    console.error('⚠️ 常驻面预算 advisory 超限——建议编辑期就瘦，别留到提交门');
+    return 1;
+  }
+  console.log('✅ 编辑时快检完成（hard/预算两道均过；WARN 明细请对照处置）');
+  return 0;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('edit-face-check.mjs');
+if (isMain) {
+  let root = process.cwd();
+  const i = process.argv.indexOf('--root');
+  if (i > 0 && process.argv[i + 1]) root = path.resolve(process.argv[i + 1]);
+  process.exit(main(root));
+}

package/templates/_agents/scripts/edit-face-check.test.mjs

@@ -0,0 +1,98 @@
+// edit-face-check.test.mjs — 编辑时快检（2026-10-09 engine-quality-round2 B2）
+// 三面：纯函数（lfBytes/globToRe/budgetAdvisory）+ 端到端全绿面 + 破坏面（删阶段索引→WARN→exit 1、
+// 预算超限→exit 1）。判定零复刻：端到端经 CHECK_LOOP_ROOT 消费真 check-loop，fixture 复制脚本集。
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+let pass = 0, fail = 0;
+const check = (name, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+};
+
+const mod = await import(pathToFileURL(path.join(SRC, 'edit-face-check.mjs')).href);
+const { lfBytes, globToRe, budgetAdvisory } = mod;
+
+// ---- ① 纯函数 ----
+check('lfBytes：CRLF 归一计 UTF-8 字节', lfBytes('a\r\nb中文') === Buffer.byteLength('a\nb中文', 'utf8'));
+check('globToRe：精确路径', globToRe('AGENTS.md').test('AGENTS.md') && !globToRe('AGENTS.md').test('x/AGENTS.md'));
+check('globToRe：段内通配', globToRe('.agents/commands/*.md').test('.agents/commands/plan.md') && !globToRe('.agents/commands/*.md').test('.agents/commands/x/plan.md'));
+check('globToRe：目录前缀', globToRe('.agents/cache/').test('.agents/cache/a/b.json'));
+
+{
+  const files = new Map([
+    ['AGENTS.md', 'x'.repeat(120)],
+    ['.agents/commands/plan.md', 'y'.repeat(50)],
+  ]);
+  const budgets = '# 注释行\nAGENTS.md 100\n.agents/commands/*.md 200\n非法行\n';
+  const r = budgetAdvisory(files, budgets);
+  check('budgetAdvisory：超限单文件报、未超限不报、非法行跳过',
+    r.length === 1 && r[0].rel === 'AGENTS.md' && r[0].limit === 100 && r[0].actual === 120, JSON.stringify(r));
+  check('budgetAdvisory：表缺失 fail-open', budgetAdvisory(files, null).length === 0);
+}
+
+// ---- ② 端到端 fixture ----
+const SCRIPTS = ['check-loop.mjs', 'policy.mjs', 'stage-gates.mjs', 'check-metric-claims.mjs', 'check-hygiene.mjs', 'check-stage-index.mjs', 'gate-seg.mjs', 'workflow-enums.mjs', 'edit-face-check.mjs'];
+// 引用完整性哑文件（检查 4/6/7 的存在性判据——避免 fixture 结构性 WARN 淹没断言面）
+const REF_COMMANDS = ['new-task', 'plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review'];
+const REF_ROLES = ['implementer', 'independent-reviewer', 'ui-verifier'];
+function mkFixture({ breakStageIndex, overBudget }) {
+  const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'efc-'));
+  fs.mkdirSync(path.join(fx, '.agents', 'scripts'), { recursive: true });
+  for (const f of SCRIPTS) fs.copyFileSync(path.join(SRC, f), path.join(fx, '.agents', 'scripts', f));
+  for (const f of ['kit.json', 'workflow-modules.txt', 'workflow-enums.txt'])
+    if (fs.existsSync(path.join(SRC, '..', f))) fs.copyFileSync(path.join(SRC, '..', f), path.join(fx, '.agents', f));
+  fs.mkdirSync(path.join(fx, 'workflow', 'intents'), { recursive: true });
+  for (const d of ['specs', 'plans', 'incidents']) fs.mkdirSync(path.join(fx, 'workflow', d), { recursive: true });
+  for (const c of REF_COMMANDS) { fs.mkdirSync(path.join(fx, '.agents', 'commands'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'commands', `${c}.md`), `# ${c}\n`); }
+  for (const rname of REF_ROLES) { fs.mkdirSync(path.join(fx, '.agents', 'roles'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'roles', `${rname}.md`), `# ${rname}\n`); }
+  // 常驻面 AGENTS.md：阶段索引齐全（含 review）/ 破坏面删索引（破坏只在 AGENTS.md 侧——new-task
+  //   哑文件写全索引，钉检查 7 的双向语义差异）
+  const routes = '.agents/commands/plan.md → .agents/commands/design.md → .agents/commands/build.md → .agents/commands/test.md → .agents/commands/deploy.md → .agents/commands/maintain.md';
+  const reviewLine = breakStageIndex ? '' : '\n**横切**：.agents/commands/review.md\n';
+  const body = `# AGENTS\n\n## 阶段路由\n\n**入口**：.agents/commands/new-task.md\n**指令**：${breakStageIndex ? '（已删）' : routes}${reviewLine}\n`;
+  fs.writeFileSync(path.join(fx, 'AGENTS.md'), overBudget ? body + 'x'.repeat(200) : body);
+  fs.writeFileSync(path.join(fx, '.agents', 'commands', 'new-task.md'),
+    `# new-task\n\n| Plan | ${routes} | Review |\n`);
+  fs.writeFileSync(path.join(fx, '.agents', 'rule-budgets.txt'), `AGENTS.md ${overBudget ? 100 : 100000}\n`);
+  return fx;
+}
+
+{
+  // 全绿面：空 workflow + 引用齐全 + 预算内 → hard/预算两道过（exit 0）。
+  //   注：不要求零 WARN——check-loop 全扫对极简 fixture 有结构性 advisory（引用/角色形态），明细
+  //   承载给编辑者对照；exit 语义只钉 hard 与预算两道（绝对 WARN 计数会让存量仓库恒非零）。
+  const fx = mkFixture({});
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  check('E2E 全绿面：exit 0（hard/预算两道过）且 AGENTS.md 侧无索引漂移', r.status === 0 && !/AGENTS\.md 缺 .* 指令索引/.test(r.stdout || ''), `status=${r.status}\n${(r.stdout || '') + (r.stderr || '')}`.slice(0, 600));
+}
+
+{
+  // 破坏面：删阶段索引 → 检查 7 WARN 点名（明细承载编辑破坏——破坏面 vs 全绿面的差异就在输出；
+  //   hard 不误触：阶段索引是 warning 级，exit≠2）
+  const fx = mkFixture({ breakStageIndex: true });
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  const out = (r.stdout || '') + (r.stderr || '');
+  check('E2E 破坏面（删阶段索引）：WARN 点名 AGENTS.md 侧索引漂移且 hard 不误触', r.status !== 2 && /AGENTS\.md 缺 plan 指令索引/.test(out), `status=${r.status}\n${out.slice(0, 600)}`);
+}
+
+{
+  // 预算超限面：AGENTS.md 超上限 → exit 1（advisory 面单独可达——workflow 全绿）
+  const fx = mkFixture({ overBudget: true });
+  const driver = path.join(fx, 'driver.mjs');
+  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
+  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
+  const out = (r.stdout || '') + (r.stderr || '');
+  check('E2E 预算超限面：exit 1 且 advisory 点名', r.status === 1 && /预算 advisory/.test(out), `status=${r.status}\n${out.slice(0, 500)}`);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/fill-intent.mjs

@@ -5,6 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ENUMS } from './workflow-enums.mjs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const TODAY = new Date().toISOString().slice(0, 10);
 const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
@@ -36,12 +38,24 @@ const SECTIONS = [
   { title: '验收标准（可测试）', hint: '- [ ] <逐条可测试；写不出可测试判据 = 还没想清楚>\n\n> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。\n> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 hard-block。' },
 ];
 
-export function renderIntent({ topic, module, level, notes, date = TODAY }) {
+// renderIntent：骨架渲染（纯函数）。kbHits（2026-10-09 engine-quality-round3 W2）：kb-search 命中行
+// 数组（📄 行原文）——非空时替换「历史教训/防复发」节的检索占位行为实际命中列表（历史坑强制注入，
+// 手动路由与 pipeline-run 工单同权）；空/缺省保留占位（fail-open 口径）。子进程调用在 main，本函数保持无 IO。
+export function renderIntent({ topic, module, level, notes, date = TODAY, kbHits = [], kbFailNote = '' }) {
   if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
   const fm = '---\n状态: draft\n级别: ' + level + '\nrisk_level: ' + level + '\n日期: ' + date + '\n模块: ' + module + '\n备注: ' + (notes || '<可选：附注自由文本，check-loop 不解析>') + '\n---\n';
   let body = '# INTENT — ' + topic + '\n\n<!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->\n<!-- frontmatter 受限子集（2026-09-13）：每行 键: 值；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；risk_level=级别（混合治理风险泳道选道：L0/L1 协作道异步审计 / L2/L3 防御道同步确认）；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->\n\n';
   for (const { title, hint } of SECTIONS) {
-    body += '## ' + title + '\n\n' + hint + '\n\n';
+    let section = hint;
+    if (title === '历史教训/防复发') {
+      const placeholder = '- 检索结果：`node .agents/scripts/kb-search.mjs "<关键词>" --type incidents` 命中结果';
+      if (kbHits.length) {
+      const injected = '- 检索结果（自动注入 ' + kbHits.length + ' 条，同域历史——起草前先读其根因与防复发）：\n' + kbHits.map((h) => '  - ' + h).join('\n');
+      if (section.includes(placeholder)) section = section.replace(placeholder, injected);
+      }
+      else if (kbFailNote) section = section.replace('- 检索结果：', '- 检索结果' + kbFailNote + '\n- 检索结果：'); // 复核 P2-2：不可用时留手工命令注释行
+    }
+    body += '## ' + title + '\n\n' + section + '\n\n';
   }
   body += '## 确认与复核\n\n- 确认日期：\n- 确认人：用户（对话内明确放行即确认）\n- 确认范围：\n- 复核：L1 不要求独立复核\n';
   return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
@@ -52,7 +66,22 @@ if (isMain) {
   const a = parseArgs(process.argv.slice(2));
   if (!a.topic || !a.module || !a.output) fail('必填：--topic / --module / --output；选填：--level（默认 L1）/ --notes');
   if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
-  const { body } = renderIntent(a);
+  // 历史坑强制注入（2026-10-09 engine-quality-round3 W2）：同目录 kb-search 子进程检索同域历史
+  // （关键词 = topic ascii 段 + 模块名；--type incidents,plans——修复先例与计划同查）。fail-open：
+  // 非零/零命中/3s 超时 → kbHits 空 → 保留占位（与手动路由「AI 自觉检索」不同，此处机器保证尝试）。
+  let kbFailNote = '';
+  let kbHits = [];
+  try {
+    const words = (String(a.topic).toLowerCase().match(/[a-z0-9]{2,}/g) || []).slice(0, 2);
+    const kw = [...new Set([...words, String(a.module || '')].filter(Boolean))]; // 复核 P1-1：模块名入关键词（spec S2 口径）
+    const r = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'kb-search.mjs'),
+      ...kw, '--scope', 'workflow', '--type', 'incidents,plans', '-n', '4'], { encoding: 'utf8', timeout: 3000, windowsHide: true });
+    if (r.status === 0 && r.stdout) {
+      kbHits = r.stdout.split(/\r?\n/).filter((l) => l.startsWith('📄')).slice(0, 4);
+    if (!kbHits.length) kbFailNote = '（自动检索不可用或零命中，手工跑：node .agents/scripts/kb-search.mjs "<关键词>" --type incidents）';
+    }
+  } catch { /* fail-open：检索不可用保留占位 */ }
+  const { body } = renderIntent({ ...a, kbHits, kbFailNote });
   fs.mkdirSync(path.dirname(a.output), { recursive: true });
   fs.writeFileSync(a.output, body);
   console.log('✅ 已生成 intent 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / 模块 ' + a.module + '）');

package/templates/_agents/scripts/fill-intent.test.mjs

@@ -78,5 +78,18 @@ function check(name, cond, detail = '') {
   }
 }
 
+
+// ---- 历史坑注入 kbHits（2026-10-09 engine-quality-round3 W2）----
+{
+  const hits = ["📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB"];
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: hits });
+  check('kb 注入：命中行替换占位（含自动注入计数与 📄 原文）',
+    body.includes('检索结果（自动注入 1 条') && body.includes("📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB") && !body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
+}
+{
+  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: [] });
+  check('kb 零命中：保留占位（fail-open 口径）', body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
+}
+
 console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
 process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -280,5 +280,56 @@ if (existing.includes(BEGIN) && existing.includes(END)) {
 } else {
   out = (existing ? existing.replace(/\s*$/, '') + '\n\n' : HEADER) + inner + '\n';
 }
-fs.writeFileSync(METRICS_P, out, 'utf8');
+
+// ---- 趋势序列 + 确认负担（2026-10-09 engine-quality-round3 W4）----
+// ① 确认负担：本月 confirmations.jsonl 行数（stage=void 除外）与上月比（口径：每次 confirm-doc 调用
+//    落一行——「确认门调用次数」即确认负担的机器事实；void 为作废标记不计）。
+// ② 趋势序列：.agents/cache/metrics-history.jsonl 每日一行幂等（同日重跑覆盖）——metrics.md「趋势」
+//    行对比昨日 docsTotal/confirmCalls；history 损坏重建（fail-open）。
+const HISTORY_P = path.join('.agents', 'cache', 'metrics-history.jsonl');
+const voidExcluded = ledgerRows.filter((e) => e.stage !== 'void');
+const monthOf = (e) => (typeof e.ts === 'string' ? e.ts.slice(0, 7) : '');
+const thisMonth = month.slice(0, 7); // month 变量 = 生成锚月（YYYY-MM）
+const prevMonthDate = new Date(thisMonth + '-01T00:00:00Z');
+prevMonthDate.setUTCMonth(prevMonthDate.getUTCMonth() - 1);
+const prevMonth = prevMonthDate.toISOString().slice(0, 7);
+const confirmThis = voidExcluded.filter((e) => monthOf(e) === thisMonth).length;
+const confirmPrev = voidExcluded.filter((e) => monthOf(e) === prevMonth).length;
+const confirmDelta = confirmPrev > 0 ? Math.round(((confirmThis - confirmPrev) / confirmPrev) * 100) : null;
+
+// docsTotal：metrics 主表本月行的文档数列（第一数值列）——从 row 提取，避免重复统计逻辑
+const docsTotal = docs.files; // 直取作用域变量（正则提取曾因「287（活跃…）」复合列失配——round3 实测修正）
+
+// history 读写（fail-open：损坏重建）
+let history = [];
+try {
+  if (fs.existsSync(HISTORY_P)) {
+    history = fs.readFileSync(HISTORY_P, 'utf8').split(/\r?\n/).filter(Boolean)
+      .map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  }
+} catch { history = []; }
+const today = new Date().toISOString().slice(0, 10);
+history = history.filter((h) => h && h.date !== today); // 同日幂等：覆盖当日行
+history.push({ date: today, docsTotal, passRate: funnel.closed ? Math.round((funnel.once / funnel.closed) * 100) + '%' : '', confirmCalls: confirmThis, savedAt: new Date().toISOString() });
+try {
+  fs.mkdirSync(path.dirname(HISTORY_P), { recursive: true });
+  const tmpH = HISTORY_P + '.tmp';
+  fs.writeFileSync(tmpH, history.map((h) => JSON.stringify(h)).join('\n') + '\n');
+  fs.renameSync(tmpH, HISTORY_P);
+} catch { /* history 写失败不影响 metrics.md 主产物 */ }
+
+// 趋势行（对比昨日快照）
+const yesterday = history.filter((h) => h.date !== today).slice(-1)[0];
+const trendParts = [];
+if (yesterday) {
+  trendParts.push('docs ' + docsTotal + '（昨日 ' + (yesterday.docsTotal ?? '?') + '）');
+  trendParts.push('确认调用 ' + confirmThis + '（昨日 ' + (yesterday.confirmCalls ?? '?') + '）');
+} else {
+  trendParts.push('无前值（history 首日）');
+}
+const trendLine = '> 趋势（环比昨日）：' + trendParts.join('；') + '；确认调用本月 ' + confirmThis + ' 次（上月 ' + confirmPrev + ' 次' + (confirmDelta === null ? '' : '，' + (confirmDelta >= 0 ? '+' : '') + confirmDelta + '%') + '；void 不计）';
+
+// 注入「闭环漏斗」节尾（inner 的 FUNNEL 段之后、END 之前）
+
+fs.writeFileSync(METRICS_P, out.replace(END, trendLine + '\n\n' + END), 'utf8');
 console.log(`✅ 已更新 workflow/metrics.md（${month} 行；共 ${rows.length} 个月）`);

package/templates/_agents/scripts/policy.mjs

@@ -3,6 +3,7 @@
 // kit.json 缺 policyVersion、或版本不在表内：回退版本 1（不启用版本 2 的 approved 锚）。
 // audit 不在本表：缺省视为全量检查（已装仓库与无 kit 的测试夹具）；init 新装显式写 false。
 import fs from 'node:fs';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 
 export const POLICIES = {
@@ -94,6 +95,30 @@ export const POLICIES = {
     // 消费方：检查 8 的 verifyDocInWindow（done ts ≥ 本值才启用精确匹配）。
     verifyDocSince: '2026-10-08T09:37:35Z',
   },
+  // 版本 7 = 版本 6 的全部键 + scopeSince（台账「机器派生改动面」的生效时刻，2026-10-09 审查 A1 干净版）。
+  // 背景：委托代录的授权凭据是 `--delegated` 的**用户原话**——机器无法校验自由文本，AI 可无成本复用同一句
+  // （本仓实测「可以」133 次、「确认」60 次），且台账 406 行里仅 6 行为 tty。整条授权链的源头不可核对，
+  // 下游的哈希链/指纹对账/内容绑定全建得很好却是建在空地基上。
+  // 干净版解法：**改动面改由机器派生，AI 无输入面**——confirm-doc 落账时自动记
+  // `scope:{files:[…], sha256}`（被确认文档 + `git status --porcelain` 实测的未提交改动集，归一去重排序后
+  // 取 sha256）。AI 无法伪造这个字段，因为它根本不参与输入；事后对质问的是「这 N 个文件」，而不是一句可复用的原话。
+  // 本版本只加一个开关键：**缺键（v1-v6）时该子检查整体跳过**，存量 406 行零新增告警；抄全键仍是铁律。
+  7: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-26',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+    check17UnclosedAfter: '0.8.0',
+    stageGateSince: '2026-09-29',
+    riskLevelSince: '2026-10-01',
+    verifySince: '2026-10-07',
+    verifyDocSince: '2026-10-08T09:37:35Z',
+    // 生效「时刻」（ISO 8601，UTC）而非日期：本日 04:29Z 已有一批旧口径台账行写入，日期粒度会把它们
+    // 纳入受审范围产出不可消退告警——沿 v6 verifyDocSince 升级为时刻的同款教训。
+    // 消费方：check-loop 检查 15 的 scope 子项（台账行 ts ≥ 本值才判）。
+    scopeSince: '2026-10-09T11:24:43Z',
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -142,3 +167,40 @@ export function hasFreshVerifyLine(lines, now = Date.now(), doc = null) {
   }
   return false;
 }
+
+// ---- 台账哈希链（2026-10-09 engine-quality-round2 D）----
+// 单源（confirm-doc appendLedger 写入与 check-loop 检查 15 验链共用——判定零复刻）：
+// ledgerChainHash(row, prevHash) = sha256(prevHash + JSON.stringify(row))。
+//   row = 台账行**去掉 prevHash/hash 两字段**后的对象（键序 = 写入序，JSON.parse 保序 → 重算一致）；
+//   prevHash = 上一行的 hash（上一行无 hash/文件首行 → ''——历史行零回填，链从首个带 hash 行起算）。
+// 边界（诚实声明）：整文件重写可重建完整链，不可机器防——兜底 = 台账文件自身的 git 历史
+//   （check-ledger-invariant 已扫 append-only 历史）；本链堵的是「就地改/删中间行」这一高频伪造面，
+//   把主动伪造从静默可行抬到必留断链痕迹。
+export function ledgerChainHash(row, prevHash) {
+  return createHash('sha256').update((prevHash || '') + JSON.stringify(row)).digest('hex');
+}
+
+// ---- 台账 scope（机器派生改动面，2026-10-09 审查 A1 干净版）----
+// scopeDigest(files) = {files, sha256}：files 归一（反斜杠→posix）、去重、排序；sha256 = files.join('\n') 的摘要。
+// **单源**（confirm-doc 落账侧构造与 check-loop 检查 15 校验侧重算共用——防两处归一/排序口径漂移，
+//   N3 教训同款）：任一侧改了口径而另一侧没改，台账会整体判失效。
+// 边界（诚实声明）：scope 是**机器实测**的「确认时刻工作树处于改动态的文件集合」，不是「本次任务应改什么」
+// 的语义判定——它能证明「你放行时盘面上就是这些文件在动」，不能证明「这些改动就是你要的」。
+// 语义正确性仍由指纹（文档内容）+ commit diff（事后对质）承担。
+export function scopeDigest(files) {
+  const norm = [...new Set((Array.isArray(files) ? files : [])
+    .map((f) => String(f).replace(/\\/g, '/').replace(/^\.\//, ''))
+    .filter(Boolean))]
+    .sort();
+  return { files: norm, sha256: createHash('sha256').update(norm.join('\n'), 'utf8').digest('hex') };
+}
+
+// scopeMatches(row)：台账行自带的 scope 是否与按其 files 重算的结果逐字一致。
+// 用于检出「行里改了 files 却没同步 sha256」的手改形态（哈希链能兜住就地改，但整文件重写可重建链——
+//   同一信任边界内的第二道，见 ledgerChainHash 边界声明）。
+export function scopeMatches(row) {
+  if (!row || typeof row !== 'object' || !row.scope) return false;
+  const s = row.scope;
+  if (!Array.isArray(s.files) || typeof s.sha256 !== 'string') return false;
+  return scopeDigest(s.files).sha256 === s.sha256;
+}