agentic-flow-kit 1.7.15 → 1.8.0

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

@@ -13,8 +13,10 @@
 //     落态记账——免 TTY、免逐份问答，但台账行如实记 source:"chat-delegated" + quote:<原话>，
 //     永不伪装 TTY 行。调用纪律（AI 须先取得用户对话内明确确认）由 AGENTS.md 确认门条款承载，
 //     quote 原话入账供事后对质。
-// 台账：.agents/confirmations.jsonl（入 git、追加式）——每行 {ts, doc, stage, fingerprint(64位), prev,
-//   source:"tty"|"chat-delegated", quote?(仅委托行), batch, seq, of}。
+// 台账：默认分片 .agents/confirmations.d/<doc基名>.jsonl（2026-10-13 ledger-shard-default，
+//   协议对齐 Shipyard 参考实现；--no-shard / CONFIRM_SHARDED=0 回退主台账 .agents/confirmations.jsonl）
+//   ——两者入 git、追加式。每行 {ts, doc, stage, fingerprint(64位), prev, source:"tty"|"chat-delegated",
+//   quote?(仅委托行), batch, seq, of}。
 //   batch/seq/of（2026-09-28 batch-ledger-audit 新增，纯增字段、向后兼容、历史行不回填）：
 //   记「本次进程调用落了几份态」这一**写入时确定已知的事实**——batch 为本次调用生成的短随机串
 //   （无时间语义、无全局唯一要求，仅需单台账内不碰撞），seq 为该次调用内件序（从 1），of 为本次
@@ -23,10 +25,12 @@
 // 指纹：内容 CRLF 归一 → 剔除「确认指纹:」行（防自引用）→ sha256；frontmatter 存前 16 位，台账存全量。
 // 用法：node .agents/scripts/confirm-doc.mjs <workflow/intents|x.md> [<doc2>...] [--root <仓库根>]
 //       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...> --delegated "<原话>" --batch（协作道批量：L1 多份一次代录）
 //       node .agents/scripts/confirm-doc.mjs <doc...> --to superseded|cancelled（放弃态：取代/取消，留指纹与台账）
+//       node .agents/scripts/confirm-doc.mjs <doc...> --no-shard（回退主台账 .agents/confirmations.jsonl：
+//         分片已是默认写入口径，环境变量 CONFIRM_SHARDED=0 同效；里程碑可选跑 compact-ledgers.mjs 归并分片）
 //   多文档一次传入：TTY 模式天然逐份过目键入；--delegated 默认一次仅一份（2026-09-27
-//   confirm-gate-one-per-call：多份并录曾系统性塌掉 build.md「逐件确认」三道门），L0/L1 协作道可
+//   confirm-gate-one-per-call：多份并录曾系统性塌掉 build.md「逐件确认」三道门），L1 协作道可
 //   `--batch` 多份一次代录（2026-09-30 hybrid-governance-risk-lanes）：逐份读「级别」，L2/L3 逐份拒绝
 //   （防御道不批量）；台账行带 `brief:true` 简洁审计标记（quote 原话仍入账供对质），check-loop 检查 15
 //   并录审计对全行带标记的批次豁免「确认并录」告警。--auto 一次仍仅一份（自治放行不批量）。
@@ -38,9 +42,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash, randomBytes } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readLedgerEntries, readLedgerRows } from './ledger-loader.mjs';
 import { confirmGateFor, clarifyGateFor, doneGateFor, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeDigest } from './policy.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 +153,40 @@ 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；2026-10-13 ledger-shard-default 升为默认）：多 worktree 并行时
