agentic-flow-kit 0.4.0 → 0.5.0

package/templates/_agents/scripts/source-sync-check.test.mjs

@@ -0,0 +1,156 @@
+// source-sync-check.test.mjs — 装户面同步一致性检查工具测试（2026-09-25 source-sync-check）
+// 方法：fixture mini 包源（templates/_agents/） + 装副本（.agents/），调 sourceSyncCheck() 拿三类差异
+//       + 实际仓库扫描做 baseline
+// 判据：①fixture 三类齐全  ②cache/ 排除  ③kit.json/settings.json 排除  ④sha 一致  ⑤baseline ≥ 100  ⑥JSON 可解析
+// 用法：node .agents/scripts/source-sync-check.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { sourceSyncCheck } from './source-sync-check.mjs';
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log('PASS ' + name); }
+  else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
+}
+
+const SRC_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+
+// ---- fixture：mini 包源 + 装副本，3 类差异各造 1 个 ----
+function mkFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents');
+  const tgtBase = path.join(target, '.agents');
+  fs.mkdirSync(path.join(pkgBase, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(pkgBase, 'scripts'), { recursive: true });
+  fs.mkdirSync(path.join(pkgBase, 'cache'), { recursive: true }); // 应排除
+  fs.mkdirSync(path.join(tgtBase, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(tgtBase, 'scripts'), { recursive: true });
+  fs.mkdirSync(path.join(tgtBase, 'hooks'), { recursive: true }); // 孤儿
+  fs.mkdirSync(path.join(tgtBase, 'cache'), { recursive: true }); // 装副本 cache 也应排除
+  // 一致文件（cmdA.md）：包源 + 装副本 同内容
+  fs.writeFileSync(path.join(pkgBase, 'commands', 'cmdA.md'), '# cmdA v1\n');
+  fs.writeFileSync(path.join(tgtBase, 'commands', 'cmdA.md'), '# cmdA v1\n');
+  // 缺失（cmdB.md）：包源有 / 装副本无
+  fs.writeFileSync(path.join(pkgBase, 'commands', 'cmdB.md'), '# cmdB v1\n');
+  // 孤儿（orphan-real.json）：装副本 hooks/ 有 / 包源无（普通孤儿，应被报告）
+  fs.writeFileSync(path.join(tgtBase, 'hooks', 'orphan-real.json'), '{}\n');
+  // 白名单孤儿（commit-check.config.json）：装副本 hooks/ 有 / 包源无，但 init 渲染产物不应报孤儿
+  fs.writeFileSync(path.join(tgtBase, 'hooks', 'commit-check.config.json'), '{}\n');
+  // 装副本独有（应排除）：kit.json / settings.json
+  fs.writeFileSync(path.join(tgtBase, 'kit.json'), '{}\n');
+  fs.writeFileSync(path.join(tgtBase, 'settings.json'), '{}\n');
+  // 漂移（scriptX.mjs）：包源 v1 / 装副本 v2
+  fs.writeFileSync(path.join(pkgBase, 'scripts', 'scriptX.mjs'), 'export const X = 1;\n');
+  fs.writeFileSync(path.join(tgtBase, 'scripts', 'scriptX.mjs'), 'export const X = 2;\n');
+  // cache/ 排除：包源 + 装副本 都有，但不应被计入
+  fs.writeFileSync(path.join(pkgBase, 'cache', 'foo.md'), 'cache-pkg\n');
+  fs.writeFileSync(path.join(tgtBase, 'cache', 'foo.md'), 'cache-tgt\n');
+  return { pkgRoot, target };
+}
+
+// ---- 场景 1：fixture 三类差异齐全（缺失 1 / 孤儿 1 / 漂移 1）----
+{
+  const { pkgRoot, target } = mkFixture();
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S1 fixture 缺失 1（cmdB.md）', r.missing.length === 1 && r.missing[0].rel === 'commands/cmdB.md', JSON.stringify(r.missing));
+  check('S1 fixture 孤儿 1（orphan-real.json）', r.orphan.length === 1 && r.orphan[0].rel === 'hooks/orphan-real.json', JSON.stringify(r.orphan));
+  check('S1 fixture 漂移 1（scriptX.mjs）', r.drift.length === 1 && r.drift[0].rel === 'scripts/scriptX.mjs', JSON.stringify(r.drift));
+  check('S1 fixture 白名单项（commit-check.config.json）不在孤儿', !r.orphan.some((o) => o.rel === 'hooks/commit-check.config.json'));
+}
+
+// ---- 场景 2：cache/ 目录排除 ----
+{
+  const { pkgRoot, target } = mkFixture();
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S2 cache/ 排除（缺失/孤儿/漂移不含 cache/foo.md）',
+    !r.missing.some((m) => m.rel.includes('cache/')) &&
+    !r.orphan.some((o) => o.rel.includes('cache/')) &&
+    !r.drift.some((d) => d.rel.includes('cache/')));
+}
+
+// ---- 场景 3：装副本独有（kit.json / settings.json）排除 ----
+{
+  const { pkgRoot, target } = mkFixture();
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S3 装副本独有（kit.json / settings.json）排除',
+    !r.orphan.some((o) => o.rel === 'kit.json' || o.rel === 'settings.json'));
+}
+
+// ---- 场景 4：sha 一致文件不出现在漂移列表 ----
+{
+  const { pkgRoot, target } = mkFixture();
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S4 一致文件 cmdA.md 不在漂移', !r.drift.some((d) => d.rel === 'commands/cmdA.md'));
+}
+
+// ---- 场景 5：实际仓库扫描 baseline（包源 ≥ 30 份 / 装副本 ≥ 30 份）----
+{
+  const pkgRoot = SRC_ROOT;
+  const target = SRC_ROOT;
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S5 实际仓库 包源 ≥ 30 份', r.pkgCount >= 30, '实际 ' + r.pkgCount);
+  check('S5 实际仓库 装副本 ≥ 30 份', r.tgtCount >= 30, '实际 ' + r.tgtCount);
+  // 装副本 kit.json / settings.json 不应在孤儿
+  check('S5 实际仓库 装副本独有（kit.json / settings.json）排除',
+    !r.orphan.some((o) => o.rel === 'kit.json' || o.rel === 'settings.json'));
+}
+
+// ---- 场景 6：--json 输出可解析（CLI 子流程）----
+{
+  const { pkgRoot, target } = mkFixture();
+  // 直接调 sourceSyncCheck + 序列化模拟 --json 输出
+  const r = sourceSyncCheck({ pkgRoot, target });
+  const jsonOut = JSON.stringify({
+    pkgCount: r.pkgCount, tgtCount: r.tgtCount,
+    missing: r.missing.map((m) => m.rel),
+    orphan: r.orphan.map((o) => o.rel),
+    drift: r.drift.map((d) => ({ rel: d.rel, pkgSha: d.pkgSha.slice(0, 8), tgtSha: d.tgtSha.slice(0, 8) })),
+  }, null, 2);
+  let parsed = null;
+  try { parsed = JSON.parse(jsonOut); } catch {}
+  check('S6 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.missing));
+}
+
+// ---- 场景 8：白名单 RHO 文件过滤（hooks/commit-check.config.json + kit.json + settings.json 都不报孤儿）----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-rho-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents');
+  const tgtBase = path.join(target, '.agents');
+  fs.mkdirSync(pkgBase, { recursive: true });
+  fs.mkdirSync(path.join(tgtBase, 'hooks'), { recursive: true });
+  fs.mkdirSync(tgtBase, { recursive: true });
+  // 3 个白名单项都装副本独有
+  fs.writeFileSync(path.join(tgtBase, 'hooks', 'commit-check.config.json'), '{}\n');
+  fs.writeFileSync(path.join(tgtBase, 'kit.json'), '{}\n');
+  fs.writeFileSync(path.join(tgtBase, 'settings.json'), '{}\n');
+  // 1 个非白名单孤儿作对照（应被报告）
+  fs.writeFileSync(path.join(tgtBase, 'hooks', 'real-orphan.json'), '{}\n');
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S8 白名单 3 项（commit-check.config.json / kit.json / settings.json）不报孤儿',
+    !r.orphan.some((o) => o.rel === 'hooks/commit-check.config.json' || o.rel === 'kit.json' || o.rel === 'settings.json'));
+  check('S8 非白名单孤儿（real-orphan.json）仍报孤儿',
+    r.orphan.length === 1 && r.orphan[0].rel === 'hooks/real-orphan.json', JSON.stringify(r.orphan));
+}
+
+// ---- 场景 9：实际仓库 hooks/commit-check.config.json 不在孤儿 ----
+{
+  const r = sourceSyncCheck({ pkgRoot: SRC_ROOT, target: SRC_ROOT });
+  check('S9 实际仓库 hooks/commit-check.config.json 不在孤儿',
+    !r.orphan.some((o) => o.rel === 'hooks/commit-check.config.json'), JSON.stringify(r.orphan));
+}
+
+// ---- 场景 7：空目录 / 不存在的目录不崩 ----
+{
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-empty-'));
+  const r = sourceSyncCheck({ pkgRoot: empty, target: empty });
+  check('S7 空目录 fixture 不崩（0/0）', r.pkgCount === 0 && r.tgtCount === 0);
+}
+
+console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
+process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/verify.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-// verify.mjs — 关单固定编排（2026-09-24 intent closeout-verify-script）
-// 用途：关单前一键过门——按写死顺序执行 npm test → check-loop.sh，逐项输出 pass/fail。
+// verify.mjs — 关单固定编排（2026-09-24 intent closeout-verify-script；2026-09-26 check-loop-node 第 2 步直连 node）
+// 用途：关单前一键过门——按写死顺序执行 npm test → check-loop，逐项输出 pass/fail。
 // 语义：只编排不裁决——两条命令都是既有门禁原样跑，本脚本不新增校验、不读配置、无状态；
