agentic-flow-kit 1.2.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {

package/src/fresh-init.test.mjs

@@ -42,6 +42,16 @@ check('新装 audit 为 false 且 policyVersion 为 2', kit.audit === false && k
   check('新装无包源模板对应条目无锚（生成类配置不参与感知）', cfg !== undefined && cfg.srcSha256 === undefined);
   const rb = tplAnchor('.agents/rule-budgets.txt');
   check('新装 _agents 前缀翻译参与感知（rule-budgets 带锚）', rb !== undefined && typeof rb.srcSha256 === 'string');
+  // CI 远端门模板（2026-10-07 adopter-ci-github）：.github → _github 通用点前缀翻译 + owned 落盘带锚
+  const ci = tplAnchor('.github/workflows/kit-ci.yml');
+  const ciSrc = fs.readFileSync(path.join(ROOT, 'templates', '_github', 'workflows', 'kit-ci.yml'), 'utf8').replace(/\r\n/g, '\n');
+  check('新装 CI 远端门模板落盘且 kit.json owned 带锚（srcSha256 == 包源 LF 归一 sha）',
+    fs.existsSync(path.join(dir, '.github', 'workflows', 'kit-ci.yml'))
+    && ci !== undefined && ci.srcSha256 === shaOf(Buffer.from(ciSrc, 'utf8')),
+    JSON.stringify(ci || null));
+  const ciText = fs.readFileSync(path.join(dir, '.github', 'workflows', 'kit-ci.yml'), 'utf8');
+  check('新装 CI 模板引用统一入口 verify.mjs、含分支策略人工边界提示且无 Tab 缩进',
+    ciText.includes('node .agents/scripts/verify.mjs') && ciText.includes('branch protection') && !ciText.includes('\t'));
 }
 check('claude 命令与角色薄适配落盘',
   fs.existsSync(path.join(dir, '.claude', 'commands', 'wf-plan.md'))

package/src/init.mjs

@@ -97,7 +97,7 @@ async function interactive() {
   const menu = (names) => '  ' + names.map((n, i) => dim(`${menuMark(i)} ${stackLabel(n)}`)).join(dim('   '));
 
   console.log(bold(cyan('▶ flow-kit init')) + dim(' · AI 闭环工作流 + wiki 知识层脚手架'));
-  console.log(dim('  安装到当前目录：.agents/ · .githooks/ · workflow/ · wiki/ · AGENTS.md（已存在的文件保守跳过；AGENTS.md 无工作流骨架时文末追加补齐）'));
+  console.log(dim('  安装到当前目录：.agents/ · .githooks/ · workflow/ · wiki/ · AGENTS.md · .github/workflows/kit-ci.yml（CI 远端门，非 GitHub 装户可删）（已存在的文件保守跳过；AGENTS.md 无工作流骨架时文末追加补齐）'));
   try {
     let hosts;
     for (;;) {

package/src/profiles.mjs

@@ -106,13 +106,17 @@ export function pickStackVars(stackKey) {
 // Node 18.20 / 20.18 / 22.11 全部 ERR_REQUIRE_ESM（只有 ≥20.19/≥22.12 可用），而本仓 engines
 // 写 >=18.0.0、CI 跑 18/22 → 装户在 CI 目标版本上根本用不了。改 .cjs 后 createRequire 同步载入
 // 全线可用。旧 .mjs 路径同样登记为 owned（免装户残留旧文件时落 managed 重演缺陷）。
+// .github/ 是装户 CI 远端门（2026-10-07 adopter-ci-github）：kit 只下发 workflows/kit-ci.yml 薄模板，
+// 触发分支 / node 版本 / 测试命令均项目特定——归 owned，sync 永不覆盖；感知锚经 srcTemplatePath
+// 通用点前缀翻译命中 templates/_github/。
 export function isOwned(rel) {
   return rel === 'AGENTS.md' || rel === '.gitattributes' || rel.startsWith('workflow/') || rel.startsWith('wiki/')
     || rel.startsWith('.agents/notes/')
     || rel === '.agents/workflow-modules.txt' || rel === '.agents/rule-budgets.txt'
     || rel === '.agents/metric-claims.txt' || rel === '.agents/metric-derivers.cjs'
     || rel === '.agents/metric-derivers.mjs'
-    || rel === '.agents/hooks/local-pre-commit';
+    || rel === '.agents/hooks/local-pre-commit'
+    || rel.startsWith('.github/');
 }
 
 // ---- 模板下发感知（2026-10-06 template-downstream）----
@@ -124,12 +128,14 @@ export function isOwned(rel) {
 // 装户不期望跟随包源模板——模板感知排除出比对面（防「拉取了也被生成器重写」的无谓出账）。新增生成器目标须同步本清单。
 export const TEMPLATE_DRIFT_EXCLUDE = new Set(['workflow/INDEX.md', 'wiki/INDEX.md', 'wiki/知识沉淀总览.html']);
 
-// 映射规则单源：renderTree 的「srcRoot/templates ↔ targetRoot/项目根」关系 + 点目录前缀翻译
-// （render.mjs：`_agents` → `.agents`）——装户 rel 以 .agents/ 开头时探 templates/_agents/<余径>。
-// 复核 P2-1（2026-10-06 template-downstream 独立复核）：漏翻译会让 rule-budgets.txt /
-// metric-claims.txt / local-pre-commit 等 5 条有包源起步模板的 owned 件永不参与感知。
+// 映射规则单源：renderTree 的「srcRoot/templates ↔ targetRoot/项目根」关系 + 点目录前缀翻译。
+// 通用点前缀翻译（2026-10-07 adopter-ci-github，由 .agents/ 特例泛化）：装户 rel 首段以 `.` 开头时探
+// templates/_<去点首段>/<余径>（.agents/notes/x → _agents/notes/x、.github/workflows/kit-ci.yml →
+// _github/…）——与 render.mjs relOf 的顶层 `_`→`.` 同一规则的逆向；无点前缀 rel（AGENTS.md / workflow/…）
+// 原样探 templates/<rel>。无对应模板返回 null（不参与感知）。
 export function srcTemplatePath(pkgRoot, rel) {
-  const tplRel = rel.startsWith('.agents/') ? `_agents/${rel.slice('.agents/'.length)}` : rel;
+  const first = rel.split('/')[0];
+  const tplRel = first.startsWith('.') ? `_${first.slice(1)}${rel.slice(first.length)}` : rel;
   const p = path.join(pkgRoot, 'templates', tplRel);
   return fs.existsSync(p) ? p : null;
 }

package/src/sync.mjs

@@ -1,7 +1,8 @@
 // flow-kit sync：按 .agents/kit.json 台账升级 managed 文件。
 // 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖；台账保持包侧基线，
 //       每次持续报告直至 --force 或本地对齐新版——防跳过一次后下次升级被静默覆盖，2026-09-24 语义修正）；
-//       生成器目标（INDEX.md / wiki 看板）→ 不比对，收尾重跑生成器走锚点重写。
+//       生成器目标（INDEX.md / wiki 看板）→ 不比对，生成器先于台账记账执行（2026-10-08 修 1：一次 sync
+//       自洽——生成器重写盘面后按终态记账），锚点内重写。
 // 附带：包内新增 managed 文件 → 安装；包内已删 → 仅报告不删盘、出台账；managed 缺失 → 恢复。
 // 台账外文件收养（2026-09-26 managed-ledger-adopt）：盘上存在但台账无该 rel 的 managed 类文件，
 //       若内容恰好等于新版渲染 sha（diskSha === fresh.sha）则收养登记——判据与台账内「改动恰好等于新版」
@@ -149,9 +150,35 @@ export function sync(args, pkgRoot) {
       console.log(`  无变化 ${unchanged} 份`);
     }
 
+    // 生成器目标走锚点重写（不参与 sha 比对）——执行前过供应链防线（init-p1-batch P1-3）：
+    // 目标侧脚本与包源渲染值 sha 一致才执行（预置/被改动的脚本不可信，跳过并显式提示）。
+    // 先于台账记账执行（2026-10-08 papercuts-cleanup-batch 修 1）：生成器会重写 owned 生成目标
+    // （INDEX/看板），记账段按生成后盘面收口——一次 sync 自洽，不再出现「wiki 变更后需二次 sync 自愈」。
+    const genGuard = (rel) => {
+      const g = scriptTrusted({ pkgRoot, target, rel, vars });
+      if (!g.ok) {
+        console.log(`  ⚠️ 跳过执行 ${rel}——${g.note}（供应链防线：只执行与包源渲染值一致的目标侧脚本）`);
+        return false;
+      }
+      return true;
+    };
+    if (genGuard('.agents/scripts/gen-workflow-index.mjs')) {
+      const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
+      if (genIndex.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-workflow-index.mjs'))) {
+        console.log(genIndex.ok ? '  已重生成 workflow/INDEX.md（锚点内重写）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
+      }
+    }
+    if (genGuard('.agents/scripts/gen-wiki-board.mjs')) {
+      const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
+      if (genBoard.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
+        console.log(genBoard.ok ? '  已重生成 wiki 速览与看板 DATA（锚点内重写）' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+      }
+    }
+
     // owned 台账按盘面自愈：owned 归项目所有，哈希只是记账不是约束——手改后无须手工刷 kit.json
     // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）。
-    // sha 按 LF 归一记（与 doctor checkOwnedDrift 同口径，2026-09-27 gate-coverage：跨 checkout 字节稳定）
+    // sha 按 LF 归一记（与 doctor checkOwnedDrift 同口径，2026-09-27 gate-coverage：跨 checkout 字节稳定）。
+    // 位于生成器之后（2026-10-08 papercuts-cleanup-batch 修 1）：生成器重写盘面后按终态记账。
     const ownedSha = (p) => sha256(Buffer.from(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
     let ownedRefreshed = 0;
     if (Array.isArray(kit.owned)) {
@@ -188,33 +215,10 @@ export function sync(args, pkgRoot) {
       console.log('    owned 归项目所有，不自动覆盖；如需跟随：从包源 templates/ 拷贝对应文件；有意定制可忽略（下次 sync 起静默）');
     }
 
-    // 台账重写：版本对齐当前包；removed 出册；skipped 保持包侧基线持续报告
+    // 台账重写（生成器之后）：版本对齐当前包；removed 出册；skipped 保持包侧基线持续报告
     kit.managed = managedNew.sort((a, b) => a.rel.localeCompare(b.rel));
     kit.version = pkg.version;
     fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
-
-    // 生成器目标走锚点重写（不参与 sha 比对）——执行前过供应链防线（init-p1-batch P1-3）：
-    // 目标侧脚本与包源渲染值 sha 一致才执行（预置/被改动的脚本不可信，跳过并显式提示）
-    const genGuard = (rel) => {
-      const g = scriptTrusted({ pkgRoot, target, rel, vars });
-      if (!g.ok) {
-        console.log(`  ⚠️ 跳过执行 ${rel}——${g.note}（供应链防线：只执行与包源渲染值一致的目标侧脚本）`);
-        return false;
-      }
-      return true;
-    };
-    if (genGuard('.agents/scripts/gen-workflow-index.mjs')) {
-      const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
-      if (genIndex.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-workflow-index.mjs'))) {
-        console.log(genIndex.ok ? '  已重生成 workflow/INDEX.md（锚点内重写）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
-      }
-    }
-    if (genGuard('.agents/scripts/gen-wiki-board.mjs')) {
-      const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
-      if (genBoard.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
-        console.log(genBoard.ok ? '  已重生成 wiki 速览与看板 DATA（锚点内重写）' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
-      }
-    }
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }

package/src/sync.test.mjs

@@ -366,5 +366,87 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S15⑥ .agents/ 前缀翻译 → _agents 模板参与感知出账', (r7.stdout + r7.stderr).includes('有演进且盘面未跟随') && (r7.stdout + r7.stderr).includes('.agents/rule-budgets.txt'));
 }
 
+// ============ 场景 16：装户 GitHub CI 远端门模板（2026-10-07 adopter-ci-github）============
+// 包源 templates/_github/workflows/kit-ci.yml → 装户 .github/workflows/kit-ci.yml（owned）：
+// ① isOwned / srcTemplatePath 契约（含 .agents 存量不回归、无模板反例）；
+// ② 存量装户盘上无该件 → newOwned 提示且不自动落盘；③ 已装 + 源演进 → 感知出账 + 锚刷新 + 再跑静默
+{
+  const sha = (s) => sha256(Buffer.from(s, 'utf8'));
+  const CI_REL = '.github/workflows/kit-ci.yml';
+  const CI_TPL = 'ci v2\n';
+  const { isOwned, srcTemplatePath } = await import(pathToFileURL(path.join(SRC_ROOT, 'profiles.mjs')).href);
+
+  // ① 契约断言：.github/ 归 owned；点前缀翻译 .github ↔ _github 命中、.agents 严格不回归、无模板 null
+  check('S16① isOwned：.github/ 前缀归 owned + 存量正例不回归（spec 验收 1）',
+    isOwned(CI_REL) === true && isOwned('.github/other.yml') === true
+    && isOwned('AGENTS.md') === true && isOwned('.agents/notes/x.md') === true && isOwned('workflow/plans/a.md') === true
+    && isOwned('.agents/scripts/check-loop.mjs') === false);
+  const fxC = mkFixture();
+  W(path.join(fxC, 'templates/_github/workflows/kit-ci.yml'), CI_TPL);
+  const norm = (p) => p.split(path.sep).join('/');
+  check('S16① srcTemplatePath 通用点前缀翻译：.github → _github 命中 / .agents 严格不回归',
+    norm(srcTemplatePath(fxC, CI_REL)).endsWith('templates/_github/workflows/kit-ci.yml')
+    && norm(srcTemplatePath(fxC, '.agents/scripts/keep.txt')).endsWith('templates/_agents/scripts/keep.txt'),
+    JSON.stringify({ ci: srcTemplatePath(fxC, CI_REL), agents: srcTemplatePath(fxC, '.agents/scripts/keep.txt') }));
+  check('S16① srcTemplatePath 无对应模板 → null（.gitattributes 反例，与旧实现等价）',
+    srcTemplatePath(fxC, '.gitattributes') === null);
+
+  // ② 存量装户（盘上无该件）→ newOwned 提示且不自动落盘
+  const fx1 = mkFixture();
+  W(path.join(fx1, 'templates/_github/workflows/kit-ci.yml'), CI_TPL);
+  const t1 = mkTarget(fx1);
+  const r1 = runCmd('sync', fx1, t1);
+  const out1 = r1.stdout + r1.stderr;
+  check('S16② 存量装户无该件 → newOwned 提示含文件名且不自动落盘',
+    out1.includes('新增 owned 起步文档') && out1.includes(CI_REL) && !fs.existsSync(path.join(t1, CI_REL)), out1);
+
+  // ③ 装户已装（带旧锚）+ 源演进 → 感知出账；锚刷新后（custom-synced）再跑静默
+  const fx2 = mkFixture();
+  W(path.join(fx2, 'templates/_github/workflows/kit-ci.yml'), CI_TPL);
+  const t2 = mkTarget(fx2);
+  W(path.join(t2, CI_REL), 'ci CUSTOM\n');
+  W(path.join(t2, '.agents/kit.json'), `${JSON.stringify({
+    kit: 'agentic-flow-kit', version: '1.0.0', createdAt: '2026-09-23T00:00:00Z',
+    options: { hosts: ['zcode'], stack: 'none', boardPort: '777' },
+    managed: [{ rel: '.agents/scripts/keep.txt', sha256: sha('keep v2\n') }],
+    owned: [{ rel: CI_REL, sha256: sha('ci CUSTOM\n'), srcSha256: sha('ci v1\n') }],
+  }, null, 2)}\n`);
+  const r2 = runCmd('sync', fx2, t2);
+  const out2 = r2.stdout + r2.stderr;
+  check('S16③ 源演进未跟随 → 感知出账含 .github rel', out2.includes('有演进且盘面未跟随') && out2.includes(CI_REL), out2.slice(0, 300));
+  check('S16③ 装户定制不被覆盖（盘面仍 CUSTOM）', R(path.join(t2, CI_REL)) === 'ci CUSTOM\n', out2);
+  const kit2 = JSON.parse(R(path.join(t2, '.agents/kit.json')));
+  check('S16③ 锚刷新为当前包源 sha', kit2.owned.find((f) => f.rel === CI_REL).srcSha256 === sha(CI_TPL), JSON.stringify(kit2.owned));
+  const r2b = runCmd('sync', fx2, t2);
+  check('S16③ 锚已刷（custom-synced）→ 再跑静默', !(r2b.stdout + r2b.stderr).includes('有演进且盘面未跟随'));
+}
+
+// ============ 场景 17：sync 一次自洽——生成器重写 owned 目标后按终态记账（2026-10-08 papercuts-cleanup-batch 修 1）============
+// 修前：记账段（owned 自愈/感知/台账重写）先于生成器执行 → 生成器重写 wiki 类 owned 目标后台账停旧值
+// → doctor §6.6 owned 漂移 FAIL 一次，需二次 sync 自愈。修后：生成器先跑，记账按生成后盘面收口。
+{
+  const sha = (s) => sha256(Buffer.from(s, 'utf8'));
+  const GEN = "import fs from 'node:fs';\nfs.writeFileSync('wiki/INDEX.md', 'generated v2\\n');\n";
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/scripts/gen-wiki-board.mjs'), GEN);
+  const t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/gen-wiki-board.mjs'), GEN); // 目标侧与包源渲染一致（genGuard/scriptTrusted 放行）
+  W(path.join(t, 'wiki/INDEX.md'), 'generated v1\n');    // 盘面停旧版——生成器将重写它
+  const k0 = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  k0.managed.push({ rel: '.agents/scripts/gen-wiki-board.mjs', sha256: sha(GEN) });
+  k0.owned.push({ rel: 'wiki/INDEX.md', sha256: sha('generated v1\n') });
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify(k0, null, 2)}\n`);
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S17 一次 sync：生成器重写后 owned 台账按终态记账（wiki/INDEX.md → v2 sha）',
+    JSON.parse(R(path.join(t, '.agents/kit.json'))).owned.find((f) => f.rel === 'wiki/INDEX.md').sha256 === sha('generated v2\n'),
+    JSON.stringify(JSON.parse(R(path.join(t, '.agents/kit.json'))).owned) + out.slice(0, 300));
+  const { checkOwnedDrift } = await import(pathToFileURL(path.join(SRC_ROOT, 'doctor.mjs')).href);
+  const d = checkOwnedDrift(t);
+  check('S17 一次 sync 后 doctor owned 零漂移（修前必漂移需二次 sync）', d.drift === 0 && d.gone.length === 0, JSON.stringify(d));
+  const r2 = runCmd('sync', fx, t);
+  check('S17 二次 sync 幂等（无 owned 刷新报告）', !(r2.stdout + r2.stderr).includes('owned 台账哈希按盘面刷新'), r2.stdout + r2.stderr);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/templates/AGENTS.md

@@ -24,6 +24,7 @@
 ### 门禁与提交
 
 - `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / 泳道完整性 / wiki 台账 / 规则面预算 / 双源一致性 / managed 台账快检 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
+- **CI 远端门（2026-10-07 起）**：`.github/workflows/kit-ci.yml`（owned）在 GitHub runner 复跑 `node .agents/scripts/verify.mjs`（云端兜底本地钩子）；非 GitHub 装户可删，等价门 = 同入口命令 + 服务端分支策略（人工一次性配置，机器不校验）。
 - **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
 - 项目专属门禁挂 `.agents/hooks/local-pre-commit`。装户五条硬规则（配对、验收、确认留痕、敏感信息、双源台账）与 `audit` 档见 `workflow/README.md`「硬规则」。
 - 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）。L1+ 三段式闭环链：`docs(*)` approved 留痕 → 代码 → 关单 `docs(*)`，相邻提交即同一闭环（2026-10-04 修订）。

package/templates/_agents/rule-budgets.txt

@@ -5,6 +5,8 @@
 # 口径：预算比较用「索引 / HEAD 字节」（git cat-file，LF 归一）；禁用工作区 wc -c 核对（CRLF 膨胀）。
 # 2026-10-06 backflow-loop-audit-remediation：6 份命令文档顶部加「装户边界」标注（build.md 实测 8386B
 # 超 8192 被拦）——单篇上限 8192→8704（与装户 Shipyard.Material 同值，512B 步进）；目录合计未超不动。
-AGENTS.md 7680
+# 2026-10-07 adopter-ci-github：AGENTS.md 门禁节补 CI 远端门一行（299B，实测 7969B 超 7680 被拦）——
+# 新门入册属合法增长，同 512B 步进上调 7680→8192。
+AGENTS.md 8192
 .agents/commands/*.md 8704
 .agents/commands/ 65536

package/templates/_agents/scripts/agg-delegations.cjs

@@ -41,6 +41,9 @@ function parseResult(raw) {
 
 // splitTables：按表头签名识别两张结果表——节标题只服务人类阅读，表头才是数据边界
 // （2026-09-24 修复：曾按 `## 委派结果` 节标题定位，节结构漂移时已有记录被静默读成「台账为空」）
+// ⚠️ 互引（2026-10-08 papercuts-cleanup-batch 修 2）：check-loop.mjs delegationResultRows 已对齐本签名
+// 口径（委派表头=含「被委派方」列 / 自做表头=首列「日期」且含「任务一句话」列）——一边改另一边须跟；
+// 差异保留：本函数按「连续 | 行」断表（聚合需分行归属），check-loop 按「## 节」终止收集（对账只需并集）
 function splitTables(text) {
   const tables = { delegated: [], self: [] };
   let cur = null;
@@ -54,9 +57,15 @@ function splitTables(text) {
   return tables;
 }
 
-function readLedger() {
-  if (!fs.existsSync(LEDGER)) fail(`找不到 ${LEDGER}`);
-  const text = fs.readFileSync(LEDGER, 'utf8');
+// readLedger：root 显式参数 + soft 模式（2026-10-08 workflow-dashboard 使能导出，判据单源复用——
+// 仪表盘 require 本函数取行，不重写表解析；缺省 root/无 soft 行为与原签名完全一致，main() 零变化）
+function readLedger(root = ROOT, opts = {}) {
+  const ledger = path.join(root, 'workflow', 'delegations.md');
+  if (!fs.existsSync(ledger)) {
+    if (opts.soft) return [];
+    fail(`找不到 ${ledger}`);
+  }
+  const text = fs.readFileSync(ledger, 'utf8');
   const tables = splitTables(text);
   const delegated = parseTableRows(tables.delegated.join('\n')).map((c) => ({
     scope: '委派',
@@ -73,7 +82,8 @@ function readLedger() {
   const rows = delegated.concat(selfDone);
   // 零数据行时区分「台账真空」与「结构漂移」：有日期开头的数据行却识别不到表 → fail-loud，不再静默「台账为空」
   if (!rows.length && /^\s*\|\s*\d{4}-\d{2}-\d{2}\s*\|/m.test(text)) {
-    fail(`台账结构漂移：${LEDGER} 存在日期开头的数据行但未识别到结果表（委派表表头须含「被委派方」列，自做表表头须为「日期 | 任务一句话 | 结果 | 备注」）`);
+    if (opts.soft) return [];
+    fail(`台账结构漂移：${ledger} 存在日期开头的数据行但未识别到结果表（委派表表头须含「被委派方」列，自做表表头须为「日期 | 任务一句话 | 结果 | 备注」）`);
   }
   return rows;
 }
@@ -197,5 +207,5 @@ function main() {
 if (require.main === module) {
   main();
 } else {
-  module.exports = { parseResult, metrics, gateMonth, expansionVerdict, GATE };
+  module.exports = { parseResult, metrics, gateMonth, expansionVerdict, GATE, readLedger };
 }

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

@@ -4,49 +4,93 @@
 // 随常规提交静默落 main，三次真实发生（0272a1c 预入 / ff3c721 还原窗口 / 537df18 闭合），本脚本在
 // 提交时刻补齐第三边。sha 口径：LF 归一 utf8（同 doctor §4 / render.mjs shaText / source-sync-check
 // 读取侧，跨 checkout 稳定；装户自包含约束决定独立实现，三处口径改动须同批）。
+// 入库态口径（2026-10-08 papercuts-cleanup-batch 修 5，独立复核 P1 修正取值链）：快检原比「工作树」，
+// 而分批提交时提交树（= HEAD + 暂存合成，删除同样被应用）里的 kit.json sha 可能指向「工作区已改、
+// 未提交」内容 → clone/CI 跑 doctor 必红（e8445c5 实证 6 项不符）。无参运行自适应：**暂存区非空即
+// 入库态**（不判「提交集含 kit.json」——diff --cached 只列与 HEAD 有差异的文件，kit.json 无变化暂存
+// 时不出现，但其合成提交树同样可能预 landing：只 add 件不 add 台账是姊妹漏洞）。入库态取值：
+// 台账清单 = 暂存版 kit.json（`git show :.agents/kit.json`）；暂存无而 HEAD 有 = 退出性提交（kit.json
+// 被暂存删除）放行；managed 内容 = `git show :rel` 暂存版，**暂存无即 gone**（提交树=index——
+// 未暂存改动的文件 index 仍在，`:rel` 必命中；`:rel` 缺失唯一可达路径是暂存删除，HEAD 兜底会把它
+// 误读为「未触碰」放行 = 提交门绕过，复核 P1 实证）。
+// 暂存区空（amend 等罕见态）→ 维持工作树口径零变化。
 // 边界：仅包源环境由 .githooks/pre-commit 触发（装户 managed 手改走 doctor §4 WARN 口径，不硬拦）；
 //       managed 删除即拦——sync 对 removed 只报不删，删件须手动同步装副本并重跑 sync 刷台账。
-// 用法：node .agents/scripts/check-ledger.mjs（cwd = 仓库根；非零出口即阻断提交）
-//       单元测试：import { ledgerDrift } from './check-ledger.mjs'
+// 用法：node .agents/scripts/check-ledger.mjs（cwd = 仓库根；非零出口即阻断提交；无参自适应两口径）
+//       单元测试：import { ledgerDrift } from './check-ledger.mjs'（{staged:true} 显式入库态）
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 
-export function ledgerDrift(target = process.cwd()) {
+const gitText = (target, args) => {
+  const r = spawnSync('git', args, { cwd: target, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout : null;
+};
+
+export function ledgerDrift(target = process.cwd(), { staged = false } = {}) {
   const kitPath = path.join(target, '.agents', 'kit.json');
   if (!fs.existsSync(kitPath)) return { skipped: true, note: '无 .agents/kit.json（非 flow-kit 安装）' };
-  let kit;
-  try {
-    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  } catch (e) {
-    return { skipped: false, fatal: `kit.json 解析失败：${e.message}`, modified: [], gone: [], total: 0, version: '?' };
+  // staged 模式：台账清单取暂存版 kit.json（提交树=index 合成语义）；暂存无而 HEAD 有 = 退出性提交
+  // （kit.json 被暂存删除）放行；两者皆无（新仓无 kit.json）同样放行
+  let kit = null;
+  if (staged) {
+    const stagedKit = gitText(target, ['show', ':.agents/kit.json']);
+    const headKit = stagedKit === null ? gitText(target, ['show', 'HEAD:.agents/kit.json']) : null;
+    if (stagedKit === null) {
+      return { skipped: true, note: headKit !== null ? '提交树无 .agents/kit.json（退出 flow-kit 的提交），跳过' : '提交树无 .agents/kit.json（新仓），跳过', mode: 'staged' };
+    }
+    try {
+      kit = JSON.parse(stagedKit);
+    } catch (e) {
+      return { skipped: false, fatal: `kit.json（暂存版）解析失败：${e.message}`, modified: [], gone: [], total: 0, version: '?', mode: 'staged' };
+    }
+  }
+  if (!kit) {
+    try {
+      kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+    } catch (e) {
+      return { skipped: false, fatal: `kit.json 解析失败：${e.message}`, modified: [], gone: [], total: 0, version: '?', mode: staged ? 'staged' : 'worktree' };
+    }
   }
   if (!Array.isArray(kit.managed)) {
     // fail-loud（独立复核 P2-3，2026-09-28）：JSON 合法但 managed 缺失/非数组时静默「全对齐」= 假放，
     // 同 doctor §4 的 Array.isArray 显式判口径，台账结构坏了必须响
-    return { skipped: false, fatal: 'kit.json managed 缺失或非数组', modified: [], gone: [], total: 0, version: kit.version };
+    return { skipped: false, fatal: 'kit.json managed 缺失或非数组', modified: [], gone: [], total: 0, version: kit.version, mode: staged ? 'staged' : 'worktree' };
   }
   const modified = [];
   const gone = [];
   const managed = kit.managed;
   for (const f of managed) {
-    const p = path.join(target, f.rel);
-    if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
-    const h = createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex'); // LF 归一，同 doctor §4
+    let content = null;
+    if (staged) {
+      // 入库态：提交树 = index（暂存版）；`:rel` 缺失唯一可达路径是暂存删除 → gone 拦（复核 P1：
+      // HEAD 兜底会把暂存删除误读为「未触碰」放行——提交树已无该件而台账仍跟踪，clone/CI 必红）
+      content = gitText(target, ['show', `:${f.rel}`]);
+      if (content === null) { gone.push(f.rel); continue; }
+    } else {
+      const p = path.join(target, f.rel);
+      if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
+      content = fs.readFileSync(p, 'utf8');
+    }
+    const h = createHash('sha256').update(content.replace(/\r\n/g, '\n'), 'utf8').digest('hex'); // LF 归一，同 doctor §4
     if (h !== f.sha256) modified.push(f.rel);
   }
-  return { skipped: false, fatal: '', modified, gone, total: managed.length, version: kit.version };
+  return { skipped: false, fatal: '', modified, gone, total: managed.length, version: kit.version, mode: staged ? 'staged' : 'worktree' };
 }
 
 const isMain = process.argv[1] && process.argv[1].endsWith('check-ledger.mjs');
 if (isMain) {
-  const r = ledgerDrift();
+  // 无参自适应：暂存区非空（有提交发生）→ 入库态口径；暂存区空（amend 等罕见态/非 git 仓）→ 工作树口径
+  const cached = gitText(process.cwd(), ['diff', '--cached', '--name-only']) || '';
+  const staged = cached.split(/\r?\n/).some((l) => l.trim() !== '');
+  const r = ledgerDrift(process.cwd(), { staged });
   console.log('▶ flow-kit check-ledger');
   if (r.skipped) {
     console.log('  ' + r.note + '，跳过 ✅');
     process.exit(0);
   }
-  console.log('  kit.json v' + r.version + '：managed ' + r.total + ' 份，台账 ↔ 盘面（工作树，LF 归一）');
+  console.log('  kit.json v' + r.version + '：managed ' + r.total + ' 份，台账 ↔ ' + (r.mode === 'staged' ? '提交树入库态（暂存版=index，暂存删除即拦，LF 归一）' : '盘面（工作树，LF 归一）'));
   if (r.fatal) console.error('❌ ' + r.fatal);
   if (r.modified.length) {
     console.error('  台账漂移（盘面 ≠ 台账 sha）' + r.modified.length + '：');
@@ -57,7 +101,7 @@ if (isMain) {
     for (const rel of r.gone) console.error('    - ' + rel);
   }
   if (r.fatal || r.modified.length || r.gone.length) {
-    console.error('  提交被拦：kit.json 与盘面不一致（预 landing / 手改未随动）——跑 node bin/flow-kit.mjs sync 成对后原路重试');
+    console.error('  提交被拦：kit.json 与' + (r.mode === 'staged' ? '提交树（暂存面）' : '盘面') + '不一致（预 landing / 手改未随动）——跑 node bin/flow-kit.mjs sync 成对后原路重试');
     process.exit(1);
   }
   console.log('  全对齐 ✅');

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

@@ -123,5 +123,75 @@ const runCli = (cwd) => spawnSync(process.execPath, [SCRIPT], { encoding: 'utf8'
   }
 }
 
+// ---- S10 入库态口径（2026-10-08 papercuts-cleanup-batch 修 5）：git 仓 fixture，分批提交场景 ----
+// 核心场景（papercuts 2026-09-30 行）：sync 刷新 kit.json 后只 add 台账不 add 件 → 提交树内 kit.json
+// 预 landing → 修前工作树口径「全对齐」放行（假绿），clone/CI doctor 必红；修后入库态模式拦。
+{
+  const GIT = process.platform === 'win32' ? 'git.exe' : 'git';
+  const g = (cwd, ...args) => spawnSync(GIT, args, { cwd, encoding: 'utf8' });
+  const W2 = (root, rel, content) => {
+    fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), content);
+  };
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-cl-git-'));
+  g(repo, 'init', '-q');
+  g(repo, 'config', 'user.email', 't@t');
+  g(repo, 'config', 'user.name', 't');
+  g(repo, 'config', 'core.autocrlf', 'false');
+  const kitOf = (aSha) => JSON.stringify({
+    kit: 't', version: '0.0.0-test',
+    managed: [{ rel: '.agents/scripts/a.mjs', sha256: aSha }],
+  }) + '\n';
+  W2(repo, '.agents/scripts/a.mjs', 'A v1\n');
+  W2(repo, '.agents/kit.json', kitOf(lfSha('A v1\n')));
+  g(repo, 'add', '-A');
+  g(repo, 'commit', '-q', '-m', 'v1');
+  // sync 模拟：件与台账同刷 v2（工作区自洽，均未提交）
+  W2(repo, '.agents/scripts/a.mjs', 'A v2\n');
+  W2(repo, '.agents/kit.json', kitOf(lfSha('A v2\n')));
+
+  // S10① 只 add kit.json（分批提交）→ 暂存台账(v2) vs 入库件(HEAD v1) → 拦
+  g(repo, 'add', '.agents/kit.json');
+  const r1 = ledgerDrift(repo, { staged: true });
+  check('S10① 入库态：台账(v2 暂存) vs 件(HEAD v1) → 拦（修前工作树口径假绿放行）',
+    r1.mode === 'staged' && r1.modified.includes('.agents/scripts/a.mjs'), JSON.stringify(r1));
+  // S10② 件与台账同 add → 入库态一致 → 过
+  g(repo, 'add', '.agents/scripts/a.mjs');
+  const r2 = ledgerDrift(repo, { staged: true });
+  check('S10② 入库态：件与台账同 add → 一致过', r2.mode === 'staged' && !r2.modified.length && !r2.gone.length, JSON.stringify(r2));
+  g(repo, 'commit', '-q', '-m', 'v2 both');
+  // S10③ 工作树删件未暂存 → index 仍有该件（`:rel` 命中 HEAD 内容）→ 不误报 gone（复核 P1 修后语义：
+  // HEAD 兜底已移除，判定路径 = `:rel` 命中而非兜底）
+  fs.rmSync(path.join(repo, '.agents/scripts/a.mjs'));
+  const r3 = ledgerDrift(repo, { staged: true });
+  check('S10③ 入库态：工作树删件未暂存 → index 仍在，不误报', !r3.gone.length && !r3.modified.length, JSON.stringify(r3));
+  // S10④ 暂存删除（git rm）→ 提交树已无该件而台账仍跟踪 → gone 拦（复核 P1：HEAD 兜底曾把它误读
+  // 为「未触碰」放行 = 提交门绕过；修后与模块头「managed 删除即拦」政策一致）
+  g(repo, 'rm', '-q', '--cached', '.agents/scripts/a.mjs');
+  const r4 = ledgerDrift(repo, { staged: true });
+  check('S10④ 入库态：暂存删除 → gone 拦（提交树=index，删除被应用）', r4.gone.includes('.agents/scripts/a.mjs'), JSON.stringify(r4));
+  // S10④b 退出性提交：kit.json 被暂存删除 → 放行（skip，语义与 managed 删除拦截区分）
+  g(repo, 'rm', '-q', '--cached', '.agents/kit.json');
+  const r4b = ledgerDrift(repo, { staged: true });
+  check('S10④b 入库态：kit.json 暂存删除（退出性提交）→ skip 放行', r4b.skipped === true, JSON.stringify(r4b));
+  g(repo, 'reset', '-q', '--hard', 'HEAD'); // 复原（防脏）
+
+  // S10⑤ isMain 无参自适应（子进程）：暂存区空 → 「工作树」；暂存区非空 → 自动「入库态」
+  g(repo, 'reset', '-q', '--hard', 'HEAD'); // 清掉 ④ 的暂存删除，回到干净 v2 both
+  const s1 = runCli(repo); // 暂存区空 → 工作树口径
+  check('S10⑤ 暂存区空 → 工作树口径', s1.status === 0 && (s1.stdout || '').includes('工作树'), `out=${s1.stdout}`);
+  W2(repo, 'unrelated.txt', 'x\n');
+  g(repo, 'add', 'unrelated.txt'); // 暂存非空（无关文件即可）→ 自动入库态；kit.json 未暂存走 HEAD 兜底
+  const s2 = runCli(repo);
+  check('S10⑤ 暂存区非空 → 自动切入库态且一致 exit 0',
+    s2.status === 0 && (s2.stdout || '').includes('入库态'), `status=${s2.status} out=${s2.stdout}`);
+  // S10⑥ 姊妹漏洞（完备口径价值场景）：只 add 件不 add 台账 → 提交树 = HEAD 台账(v1? v2) + 暂存件 → 错位拦
+  W2(repo, '.agents/scripts/a.mjs', 'A v3\n');
+  g(repo, 'add', '.agents/scripts/a.mjs');
+  const s3 = runCli(repo);
+  check('S10⑥ 只 add 件不 add 台账 → 入库态错位拦 exit 1', s3.status === 1 && (s3.stderr || '').includes('.agents/scripts/a.mjs'), `status=${s3.status} err=${s3.stderr}`);
+  fs.rmSync(repo, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/check-loop-unit.test.mjs

@@ -0,0 +1,95 @@
+// check-loop-unit.test.mjs — check-loop 零件直测（2026-10-08 checkloop-importable）
+// papercuts 2026-10-04 isMain 行的兑现：check-loop.mjs 自 isMain 主守卫 + runCheckLoop 接缝后可 import——
+// 本套件全部进程内直测（不 spawn），与 check-loop.test.mjs（端到端 spawn，行为回归网）互补。
+// 覆盖：①runCheckLoop({root}) 三态（干净 exit 0 / 构造 blocker exit 1 且数组带内容 / rev+root 互斥）；
+//       ②四纯零件：delegationResultRows 表头签名（节标题漂移仍解析）、versionGreater 边界、
+//         fmStatus 形态、bindingSha256 prev 复原与「确认指纹」剔除对称。
+// 用法：node templates/_agents/scripts/check-loop-unit.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const { runCheckLoop, delegationResultRows, versionGreater, fmStatus, bindingSha256 } =
+  await import(pathToFileURL(path.join(SCRIPT_DIR, 'check-loop.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+};
+const W = (root, rel, content) => { fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true }); fs.writeFileSync(path.join(root, rel), content); };
+
+// ---- ① runCheckLoop 进程内直测 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cl-unit-'));
+  W(root, '.agents/workflow-enums.txt', fs.readFileSync(path.join(SCRIPT_DIR, '..', 'workflow-enums.txt'), 'utf8'));
+  let r = runCheckLoop({ root });
+  check('run：干净 fixture → exit 0（blockers/warnings 均数组）',
+    r.exitCode === 0 && Array.isArray(r.blockers) && Array.isArray(r.warnings) && r.blockers.length === 0,
+    `exit=${r.exitCode} b=${r.blockers.length}`);
+  // 构造 blocker：L2 done intent 缺 spec 配对（配对断裂 hard）
+  W(root, 'workflow/intents/2026-10-08-x.md', '---\n状态: done\n级别: L2\n日期: 2026-10-08\n模块: pipeline\n---\n# x\n');
+  r = runCheckLoop({ root });
+  check('run：构造 L2 缺配对 → exit 1 且 blockers 数组带内容',
+    r.exitCode === 1 && r.blockers.length > 0 && r.blockers[0].includes('配对断裂'),
+    `exit=${r.exitCode} b=${JSON.stringify(r.blockers).slice(0, 80)}`);
+  // rev+root 互斥（root 参数通道）
+  const r2 = runCheckLoop({ root, rev: 'abc1234' });
+  check('run：rev+root 互斥 → exit 1（报错走 stderr，返回空数组判决）', r2.exitCode === 1, `exit=${r2.exitCode}`);
+  // root 不可访问 → exit 1（不抛异常）
+  const r3 = runCheckLoop({ root: path.join(root, '不存在目录') });
+  check('run：root 不可访问 → exit 1（同款报错语义）', r3.exitCode === 1, `exit=${r3.exitCode}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- ② delegationResultRows：表头签名识别（零件级直测）----
+{
+  const f = path.join(os.tmpdir(), `cl-unit-${Date.now()}-delegations.md`);
+  // 节标题漂移（「委派结果表」≠精确节名）而表头不动 → 仍解析（papercuts-cleanup-batch 修 2 语义）
+  fs.writeFileSync(f, '## 委派结果表\n\n| 日期 | 被委派方 | 任务一句话 | 结果 | 备注 |\n|---|---|---|---|---|\n| 2026-10-01 | x | y | 一次通过 | z |\n\n## 自做台账\n\n| 日期 | 任务一句话 | 结果 | 备注 |\n|---|---|---|---|\n| 2026-10-02 | p | 返工×2 | q |\n');
+  const rows = delegationResultRows(f);
+  check('零件 delegationResultRows：节标题漂移仍按表头签名解析（委派 1 + 自做 1）',
+    rows.length === 2 && rows[0].date === '2026-10-01' && rows[1].date === '2026-10-02' && rows[1].line.includes('返工×2'),
+    JSON.stringify(rows));
+  check('零件 delegationResultRows：文件不存在 → 空数组不抛', delegationResultRows(path.join(os.tmpdir(), 'cl-unit-nope.md')).length === 0);
+  fs.rmSync(f, { force: true });
+}
+
+// ---- ③ versionGreater 边界 ----
+{
+  check('零件 versionGreater：1.2.3>1.2.2 / 1.10.0>1.9.9 / 相等 false / 非法 false',
+    versionGreater('1.2.3', '1.2.2') === true
+    && versionGreater('1.10.0', '1.9.9') === true
+    && versionGreater('1.2.3', '1.2.3') === false
+    && versionGreater('abc', '1.0.0') === false);
+}
+
+// ---- ④ fmStatus 形态 ----
+{
+  check('零件 fmStatus：标准/双空格/CRLF/无 frontmatter',
+    fmStatus('---\n状态: done\n级别: L1\n---\n# x') === 'done'
+    && fmStatus('---\r\n状态:  approved\r\n---\r\n# x') === 'approved'
+    && fmStatus('# 无 frontmatter') === '');
+}
+
+// ---- ⑤ bindingSha256：prev 复原与「确认指纹」剔除对称 ----
+{
+  // 前向：approved 落态全文算指纹（confirm-doc computeFingerprint 口径：CRLF 归一→剔指纹行→sha256）
+  const fpOf = (text) => createHash('sha256')
+    .update(text.replace(/\r\n/g, '\n').split('\n').filter((l) => !/^确认指纹:/.test(l)).join('\n'), 'utf8').digest('hex');
+  const approved = '---\n状态: approved\n级别: L2\n日期: 2026-10-08\n模块: pipeline\n确认指纹: ab12cd34ef56ab12\n---\n# T\n\n## 验收标准（可测试）\n\n- [x] 用例（证据:a1b2c3d）\n';
+  const done = approved.replace('状态: approved', '状态: done');
+  // 逆推：done 行集（lines 已 CRLF 归一）+ prev='approved' → 应还原出与 approved 落态一致的指纹
+  const reversed = bindingSha256(done.replace(/\r\n/g, '\n').split('\n'), 'approved');
+  check('零件 bindingSha256：done 行集经 prev 复原重算 == approved 落态指纹（内容绑定对称性）',
+    reversed === fpOf(approved), `${reversed.slice(0, 12)} vs ${fpOf(approved).slice(0, 12)}`);
+  // prev 不同 → 指纹不同（判定不恒真）
+  check('零件 bindingSha256：prev 不同 → 复原指纹不同（判定不恒真）',
+    bindingSha256(done.replace(/\r\n/g, '\n').split('\n'), 'draft') !== reversed);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);