agentic-flow-kit 0.3.1 → 0.5.0

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

@@ -0,0 +1,131 @@
+// flow-kit source-sync-check：装户面同步一致性检查（包源 templates/_agents/ vs 装副本 .agents/）
+// 目的：包源改了 templates/_agents/ 但 .agents/ 装副本没刷新——这种"真空地带"sync.mjs 不扫、doctor.mjs §6.6 不扫
+//       本工具扫 templates/_agents/ 下所有 .md / .mjs / .json / .txt（排除 cache/）vs .agents/ 对应路径
+//       输出三类差异：缺失（包源有装副本无）/ 孤儿（包源无装副本有）/ 漂移（两者都有 sha 不一致）
+//       排除装副本独有文件：kit.json / settings.json / hooks/commit-check.config.json（init 渲染产物，不属双源）
+// 用法：node .agents/scripts/source-sync-check.mjs --diff
+//       node .agents/scripts/source-sync-check.mjs --json
+//       node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>
+// 零依赖；B-b 决策「只报告不修复」
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const VALID_EXTS = new Set(['.md', '.mjs', '.json', '.txt']);
+// 装副本独有文件（init 渲染产物，不属双源结构）
+const RENDER_OUTPUT_FILES = new Set(['kit.json', 'settings.json', 'hooks/commit-check.config.json']);
+const TARGET_EXCLUDE = RENDER_OUTPUT_FILES;  // 向后兼容别名
+
+function sha256(p) {
+  try {
+    return createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+// walkMd：递归扫目录，列出所有 validExt 文件（排除 cache/）
+function walkMd(root) {
+  const out = [];
+  function walk(dir, relBase) {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const rel = relBase ? relBase + '/' + e.name : e.name;
+      const abs = path.join(dir, e.name);
+      // 排除 cache/ 目录（与 sync.mjs 既有约定一致）
+      if (rel === 'cache' || rel.startsWith('cache/')) continue;
+      if (e.isDirectory()) walk(abs, rel);
+      else if (VALID_EXTS.has(path.extname(e.name))) out.push(rel);
+    }
+  }
+  walk(root, '');
+  return out;
+}
+
+export function sourceSyncCheck({ pkgRoot, target }) {
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adapterRoot = path.join(target, '.agents');
+  const pkgFiles = walkMd(authorityRoot);
+  const tgtFiles = walkMd(adapterRoot).filter((f) => !TARGET_EXCLUDE.has(f));
+  const pkgSet = new Set(pkgFiles);
+  const tgtSet = new Set(tgtFiles);
+  const missing = []; // 包源有 / 装副本无
+  const orphan = [];  // 包源无 / 装副本有
+  const drift = [];   // 两者都有但 sha 不一致
+  for (const f of pkgFiles) {
+    if (!tgtSet.has(f)) { missing.push({ rel: f }); continue; }
+    const pkgSha = sha256(path.join(authorityRoot, f));
+    const tgtSha = sha256(path.join(adapterRoot, f));
+    if (pkgSha !== null && tgtSha !== null && pkgSha !== tgtSha) {
+      drift.push({ rel: f, pkgSha, tgtSha });
+    }
+  }
+  for (const f of tgtFiles) {
+    if (!pkgSet.has(f)) orphan.push({ rel: f });
+  }
+  return {
+    pkgRoot, target,
+    pkgCount: pkgFiles.length,
+    tgtCount: tgtFiles.length,
+    missing: missing.sort((a, b) => a.rel.localeCompare(b.rel)),
+    orphan: orphan.sort((a, b) => a.rel.localeCompare(b.rel)),
+    drift: drift.sort((a, b) => a.rel.localeCompare(b.rel)),
+  };
+}
+
+function printDiff(result) {
+  console.log('▶ flow-kit source-sync-check --diff');
+  console.log('  包源 (templates/_agents/) ' + result.pkgCount + ' 份  |  装副本 (.agents/) ' + result.tgtCount + ' 份');
+  if (!result.missing.length && !result.orphan.length && !result.drift.length) {
+    console.log('  无差异 ✅');
+    return;
+  }
+  if (result.missing.length) {
+    console.log('  缺失（包源有 / 装副本无）' + result.missing.length + '：');
+    for (const m of result.missing) console.log('    - ' + m.rel);
+  }
+  if (result.orphan.length) {
+    console.log('  孤儿（包源无 / 装副本有）' + result.orphan.length + '：');
+    for (const o of result.orphan) console.log('    - ' + o.rel);
+  }
+  if (result.drift.length) {
+    console.log('  漂移（包源装副本都有但 sha 不一致）' + result.drift.length + '：');
+    for (const d of result.drift) console.log('    - ' + d.rel + '  pkg=' + d.pkgSha.slice(0, 8) + '…  tgt=' + d.tgtSha.slice(0, 8) + '…');
+  }
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('source-sync-check.mjs');
+if (isMain) {
+  let jsonMode = false, diffMode = false;
+  let pkgRoot = null, target = null;
+  for (let i = 0; i < process.argv.length - 2; i++) {
+    const a = process.argv[2 + i];
+    if (a === '--json') jsonMode = true;
+    else if (a === '--diff') diffMode = true;
+    else if (a === '--pkg-root') pkgRoot = process.argv[2 + i + 1];
+    else if (a === '--target') target = process.argv[2 + i + 1];
+  }
+  if (!pkgRoot) pkgRoot = process.cwd();
+  if (!target) target = process.cwd();
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adapterRoot = path.join(target, '.agents');
+  if (!fs.existsSync(authorityRoot)) fail('找不到包源：' + authorityRoot);
+  if (!fs.existsSync(adapterRoot)) fail('找不到装副本：' + adapterRoot);
+  const result = sourceSyncCheck({ pkgRoot, target });
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({
+      pkgCount: result.pkgCount,
+      tgtCount: result.tgtCount,
+      missing: result.missing.map((m) => m.rel),
+      orphan: result.orphan.map((o) => o.rel),
+      drift: result.drift.map((d) => ({ rel: d.rel, pkgSha: d.pkgSha.slice(0, 8), tgtSha: d.tgtSha.slice(0, 8) })),
+    }, null, 2) + '\n');
+  } else {
+    printDiff(result);
+  }
+  // diff/json 模式总 exit 0；差异存在不视作错误（人类阅读用；B-b 决策「只报告不修复」）
+  process.exit(0);
+}
+export default sourceSyncCheck;

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