-//   任一步非零即 fail-fast 退出 1，失败原因经 stdio inherit 原样透传不吞；
-//   缺 sh 环境 fail-closed 明确报错（关单门不可跳过，不像 run-tests 那样跳过并提示）。
+//   任一步非零即 fail-fast 退出 1，失败原因经 stdio inherit 原样透传不吞。
+//   check-loop 为 node 实现（经 check-loop.mjs 直跑——node 即本脚本运行时必然可用，
+//   旧「缺 sh 环境 fail-closed」分支随 sh 依赖消失退役）。
 // 测试：node templates/_agents/scripts/verify.test.mjs（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具，不触真实 npm test 与 workflow）
 // 用法：node .agents/scripts/verify.mjs [--test-cmd "<shell 命令>"]（--test-cmd 仅供测试注入）
 import { spawnSync } from 'node:child_process';
@@ -13,7 +14,7 @@ import { fileURLToPath } from 'node:url';
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const args = process.argv.slice(2);
 const testCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : 'npm test';
-const checkLoop = path.join(SCRIPT_DIR, 'check-loop.sh');
+const checkLoop = path.join(SCRIPT_DIR, 'check-loop.mjs');
 
 console.log(`[verify] ▶ 1/2 ${testCmd}`);
 const t = spawnSync(testCmd, { shell: true, stdio: 'inherit' });
