agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/verify.test.mjs

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
 // verify.mjs 的 fixture 测试（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具根，不触真实 npm test 与 workflow）
-// 断言：①绿路径（假过 + 空夹具闭环）exit 0；②步骤 1 假败 exit 1 且不出全绿；
-// ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言——孙进程 stdio inherit 输出不进本测试管道）；
-// ④⑤⑥凭证落账三态（绿落 / check-loop 红不落 / 无汇总行省略计数键）；
-// ⑦装户仓（cwd 无 package.json）未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2、exit 0；
-// ⑧--doc 绑定五态；⑨⑩嵌套套件同形汇总行不得被误取（计数口径=编排器权威套件数，2026-10-09 审查 P0-2 回归锁）。
+// 断言：①绿路径（假过 + 空夹具闭环）exit 0；②步骤假败 exit 1 且失败行留痕（suite=test）；
+// ③步骤 2 配对断裂夹具 exit 1（verify 自身标记断言）；④凭证落账（绿行 + 计数捕获）；
+// ④b fixture 绿不产 committed 摘要；⑤check-loop 红失败行留痕、无绿行；
+// ⑥无汇总行省略计数键；⑦装户仓（cwd 无 package.json）跳过测试门、不落凭证、其余门全过 → exit 0；
+// ⑧--doc 绑定五态；⑨⑩嵌套套件同形汇总行不得被误取；⑪--list 七门序；⑫--list 与 --test-cmd 互斥；
+// ⑬生产模式中段红 → fail-fast + 未执行门清单 + 失败行留痕；
+// ⑭生产模式全绿端到端（七门 + 凭证含门数/headShort/套件计数 + 绿凭证摘要生成）。
+// 生产模式夹具经 fixture-scripts.mjs#copyScriptClosure 把门脚本依赖闭包拷进临时根（并种子
+// workflow/effective-policy.md——生效规则视图门对缺文件判漂移，与 init 生成器首跑同款）。
 // 用法：node templates/_agents/scripts/verify.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';
+import { copyScriptClosure } from './fixture-scripts.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const VERIFY = path.join(SCRIPT_DIR, 'verify.mjs');
@@ -35,7 +40,7 @@ const mkfix = () => {
     'doc.status.abandoned=superseded cancelled',
     'incident.status.all=open fixed closed',
     'incident.status.active=open',
-    'level.all=L0 L1 L2 L3',
+    'level.all=L1 L2 L3',
     '',
   ].join('\n'), 'utf8');
   return d;
@@ -57,6 +62,33 @@ const mkCmd = (code, out = '') => {
 };
 const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv], { encoding: 'utf8', ...opts });
 
+// 生产模式夹具：门脚本依赖闭包拷贝 + .agents/hooks 目录（语法门 fail-closed 要求）+
+// workflow/effective-policy.md 种子（生效规则视图门对缺文件判漂移——与 init §6 生成器首跑同款）
+const provision = (root) => {
+  fs.mkdirSync(path.join(root, '.agents', 'hooks'), { recursive: true });
+  copyScriptClosure(path.join(root, '.agents', 'scripts'), [
+    'check-scripts-syntax.mjs', 'workflows-check.mjs', 'rule-budget.mjs',
+    'gen-effective-policy.mjs', 'check-ledger-invariant.mjs', 'check-loop.mjs',
+  ]);
+  const gen = spawnSync(process.execPath, [path.join(root, '.agents', 'scripts', 'gen-effective-policy.mjs'), '--root', root], { encoding: 'utf8' });
+  if (gen.status !== 0) throw new Error(`夹具种子生成失败：${gen.stdout}${gen.stderr}`);
+  return root;
+};
+// 生产夹具变 git 仓（台账不变量门在非 git 根会 fail-closed；commit 供凭证 headShort 钉 SHA）
+const gitify = (root) => {
+  const g = (a) => spawnSync('git', ['-C', root, ...a], { encoding: 'utf8' });
+  g(['init']);
+  g(['-c', 'user.email=fixture@test', '-c', 'user.name=fixture', 'add', '-A']);
+  const c = g(['-c', 'user.email=fixture@test', '-c', 'user.name=fixture', 'commit', '-m', 'fixture init', '--no-gpg-sign', '-q']);
+  if (c.status !== 0) throw new Error(`夹具 git commit 失败：${c.stderr}`);
+  return g(['rev-parse', '--short', 'HEAD']).stdout.trim();
+};
+const readLedger = (root) => {
+  const p = path.join(root, '.agents', 'verifications.jsonl');
+  if (!fs.existsSync(p)) return [];
+  return fs.readFileSync(p, 'utf8').split(/\r?\n/).filter(Boolean).map((l) => JSON.parse(l));
+};
+
 // ---- 场景 1：绿路径——假过 + 空夹具闭环 → exit 0 ----
 {
   const root = mkfix();
@@ -66,12 +98,16 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   fs.rmSync(root, { recursive: true, force: true });
 }
 
