agentic-flow-kit 1.5.0 → 1.6.0

package/templates/_agents/scripts/check-loop.mjs

@@ -111,7 +111,7 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { loadEnums } from './workflow-enums.mjs';
 import { runCheck16 } from './check-metric-claims.mjs';
-import { auditEnabled, loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
+import { auditEnabled, loadKitPolicy, hasFreshVerifyLine, ledgerChainHash } from './policy.mjs';
 import { laneOfEntry } from './stage-gates.mjs';
 // MARK_RE：incident 留痕形态的单源（第七轮复核 N3——此前 check-loop 内联复制一份同口径字面量，
 // 两处靠注释与人工同步；改为复用 stage-gates.mjs 的导出，从结构上消除漂移可能）
@@ -120,6 +120,8 @@ import { MARK_RE, approvedTraceHit } from './stage-gates.mjs';
 // 本文件只组装 ctx 并消费返回的文案数组（先例 = check-metric-claims.mjs 承载检查 16）。
 // 调用点位置即输出顺序位：须留在检查 10 与 12 之间以保持 warnings 行序（稳定输出契约），见该模块内注释。
 import { runCheckHygiene } from './check-hygiene.mjs';
+// 检查 7 拆模块（2026-10-09 engine-quality-round2 A1）：阶段索引同步迁 check-stage-index.mjs
+import { runCheckStageIndex } from './check-stage-index.mjs';
 import { gateSeg, finishSegs, makeCollector } from './gate-seg.mjs';
 
 // CHECK_LOOP_GIT：测试注入钩子（指向不存在/不可执行路径可稳定触发 spawn 异常）；未设置时与原行为逐字节一致（2026-10-05-gitout-fail-open）
@@ -592,19 +594,10 @@ export function runCheckLoop(opts = {}) {
     if (modelHits.length) warnings.push(`- [WARN 宿主耦合] 薄 Adapter 不应固定模型:\n${modelHits.join('\n')}`);
   }
 
-  // --- 6. 阶段索引同步 [warning] ---
-  markGate('6', '阶段索引同步');
-  for (const cmd of ['plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review']) {
-    for (const doc of ['AGENTS.md', '.agents/commands/new-task.md']) {
-      // existsSync 守卫（2026-10-06-check19-entry-enoent 同类）：两文件可合法缺失（下方 text 判空本就
-      // 预期缺失态），fail-loud fs 读下按空跳过、不再响亮出账
-      const docPath = path.join(ROOT, doc);
-      const text = fs.existsSync(docPath) ? linesOf(docPath) : null;
-      if (text && !text.some((l) => l.includes(`.agents/commands/${cmd}.md`))) {
-        warnings.push(`- [WARN 阶段索引漂移] ${doc} 缺 ${cmd} 指令索引(两处阶段表须同步维护)`);
-      }
-    }
-  }
+  // --- 6. 阶段索引同步 [warning]（2026-10-09 engine-quality-round2 A1：实现迁 check-stage-index.mjs——
+  //     先例 check-hygiene / check-metric-claims；段 id 沿 sh 版 '6'，清单编号 7 与文案逐字不动；
+  //     调用点位置即输出顺序契约）---
+  warnings.push(...runCheckStageIndex({ root: ROOT, linesOf, gateStats }));
 
   // --- 共享：文件「首次加入 git」的日期索引（2026-09-28 check8-git-anchor）---
   // 用途：检查 8 的生效日锚从**可手填的文件名前缀**（项目命名规范本身即 `YYYY-MM-DD-<主题>`，作者
@@ -618,18 +611,13 @@ export function runCheckLoop(opts = {}) {
   // 非 git / 命令失败 → null，调用方按既有「非 git 跳过」语义退化（不 fail-loud）。
   // 注：检查 10 需要的是「文件→加入 commit」+「commit→文件清单」两份映射（判断同提交是否触及迁移 SQL），
   // 与本索引「文件→日期」不同构，故**不合并**——避免把两处判据耦死。
-  const addedDates = (() => {
-    if (gitOut(['rev-parse', '--git-dir']) === null) return null;
-    const log = gitOut(['log', '--diff-filter=A', '--format=@%aI', '--name-only']);
-    if (log === null) return null;
-    const m = new Map();
-    let cur = null;
-    for (const line of log.split('\n')) {
-      if (line.startsWith('@')) { cur = line.slice(1); continue; }
-      if (line.trim() && cur && !m.has(line.trim())) m.set(line.trim(), cur); // 新→旧序首遇 = 最早
-    }
-    return m;
-  })();
+  // addedDates（2026-10-09 engine-quality-round3 W1）：全史解析走持久缓存（HEAD 键）——
+  // 同 HEAD 多入口复跑（verify/edit-face-check/pre-commit/CI）不再重复全算；git-dir 探测保留在前。
+  const addedDates = gitOut(['rev-parse', '--git-dir']) === null ? null : addedDatesWithCache({
+    head: gitOut(['rev-parse', 'HEAD']),
+    gitLog: () => gitOut(['log', '--diff-filter=A', '--format=@%aI', '--name-only']),
+    cachePath: path.join(ROOT, '.agents', 'cache', 'added-dates.json'),
+  });
   // 某文档「首次加入日期」（YYYY-MM-DD）；不可判定（非 git / 查不到）返回 ''
   const addedDateOf = (absDoc) => {
     if (!addedDates) return '';
@@ -983,10 +971,39 @@ export function runCheckLoop(opts = {}) {
     const EFFECTIVE = kitPolicy.confirmDocsEffective;
     const ledgerPath = path.join(ROOT, '.agents', 'confirmations.jsonl');
     const ledger = [];
+    const ledgerBadLines = []; // 坏行（JSON.parse 失败）的物理行号（复核 P2-1：报文行号须对齐物理行）
     if (fs.existsSync(ledgerPath)) {
-      for (const line of linesOf(ledgerPath) || []) {
+      for (const [lineNo, line] of (linesOf(ledgerPath) || []).entries()) {
         if (!line.trim()) continue;
-        try { ledger.push(JSON.parse(line)); } catch { /* 坏行跳过 */ }
+        try { ledger.push(JSON.parse(line)); } catch { ledgerBadLines.push(lineNo + 1); }
+      }
+    }
+    // 台账哈希链校验（2026-10-09 engine-quality-round2 D；写入侧=confirm-doc appendLedger，哈希单源
+    // policy.ledgerChainHash——判定零复刻）。判据：连续带 hash 行段内，① prevHash 须等于前一带 hash
+    // 行的 hash（无 hash 行后链段重启 ''，与写入侧读末行口径一致）；② hash 须可重算一致。
+    // **坏行口径（复核 P2-1 勘误，此前注释误称「与写入侧一致」）**：坏行被本解析整体剔除、不重置游标
+    // ——坏行后写入的链行（写入侧读末行遇坏行 prevHash=''）验链必失配出账。这是**预期 fail-loud**
+    // （坏行本身即台账完整性事故，应人工查验），非口径一致场景。
+    // 断裂 = hard「台账链断裂」（只报首断**物理行号** + 影响行计数，不做逐行刷屏）——就地改/删中间行
+    // 必留痕迹；边界：整文件重写可重建链，不可机器防，兜底 = 台账自身 git 历史（check-ledger-invariant）。
+    // 历史行（v1.5.0 前，无 hash 字段）零回填零告警——向后兼容。
+    {
+      let prevHash = '';
+      let brokenAt = 0;
+      let brokenCount = 0;
+      ledger.forEach((row, idx) => {
+        if (!row || typeof row.hash !== 'string') { prevHash = ''; return; } // 存量行/无链字段 → 链段重启
+        const { hash, prevHash: p, ...rest } = row;
+        const ok = (p ?? '') === prevHash && ledgerChainHash(rest, p ?? '') === hash;
+        if (!ok) {
+          if (!brokenAt) brokenAt = idx + 1;
+          brokenCount++;
+        }
+        prevHash = hash;
+      });
+      if (brokenAt) {
+        const physical = brokenAt + ledgerBadLines.filter((n) => n <= brokenAt).length; // 物理行号（复核 P2-1：剔除坏行会令数组下标漂移）
+        blockers.push(`- [台账链断裂] confirmations.jsonl 自第 ${physical} 行（物理）起哈希链校验失败（共 ${brokenCount} 行不一致——append-only 台账出现就地改/删痕迹；prevHash 接续或内容重算不符。整文件重写不可机器防，对质走台账自身 git 历史）`);
       }
     }
     // incidents 侧覆盖（2026-09-27 gate-coverage）：fixed/closed 为已确认态（open = 起草态不加门——
@@ -1437,6 +1454,43 @@ export function fmStatus(text) {
 // lines 已 CRLF 归一（split(/\r?\n/)），frontmatter 区内首个「状态:」行保分隔符换值为 prev（`状态:  done`
 // 双空格 → `状态:  approved`——与前向按原行字面计算对称，非规范分隔符不误伤；行尾空白等更奇异格式仍会
 // 失配，触发前提本身已违反「确认落态唯一入口」约定，接受），全文剔「确认指纹:」行后 join('\n') 再 sha256。
+// parseAddedDatesLog：git log（--diff-filter=A --format=@%aI --name-only）文本 → Map(rel → 加入 ISO 时间)。
+// 新→旧序首遇 = 最新一次加入（复核 P2-1 勘误：旧注释「最早」系误述——行为原样零复刻，检查 8 isNew 取最新加入日期更保守）。
+export function parseAddedDatesLog(logText) {
+  const m = new Map();
+  let cur = null;
+  for (const line of logText.split('\n')) {
+    if (line.startsWith('@')) { cur = line.slice(1); continue; }
+    if (line.trim() && cur && !m.has(line.trim())) m.set(line.trim(), cur);
+  }
+  return m;
+}
+
+// addedDatesWithCache：addedDates 的持久缓存层（2026-10-09 engine-quality-round3 W1）。
+// 键 = HEAD sha（同 commit 祖先不可变 → log 幂等；rebase 必改 HEAD 必重算；复核 P2-4：shallow→unshallow 同 HEAD 可见性增长有陈旧窗口——后果退化为旧行为 addedDateOf 返回 ""，HEAD 变化自愈）；
+// 缓存位于 .agents/cache/（gitignored 运行态）；读/写任一失败 fail-open 回退全算（门禁不失效）；
+// head 缺省（detached --rev worktree 等场景）→ 不读写缓存直接全算（语义不变）。
+export function addedDatesWithCache({ head, gitLog, cachePath }) {
+  if (head) {
+    try {
+      const c = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+      if (c && c.head === head && c.map && Object.keys(c.map).length) return new Map(Object.entries(c.map));
+    } catch { /* 缓存缺失/损坏 → 全算 */ }
+  }
+  const log = gitLog();
+  if (log === null) return null;
+  const m = parseAddedDatesLog(log);
+  if (head) {
+    try {
+      fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+      const tmp = cachePath + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify({ head, map: Object.fromEntries(m), savedAt: new Date().toISOString() }) + '\n');
+      fs.renameSync(tmp, cachePath);
+    } catch { /* 写失败 fail-open：本轮已用全算结果，缓存留待下次 */ }
+  }
+  return m;
+}
+
 export function bindingSha256(lines, prevStatus) {
   const isDelim = (l) => /^---\s*$/.test(l);
   const out = [];

package/templates/_agents/scripts/check-loop.test.mjs

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { computeFingerprint } from './confirm-doc.mjs';
 import { POLICIES, loadKitPolicy } from './policy.mjs';
 import { entryConfirmed, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
+import { parseAddedDatesLog, addedDatesWithCache } from './check-loop.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
@@ -2902,5 +2903,70 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   rmfix(T);
 }
 
+// ---- 场景 21:台账哈希链（2026-10-09 engine-quality-round2 D）——篡改必抓 / 存量零告警 ----
+{
+  // 21a：连续带 hash 行中间被篡改（改 quote 不动链字段）→ hard「台账链断裂」
+  const T = mkfix();
+  const { ledgerChainHash } = await import('./policy.mjs');
+  const chainRow = (prevHash, fields) => {
+    const row = { ...fields, prevHash };
+    return { ...row, hash: ledgerChainHash(fields, prevHash) };
+  };
+  const row1 = chainRow('', { ts: '2026-10-09T01:00:00Z', doc: 'workflow/intents/2026-10-09-a.md', stage: 'approved', fingerprint: 'a'.repeat(64), prev: 'draft', source: 'chat-delegated', quote: '真原话一' });
+  const row2 = chainRow(row1.hash, { ts: '2026-10-09T02:00:00Z', doc: 'workflow/intents/2026-10-09-a.md', stage: 'done', fingerprint: 'b'.repeat(64), prev: 'approved', source: 'chat-delegated', quote: '真原话二' });
+  // 篡改第一行 quote（链字段不动 → hash 失配）
+  const tampered = { ...row1, quote: '篡改后的假原话' };
+  writeLedger(T, [tampered, row2]);
+  let r = run(T);
+  let out = outOf(r);
+  check('场景 21a 链断裂：中间行篡改 → hard 台账链断裂（指首断行号）',
+    r.status !== 0 && out.includes('台账链断裂') && /第 1 行/.test(out), `exit=${r.status}\n${out.slice(-400)}`);
+  // 反证还原：篡改行恢复原 quote → 链复通（断言非恒绿）
+  writeLedger(T, [row1, row2]);
+  r = run(T);
+  check('场景 21b 反证还原：篡改修复 → 链校验通过', !outOf(r).includes('台账链断裂'), outOf(r).slice(-300));
+  rmfix(T);
+}
+{
+  // 21c：全无 hash 的存量台账（v1.5.0 前形态）→ 零链告警（向后兼容）
+  const T = mkfix();
+  writeLedger(T, [
+    { ts: '2026-09-20T01:00:00Z', doc: 'workflow/intents/2026-09-20-legacy.md', stage: 'approved', fingerprint: 'c'.repeat(64), prev: 'draft' },
+    { ts: '2026-09-20T02:00:00Z', doc: 'workflow/intents/2026-09-20-legacy.md', stage: 'done', fingerprint: 'd'.repeat(64), prev: 'approved' },
+  ]);
+  const r = run(T);
+  check('场景 21c 存量无 hash 行：零链告警（不追溯）', !outOf(r).includes('台账链断裂'), outOf(r).slice(-300));
+  rmfix(T);
+}
+
+
+// ---- 场景 22:addedDates 持久缓存（2026-10-09 engine-quality-round3 W1）----
+{
+  const log = '@2026-10-02T10:00:00+08:00\nworkflow/intents/a.md\nworkflow/plans/a.md\n@2026-10-01T09:00:00+08:00\nworkflow/intents/a.md\n';
+  const m = parseAddedDatesLog(log);
+  check('场景 22a 提取：新→旧序首遇 = 最新一次加入（原 IIFE 语义零复刻；注释「最早」为历史误述）', m.get('workflow/intents/a.md') === '2026-10-02T10:00:00+08:00' && m.get('workflow/plans/a.md') === '2026-10-02T10:00:00+08:00', JSON.stringify([...m]));
+}
+{
+  const cacheP = path.join(os.tmpdir(), 'adc-' + Date.now() + '.json');
+  let gitLogCalls = 0;
+  const gitLog = () => { gitLogCalls++; return '@2026-10-01T09:00:00+08:00\nworkflow/intents/a.md\n'; };
+  const head = 'head-sha-1';
+  const m1 = addedDatesWithCache({ head, gitLog, cachePath: cacheP });
+  const m2 = addedDatesWithCache({ head, gitLog, cachePath: cacheP });
+  check('场景 22b 缓存命中：同 HEAD 二次调用 gitLog 仅 1 次且结果一致',
+    gitLogCalls === 1 && m1.get('workflow/intents/a.md') === m2.get('workflow/intents/a.md'), 'calls=' + gitLogCalls);
+  const m3 = addedDatesWithCache({ head: 'head-sha-2', gitLog, cachePath: cacheP });
+  check('场景 22c HEAD 变更：重算（gitLog 计 2 次）', gitLogCalls === 2 && m3.get('workflow/intents/a.md') === '2026-10-01T09:00:00+08:00', 'calls=' + gitLogCalls);
+  fs.writeFileSync(cacheP, '{broken json');
+  const before = gitLogCalls;
+  const m4 = addedDatesWithCache({ head: 'head-sha-2', gitLog, cachePath: cacheP });
+  check('场景 22d 缓存损坏：fail-open 全算（gitLog 再调 1 次）且结果正确',
+    gitLogCalls === before + 1 && m4.get('workflow/intents/a.md') === '2026-10-01T09:00:00+08:00', 'calls=' + gitLogCalls);
+  const before2 = gitLogCalls;
+  addedDatesWithCache({ head: null, gitLog, cachePath: cacheP });
+  check('场景 22e 无 head：不读缓存直接全算（gitLog 再调 1 次）', gitLogCalls === before2 + 1, 'calls=' + gitLogCalls);
+  fs.rmSync(cacheP, { force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/check-stage-index.mjs

@@ -0,0 +1,40 @@
+// check-stage-index.mjs — check-loop 检查 7 模块（阶段索引同步，2026-10-09 engine-quality-round2 A1）
+// 拆分先例 = check-hygiene.mjs（检查 2/9/11/12/13）/ check-metric-claims.mjs（检查 16）：
+//   ctx 传入既有 helper（linesOf——读异常响亮出账 + 按空文档降级的语义承载者，零复刻），
+//   模块只返回 warnings 数组，不打印、不 exit、不改 ctx。
+// 输出顺序契约：调用点位置即 warnings 插入序（check-loop 原位调用，段 id 沿 sh 版 '6'——清单编号 7
+//   不动，gate-checklist 按 id 消费面不受影响）。
+// 判据（沿 sh 版逐条）：AGENTS.md 与 .agents/commands/new-task.md 须各含全部阶段指令路径串
+//   `.agents/commands/<cmd>.md`（双向索引）；缺任一 = WARN。两文件可合法缺失（text 判空预期缺失态）。
+// 测试：node templates/_agents/scripts/check-stage-index.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import { gateSeg, finishSegs, makeCollector, appendSegs } from './gate-seg.mjs';
+
+const STAGE_CMDS = ['plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review'];
+const FACE_DOCS = ['AGENTS.md', '.agents/commands/new-task.md'];
+
+export function runCheckStageIndex(ctx) {
+  const { root: ROOT, linesOf } = ctx;
+  const warnings = [];
+  // 插桩（selfmeasure 先例）：局部收集器 + appendSegs 并入全局——模块产出局部数组，直接共用全局
+  // 游标会错账（check-hygiene.mjs:36-39 实测教训）
+  const localStats = makeCollector(warnings, []);
+  const markGate = (id, label) => { if (ctx.gateStats) gateSeg(localStats, id, label); };
+
+  markGate('6', '阶段索引同步');
+  for (const cmd of STAGE_CMDS) {
+    for (const doc of FACE_DOCS) {
+      // existsSync 守卫（2026-10-06-check19-entry-enoent 同类）：两文件可合法缺失（下方 text 判空本就
+      // 预期缺失态），fail-loud fs 读下按空跳过、不再响亮出账
+      const docPath = path.join(ROOT, doc);
+      const text = fs.existsSync(docPath) ? linesOf(docPath) : null;
+      if (text && !text.some((l) => l.includes(`.agents/commands/${cmd}.md`))) {
+        warnings.push(`- [WARN 阶段索引漂移] ${doc} 缺 ${cmd} 指令索引(两处阶段表须同步维护)`);
+      }
+    }
+  }
+
+  if (ctx.gateStats) appendSegs(ctx.gateStats, finishSegs(localStats));
+  return warnings;
+}

package/templates/_agents/scripts/check-stage-index.test.mjs

@@ -0,0 +1,77 @@
+// check-stage-index.test.mjs — 检查 7 模块直测（2026-10-09 engine-quality-round2 A1）
+// 四面：全绿 / AGENTS 侧缺索引 / new-task 文件缺失合法 / gate-seg 段归属（局部收集器并入）
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { runCheckStageIndex } from './check-stage-index.mjs';
+import { makeCollector, finishSegs } from './gate-seg.mjs';
+
+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}` : ''}`); }
+};
+
+// ctx 构造：linesOf 提供读异常→null 语义（与 check-loop 内部实现同语义；「判定零复刻」指模块不重写
+// 判据，测试 fixture 提供测试版 helper 是 check-hygiene.test 先例）
+function makeCtx(root, overrides = {}) {
+  const fileLinesCache = new Map();
+  const linesOf = (file) => {
+    if (!fileLinesCache.has(file)) {
+      let lines = null;
+      try { lines = fs.readFileSync(file, 'utf8').split(/\r?\n/); } catch { lines = null; }
+      fileLinesCache.set(file, lines);
+    }
+    return fileLinesCache.get(file);
+  };
+  return { root, linesOf, ...overrides };
+}
+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 mkRoot = (agentsBody, newTaskBody, { noAgents, noNewTask } = {}) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'csi-'));
+  fs.mkdirSync(path.join(root, '.agents', 'commands'), { recursive: true });
+  if (!noAgents) fs.writeFileSync(path.join(root, 'AGENTS.md'), agentsBody);
+  if (!noNewTask) fs.writeFileSync(path.join(root, '.agents', 'commands', 'new-task.md'), newTaskBody);
+  return root;
+};
+const FULL = `# AGENTS\n\n${ROUTES}\n\n**横切**：.agents/commands/review.md\n`;
+const FULL_NT = `# new-task\n\n| Plan | ${ROUTES} | Review(.agents/commands/review.md) |\n`;
+
+{
+  // ① 双面全索引 → 零告警
+  const root = mkRoot(FULL, FULL_NT);
+  const r = runCheckStageIndex(makeCtx(root));
+  check('① 双面全索引 → 零告警', r.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ② AGENTS 侧缺 plan → 仅 AGENTS.md 侧告警（new-task 索引齐全不误报）
+  const root = mkRoot(FULL.replace('.agents/commands/plan.md → ', ''), FULL_NT);
+  const r = runCheckStageIndex(makeCtx(root));
+  check('② AGENTS 侧缺 plan → WARN 点名 AGENTS.md',
+    r.some((w) => w.includes('AGENTS.md 缺 plan 指令索引')), JSON.stringify(r));
+  check('② new-task 侧不告警（其索引齐全）', !r.some((w) => w.includes('new-task.md 缺')), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ③ new-task 文件不存在 = 合法缺失态（existsSync 守卫）→ 零告警
+  const root = mkRoot(FULL, FULL_NT, { noNewTask: true });
+  const r = runCheckStageIndex(makeCtx(root));
+  check('③ new-task 文件缺失 → 合法缺失零告警', r.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+{
+  // ④ gate-seg 段归属：ctx.gateStats 在场时段 '6' 入账、warns 与实际 WARN 数一致（selfmeasure 接线
+  //   教训：模块须用局部收集器 + appendSegs，直接共用全局游标会错账）
+  const root = mkRoot(FULL.replace('.agents/commands/plan.md → ', ''), FULL_NT);
+  const stats = makeCollector([], []);
+  const r = runCheckStageIndex(makeCtx(root, { gateStats: stats }));
+  const seg6 = finishSegs(stats).filter((s) => s.id === '6');
+  check('④ gate-seg：段 6 入账一次且 warns 与实际 WARN 数一致',
+    seg6.length === 1 && seg6[0].warns === r.length && r.length === 1,
+    JSON.stringify({ seg6, ret: r }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -39,7 +39,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
 import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy, hasFreshVerifyLine } from './policy.mjs';
+import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash } from './policy.mjs';
 
 // hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
 // policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
@@ -120,10 +120,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;
 }
 

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

@@ -104,6 +104,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-'));

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);