agentic-flow-kit 0.9.1 → 1.0.0

package/templates/_agents/commands/pipeline-run.md

@@ -0,0 +1,43 @@
+---
+description: pipeline-run 自动化驱动入口——单命令驱动六阶段闭环（工单协议+机器门+原话代录）
+stage: entry
+triggers:
+  - "pipeline-run"
+  - "跑执行器"
+  - "全自动跑"
+approval_required: true
+fallback: 主智能体亲自做 AI 槽位（工单由主智能体完成，不依赖子智能体）
+next: 按 run 停机点循环推进至 done
+---
+
+# pipeline-run · 全自动闭环执行器入口
+
+> 确定性部分由 `pipeline-run.mjs` 状态机驱动（机器门序列：fill-* → confirm-doc → verify.mjs → git，退出码全记录）；
+> AI 槽位经工单协议交宿主执行；人件门到点即停、原话代录。宿主只按本协议驱动，不自行改状态。
+
+## 驱动协议（宿主 AI 逐条执行）
+
+1. **启动**：`node .agents/scripts/pipeline-run.mjs start "<需求原文>"`（可预判则加 `--hint "kind=… level=… module=…"`）。
+2. **循环读停机点**：每次命令的 stdout 末行是机器标记 `PIPELINE-STOP <type> …`，按 type 分流：
+   - `work-order <runId> <工单id>`——读工单全文（目标/步骤/约束/验收），**按单干活**：
+     - triage：判级回填 `next --triage "kind=… level=… module=… topic=<英文kebab>"`（就高不就低）
+     - draft：起草指定文档；implement/fix：按授权文件实现（**偏离即停**——公共接口/计划外文件/新依赖→停机向用户上报，不自行放行）；review/closeout：按单产出并写入指定位
+     - 干完回跑 `next`（implement/fix 须 `--files "a,b"` 回填改动清单；review-only 汇报后 `--done` 收尾）
+   - `await-confirm <runId> <doc>`——**人件门**：向用户转述「要点」索确认；用户明确放行后
+     `next --delegated "<用户原话>"`（逐字原话，**永不编造、永不复用旧句**；一次一份）
+   - `gate-fail <runId> <stage>`——读 problems 原因，修复后原路重跑（不绕门、不加 `--no-verify`）
+   - `done <runId>`——向用户汇报总结（阶段条/门数/提交链），流程结束
+   - `aborted <runId>`——已显式放弃，汇报放弃态与留档位置
+3. **放弃**：用户明确不做时 `abort --run <id> --to superseded|cancelled --delegated "<原话>"`（approved 文档逐份走 confirm-doc --to）。
+4. **观测**（可选）：`status [--run <id>] [--json]` 全量事件流水；`watch` 终端轮询视图。
+
+## 硬纪律（违反即协议破坏）
+
+- 状态迁移唯一入口是脚本内部的 confirm-doc 调用——宿主**永不直改** workflow 文档 frontmatter 状态。
+- `--delegated` 的原话必须是用户当次对话原话（台账 `confirmations.jsonl` 留痕可对质）。
+- 修复环超限（3 次）时停机交人工，不带病推进；verify 非绿不关单。
+- run 文件（.agents/cache/pipeline-runs/）是脚本亲写的机器事实——宿主只读不写。
+
+## 与 new-task 的关系
+
+本命令是**自动化驱动的并列入口**（单命令走全程）；new-task.md 是手动阶段路由入口。同一套门禁与确认语义，二者只选其一驱动一个任务，不混用。

package/templates/_agents/commands/plan.md

@@ -21,11 +21,11 @@ next: L1 → .agents/commands/build.md (起草 Quick-Plan) ；L2/L3 → .agents/
 1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
 2. 否则起草新 intent:
    - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
-   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段（含 risk_level）+ 7 节正文（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准）的草稿；AI 据此填实，模板与节标题机器保证不出错
+   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段（含 risk_level）+ 9 节（背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核）的草稿；AI 据此填实，模板与节标题机器保证不出错
    - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
    - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
