agentic-flow-kit 0.8.0 → 0.9.1

package/templates/_agents/scripts/policy.mjs

@@ -0,0 +1,46 @@
+// policy.mjs — check-loop 豁免锚的单源（policyVersion）
+// 新豁免改 POLICIES 并升版本，不在 check-loop 里再写散落日期。
+// kit.json 缺 policyVersion、或版本不在表内：回退版本 1（不启用版本 2 的 approved 锚）。
+// audit 不在本表：缺省视为全量检查（已装仓库与无 kit 的测试夹具）；init 新装显式写 false。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const POLICIES = {
+  1: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-23',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+  },
+  // 版本 2 = 版本 1 的五个日期 + 检查 17 的 approved 锚 + 检查 19 的 stageGateSince + check14Since 后移至确认门实际上线日（2026-09-23 → 2026-09-26）。
+  // 漏抄日期键会改动其他检查的生效日。
+  2: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-26',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+    check17UnclosedAfter: '0.8.0',
+    stageGateSince: '2026-09-29', // 检查 19 逐阶段审计的生效日（2026-09-30 stage-gate-machine）；锚 = 台账 ts 的 UTC 日期（复核 P2-3：本批 ts 2026-09-29T17:33Z 落在受审范围，顺序合规故静默）；v1 无此键 → 该检查整体跳过
+  },
+};
+
+export function loadKitPolicy(root) {
+  let raw = null;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.join(root, '.agents', 'kit.json'), 'utf8'));
+  } catch { /* 无 kit 或不可解析 */ }
+  const requested = raw && Number.isInteger(raw.policyVersion) ? raw.policyVersion : 1;
+  const policyVersion = Object.prototype.hasOwnProperty.call(POLICIES, requested) ? requested : 1;
+  return {
+    ...POLICIES[policyVersion],
+    policyVersion,
+    requestedVersion: requested,
+    audit: raw && typeof raw.audit === 'boolean' ? raw.audit : undefined,
+  };
+}
+
+export function auditEnabled(policy) {
+  return policy.audit !== false;
+}