@@ -24,12 +25,9 @@ if (t.status !== 0) {
 console.log('[verify] ✅ 1/2 测试通过');
 
 console.log('[verify] ▶ 2/2 check-loop');
-const c = spawnSync('sh', [checkLoop], { stdio: 'inherit' });
+const c = spawnSync(process.execPath, [checkLoop], { stdio: 'inherit' });
 if (c.status !== 0) {
-  const hint = c.error?.code === 'ENOENT'
-    ? '环境无 sh（装 Git Bash / WSL）——关单门不可跳过，不静默放行'
-    : '按上方输出修复后原路重跑';
-  console.error(`[verify] ❌ 2/2 check-loop 未通过（exit ${c.status ?? c.error?.code}）——${hint}`);
+  console.error(`[verify] ❌ 2/2 check-loop 未通过（exit ${c.status ?? c.error?.code}）——按上方输出修复后原路重跑`);
   process.exit(1);
 }
 console.log('[verify] ✅ 2/2 闭环校验通过');

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

@@ -19,10 +19,22 @@ const check = (desc, cond, detail = '') => {
   else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
 };
 
-// 空闭环夹具（四目录齐全、无文档 → check-loop 无断档）
+// 空闭环夹具（四目录齐全、无文档 → check-loop 无断档；枚举单源随 fixture 内联——check-loop 启动段 fail-loud 要求）
 const mkfix = () => {
   const d = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-fix-'));
   for (const s of ['intents', 'specs', 'plans', 'incidents']) fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'), [
+    'doc.status.all=draft approved done superseded cancelled',
+    'doc.status.confirmed=approved done superseded cancelled',
+    'doc.status.active=draft approved',
+    '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',
+    '',
+  ].join('\n'), 'utf8');
   return d;
 };
 // 配对断裂夹具（L1 intent 无同名 plan → hard-block）

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