+//   两个进程同时 append 同一台账文件会互相覆盖（各自读到同一末行 → 同 prevHash → 后写者覆盖前写者）。
+//   分片把本行写入 `.agents/confirmations.d/<doc基名>.jsonl`，各 worktree 各写各的、互不冲突。
+//   **默认写分片**（CLI 层；--no-shard / CONFIRM_SHARDED=0 显式回退主台账）——doc 链未激活
+//   （policyVersion < 8）时 CLI 层自动回退主台账（见 isMain 内 ledger-shard-default 注释），
+//   存量装户升级后行为零变化。函数层契约不变：shard 显式传入，默认 false。
+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');
@@ -189,7 +212,8 @@ if (isMain) {
   let delegatedQuote = null; // null = TTY 模式；字符串 = 委托代录的用户对话原话
   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 batchMode = false; // 协作道批量代录（--batch，2026-09-30 hybrid-governance-risk-lanes：仅 --delegated + L1）
+  let shardWrite = process.env.CONFIRM_SHARDED !== '0'; // 分片默认写入口径（2026-10-13 ledger-shard-default）：CONFIRM_SHARDED=0 显式回退主台账
   const docs = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--root') root = path.resolve(argv[++i]);
@@ -197,12 +221,36 @@ 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 if (argv[i] === '--no-shard') shardWrite = false;
     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);
   }