package/templates/_agents/scripts/pre-push.test.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// pre-push.test.mjs — 加固门目标分支判定 fixture 套件（2026-10-01 v09-review-defects）
+// 真仓端到端：临时仓库挂载真实 pre-push，.agents/scripts/check-loop.sh 以桩脚本记录 argv。
+// 断言三态 refspec：
+//   main→main                  → argv 含 --hardening（加固门）
+//   experiment/x→main         → argv 含 --hardening（修复回归：直推漏口）
+//   experiment/y→experiment/y → argv 不含 --hardening（advisory）
+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 PRE_PUSH = path.join(SCRIPT_DIR, '..', '..', '_githooks', 'pre-push');
+
+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 git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+const run = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8' });
+
+const setup = () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'prepush-test-'));
+  const remote = path.join(root, 'remote.git');
+  fs.mkdirSync(path.join(root, '.githooks'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents', 'scripts'), { recursive: true });
+  // 挂载真实 pre-push（装户同款），stub 替换 check-loop 记录 argv
+  fs.copyFileSync(PRE_PUSH, path.join(root, '.githooks', 'pre-push'));
+  fs.writeFileSync(path.join(root, '.agents', 'scripts', 'check-loop.sh'), '#!/bin/sh\necho "$@" >> .stub-args\nexit 0\n');
+  fs.writeFileSync(path.join(root, 'a.txt'), 'a\n');
+  git(root, ['init', '-q']);
+  git(root, ['config', 'user.email', 't@t']);
+  git(root, ['config', 'user.name', 't']);
+  git(root, ['config', 'core.hooksPath', '.githooks']);
+  git(root, ['add', 'a.txt']);
+  git(root, ['commit', '-q', '-m', 'init']);
+  git(root, ['init', '-q', '--bare', remote]);
+  git(root, ['remote', 'add', 'origin', remote]);
+  return root;
+};
+const stubArgs = (root) => {
+  const p = path.join(root, '.stub-args');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split(/\n/).filter(Boolean) : [];
+};
+
+const root = setup();
+const w = (f, c) => fs.writeFileSync(path.join(root, f), c);
+
+// 1) main → main：应含 --hardening
+git(root, ['checkout', '-q', '-b', 'main']);
+let r = run(root, ['push', 'origin', 'HEAD:main']);
+check('main→main 推送成功', r.status === 0, `${r.stdout}${r.stderr}`);
+check('main→main argv 含 --hardening', (stubArgs(root)[0] || '').includes('--hardening'), stubArgs(root).join('|'));
+
+// 2) experiment/x → main（回归漏口）：本地分支在 experiment，目标 main → 必须含 --hardening
+git(root, ['checkout', '-q', '-b', 'experiment/x']);
+w('b.txt', 'b\n');
+git(root, ['add', 'b.txt']);
+git(root, ['commit', '-q', '-m', 'x']);
+r = run(root, ['push', 'origin', 'HEAD:main']);
+check('experiment/x→main 推送成功', r.status === 0, `${r.stdout}${r.stderr}`);
+check('experiment/x→main argv 含 --hardening（直推漏口修复）', (stubArgs(root)[1] || '').includes('--hardening'), stubArgs(root).join('|'));
+
+// 3) experiment/y → experiment/y：目标在探索泳道 → 不含 --hardening
+git(root, ['fetch', '-q', 'origin']);
+git(root, ['branch', 'experiment/y', 'origin/main']);
+git(root, ['checkout', '-q', 'experiment/y']);
+w('c.txt', 'c\n');
+git(root, ['add', 'c.txt']);
+git(root, ['commit', '-q', '-m', 'y']);
+r = run(root, ['push', 'origin', 'HEAD:experiment/y']);
+check('experiment→experiment 推送成功', r.status === 0, `${r.stdout}${r.stderr}`);
+const line3 = stubArgs(root)[2] || '';
+check('experiment→experiment argv 不含 --hardening', !line3.includes('--hardening'), stubArgs(root).join('|'));
+
+console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/solidify-task.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// solidify-task: 将 L1 液态草稿固化为正式 workflow 文档（迁移 + 可选确认 + 索引更新）
+// 用法：
+//   node .agents/scripts/solidify-task.mjs --topic <主题> [--root <仓库根>]
+//       # 只迁移 + 更新索引，绝不写确认台账；末尾打印确认指引
+//   node .agents/scripts/solidify-task.mjs --topic <主题> --delegated "<用户原话>"
+//       # 迁移后，以调用方显式传入的用户原话逐份 confirm-doc --delegated（quote 原样转发）
+//   node .agents/scripts/solidify-task.mjs --topic <主题> --auto
+//       # 迁移后，逐份 confirm-doc --auto（trust-mode=Trusted 才放行；Strict 下被拒并计数失败）
+// 确认门契约（incidents/2026-10-01-v09-review-defects）：--delegated 的 quote 必须来自用户在对话内的
+//   明确原话，由调用方显式传入——本脚本永不编造用户话术。无确认来源时只迁移不落账，末尾打印指引。
+import fs from 'node:fs';
+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));
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+function parseArgs() {
+  const topicIdx = process.argv.indexOf('--topic');
+  const topic = topicIdx !== -1 ? process.argv[topicIdx + 1] : '';
+  if (!topic) fail('用法: node .agents/scripts/solidify-task.mjs --topic "主题" [--root <仓库根>] [--delegated "<用户原话>" | --auto]');
+  let root = process.cwd();
+  const rootIdx = process.argv.indexOf('--root');
+  if (rootIdx !== -1 && process.argv[rootIdx + 1]) root = process.argv[rootIdx + 1];
+  const delegatedIdx = process.argv.indexOf('--delegated');
+  const delegated = delegatedIdx !== -1 ? String(process.argv[delegatedIdx + 1] ?? '') : '';
+  const auto = process.argv.includes('--auto');
+  if (delegated && auto) fail('--delegated 与 --auto 互斥，只能选其一');
+  return { topic, root, delegated, auto };
+}
+
+const classify = (content) => {
+  if (content.includes('# INTENT')) return 'intents';
+  if (content.includes('# PLAN')) return 'plans';
+  if (content.includes('# SPEC')) return 'specs';
+  if (content.includes('# INCIDENT')) return 'incidents';
+  return null;
+};
+
+function run() {
+  const { topic, root, delegated, auto } = parseArgs();
+  const draftsDir = path.join(root, '.zcode', 'drafts');
+  if (!fs.existsSync(draftsDir)) fail(`草稿目录 ${draftsDir} 不存在`);
+  const files = fs.readdirSync(draftsDir).filter((f) => f.includes(topic) && f.endsWith('.md'));
+  if (!files.length) fail(`在 ${draftsDir} 中未找到主题为 ${topic} 的草稿文件`);
+
+  const today = new Date().toISOString().slice(0, 10);
+  const solidified = [];
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(draftsDir, file), 'utf8');
+    const targetDir = classify(content);
+    if (!targetDir) continue;
+    // 统一强制 YYYY-MM-DD- 前缀；已有前缀的文件名原样保留
+    const finalName = /^\d{4}-\d{2}-\d{2}-/.test(file) ? file : `${today}-${file}`;
+    const targetPath = path.join(root, 'workflow', targetDir, finalName);
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.copyFileSync(path.join(draftsDir, file), targetPath);
+    solidified.push({ rel: `workflow/${targetDir}/${finalName}`, abs: targetPath, type: targetDir });
+    console.log(` 📦 迁移: ${file} -> ${targetDir}/${finalName}`);
+  }
+  if (!solidified.length) fail(`草稿中未找到可识别的 INTENT/PLAN/SPEC/INCIDENT 文档（主题 ${topic}）`);
+
+  // 确认：仅当调用方显式提供确认来源时执行；否则只迁移，绝不落账。
+  let failed = 0;
+  if (delegated || auto) {
+    console.log('🛡️ 执行逐份确认...');
+    for (const item of solidified) {
+      const args = [path.join(SCRIPT_DIR, 'confirm-doc.mjs'), item.rel, '--root', root];
+      if (delegated) args.push('--delegated', delegated);
+      else args.push('--auto');
+      const res = spawnSync('node', args, { cwd: root, encoding: 'utf8' });
+      if (res.status !== 0) {
+        failed++;
+        console.error(` ❌ 确认失败 [${item.rel}]: ${(res.stderr || '').trim()}`);
+      } else {
+        console.log(` ✅ 已确认: ${item.rel}`);
+      }
+    }
+    console.log(`确认汇总：${solidified.length - failed}/${solidified.length} 成功${failed ? `，${failed} 失败` : ''}`);
+  } else {
+    console.log('⏭️ 未提供确认来源，仅迁移不落账。');
+    for (const item of solidified) {
+      console.log(`  → 确认指引: node .agents/scripts/confirm-doc.mjs ${item.rel}（TTY 键入「可以」）`);
+      console.log(`    或（用户对话内明确确认后）: node .agents/scripts/confirm-doc.mjs ${item.rel} --delegated "<用户原话>"`);
+    }
+  }
+
+  // 更新索引；失败同样传播退出码。
+  console.log('📖 更新工作流索引...');
+  const idx = spawnSync('node', [path.join(SCRIPT_DIR, 'gen-workflow-index.mjs')], { cwd: root, stdio: 'inherit' });
+  if (idx.status !== 0) {
+    console.error(' ❌ 索引更新失败');
+    process.exit(1);
+  }
+
+  if (failed) process.exit(1);
+  console.log(`\n✨ 任务 ${topic} 已成功固化！`);
+  console.log(`👉 建议执行: git add workflow/ .agents/confirmations.jsonl && git commit -m "docs(workflow): solidify L1 task ${topic}"`);
+}
+
+run();