@@ -0,0 +1,158 @@
+// wf-journal — 编排执行 run journal（2026-09-26 orchestration-journal-human，审查改进方向 4）
+// 用途：宿主 AI 按 .agents/workflows/_TEMPLATE.md 纪律，每个 stage 每次尝试出结果（pass/fail/blocked）
+//       记一行 JSONL；中止后重跑先看 status——已 pass 不重跑，从就绪层续（断点续跑与重试计量）。
+// 存储：.agents/cache/orchestration-runs.jsonl（本地运行态缓存，已 gitignore，可丢弃——丢失仅失去
+//       续跑记忆，不影响任何门禁；status 对空 journal 天然全量输出不误报）。
+// 行 schema：{ ts, run, wf, stage, form?, status, attempt, note? }
+//   run = <wf>@<YYYYMMDD-HHMM>；同 run 同 stage 多行按末次状态生效（重试后过 = pass），attempt 取最大。
+// 语义口径（与 _TEMPLATE.md 四形态一致；stages 表解析复用 workflows-check.mjs 的 parseStages 单源）。
+// 用法：
+//   node .agents/scripts/wf-journal.mjs add --wf <编排名> --stage <id> --status <pass|fail|blocked>
+//        [--form role|step|gate|human] [--attempt N] [--note <文本>] [--run <runId>] [--new-run]
+//        [--journal <文件>]（默认 .agents/cache/orchestration-runs.jsonl，按 cwd）
+//   node .agents/scripts/wf-journal.mjs status --wf <编排名> [--run <runId>] [--journal <文件>] [--wf-root <目录>]
+// 测试：node templates/_agents/scripts/wf-journal.test.mjs（fixture + 真实仓库场景）
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseStages } from './workflows-check.mjs';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const DEFAULT_JOURNAL = () => path.join(process.cwd(), '.agents', 'cache', 'orchestration-runs.jsonl');
+const DEFAULT_WF_ROOT = () => path.join(process.cwd(), '.agents', 'workflows');
+const STATUSES = ['pass', 'fail', 'blocked'];
+const FORMS = ['role', 'step', 'gate', 'human'];
+
+// 读 journal 原始行（文件不存在/空 → []；目录不存在自动可建由 add 处理）
+export function readJournalLines(journalFile) {
+  try {
+    return fs.readFileSync(journalFile, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+  } catch {
+    return [];
+  }
+}
+
+// replayRun：重放一个 run 的记录 → { state: {stage: {status, attempt, form, note, ts}}, total, bad }
+//   末次状态生效；attempt 取出现过的最大值；坏行跳过（计数返回，调用方决定告警口径）
+export function replayRun(rawLines, run) {
+  const state = {};
+  let total = 0;
+  let bad = 0;
+  for (const line of rawLines) {
+    let j;
+    try { j = JSON.parse(line); } catch { bad++; continue; }
+    if (!j || typeof j !== 'object' || j.run !== run) continue;
+    if (!j.stage || !STATUSES.includes(j.status)) { bad++; continue; }
+    total++;
+    const prev = state[j.stage];
+    state[j.stage] = {
+      status: j.status,
+      attempt: Math.max(prev?.attempt ?? 0, Number(j.attempt) || 1),
+      ...(j.form ? { form: j.form } : {}),
+      ...(j.note ? { note: j.note } : {}),
+      ts: j.ts,
+    };
+  }
+  return { state, total, bad };
+}
+
+// latestRun：journal 中该 wf 最后一条的 run id（无记录 → null）
+export function latestRun(rawLines, wf) {
+  let run = null;
+  for (const line of rawLines) {
+    try {
+      const j = JSON.parse(line);
+      if (j && j.wf === wf && j.run) run = j.run;
+    } catch { /* 坏行不参与 run 推断 */ }
+  }
+  return run;
+}
+
+// planStages：stages（parseStages 产物）× 状态 → { passed, ready, pending, blocked }
+//   passed  = 末次 pass；ready = 依赖全 pass 且自身未 pass（末次 fail 标注重试就绪）；blocked = 自身末次 blocked；pending = 其余
+export function planStages(stages, state) {
+  const passed = [];
+  const ready = [];
+  const pending = [];
+  const blocked = [];
+  const passedSet = new Set(stages.filter((s) => state[s.id]?.status === 'pass').map((s) => s.id));
+  for (const s of stages) {
+    const st = state[s.id];
+    if (st?.status === 'pass') { passed.push({ id: s.id }); continue; }
+    if (st?.status === 'blocked') { blocked.push({ id: s.id, note: st.note || '' }); continue; }
+    const deps = s.after ? s.after.split(/[,，、\s]+/).filter(Boolean) : [];
+    if (deps.every((d) => passedSet.has(d))) {
+      ready.push({ id: s.id, ...(st?.status === 'fail' ? { retry: st.attempt } : {}) });
+    } else {
+      pending.push({ id: s.id, ...(deps.some((d) => state[d] && state[d].status !== 'pass') && (state[deps.find((d) => state[d] && state[d].status !== 'pass')]?.status === 'blocked') ? { depBlocked: true } : {}) });
+    }
+  }
+  return { passed, ready, pending, blocked };
+}
+
+const pad = (n) => String(n).padStart(2, '0');
+const runIdOf = (wf, d = new Date()) =>
+  `${wf}@${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}`;
+
+function parseArgs(argv) {
+  const out = { cmd: argv[0] };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) out[a.slice(2)] = argv[++i] ?? true;
+    else fail(`未知参数：${a}（用法见文件头注释）`);
+  }
+  return out;
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('wf-journal.mjs');
+if (isMain) {
+  const a = parseArgs(process.argv.slice(2));
+  const journalFile = a.journal || DEFAULT_JOURNAL();
+  if (a.cmd === 'add') {
+    if (!a.wf || !a.stage || !a.status) fail('add 必填：--wf / --stage / --status（pass|fail|blocked）');
+    if (!STATUSES.includes(a.status)) fail(`--status 须为 ${STATUSES.join('|')}（现 ${a.status}）`);
+    if (a.form && !FORMS.includes(a.form)) fail(`--form 须为 ${FORMS.join('|')}（现 ${a.form}）`);
+    const lines = readJournalLines(journalFile);
+    const run = a.run || (a['new-run'] ? runIdOf(a.wf) : latestRun(lines, a.wf) || runIdOf(a.wf));
+    const attempt = a.attempt
+      ? Number(a.attempt)
+      : lines.filter((l) => { try { const j = JSON.parse(l); return j.run === run && j.stage === a.stage; } catch { return false; } }).length + 1;
+    const row = {
+      ts: new Date().toISOString(), run, wf: a.wf, stage: a.stage,
+      status: a.status, attempt,
+      ...(a.form ? { form: a.form } : {}), ...(a.note ? { note: a.note } : {}),
+    };
+    fs.mkdirSync(path.dirname(journalFile), { recursive: true });
+    fs.appendFileSync(journalFile, JSON.stringify(row) + '\n');
+    console.log(`✅ journal += ${a.wf}/${a.stage} ${a.status}（attempt ${attempt}，run ${run}）`);
+    process.exit(0);
+  }
+  if (a.cmd === 'status') {
+    if (!a.wf) fail('status 必填：--wf（编排名）');
+    const wfRoot = a['wf-root'] || DEFAULT_WF_ROOT();
+    const wfFile = path.join(wfRoot, `${a.wf}.md`);
+    if (!fs.existsSync(wfFile)) fail(`找不到编排脚本：${wfFile}`);
+    const stages = parseStages(fs.readFileSync(wfFile, 'utf8'));
+    if (!stages) fail(`编排脚本缺 stages 表：${wfFile}`);
+    const lines = readJournalLines(journalFile);
+    const run = a.run || latestRun(lines, a.wf);
+    console.log(`▶ wf-journal status — ${a.wf}${run ? ` @ ${run}` : '（无 journal 记录，按首轮输出）'}`);
+    if (!run) {
+      const { ready, pending } = planStages(stages, {});
+      console.log(`  ▶ 就绪（第 0 层，${ready.length}）：${ready.map((s) => s.id).join('、') || '无'}`);
+      console.log(`  ⏸ 待定（${pending.length}）：${pending.map((s) => s.id).join('、') || '无'}`);
+      process.exit(0);
+    }
+    const { state, total, bad } = replayRun(lines, run);
+    if (bad) console.error(`⚠️ journal 坏行 ${bad} 条已跳过（缓存可丢弃，不影响门禁）`);
+    const plan = planStages(stages, state);
+    console.log(`  （${total} 条记录）`);
+    console.log(`  ✅ 已完成（${plan.passed.length}）：${plan.passed.map((s) => s.id).join('、') || '无'}`);
+    console.log(`  ▶ 就绪（${plan.ready.length}）：${plan.ready.map((s) => (s.retry ? `${s.id}（重试就绪×${s.retry}）` : s.id)).join('、') || '无'}`);
+    console.log(`  ⏸ 待定（${plan.pending.length}）：${plan.pending.map((s) => s.id + (s.depBlocked ? '（依赖中止）' : '')).join('、') || '无'}`);
+    console.log(`  ⛔ 中止（${plan.blocked.length}）：${plan.blocked.map((s) => `${s.id}${s.note ? `（${s.note}）` : ''}`).join('、') || '无'}`);
+    process.exit(0);
+  }
+  fail(`未知命令：${a.cmd ?? ''}（add | status，用法见文件头注释）`);
+}
+export default { replayRun, planStages, latestRun, readJournalLines };

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

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// wf-journal.test.mjs — run journal 测试（2026-09-26 orchestration-journal-human）
+// 方法：纯函数（replayRun/planStages/latestRun）fixture 直测 + CLI add/status spawn 冒烟（临时 journal + 临时 workflows 目录）
+//       + 真实仓库 pipeline-closing 解析（human 形态行在位）。
+// 判据：① schema 各字段与 attempt/run 语义 ② 末次生效 ③ 就绪/待定/中止分层 ④ 坏行容忍 ⑤ 9 列/human 列两代表全解析
+// 用法：node templates/_agents/scripts/wf-journal.test.mjs（npm test 随跑）
+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 { replayRun, planStages, latestRun } from './wf-journal.mjs';
+import { parseStages } from './workflows-check.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 SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const JOURNAL_CLI = path.join(SCRIPT_DIR, 'wf-journal.mjs');
+
+const mkline = (over = {}) => JSON.stringify({ ts: '2026-09-26T10:00:00Z', run: 'w@20260926-1000', wf: 'w', stage: 'a', status: 'pass', attempt: 1, ...over });
+const STAGES = parseStages(`| id | after | role | step | task | files | accept | gate | human | retries |
+|----|-------|------|------|------|-------|--------|------|-------|---------|
+| a | — | implementer | — | 做 A | src/** | 过 | | | |
+| ask | a | — | — | 用户确认 | — | 一句可以 | | 用户确认 | |
+| b | ask | — | — | — | — | — | npm test | | |
+| c | b | — | — | — | — | — | npm run build | | |
+`) || [];
+
+// ---- S1 replayRun：字段进 state、total 计数 ----
+{
+  const r = replayRun([mkline(), mkline({ stage: 'ask', form: 'human', status: 'pass', note: '用户点头' })], 'w@20260926-1000');
+  check('S1 replayRun 记 2 条且 form/note 进 state',
+    r.total === 2 && r.state.a.status === 'pass' && r.state.ask.form === 'human' && r.state.ask.note === '用户点头',
+    JSON.stringify(r));
+}
+
+// ---- S2 末次生效 + attempt 取最大（fail→pass 重试）----
+{
+  const r = replayRun([
+    mkline({ stage: 'b', status: 'fail', attempt: 1 }),
+    mkline({ stage: 'b', status: 'fail', attempt: 2 }),
+    mkline({ stage: 'b', status: 'pass', attempt: 3 }),
+  ], 'w@20260926-1000');
+  check('S2 末次状态生效 pass 且 attempt=3',
+    r.state.b.status === 'pass' && r.state.b.attempt === 3,
+    JSON.stringify(r.state.b));
+}
+
+// ---- S3 其他 run / 坏行不混入 ----
+{
+  const r = replayRun([
+    mkline({ stage: 'a' }),
+    mkline({ stage: 'x', run: 'w@OTHER' }),
+    '{ broken json',
+    mkline({ stage: 'a', status: 'nope' }),
+  ], 'w@20260926-1000');
+  check('S3 异 run 过滤 + 坏 JSON/坏 status 计 bad 不进 state',
+    r.total === 1 && r.bad === 2 && !r.state.x,
+    JSON.stringify(r));
+}
+
+// ---- S4 latestRun：取该 wf 最后一条 run ----
+{
+  const run = latestRun([mkline({ run: 'w@A' }), mkline({ run: 'w@B', stage: 'a' })], 'w');
+  check('S4 latestRun 取末条 w@B', run === 'w@B', String(run));
+}
+
+// ---- S5 planStages：空状态 → 第 0 层就绪；pass 后下层就绪；fail 下层待定 ----
+{
+  const p0 = planStages(STAGES, {});
+  const p1 = planStages(STAGES, { a: { status: 'pass', attempt: 1 } });
+  const p2 = planStages(STAGES, { a: { status: 'pass', attempt: 1 }, ask: { status: 'fail', attempt: 1 } });
+  check('S5 分层：首层 a 就绪 → a 过后 ask 就绪 → ask fail 时 b/c 待定且 ask 重试就绪',
+    p0.ready.map((s) => s.id).join() === 'a'
+      && p1.ready.map((s) => s.id).join() === 'ask'
+      && p2.ready.some((s) => s.id === 'ask' && s.retry === 1)
+      && p2.pending.map((s) => s.id).join() === 'b,c',
+    JSON.stringify({ p0, p1, p2 }));
+}
+
+// ---- S6 planStages：blocked 标注中止 + 依赖中止提示 ----
+{
+  const p = planStages(STAGES, { a: { status: 'pass', attempt: 1 }, ask: { status: 'blocked', attempt: 1, note: '用户驳回' } });
+  check('S6 blocked 进中止列且下游标依赖中止',
+    p.blocked.length === 1 && p.blocked[0].id === 'ask' && p.blocked[0].note === '用户驳回'
+      && p.pending.some((s) => s.id === 'b' && s.depBlocked),
+    JSON.stringify(p));
+}
+
+// ---- S7 CLI add 冒烟：attempt 自动计次 + run 复用 ----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'wfj-cli-'));
+  const j = path.join(tmp, 'j.jsonl');
+  const run = (args) => spawnSync(process.execPath, [JOURNAL_CLI, ...args], { encoding: 'utf8' });
+  const r1 = run(['add', '--wf', 'w', '--stage', 'a', '--status', 'pass', '--journal', j]);
+  const r2 = run(['add', '--wf', 'w', '--stage', 'a', '--status', 'fail', '--journal', j]);
+  const lines = fs.readFileSync(j, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  check('S7 add×2 attempt 自动 1→2 且 run 复用同 id',
+    r1.status === 0 && r2.status === 0 && lines.length === 2
+      && lines[0].attempt === 1 && lines[1].attempt === 2 && lines[0].run === lines[1].run,
+    JSON.stringify({ r1: r1.stdout + r1.stderr, r2: r2.stdout + r2.stderr, lines }));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+// ---- S8 CLI status 冒烟：临时 workflows 目录 + 坏行容忍 ----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'wfj-st-'));
+  const wfRoot = path.join(tmp, 'workflows');
+  fs.mkdirSync(wfRoot, { recursive: true });
+  fs.writeFileSync(path.join(wfRoot, 'demo.md'),
+    '---\nname: demo\ndescription: d\n---\n\n' +
+    '| id | after | role | step | task | files | accept | gate | retries |\n' +
+    '|----|-------|------|------|------|-------|--------|------|---------|\n' +
+    '| a | — | — | — | — | — | — | npm test | |\n' +
+    '| b | a | — | — | — | — | — | npm run build | |\n');
+  const j = path.join(tmp, 'j.jsonl');
+  fs.writeFileSync(j, '{ broken\n' + mkline({ wf: 'demo', stage: 'a' }) + '\n');
+  const r = spawnSync(process.execPath, [JOURNAL_CLI, 'status', '--wf', 'demo', '--journal', j, '--wf-root', wfRoot], { encoding: 'utf8' });
+  check('S8 status：坏行告警不炸、a 已完成、b 就绪',
+    r.status === 0 && /坏行 1 条/.test(r.stderr) && /已完成（1）：a/.test(r.stdout) && /就绪（1）：b/.test(r.stdout),
+    JSON.stringify({ out: r.stdout, err: r.stderr }));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+// ---- S9 真实仓库：pipeline-closing 解析含 human 形态 confirm 行；无 journal 时首层就绪 ----
+{
+  const ROOT = path.resolve(SCRIPT_DIR, '..', '..', '..');
+  const wfFile = path.join(ROOT, '.agents', 'workflows', 'pipeline-closing.md');
+  if (!fs.existsSync(wfFile)) {
+    console.log('SKIP  S9（非包源仓库，无 pipeline-closing）');
+  } else {
+    const stages = parseStages(fs.readFileSync(wfFile, 'utf8')) || [];
+    const confirm = stages.find((s) => s.id === 'confirm');
+    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
+        && r.status === 0 && /就绪（第 0 层.*author/.test(r.stdout),
+      JSON.stringify({ confirm, out: r.stdout }));
+    fs.rmSync(j, { force: true });
+  }
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFile } from 'node:child_process';
+import { ENUMS } from './workflow-enums.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 const WORKFLOW = path.join(ROOT, 'workflow');
@@ -51,17 +52,17 @@ function parseAcceptance(text) {
 }
 
 // ---- 配对断裂检测：按 slug 聚合同族（同名 intent/incident/plan/spec），异常卡附 alerts ----
