agentic-flow-kit 1.7.16 → 1.8.1

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

@@ -0,0 +1,64 @@
+// check-prejudgment.mjs — 检查 25：路由预判一致性 [warning]（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s25-prejudgment.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git 历史与
+//   CHANGELOG——装户径不引实例路径）
+// 背景（prejudgment-ledger）：类型误路由（修复被当新需求 → 跳过 incident 立项与 kb-search 历史检索）
+// 是路由自动识别的静默盲区；级别判低已有「红线判低」hard 与泳道门兜底，但「入口预判 vs 实际落位」的
+// 偏离本身不可见。本段只做 advisory 比对：frontmatter「预判: kind=<kind> level=<L1|L2|L3>」在场才检——
+// kind 与入口类型不符 / level 与「级别」字段不符 / 词表非法 → WARN，不阻断。
+// kind 语义源 = pipeline-run.mjs KINDS（require/fix/verify/review/deploy）；类型只对 intents(≡require)/
+// incidents(≡fix) 执法——plans/specs 是两道共用件不判类型、只比对级别。
+// 缺字段零告警（存量宽容不回填，不做强制前置）——灰度数据经 judgments.jsonl（WARN 预判* 计数）
+// 月度对账后再议升格，退役/升格阈值由 mechanism-registry §25 行承载。
+// kit 适配（源仓→kit 逐条）：无判据改动。kind 词表沿源仓 s25 等价落——pipeline-run.mjs 的 KINDS 为
+//   模块内常量、无导出（两侧同状），故本文件按源仓同款内联声明 + 注释互引（改任一侧须同步，见下）。
+import path from 'node:path';
+
+export function run(ctx) {
+  const { ROOT, WF, DOC_DIRS, ENUMS, inSet, fmGet, isTracked, readdirOrNull, warnings } = ctx;
+  // --- 25. 路由预判一致性 [warning] ---
+  // kind 词表单源 = pipeline-run.mjs KINDS（该处为模块内常量、未导出——源仓 s25 同款内联等价落）；
+  // 两侧各一份靠本注释互引，改词表须同步（pipeline-run 校验文案 `kind 须为 …` 同步）。
+  const KINDS = ['require', 'fix', 'verify', 'review', 'deploy'];
+  const rankOf = (lv) => Number(String(lv).replace(/^L/, '')) || 0;
+  for (const sub of DOC_DIRS) {
+    const dir = path.join(ROOT, WF, sub);
+    for (const f of readdirOrNull(dir) || []) {
+      if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
+      const abs = path.join(dir, f);
+      if (!isTracked(abs)) continue;
+      const pj = fmGet(abs, '预判');
+      if (!pj) continue;
+      const rel = `${WF}/${sub}/${f}`;
+      // 终态文档（2026-10-15）：形态/词表类告警跳过——终态受检查 15 内容绑定不可修订，此类 WARN 永不可
+      // 消（「不可消除噪声」红线）；类型/级别比对保留——那是路由审计的本体信号，灰度对账照常采集。
+      // （终态并集 = doc 终态 done/superseded/cancelled + incident 终态 fixed/closed——两侧枚举无单一键
+      // 覆盖该并集，故与源仓 s25 同款内联声明。）
+      const terminalDoc = ['done', 'superseded', 'cancelled', 'fixed', 'closed'].includes(fmGet(abs, '状态'));
+      const kv = {};
+      for (const m of pj.matchAll(/(kind|level)=([^\s]+)/g)) kv[m[1]] = m[2];
+      if (!Object.keys(kv).length) {
+        if (!terminalDoc) warnings.push(`- [WARN 预判字段不可解析] 须形如「预判: kind=<kind> level=<L1|L2|L3>」:${rel}`);
+        continue;
+      }
+      if (kv.kind && !KINDS.includes(kv.kind) && !terminalDoc) {
+        warnings.push(`- [WARN 预判字段不可解析] kind=${kv.kind} 不在词表（${KINDS.join('/')}）:${rel}`);
+      }
+      if (kv.level && !inSet(kv.level, ENUMS['level.all']) && !terminalDoc) {
+        warnings.push(`- [WARN 预判字段不可解析] level=${kv.level} 不在枚举 level.all:${rel}`);
+      }
+      // 类型比对：intents ≡ require、incidents ≡ fix（plans/specs 两道共用，不判类型）
+      const actualKind = sub === 'incidents' ? 'fix' : sub === 'intents' ? 'require' : null;
+      if (kv.kind && actualKind && kv.kind !== actualKind) {
+        warnings.push(`- [WARN 预判类型不符] 预判 kind=${kv.kind} 但落位 ${sub}（实际 kind=${actualKind}）——类型误路由会跳过对应道的检索与立档，确认是否有意:${rel}`);
+      }
+      // 级别比对：与 frontmatter「级别」字段
+      if (kv.level) {
+        const lv = fmGet(abs, '级别');
+        if (lv && lv !== kv.level) {
+          const hint = rankOf(lv) < rankOf(kv.level) ? '（判低信号——落位低于预判，复核两问判据）' : '（判高——流程偏重，无害）';
+          warnings.push(`- [WARN 预判级别不符] 预判 ${kv.level} 落位 ${lv}${hint}:${rel}`);
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,45 @@
+// check-registry.mjs — 检查 22：机制使用量台账 [warning]（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s22-registry.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git 历史与
+//   CHANGELOG——装户径不引实例路径）
+// 背景：门禁只增不减（每道门都有事故背书，但无退役机制）——本检查给「低频机制退役」装强制处置环。
+// .agents/mechanism-registry.md 在场才启用（历史 clone / 装户缺文件 = 跳过，沿 lane-surfaces.txt
+// 「缺失即跳过」惯例，不制造一次性噪声）。表格式 markdown 管道表，列序固定：
+//   | 机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限 |
+// 判据：状态 ∈ {现役,待退役,已退役}；「待退役」必须填处置期限（日期或批次号）——台账的目的不是记录
+// 而是强制处置：没有时间表的退役意向等于永不变退役。触发计数本身半自动（口径列写明统计方法），
+// 不进机器门——先有账，再谈自动化。纯 WARN advisory，永不 hard（机制未登记/只有示例行都只出账不拦）。
+// kit 适配（源仓→kit 逐条）：台账路径平铺 .agents/config/ → .agents/（kit 装户布局无 config/ 层）。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function run(ctx) {
+  const { ROOT, linesOf, warnings } = ctx;
+  // --- 22. 机制使用量台账（mechanism-registry；复杂度棘轮的出口）---
+  {
+    const regPath = path.join(ROOT, '.agents', 'mechanism-registry.md');
+    if (fs.existsSync(regPath)) {
+      const dataRows = (linesOf(regPath) || [])
+        .filter((l) => /^\|/.test(l))
+        .filter((l) => !/^\|[\s:|-]+\|?\s*$/.test(l))          // 分隔行
+        .filter((l) => (l.split('|')[1] || '').trim() !== '机制'); // 表头行
+      if (!dataRows.length) {
+        warnings.push('- [WARN 机制台账] 无数据行——表格式：| 机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限 |');
+      }
+      for (const l of dataRows) {
+        const cells = l.split('|').slice(1, -1).map((c) => c.trim());
+        if (cells.length !== 7) {
+          warnings.push(`- [WARN 机制台账] 行列数 ${cells.length} ≠ 7（机制|门禁位置|触发统计口径|退役阈值|最近触发|状态|处置期限）:${cells[0] || l.slice(0, 30)}`);
+          continue;
+        }
+        const [name, , , , , status, deadline] = cells;
+        if (!['现役', '待退役', '已退役'].includes(status)) {
+          warnings.push(`- [WARN 机制台账] 「${name}」状态非法（须 现役/待退役/已退役）:${status}`);
+          continue;
+        }
+        if (status === '待退役' && !deadline) {
+          warnings.push(`- [WARN 机制台账] 「${name}」待退役但缺处置期限——补时间表，或改回现役并在阈值列写保留理由`);
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// check-scope.mjs — plan 改动面 ↔ git 变更双向对账（advisory 工具；2026-10-13 自 Shipyard.Material
+//   参考实现回灌，源仓沿革留痕在包源仓 git 历史与 CHANGELOG——装户径不引实例路径）
+// 用途：解析 plan「改动面 / 任务拆解 / 改动方案」节声明的文件清单，与 git 变更集对账——
+//   越界件（改了未声明）= 范围蔓延信号；未落件（声明未改）= plan 滞后或改名信号。check-loop 检查 8
+//   的证据对账只做单向交集（提交须触及至少一个声明文件），夹带 plan 外文件不报——本件补越界方向。
+// 语义与红线：只读裁决（判红绿，不改任何状态——命名规约 check- 前缀）；默认 advisory（exit 0 出报告），
+//   --strict 时越界件非空 exit 1（供门禁化调用方使用）；plan 不可读 exit 2（fail-loud，不静默放行）。
+//   文件匹配沿 check-loop 检查 8 宽松规则（f===df / 后缀 / 双向 includes）——声明粒度粗（写目录或部分路径）
+//   不误报越界；白名单豁免：workflow/ 台账（intents/specs/plans/incidents/INDEX）、.agents/confirmations.jsonl、
+//   .agents/confirmations.d/ 分片、package-lock.json——闭环随行件不算越界。
+// 测试：node .agents/scripts/check-scope.test.mjs（tmp git 仓 fixture：越界 / 未落 / 白名单 / strict / 无 plan）
+// 用法：node .agents/scripts/check-scope.mjs workflow/plans/<name>.md [--base <sha>|--staged] [--strict] [--root <dir>]
+//   默认比对工作区（含未跟踪，git status --porcelain 口径）；--base <sha> 比对 sha..HEAD 已提交变更；
+//   --staged 仅比对暂存区。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2);
+let planRel = '', base = '', staged = false, strict = false, rootArg = '';
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--base') base = args[++i] || '';
+  else if (a === '--staged') staged = true;
+  else if (a === '--strict') strict = true;
+  else if (a === '--root') rootArg = args[++i] || '';
+  else if (!planRel && !a.startsWith('--')) planRel = a;
+}
+const ROOT = path.resolve(rootArg || process.cwd());
+if (!planRel) { console.error('用法: node .agents/scripts/check-scope.mjs workflow/plans/<name>.md [--base <sha>|--staged] [--strict] [--root <dir>]'); process.exit(2); }
+const planAbs = path.isAbsolute(planRel) ? planRel : path.join(ROOT, planRel);
+if (!fs.existsSync(planAbs)) { console.error(`plan 不可读: ${planRel}`); process.exit(2); }
+
+// 声明文件提取——与 check-loop 检查 8 同节同正则（改动面|任务拆解|改动方案），另加扩展名白名单
+// （过滤 v1.2.2 之类版本号伪 token：无目录且扩展名不在清单内则弃）
+const KNOWN_EXT = new Set(['.md', '.mjs', '.js', '.ts', '.json', '.txt', '.cs', '.csproj', '.sln', '.vue', '.ps1', '.sh', '.yml', '.yaml', '.sql', '.cjs']);
+const declared = [];
+{
+  const lines = fs.readFileSync(planAbs, 'utf8').split(/\r?\n/);
+  let inSec = false;
+  for (const line of lines) {
+    if (/^##\s+(改动面|任务拆解|改动方案)/.test(line)) { inSec = true; continue; }
+    if (inSec && /^##\s+/.test(line)) { inSec = false; continue; }
+    if (!inSec) continue;
+    const m = line.match(/([a-zA-Z0-9._/-]+\.[a-zA-Z0-9]+)/);
+    if (!m) continue;
+    const tok = m[1].replace(/\\/g, '/');
+    const ext = tok.slice(tok.lastIndexOf('.'));
+    if (tok.includes('/') || KNOWN_EXT.has(ext.toLowerCase())) declared.push(tok);
+  }
+}
+
+const git = (gitArgs, opts = {}) => spawnSync('git', gitArgs, { cwd: ROOT, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, ...opts });
+let changed = [];
+if (base) {
+  const r = git(['diff', '--name-only', `${base}..HEAD`]);
+  if (r.status !== 0) { console.error(`git diff 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean);
+} else if (staged) {
+  const r = git(['diff', '--name-only', '--cached']);
+  if (r.status !== 0) { console.error(`git diff 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean);
+} else {
+  // 工作区口径：status --porcelain -uall（含未跟踪且逐文件展开——默认折叠成 `?? dir/` 会把整个新目录误判越界）
+  const r = git(['status', '--porcelain', '-uall']);
+  if (r.status !== 0) { console.error(`git status 失败: ${r.stderr}`); process.exit(2); }
+  changed = r.stdout.split(/\r?\n/).filter(Boolean).map((l) => {
+    const body = l.slice(3);
+    const ren = body.match(/.* -> (.*)$/); // 重命名取新路径
+    return (ren ? ren[1] : body).trim().replace(/^"(.*)"$/, '$1');
+  });
+}
+
+const WHITELIST_RE = /^(?:workflow\/(?:intents|specs|plans|incidents)\/|workflow\/INDEX\.md$|\.agents\/confirmations\.jsonl$|\.agents\/confirmations\.d\/|package-lock\.json$)/;
+const norm = (p) => p.replace(/\\/g, '/');
+const matches = (f, df) => f === df || f.endsWith(`/${df}`) || f.includes(df) || df.includes(f);
+
+const outOfScope = changed.filter((f) => !WHITELIST_RE.test(norm(f)) && !declared.some((df) => matches(norm(f), df)));
+const notLanded = declared.filter((df) => !changed.some((f) => matches(norm(f), df)));
+
+console.log(`▶ check-scope（plan 改动面 ↔ git 变更对账）: ${planRel}`);
+console.log(`  声明 ${declared.length} ｜ 变更 ${changed.length}${base ? `（${base}..HEAD）` : staged ? '（staged）' : '（工作区）'}`);
+if (outOfScope.length) {
+  console.log('  越界件（改了未声明）:');
+  outOfScope.forEach((f) => console.log(`    - ${f}`));
+}
+if (notLanded.length) {
+  console.log('  未落件（声明未变更）:');
+  notLanded.forEach((f) => console.log(`    - ${f}`));
+}
+if (!outOfScope.length && !notLanded.length) console.log('  双向对齐 ✅');
+else if (!strict) console.log('  （advisory 报告——--strict 时越界件即 fail）');
+
+if (strict && outOfScope.length) process.exit(1);
+process.exit(0);

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

@@ -0,0 +1,96 @@
+// check-scope.test.mjs — tmp git 仓 fixture（2026-10-13 自 Shipyard.Material 参考实现回灌）
+// 覆盖：越界检出 / 未落检出 / 白名单豁免 / --strict 退出码 / 无 plan exit 2 / 版本号 token 过滤
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const CLI = path.join(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')), 'check-scope.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}` : ''}`); }
+};
+
+function mkRepo() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'check-scope-'));
+  const g = (...a) => spawnSync('git', a, { cwd: root, encoding: 'utf8' });
+  g('init', '-q');
+  g('config', 'user.email', 't@t');
+  g('config', 'user.name', 't');
+  fs.writeFileSync(path.join(root, 'src-a.md'), '# A\n');
+  g('add', '.');
+  g('commit', '-qm', 'init');
+  return { root, g };
+}
+
+const run = (root, planArgs = []) => spawnSync(process.execPath, [CLI, ...planArgs, '--root', root], { cwd: root, encoding: 'utf8' });
+
+// S1 越界检出（工作区默认口径，含未跟踪）
+{
+  const { root } = mkRepo();
+  fs.mkdirSync(path.join(root, 'workflow', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'plans', 'p1.md'), '## 改动面\n- src-a.md：改\n- src-new.md：新建\n');
+  fs.writeFileSync(path.join(root, 'src-b.md'), '# B 越界\n'); // 未跟踪新文件，未声明
+  const r = run(root, ['workflow/plans/p1.md']);
+  check('S1 越界件检出（未跟踪 src-b.md）', r.status === 0 && /越界件/.test(r.stdout) && /src-b\.md/.test(r.stdout), JSON.stringify({ status: r.status, out: r.stdout.slice(0, 300) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// S2 未落检出（声明未变更）
+{
+  const { root } = mkRepo();
+  fs.mkdirSync(path.join(root, 'workflow', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'plans', 'p2.md'), '## 改动面\n- src-ghost.md：计划改但没改\n');
+  const r = run(root, ['workflow/plans/p2.md']);
+  check('S2 未落件检出（src-ghost.md）', r.status === 0 && /未落件/.test(r.stdout) && /src-ghost\.md/.test(r.stdout), JSON.stringify({ status: r.status, out: r.stdout.slice(0, 300) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// S3 白名单豁免（workflow 台账随行件不算越界）
+{
+  const { root } = mkRepo();
+  fs.mkdirSync(path.join(root, 'workflow', 'intents'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'workflow', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'plans', 'p3.md'), '## 改动面\n- src-a.md：改\n');
+  fs.writeFileSync(path.join(root, 'src-a.md'), '# A2\n');
+  fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-10-09-x.md'), '---\n状态: draft\n---\n');
+  const r = run(root, ['workflow/plans/p3.md']);
+  check('S3 台账随行件豁免（workflow/intents 不算越界）', r.status === 0 && !/workflow[\\/]intents/.test(r.stdout.split('未落件')[0]), JSON.stringify({ status: r.status, out: r.stdout.slice(0, 300) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// S4 --strict 越界 exit 1；无越界 exit 0
+{
+  const { root } = mkRepo();
+  fs.mkdirSync(path.join(root, 'workflow', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'plans', 'p4.md'), '## 改动面\n- src-a.md：改\n');
+  fs.writeFileSync(path.join(root, 'src-a.md'), '# A2\n');
+  check('S4a 无越界 --strict exit 0', run(root, ['workflow/plans/p4.md', '--strict']).status === 0);
+  fs.writeFileSync(path.join(root, 'src-rogue.md'), '# rogue\n');
+  check('S4b 越界 --strict exit 1', run(root, ['workflow/plans/p4.md', '--strict']).status === 1);
+  check('S4c 越界无 --strict exit 0（advisory）', run(root, ['workflow/plans/p4.md']).status === 0);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// S5 无 plan exit 2（fail-loud）
+{
+  const { root } = mkRepo();
+  const r = run(root, ['workflow/plans/nope.md']);
+  check('S5 plan 不存在 exit 2', r.status === 2, JSON.stringify({ status: r.status }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// S6 版本号伪 token 过滤（v1.2.2 不入声明清单）
+{
+  const { root } = mkRepo();
+  fs.mkdirSync(path.join(root, 'workflow', 'plans'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'plans', 'p6.md'), '## 改动面\n- src-a.md：升级到 v1.2.2\n');
+  fs.writeFileSync(path.join(root, 'src-a.md'), '# A2\n');
+  const r = run(root, ['workflow/plans/p6.md']);
+  check('S6 版本号 token 不产生未落噪声', r.status === 0 && !/1\.2\.2/.test(r.stdout), JSON.stringify({ out: r.stdout.slice(0, 300) }));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// check-scripts-syntax.mjs — 引擎脚本语法自检（node --check 全量扫描）
+// 用途：守护者受守护——对 .agents/scripts 与 .agents/hooks 下全部 .mjs/.cjs 逐个 node --check，
+//       任何文件不可解析即判红（先例教训：verify.mjs:31 SyntaxError 带病进 CI，全链门静默失效）。
+// 语义与红线：只读裁决，不改任何状态；检查目录缺失或可检文件数为 0 一律判红（fail-closed，
+//       防「改名/删除脚本即去门」）；不 import 任何引擎件，零依赖可独立调度。
+// 测试：node .agents/scripts/check-scripts-syntax.test.mjs
+// 用法：node .agents/scripts/check-scripts-syntax.mjs [目录...]（相对仓库根；缺省 .agents/scripts .agents/hooks；
+//       CHECK_LOOP_ROOT 可覆写仓库根，与 check-loop/verify 同口径）
+// 沿革：2026-10-09 guardian-selfcheck（审计 P0-1 立项，verify.mjs GATES 首门消费）。
+
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const DEFAULT_DIRS = ['.agents/scripts', '.agents/hooks'];
+
+const dirs = process.argv.slice(2);
+const targets = dirs.length ? dirs : DEFAULT_DIRS;
+
+let total = 0;
+const reds = [];
+const missing = [];
+for (const d of targets) {
+  const abs = path.resolve(ROOT, d);
+  let names;
+  try {
+    if (!fs.statSync(abs).isDirectory()) { missing.push(d); continue; }
+    names = fs.readdirSync(abs);
+  } catch {
+    missing.push(d);
+    continue;
+  }
+  for (const f of names.filter((n) => /\.(mjs|cjs)$/.test(n)).sort()) {
+    total++;
+    const r = spawnSync(process.execPath, ['--check', path.join(abs, f)], { encoding: 'utf8' });
+    if (r.status !== 0) {
+      const first = (r.stderr || '').split(/\r?\n/).find((l) => l.trim()) || `exit ${r.status}`;
+      reds.push(`[syntax] ❌ ${d}/${f}: ${first}`);
+    }
+  }
+}
+
+if (missing.length) {
+  console.error(`[syntax] ❌ 检查目标目录缺失：${missing.join('、')}（fail-closed——脚本被改名/删除即去门）`);
+  process.exit(1);
+}
+if (total === 0) {
+  console.error('[syntax] ❌ 可检文件数为 0（目录为空或参数指错，fail-closed）');
+  process.exit(1);
+}
+if (reds.length) {
+  for (const line of reds) console.error(line);
+  console.error(`[syntax] 共 ${total} 个引擎脚本，${reds.length} 个不可解析`);
+  process.exit(1);
+}
+console.log(`[syntax] ✅ ${total} 个引擎脚本全部可解析（node --check）`);
+process.exit(0);

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// check-scripts-syntax.mjs 的夹具测试（CHECK_LOOP_ROOT 注入临时根 + 显式目录参数，不触真实 .agents）
+// 断言：①全绿目录 exit 0 且报数；②混入语法坏件 exit 1 且点名坏文件；③目录缺失 exit 1（fail-closed）；
+//       ④空目录（可检数 0）exit 1（防「清空目录即去门」）；⑤非 .mjs/.cjs 扩展名不入扫描。
+// 用法：node .agents/scripts/check-scripts-syntax.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const CHECKER = path.join(SCRIPT_DIR, 'check-scripts-syntax.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const mkroot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'syn-fix-'));
+const run = (root, argv) => spawnSync(process.execPath, [CHECKER, ...argv], {
+  encoding: 'utf8',
+  env: { ...process.env, CHECK_LOOP_ROOT: root },
+});
+
+// ---- 场景 1：全绿目录 → exit 0 且报数 2（txt 不入扫描） ----
+{
+  const root = mkroot();
+  fs.mkdirSync(path.join(root, 'sd'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'sd', 'good.mjs'), 'const a = 1;\n', 'utf8');
+  fs.writeFileSync(path.join(root, 'sd', 'good.cjs'), 'module.exports = 1;\n', 'utf8');
+  fs.writeFileSync(path.join(root, 'sd', 'note.txt'), 'not scanned\n', 'utf8');
+  const r = run(root, ['sd']);
+  check('场景 1：全绿 → exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  check('场景 1：报数 2 且 txt 被排除', r.stdout.includes('✅ 2 个引擎脚本'), r.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：语法坏件 → exit 1 且点名 ----
+{
+  const root = mkroot();
+  fs.mkdirSync(path.join(root, 'sd'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'sd', 'good.mjs'), 'const a = 1;\n', 'utf8');
+  fs.writeFileSync(path.join(root, 'sd', 'broken.mjs'), 'if (true) entry.x process.env.Y;\n', 'utf8');
+  const r = run(root, ['sd']);
+  check('场景 2：混入坏件 → exit 1', r.status === 1, `exit=${r.status}`);
+  check('场景 2：stderr 点名坏文件', r.stderr.includes('sd/broken.mjs') && r.stderr.includes('1 个不可解析'), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：目录缺失 → exit 1（fail-closed） ----
+{
+  const root = mkroot();
+  const r = run(root, ['no-such-dir']);
+  check('场景 3：目录缺失 → exit 1 且提示 fail-closed', r.status === 1 && r.stderr.includes('检查目标目录缺失'), `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 4：空目录 → exit 1（可检数 0 拒放行） ----
+{
+  const root = mkroot();
+  fs.mkdirSync(path.join(root, 'sd'), { recursive: true });
+  const r = run(root, ['sd']);
+  check('场景 4：空目录 → exit 1 且提示数为 0', r.status === 1 && r.stderr.includes('可检文件数为 0'), `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) process.exit(1);
+process.exit(0);

package/templates/_agents/scripts/check-spec-verif.mjs

@@ -0,0 +1,47 @@
+// check-spec-verif.mjs — 检查 21：spec 验证落地核查 [warning]（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s21-spec-verif.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git 历史与
+//   CHANGELOG——装户径不引实例路径）
+// review P1「spec 承诺落地：spec §测试用例须真落到测试」的机器面：L2/L3 done spec 且建档日 ≥ 锚
+// （policy v9 specVerifSince；v1–v8 缺键 → 本段整体跳过），其「测试用例 / 验证计划 / 验证方式」节
+// 无测试文件或验证命令引用 → WARN（advisory——spec 可能以 UI 实测等人工可复跑方式验证，不做 hard）。
+// 缺键（v1–v8）→ 整体跳过；存量（< 锚）豁免。
+// 模块形态（kit check-hygiene / check-stage-index 先例的 run(ctx)）：判定语义单源在本文件，ctx 只传
+// check-loop.mjs 既有共享面（helper 单源在那边，复刻即造口径分叉）；warn 直接进 ctx.warnings，
+// 输出序 = check-loop 调用序（稳定输出契约）。
+// kit 适配（源仓→kit 逐条）：证据正则剔除源仓实例路径面（backend/…Tests.cs、frontend/__tests__、
+//   verify-ui）——kit 口径保留通用形态（.test.mjs / 回归清单 / 测试与门命令），见 VERIF_EVIDENCE_RE 注。
+import path from 'node:path';
+
+export function run(ctx) {
+  const { docFiles, fmGet, linesOf, addedDateOf, kitPolicy, warnings } = ctx;
+  // --- 21. spec 验证落地核查 [warning]（锚 specVerifSince）---
+  {
+    const anchor = kitPolicy.specVerifSince;
+    if (anchor) {
+      const VERIF_SEC_RE = /^##\s+.*(测试用例|验证计划|验证方式|测试与验证)/;
+      // 证据引用形态（宽匹配——门的是「验证节里有可复跑资产的身影」，不猜具体测试名）：
+      //   引擎 .test.mjs / 回归清单（kit 模板 workflow/regression-checklist.md）/ 冒烟与测试命令
+      //   （npm test、dotnet test、run-tests、check-scope、verify.mjs）。源仓实例路径面
+      //   （backend/…、\w+Tests.cs、frontend/…、verify-ui）按 instance-ref 门修法剔除，判据方向不变。
+      const VERIF_EVIDENCE_RE = /\.test\.mjs|workflow\/regression-checklist\.md|regression-smoke|npm\s+test|dotnet\s+test|run-tests|check-scope|verify\.mjs/;
+      for (const spec of docFiles('specs')) {
+        const st = fmGet(spec, '状态');
+        const lvl = fmGet(spec, '级别');
+        if (st !== 'done' || !['L2', 'L3'].includes(lvl)) continue;
+        const add = addedDateOf(spec);
+        if (!add || add < anchor) continue;
+        const lines = linesOf(spec) || [];
+        const secLines = [];
+        let inSec = false;
+        for (const l of lines) {
+          if (VERIF_SEC_RE.test(l)) { inSec = true; continue; }
+          if (inSec && /^##\s+/.test(l)) { inSec = false; continue; }
+          if (inSec) secLines.push(l);
+        }
+        if (secLines.length && !secLines.some((l) => VERIF_EVIDENCE_RE.test(l))) {
+          warnings.push(`- [WARN spec 验证落地] ${path.basename(spec)} 验证节无测试文件/验证命令引用——review P1「spec 承诺落地」要求落到可复跑验证资产`);
+        }
+      }
+    }
+  }
+}

package/templates/_agents/scripts/compact-ledgers.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-// compact-ledgers.mjs — 台账分片归并器（2026-10-12 ledger-shard-write 配套）
+// compact-ledgers.mjs — 台账分片归并器（2026-10-12 ledger-shard-write 配套；2026-10-13 ledger-shard-default 起为默认分片的收敛动作）
 // 用途：里程碑节点或发布前，把 `.agents/confirmations.d/*.jsonl` 的分片确认行并回主台账
-//   `.agents/confirmations.jsonl` 并清理分片。`--shard` 写入的分片若长期不归并，会让台账面无限碎片化，
-//   且分片的历史不受主台账的前缀不变量约束（见 check-ledger-invariant 已知边界）——本脚本就是收敛动作。
+//   `.agents/confirmations.jsonl` 并清理分片。分片已是**默认**写入口径（confirm-doc 不带 --no-shard 即写分片），
+//   长期不归并会让台账面无限碎片化——本脚本就是可选的收敛动作（跨分支合并另由 union driver 承担，归并非必需）。
 //
 // 保持 append-only 前缀不变量：主台账既有行**严格保序不动**，分片新行只追加到末尾——这正是
 //   check-ledger-invariant 的「旧 blob 是新 blob 的逐字节前缀」所要求的形态。绝不做重排/去重改写。