agentic-flow-kit 1.7.0 → 1.7.16

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

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// compact-ledgers.test.mjs — 台账分片写入与 compact 归并 fixture 套件（2026-10-12 ledger-shard-write）
+// 覆盖：分片写入定位 + 跨来源链衔接 / compact 默认 dry-run 不动盘 / 幂等 / 前缀不变式（既有行保序）/
+//       读取失败中止 / 分片历史扫描与 compact 删除豁免 / 行未并入时仍拦丢行。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { compactLedgers } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'compact-ledgers.mjs')).href);
+const { appendLedger } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'confirm-doc.mjs')).href);
+const { ledgerChainHash } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'policy.mjs')).href);
+// 夹具闭包（2026-10-12 fixture-closure-rootfix）：整闭包自动跟随，不再手写依赖枚举（漏拷 = 假绿）
+const { copyScriptClosure } = await import(pathToFileURL(path.join(SCRIPT_DIR, 'fixture-scripts.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+};
+
+const DOC_A = 'workflow/intents/2026-10-01-a.md';
+const DOC_B = 'workflow/intents/2026-10-01-b.md';
+const baseEntry = (doc, stage = 'approved') => ({
+  ts: new Date().toISOString(), doc, stage, fingerprint: 'a'.repeat(64), source: 'tty',
+});
+// --shard 依赖 doc 链口径（policyVersion ≥ 8）：分片与主台账是不同文件，只有 doc 链跨来源接续。
+// 装 kit.json 的 policyVersion=8 来启用，与真实装户升级后的形态一致。
+const enableDocChain = (root) => {
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({ policyVersion: 8 }), 'utf8');
+};
+
+// ============ 场景 1：--shard 写入定位到分片，且跨来源链接得上 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-write-'));
+  enableDocChain(root);
+  // 先用主台账写一行（模拟该 doc 的历史行在主台账）
+  appendLedger(root, baseEntry(DOC_A));
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  check('S1 默认写主台账', fs.existsSync(mainPath));
+
+  // 再对同一 doc 用 --shard 写一行：前驱必须接主台账那行，而不是从 '' 重启
+  appendLedger(root, baseEntry(DOC_A, 'done'), { shard: true });
+  const shardPath = path.join(root, '.agents', 'confirmations.d', '2026-10-01-a.jsonl');
+  check('S1 --shard 写入分片文件（按 doc 基名命名）', fs.existsSync(shardPath));
+
+  const mainRows = fs.readFileSync(mainPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  const shardRows = fs.readFileSync(shardPath, 'utf8').trim().split('\n').map((l) => JSON.parse(l));
+  check('S1 分片行的 prevHash 接主台账同 doc 行（跨来源衔接，链不断）',
+    shardRows[0].prevHash === mainRows[0].hash, `${shardRows[0].prevHash} vs ${mainRows[0].hash}`);
+  // 行内重算仍一致（doc 链前提）
+  const { hash, prevHash, ...rest } = shardRows[0];
+  check('S1 分片行行内哈希可重算', ledgerChainHash(rest, prevHash) === hash);
+}
+
+// ============ 场景 2：compact 默认 dry-run 不动盘 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-dry-'));
+  appendLedger(root, baseEntry(DOC_A));
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const before = fs.readFileSync(mainPath, 'utf8');
+  const shardPath = path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl');
+
+  const r = compactLedgers(root); // 默认 execute:false
+  check('S2 dry-run 标记 skipped 且给出并入行数', r.ok && r.skipped && r.reason === 'dry-run' && r.added === 1, JSON.stringify(r));
+  check('S2 dry-run 主台账字节不变', fs.readFileSync(mainPath, 'utf8') === before);
+  check('S2 dry-run 分片仍在', fs.existsSync(shardPath));
+}
+
+// ============ 场景 3：--execute 归并 + 前缀不变式 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-exec-'));
+  appendLedger(root, baseEntry(DOC_A));
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const before = fs.readFileSync(mainPath, 'utf8');
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+
+  const r = compactLedgers(root, { execute: true });
+  const after = fs.readFileSync(mainPath, 'utf8');
+  check('S3 execute 归并成功并计入 1 行', r.ok && !r.skipped && r.added === 1, JSON.stringify(r));
+  check('S3 既有行严格保序在前（append-only 前缀不变式）', after.startsWith(before), JSON.stringify(after.slice(0, 40)));
+  check('S3 分片已清理', !fs.existsSync(path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl')));
+}
+
+// ============ 场景 4：幂等（重跑不重复追加）============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-idem-'));
+  enableDocChain(root);
+  appendLedger(root, baseEntry(DOC_A));
+  appendLedger(root, baseEntry(DOC_B), { shard: true });
+  compactLedgers(root, { execute: true });
+  const mainPath = path.join(root, '.agents', 'confirmations.jsonl');
+  const after1 = fs.readFileSync(mainPath, 'utf8');
+  const mergedLine = after1.trim().split('\n').pop(); // 归并时实际追加的那一行（含 prevHash/hash）
+
+  // 把**同一行原文**再放进分片重跑（模拟重复归并同批内容）——行文本逐字相同才会被去重
+  fs.mkdirSync(path.join(root, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'), mergedLine + '\n', 'utf8');
+  const r = compactLedgers(root, { execute: true });
+  const after2 = fs.readFileSync(mainPath, 'utf8');
+  check('S4 重复归并不重复追加（并集按整行去重）', r.ok && r.added === 0 && after1 === after2, `added=${r.added}`);
+}
+
+// ============ 场景 5：无分片 / 空分片 → 跳过且不报错 ============
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-none-'));
+  const r = compactLedgers(root);
+  check('S5 无分片目录 → 跳过且 ok', r.ok && r.skipped);
+}
+
+// ============ 场景 6：分片历史扫描 + compact 删除豁免（真 git）============
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'shard-hist-'));
+  const git = (...args) => spawnSync('git', args, { cwd: d, encoding: 'utf8' });
+  git('init', '-q', '.'); git('config', 'user.email', 't@t.io'); git('config', 'user.name', 't');
+  git('config', 'core.autocrlf', 'false');
+  fs.mkdirSync(path.join(d, '.agents', 'scripts'), { recursive: true });
+  copyScriptClosure(path.join(d, '.agents', 'scripts'), ['check-ledger-invariant.mjs']);
+  const mkDoc = (rel) => {
+    const p = path.join(d, ...rel.split('/'));
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, '---\n状态: approved\n---\n# doc\n', 'utf8');
+  };
+  const rowObj = (doc) => JSON.stringify({ ts: '2026-10-01T00:00:00Z', doc, stage: 'approved', fingerprint: 'a'.repeat(64), source: 'tty' });
+  const runGate = () => spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs'], { cwd: d, encoding: 'utf8' });
+
+  mkDoc(DOC_A); mkDoc(DOC_B);
+  // 基线：主台账一行 + 分片一行（分片持有 B 的行）
+  fs.mkdirSync(path.join(d, '.agents', 'confirmations.d'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowObj(DOC_A) + '\n', 'utf8');
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'), rowObj(DOC_B) + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'base with shard');
+  let r = runGate();
+  check('S6 分片入库且未删 → 历史扫描放行', r.status === 0, `exit=${r.status} ${r.stderr}`);
+
+  // compact 归并后删分片：删除豁免应认领
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), rowObj(DOC_A) + '\n' + rowObj(DOC_B) + '\n', 'utf8');
+  fs.rmSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-b.jsonl'));
+  git('add', '-A'); git('commit', '-qm', 'compact merged');
+  r = runGate();
+  check('S6 compact 归并删分片 → 删除豁免认领，exit 0', r.status === 0, `exit=${r.status} ${r.stderr}`);
+  check('S6 豁免记录点名 compact 归并形态', /compact 归并形态/.test(r.stderr), r.stderr.slice(0, 200));
+
+  // 未归并就删分片（丢行）→ 仍 hard 拦。用**从未进过主台账**的独立 doc C，
+  // 否则它的行已在主台账里（早先 compact 并过），删除豁免会正确地放行——那正是豁免该有的行为。
+  const DOC_C = 'workflow/intents/2026-10-01-c.md';
+  mkDoc(DOC_C);
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-c.jsonl'), rowObj(DOC_C) + '\n', 'utf8');
+  git('add', '-A'); git('commit', '-qm', 'add shard c');
+  fs.rmSync(path.join(d, '.agents', 'confirmations.d', '2026-10-01-c.jsonl'));
+  git('add', '-A'); git('commit', '-qm', 'drop shard c without merge');
+  r = runGate();
+  check('S6 未归并即删分片（丢行）→ exit 1 hard 拦', r.status === 1, `exit=${r.status}`);
+  check('S6 报文点名「分片删除丢行」', /分片删除丢行/.test(r.stderr), r.stderr.slice(0, 300));
+}
+
+console.log(`\n[compact-ledgers.test] PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/confirm-doc.mjs

@@ -25,6 +25,8 @@
 //       node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<用户对话原话>"（委托代录）
 //       node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<原话>" --batch（协作道批量：L0/L1 多份一次代录）
 //       node .agents/scripts/confirm-doc.mjs <doc...> --to superseded|cancelled（放弃态：取代/取消，留指纹与台账）
+//       node .agents/scripts/confirm-doc.mjs <doc...> --shard（分片写入：多 worktree 并行时各写各的
+//         .agents/confirmations.d/<doc>.jsonl，避免同文件并发覆盖；里程碑跑 compact-ledgers.mjs 归并）
 //   多文档一次传入：TTY 模式天然逐份过目键入；--delegated 默认一次仅一份（2026-09-27
 //   confirm-gate-one-per-call：多份并录曾系统性塌掉 build.md「逐件确认」三道门），L0/L1 协作道可
 //   `--batch` 多份一次代录（2026-09-30 hybrid-governance-risk-lanes）：逐份读「级别」，L2/L3 逐份拒绝
@@ -39,8 +41,9 @@ import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
-import { confirmGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeDigest } from './policy.mjs';
+import { readLedgerEntries } from './ledger-loader.mjs';
+import { confirmGateFor, clarifyGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
+import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, ledgerDocChainActive, ledgerDocChainPrev, scopeDigest } from './policy.mjs';
 
 // hasFreshVerify(root, doc)：读 <root>/.agents/verifications.jsonl 判 24h 窗口绿行（判定单源
 // policy.hasFreshVerifyLine）。只读，台账缺失/不可读一律 false（=无凭证，advisory 层 fail-open）。
@@ -148,22 +151,38 @@ export function applyTransition(text, targetStage, fingerprint16) {
 }
 
 // appendLedger(root, entry)：追加一行 JSON（目录不存在自动建；只 append 不重写）
-// 哈希链（2026-10-09 engine-quality-round2 D）：每行追加 prevHash（末行 hash，末行无 hash/空文件 → ''）
-//   与 hash（ledgerChainHash 单源计算，check-loop 15 同函数验链）——「就地改/删中间行」必留断链痕迹；
-//   历史行零回填（无 hash 行后链重启），整文件重写不可机器防（边界声明见 policy.ledgerChainHash）。
-export function appendLedger(root, entry) {
-  const p = path.join(root, '.agents', 'confirmations.jsonl');
+// 哈希链（2026-10-09 engine-quality-round2 D）：每行追加 prevHash 与 hash（ledgerChainHash 单源计算，
+//   check-loop 15 同函数验链）——「就地改/删中间行」必留断链痕迹；历史行零回填（无 hash 行后链重启），
+//   整文件重写不可机器防（边界声明见 policy.ledgerChainHash）。
+// 链域（2026-10-12 ledger-doc-chain）：policy.ledgerDocChainSince 存在且合法 → prevHash 取**同行 doc 的
+//   最后一个带 hash 行**（ledgerDocChainPrev），不再取物理末行。理由见 POLICIES v8 注释：物理链隐含
+//   「单写者顺序追加」前提，而并发 append / git 并集合并 / 分片归并三种**正常协作**都会打断它。
+//   缺键（v1-v7）→ 走旧物理链口径，存量零变化。
+// shard（2026-10-12 ledger-shard-write）：多 worktree 并行时两个进程同时 append 同一台账文件会互相覆盖
+//   （各自读到同一末行 → 同 prevHash → 后写者覆盖前写者）。--shard 把本行写入分片
+//   `.agents/confirmations.d/<doc基名>.jsonl`，各 worktree 各写各的、互不冲突；里程碑跑 compact-ledgers.mjs
+//   归并回主台账。**默认仍写主台账**——分片是有意的并发开关，不设则零影响。
+export function appendLedger(root, entry, { shard = false } = {}) {
+  const p = shard && entry.doc
+    ? path.join(root, '.agents', 'confirmations.d', `${path.basename(entry.doc, '.md')}.jsonl`)
+    : path.join(root, '.agents', 'confirmations.jsonl');
   fs.mkdirSync(path.dirname(p), { recursive: true });
   let prevHash = '';
   try {
-    if (fs.existsSync(p)) {
+    if (ledgerDocChainActive(loadKitPolicy(root))) {
+      // doc 链取前驱走**台账视图**（主台账 + 分片）而非单个文件：--shard 写入时，该 doc 的历史行
+      // 很可能在主台账里，只读分片文件会从 '' 重启 → 链断裂。视图取法天然跨来源衔接。
+      const rows = readLedgerEntries(root).map((e) => e.row);
+      prevHash = ledgerDocChainPrev(rows, entry.doc);
+    } else if (fs.existsSync(p)) {
+      // 旧物理链口径：取**本次写入目标文件**的末行 hash（v1-v7 存量行为，逐字不变）
       const lines = fs.readFileSync(p, 'utf8').split(/\r?\n/).filter((l) => l.trim());
       if (lines.length) {
         const last = JSON.parse(lines[lines.length - 1]);
         prevHash = last && typeof last.hash === 'string' ? last.hash : '';
       }
     }
-  } catch { /* 末行不可解析 → prevHash ''（链从本行重启；断裂由 check-loop 15 出账） */ }
+  } catch { /* 不可解析 → prevHash ''（链从本行重启；断裂由 check-loop 15 出账） */ }
   const { hash: _h, prevHash: _p, ...rest } = entry;
   const row = { ...rest, prevHash, hash: ledgerChainHash(rest, prevHash) };
   fs.appendFileSync(p, JSON.stringify(row) + '\n');
@@ -190,6 +209,7 @@ if (isMain) {
   let toTarget = null; // null = 默认前向跳转；superseded|cancelled = 放弃态显式目标
   let autoMode = false; // AI 自治模式（信任等级授权，2026-09-30 ai-autonomy-trust）
   let batchMode = false; // 协作道批量代录（--batch，2026-09-30 hybrid-governance-risk-lanes：仅 --delegated + L0/L1）
+  let shardWrite = false; // 分片写入（--shard，2026-10-12 ledger-shard-write）：多 worktree 并行时各写各的分片，避免互相覆盖
   const docs = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--root') root = path.resolve(argv[++i]);
@@ -197,12 +217,21 @@ if (isMain) {
     else if (argv[i] === '--to') toTarget = argv[++i] ?? '';
     else if (argv[i] === '--auto') autoMode = true;
     else if (argv[i] === '--batch') batchMode = true;
+    else if (argv[i] === '--shard') shardWrite = true;
     else docs.push(argv[i].replace(/\\/g, '/'));
   }
   if (toTarget !== null && !ABANDON_TARGETS.includes(toTarget)) {
     console.error(`用法：--to 仅接受 superseded|cancelled（现「${toTarget}」）——cancelled 自 draft/approved/open/fixed；superseded 自 approved/done/fixed/closed（未确认态只能 cancelled；终态间仅允许 done/closed→superseded）`);
     process.exit(1);
   }
+  // --shard 与 doc 链口径绑定（2026-10-12 ledger-shard-write）：分片与主台账分属不同文件，
+//   只有 doc 链能跨来源接续；旧物理链口径下分片行的 prevHash 会与主台账末行失配 → 提交即断链。
+//   故缺锚时**参数期直接拒**（友好报错），而不是让用户写完台账再被门禁拦。
+if (shardWrite && !ledgerDocChainActive(loadKitPolicy(root))) {
+    console.error('❌ --shard 需要台账 doc 链口径（policy.ledgerDocChainSince），当前 policyVersion 无此键。\n   原因：分片与主台账是不同文件，只有 doc 链能跨来源接续；旧物理链口径下分片行会与主台账断链。\n   修法：在 .agents/kit.json 设 policyVersion: 8（或更高的支持版本）后重试。');
+    process.exit(1);
+  }
+
   const delegated = delegatedQuote !== null;
   if (delegated && autoMode) {
     console.error('❌ --auto 与 --delegated 互斥：自治模式是用户预先授权的机器放行，委托代录是单次对话确认');
@@ -358,6 +387,19 @@ if (isMain) {
         refused++;
         continue;
       }
+      // 待澄清项门（2026-10-12 needs-clarification）：起草期挂「待澄清」标记**不阻断**（零阻塞），
+      // 但 draft→approved 确认时若仍挂着未澄清项则拒绝——确认即「认可这份文档」，文档里还写着
+      // 「这里我不知道」，确认就没有意义。与上面的前置门分开出账：拒绝原因必须指向真正的原因
+      // （合并会让作者去查「前置」，而前置其实是好的）。
+      // ⚠️ 文案锚点硬约束：本段禁止并入上方 gate 分支的输出契约（既有 confirm-doc.test.mjs 断言
+      // 锚定「未过逐阶段前置门（stage-gates）」子串），故单列独立分支。
+      const cl = clarifyGateFor(abs);
+      if (!cl.ok) {
+        console.error(`❌ ${doc} 含未澄清项（needs-clarification）：${cl.reason}`);
+        console.error(`   ${cl.hint}（本份未落账、未写盘）`);
+        refused++;
+        continue;
+      }
     }
     // done 前置门（2026-09-30 confirm-gate-approved-history）：→done 须 git 历史已留 approved 态
     // （先 done 后提交 / 两跳同批提交 → 拒绝；防「确认态缺失」缺陷复发；判据单源见 stage-gates.doneGateFor）。
@@ -407,7 +449,7 @@ if (isMain) {
       }
       fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
       appendLedger(root, {
-        ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
+        shard: shardWrite, ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
         source: `ai-auto-trust-L${trustConfig.level}`, quote: `AI 自治放行 (Trust Level ${trustConfig.level})`,
         batch, seq, of: docs.length, scope,
       });
@@ -428,7 +470,7 @@ if (isMain) {
       }
       fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
       appendLedger(root, {
-        ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
+        shard: shardWrite, ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
         source: 'chat-delegated', quote: String(delegatedQuote),
         // 调用事实（batch-ledger-audit）：seq=本次调用内件序（从 1），of=本次调用总份数
         batch, seq, of: docs.length,
@@ -458,7 +500,7 @@ if (isMain) {
     }
     fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
     appendLedger(root, {
-      ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
+        shard: shardWrite, ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
       source: 'tty',
       batch, seq, of: docs.length, // 调用事实（形态无关：TTY 多文档天然逐件过目，of>1 不构成违规）
     });

package/templates/_agents/scripts/confirm-doc.test.mjs

@@ -386,6 +386,65 @@ const readLedgerOf = (root) => {
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S19b【待澄清门】spec 挂未澄清项 → 拒绝落账（2026-10-12 needs-clarification）----
+// 夹具沿 S23 的正路入口（台账行 + approved），确保**前置门已过**——否则拒绝原因会指向前置而非待澄清，
+// 用例就测不出新门。断言拒绝文案点名「needs-clarification」且**不含**前置门文案（两门分开出账）。
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl1-'));
+  for (const sub of ['intents', 'specs']) fs.mkdirSync(path.join(root, 'workflow', sub), { recursive: true });
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  const fp = 'c'.repeat(64);
+  fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-10-12-n.md'), `---\n状态: approved\n级别: L2\n日期: 2026-10-12\n确认指纹: ${fp.slice(0, 16)}\n---\n# I\n`);
+  fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: '2026-10-12T02:00:00.000Z', doc: 'workflow/intents/2026-10-12-n.md', stage: 'approved', fingerprint: fp, prev: 'draft', source: 'chat-delegated', batch: 'n1', seq: 1, of: 1 }) + '\n');
+  const specP = path.join(root, 'workflow', 'specs', '2026-10-12-n.md');
+  fs.writeFileSync(specP, '---\n状态: draft\n级别: L2\n---\n# S\n\n## 功能行为\n- 待澄清：错误率的判据是 5xx 占比还是全量？\n');
+  const before = fs.readFileSync(specP, 'utf8');
+  const r = spawnSync(process.execPath, [CLI, 'workflow/specs/2026-10-12-n.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+  const after = fs.readFileSync(specP, 'utf8');
+  const led = readLedgerOf(root);
+  check('S19b 待澄清门：挂未澄清项 → exit 2 + 点名行号与内容 + 未落盘 + 零新增台账',
+    r.status === 2 && /needs-clarification/.test(r.stderr) && /第8行/.test(r.stderr) && /5xx 占比还是全量/.test(r.stderr)
+      && after === before && led.length === 1,
+    JSON.stringify({ status: r.status, stderr: r.stderr, ledger: led.length }));
+  check('S19b 待澄清门：拒绝原因不误指向前置门（两门分开出账，否则作者查错地方）',
+    !/逐阶段前置门/.test(r.stderr), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S19c【待澄清门】解决后（行首改「已澄清」）→ 放行；纯删行亦可 ----
+{
+  const mkClarified = (body) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl2-'));
+    for (const sub of ['intents', 'specs']) fs.mkdirSync(path.join(root, 'workflow', sub), { recursive: true });
+    fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+    const fp = 'd'.repeat(64);
+    fs.writeFileSync(path.join(root, 'workflow', 'intents', '2026-10-12-o.md'), `---\n状态: approved\n级别: L2\n日期: 2026-10-12\n确认指纹: ${fp.slice(0, 16)}\n---\n# I\n`);
+    fs.writeFileSync(path.join(root, '.agents', 'confirmations.jsonl'), JSON.stringify({ ts: '2026-10-12T02:00:00.000Z', doc: 'workflow/intents/2026-10-12-o.md', stage: 'approved', fingerprint: fp, prev: 'draft', source: 'chat-delegated', batch: 'o1', seq: 1, of: 1 }) + '\n');
+    fs.writeFileSync(path.join(root, 'workflow', 'specs', '2026-10-12-o.md'), body);
+    return root;
+  };
+  for (const [name, body] of [
+    ['改前缀为「已澄清」（保留行、留痕曾不清楚）', '---\n状态: draft\n级别: L2\n---\n# S\n\n- 已澄清：错误率判据 = 5xx 占比（与用户 10-12 对齐）\n'],
+    ['直接删行', '---\n状态: draft\n级别: L2\n---\n# S\n\n## 功能行为\n- 错误率判据 = 5xx 占比\n'],
+  ]) {
+    const root = mkClarified(body);
+    const r = spawnSync(process.execPath, [CLI, 'workflow/specs/2026-10-12-o.md', '--delegated', '可以'], { cwd: root, encoding: 'utf8' });
+    const after = fs.readFileSync(path.join(root, 'workflow', 'specs', '2026-10-12-o.md'), 'utf8');
+    check(`S19c 待澄清门：${name} → 放行落态`, r.status === 0 && after.includes('状态: approved'),
+      JSON.stringify({ status: r.status, stderr: r.stderr }));
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  // intents 不受本门约束（歧义标记的落点是 spec/plan 的设计判据；intent 是需求单，澄清天然发生在此处）
+  const root3 = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl3-'));
+  fs.mkdirSync(path.join(root3, 'workflow', 'intents'), { recursive: true });
+  fs.writeFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), '---\n状态: draft\n级别: L1\n---\n# I\n\n- 待澄清：范围含不含移动端？\n');
+  const r3 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
+  check('S19c 待澄清门：intent 不受本门约束（澄清天然发生在需求单处）',
+    r3.status === 0 && fs.readFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), 'utf8').includes('状态: approved'),
+    JSON.stringify({ status: r3.status, stderr: r3.stderr }));
+  fs.rmSync(root3, { recursive: true, force: true });
+}
+
 // ---- S20【逐阶段门】入口存在但未确认（draft）→ 拒绝 ----
 {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-sg2-'));