-// 规则（口径对齐 check-loop.sh 的硬断档 + 状态枚举，看板为预警层、不阻断）：
+// 规则（口径对齐 check-loop.sh 的硬断档 + 状态枚举，看板为预警层、不阻断；枚举读单源 workflow-enums.txt）：
 //   孤儿 spec / 孤儿 plan（无同名 intent·incident 入口）；入口 done 但 plan 未终态（看板启发式）；
 //   入口缺 plan（intent 一律要求；incident 需非 legacy 且级别 L1/L2/L3）；L2/L3 入口缺同名 spec；
 //   spec L3 确认三件缺失（确认结果 / 确认时间 / 正文独立复核行）；
-//   状态不在枚举内或缺失（intent·spec·plan: approved/done/superseded/cancelled；incident: open/fixed/closed）
-const PLAN_TERMINAL = ['done', 'superseded', 'cancelled'];
+//   状态不在枚举内或缺失（doc=confirmed 集；incident=all 集）
+const PLAN_TERMINAL = ENUMS['doc.status.terminal'];
 const STATUS_ENUM = {
-  intents: ['approved', 'done', 'superseded', 'cancelled'],
-  specs: ['approved', 'done', 'superseded', 'cancelled'],
-  plans: ['approved', 'done', 'superseded', 'cancelled'],
-  incidents: ['open', 'fixed', 'closed'],
+  intents: ENUMS['doc.status.confirmed'],
+  specs: ENUMS['doc.status.confirmed'],
+  plans: ENUMS['doc.status.confirmed'],
+  incidents: ENUMS['incident.status.all'],
 };
 const NO_STATUS = '（未填）';
 const L3_REVIEW = /^- 独立复核：[ \t]*[^<\s]/m; // 正文独立复核行须有实质内容（对照 check-loop 锚定）