package/templates/_agents/scripts/solidify-task.test.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// solidify-task.test.mjs — 快车道固化脚本 fixture 套件（2026-10-01 v09-review-defects）
+// 验证确认门契约：无确认来源只迁移不落账；--delegated quote 原样转发；--auto Strict 下拒绝且失败退出；
+// 互斥/缺草稿/非文档等边界。gen-workflow-index 无 --root 参数，spawn 时以 fixture 根为 cwd。
+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 SCRIPT = path.join(SCRIPT_DIR, 'solidify-task.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 ENUMS_FIXTURE = [
+  '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') + '\n';
+
+const mkfix = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'solidify-test-'));
+  for (const s of ['intents', 'plans', 'specs', 'incidents']) {
+    fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  }
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.mkdirSync(path.join(d, '.zcode', 'drafts'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'), ENUMS_FIXTURE);
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-modules.txt'), '# modules\npipeline\nui\n');
+  return d;
+};
+const DRAFT = (name, eol = '\n') =>
+  `---${eol}状态: draft${eol}级别: L1${eol}日期: 2026-10-01${eol}模块: pipeline${eol}---${eol}# INTENT — ${name}${eol}`;
+const run = (root, args) => {
+  const r = spawnSync(process.execPath, [SCRIPT, ...args], { cwd: root, encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+const ledgerLines = (root) => {
+  const p = path.join(root, '.agents', 'confirmations.jsonl');
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split(/\n/).filter(Boolean) : [];
+};
+
+// T1：默认只迁移不落账
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  const r = run(d, ['--topic', 'demo', '--root', d]);
+  check('T1 默认迁移成功 exit 0', r.code === 0, r.out);
+  check('T1 草稿已迁移到 intents 且日期前缀正确',
+    fs.existsSync(path.join(d, 'workflow', 'intents', '2026-10-01-demo-task.md')), '');
+  check('T1 零台账新增（无确认来源绝不落账）', ledgerLines(d).length === 0, JSON.stringify(ledgerLines(d)));
+  check('T1 输出含确认指引', r.out.includes('确认指引') && r.out.includes('--delegated'), r.out);
+}
+// T2：--delegated 原话原样转发
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  const r = run(d, ['--topic', 'demo', '--root', d, '--delegated', '固化了可以']);
+  check('T2 --delegated 流程 exit 0', r.code === 0, r.out);
+  const lines = ledgerLines(d);
+  check('T2 台账落 1 行', lines.length === 1, JSON.stringify(lines));
+  check('T2 quote 原样（脚本不编造话术）',
+    lines[0].includes('"quote":"固化了可以"') && lines[0].includes('chat-delegated'), lines[0]);
+  check('T2 目标文档状态已 approved',
+    fs.readFileSync(path.join(d, 'workflow', 'intents', '2026-10-01-demo-task.md'), 'utf8').includes('状态: approved'), '');
+}
+// T3：--auto 在 Strict（缺 trust-mode.json）下被拒 → 失败计数并 exit 1
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  const r = run(d, ['--topic', 'demo', '--root', d, '--auto']);
+  check('T3 --auto 在缺省 Strict 下 exit 1（不吞失败）', r.code === 1, r.out);
+  check('T3 输出含失败汇总', r.out.includes('确认汇总') && r.out.includes('失败'), r.out);
+  check('T3 台账零行（拒绝不落账）', ledgerLines(d).length === 0, JSON.stringify(ledgerLines(d)));
+}
+// T4：缺草稿 → exit 1
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'other.md'), DRAFT('other'));
+  const r = run(d, ['--topic', 'nope', '--root', d]);
+  check('T4 缺主题草稿 exit 1 且带指引', r.code === 1 && r.out.includes('未找到主题'), r.out);
+}
+// T5：草稿非可识别文档 → exit 1
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-note.md'), '# 随手笔记\nnot a workflow doc\n');
+  const r = run(d, ['--topic', 'demo', '--root', d]);
+  check('T5 无可识别文档 exit 1', r.code === 1 && r.out.includes('未找到可识别'), r.out);
+}
+// T6：--delegated 与 --auto 互斥 → exit 1
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  const r = run(d, ['--topic', 'demo', '--root', d, '--delegated', 'x', '--auto']);
+  check('T6 互斥 exit 1', r.code === 1 && r.out.includes('互斥'), r.out);
+}
+// T7：失败路径退出码传播（确认失败后 exit 1，不吞）
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  // 让确认失败：用 --auto 触发 Strict 拒绝（缺 trust-mode.json 即 Strict）。
+  const r = run(d, ['--topic', 'demo', '--root', d, '--auto']);
+  check('T7 失败后 exit 1 且索引仍生成', r.code === 1 && fs.existsSync(path.join(d, 'workflow', 'INDEX.md')), r.out);
+}
+// T8：索引更新失败传播退出码（独立于确认失败路径——删除 workflow/plans 目录使 gen-workflow-index 失败）
+{
+  const d = mkfix();
+  fs.writeFileSync(path.join(d, '.zcode', 'drafts', 'demo-task.md'), DRAFT('demo'));
+  fs.rmSync(path.join(d, 'workflow', 'plans'), { recursive: true });
+  const r = run(d, ['--topic', 'demo', '--root', d]);
+  check('T8 索引更新失败 exit 1 且输出指明', r.code === 1 && r.out.includes('索引更新失败'), r.out);
+}
+
+console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/stage-gates.mjs