+  // 分片默认写入口径（2026-10-13 ledger-shard-default，对齐 Shipyard 参考实现）：
+  //   确认行默认写 `.agents/confirmations.d/<doc基名>.jsonl`——多 worktree / 多人并行天然各写各的，
+  //   互不覆盖；跨分支合并走 .gitattributes 的 union driver（confirmations.d/*.jsonl merge=jsonl-union），
+  //   里程碑可选跑 compact-ledgers.mjs 收敛碎片。--no-shard / CONFIRM_SHARDED=0 显式回退主台账。
+  // doc 链仍是分片的前提（2026-10-12 ledger-shard-write 口径保留）：分片与主台账分属不同文件，
+  //   只有 doc 链能跨来源接续；旧物理链口径下分片行的 prevHash 会与主台账末行失配 → 提交即断链。故：
+  //   显式 --shard + doc 链未激活 → 参数期直接拒（友好报错，原口径不变）；
+  //   默认分片 + doc 链未激活 → 自动回退主台账并出 ℹ️——存量装户（policyVersion < 8）升级模板后
+  //     行为零变化，分片默认仅对 doc 链已激活的装户生效；升级法：.agents/kit.json 设 policyVersion: 8。
+  if (argv.includes('--shard') && argv.includes('--no-shard')) {
+    console.error('用法：--shard 与 --no-shard 互斥——分片已是默认写入口径，显式回退主台账只需 --no-shard');
+    process.exit(1);
+  }
+  if (shardWrite && !ledgerDocChainActive(loadKitPolicy(root))) {
+    if (argv.includes('--shard')) {
+      console.error('❌ --shard 需要台账 doc 链口径（policy.ledgerDocChainSince），当前 policyVersion 无此键。\n   原因：分片与主台账是不同文件，只有 doc 链能跨来源接续；旧物理链口径下分片行会与主台账断链。\n   修法：在 .agents/kit.json 设 policyVersion: 8（或更高的支持版本）后重试，或改用 --no-shard 显式写主台账。');
+      process.exit(1);
+    }
+    shardWrite = false; // 存量装户回退：分片默认仅对 doc 链已激活（policyVersion ≥ 8）的装户生效
+    console.error('ℹ️ 分片默认写入口径需 doc 链口径（policy.ledgerDocChainSince），当前 policyVersion 未激活——本次写主台账 .agents/confirmations.jsonl。升级法：.agents/kit.json 设 policyVersion: 8。');
+  }
+
   const delegated = delegatedQuote !== null;
   if (delegated && autoMode) {
     console.error('❌ --auto 与 --delegated 互斥：自治模式是用户预先授权的机器放行，委托代录是单次对话确认');
@@ -218,7 +266,7 @@ if (isMain) {
   }
   // AI 自治门（2026-09-30 ai-autonomy-trust；2026-09-30 hybrid-governance-explore-hardening 加隐式形态）：
   // 读 .agents/trust-mode.json。除显式 --auto 外，Trusted（level=2）下的非 TTY 单份调用在 TTY 门处
-  // 免旗标自动转入本分支（见「Trusted 自动泳道」）——L0/L1 门 / incidents 排除 / 逐阶段与 done 门照常执行。
+  // 免旗标自动转入本分支（见「Trusted 自动泳道」）——L1 门 / incidents 排除 / 逐阶段与 done 门照常执行。
   let trustConfig = null;
   if (autoMode) {
     try {
@@ -236,7 +284,7 @@ if (isMain) {
       console.error('❌ AI 自治模式一次仅接受一份文档（与 --delegated 同口径，逐件放行）');
       process.exit(1);
     }
-    console.error(`⚠️  AI 自治模式（Trust L${trustConfig.level}）：仅限 L0/L1 文档；Level 1 只放行 draft→approved，Level 2 放行至 done`);
+    console.error(`⚠️  AI 自治模式（Trust L${trustConfig.level}）：仅限 L1 文档；Level 1 只放行 draft→approved，Level 2 放行至 done`);
   }
   if (delegated && !String(delegatedQuote).trim()) {
     console.error('用法：--delegated 须带用户对话原话（node .agents/scripts/confirm-doc.mjs <doc...> --delegated "<用户原话>"）——原话入台账供事后对质，不可缺省');
@@ -257,7 +305,7 @@ if (isMain) {
   if (!delegated && !autoMode && !ttyForced && (!process.stdin.isTTY || !process.stdout.isTTY)) {
     // Trusted 自动泳道（2026-09-30 hybrid-governance-explore-hardening）：trust-mode.json 为 Trusted
     // （enabled 且 level=2）时，非 TTY 调用（AI 会话）对文档**免手工触发**（无需 --delegated 原话 /
-    // --auto 旗标）自动转入 AI 自治放行——单份、非放弃态才可隐式（与 --auto 同口径，L0/L1 门与
+    // --auto 旗标）自动转入 AI 自治放行——单份、非放弃态才可隐式（与 --auto 同口径，L1 门与
     // incidents 排除由主循环自治门照常执行）；不满足则维持原拒绝（fail-closed，Standard/Strict 不隐式）。
     let implicitTrust = null;
     try {
@@ -265,8 +313,8 @@ if (isMain) {
     } catch { implicitTrust = { enabled: false, level: 0 }; }
     if (implicitTrust.enabled && implicitTrust.level === 2 && docs.length === 1 && !toTarget) {
       autoMode = true;
-      trustConfig = implicitTrust; // 主循环自治门（L0/L1 与 incidents 排除）直读本配置——顶部 if (autoMode) 块先于 TTY 门执行，须在此补装
-      console.error('⚠️  Trusted 自动泳道（隐式）：单份 L0/L1 文档按 AI 自治放行（Level 2 全闭环，台账 source=ai-auto-trust-L2）；L2/L3 与 incidents 仍须人工确认');
+      trustConfig = implicitTrust; // 主循环自治门（L1 与 incidents 排除）直读本配置——顶部 if (autoMode) 块先于 TTY 门执行，须在此补装
+      console.error('⚠️  Trusted 自动泳道（隐式）：单份 L1 文档按 AI 自治放行（Level 2 全闭环，台账 source=ai-auto-trust-L2）；L2/L3 与 incidents 仍须人工确认');
     } else {
       console.error('确认门须由用户在终端亲手运行（node .agents/scripts/confirm-doc.mjs <workflow/文档>...）——AI 会话内不可代确认；用户对话内明确确认后可用 --delegated "<用户原话>" 委托代录（台账如实记来源）');
       process.exit(1);
@@ -282,14 +330,14 @@ if (isMain) {
     // 单文档默认（2026-09-27 confirm-gate-one-per-call）：delegated 没有TTY「逐份过目」的天然机制——
     // 多文档并录曾系统性塌掉三道阶段门（build.md「逐件确认不得并作一次」）。逐件调用：一次一份、
     // 每次带当次用户原话。TTY 形态不受限（用户亲手逐份过目键入，天然逐件）。
-    // 协作道批量（2026-09-30 hybrid-governance-risk-lanes）：L0/L1 可 `--batch` 多份一次代录——
+    // 协作道批量（2026-09-30 hybrid-governance-risk-lanes）：L1 可 `--batch` 多份一次代录——
     // 逐份读「级别」，L2/L3 逐份拒绝（见主循环协作道门）；台账行带 brief:true，检查 15 据此豁免并录告警。
     if (docs.length > 1) {
       if (!batchMode) {
-        console.error(`❌ --delegated 一次仅接受一份文档（现 ${docs.length} 份：${docs.join(' ')}）——逐件确认口径（build.md）：每份一次调用、每次带当次用户原话；L0/L1 协作道批量可加 --batch`);
+        console.error(`❌ --delegated 一次仅接受一份文档（现 ${docs.length} 份：${docs.join(' ')}）——逐件确认口径（build.md）：每份一次调用、每次带当次用户原话；L1 协作道批量可加 --batch`);
         process.exit(1);
       }
-      console.error(`   批量代录（--batch）：${docs.length} 份，仅受理 L0/L1（协作道，异步审计兜底）；L2/L3 逐份拒绝`);
+      console.error(`   批量代录（--batch）：${docs.length} 份，仅受理 L1（协作道，异步审计兜底）；L2/L3 逐份拒绝`);
     }
   }
   // 调用事实（2026-09-28 batch-ledger-audit）：本次进程调用的批次标识与件序——
@@ -405,7 +453,7 @@ if (isMain) {
     // TTY 形态同样需要（事后对质问的是「放行时盘面上哪些文件在动」，与谁点的确认无关）。
     const scope = machineScope(root, doc);
     // AI 自治放行分支（2026-09-30 ai-autonomy-trust）：
-    // ① 仅 L0/L1（读 frontmatter「级别」，缺级别按不可自治处理——fail-closed）；
+    // ① 仅 L1（读 frontmatter「级别」，缺级别按不可自治处理——fail-closed）；
     // ② Level 1：仅 draft→approved；Level 2：draft→approved 与 approved→done；
     // ③ incidents 永不自治（open→fixed/fixed→closed 必须人工）。
     if (autoMode) {
@@ -414,16 +462,18 @@ if (isMain) {
         ? (target === 'approved' || target === 'done')
         : target === 'approved';
       if (!isLowLevel || !stageAllowed || doc.startsWith('workflow/incidents/')) {
-        console.error(`❌ ${doc} 未过 AI 自治门（级别「${lvl || '缺失'}」/ 泳道「${lane}」/ 目标态「${target}」/ 类型）：Level ${trustConfig.level} 仅授权泳道 low（intent 两字段一致 L0/L1；suspect 须先对齐「级别/risk_level」）的 ${trustConfig.level === 2 ? 'approved/done' : 'approved'} 且不含 incidents`);
+        console.error(`❌ ${doc} 未过 AI 自治门（级别「${lvl || '缺失'}」/ 泳道「${lane}」/ 目标态「${target}」/ 类型）：Level ${trustConfig.level} 仅授权泳道 low（intent 级别 L1；suspect 须先对齐「级别/risk_level」）的 ${trustConfig.level === 2 ? 'approved/done' : 'approved'} 且不含 incidents`);
         refused++;
         continue;
       }
       fs.writeFileSync(abs, applyTransition(text, target, fp.slice(0, 16)));
+      // shard 走第三参 options（不进 entry）：appendLedger(root, entry, { shard }) 的契约是 options 形参，
+      // 写进 entry 会让旗标混入台账行数据且分片开关失效（2026-10-13 ledger-shard-default 修复的存量缺陷）。
       appendLedger(root, {
         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,
-      });
+      }, { shard: shardWrite });
       console.log(`✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，AI 自治已记账：source=ai-auto-trust-L${trustConfig.level}）`);
       confirmed++;
       seq++;
@@ -431,11 +481,11 @@ if (isMain) {
     }
     if (delegated) {
       // 协作道门（2026-09-30 hybrid-governance-risk-lanes；2026-10-02 caliber-convergence 起单源泳道）：
-      // --batch 批量仅受理泳道 low（intent 两字段一致 L0/L1；suspect 拒）——high/suspect 逐份拒绝落账；
+      // --batch 批量仅受理泳道 low（intent 级别 L1；suspect 拒）——high/suspect 逐份拒绝落账；
       // 不带 --batch 的单份代录不限级别（既有口径不变）。
       const low = lane === 'low';
       if (batchMode && !low) {
-        console.error(`❌ ${doc} 泳道「${lane}」（级别「${lvl || '缺失'}」）不在协作道——--batch 批量代录仅限两字段一致的 L0/L1；suspect（级别/risk_level 缺失、非法或分歧）须先对齐两字段，L2/L3 防御道须逐份确认（本份未落账、未写盘）`);
+        console.error(`❌ ${doc} 泳道「${lane}」（级别「${lvl || '缺失'}」）不在协作道——--batch 批量代录仅限级别 L1；suspect（级别/risk_level 缺失、非法或分歧）须先对齐两字段，L2/L3 防御道须逐份确认（本份未落账、未写盘）`);
         refused++;
         continue;
       }
@@ -448,10 +498,10 @@ if (isMain) {
         // 改动面事实（A1 干净版）：quote 降级为「人类可读摘要」，分辨力改由 scope（机器派生）+ fingerprint
         // （文档内容）承担——「不复用同句」纪律据此退役（复用一句摘要不再削弱任何判据）。
         scope,
-        // 简洁审计标记（hybrid-governance-risk-lanes）：L0/L1 协作道行带 brief（quote 仍入账供对质），
+        // 简洁审计标记（hybrid-governance-risk-lanes）：L1 协作道行带 brief（quote 仍入账供对质），
         // 检查 15 并录审计对全 brief 批次豁免「确认并录」告警
         ...(low ? { brief: true } : {}),
-      });
+      }, { shard: shardWrite });
       console.log(low
         ? `✓ ${doc} ${st} → ${target} [${lvl} 协作道/异步审计]（指纹 ${fp.slice(0, 16)}）`
         : `✓ ${doc} ${st} → ${target}（指纹 ${fp.slice(0, 16)}，代录已记账：source=chat-delegated）`);
@@ -471,15 +521,70 @@ 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,
+        ts: new Date().toISOString(), doc, stage: target, fingerprint: fp, prev: st,
       source: 'tty',
       batch, seq, of: docs.length, // 调用事实（形态无关：TTY 多文档天然逐件过目，of>1 不构成违规）
-    });
+    }, { shard: shardWrite });
     console.log(`✓ ${doc} → ${target}（指纹 ${fp.slice(0, 16)}，台账已记）`);
     confirmed++;
     seq++;
   }
   if (rl) rl.close();
+  // --- 终态件滚动归档（2026-10-13 archive-on-close；B9 自 Shipyard.Material 回灌，行为边界逐字对齐）---
+  // 关单即归档：本进程刚落终态的文档，其同名家族若已全终态且超窗、无活跃引用 → git mv 进
+  // workflow/archive/<家族最晚终态月>/{类型}/。动机：archive-sweep 是手工工具、无人跑，活跃目录
+  // 无限膨胀（源仓实测 885 篇、733 篇终态零引用——留痕在包源仓 git 历史与 CHANGELOG）；挂进确认门
+  // 后活跃目录恒定。判定单源 = archive-sweep.analyze（禁第二套口径）；归档单位 = 同名家族
+  // （check-loop 检查 1 的结构配对是家族双向在场审计，单篇归档会造配对断裂——源仓首批返工实证）。
+  // 时序：**台账行已写、状态已落盘之后**才 mv——check-loop 检查 15 的内容绑定按台账 doc 路径读
+  // 四目录直下文件，归档后该路径不在 buildDocList() 扫描面内，绑定检查自然跳过（归档件不再受
+  // 内容绑定约束，与既有归档批次同口径）。失败一律 fail-open：归档是卫生动作，不得回滚已完成的
+  // 确认（**归档失败不阻断关单**——与源仓语义逐字一致）。启用锚（照搬源仓，无 policy 锚）：
+  // ① 仓库已建立归档约定（workflow/archive/ 存在）——真实装户仓有，临时 fixture 无，避免测试夹具
+  //   被静默搬走（也避免在未采纳归档的仓库里凭空造目录）；② env 逃生门 CONFIRM_DOC_NO_ARCHIVE。
+  const archiveRoot = path.join(root, 'workflow', 'archive');
+  if (confirmed > 0 && !process.env.CONFIRM_DOC_NO_ARCHIVE && fs.existsSync(archiveRoot)) {
+    try {
+      const { analyze, buildDocList, loadLastTouch, parseStatus, TERMINAL, ACTIVE } = await import('./archive-sweep.mjs');
+      // 台账终态锚：kit 读侧单源 = readLedgerRows（主台账+分片透明合并；源仓走
+      // loadAllConfirmations——「每 doc 终态行最大日期」的 max 判据对去重口径无语义差，
+      // 见 archive-sweep.loadLedgerTs 同款注释）。CONFIRM_DOC_TEST_NOW 仅测试注入，生产不设。
+      const ledgerTs = {};
+      for (const e of readLedgerRows(root)) {
+        if (TERMINAL.has(e.stage) && e.doc) {
+          const d = (e.ts || '').slice(0, 10);
+          if (d && (!ledgerTs[e.doc] || d > ledgerTs[e.doc])) ledgerTs[e.doc] = d;
+        }
+      }
+      const allDocs = buildDocList(root);
+      // 窗口口径：本次确认的文档**刚**落终态，其台账 ts = 今日 → 21 天窗口必然拦下（窗口的用途是
+      // 「防归档仍在编辑的在途件」，而刚过确认门的终态件按定义已定稿，窗口对它冗余）。故对本进程
+      // 确认过的家族用 windowDays=-1（判据 `floor((today-tTime)/864e5) <= windowDays` 恒 false = 窗口
+      // 关闭；注意 0 不等于关闭——0 表示「同日也算未满窗」）；未涉及的家族不在此次归档范围（touched
+      // 过滤），历史积压仍走 archive-sweep 手工批次 + 21 天窗口。
+      const r = analyze({
+        docs: allDocs,
+        ledgerTs,
+        lastTouch: loadLastTouch(root),
+        activeTexts: allDocs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+        windowDays: -1,
+      });
+      // 只归档「本次确认涉及的家族」——不越权清理历史积压（积压走 archive-sweep 手工批次）
+      const touched = new Set(docs.map((d) => path.basename(d)));
+      const mine = r.candidates.filter((x) => touched.has(x.file));
+      if (mine.length) {
+        for (const x of mine) {
+          const destDir = path.join(root, 'workflow', 'archive', x.month, x.dir);
+          fs.mkdirSync(destDir, { recursive: true });
+          execFileSync('git', ['mv', x.rel, path.join('workflow', 'archive', x.month, x.dir, x.file)], { cwd: root });
+        }
+        const fams = new Set(mine.map((x) => x.file));
+        console.log(`📦 归档 ${mine.length} 篇 / ${fams.size} 族 → workflow/archive/<终态月>/（家族原子；活跃目录不再累积终态件）`);
+      }
+    } catch (err) {
+      console.error(`⚠️ 归档跳过（fail-open，不影响已完成的确认）：${err.message}`);
+    }
+  }
   console.log(`\n完成：确认 ${confirmed} 份 / 跳过 ${docs.length - confirmed - refused} 份 / 拒绝 ${refused} 份${delegated ? '（委托代录）' : ''}`);
   process.exit(refused ? 2 : 0);
 }