@@ -94,7 +95,7 @@ function detectAlerts(cards) {
       alerts.push('入口缺 plan：无同名 plan');
     if (isEntry && !legacyIncident && ['L2', 'L3'].includes(c.level) && !types.has('specs'))
       alerts.push(`${c.level} 入口缺同名 spec`);
-    if (c.type === 'specs' && c.level === 'L3' && !['superseded', 'cancelled'].includes(c.status)) {
+    if (c.type === 'specs' && c.level === 'L3' && !ENUMS['doc.status.abandoned'].includes(c.status)) {
       if (c.confirm !== 'approved') alerts.push(`L3 确认缺失：确认结果须为 approved（现 ${c.confirm || '缺失'}）`);
       if (!c.confirmTime) alerts.push('L3 确认缺失：须记录确认时间');
       if (!c.hasReview) alerts.push('L3 复核缺失：须记录新会话独立复核结论');

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

@@ -0,0 +1,68 @@
+// workflow-enums 读取器——.agents/workflow-enums.txt 单源（2026-09-25 enum-single-source）
+// 消费方：workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs / fill-{intent,plan,spec}.mjs
+//   （check-loop.sh 为 POSIX sh，自行 sed 读取同文件，口径同本读取器的键）。
+// fail-loud 无 fallback：kit 自带该文件，缺失/坏数据属安装破损——直接抛错崩得可见，
+//   doctor §2 布局门同时把关文件存在性。禁止在任何消费方内再抄一份枚举字面量。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ENUMS_FILE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'workflow-enums.txt');
+
+// parseEnums(text)：`key=a b` 行 → { key: ['a','b'] }；非法行/重复键/重复值抛错（单源纪律）
+export function parseEnums(text) {
+  const out = {};
+  for (const line of String(text).split(/\r?\n/)) {
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(/^([a-z][a-z0-9.]*)=(\S.*)$/);
+    if (!m) throw new Error('workflow-enums 行格式非法（须 key=value value）: ' + line);
+    if (m[1] in out) throw new Error('workflow-enums 键重复: ' + m[1]);
+    const vals = m[2].trim().split(/\s+/);
+    if (new Set(vals).size !== vals.length) throw new Error('workflow-enums 值重复: ' + line);
+    out[m[1]] = vals;
+  }
+  return out;
+}
+
+const NEED_KEYS = [
+  'doc.status.all', 'doc.status.confirmed', 'doc.status.active', 'doc.status.terminal', 'doc.status.abandoned',
+  'incident.status.all', 'incident.status.active', 'level.all',
+];
+
+// validateEnums(enums)：跨键不变量（子集关系 + 活跃/终态互斥 + 关键态在位）——坏数据尽早抛错
+export function validateEnums(e) {
+  for (const k of NEED_KEYS) {
+    if (!Array.isArray(e[k]) || !e[k].length) throw new Error('workflow-enums 缺键或空值: ' + k);
+  }
+  const sub = (a, b) => {
+    for (const v of e[a]) if (!e[b].includes(v)) throw new Error(`workflow-enums 不变量破: ${a} 含 ${b} 外的值 ${v}`);
+  };
+  sub('doc.status.confirmed', 'doc.status.all');
+  sub('doc.status.active', 'doc.status.all');
+  sub('doc.status.terminal', 'doc.status.all');
+  sub('doc.status.abandoned', 'doc.status.all');
+  sub('doc.status.abandoned', 'doc.status.terminal');
+  sub('incident.status.active', 'incident.status.all');
+  if (e['doc.status.active'].some((v) => e['doc.status.terminal'].includes(v))) {
+    throw new Error('workflow-enums 不变量破: doc.status.active 与 doc.status.terminal 重叠');
+  }
+  if (!e['doc.status.confirmed'].includes('approved') || !e['doc.status.terminal'].includes('done')) {
+    throw new Error('workflow-enums 不变量破: approved 须在 confirmed、done 须在 terminal（确认/关单语义锚点）');
+  }
+  return e;
+}
+
+// loadEnums(file = 单源标准位置)：读文件 → parse → validate；缺文件抛错（fail-loud）
+export function loadEnums(file = ENUMS_FILE) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error('workflow-enums 单源文件不可读（kit 自带，跑 flow-kit sync 恢复）: ' + file + ' — ' + err.message);
+  }
+  return validateEnums(parseEnums(text));
+}
+
+// 模块级常量：import 即加载即校验（标准位置）
+export const ENUMS = loadEnums();
+export default ENUMS;