agentic-flow-kit 1.8.7 → 2.1.0

package/templates/engine/.agents/scripts/archive-sweep.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// archive-sweep — workflow 终态件滚动归档（2026-10-09）
+// **归档单位 = 同名家族**（intent/spec/plan/incident 同名文件同进同退）：check-loop 检查 1 的结构配对
+//   是「家族双向在场」审计——intent 缺 spec/plan、spec/plan 缺 intent、incident 缺 plan/spec 均为
+//   hard-block（首批执行 89 篇按单篇准入产生 57 处配对断裂的返工实证）。家族任一成员不满足条件
+//   （非终态/未满窗/被活跃引用/无日期），整族留守。
+// 终态时间三级锚（2026-10-13 修锚）：confirmations 终态行 ts（精确）→ **内容 last-touch**（回退）→ 文件名日期
+// 回退级原用 git last-touch，被批量提交系统性污染：2026-09-13 frontmatter 迁移（223 文件）、
+// 2026-09-28 两步式留痕补录（193+193 文件）把 ~386 篇老文档的 last-touch 刷成当日 → 21 天窗口
+// 恒不满足，实测候选仅 5 篇（真实终态且零引用者 733 篇）。修法：回退级改「最后一次**正文**变更」
+// ——frontmatter-only 提交（状态/确认指纹/备注行增删改）不计入，因其不改变文档的实质内容与
+// 归档安全性（归档只依赖终态 + 无活跃引用，二者均由当前 frontmatter 与引用扫描独立判定）。
+// 判定：逐提交比对 blob，剥 frontmatter 区后正文逐字节相同 → 视为 frontmatter-only，跳过。
+// 归档形态：git mv → workflow/archive/<家族最晚终态月>/{类型}/（kit-engine 先例同款；check-loop docFiles
+// 与配对门只扫四目录直下；kb-search 已扩 archive/<批次>/<type> 覆盖——同日返工中补齐）
+// 用法：
+// node .agents/scripts/archive-sweep.mjs # dry-run（缺省），--window 21
+// node .agents/scripts/archive-sweep.mjs --window 21 --execute # git mv 执行
+// 测试面已随引擎减重退役（2026-10-28，owner 决策），本脚本现无测试兜底
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadAllConfirmations } from './ledger-loader.mjs';
+
+const DIRS = ['intents', 'specs', 'plans', 'incidents'];
+export const TERMINAL = new Set(['done', 'superseded', 'cancelled', 'closed']);
+export const ACTIVE = new Set(['draft', 'approved', 'open', 'fixed']);
+
+export function parseStatus(text) {
+ const lines = text.split(/\r?\n/);
+ const end = lines.indexOf('---', 1);
+ for (let i = 1; i < (end === -1 ? Math.min(lines.length, 15) : end); i++) {
+ const s = /^状态:\s*(\S+)/.exec(lines[i]);
+ if (s) return s[1];
+ }
+ return '';
+}
+
+// bodyOf(text)：剥 frontmatter 区（首 --- 至闭合 ---）后的正文，CRLF 归一。
+// 用途：判定一次提交是否只动了 frontmatter（状态/确认指纹/备注）——此类提交不改变文档实质内容，
+// 不应刷新「内容 last-touch」（2026-10-13 修锚，见文件头注释）。无 frontmatter → 全文即正文。
+export function bodyOf(text) {
+ const norm = String(text).replace(/\r\n/g, '\n');
+ const lines = norm.split('\n');
+ if (!/^---\s*$/.test(lines[0] || '')) return norm;
+ for (let i = 1; i < lines.length; i++) {
+ if (/^---\s*$/.test(lines[i])) return lines.slice(i + 1).join('\n');
+ }
+ return norm; // 未闭合 → 保守视全文为正文（宁可刷新，不误判为 frontmatter-only）
+}
+
+// 纯函数：候选分析（fixture 测试直接驱动；docs 项 = { rel, file, dir, text }）
+// 归档单位 = 同名家族：家族候选 ⇔ 全成员终态 + 全成员有终态时间且超窗 + 无成员被活跃引用
+export function analyze({ docs, ledgerTs = {}, lastTouch = {}, activeTexts = [], windowDays = 21, today = Date.now() }) {
+  const referenced = new Set();
+  const fams = new Map();
+  for (const d of docs) {
+    if (d.file.startsWith('_TEMPLATE')) continue;
+    if (!fams.has(d.file)) fams.set(d.file, []);
+    fams.get(d.file).push(d);
+  }
+  for (const text of activeTexts) for (const file of fams.keys()) if (text.includes(file)) referenced.add(file);
+
+  const active = [];
+  const terminal = [];
+  const candidates = [];
+  const tooRecent = [];
+  const noDate = [];
+  for (const [, members] of fams) {
+    const enriched = members.map((d) => {
+      const st = parseStatus(d.text);
+      const tTime = ledgerTs[d.rel] || lastTouch[d.rel] || /^(\d{4}-\d{2}-\d{2})/.exec(d.file)?.[1] || '';
+      const src = ledgerTs[d.rel] ? 'ledger' : lastTouch[d.rel] ? 'git' : 'name';
+      return { ...d, st, tTime, src };
+    });
+    const allTerminal = enriched.every((x) => TERMINAL.has(x.st));
+    const refd = enriched.some((x) => referenced.has(x.file));
+    const undated = enriched.filter((x) => !x.tTime);
+    const recent = enriched.filter((x) => x.tTime && Math.floor((today - new Date(x.tTime).getTime()) / 864e5) <= windowDays);
+    const archivable = allTerminal && !refd && !undated.length && !recent.length;
+    for (const x of enriched) {
+      if (TERMINAL.has(x.st)) terminal.push(x);
+      if (ACTIVE.has(x.st)) active.push(x);
+    }
+    if (!archivable) {
+      if (undated.length) noDate.push(...undated);
+      if (recent.length) tooRecent.push(...recent);
+      continue;
+    }
+    const month = enriched.map((x) => x.tTime).sort().pop().slice(0, 7); // 家族最晚终态月，整族同批
+    for (const x of enriched) candidates.push({ ...x, month });
+  }
+  return { active, terminal, candidates, referenced, tooRecent, noDate };
+}
+
+export function buildDocList(root, dirs = DIRS) {
+ const docs = [];
+ for (const d of dirs) {
+ const dir = path.join(root, 'workflow', d);
+ if (!fs.existsSync(dir)) continue; // 目录缺失（fixture / 部分类型未建）→ 跳过，不抛
+ for (const f of fs.readdirSync(dir)) {
+ if (!f.endsWith('.md')) continue;
+ const rel = `workflow/${d}/${f}`;
+ docs.push({ rel, file: f, dir: d, text: fs.readFileSync(path.join(dir, f), 'utf8') });
+ }
+ }
+ return docs;
+}
+
+// loadLedgerTs(root)：每篇文档的终态台账行最新日期（YYYY-MM-DD）。主台账+分片统一视图；
+// 2026-10-15 起导出（gen-workflow-metrics 归档积压提醒复用——此前 confirm-doc 内联同型逻辑，
+// 导出后新消费方零复制）。
+export function loadLedgerTs(root) {
+  const out = {};
+  // 台账统一视图（主台账+分片透明合并，坏行跳过、同 doc|stage|fingerprint 键去重取末次）
+  for (const e of loadAllConfirmations(root)) {
+    if (TERMINAL.has(e.stage) && e.doc) {
+      const d = (e.ts || '').slice(0, 10);
+      if (d && (!out[e.doc] || d > out[e.doc])) out[e.doc] = d;
+    }
+  }
+  return out;
+}
+
+// loadLastTouch(root)：每篇 workflow 文档的「最后一次正文变更」日期（YYYY-MM-DD）。
+// 逐提交（新→旧）取该文件的 blob 与上一版比对：正文（bodyOf）逐字节相同 → frontmatter-only 提交，
+// 跳过不记；正文有变 → 记该提交日期并停止追踪该文件（新→旧遍历，首遇即最近一次正文变更）。
+// 批量迁移/补录提交（只改状态与确认指纹）因此不再刷新锚——2026-10-13 修锚的核心。
+// 实现：单次 `git log --raw` 拿「提交 × 文件 × 前后 blob sha」，再按需 `git cat-file --batch` 取内容
+// （同 blob 内容天然去重，批量提交里 193 个文件多为同一份 frontmatter 改写，实际读取量远小于文件数）。
+export function loadLastTouch(root) {
+ const out = {};
+ const raw = execFileSync('git', ['log', '--raw', '--no-renames', '--format=%x01%cI', '--', 'workflow'], {
+ cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024,
+ });
+ // 收集待比对项：按 path 分组，保留**全部**历史条目（新→旧），逐条比对直到找到正文变更
+ const byPath = new Map();
+ for (const entry of raw.split('\u0001')) {
+ const lines = entry.split('\n');
+ const date = (lines[0] || '').slice(0, 10);
+ if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
+ for (const line of lines.slice(1)) {
+ // `:<oldmode> <newmode> <oldsha> <newsha> <status>\t<path>`
+ const m = /^:\d+ \d+ ([0-9a-f]+) ([0-9a-f]+) [A-Z]\d*\t(.+)$/.exec(line);
+ if (!m) continue;
+ const [, oldSha, newSha, p] = m;
+ if (!byPath.has(p)) byPath.set(p, []);
+ byPath.get(p).push({ date, oldSha, newSha });
+ }
+ }
+ // 批量取 blob 内容（--batch 一次喂全部 sha，输出 `<full-sha> blob <size>\n<content>\n`）
+ // 注意：--batch 回显**完整** sha，而输入是 core.abbrev 缩写——按输入顺序回填，键用请求时的缩写，
+ // 否则 blobs.get(缩写) 恒 miss → 全部走保守回退（2026-10-13 实测踩中）。
+ const shas = [...new Set([...byPath.values()].flat().flatMap((x) => [x.oldSha, x.newSha]).filter((s) => s && !/^0+$/.test(s)))];
+ const blobs = new Map();
+ if (shas.length) {
+ const outBuf = execFileSync('git', ['cat-file', '--batch'], {
+ cwd: root, input: shas.join('\n') + '\n', maxBuffer: 512 * 1024 * 1024,
+ });
+ // 按 header 行切分（内容可能含任意字节，故按 size 精确切片）；第 i 个响应 ↔ shas[i]
+ let pos = 0;
+ let idx = 0;
+ while (pos < outBuf.length && idx < shas.length) {
+ const nl = outBuf.indexOf(0x0a, pos);
+ if (nl === -1) break;
+ const header = outBuf.toString('utf8', pos, nl);
+ const hm = /^([0-9a-f]+) blob (\d+)$/.exec(header);
+ if (!hm) { pos = nl + 1; continue; }
+ const size = Number(hm[2]);
+ const start = nl + 1;
+ blobs.set(shas[idx], outBuf.toString('utf8', start, start + size));
+ pos = start + size + 1; // 跳过内容后的换行
+ idx++;
+ }
+ }
+ // 逐 path 新→旧扫描：首个「正文有变」的提交日期即内容 last-touch；全为 frontmatter-only → 不记
+ // （调用方回退到文件名日期）。新增文件（oldSha 全 0）→ 该次提交即首次入库，记为正文变更。
+ for (const [p, entries] of byPath) {
+ for (const { date, oldSha, newSha } of entries) {
+ // 全 0 sha（新增文件，git 按 core.abbrev 输出 7 位 `0000000`）→ 首次入库即正文变更
+ if (/^0+$/.test(oldSha)) { out[p] = date; break; }
+ const before = blobs.get(oldSha);
+ const after = blobs.get(newSha);
+ // 取不到内容（异常态）→ 保守记为正文变更（宁可刷新，不误跳过）
+ if (before === undefined || after === undefined) { out[p] = date; break; }
+ if (bodyOf(before) !== bodyOf(after)) { out[p] = date; break; }
+ }
+ }
+ return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const execute = argv.includes('--execute');
+  const wArg = argv.find((a) => a.startsWith('--window='));
+  const windowDays = wArg ? Number(wArg.split('=')[1]) : 21;
+  if (!Number.isFinite(windowDays) || windowDays < 0) {
+    console.error('archive-sweep: --window 须为非负数字');
+    process.exit(2);
+  }
+  const root = process.cwd();
+  const docs = buildDocList(root);
+  const r = analyze({
+    docs,
+    ledgerTs: loadLedgerTs(root),
+    lastTouch: loadLastTouch(root),
+    activeTexts: docs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+    windowDays,
+  });
+  const byDir = {};
+  for (const d of DIRS) byDir[d] = r.candidates.filter((x) => x.dir === d).length;
+  const fams = new Set(r.candidates.map((x) => x.file));
+  console.log(`窗口 ${windowDays} 天｜候选 ${r.candidates.length} 篇 / ${fams.size} 族（${JSON.stringify(byDir)}）｜活跃 ${r.active.length}｜未满窗 ${r.tooRecent.length}｜被活跃引用排除 ${r.referenced.size}｜无日期 ${r.noDate.length}`);
+  if (!execute) {
+    for (const x of r.candidates) console.log(`  [dry] ${x.rel} → workflow/archive/${x.month}/${x.dir}/${x.file}`);
+    console.log('dry-run 结束（加 --execute 执行 git mv）');
+    return;
+  }
+  let moved = 0;
+  for (const x of r.candidates) {
+    const destDir = path.join(root, 'workflow', 'archive', x.month, x.dir);
+    fs.mkdirSync(destDir, { recursive: true });
+    execFileSync('git', ['mv', x.rel, path.join('workflow', 'archive', x.month, x.dir, x.file)], { cwd: root });
+    moved++;
+  }
+  console.log(`execute 完成：git mv ${moved} 篇 → workflow/archive/<家族最晚终态月>/`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith('archive-sweep.mjs')) main();

package/templates/engine/.agents/scripts/auto-tour.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// auto-tour.mjs — plan 落盘后自动拉起开发全景看板并输出 /tour 链接（Build 段回填后调用）
+// 用法：node .agents/scripts/auto-tour.mjs workflow/plans/<name>.md
+//
+// 存在理由（2026-11-11）：stages.md Build §2 第 5 步要求「生成全景并核对文档外实际改动」，
+// 但那步只产出静态快照；看板实时版要人手动跑 ensure-board 再自己拼 /tour?file= 链接。
+// 本脚本把两件事并成一步：拉起看板（幂等）+ 打印本 plan 的实时链接，不弹浏览器。
+//
+// 三条硬约束：
+//   1. 幂等：看板已在跑则复用（ensure-board 自身判定 up-to-date / stale 并决定是否重启），
+//      重复调用不产生第二个进程、不抢焦点。
+//   2. 不弹浏览器：ensure-board 的 --no-open；链接由本脚本输出，由人或 AI 自行打开。
+//   3. 失败不阻断：看板拉不起来（端口被他人占 / 冷启动超时）时打印告警并 exit 0——
+//      全景图是可选的观察面，不是门禁，Build 流程不应因它停摆。
+//
+// 端口单源：board-port.mjs（显式 --port > 配置基线 > BASE_BOARD_PORT，再按 SHIPYARD_SLOT 偏移；
+//   与 ensure-board.mjs 同口径，共用同一函数，端口字面量不落本文件）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveBoardPort } from './board-port.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, '../..');
+const ENSURE_BOARD = path.join(SCRIPT_DIR, 'ensure-board.mjs');
+
+const USAGE = `用法：node .agents/scripts/auto-tour.mjs <workflow/plans/<name>.md> [--port <port>]
+
+plan 落盘后拉起开发全景看板并打印实时链接（不弹浏览器）。
+看板已在跑则复用；拉起失败只告警不阻断（exit 0）。`;
+
+function parseArgs(argv) {
+  const out = { doc: '', port: '' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
+    else if (a === '--port') out.port = argv[++i] || '';
+    else if (a.startsWith('-')) { console.error(`❌ 未知参数：${a}\n\n${USAGE}`); process.exit(1); }
+    else if (!out.doc) out.doc = a;
+    else { console.error(`❌ 只接受一个文档参数（多余：${a}）\n\n${USAGE}`); process.exit(1); }
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.doc) { console.error(USAGE); process.exit(1); }
+
+  const docAbs = path.resolve(ROOT, args.doc);
+  if (!fs.existsSync(docAbs)) {
+    console.error(`❌ 找不到文档：${args.doc}`);
+    process.exit(1);
+  }
+  // 传相对路径给看板（看板按仓库相对路径解析 file 参数）
+  const rel = path.relative(ROOT, docAbs).split(path.sep).join('/');
+
+  const port = resolveBoardPort({ explicit: args.port, root: ROOT });
+  const r = spawnSync(process.execPath, [ENSURE_BOARD, '--port', String(port), '--no-open'], {
+    cwd: ROOT, encoding: 'utf8', timeout: 60000,
+  });
+  const out = `${r.stdout || ''}${r.stderr || ''}`.trim();
+
+  // ensure-board 失败 = 端口被他人占或冷启动超时；不阻断 Build 流程。
+  // 透传末 3 行（失败信息是「原因+处置」多行，单行截尾会丢处置提示；逐行缩进保可读）
+  if (r.status !== 0) {
+    const tail = out.split('\n').filter(Boolean).slice(-3).map((l) => `   ${l}`).join('\n');
+    console.error(`⚠ 开发全景看板未就绪（不影响 Build 流程）：\n${tail || `   exit ${r.status}`}`);
+    console.error(`   手动拉起：node .agents/scripts/ensure-board.mjs --no-open`);
+    process.exit(0);
+  }
+
+  console.log(out.split('\n').filter(Boolean).pop() || `board: up-to-date at http://127.0.0.1:${port}`);
+  console.log(`   开发全景实时版：http://127.0.0.1:${port}/tour?file=${encodeURIComponent(rel)}`);
+}
+
+main();

package/templates/engine/.agents/scripts/board-port.mjs

@@ -0,0 +1,17 @@
+// board-port.mjs — 看板基端口解析单源（ensure-board.mjs / auto-tour.mjs 共用，2026-11-11 抽取前各自复制同构段）
+// 口径：显式 --port（绝对值，不吃槽位偏移）> engine.json boardPort（配置基线）> ports.mjs BASE_BOARD_PORT，
+//   再按 SHIPYARD_SLOT 偏移。槽位派生仍单源 scripts/verify/e2e/ports.mjs（本文件 import，端口字面量不落此处）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { shiftPort, BASE_BOARD_PORT } from '../../scripts/verify/e2e/ports.mjs';
+
+/** 解析看板基端口。explicit 传调用方的 --port 原始字符串；root 为仓库根（engine.json 定位用）。 */
+export function resolveBoardPort({ explicit = '', root } = {}) {
+  if (explicit && Number(explicit)) return Number(explicit); // 显式端口 = 绝对值，不吃槽位偏移（逃生口）
+  // 基端口取引擎配置（init 询问值）；无配置或解析失败回落基线（单源 ports.mjs）；再叠加槽位偏移（board-slot-strict）
+  let configured = BASE_BOARD_PORT;
+  try {
+    configured = Number(JSON.parse(fs.readFileSync(path.join(root, '.agents', 'config', 'engine.json'), 'utf8')).options.boardPort) || BASE_BOARD_PORT;
+  } catch { /* 无配置回落基线 */ }
+  return shiftPort(configured);
+}

package/templates/engine/.agents/scripts/check-doc-body-drift.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// check-doc-body-drift.mjs — 提交期可见性 advisory（2026-11-10；incident 2026-10-26-workflow-confirmation-drift-hard-block
+// 复盘三件套 #1「结构性修复」，advisory 先行不合门）
+// 缺口：改已关单文档正文在提交时刻完全不可见，直到下次关单 check-loop §15 才炸 [确认内容漂移] hard-block
+//（根因 = 771bc09c 恢复类提交改回旧正文而未同步重录确认指纹，台账分片未随动）。本脚本把该缺口前移到
+// 提交时刻打 advisory，执法面仍是 check-loop §15 关单对账（判定口径零变化）。
+// 触发口径：暂存面含 workflow/{intents,specs,plans,incidents}/*.md（INDEX.md 在 workflow/ 直下，天然不在面内）
+// 且该文档当前状态属已确认终态（done/superseded/closed/cancelled/fixed）时——若暂存 diff 改了「正文」
+//（排除：仅 frontmatter「状态:」行、仅「确认指纹:」行——confirm-doc 自身流转只动这两行）而同笔暂存
+// 无对应确认台账变更（.agents/confirmations.d/<基名>.jsonl 分片或主台账 .agents/confirmations.jsonl
+// 任一在场即算；append-compensation.mjs 的补偿行正落在分片，补偿路径天然不警）→ 打印 advisory：
+// 疑似改已关单正文未重录指纹，确认后重录或说明。exit 0 恒不拦。
+// 用法：node .agents/scripts/check-doc-body-drift.mjs [--staged]（--staged 仅为可读性别名，本脚本恒查暂存面）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const DOC_RE = /^workflow\/(intents|specs|plans|incidents)\/[^/]+\.md$/;
+const TERMINAL = new Set(['done', 'superseded', 'closed', 'cancelled', 'fixed']);
+const MAIN_LEDGER = '.agents/confirmations.jsonl';
+
+const git = (args) => spawnSync('git', ['-c', 'core.quotepath=off', ...args], { encoding: 'utf8' });
+
+// fmStatusOf(abs)：frontmatter（首个 --- 块）内「状态:」值；无 frontmatter/键/文件不可读 → ''
+function fmStatusOf(abs) {
+  let lines;
+  try { lines = fs.readFileSync(abs, 'utf8').split(/\r?\n/); } catch { return ''; }
+  if (!/^---\s*$/.test(lines[0] || '')) return '';
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) return '';
+    const m = lines[i].match(/^状态:\s*(\S+)/);
+    if (m) return m[1];
+  }
+  return '';
+}
+
+// bodyChangedInStagedDiff(rel)：暂存 diff（-U0 --no-renames）是否含「正文」变更——剔除状态行与指纹行后
+// 仍有 +/- 内容行即视为正文变更。git 调用失败按无变更降级（advisory 不合门，不因基础设施误报）。
+function bodyChangedInStagedDiff(rel) {
+  const r = git(['diff', '--cached', '--unified=0', '--no-renames', '--', rel]);
+  if (r.status !== 0) return false;
+  for (const line of String(r.stdout || '').split(/\r?\n/)) {
+    if (!line.startsWith('+') && !line.startsWith('-')) continue;
+    if (line.startsWith('+++') || line.startsWith('---')) continue;
+    if (line.startsWith('\\')) continue; // “”
+    const content = line.slice(1).trim();
+    if (!content) continue;
+    if (/^状态:/.test(content) || /^确认指纹:/.test(content)) continue; // confirm-doc 自身流转面
+    return true;
+  }
+  return false;
+}
+
+// ledgerRowStaged(rel, files)：同笔暂存是否携带**该 doc** 的确认台账行（重录/补偿行均形态）——
+// 台账面 = 主台账（若暂存）∪ 该 doc 的分片（若暂存）；判据 = 台账暂存 diff 的新增行含 `"doc":"<rel>"`。
+// 逐行对应而非「任一台账文件在场」：并录批次里他份的行不豁免本份（shard 按基名天然隔离；
+// 主台账混合行靠行级判据收口）。
+function ledgerRowStaged(rel, files) {
+  const candidates = [MAIN_LEDGER, `.agents/confirmations.d/${path.basename(rel, '.md')}.jsonl`]
+    .filter((f) => files.includes(f));
+  for (const f of candidates) {
+    const r = git(['diff', '--cached', '--unified=0', '--no-renames', '--', f]);
+    if (r.status !== 0) continue;
+    const added = String(r.stdout || '').split(/\r?\n/)
+      .some((l) => l.startsWith('+') && !l.startsWith('+++') && l.includes(`"doc":"${rel}"`));
+    if (added) return true;
+  }
+  return false;
+}
+
+// run(root)：扫描暂存面，打印 advisory；恒返回 0（exit 0 恒不拦）。
+export function run(root = process.cwd()) {
+  const staged = git(['diff', '--cached', '--name-only']);
+  if (staged.status !== 0) return 0;
+  const files = String(staged.stdout || '').split(/\r?\n/).filter(Boolean).map((f) => f.replace(/\\/g, '/'));
+  const docs = files.filter((f) => DOC_RE.test(f));
+  if (!docs.length) return 0;
+  const hits = [];
+  for (const rel of docs) {
+    const st = fmStatusOf(path.join(root, rel));
+    if (!TERMINAL.has(st)) continue; // 非已确认终态（draft/approved/open 及删除件）不在 advisory 面
+    if (!bodyChangedInStagedDiff(rel)) continue; // 仅状态行/指纹行变更 = confirm-doc 自身流转，不警
+    if (ledgerRowStaged(rel, files)) continue; // 同笔已重录指纹 / 追加补偿行（append-compensation.mjs）→ 对账口径成立，不警
+    hits.push({ rel, st });
+  }
+  if (hits.length) {
+    console.error('[advisory][doc-body-drift] 检出疑似「改已关单正文未重录指纹」（本提示不合门，exit 0）：');
+    for (const h of hits) {
+      console.error(`  - ${h.rel}（状态 ${h.st}）：暂存 diff 改了正文，同笔暂存无对应确认台账变更（.agents/confirmations.d/${path.basename(h.rel, '.md')}.jsonl）`);
+    }
+    console.error('  口径：确认后同笔重录（confirm-doc / --reconfirm / append-compensation 补偿行）或在提交说明中说明理由；否则下次关单 check-loop §15 判「确认内容漂移」hard。');
+  }
+  return 0;
+}
+
+function main() {
+  process.exit(run());
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();

package/templates/engine/.agents/scripts/check-engine-artifacts.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// check-engine-artifacts.mjs — 生成物漂移单门（2026-10-28 引擎减重第三刀；2026-11-08 档 2-E 改自愈）
+// 背景：effective-policy / engine-map / workflow-index 三门机制完全相同（跑生成器 --check 比对磁盘），
+//   逐个挂 verify 只增加门数与输出噪音。本脚本把三份收口成一次调用。
+// 口径（档 2-E 自愈，2026-11-08）：生成物是磁盘态的确定函数，漂移的正确处置是重生成而非拦人——
+//   --check 检出漂移 → 原地重生成受影响生成物 → 复跑 --check 确认后按通过计（并行会话在途立档
+//   期间的既有漂移不再误伤关单 verify，本仓 11-08 两次实证）；重生成或复检失败才 exit 1。
+//   各档（含 --full / CI）同语义无害：CI 工作区可写且生成物不随 CI 提交。
+//   判据仍以各生成器 --check 为唯一单源（不复制比对逻辑）；workflow/verify-evidence.md 由 verify
+//   全绿尾段（gen-verify-evidence）在全部门结束后的串行尾段写入——三个生成物均不以其为源，
+//   与本门自愈写盘无读写交集，不存在顺序/幂等冲突。
+// 用法：node .agents/scripts/check-engine-artifacts.mjs
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DIR = path.dirname(fileURLToPath(import.meta.url));
+const ITEMS = [
+  ['effective-policy', 'gen-effective-policy.mjs', 'workflow/effective-policy.md'],
+  ['engine-map', 'gen-engine-map.mjs', '.agents/notes/engine-map.md'],
+  ['workflow-index', 'gen-workflow-index.mjs', 'workflow/INDEX.md'],
+];
+
+// check=true 跑生成器 --check（唯一判据，不写盘）；check=false 原地重生成。
+const run = (script, check) =>
+  spawnSync(process.execPath, [path.join(DIR, script), ...(check ? ['--check'] : [])], { encoding: 'utf8' });
+
+let red = 0;
+for (const [id, script, artifact] of ITEMS) {
+  const r = run(script, true);
+  if (r.status === 0) {
+    console.log(`[artifacts] ✅ ${id}`);
+    continue;
+  }
+  // 档 2-E 自愈：漂移 → 原地重生成 → 复跑 --check 确认；无漂移不写盘（幂等），自愈失败才红。
+  const reason = (`${r.stdout || ''}${r.stderr || ''}`.trim().split(/\r?\n/)[0] || `exit ${r.status}`).slice(0, 200);
+  const regen = run(script, false);
+  const recheck = regen.status === 0 ? run(script, true) : null;
+  if (recheck && recheck.status === 0) {
+    console.log(`[artifacts] ♻️ 已自愈重生成：${artifact}（漂移原因随场景：${reason}）`);
+    continue;
+  }
+  red++;
+  const f = recheck || regen;
+  const why = regen.status === 0 ? '重生成后复检仍漂移' : `重生成器异常 exit ${regen.status}`;
+  console.error(`[artifacts] ❌ ${id} 自愈失败（${why}）：${(`${f.stdout || ''}${f.stderr || ''}`.trim()) || `exit ${f.status}`}`);
+  console.error(`[artifacts]    ${artifact} 手动重生成：node .agents/scripts/${script}`);
+}
+if (red) {
+  console.error(`[artifacts] ${red}/${ITEMS.length} 份生成物自愈失败——单源与磁盘不可自动收敛，人工介入`);
+  process.exit(1);
+}
+console.log(`[artifacts] ✅ ${ITEMS.length} 份生成物与单源一致`);
+process.exit(0);

package/templates/engine/.agents/scripts/check-hook-wiring.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// check-hook-wiring — 宿主接线宣称 ↔ 实态一致性机检（2026-10-29 P0）
+//
+// 为什么需要：引擎测试面退役（2026-10-28）后接线漂移无自动防线——实证案例（2026-10-29）：
+//   ① registry 行 40 记「zcode 接线坐实」，实态 = .zcode/config.json Bash 槽 enabled:false。
+// 本脚本只做「宣称 == 实态」对账（drift 检出），不替 owner 决定期望态——期望态变更（如 zcode Bash
+// 槽启用）须同步改 CLAIMS 与 registry 行；两侧任一漂移本门即红。
+//
+// 挂载点：.githooks/pre-push（推送范围触及宿主壳/.agents/hooks/registry 时条件执行）；手动：node 本文件。
+// 退出码：0 一致 / 1 漂移或自检失败。
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, '../..');
+
+// 宣称表（单源：期望态在此声明并指回 registry 行；改期望态 = 改本表 + registry 行同提交）
+// 只列**入库宿主**（engine.json options.hosts = trae / codebuddy）。本机宿主壳（.zcode/.qoder/.grok/
+// .omp/.qwen 等，见 .gitignore 宿主政策）禁止入表：文件不随 clone 传播，写了必在他机假红
+// （实证：2026-11-07 移出 zcode 跟踪后本门恒红一日无人见——pre-push 仅推送范围触宿主壳才条件起它）。
+const CLAIMS = [
+  {
+    host: '.trae/hooks.json', event: 'PreToolUse', matcher: 'RunCommand|Bash|Shell|Terminal',
+    cmdIncludes: 'pre-shell-check.cjs', enabled: null, // null = 该宿主配置无 enabled 字段（缺省即启用），只验存在
+    claim: 'runtime-env §6.4 宿主事实（Trae RunCommand）',
+  },
+  {
+    host: '.codebuddy/settings.json', event: 'PreToolUse', matcher: 'Bash|PowerShell|RunCommand|Shell|Terminal',
+    cmdIncludes: 'pre-shell-check.cjs', enabled: null,
+    claim: 'runtime-env §6.4 宿主事实（CodeBuddy Bash 主通道 + PowerShell 次通道）',
+  },
+  {
+    host: '.codebuddy/settings.json', event: 'PreToolUse', matcher: 'Write|Edit|MultiEdit',
+    cmdIncludes: 'pre-write-check.cjs', enabled: null,
+    claim: 'registry 宿主写前门行（2026-11-11 codebuddy 接线，trae 仍无写前壳）',
+  },
+  // post-edit-check（PostToolUse 反馈腿）已于 2026-11-08 档 1 减重退役（与写前门/pre-commit 重复执法），
+  // 对应 CLAIMS 两行随码同批删除；registry「宿主写前门」行口径同批更新。
+];
+
+const problems = [];
+for (const c of CLAIMS) {
+  const abs = path.join(ROOT, c.host);
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(abs, 'utf8'));
+  } catch (e) {
+    problems.push(`${c.host} 不可读/不可解析（${e.message}）——宣称 ${c.event}[${c.matcher}] 无法核验`);
+    continue;
+  }
+  const entries = cfg?.hooks?.events?.[c.event] ?? cfg?.hooks?.[c.event] ?? [];
+  const hit = entries.find((e) => e?.matcher === c.matcher);
+  if (!hit) {
+    problems.push(`${c.host} 缺 ${c.event}[${c.matcher}]（宣称：${c.claim}）`);
+    continue;
+  }
+  const wired = (hit.hooks || []).find((h) => typeof h?.command === 'string' && h.command.includes(c.cmdIncludes));
+  if (!wired) {
+    problems.push(`${c.host} ${c.event}[${c.matcher}] 未挂 ${c.cmdIncludes}（宣称：${c.claim}）`);
+    continue;
+  }
+  if (c.enabled !== null && wired.enabled !== c.enabled) {
+    problems.push(`${c.host} ${c.event}[${c.matcher}] → ${c.cmdIncludes} enabled=${wired.enabled}，宣称=${c.enabled}（${c.claim}）`);
+  }
+}
+
+if (problems.length) {
+  console.error('check-hook-wiring: 接线漂移——宣称与实态不一致：');
+  for (const p of problems) console.error('  ❌ ' + p);
+  console.error('处置：改实态（宿主配置/挂载）或改宣称（本脚本 CLAIMS + mechanism-registry 对应行）后重跑；两侧须同提交。');
+  process.exit(1);
+}
+console.log(`check-hook-wiring: ✅ ${CLAIMS.length} 项宣称与实态一致`);