@@ -0,0 +1,256 @@
+// stage-gates.mjs — 逐阶段前置判定的单源（fill-spec / fill-plan / confirm-doc 共享；2026-09-30 stage-gate-machine）
+// 口径（与 check-loop 检查 19 内联实现互引——改一处须跟另一处）：
+//   入口「已确认」= 文件存在且 frontmatter 状态 ∈ {approved, done}，且【机器事实源】满足其一：
+//     ① confirmations.jsonl 台账存在该 doc 的 stage ∈ {approved, done} 行（经 confirm-doc 才产生，防手改状态冒充）；
+//     ② 存量口径：文档日期早于 policy.confirmDocsEffective，或行首含「流程: legacy」。
+//   incident 入口 = 文件存在 + 「时间线」小节内、行首列表条目含「用户确认」（原 maintain.md §3 约定；
+//     2026-09-30 复核 P2-1 收窄为小节内行首条目；第三轮复核 P1-1 起接受日期前缀形态，与模板样例一致）；
+//     状态 ∈ {open, fixed, closed}（spec/plan 须先于 fixed 起草，故 open 即为有效态）。
+//   入口「级别」须 ∈ L0-L3；缺失即拒（fail-closed）——**但库存量形态短路**（`流程: legacy` 或 日期早于
+//     确认门生效日）：跳过级别校验与 spec 档（2026-09-30 增量复核 N1——存量最可能缺级别，硬拒会锁死
+//     spec 起草与确认）。
+//   注意：**库存量信号本身即等于「入口已确认」**（judgeDoc：`台账行 || 存量口径`，与检查 15 / 检查 1 /
+//     配对门的既有口径一致——早于确认门生效日的自报日期即存量豁免，不要求另有台账行）；此处「短路」
+//     只额外豁免**级别前置与 spec 档**，不是对台账要求的二次豁免（P2-1：原注释把二者写反，已订正）。
+//   plan 门追加：入口级别（取入口 frontmatter 级别，不取工具 --level）为 L2/L3 时，同名 spec 须已确认（同口径）。
+//   探索泳道豁免（2026-09-30 hybrid-governance-explore-hardening）：同名 intent 仍为 draft 且风险泳道为
+//     L0/L1（级别优先；级别缺失或非法时回落 risk_level——fill-intent 双写同值）→「先起草后确认」是协作道
+//     语义（check-loop 检查 19 同款豁免口径），放行 spec/plan 起草与确认；L2/L3 防御道维持入口确认前置。
+//     incident 入口不豁免（过目留痕本就轻量）。收口由 check-loop --hardening 加固门兜底（入 main 前须
+//     intent approved/done + spec/plan 在场）。
+// 信任边界声明（沿 2026-09-28 audit-gate-hardening 口径）：本地可写台账 / 手改状态仍可伪造——本模块只把
+//   「顺手绕过」抬到「主动伪造」，不宣称通道关闭；事后对质靠 git 历史与台账。
+// 设计先例：fill-* 已 import 同目录 workflow-enums.mjs；check-loop 检查 19 内联同口径（门禁脚本自包含、防兄弟依赖）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadKitPolicy } from './policy.mjs';
+
+export const ENTRY_STATUSES = ['approved', 'done'];
+export const INCIDENT_STATUSES = ['open', 'fixed', 'closed'];
+
+// readFm：frontmatter 区（首 --- 至闭合 ---）取单字段值；无 frontmatter / 无该键 → ''
+export function readFm(abs, key) {
+  let text;
+  try { text = fs.readFileSync(abs, 'utf8'); } catch { return ''; }
+  const lines = text.replace(/\r\n/g, '\n').split('\n');
+  if (!/^---\s*$/.test(lines[0] || '')) return '';
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) break;
+    const m = lines[i].match(new RegExp(`^${key}:\\s*(.*)$`));
+    if (m) return m[1].trim();
+  }
+  return '';
+}
+
+function readBody(abs) {
+  try { return fs.readFileSync(abs, 'utf8'); } catch { return ''; }
+}
+
+// readLedger：confirmations.jsonl 追加式台账（坏行容忍跳过；与 check-loop 检查 15 同容错口径）
+export function readLedger(root) {
+  const p = path.join(root, '.agents', 'confirmations.jsonl');
+  let text = '';
+  try { text = fs.readFileSync(p, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* 坏行跳过 */ }
+  }
+  return out;
+}
+
+// judgeDoc：状态枚举 + 机器事实源判定（供入口 / spec 复用）
+// legacy：库存量信号（`流程: legacy` 标记 或 日期 < confirmDocsEffective）——所有调用方与门禁其余部分
+// 同口径（配对门 / 检查 1 / 检查 15 / 检查 19）；2026-09-30 复核 N1：存量入口须先短路，不得被
+// 「缺级别」fail-closed 硬拒（存量最可能缺级别，硬拒会锁死 spec 起草/确认，违反「存量零新增」契约）。
+function judgeDoc(root, abs, rel, statuses) {
+  const st = readFm(abs, '状态');
+  if (!statuses.includes(st)) {
+    return { ok: false, status: st, legacy: false, reason: `状态「${st || '缺失'}」不在 ${statuses.join(' / ')}` };
+  }
+  const policy = loadKitPolicy(root);
+  const body = readBody(abs);
+  const legacyByMarker = body.split(/\r?\n/).some((l) => /^流程: legacy/.test(l));
+  const d = readFm(abs, '日期') || readFm(abs, '发现');
+  const legacyByDate = /^\d{4}-\d{2}-\d{2}$/.test(d) && d < policy.confirmDocsEffective;
+  const legacy = legacyByMarker || legacyByDate;
+  const hasRow = readLedger(root).some((e) => e && e.doc === rel && (e.stage === 'approved' || e.stage === 'done'));
+  if (hasRow || legacy) return { ok: true, status: st, legacy };
+  return { ok: false, status: st, legacy: false, reason: `无确认台账行（门禁后的入口须经 confirm-doc，且台账无 ${rel} 的 approved / done 行）` };
+}
+
+// entryStorageLegacy：入口是否属「库存量」形态（`流程: legacy` 标记 或 日期早于确认门生效日）——
+// 与 judgeDoc 的存量信号同口径，供门在**级别校验**处短路（2026-09-30 增量复核 N1）。注意：本短路
+// **只豁免 level 前置**（存量多为门禁前建档、无级别字段），**不豁免台账要求**——`judgeDoc` 的
+// hasRow||legacy 仍照常判定（门禁后无台账行即拒，不因日期早于生效日而放行）。
+export function entryStorageLegacy(root, abs) {
+  const body = readBody(abs);
+  if (body.split(/\r?\n/).some((l) => /^流程: legacy/.test(l))) return true;
+  const d = readFm(abs, '日期') || readFm(abs, '发现');
+  return /^\d{4}-\d{2}-\d{2}$/.test(d) && d < loadKitPolicy(root).confirmDocsEffective;
+}
+
+// incidentMarked：「## 时间线」小节内、行首列表条目形态的「用户确认」（维持口径；正文叙述句不算——
+// 2026-09-30 复核 P2-1 实证：全仓唯一历史命中为叙述句，非过目留痕）。
+// 行首可选日期前缀（`- 2026-09-30 用户确认：…`）与可选加粗（`- **用户确认**：…`）均接受——
+// 与 _TEMPLATE.md 时间线样例形态保持一致（2026-09-30 第三轮复核 P1-1：样例若不可解析即误导）。
+export function incidentMarked(body) {
+  let inTimeline = false;
+  for (const l of String(body).replace(/\r\n/g, '\n').split('\n')) {
+    if (/^##\s/.test(l)) { inTimeline = /^##\s*时间线/.test(l); continue; }
+    if (inTimeline && MARK_RE.test(l)) return true;
+  }
+  return false;
+}
+
+// MARK_RE：行首列表条目 + 可选日期前缀（YYYY-MM-DD 或 <日期> 占位）+ 可选加粗围栏（词前 / 词后均可）
+// + 「用户确认」+ **须紧跟冒号或行尾**（词边界）。
+// 形态矩阵（2026-09-30 四/五轮复核收敛，8 正例 / 5 负例由 fill-spec.test S19/S20 钉死）：
+//   命中：`- 用户确认：…` / `- **用户确认**：…` / `- 2026-09-30 用户确认：…` / `- <日期> **用户确认**：…` / 行尾无冒号
+//   拒绝：`- 2026-09-30 用户确认了方案` / `- 用户确认书已归档` / `- 用户确认。` / `- 待用户确认：…`
+//   注：词前的 `\**` 与词后的 `\**` 必须都允许——只开一侧即产生结构性假阴性（第五轮复核 P1 实证：
+//   加粗围栏形态被拒，与 _TEMPLATE.md 自述契约冲突）。
+export const MARK_RE = /^\s*[-*]\s*(?:\d{4}-\d{2}-\d{2}|<日期>)?\s*\**用户确认\**(?=\s*[：:]|\s*$)/;
+
+// entryConfirmed：同主题入口判定（intent 优先；否则 incidents）——返回 {ok, kind, rel, level, status, reason?}
+export function entryConfirmed(root, base) {
+  const intentRel = `workflow/intents/${base}.md`;
+  const intentAbs = path.join(root, intentRel);
+  if (fs.existsSync(intentAbs)) {
+    const r = judgeDoc(root, intentAbs, intentRel, ENTRY_STATUSES);
+    return { ...r, kind: 'intent', rel: intentRel, level: readFm(intentAbs, '级别'), risk: readFm(intentAbs, 'risk_level'), storageLegacy: entryStorageLegacy(root, intentAbs) };
+  }
+  const incRel = `workflow/incidents/${base}.md`;
+  const incAbs = path.join(root, incRel);
+  if (fs.existsSync(incAbs)) {
+    const st = readFm(incAbs, '状态');
+    const level = readFm(incAbs, '级别');
+    if (INCIDENT_STATUSES.includes(st) && incidentMarked(readBody(incAbs))) {
+      return { ok: true, kind: 'incident', rel: incRel, level, status: st, legacy: false };
+    }
+    const why = !INCIDENT_STATUSES.includes(st) ? `状态「${st || '缺失'}」非法` : '「时间线」小节缺「用户确认」条目（maintain.md §3）';
+    return { ok: false, kind: 'incident', rel: incRel, level, status: st, legacy: false, reason: `同名 incident 未过目确认——${why}` };
+  }
+  return { ok: false, kind: null, rel: null, level: '', status: '', reason: `未找到同名入口（workflow/intents 与 workflow/incidents 均无 ${base}.md）` };
+}
+
+// specConfirmed：plan 门的 L2/L3 追加要求
+export function specConfirmed(root, base) {
+  const rel = `workflow/specs/${base}.md`;
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) return { ok: false, reason: `缺同名 spec（${rel}）` };
+  return judgeDoc(root, abs, rel, ENTRY_STATUSES);
+}
+
+// draftGateFor：起草门总判（kind = 'spec' | 'plan'，fill 工具与 confirm-doc 逐阶段门共用）
+export function draftGateFor(kind, root, base) {
+  const entry = entryConfirmed(root, base);
+  if (!entry.ok) {
+    // 探索泳道豁免（2026-09-30 hybrid-governance-explore-hardening，口径见头部注释）：L0/L1 draft intent
+    // 放行起草——「先动手后确认」；泳道取级别优先、缺失/非法回落 risk_level（与 fill-intent 双写兼容，
+    // 级别合法但为 L2/L3 时不回落——fail-closed 就严）。
+    const lane = /^L[0-3]$/.test(entry.level || '') ? entry.level : entry.risk;
+    if (entry.kind === 'intent' && entry.status === 'draft' && (lane === 'L0' || lane === 'L1')) {
+      return { ok: true, entry, laneBypass: true };
+    }
+    return {
+      ok: false,
+      reason: `同主题入口未确认——${entry.reason}`,
+      hint: '先走 plan.md 完成入口确认（修复类走 maintain.md，incident 草稿过目后在时间线留「用户确认」条目）',
+    };
+  }
+  // 库存量形态短路（2026-09-30 增量复核 N1）：**只额外豁免「级别前置」与「spec 档」**——
+  // 库存量入口（`流程: legacy` / 日期早于确认门生效日）多为门禁前建档、常缺「级别」字段，硬拒会锁死
+  // spec 起草与确认。注意：库存量信号**本身即等于入口已确认**（judgeDoc 的 `台账行 || 存量口径`，
+  // 与检查 1 / 15 / 配对门同口径）——台账豁免发生在 judgeDoc，不在本处；本处不做二次豁免
+  // （第三轮复核 P2-1：原句「台账要求不豁免」把两件事写反，已订正）。
+  if (!entry.storageLegacy && !/^L[0-3]$/.test(entry.level)) {
+    return {
+      ok: false,
+      reason: `入口缺合法「级别」字段（现「${entry.level || '缺失'}」，无法判定前置深度）`,
+      hint: '先给入口补「级别: L0-L3」字段，再继续',
+    };
+  }
+  if (kind === 'plan' && !entry.storageLegacy && (entry.level === 'L2' || entry.level === 'L3')) {
+    const sp = specConfirmed(root, base);
+    if (!sp.ok) {
+      return { ok: false, reason: `入口级别 ${entry.level}，前置 spec 未确认——${sp.reason}`, hint: '先走 design.md 完成 spec 确认' };
+    }
+  }
+  return { ok: true, entry };
+}
+
+// confirmGateFor：确认门总判（confirm-doc 用；docRel = workflow/specs/... 或 workflow/plans/...）
+export function confirmGateFor(root, docRel) {
+  const base = path.basename(docRel).replace(/\.md$/, '');
+  const kind = docRel.startsWith('workflow/specs/') ? 'spec' : 'plan';
+  return draftGateFor(kind, root, base);
+}
+
+// ---- done 前置门族（2026-09-30 confirm-gate-approved-history）----
+// 背景：stage-gate-machine 关单后检查 14 报「确认态缺失」×2——approved→done 期间从未提交、首次提交即
+// done 态（先 done 后提交），git 历史无 approved 中间态；检查 14 是事后审计（发现即定局），本族把
+// 校验收口到 confirm-doc 的「→done」跳转——「approved 态还在工作区」的最后一刻，即唯一可拦截窗口。
+// 命中判据单源：approvedTraceHit 命令行与 check-loop 检查 14 逐字一致（-G '^状态:[[:space:]]*approved'），
+// 本模块为唯一实现、两调用方共享（2026-09-30 复核 N3 教训：双份字面量靠注释同步必漂移）。
+// 注（2026-09-30 复核 P2-2 登记）：gitRun 的 GIT 解析 / maxBuffer / 失败语义与 check-loop.mjs 的
+// gitOut、gitReady 与检查 14 段级两条 rev-parse 为**同口径的两份实现**（未合并——检查 14 段结构不动
+// 属本单非目标）——任一侧调整（如加 --no-pager）须同步另一侧，防段级门与文档级判据分叉。
+const GIT = process.platform === 'win32' ? 'git.exe' : 'git';
+
+function gitRun(root, args) {
+  const r = spawnSync(GIT, args, { cwd: root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout || '';
+}
+
+// gitReady：git 环境可用（在仓库内且已有 HEAD）——与检查 14 段级两条 rev-parse 同口径
+export function gitReady(root) {
+  return gitRun(root, ['rev-parse', '--git-dir']) !== null
+    && gitRun(root, ['rev-parse', '-q', '--verify', 'HEAD']) !== null;
+}
+
+// approvedTraceHit：命中判定单源——git 历史是否出现过行首「状态: approved」（经提交进入历史才算，
+// 当前工作区未提交的 approved 不算——这正是「留痕」语义）。rel = 仓库根相对路径。
+// 返回：'' = 从未出现；<sha> = 命中；null = git 调用失败（调用方按各自容错口径处理——检查 14 不报、
+// done 门跳过，均沿 fail-open 边界；诚实边界声明见 spec）。
+export function approvedTraceHit(root, rel) {
+  const r = gitRun(root, ['log', '-1', '--format=%H', '-G', '^状态:[[:space:]]*approved', '--', rel]);
+  return r === null ? null : r.trim();
+}
+
+// doneGateFor：confirm-doc「→done」前置门（三件套 intent/spec/plan 均适用；incidents 的 fixed/closed 不在本门）。
+// 豁免与顺序：① 行首 `流程: legacy` ② 行含「存量确认态豁免（」声明（与检查 14 同标记，显式逃生口）
+// ③ 非 git 环境 ④ git 调用失败 → 均跳过（不误拦）。未豁免且未命中 → 拒绝（调用方负责非零退出 +
+// 零落账 + 零写盘 + 回退指引）。
+export function doneGateFor(root, abs, rel) {
+  const body = readBody(abs);
+  if (body.split(/\r?\n/).some((l) => /^流程: legacy/.test(l))) return { ok: true, skipped: 'legacy' };
+  if (body.split(/\r?\n/).some((l) => l.includes('存量确认态豁免（'))) return { ok: true, skipped: 'declared' };
+  if (!gitReady(root)) return { ok: true, skipped: 'no-git' };
+  const hit = approvedTraceHit(root, rel);
+  if (hit === null) return { ok: true, skipped: 'git-error' };
+  if (hit === '') {
+    return {
+      ok: false,
+      reason: 'git 历史中从未出现行首「状态: approved」——确认态未留痕（先 done 后提交 / 两跳同批提交）',
+      hint: '先把该文档的 approved 态提交（git add 该文件并 commit）后再重试关单',
+    };
+  }
+  return { ok: true, hit };
+}
+
+// resolveWorkspace：从输出路径推导工作区根与主题名；output 路径不含 workflow 段 → null（仓外草稿，不校验）
+export function resolveWorkspace(outputPath, rootOverride) {
+  const abs = path.resolve(outputPath);
+  const base = path.basename(abs).replace(/\.md$/, '');
+  if (rootOverride) return { root: path.resolve(rootOverride), base };
+  const parts = abs.split(path.sep);
+  for (let i = parts.length - 2; i >= 0; i--) {
+    if (parts[i].toLowerCase() === 'workflow') return { root: parts.slice(0, i).join(path.sep) || path.sep, base };
+  }
+  return null;
+}
+
+export default { entryConfirmed, specConfirmed, draftGateFor, confirmGateFor, doneGateFor, gitReady, approvedTraceHit, resolveWorkspace, readFm, readLedger };