-   - 按 6 节填写:背景与问题 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线（L1 微改动可省非目标/约束两节，不硬填）
-   - 红线勾选对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
+   - 按 8 节填写:背景与问题 / 历史教训防复发 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线 / 验收标准（L1 微改动可省非目标/约束两节，不硬填）
+   - 红线勾选对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
 

package/templates/_agents/commands/sync-hosts.md

@@ -22,7 +22,7 @@ next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的
 
 ## 何时跑
 
-- 改 `templates/_agents/commands/*.md` 正文后（8 个 commands 文件）
+- 改 `templates/_agents/commands/*.md` 正文后（11 个 commands 文件）
 - 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
 - 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
 - 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件

package/templates/_agents/scripts/check-lane-surface.mjs

@@ -23,6 +23,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { laneOfEntry, laneOfDoc } from './stage-gates.mjs';
+import { loadKitPolicy } from './policy.mjs';
 
 const argv = process.argv.slice(2);
 const argOf = (k) => {
@@ -44,6 +46,8 @@ const STAGED = stagedArg
   : gitOut(ROOT, ['diff', '--cached', '--name-only', '--diff-filter=ACMR']).split(/\r?\n/).filter(Boolean);
 
 const isExperiment = /^experiment\//.test(BRANCH);
+// 泳道协议锚（单源 policy.mjs）：无 kit.json 的测试夹具回落 v1（无键=双字段协议从未生效，单字段判）
+const RISK_LEVEL_SINCE = loadKitPolicy(ROOT).riskLevelSince;
 
 // frontmatter 读取（CRLF 容忍；口径同 check-loop fmGet：--- 包夹、键行前缀匹配）
 const fmOf = (file) => {
@@ -88,7 +92,10 @@ const loadPatterns = () => {
   return pats;
 };
 
-// 活跃入口收集（incident≡intent 等价；日期键 intent=日期 / incident=发现）
+// 活跃入口收集（incident≡intent 等价；日期键 intent=日期 / incident=发现）。
+// 泳道单源（2026-10-02 caliber-convergence 方案 C 分歧双严）：intent 走 laneOfEntry（双字段三态，
+// 协议锚 policy.riskLevelSince），其余走 laneOfDoc（级别单字段）——suspect（缺失/非法/分歧）不计
+// high（不作豁免依据）、计入拦截集（消息按 suspect 给「两字段对齐」指引）。
 const ACTIVE = {
   intent: new Set(['draft', 'approved']),
   incident: new Set(['open', 'fixed']),
@@ -102,7 +109,10 @@ const collectActive = () => {
       if (!f.endsWith('.md') || f === '_TEMPLATE.md') continue;
       const fm = fmOf(path.join(dirPath, f));
       if (!ACTIVE[kind].has(fm['状态'] || '')) continue;
-      out.push({ rel: `workflow/${dir}/${f}`, base: f.replace(/\.md$/, ''), level: fm['级别'] || '', date: fm[dateKey] || '', kind });
+      const lane = kind === 'intent'
+        ? laneOfEntry(fm['级别'] || '', fm['risk_level'] || '', RISK_LEVEL_SINCE, fm['日期'] || '')
+        : laneOfDoc(fm['级别'] || '');
+      out.push({ rel: `workflow/${dir}/${f}`, base: f.replace(/\.md$/, ''), level: fm['级别'] || '', risk: fm['risk_level'] || '', lane, date: fm[dateKey] || '', kind });
     }
   }
   return out;
@@ -116,16 +126,19 @@ const patterns = loadPatterns();
 const hits = patterns.length ? STAGED.filter((p) => patterns.some((re) => re.test(p))) : [];
 if (hits.length) {
   const active = collectActive();
-  const hasHigh = active.some((e) => e.level === 'L2' || e.level === 'L3');
+  const hasHigh = active.some((e) => e.lane === 'high');
   if (!hasHigh) {
-    const low = active.filter((e) => e.level !== 'L2' && e.level !== 'L3');
+    const low = active.filter((e) => e.lane !== 'high'); // low + suspect 均拦（suspect 不作豁免依据）
     if (low.length) {
       const newest = [...low].sort((a, b) => (b.date || '').localeCompare(a.date || '') || b.rel.localeCompare(a.rel))[0];
+      const fixVerb = newest.lane === 'suspect'
+        ? '① 对齐该入口「级别」与「risk_level」两字段至一致的 L2/L3（fill-intent 双写口径；现两值缺失/非法/分歧）并补同名 spec（.agents/commands/design.md）'
+        : '① 升级该入口「级别」与「risk_level」两字段至 L2/L3 并补同名 spec（.agents/commands/design.md）';
       const text = [
-        `[触达面判低] 暂存命中 L2 触达面，但活跃入口全为 L0/L1（含级别缺失）：`,
+        `[触达面判低] 暂存命中 L2 触达面，但活跃入口无泳道 high（存在 low/suspect）：`,
         `  命中: ${hits.join(' ')}`,
-        `  关联入口: ${newest.rel}（${newest.level || '级别缺失'}${newest.date ? `，${newest.date}` : ''}；活跃 L0/L1 共 ${low.length} 件）`,
-        `  修法（三选一）: ① 升级该入口「级别/risk_level」至 L2/L3 并补同名 spec（.agents/commands/design.md）`,
+        `  关联入口: ${newest.rel}（级别 ${newest.level || '缺失'}/risk_level ${newest.risk || '缺失'}→ 泳道 ${newest.lane}${newest.date ? `，${newest.date}` : ''}；活跃非 high 共 ${low.length} 件）`,
+        `  修法（三选一）: ${fixVerb}`,
         `    ② 该入口已完成则关单（done）或显式放弃（superseded/cancelled）——不留活跃残留`,
         `    ③ 面清单误配则修 .agents/lane-surfaces.txt`,
       ].join('\n');

package/templates/_agents/scripts/check-lane-surface.test.mjs

@@ -133,12 +133,34 @@ const FM_L0_NEW = '状态: draft\n级别: L0\n日期: 2026-10-01\n模块: ui';
   check('incident 等价：fixed L1 算活跃低级入口 → 阻断',
     r.code === 1 && r.out.includes('[触达面判低]') && r.out.includes('incidents/2026-09-30-inc.md'), r.out);
 }
-// --- 级别缺失：按低级计（不能自证 L2+ 即拦）---
+// --- 级别缺失：suspect 拦截（方案 C：不能自证 high 即拦，消息给两字段对齐指引）---
 {
   const d = mkfix();
   base(d, { level: '', status: 'draft' });
   const r = run(d, { staged: ['templates/t.md'] });
-  check('级别缺失的活跃入口按低级计 → 阻断且消息含「级别缺失」', r.code === 1 && r.out.includes('级别缺失'), r.out);
+  check('级别缺失 → 泳道 suspect 拦断且消息含两字段对齐指引',
+    r.code === 1 && r.out.includes('suspect') && r.out.includes('对齐'), r.out);
+}
+// --- 方案 C：级别与 risk_level 分歧 → suspect 拦截（两字段协议期）---
+{
+  const d = mkfix();
+  w(d, '.agents/lane-surfaces.txt', '^templates/\n');
+  w(d, '.agents/kit.json', JSON.stringify({ policyVersion: 2 }));
+  w(d, 'workflow/intents/2026-10-02-divergent.md',
+    intent('x', '状态: approved\n级别: L2\nrisk_level: L1\n日期: 2026-10-02\n模块: pipeline'));
+  const r = run(d, { staged: ['templates/t.md'] });
+  check('分歧（L2/L1）→ suspect 拦断（不作豁免依据）',
+    r.code === 1 && r.out.includes('suspect') && r.out.includes('2026-10-02-divergent'), r.out);
+}
+// --- 方案 C：两字段一致 high → 豁免（对照）---
+{
+  const d = mkfix();
+  w(d, '.agents/lane-surfaces.txt', '^templates/\n');
+  w(d, '.agents/kit.json', JSON.stringify({ policyVersion: 2 }));
+  w(d, 'workflow/intents/2026-10-02-aligned.md',
+    intent('x', '状态: approved\n级别: L2\nrisk_level: L2\n日期: 2026-10-02\n模块: pipeline'));
+  const r = run(d, { staged: ['templates/t.md'] });
+  check('两字段一致 L2 → 豁免放行', r.code === 0 && !r.out.includes('触达面判低'), r.out);
 }
 // --- 平台边界：CRLF frontmatter ---
 {

package/templates/_agents/scripts/check-ledger-invariant.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// check-ledger-invariant — confirmations.jsonl 提交不变量（2026-10-02 ledger-ci-invariant）
+// 目的：把「台账本地可写」的伪造面从事后对质级升为机器可检出级（能力评审审计维度扣分项）。
+// 台账不可变原则：confirmations.jsonl 历史行禁删改——修正只能走追加补偿行（README 硬规则 6）。
+//
+// 模式：
+//   历史全扫（缺省，CI 机器门）：遍历台账全部提交历史（时间正序），每次变更必须以旧 blob 为
+//     **逐字节前缀**（允许纯追加；禁止删行/改行/重排）；再对最终树做行级校验（五项，见下）。
+//     blob 读取走 git 对象库（入库 LF 归一口径），不受工作树 autocrlf 影响。
+//   --staged（pre-commit 前置）：暂存 blob 必须以 HEAD blob 为逐字节前缀——提交时刻即拦重写。
+//
+// 行级校验（终树，五项）：
+//   ① ts 为 ISO 字符串且全表非降序（追加时序单调）
+//   ② fingerprint 为 64 位 hex
+//   ③ source=chat-delegated 行必有非空 quote（原话对质面）
+//   ④ doc 匹配 workflow/(intents|specs|plans|incidents)/[^/]+.md 且当前树存在
+//   ⑤ stage ∈ 合法跳转终态集（approved/done/fixed/closed/superseded/cancelled）
+//
+// 静默条件：台账不存在 / 零提交历史（装户、新仓）/ --staged 且暂存未触台账或无 HEAD 版本。
+// 已知边界：git log --follow 未用——台账自创建无重命名（单一路径取史）；克隆深度不足时仅扫可得
+//   历史（CI 侧 fetch-depth:0 兜全史，深度不足会告警声明边界，fail-open 于深度、fail-closed 于内容）。
+// 用法：node check-ledger-invariant.mjs [--root <仓库根>] [--staged]
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const staged = argv.includes('--staged');
+const ROOT = argOf('--root') || (staged ? process.cwd() : execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim());
+const REL = '.agents/confirmations.jsonl';
+const FILE = path.join(ROOT, REL);
+const VALID_STAGES = new Set(['approved', 'done', 'fixed', 'closed', 'superseded', 'cancelled',
+  'revert-draft', 'revert-open']); // 回退注记行（check-loop :822 认可；fingerprint 恒 n/a）
+
+const git = (args, opts = {}) => execFileSync('git', args, { cwd: ROOT, encoding: 'buffer', maxBuffer: 64 * 1024 * 1024, ...opts });
+const gitText = (args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+const blobOf = (ref) => git(['show', ref]); // ref 必须为完整对象引用（<sha>:<path> / HEAD:<path> / :<path>）
+
+const problems = [];
+const fail = (msg) => { console.error(msg); process.exit(1); };
+
+// ---- --staged：暂存 blob ⊇ HEAD blob ----
+if (staged) {
+  const stagedHit = gitText(['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only']).split(/\r?\n/).includes(REL);
+  if (!stagedHit) process.exit(0);
+  const headExists = (() => { try { gitText(['rev-parse', '--verify', '--quiet', `HEAD:${REL}`]); return true; } catch { return false; } })();
+  if (!headExists) process.exit(0); // 首次入库：无 HEAD 基线，历史全扫后续覆盖
+  let head, cur;
+  try {
+    head = blobOf(`HEAD:${REL}`);
+    cur = blobOf(`:${REL}`); // 暂存区
+  } catch {
+    process.exit(0); // 对象读取异常（如极端并发）交由 CI 全扫兜底
+  }
+  if (!cur.subarray(0, head.length).equals(head)) {
+    let off = 0;
+    while (off < Math.min(head.length, cur.length) && head[off] === cur[off]) off++;
+    problems.push(`- [台账重写] 暂存内容不是 HEAD 的前缀扩展（首异偏移 ${off}，HEAD ${head.length}B → 暂存 ${cur.length}B）`);
+    console.error('台账不可变（--staged）— BLOCK:\n' + problems.join('\n'));
+    console.error('  修法：台账历史行禁删改——误写走追加补偿行（node .agents/scripts/confirm-doc.mjs ...）；确需撤销历史提交请 git revert 后重新追加');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// ---- 历史全扫（缺省）----
+if (!fs.existsSync(FILE)) process.exit(0); // 装户/新仓无台账面
+let shas;
+try {
+  shas = gitText(['log', '--format=%H', '--reverse', '--', REL]).split(/\s+/).filter(Boolean);
+} catch {
+  process.exit(0); // 非仓库或文件未入库（测试夹具）
+}
+if (!shas.length) process.exit(0);
+
+let prev = null;
+let prevSha = null;
+for (const sha of shas) {
+  let cur;
+  // 删除提交不是静默边界（复核 P2 收口）：台账在 append-only 世界里永不应删除——任一历史提交删除
+  // 台账即 hard fail（否则「删除→次提交重加」会把重加 blob 当新基线绕过前缀判据）。
+  try { cur = blobOf(`${sha}:${REL}`); } catch {
+    problems.push(`- [台账删除] ${sha.slice(0, 10)}：该提交删除了 confirmations.jsonl（append-only 世界禁删文件）`);
+    prev = null; // 后续重加无基线可比，仅受行级校验约束
+    continue;
+  }
+  if (prev !== null && !cur.subarray(0, prev.length).equals(prev)) {
+    let off = 0;
+    while (off < Math.min(prev.length, cur.length) && prev[off] === cur[off]) off++;
+    const removed = prev.length > cur.length;
+    problems.push(`- [前缀破坏] ${sha.slice(0, 10)}（前承 ${prevSha.slice(0, 10)}）：历史内容被${removed ? `删减 ${prev.length - cur.length}B` : `改写（首异偏移 ${off}，旧 ${prev.length}B → 新 ${cur.length}B）`}`);
+  }
+  prev = cur;
+  prevSha = sha;
+}
+
+// ---- 行级校验（终树）----
+let rows = [];
+try {
+  rows = fs.readFileSync(FILE, 'utf8').split(/\r?\n/).filter((l) => l.trim()).map((l) => { try { return JSON.parse(l); } catch { return null; } });
+} catch { /* 上面 existsSync 已兜 */ }
+let prevTs = '';
+rows.forEach((e, idx) => {
+  const at = `第 ${idx + 1} 行`;
+  if (!e || typeof e !== 'object') { problems.push(`- [行级] ${at}：非 JSON 对象行`); return; }
+  if (typeof e.ts !== 'string' || Number.isNaN(Date.parse(e.ts))) problems.push(`- [行级] ${at}：ts 非 ISO 字符串`);
+  else {
+    if (prevTs && e.ts < prevTs) problems.push(`- [行级] ${at}：ts ${e.ts} 早于前行 ${prevTs}（追加时序非单调）`);
+    prevTs = e.ts;
+  }
+  const isRevertNote = typeof e.stage === 'string' && e.stage.startsWith('revert-');
+  if (isRevertNote) {
+    if (e.fingerprint !== 'n/a') problems.push(`- [行级] ${at}：回退注记行 fingerprint 恒为「n/a」`);
+  } else if (typeof e.fingerprint !== 'string' || !/^[0-9a-f]{64}$/.test(e.fingerprint)) {
+    problems.push(`- [行级] ${at}：fingerprint 非 64 位 hex`);
+  }
+  if (e.source === 'chat-delegated' && !(typeof e.quote === 'string' && e.quote.trim())) problems.push(`- [行级] ${at}：chat-delegated 行缺非空 quote（原话对质面）`);
+  if (typeof e.doc !== 'string' || !/^workflow\/(intents|specs|plans|incidents)\/[^/]+\.md$/.test(e.doc)) {
+    problems.push(`- [行级] ${at}：doc 路径不在 workflow 四目录协议内`);
+  } else if (!fs.existsSync(path.join(ROOT, e.doc))) {
+    problems.push(`- [行级] ${at}：doc ${e.doc} 在当前树不存在`);
+  }
+  if (!VALID_STAGES.has(e.stage)) problems.push(`- [行级] ${at}：stage「${e.stage || '缺失'}」不在合法跳转终态集`);
+});
+
+if (problems.length) {
+  console.error(`台账不可变（历史全扫）— HARD-BLOCK:\n\n${problems.join('\n')}\n`);
+  console.error('  修法：台账历史行禁删改（append-only 前缀不变量）——误写只能追加补偿行；确需撤销历史提交请 git revert 后重新追加。篡改属审计事件，保留现场联系仓库所有者。');
+  process.exit(1);
+}
+process.exit(0);

package/templates/_agents/scripts/check-ledger-invariant.test.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// check-ledger-invariant.test.mjs — 台账提交不变量 fixture 套件（2026-10-02 ledger-ci-invariant）
+// 真 git 仓注入：合法追加放行 / 六类篡改与行级违例检出 / --staged 双态 / 首次入库与空台账静默。
+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, 'check-ledger-invariant.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 HEX = 'a'.repeat(64);
+const row = (o = {}) => JSON.stringify({
+  ts: '2026-10-02T00:00:00.000Z', doc: 'workflow/intents/demo.md', stage: 'approved',
+  fingerprint: HEX, prev: 'draft', source: 'chat-delegated', quote: '确认', ...o,
+});
+
+const G = (root, args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+const commitAll = (root, msg) => { G(root, ['add', '-A']); G(root, ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', msg]); };
+const run = (root, args = []) => {
+  const r = spawnSync(process.execPath, [SCRIPT, '--root', root, ...args], { encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+
+// mkrepo：临时真仓（workflow/intents/demo.md 在树 + 台账首行已提交）
+const mkrepo = (firstRow = row()) => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-inv-test-'));
+  fs.mkdirSync(path.join(d, 'workflow', 'intents'), { recursive: true });
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(d, 'workflow', 'intents', 'demo.md'), '---\n状态: approved\n级别: L1\n日期: 2026-10-02\n模块: pipeline\n---\n# I\n');
+  fs.writeFileSync(path.join(d, '.agents', 'confirmations.jsonl'), firstRow + '\n');
+  G(d, ['init', '-q']);
+  G(d, ['config', 'user.email', 't@t']);
+  G(d, ['config', 'user.name', 't']);
+  commitAll(d, 'base ledger');
+  return d;
+};
+const ledPath = (d) => path.join(d, '.agents', 'confirmations.jsonl');
+const append = (d, line) => fs.appendFileSync(ledPath(d), line + '\n');
+
+// S1：合法追加 ×2 → 历史全扫过
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  commitAll(d, 'append 2nd');
+  const r = run(d);
+  check('S1 合法追加两次 → 历史全扫 exit 0', r.code === 0, r.out);
+}
+// S2：删历史行 → 前缀破坏拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  commitAll(d, 'append');
+  fs.writeFileSync(ledPath(d), row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }) + '\n'); // 删首行
+  commitAll(d, 'drop first row');
+  const r = run(d);
+  check('S2 删历史行 → 前缀破坏 exit 1', r.code === 1 && r.out.includes('前缀破坏') && r.out.includes('删减'), r.out);
+}
+// S3：改历史行内容 → 拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  commitAll(d, 'append');
+  const lines = fs.readFileSync(ledPath(d), 'utf8').split('\n').filter(Boolean);
+  lines[0] = lines[0].replace('确认', '改成别的'); // 改首行 quote
+  fs.writeFileSync(ledPath(d), lines.join('\n') + '\n');
+  commitAll(d, 'rewrite first line');
+  const r = run(d);
+  check('S3 改历史行 → 前缀破坏 exit 1（首异偏移）', r.code === 1 && r.out.includes('改写') && r.out.includes('首异偏移'), r.out);
+}
+// S4：非前缀改写（截断+异内容）→ 拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  commitAll(d, 'append');
+  fs.writeFileSync(ledPath(d), row({ ts: '2027-01-01T00:00:00.000Z', quote: '另起炉灶' }) + '\n');
+  commitAll(d, 'replace all');
+  const r = run(d);
+  check('S4 非前缀整体改写 → exit 1', r.code === 1 && r.out.includes('前缀破坏'), r.out);
+}
+// S5：ts 乱序追加 → 行级拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-01T00:00:00.000Z', stage: 'done' })); // 早于首行
+  commitAll(d, 'append out-of-order');
+  const r = run(d);
+  check('S5 ts 非单调 → 行级 exit 1', r.code === 1 && r.out.includes('非单调'), r.out);
+}
+// S6：伪指纹（非 64-hex）→ 行级拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done', fingerprint: 'zzz' }));
+  commitAll(d, 'append bad fp');
+  const r = run(d);
+  check('S6 fingerprint 非 64-hex → 行级 exit 1', r.code === 1 && r.out.includes('64 位 hex'), r.out);
+}
+// S7：chat-delegated 空 quote → 行级拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done', quote: '' }));
+  commitAll(d, 'append empty quote');
+  const r = run(d);
+  check('S7 chat-delegated 空 quote → 行级 exit 1', r.code === 1 && r.out.includes('quote'), r.out);
+}
+// S8：doc 路径在树中不存在 → 行级拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done', doc: 'workflow/intents/ghost.md' }));
+  commitAll(d, 'append ghost doc');
+  const r = run(d);
+  check('S8 doc 当前树不存在 → 行级 exit 1', r.code === 1 && r.out.includes('不存在'), r.out);
+}
+// S9：--staged 合法追加 → 过
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  G(d, ['add', '-A']);
+  const r = run(d, ['--staged']);
+  check('S9 --staged 合法追加 → exit 0', r.code === 0, r.out);
+}
+// S10：--staged 删历史行 → 拦
+{
+  const d = mkrepo();
+  append(d, row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }));
+  commitAll(d, 'append');
+  fs.writeFileSync(ledPath(d), row({ ts: '2026-10-02T01:00:00.000Z', stage: 'done' }) + '\n');
+  G(d, ['add', '-A']);
+  const r = run(d, ['--staged']);
+  check('S10 --staged 删历史行 → exit 1', r.code === 1 && r.out.includes('台账重写'), r.out);
+}
+// S11：首次入库（无 HEAD 基线）与空台账 → 静默过
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'ledger-inv-fresh-'));
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  G(d, ['init', '-q']);
+  G(d, ['config', 'user.email', 't@t']);
+  G(d, ['config', 'user.name', 't']);
+  fs.writeFileSync(ledPath(d), row() + '\n');
+  G(d, ['add', '-A']);
+  const rs = run(d, ['--staged']);
+  const rh = run(d);
+  check('S11 首次入库（staged 无 HEAD 基线 / 历史零提交）均静默过', rs.code === 0 && rh.code === 0, `staged=${rs.out} hist=${rh.out}`);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+// S12：回退注记行（revert-draft / fingerprint n/a）合法放行
+{
+  const d = mkrepo(row({ ts: '2026-10-02T00:00:00.000Z', stage: 'revert-draft', fingerprint: 'n/a', prev: 'approved' }));
+  const r = run(d);
+  check('S12 回退注记行（n/a 指纹）→ 历史全扫过', r.code === 0, r.out);
+}
+
+console.log(`\n${fail ? `❌ ${fail} failed` : '✅ all passed'}（${pass} passed）`);
+process.exit(fail ? 1 : 0);