-// ---- 场景 2：红路径步骤 1——假败 → exit 1、fail-fast 不出全绿 ----
+// ---- 场景 2：红路径测试门——假败 → exit 1、fail-fast 不出全绿；失败行留痕 ----
 {
   const root = mkfix();
   const r = run(['--test-cmd', `node ${mkCmd(3)}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
   check('场景 2：exit 1', r.status === 1, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
-  check('场景 2：步骤 1 失败标记在 stderr，且不输出全绿', r.stderr.includes('❌ 1/2') && !r.stdout.includes('全绿'), `${r.stdout}\n${r.stderr}`);
+  check('场景 2：步骤失败标记在 stderr，且不输出全绿', r.stderr.includes('❌ 1/2') && !r.stdout.includes('全绿'), `${r.stdout}\n${r.stderr}`);
+  const lines = readLedger(root);
+  check('场景 2：测试门红 → 失败行留痕（exitCode 3 + suite=test）',
+    lines.length === 1 && lines[0].exitCode === 3 && lines[0].suite === 'test' && typeof lines[0].ts === 'string',
+    `lines=${JSON.stringify(lines)}`);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
@@ -84,65 +120,75 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   fs.rmSync(root, { recursive: true, force: true });
 }
 
-// ---- 场景 4：绿路径凭证落账（2026-10-07 verify-evidence）——全绿后 fixture 台账出合法绿行 ----
+// ---- 场景 4：绿路径凭证落账——全绿后 fixture 台账出合法绿行（计数捕获 + testCmd 注入输出口径） ----
 {
   const root = mkfix();
   const r = run(['--test-cmd', `node ${mkCmd(0, '[run-tests] 合计: SUITES 3 / FAILED 0\n')}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
-  const vp = path.join(root, '.agents', 'verifications.jsonl');
-  const line = fs.existsSync(vp) ? JSON.parse(fs.readFileSync(vp, 'utf8').trim()) : null;
-  check('场景 4：全绿 → verifications.jsonl 落绿行（exitCode 0 + 计数捕获）',
+  const line = readLedger(root)[0] || null;
+  check('场景 4：全绿 → verifications.jsonl 落绿行（exitCode 0 + 计数捕获 + 门数）',
     r.status === 0 && line !== null && line.exitCode === 0 && line.passed === 3 && line.failed === 0
-      && typeof line.ts === 'string' && r.stdout.includes('凭证已落账'),
+      && line.gates === 2 && typeof line.ts === 'string' && line.suite === 'npm test' && r.stdout.includes('凭证已落账'),
     `exit=${r.status} line=${JSON.stringify(line)}`);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
-// ---- 场景 5：红路径不落账（check-loop 红 → fail-fast 在落账前退出）----
+// ---- 场景 4b：fixture 全绿不得触发摘要生成（假门凭证只进本地台账，不产 committed 摘要） ----
+{
+  const root = mkfix();
+  const r = run(['--test-cmd', `node ${mkCmd(0, '[run-tests] 合计: SUITES 3 / FAILED 0\n')}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  const ev = path.join(root, 'workflow', 'verify-evidence.md');
+  check('场景 4b：fixture 绿 → 不生成 workflow/verify-evidence.md、输出无摘要生成标记',
+    r.status === 0 && !fs.existsSync(ev) && !r.stdout.includes('已生成'),
+    `exit=${r.status} exists=${fs.existsSync(ev)}\n${r.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 5：check-loop 红 → 失败行留痕、无绿行（失败也留痕；绿行语义 = verify 全绿不变） ----
 {
   const root = mkBroken();
   const r = run(['--test-cmd', `node ${mkCmd(0)}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
-  check('场景 5：npm test 绿但 check-loop 红 → 无凭证行（凭证语义 = verify 全绿）',
-    r.status === 1 && !fs.existsSync(path.join(root, '.agents', 'verifications.jsonl')),
-    `exit=${r.status}`);
+  const lines = readLedger(root);
+  check('场景 5：测试门绿但 check-loop 红 → 仅失败行（suite=check-loop），无绿行',
+    r.status === 1 && lines.length === 1 && lines[0].exitCode !== 0 && lines[0].suite === 'check-loop'
+      && !lines.some((l) => l.exitCode === 0),
+    `exit=${r.status} lines=${JSON.stringify(lines)}`);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
-// ---- 场景 6：输出无汇总行 → 计数键省略（exitCode 才是硬事实）----
+// ---- 场景 6：输出无汇总行 → 计数键省略（exitCode 才是硬事实） ----
 {
   const root = mkfix();
   const r = run(['--test-cmd', `node ${mkCmd(0, 'ok\n')}`], { env: { ...process.env, CHECK_LOOP_ROOT: root } });
-  const vp = path.join(root, '.agents', 'verifications.jsonl');
-  const line = fs.existsSync(vp) ? JSON.parse(fs.readFileSync(vp, 'utf8').trim()) : null;
+  const line = readLedger(root)[0] || null;
   check('场景 6：无汇总输出 → 绿行落盘但计数键省略',
     r.status === 0 && line !== null && line.exitCode === 0 && !('passed' in line) && !('failed' in line),
     `line=${JSON.stringify(line)}`);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
-// ---- 场景 7：装户仓（cwd 无 package.json）且未给 --test-cmd → 跳过步骤 1、不落凭证、仍跑步骤 2 → exit 0 ----
+// ---- 场景 7：装户仓（cwd 无 package.json）且未给 --test-cmd → 跳过测试门、不落凭证、其余门全过 → exit 0 ----
 {
- const root = mkfix();
- const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-'));
- const r = run([], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: root } });
- check('场景 7：exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
- check('场景 7：步骤 1 显式跳过（⏭ 1/2）、步骤 2 通过且全绿', r.stdout.includes('⏭ 1/2') && r.stdout.includes('✅ 2/2') && r.stdout.includes('全绿'), r.stdout);
- check('场景 7：跳过时不落测试绿凭证（防假绿）',
- !fs.existsSync(path.join(root, '.agents', 'verifications.jsonl')) && r.stdout.includes('不落测试绿凭证'),
- r.stdout);
- fs.rmSync(root, { recursive: true, force: true });
- fs.rmSync(bare, { recursive: true, force: true });
+  const root = provision(mkfix());
+  gitify(root);
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-'));
+  const r = run([], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  check('场景 7：exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  check('场景 7：测试门显式跳过（⏭ 2/7）、末门通过且全绿', r.stdout.includes('⏭ 2/7') && r.stdout.includes('✅ 7/7') && r.stdout.includes('全绿'), r.stdout);
+  check('场景 7：跳过时不落测试绿凭证（防假绿）且不生成摘要',
+    readLedger(root).length === 0 && !fs.existsSync(path.join(root, 'workflow', 'verify-evidence.md')) && r.stdout.includes('不落测试绿凭证'),
+    r.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(bare, { recursive: true, force: true });
 }
 
-// ---- 场景 8：--doc 凭证绑定（2026-10-08 verify-doc-binding）----
+// ---- 场景 8：--doc 凭证绑定 ----
 // ① 带 --doc → 末行含 doc 且为规范化 posix 相对路径；② 不带 → 末行**无 doc 键**（不是 null）；
 // ③ win32 反斜杠 / posix / 绝对路径三种写法落同一值（归一是本单的地基，错一处=凭证永远匹配不上）；
-// ④ 缺值 → exit 1 用法错误；⑤ 跳过步骤 1 时即便带 --doc 仍不落账（防假绿语义不得被 --doc 破坏）。
+// ④ 缺值 → exit 1 用法错误；⑤ 跳过测试门时即便带 --doc 仍不落账（防假绿语义不得被 --doc 破坏）。
 {
   const readLast = (root) => {
-    const p = path.join(root, '.agents', 'verifications.jsonl');
-    if (!fs.existsSync(p)) return null;
-    const lines = fs.readFileSync(p, 'utf8').trim().split('\n').filter(Boolean);
-    return lines.length ? JSON.parse(lines[lines.length - 1]) : null;
+    const lines = readLedger(root);
+    return lines.length ? lines[lines.length - 1] : null;
   };
 
   const rootA = mkfix();
@@ -175,27 +221,27 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   check('场景 8④：--doc 缺值 → exit 1 + 用法提示',
     rD.status === 1 && /--doc 缺值/.test(rD.stderr), `exit=${rD.status} ${rD.stderr}`);
 
-  const rootE = mkfix();
+  const rootE = provision(mkfix());
+  gitify(rootE);
   const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-doc-'));
   const rE = run(['--doc', rel], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: rootE } });
-  check('场景 8⑤：步骤 1 跳过时即便带 --doc 仍不落账（防假绿语义不被 --doc 破坏）',
-    rE.status === 0 && !fs.existsSync(path.join(rootE, '.agents', 'verifications.jsonl')) && rE.stdout.includes('不落测试绿凭证'),
+  check('场景 8⑤：测试门跳过时即便带 --doc 仍不落账（防假绿语义不被 --doc 破坏）',
+    rE.status === 0 && readLedger(rootE).length === 0 && rE.stdout.includes('不落测试绿凭证'),
     `exit=${rE.status} ${rE.stdout}`);
 
   for (const r of [rootA, rootB, rootC, rootD, rootE]) fs.rmSync(r, { recursive: true, force: true });
   fs.rmSync(bare, { recursive: true, force: true });
 }
 
-// ---- 场景 9 / 10：嵌套套件同形汇总行不得被误取（2026-10-09 审查 P0-2 回归锁）----
-// 缺陷复现：旧判据 pop 通配「合计: PASS n / FAIL n」，而全仓 45+ 套件每个都打印自己那行同形文本，
-// 取到的是字母序最后一个套件的场景数（本仓实况 workflows-check.test.mjs = 15），落进凭证 passed。
+// ---- 场景 9 / 10：嵌套套件同形汇总行不得被误取（计数口径=编排器权威套件数，回归锁） ----
+// 缺陷复现：旧判据 pop 通配「合计: PASS n / FAIL n」，而全套件每个都打印自己那行同形文本，
+// 取到的是字母序最后一个套件的场景数，落进凭证 passed。
 // ⑨ 权威行与同形行并存 → 取权威套件数；⑩ 仅有同形行 → 省略计数键（宁缺勿错，不回退到错的事实）。
 {
   const root9 = mkfix();
   const r9 = run(['--test-cmd', `node ${mkCmd(0, '合计: PASS 15 / FAIL 0\n[run-tests] 合计: SUITES 45 / FAILED 0\n')}`],
     { env: { ...process.env, CHECK_LOOP_ROOT: root9 } });
-  const vp9 = path.join(root9, '.agents', 'verifications.jsonl');
-  const l9 = fs.existsSync(vp9) ? JSON.parse(fs.readFileSync(vp9, 'utf8').trim()) : null;
+  const l9 = readLedger(root9)[0] || null;
   check('场景 9：嵌套套件同形行不被误取，计数取编排器权威套件数',
     r9.status === 0 && l9 !== null && l9.passed === 45 && l9.failed === 0,
     `line=${JSON.stringify(l9)}`);
@@ -204,14 +250,77 @@ const run = (argv, opts = {}) => spawnSync(process.execPath, [VERIFY, ...argv],
   const root10 = mkfix();
   const r10 = run(['--test-cmd', `node ${mkCmd(0, '合计: PASS 15 / FAIL 0\n')}`],
     { env: { ...process.env, CHECK_LOOP_ROOT: root10 } });
-  const vp10 = path.join(root10, '.agents', 'verifications.jsonl');
-  const l10 = fs.existsSync(vp10) ? JSON.parse(fs.readFileSync(vp10, 'utf8').trim()) : null;
+  const l10 = readLedger(root10)[0] || null;
   check('场景 10：仅有嵌套同形行 → 绿行落盘但省略计数键（不回退到错的事实）',
     r10.status === 0 && l10 !== null && l10.exitCode === 0 && !('passed' in l10) && !('failed' in l10),
     `line=${JSON.stringify(l10)}`);
   fs.rmSync(root10, { recursive: true, force: true });
 }
 
+// ---- 场景 11：--list 锁定 engine cohort 七门序，不执行门 ----
+{
+  const expect = ['scripts-syntax', 'engine-tests', 'workflows-check', 'rule-budget', 'effective-policy', 'check-loop', 'ledger-invariant'];
+  const r = run(['--list'], {});
+  const ids = (r.stdout || '').trim().split(/\r?\n/).filter(Boolean);
+  check('场景 11：--list exit 0 且恰七门、序不变、不执行',
+    r.status === 0 && ids.length === expect.length && expect.every((id, i) => ids[i] === id)
+      && !String(r.stdout).includes('开始静态门'),
+    `exit=${r.status}\n${r.stdout}`);
+}
+
+// ---- 场景 12：--list 与 --test-cmd 互斥 ----
+{
+  const r = run(['--list', '--test-cmd', 'node nothing.mjs'], {});
+  check('场景 12：--list + --test-cmd → exit 1', r.status === 1 && /互斥/.test(r.stderr), `exit=${r.status} ${r.stderr}`);
+}
+
+// ---- 场景 13：生产模式中段红 → fail-fast + 未执行门清单 + 失败行留痕 ----
+// 编排脚本检查门注入一份缺 frontmatter 的坏编排（E1 error）→ 第 3 门红，后四门状态未知须点名
+{
+  const root = provision(mkfix());
+  fs.mkdirSync(path.join(root, '.agents', 'workflows'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'workflows', 'bad.md'), '没有 frontmatter 的坏编排\n', 'utf8');
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-bare-ff-'));
+  const r = run([], { cwd: bare, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  check('场景 13：exit 1 且不出全绿', r.status === 1 && !r.stdout.includes('全绿'), `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  check('场景 13：fail-fast 点名未执行门（rule-budget、effective-policy、check-loop、ledger-invariant）',
+    r.stderr.includes('未执行门') && ['rule-budget', 'effective-policy', 'check-loop', 'ledger-invariant'].every((id) => r.stderr.includes(id)),
+    r.stderr);
+  const lines = readLedger(root);
+  check('场景 13：失败行留痕（suite=workflows-check）且无绿行',
+    lines.length === 1 && lines[0].suite === 'workflows-check' && lines[0].exitCode !== 0,
+    `lines=${JSON.stringify(lines)}`);
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(bare, { recursive: true, force: true });
+}
+
+// ---- 场景 14：生产模式全绿端到端——七门按序全过、凭证钉门数/headShort/套件计数、摘要生成 ----
+{
+  const root = provision(mkfix());
+  // 根 package.json（装户带根 package.json 的形态）：测试命令打印编排器权威汇总行
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({
+    name: 'verify-e2e-fixture',
+    private: true,
+    scripts: { test: 'node .agents/probe-test.mjs' },
+  }, null, 2));
+  fs.writeFileSync(path.join(root, '.agents', 'probe-test.mjs'), "console.log('[run-tests] 合计: SUITES 3 / FAILED 0');\n", 'utf8');
+  const headShort = gitify(root);
+  const r = run([], { cwd: root, env: { ...process.env, CHECK_LOOP_ROOT: root } });
+  check('场景 14：exit 0 且七门逐门输出 + 全绿',
+    r.status === 0 && ['✅ 1/7', '✅ 2/7', '✅ 3/7', '✅ 4/7', '✅ 5/7', '✅ 6/7', '✅ 7/7'].every((s) => r.stdout.includes(s)) && r.stdout.includes('全绿'),
+    `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  const line = readLedger(root)[0] || null;
+  check('场景 14：绿凭证钉门数 7 + headShort + 套件计数',
+    line !== null && line.exitCode === 0 && line.gates === 7 && line.headShort === headShort && line.passed === 3 && line.failed === 0,
+    `headShort=${line && line.headShort} expect=${headShort} line=${JSON.stringify(line)}`);
+  const ev = path.join(root, 'workflow', 'verify-evidence.md');
+  const evText = fs.existsSync(ev) ? fs.readFileSync(ev, 'utf8') : '';
+  check('场景 14：绿凭证摘要已生成且含本 SHA 一行（自动重生成接线）',
+    fs.existsSync(ev) && evText.includes(`\`${headShort}\``) && evText.includes('| 7 | PASS 3 / FAIL 0 |'),
+    evText);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node templates/_agents/scripts/verify.test.mjs');

package/templates/_agents/scripts/wf-journal.mjs

@@ -15,6 +15,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseStages } from './workflows-check.mjs';
+// 委派台账分片感知读（2026-10-13 ledger-shard-ledgers 回灌）：单源 = ledger-shards.readDelegationsText。
+import { readDelegationsText as readDelegationsShardText } from './ledger-shards.mjs';
 
 function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
 
@@ -162,8 +164,9 @@ if (isMain) {
   fail(`未知命令：${a.cmd ?? ''}（add | status，用法见文件头注释）`);
 }
 function readDelegationsText(file) {
-  const p = file || path.join(process.cwd(), 'workflow', 'delegations.md');
-  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+  // 分片感知读（2026-10-13 ledger-shard-ledgers 回灌）：单源 = ledger-shards.readDelegationsText。
+  //（file 为显式注入路径时只读该文件——测试语义不变；null/默认路径 → 主台账 ∪ delegations.d/*.md）
+  return readDelegationsShardText(process.cwd(), file || null);
 }
 
 function delegationSectionRows(text) {
@@ -172,8 +175,9 @@ function delegationSectionRows(text) {
   const rows = [];
   for (const line of lines) {
     if (/^##\s+/.test(line)) {
-      if (inSec) break;
-      if (/^##\s+委派结果\s*$/.test(line)) inSec = true;
+      // 不 break：合并文本（主台账 ∪ 分片）里 `## 委派结果` 会出现多次，break 会漏掉后续分片的行
+      // （2026-10-13 源仓实测踩中：分片行读不到 → 静默漏报「委派台账未记录」）。
+      inSec = /^##\s+委派结果\s*$/.test(line);
       continue;
     }
     if (!inSec || !/^\s*\|/.test(line)) continue;

package/templates/_agents/scripts/wf-journal.test.mjs

@@ -139,7 +139,7 @@ const STAGES = parseStages(`| id | after | role | step | task | files | accept |
     const j = path.join(os.tmpdir(), `wfj-real-${Date.now()}.jsonl`);
     const r = spawnSync(process.execPath, [JOURNAL_CLI, 'status', '--wf', 'pipeline-closing', '--journal', j], { encoding: 'utf8', cwd: ROOT });
     check('S9 真实 pipeline-closing：confirm 为 human 形态且无 journal 时 author 首层就绪',
-      !!confirm && confirm.human && !confirm.role && stages.length >= 10
+      !!confirm && confirm.human && !confirm.role && stages.length >= 9
         && r.status === 0 && /就绪（第 0 层.*author/.test(r.stdout),
       JSON.stringify({ confirm, out: r.stdout }));
     fs.rmSync(j, { force: true });

package/templates/_agents/scripts/wiki-search.test.mjs

@@ -6,22 +6,21 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } 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 COPIED = ['wiki-search.mjs', 'kb-search.mjs', 'workflow-enums.mjs'];
+// 夹具闭包（2026-10-12 fixture-closure-rootfix）：入口只写 wiki-search.mjs，kb-search 及其传递依赖
+// （workflow-enums.mjs 等）由闭包自动带入——此前手写枚举，漏拷即 import 失败 → 假绿。
+const { copyScriptClosure, copyAgentsFiles } = await import('./fixture-scripts.mjs');
 function mkFixture() {
   const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'ws-'));
   fs.mkdirSync(path.join(fx, '.agents', 'scripts'), { recursive: true });
-  for (const f of COPIED) fs.copyFileSync(path.join(SRC, f), path.join(fx, '.agents', 'scripts', f));
-  for (const f of ['workflow-enums.txt', 'workflow-modules.txt'])
-    fs.copyFileSync(path.join(SRC, '..', f), path.join(fx, '.agents', f));
+  copyScriptClosure(path.join(fx, '.agents', 'scripts'), ['wiki-search.mjs']);
+  copyAgentsFiles(path.join(fx, '.agents'), ['workflow-enums.txt', 'workflow-modules.txt']);
   fs.mkdirSync(path.join(fx, 'wiki', '测试主题'), { recursive: true });
   fs.writeFileSync(path.join(fx, 'wiki', '测试主题', '说明.md'), '# 说明\n\n编码模板的领域知识条目。\n');
   fs.mkdirSync(path.join(fx, 'workflow', 'intents'), { recursive: true });

package/templates/_agents/scripts/workflow-board-server.test.mjs

@@ -64,7 +64,7 @@ const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
     'doc.status.abandoned=superseded cancelled',
     'incident.status.all=open fixed closed',
     'incident.status.active=open',
-    'level.all=L0 L1 L2 L3',
+    'level.all=L1 L2 L3',
   ].join('\n') + '\n');
   const w = (rel, c) => fs.writeFileSync(path.join(T, rel), c);
   // 回路断档：incident 三件套选「是」但引用 intent 不存在
@@ -169,7 +169,7 @@ const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
     requirement: '在 runtime-env.md 补记 pipeline-run 运行态',
     stage: 'done',
     stopType: 'done',
-    triage: { kind: 'require', level: 'L0', module: 'pipeline', topic: 'runtime-note', decidedBy: 'ai' },
+    triage: { kind: 'require', level: 'L1', module: 'pipeline', topic: 'runtime-note', decidedBy: 'ai' },
     updatedAt: '2026-10-02T10:19:22.566Z',
     events: [
       { t: '2026-10-02T10:19:02.680Z', type: 'run-created', requirement: 'x' },

package/templates/_agents/scripts/workflow-enums.test.mjs

@@ -1,6 +1,6 @@
 // workflow-enums.test.mjs — 枚举单源读取器测试（2026-09-25 enum-single-source）
 // 判据：① 真实单源文件解析 + 不变量通过 ② 坏数据（坏行/重复键/重复值/缺键/子集破/重叠）fail-loud
-//       ③ 缺文件 fail-loud ④ sh 消费方同口径（sed 可取到全部 8 键）
+//       ③ 缺文件 fail-loud ④ sh 消费方同口径（sed 可取到全部键）
 // 用法：node templates/_agents/scripts/workflow-enums.test.mjs（npm test 随跑）
 import path from 'node:path';
 import { execSync } from 'node:child_process';
@@ -20,14 +20,22 @@ const throwsWith = (fn, kw) => {
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ENUMS_TXT = path.join(SCRIPT_DIR, '..', 'workflow-enums.txt');
 
-// ---- S1 模块级 ENUMS 即加载即校验（真实文件），8 键齐 ----
+// ---- S1 模块级 ENUMS 即加载即校验（真实文件），10 键齐（2026-10-13 自 Shipyard 回灌归因两键）----
 {
   const keys = Object.keys(ENUMS).sort();
-  check('S1 真实单源文件加载成功且 8 键齐',
-    keys.length === 8 && keys.join(',') === 'doc.status.abandoned,doc.status.active,doc.status.all,doc.status.confirmed,doc.status.terminal,incident.status.active,incident.status.all,level.all',
+  check('S1 真实单源文件加载成功且 10 键齐',
+    keys.length === 10 && keys.join(',') === 'doc.status.abandoned,doc.status.active,doc.status.all,doc.status.confirmed,doc.status.terminal,incident.env.all,incident.source.all,incident.status.active,incident.status.all,level.all',
     JSON.stringify(keys));
 }
 
+// ---- S1b 归因两键值域逐字对齐 Shipyard（incident.source.all / incident.env.all）----
+{
+  check('S1b 归因两键值域：source=self user test monitor、env=dev staging prod none',
+    ENUMS['incident.source.all'].join('+') === 'self+user+test+monitor'
+      && ENUMS['incident.env.all'].join('+') === 'dev+staging+prod+none',
+    JSON.stringify(ENUMS));
+}
+
 // ---- S2 真实文件关键值口径（check-loop/看板/检索的行为锚点，值变更须连本测试一起改）----
 {
   check('S2 关键集值口径：confirmed 不含 draft、active=draft+approved、terminal 含 done、abandoned ⊆ terminal',
@@ -35,7 +43,8 @@ const ENUMS_TXT = path.join(SCRIPT_DIR, '..', 'workflow-enums.txt');
       && ENUMS['doc.status.active'].join('+') === 'draft+approved'
       && ENUMS['doc.status.terminal'].includes('done')
       && ENUMS['doc.status.abandoned'].every((v) => ENUMS['doc.status.terminal'].includes(v))
-      && ENUMS['level.all'].length === 4,
+      // level.all=L1 L2 L3——L0 已退役（2026-10-13 自源仓收敛系列 1 回灌）
+      && ENUMS['level.all'].join('+') === 'L1+L2+L3',
     JSON.stringify(ENUMS));
 }
 

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

@@ -27,7 +27,7 @@
 //        到首个非 `|` 行截止；仅此一张表——编排脚本按机制文档只允许一张 stages 表。
 // 用法：node .agents/scripts/workflows-check.mjs [--root <目标根>] [--json]
 //       默认根 = process.cwd()（doctor 以 cwd=target 调用；仓库根直跑即自扫）
-// 零依赖；只报告不修复（B-b 决策口径，同 source-sync-check）
+// 零依赖；只报告不修复（B-b 决策口径）
 // 测试：node templates/_agents/scripts/workflows-check.test.mjs（fixture + 真实仓库 baseline）
 import fs from 'node:fs';
 import path from 'node:path';

package/templates/_agents/scripts-test-exempt.txt

@@ -4,6 +4,7 @@
 # 新增引擎脚本默认必须带同名 .test.mjs（README 规范条目）；确属库件/工具才登记本文件。
 # 2026-10-09 A2 评估：verify-wiki-consistency 已移出（补测 3 场景）；wiki-search 已移出（转发壳，判定单源 kb-search.test 覆盖）。
 check-metric-claims.mjs | 经 check-loop.mjs 消费 | 由 check-loop.test.mjs 间接覆盖其调用路径
+rule-budget.mjs | 判定器（2026-10-13 自 .sh 移植 node；经 check-hygiene 检查 13 与 pre-commit 消费，Shipyard 侧同无直测） | check-loop.test.mjs 场景 28-30（含 --staged 硬拦两态）+ check-loop-rev.test.mjs 间接覆盖；src/rule-budget.test.mjs 平行实现作口径对照
 ensure-board.mjs | 看板启动器 | 永久工具豁免（需真实端口/进程环境，自动化覆盖无性价比——2026-10-09 engine-quality-round2 A2 评估定性）
 policy.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖
 # 2026-10-12 needs-clarification：stage-gates.mjs 已建同名直测（stage-gates.test.mjs 15 断言），

package/templates/_agents/skills/papercut-fix/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: papercut-fix
+description: 修 workflow/papercuts.md 里指定的未升级 papercut 条目（把存量债降到 0 的回路执行器）。按控制器给的行号定位症状、照「拟修」列改权威文件、回写台账并跑验证门。
+---
+
+# papercut-fix — 单条 papercut 升级执行器
+
+## 目标
+将 `workflow/papercuts.md` 中指定的一条 papercut 条目状态更新为「已消债」。
+
+## 触发条件
+- 用户指令：`跑一轮 papercut 回路` / `清 papercut 存量` / `修第 N 条 papercut`。
+
+## 约束与红线
+- **单一目标**：每轮执行仅处理一条目标，禁止顺手修复相邻条目或夹带其他改动。
+- **范围限制**：改动仅限文档面（`.agents/commands/`, `.agents/roles/`, `.agents/skills/`, `.githooks/`, `.agents/scripts/`, `workflow/`）。
+- **绝对禁区**：禁止修改 `backend/`, `frontend/`, `tests/`, `wiki/`，禁止连接数据库——与控制器 scope gate（`OUT_OF_SCOPE` 正则）同一清单，命中即停。超出范围时必须停止并报告用户。
+- **验证优先**：禁止凭台账描述臆测现状。必须先读权威文件验证症状是否成立。
+- **编辑规范**：修改 `workflow/` 文档必须使用 Edit 工具。禁止使用 `node -e` 或脚本批量替换（CRLF 环境下会静默失败）。
+- **消债判定**：分支 A（修复）与分支 B（暂缓/失效）**均**满足 `debt -1` 不变量。
+
+## 工作流
+
+### 1. 定位与预检
+- 从控制器输出提取：`行号` (Lxx), `位置` (路径), `症状`, `拟修`。
+- 使用 Read 工具读取该行及其上下文。
+
+### 2. 现状验证
+- 读取「位置」列指定的权威文件。
+- **判定结论**：
+    - **缺陷仍在** $\rightarrow$ 进入分支 A。
+    - **已失效** (已被其他改动修复/文件已删除) $\rightarrow$ 进入分支 B。
+    - **方向相反/描述有误** $\rightarrow$ 重新定性后再执行。
+
+### 3. 执行修复
+- **分支 A (缺陷仍在)**：
+    1. 对权威文件执行最小化修复。
+    2. 在 `workflow/papercuts.md`（或承载该条目的 `workflow/papercuts.d/` 分片）该行末尾追加：`✅ 已升级修复(YYYY-MM-DD): <改动描述> <commit>`。
+    3. 若原「拟修」描述已不适用，在追加记录中写明实际修法。
+- **分支 B (已失效)**：
+    1. 在 `workflow/papercuts.md`（或承载该条目的分片）该行末尾追加：`⏸ 暂缓(YYYY-MM-DD): <失效理由>`。理由必须明确。
+    2. **核实纪律**：
+        - 检查用户级技能目录（`~/.claude/skills/`、`~/.trae/skills/` 等宿主适配目录）确认文件是否仅是迁移而非删除。
+        - 区分「环境约束」与「代码缺陷」。
+        - 针对「跨环境」症状，使用 `git worktree` 构建真实检出态实验证伪。
+        - 针对「已落地」症状，使用 `git log -S` 追溯引入提交日期。
+- **分支 C (越界)**：停止执行，报告理由并请求授权。
+
+### 4. 验证与收尾
+- **备份**：修改台账（主台账或分片）前强制 `cp <台账文件> tmp/papercuts.wip-backup.md`。
+- **运行检查**：
+    - `node .agents/scripts/papercut-debt-sensor.mjs` $\rightarrow$ `debt` 必须恰好减少 1。
+    - `node .agents/scripts/papercut-debt-controller.mjs` $\rightarrow$ 确认目标推进。
+    - 检查台账（主台账 ∪ 分片）的总行数（`total` 不得减少——`debt` 符合预期 ≠ 文件没被压行）、列数分布及是否存在超长行（压行信号）。
+- **体积检查**：若修改了 `.agents/commands/`，跑 `node .agents/scripts/rule-budget.mjs --staged` 对比 `.agents/rule-budgets.txt` 上限（一进一出；禁用工作区 `wc -c` 核对——CRLF 膨胀会误报）。
+
+## 回报要求
+- 参照 `references/response-template.md` 输出。
+- 包含：行号、位置、分支结论(A/B/C)、改动文件、验证结果(debt 前后值)、待决策事项。
+- **禁令**：禁止自动 commit 或 push。

package/templates/_agents/skills/papercut-fix/references/response-template.md

@@ -0,0 +1,81 @@
+# papercut-fix 回应模板
+
+单轮回路执行器的最终输出格式。给用户看，决定他是否放行这次改动。
+
+---
+
+## 模板
+
+```markdown
+papercut 回路 · 第 N 轮
+
+**目标**：L{line} `{location}`（{date}，第 {hits} 次命中）
+**结论**：{A 缺陷仍在 / B 已失效 / B2 账未销（拟修已由别的改动落地）/ B3 台账方向记反（检出态实验证伪）/ C 越界待授权}
+
+### 改动
+
+| 文件 | 改了什么 |
+|---|---|
+| `{权威文件路径}` | {一句话} |
+| `workflow/papercuts.md` | 回写行标记：{`✅ 已升级修复（日期）` / `⏸ 暂缓（日期）：理由`} |
+
+### 验证
+
+- `papercut-debt-sensor.mjs`：debt {before} → {after}（预期 -1）
+- {其他检查，如体积预算核对：通过 / 不适用}
+
+### 台账依据
+
+{若实际修法与「拟修」列描述不一致，在此说明「拟修」列写的什么、实际怎么做的、为什么。
+ B2 结论必须写出落地提交：`由 <sha>（<日期>，<标题>）落地`。}
+
+### 需你决定
+
+{列出需要用户拍板的事项；没有则写「无」。典型场景：
+ - 结论为 C（越界）——是否单独授权改源码/连库
+ - 「拟修」列描述已过期——是否更新该列文本
+ - 控制器列出的「待人工定性」条目——是否本轮顺带定性
+ - 改动触及常驻面体积预算——是否接受，或改为下沉/删除被取代条目}
+```
+
+---
+
+## 格式要求
+
+1. **先给结论，再给细节**。用户扫第一行就要知道"修了哪条、结论是什么"。
+2. **「需你决定」不许空着**。即使本轮无事，也显式写「无」——让"没有待决事项"和"忘了写"可区分。
+3. **验证值给具体数字**，不要只说"验证通过"。debt 的前后值是设定点误差，必须可核。
+4. **不粉饰失败**。验证门红了就写红，附命令与原始报错摘要。回路的价值在于给出可信的账，不是好看的账。
+5. **不写"建议接下来…"式的空话**。要写就写具体动作 + 具体条目编号。
+
+---
+
+## 示例（结论 A，示意——占位符形态，非真实条目）
+
+```markdown
+papercut 回路 · 第 3 轮
+
+**目标**：L34 `.agents/commands/test.md`（静态门清单 §2 缺一条豁免说明）（<日期>）
+**结论**：A 缺陷仍在
+
+### 改动
+
+| 文件 | 改了什么 |
+|---|---|
+| `.agents/commands/test.md` | §2 补一条：跳过条件的判据以 <权威判据> 为准，不以 <表象> 为准；§常见误判 补对应条目 |
+| `workflow/papercuts.md` | 回写 L34 标记：`✅ 已升级修复（YYYY-MM-DD）` |
+
+### 验证
+
+- `papercut-debt-sensor.mjs`：debt 16 → 15（预期 -1）
+- 体积预算：`node .agents/scripts/rule-budget.mjs --staged` 通过（未触 `.agents/commands/` 上限）
+
+### 台账依据
+
+「拟修」列写的是「补一条 <表象> 的判定说明」。实际执行时发现症状描述的是 <相邻机制>，而 §2 真正缺的是**判据本身**（<相邻机制> 只在特定前提后需要，判据该按 <权威判据>）。两者相邻但不同，已按判据写，相邻条目并入同节。
+
+### 需你决定
+
+- 「拟修」列文本与实际修法有偏差（见上），是否更新该列描述以免下次复发时对不上？
+- 控制器列出的「待人工定性」3 条（位置列路径已不存在）——其中 1 条指向的脚本性能问题已随某次重构解决，本轮修完后建议一并定性。要不要现在处理？
+```

package/templates/_agents/workflow-enums.txt

@@ -16,4 +16,11 @@ doc.status.terminal=done superseded cancelled
 doc.status.abandoned=superseded cancelled
 incident.status.all=open fixed closed
 incident.status.active=open
-level.all=L0 L1 L2 L3
+# 归因枚举（2026-10-13 自 Shipyard 回灌 incident-attribution）：归因检查（B6b 落地后编号以 check-loop.mjs 头部清单为准）校验 incident frontmatter 的「来源:」/「影响环境:」。
+#   source = 谁发现（self=AI 自查 / user=用户报出 / test=测试或实测暴露 / monitor=监控告警）
+#   env    = 缺陷触达的环境（none=未触达任何运行环境，如仅静态检查发现）
+# 锚前存量不回填；新 open 件必填（生效锚随 B6b 归因检查落地）。
+incident.source.all=self user test monitor
+incident.env.all=dev staging prod none
+# 级别三档（2026-10-13 L0 退役自源仓收敛系列 1 回灌）：L1 = 一份 plan 即入口（协作道）；L2/L3 = 防御道。
+level.all=L1 L2 L3