agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/workflows/pipeline-closing.md

@@ -1,6 +1,6 @@
 ---
 name: pipeline-closing
-description: 推广环节 6 阶段闭环——起草 intent + plan（双写）→ 用户对话内确认 → 按 plan 改动面实施 → 3 关静态门（source-sync-check / npm test / doctor）→ 关单留痕（intent + plan → done + docs commit）。可复用于本项目所有 L1 推广环节（新增工具 / 微改动 / 协议修补）
+description: 推广环节 6 阶段闭环——起草 intent + plan（双写）→ 用户对话内确认 → 按 plan 改动面实施 → 2 关静态门（npm test / doctor）→ 关单留痕（intent + plan → done + docs commit）。可复用于本项目所有 L1 推广环节（新增工具 / 微改动 / 协议修补）
 concurrency: 2
 ---
 # workflow — pipeline-closing（推广环节 6 阶段闭环）
@@ -13,14 +13,13 @@ concurrency: 2
 | gate-doc | author | — | — | — | — | — | node .agents/scripts/fill-intent.test.mjs && node .agents/scripts/fill-plan.test.mjs | | |
 | confirm | gate-doc | — | — | plan 草稿全文过目，用户对话内一句"可以" → plan 状态 draft → approved + 回填「确认与复核」节 | — | plan 状态 approved + 「确认结果：approved（YYYY-MM-DD 用户对话内确认）」 | | 用户确认（plan 确认门） | |
 | plan-commit | confirm | implementer | — | 提交 plan 立项 commit（docs(workflow)） | workflow/intents/, workflow/plans/, workflow/INDEX.md | pre-commit 钩子全过；commit message 含 plan 改动面摘要 | | | 0 |
-| build | plan-commit | implementer | — | 按 plan §改动面 执行（含双源纪律：包源改了装副本手动同步） | 见 plan | plan 改动面全部完成；双源文件 sha 一致 | | | 1 |
-| gate-sync | build | — | — | — | — | — | node .agents/scripts/source-sync-check.mjs --diff（必须 0 差异） | | |
+| build | plan-commit | implementer | — | 按 plan §改动面 执行 | 见 plan | plan 改动面全部完成 | | | 1 |
 | gate-test | build | — | — | — | — | — | npm test（必须全绿） | | |
 | gate-doctor | build | — | — | — | — | — | node bin/flow-kit.mjs doctor（必须 0 FAIL） | | |
-| feat-commit | gate-sync,gate-test,gate-doctor | implementer | — | 提交 feat commit（feat(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 build 改动面摘要 | | | 0 |
+| feat-commit | gate-test,gate-doctor | implementer | — | 提交 feat commit（feat(模块名)） | 工作区所有变更文件 | pre-commit 钩子全过；commit message 含 build 改动面摘要 | | | 0 |
 | closeout | feat-commit | implementer | — | 补 intent 8 条验收勾验 + plan → done + 关单 docs commit 留痕；同步 INDEX.md（如适用） | workflow/intents/<date>-<topic>.md, workflow/plans/<date>-<topic>.md, workflow/INDEX.md | intent + plan 状态均 done；8 条验收勾验含 commit SHA 证据；commit message 含关单 commit + 8 条勾验摘要 | | | 0 |
 
-**编排语义**：第 0 层 author → 第 1 层 gate-doc + confirm（confirm 为 human 确认门形态——宿主 AI 停下询问用户，不派子智能体；通过才派下层）→ 第 2 层 plan-commit → 第 3 层 build → 第 4 层 3 关静态门（并行 fan-out）→ 第 5 层 feat-commit → 第 6 层 closeout。失败且 retries > 0 → 重派（全新上下文）；gate 非零 / human 驳回 → 中止后续、汇总报告失败项。每个 stage 每次尝试出结果记 `wf-journal.mjs add`；中止续跑先 `wf-journal.mjs status --wf pipeline-closing`（已 pass 不重跑）。
+**编排语义**：第 0 层 author → 第 1 层 gate-doc + confirm（confirm 为 human 确认门形态——宿主 AI 停下询问用户，不派子智能体；通过才派下层）→ 第 2 层 plan-commit → 第 3 层 build → 第 4 层 2 关静态门（并行 fan-out）→ 第 5 层 feat-commit → 第 6 层 closeout。失败且 retries > 0 → 重派（全新上下文）；gate 非零 / human 驳回 → 中止后续、汇总报告失败项。每个 stage 每次尝试出结果记 `wf-journal.mjs add`；中止续跑先 `wf-journal.mjs status --wf pipeline-closing`（已 pass 不重跑）。
 
 **纪律**（先读）：
 - 声明随 plan 确认后方可执行——本 workflow 是 plan 任务拆解的执行器；plan 草稿先经用户对话内确认。

package/templates/_githooks/pre-commit

@@ -1,132 +1,121 @@
-#!/bin/sh
-# Git 原生 pre-commit hook（经 core.hooksPath 挂载，git 执行、不依赖 agent 客户端）— agentic-flow-kit 通用编排
-# 通用门禁序：闭环配对(增量) → 泳道完整性(增量) → wiki 台账(增量) → 常驻面体积预算(增量) → 双源一致性(增量) → managed 台账快检(包源恒跑) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
-# 项目专属门禁（架构红线/业务守卫等）放 .agents/hooks/local-pre-commit——存在即在本钩子内执行，返回非零即阻断提交
-# 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
-# 不是 pre-commit）——门禁清单只此一份，避免两处分叉
+#!/usr/bin/env node
+// Git 原生 pre-commit hook（经 core.hooksPath 挂载）— agentic-flow-kit 通用编排
+// 2026-10-13 门禁去 sh 化（B2，自 Shipyard.Material 参考实现回灌）：钩子体不再含 sh 逻辑——git 仍以自带
+// sh 启动本文件（钩子机制要求），但 shebang 即 node，PATH 无 sh 不再影响任何逻辑；语言单化后 CI 代理/
+// 本地行为一致。写法为 CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测。
+// 通用门禁序：闭环配对(增量) → 泳道完整性(增量) → wiki 台账(增量) → 索引漂移(增量) → 常驻面体积预算(增量) → 确认台账不变量(暂存触台账) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
+// 项目专属门禁（架构红线/业务守卫等）放 .agents/hooks/local-pre-commit——sh 挂载点（add-gate 生态按行接线），
+// 存在即在本钩子内以 sh（缺则 bash）执行，返回非零即阻断提交
+// 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
+// 不是 pre-commit）——门禁清单只此一份，避免两处分叉
+// fail-closed（沿 Shipyard 2026-10-09 口径；node 化后天然成立——本进程即 node）：门脚本缺失 = 拒提交；
+// 仅 local-pre-commit 保留「存在即执行」挂载点语义（缺失打 advisory）。
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
 
-cd "$(git rev-parse --show-toplevel)" || exit 1
-
-# run_gate <标签> <脚本> [参数...]：sh 优先、无 sh 用 bash；非零即阻断
-run_gate() {
-  gate_label="$1"; shift
-  if command -v sh >/dev/null 2>&1; then sh "$@"; else bash "$@"; fi
-  rc=$?
-  if [ $rc -ne 0 ]; then
-    echo "pre-commit: $gate_label 未通过，提交已阻止" >&2
-    exit $rc
-  fi
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-commit: 无法定位仓库根（git rev-parse --show-toplevel 失败）——提交已阻止');
+  process.exit(1);
 }
+process.chdir(top.stdout.trim());
 
-# 闭环配对门禁（增量版，check-pairing-incremental.sh：本次暂存的 intents/incidents 入口须已有同名 plan）
-# experiment/* 泳道分支（2026-09-30 hybrid-governance-explore-hardening）：降级为 advisory——快速 PoC
-# 迭代不因闭环文档断档被拦（断档报告照出），转正合入 main 由 pre-push 加固门（check-loop --hardening）兜底。
-# 仅降级闭环文档面：双源 / 台账 / 常驻面 / 敏感信息扫描等门禁不豁免。分支不可判（detached HEAD 等）走严格模式。
-pairing_gate_mode=strict
-case "$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" in
-  experiment/*) pairing_gate_mode=advisory ;;
-esac
-if [ "$pairing_gate_mode" = "advisory" ]; then
-  echo "pre-commit: experiment/* 泳道分支——闭环配对门禁降级为 advisory（报告不阻断；转正入 main 须过加固门）" >&2
-  if command -v sh >/dev/null 2>&1; then
-    sh .agents/hooks/check-pairing-incremental.sh || echo "pre-commit: （advisory）闭环配对断档已在上方列出——experiment 泳道不阻断提交" >&2
-  else
-    bash .agents/hooks/check-pairing-incremental.sh || echo "pre-commit: （advisory）闭环配对断档已在上方列出——experiment 泳道不阻断提交" >&2
-  fi
-else
-  run_gate "闭环配对（增量）" .agents/hooks/check-pairing-incremental.sh
-fi
-
-# 泳道完整性（增量，check-lane-surface.mjs——2026-10-01 drift-hardening）：
-#   检查 A「触达面判低」——暂存命中项目 L2 触达面（.agents/lane-surfaces.txt，ERE 逐行；缺失/空=跳过，
-#   装户无感）且活跃入口（draft/approved / open/fixed）全为 L0/L1 → 拦；有活跃 L2/L3 → 放行；无活跃入口 →
-#   仅 advisory（docs/bootstrap 豁免类）。experiment/* 分支降级 advisory（转正由 pre-push 加固门兜底）。
-#   检查 B「探索标记缺失」——experiment/* 分支暂存 intent 缺「阶段: exploring」→ 拦（标记零成本，
-#   advisory 免纪律不免标记——标记是加固门覆盖率的前提）。
-#   旧装副本无脚本自然跳过；node 缺失时本门跳过（其后 commit-check 节点检查仍会拦提交，无空洞）。
-#   注意：不经 run_gate（其实现为 sh "$@"，会把 node 当脚本解释——直接 node 调用，模式同双源门禁块）。
-if [ -f .agents/scripts/check-lane-surface.mjs ] && command -v node >/dev/null 2>&1; then
-  if ! node .agents/scripts/check-lane-surface.mjs; then
-    echo "pre-commit: 泳道完整性（增量）未通过，提交已阻止" >&2
-    exit 1
-  fi
-fi
+// gate(label, script, args)：node 直跑门脚本，非零即阻断（含 fail-closed 缺失检查）
+const requireScript = (rel) => {
+  if (!fs.existsSync(rel)) {
+    console.error(`pre-commit: 门脚本缺失 ${rel}——提交已阻止（脚本随包下发；flow-kit sync 恢复后重试）`);
+    process.exit(1);
+  }
+};
+const gate = (label, script, args = []) => {
+  requireScript(script);
+  const r = spawnSync(process.execPath, [script, ...args], { stdio: 'inherit' });
+  if (r.status !== 0) {
+    console.error(`pre-commit: ${label} 未通过，提交已阻止`);
+    process.exit(r.status === null ? 1 : r.status);
+  }
+};
 
-# wiki 台账门禁（增量，check-wiki-ledger.sh：暂存区触及 wiki/ 时跑 verify-wiki-consistency 三方一致性；
-# 无 wiki/ 变更即跳过）
-run_gate "wiki 台账（增量）" .agents/hooks/check-wiki-ledger.sh
+// 闭环配对门禁（增量版，check-pairing-incremental.mjs：本次暂存的 intents/incidents 入口须已有同名 plan；
+// L2/L3 另须同名 spec）。experiment/* 泳道分支（2026-09-30 hybrid-governance-explore-hardening）：
+// 降级为 advisory——快速 PoC 迭代不因闭环文档断档被拦（断档报告照出），转正合入 main 由 pre-push
+// 加固门（check-loop --hardening）兜底。仅降级闭环文档面：常驻面 / 台账 / 敏感信息扫描等门禁不豁免。
+// 分支不可判（detached HEAD 等）走严格模式。
+const branch = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { encoding: 'utf8' });
+const branchName = branch.status === 0 ? branch.stdout.trim() : '';
+if (branchName.startsWith('experiment/')) {
+  console.error('pre-commit: experiment/* 泳道分支——闭环配对门禁降级为 advisory（报告不阻断；转正入 main 须过加固门）');
+  const adv = spawnSync(process.execPath, ['.agents/hooks/check-pairing-incremental.mjs'], { stdio: 'inherit' });
+  if (adv.status !== 0) console.error('pre-commit: （advisory）闭环配对断档已在上方列出——experiment 泳道不阻断提交');
+} else {
+  gate('闭环配对（增量）', '.agents/hooks/check-pairing-incremental.mjs');
+}
 
-# 常驻面体积预算（增量硬拦，rule-budget.sh --staged：只查本次暂存触及的条目与触及目录的合计；
-# 超限即阻断——常驻面只增不减，须先删除或下沉一条被取代条目再增）
-if [ -f .agents/scripts/rule-budget.sh ] && [ -f .agents/rule-budgets.txt ]; then
-  run_gate "常驻面体积预算" .agents/scripts/rule-budget.sh --staged
-fi
+// 泳道完整性（增量，check-lane-surface.mjs——2026-10-01 drift-hardening）：
+//   检查 A「触达面判低」——暂存命中项目 L2 触达面（.agents/lane-surfaces.txt，ERE 逐行；缺失/空=跳过，
+//   装户无感）且活跃入口（draft/approved / open/fixed）全为 L0/L1 → 拦；有活跃 L2/L3 → 放行；无活跃入口 →
+//   仅 advisory（docs/bootstrap 豁免类）。experiment/* 分支降级 advisory（转正由 pre-push 加固门兜底）。
+//   检查 B「探索标记缺失」——experiment/* 分支暂存 intent 缺「阶段: exploring」→ 拦（标记零成本，
+//   advisory 免纪律不免标记——标记是加固门覆盖率的前提）。
+//   脚本缺失 fail-closed 阻断（见 gate()）。
+gate('泳道完整性（增量）', '.agents/scripts/check-lane-surface.mjs');
 
-# 双源一致性（增量，2026-09-27 audit-gate-hardening）：包源 templates/_agents/ 与装副本 .agents/ 须同提交成对。
-# 暂存触及任一侧时跑 source-sync-check --gate（缺失/漂移 exit 1，孤儿只报告）——拦「包源改了装副本没跟」
-# （doctor §4 台账 sha 对此静默：盘面=台账即 PASS；该故障模式曾两次真实发生，见 incidents/2026-09-25-wf-runtime）。
-# 比较工作树而非暂存区（口径沿 check-pairing-incremental 先例）：两侧都已改好、分两笔提交时不拦——最终一致即可。
-# 已知边界（复核 P2-2 声明，2026-09-27 gate-hardening-p2-batch）：包源删除文件不触发缺失/漂移——装副本残件
-# 退化为「孤儿」只报告不计失败，删包源时须手动同步清理装副本（sync 对 removed 同样仅报告不删盘）。
-# 装户环境（无 templates/_agents/ 包源）自然跳过。
-if [ -d templates/_agents ] && [ -f .agents/scripts/source-sync-check.mjs ] \
-  && git -c core.quotepath=off diff --cached --name-only | grep -qE '^(templates/_agents/|\.agents/)'; then
-  if ! node .agents/scripts/source-sync-check.mjs --gate; then
-    echo "pre-commit: 双源一致性（增量）未通过，提交已阻止——单边改动先跑 node bin/flow-kit.mjs sync 成对后原路重试" >&2
-    exit 1
-  fi
-fi
+// wiki 台账门禁（增量，check-wiki-ledger.mjs：暂存区触及 wiki/ 时跑 verify-wiki-consistency 三方一致性；
+// 无 wiki/ 变更即跳过。脚本缺失 fail-closed）
+gate('wiki 台账（增量）', '.agents/hooks/check-wiki-ledger.mjs');
 
-# managed 台账快检（包源环境恒跑，2026-09-28 ledger-precommit-gate；同日独立复核 P2-2 采纳）：
-# kit.json 台账 sha ↔ 盘面工作树（LF 归一，同 doctor §4 口径）——拦「台账 sha 预 landing」：台账记了
-# 盘面尚不存在的内容 sha。双源门禁对此静默（templates↔.agents 成对回退时两侧一致），doctor §4 只在
-# 手动全量跑——该故障模式三次真实发生（0272a1c 预入 / ff3c721 还原窗口 / 537df18 闭合），本块补齐
-# 提交时刻的第三边。恒跑不作暂存触发：预 landing 是仓态而非暂存态，暂存 grep 有前缀缝（如 .githooks/*
-# managed 件单边漂移不命中），毫秒级 80 份 hash 不构成开销理由。比较工作树而非暂存区（沿双源门禁
-# 口径）。装户环境（无 templates/_agents/ 包源）自然跳过——装户 managed 手改走 doctor §4 WARN 口径，
-# 不硬拦。已知边界：managed 删除即拦（sync 对 removed 只报不删，删件须手动同步装副本并重跑 sync 刷
-# 台账）。
-if [ -d templates/_agents ] && [ -f .agents/scripts/check-ledger.mjs ]; then
-  if ! node .agents/scripts/check-ledger.mjs; then
-    echo "pre-commit: managed 台账快检未通过，提交已阻止——kit.json 与盘面不一致，跑 node bin/flow-kit.mjs sync 成对后原路重试" >&2
-    exit 1
-  fi
-fi
+// 索引漂移（增量硬拦，check-index-incremental.mjs）：暂存触及 workflow 四目录 / 归档 / INDEX.md 时，
+// gen-workflow-index.mjs --check 不一致即拒。卫生段检查 11 仍是 WARN，挡不住关单提交。
+// 未触及这些路径则脚本内跳过。脚本缺失 fail-closed。
+gate('索引漂移（增量）', '.agents/hooks/check-index-incremental.mjs');
 
-# 确认台账不变量前置（--staged，2026-10-02 ledger-ci-invariant）：暂存的 confirmations.jsonl 必须
-# 是 HEAD 的逐字节前缀扩展（append-only）——本地提交时刻即拦「顺手重写台账」，CI 历史全扫兜底。
-# guard 旧装副本自然跳过；暂存未触台账静默。
-if [ -f .agents/scripts/check-ledger-invariant.mjs ] && command -v node >/dev/null 2>&1; then
-  if git -c core.quotepath=off diff --cached --name-only | grep -q '^\.agents/confirmations\.jsonl$'; then
-    if ! node .agents/scripts/check-ledger-invariant.mjs --staged; then
-      echo "pre-commit: 确认台账不变量未通过，提交已阻止——历史行禁删改（append-only），修正走追加补偿行" >&2
-      exit 1
-    fi
-  fi
-fi
+// 常驻面体积预算（增量硬拦，rule-budget.mjs --staged：只查本次暂存触及的条目与触及目录的合计；
+// 超限即阻断——常驻面只增不减，须先删除或下沉一条被取代条目再增。预算登记表缺失同样 fail-closed）
+requireScript('.agents/rule-budgets.txt');
+gate('常驻面体积预算', '.agents/scripts/rule-budget.mjs', ['--staged']);
 
-# 项目门禁挂载点：.agents/hooks/local-pre-commit（项目自建门禁/门禁模块接线处，存在即执行）
-if [ -f .agents/hooks/local-pre-commit ]; then
-  run_gate "项目门禁（local-pre-commit）" .agents/hooks/local-pre-commit
-fi
+// 确认台账不变量前置（--staged，2026-10-02 ledger-ci-invariant）：暂存的 confirmations.jsonl 与分片
+// confirmations.d/*.jsonl（2026-10-13 ledger-shard-default 起分片为默认写入口径，触发面同步扩大）必须
+// 是 HEAD 的逐字节前缀扩展（append-only）——本地提交时刻即拦「顺手重写台账」，CI 历史全扫兜底。
+// 暂存未触台账静默；触台账而脚本缺失 fail-closed 阻断。
+const staged = spawnSync('git', ['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only'], { encoding: 'utf8' });
+const stagedFiles = String(staged.stdout || '').split(/\r?\n/).filter(Boolean).map((f) => f.replace(/\\/g, '/'));
+const touchesLedger = stagedFiles.some((f) => /^\.agents\/confirmations\.jsonl$|^\.agents\/confirmations\.d\/[^/]+\.jsonl$/.test(f));
+if (touchesLedger) {
+  requireScript('.agents/scripts/check-ledger-invariant.mjs');
+  const li = spawnSync(process.execPath, ['.agents/scripts/check-ledger-invariant.mjs', '--staged'], { stdio: 'inherit' });
+  if (li.status !== 0) {
+    console.error('pre-commit: 确认台账不变量未通过，提交已阻止——历史行禁删改（append-only），修正走追加补偿行');
+    process.exit(li.status === null ? 1 : li.status);
+  }
+}
 
-if ! command -v node >/dev/null 2>&1; then
-  echo "pre-commit: 未找到 node——敏感信息扫描与条件构建无法执行，提交已阻止（安装 Node.js 后重试）" >&2
-  exit 1
-fi
+// 项目门禁挂载点：.agents/hooks/local-pre-commit（项目自建门禁/门禁模块接线处，add-gate 生态往里写行）。
+// 保持 sh 形态：以 sh（缺则 bash）执行；存在即执行、缺失打 advisory 不阻断（挂载点可选语义），
+// 但缺失不再无声——该文件随包下发，advisory 即误删信号。
+if (fs.existsSync('.agents/hooks/local-pre-commit')) {
+  const shBin = spawnSync('sh', ['-c', 'true']).status === 0 ? 'sh' : 'bash';
+  const lp = spawnSync(shBin, ['.agents/hooks/local-pre-commit'], { stdio: 'inherit' });
+  if (lp.status !== 0) {
+    console.error('pre-commit: 项目门禁（local-pre-commit）未通过，提交已阻止');
+    process.exit(lp.status === null ? 1 : lp.status);
+  }
+} else {
+  console.error('pre-commit: （advisory）项目门禁挂载点 .agents/hooks/local-pre-commit 不在场——add-gate 接线处随包下发，若为误删请 flow-kit sync 恢复');
+}
 
-# 合并提交 → 构建验证覆盖【完整合并树】，不做按扩展名的条件裁剪。
-# 两条路径：`git merge` 自动提交由 .githooks/pre-merge-commit 显式传 `--full` 转发到本脚本；
-# 冲突解决后手动 `git commit` 由 git 直接调本脚本，此处按 MERGE_HEAD 探测补上（此时合并仍在进行）。
-full_args="$*"
-if [ -z "$full_args" ] && git rev-parse -q --verify MERGE_HEAD >/dev/null 2>&1; then
-  full_args=--full
-fi
+// 合并提交 → 构建验证覆盖【完整合并树】，不做按扩展名的条件裁剪。
+// 两条路径：`git merge` 自动提交由 .githooks/pre-merge-commit 显式传 `--full` 转发到本脚本；
+// 冲突解决后手动 `git commit` 由 git 直接调本脚本，此处按 MERGE_HEAD 探测补上（此时合并仍在进行）。
+let fullArgs = process.argv.slice(2);
+if (fullArgs.length === 0) {
+  const mergeHead = spawnSync('git', ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { encoding: 'utf8' });
+  if (mergeHead.status === 0) fullArgs = ['--full'];
+}
 
-node .agents/hooks/commit-check.cjs $full_args
-rc=$?
-if [ $rc -ne 0 ]; then
-  echo "pre-commit: 验证未通过，提交已阻止" >&2
-  exit $rc
-fi
-exit 0
+const cc = spawnSync(process.execPath, ['.agents/hooks/commit-check.cjs', ...fullArgs], { stdio: 'inherit' });
+if (cc.status !== 0) {
+  console.error('pre-commit: 验证未通过，提交已阻止');
+  process.exit(cc.status === null ? 1 : cc.status);
+}
+process.exit(0);

package/templates/_githooks/pre-merge-commit

@@ -1,24 +1,28 @@
-#!/bin/sh
-# Git 原生 pre-merge-commit hook（经 core.hooksPath 挂载，git 执行、不依赖 agent 客户端）
-#
-# 背景：git 对 `git merge` 调的是**本钩子**，不是 pre-commit。此前仓库只挂了
-# pre-commit / pre-push / commit-msg，故合并提交绕过全部门禁、未经任何校验直接落库
-# （2026-09-19 实测，见 workflow/papercuts.md 同日行——那次合并带入后端 .cs 改动，
-# 靠人工补跑静态门 + 全量测试才覆盖到）。
-#
-# 做法：转发到 .githooks/pre-commit（门禁清单只此一份，避免两份拷贝日后分叉），
-# 并显式传 `--full`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
-# MERGE_HEAD（2026-09-19 实测：本时点 MERGE_HEAD 已不可靠）。`--full` 令编译验证
-# 覆盖【完整合并树】、不按扩展名条件裁剪：合并结果是没人验证过的新状态，且其 diff
-# 相对第一父，裁剪会漏掉需要重跑的一侧。
-#
-# 冲突解决后手动 `git commit` 走的是 pre-commit 自身，那条路径由 pre-commit 内部的
-# MERGE_HEAD 探测覆盖（此时合并仍在进行，MERGE_HEAD 确定存在）。
+#!/usr/bin/env node
+// Git 原生 pre-merge-commit hook（经 core.hooksPath 挂载；2026-10-13 随 pre-commit node 化（B2）改为 node 转发
+// ——转发不再经 sh。CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ESM 语法探测）
+//
+// 背景：git 对 `git merge` 调的是**本钩子**，不是 pre-commit。此前仓库只挂了
+// pre-commit / pre-push / commit-msg，故合并提交绕过全部门禁、未经任何校验直接落库
+// （2026-09-19 实测，见 workflow/papercuts.md 同日行——那次合并带入后端 .cs 改动，
+// 靠人工补跑静态门 + 全量测试才覆盖到）。
+//
+// 做法：转发到 .githooks/pre-commit（门禁清单只此一份，避免两份拷贝日后分叉），
+// 并显式传 `--full`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
+// MERGE_HEAD（2026-09-19 实测：本时点 MERGE_HEAD 已不可靠）。`--full` 令编译验证
+// 覆盖【完整合并树】、不按扩展名的条件裁剪：合并结果是没人验证过的新状态，且其 diff
+// 相对第一父，裁剪会漏掉需要重跑的一侧。
+//
+// 冲突解决后手动 `git commit` 走的是 pre-commit 自身，那条路径由 pre-commit 内部的
+// MERGE_HEAD 探测覆盖（此时合并仍在进行，MERGE_HEAD 确定存在）。
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
 
-cd "$(git rev-parse --show-toplevel)" || exit 1
-
-if command -v sh >/dev/null 2>&1; then
-  exec sh .githooks/pre-commit --full
-else
-  exec bash .githooks/pre-commit --full
-fi
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-merge-commit: 无法定位仓库根——合并提交已阻止');
+  process.exit(1);
+}
+const hook = path.join(top.stdout.trim(), '.githooks', 'pre-commit');
+const r = spawnSync(process.execPath, [hook, '--full'], { stdio: 'inherit' });
+process.exit(r.status === null ? 1 : r.status);

package/templates/_githooks/pre-push

@@ -1,8 +1,9 @@
 #!/bin/sh
 # Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）
-# 跑 .agents/scripts/check-loop.sh：扫 workflow/ 闭环骨架断档
-#   - 硬阻断（exit 1）= 配对断裂 / 回路断档 → push 立即阻断
-#   - 警告（advisory）= 状态未确认 / 模板占位残留 / 引用漂移 等卫生项 → 仅打印提示
+# 跑 .agents/scripts/check-loop.sh：扫 workflow/ 闭环骨架断档（2026-10-13 分道——默认只扫硬门，源仓同款）
+#   - 硬阻断（exit 1）= 配对断裂 / 回路断档 等硬门违例 → push 立即阻断
+#   - 卫生项（索引/宿主/词表/体积预算等 WARN 面）不进 push 门——要看时手跑 check-loop.mjs --hygiene
+#     （--all 两面都跑 = 分道前的裸跑全量）
 # stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
 #
 # experiment/* 泳道（2026-09-30 hybrid-governance-explore-hardening）：**目标分支**为 experiment/* 时，
@@ -12,9 +13,9 @@
 #   （intent approved/done + 同名 plan 在场 + L2/L3 另须同名 spec；判据见 check-loop.mjs 加固门段），
 #   hard 失败即阻断 push，防「未文档化的探索件」进 main。
 #
-# 机器门：本地钩子（唯一机器门）——kit 不附带 CI 配置，装户仓裸装无跨环境保证。
-# kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 复跑 check-loop / doctor / source-sync-check --gate / workflows-check 四道门。
-# 装户仓（无 templates/ 包源）：无 CI——source-sync-check --gate / doctor / flow-kit 命令不适用（引用即失败），本地钩子即全部机器门。
+# 机器门：本地钩子跑 check-loop.sh。装户仓的远端门是随包下发的 .github/workflows/kit-ci.yml（verify.mjs）。
+# kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 跑 npm test（lint + 全量套件）。
+# 装户仓无包源 templates/：sync-hosts 等包源命令不适用。本地钩子仍是提交时刻的机器门。
 # 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
 
 cd "$(git rev-parse --show-toplevel)" || exit 1

package/templates/_github/workflows/kit-ci.yml

@@ -1,7 +1,8 @@
 # kit-ci —— agentic-flow-kit 装户远端门（GitHub Actions 薄模板，2026-10-07 adopter-ci-github）
 # 语义：本地 git hooks 可被 --no-verify / 未配 hooksPath 的克隆绕过——本工作流在 GitHub runner 上复跑
-# 统一入口 node .agents/scripts/verify.mjs（测试【有根 package.json 才跑】+ check-loop），任一非零即红；
-# 不在 YAML 里复制门禁逻辑（本地/远端单源，防口径漂移）。
+# 统一入口 node .agents/scripts/verify.mjs（七门 GATES 编排：语法自检 / 测试【有根 package.json 才跑】/
+# 编排脚本检查 / 常驻面预算 / 生效规则视图漂移 / check-loop 闭环硬门 / 台账不变量历史全扫——门清单见
+# verify.mjs --list），任一门红即红；不在 YAML 里复制门禁逻辑（本地/远端单源，防口径漂移）。
 # 本文件归装户自持（owned）：触发分支 / node 版本 / 测试命令可自改，flow-kit sync 永不覆盖。
 # 装户仓工程在子目录（根无 package.json）时 verify 会跳过测试——改用
 #   node .agents/scripts/verify.mjs --test-cmd "<项目测试命令>"
@@ -24,7 +25,7 @@ jobs:
       - name: 安装依赖（有根 package.json 才跑；私有源在此加 registry 配置）
         if: hashFiles('package.json') != ''
         run: npm ci || npm install || npm install --registry=https://registry.npmjs.org # 末级官方源兜底（2026-10-09 engine-quality-round3 W3：镜像故障不阻塞 CI）
-      - name: 远端门（测试 + 闭环校验）
+      - name: 远端门（verify 七门编排）
         run: node .agents/scripts/verify.mjs
       - name: CI 红回溯点名（2026-10-09 engine-quality-round2 B3：红时列出最近关单，复核优先）
         if: failure()

package/templates/workflow/README.md

@@ -12,15 +12,18 @@
 | `specs/` | 设计规格：功能行为、数据流、系统改动、约束遵守映射 | 与入口文档（intent / incident）同名 |
 | `plans/` | 计划文档：与入口文档同名配对，任务拆解 + 判据 + 风险 | 与入口文档（intent / incident）同名 |
 | `incidents/` | 事故复盘：时间线、根因、为什么没拦住、复盘三件套 | `YYYY-MM-DD-<主题>.md` |
+| `archive/` | 终态件归档（`<YYYY-MM>/<类型>/`）：同名家族滚动归档的落点，整族退出活跃面——INDEX、check-loop 配对门与 kb 活跃语料只扫四目录直下，台账行原路径未命中时 check-ledger-invariant 会探到此处 | `YYYY-MM/` |
 
 **命名一律英文 kebab-case**（如 `2026-09-07-<主题>.md`），**禁中文文件名**——check-loop 对非 ASCII 文件名给 warning。文档内容（标题/正文）不受此限。
 
-**文档协议（frontmatter 受限子集）**：四类文档头部一律为 YAML frontmatter（每行 `键: 值`，机器字段唯一来源）——`状态`（intent/spec/plan：draft/approved/done/superseded/cancelled；incident：open/fixed/closed，**严格枚举，单源 `.agents/workflow-enums.txt`**——check-loop / 看板 / 检索 / fill-* 一律读它，改枚举改那边；附注写 `备注:` 键）、`级别`（L0-L3，同单源）、intent 的 `risk_level`（=级别，混合治理风险泳道选道字段，fill-intent 落）、`日期`/`发现`（YYYY-MM-DD）、`模块`（**新建文档必填**，取值见 `.agents/workflow-modules.txt` 词表，单值取主导模块；存量不回填，AI 触碰时顺手补）、L3 spec 的 `确认结果`/`确认时间`、回填件 `流程: legacy`。**`状态` 迁移须经 `approved`**（确认环节的机器可见态，`done` 只在关单出现）：新建的 spec/plan 若已 done 而 git 历史中从未出现行首 `状态: approved`，check-loop 报「确认态缺失」warning。check-loop 只扫 frontmatter 取机器字段（`fm_get` 字段断言），正文不再写「状态：/级别：」行；叙述性字段（独立复核/复盘三件套/验收勾验）仍留正文按节锚定。
+**文档协议（frontmatter 受限子集）**：四类文档头部一律为 YAML frontmatter（每行 `键: 值`，机器字段唯一来源）——`状态`（intent/spec/plan：draft/approved/done/superseded/cancelled；incident：open/fixed/closed，**严格枚举，单源 `.agents/workflow-enums.txt`**——check-loop / 看板 / 检索 / fill-* 一律读它，改枚举改那边；附注写 `备注:` 键）、`级别`（L1-L3，同单源；L0 已退役，存量件改 L1 或标 `流程: legacy`）、intent 的 `risk_level`（=级别，混合治理风险泳道选道字段，fill-intent 落）、`日期`/`发现`（YYYY-MM-DD）、`模块`（**新建文档必填**，取值见 `.agents/workflow-modules.txt` 词表，单值取主导模块；存量不回填，AI 触碰时顺手补）、L3 spec 的 `确认结果`/`确认时间`、回填件 `流程: legacy`。**`状态` 迁移须经 `approved`**（确认环节的机器可见态，`done` 只在关单出现）：新建的 spec/plan 若已 done 而 git 历史中从未出现行首 `状态: approved`，check-loop 报「确认态缺失」warning。check-loop 只扫 frontmatter 取机器字段（`fm_get` 字段断言），正文不再写「状态：/级别：」行；叙述性字段（独立复核/复盘三件套/验收勾验）仍留正文按节锚定。
 
 各子目录内 `_TEMPLATE.md` 为起步模板，复制后填写，不直接改动模板本身。
 
 根目录 `regression-checklist.md` 为**活文档回归清单**：deploy 回归必过条目与 incident 防复发验证的统一落点，随模块上线补充、随 incident 追加。
 
+**三份 append-only 台账已分片**（2026-10-13 ledger-shard-ledgers）：`regression-checklist` / `delegations` / `papercuts` 的数据行按月存 `workflow/<台账>.d/<YYYY-MM>.md`，主台账只留说明、表头与 GENERATED 区——消除「每次追加全量重写整文件」的体积与合并冲突面。读写单源 = `.agents/scripts/ledger-shards.mjs`（读侧自动合并主台账 ∪ 全部分片，既有消费者无需改动）；追加一行用 `node .agents/scripts/ledger-shards.mjs --append <台账> --row "<行>"`。
+
 ## 使用方式
 
 - **发起新任务**：执行 `.agents/commands/new-task.md` 定义的流程（6 阶段总入口）
@@ -30,11 +33,13 @@
 - **评审**：`.agents/commands/review.md`（按 P0 / P1 / P2 分级：机器兜底 + AI 自查出清单，用户决策定性与合入）
 - **上线**：`.agents/commands/deploy.md`（上线前必跑清单）
 - **量化**：委派/自做结果记 `delegations.md`，聚合跑 `node .agents/scripts/agg-delegations.cjs`（**并发扩容门槛见该文件——数字达标前不扩并发**）；语料与常驻面体积的**月度快照**跑 `node .agents/scripts/gen-workflow-metrics.mjs`（每月一行落 `metrics.md`，同月重跑即更新；明细看 stdout）
+- **归档**：终态件滚动归档跑 `node .agents/scripts/archive-sweep.mjs`（缺省 dry-run 预览；`--window 21 --execute` 执行 git mv）——归档单位 = **同名家族**（intent/spec/plan/incident 同进同退：任一成员非终态 / 未满窗 / 被活跃引用 / 无日期，整族留守）；终态时间三级锚 = 确认台账终态行 ts → 内容 last-touch（frontmatter-only 提交不刷新）→ 文件名日期；落点 `workflow/archive/<家族最晚终态月>/<类型>/`
+- **papercut 回路（存量债清偿，手动触发）**：命令/技能卡壳记 `workflow/papercuts.md` 攒成的未升级条目 = 存量债；要清时跑 `node .agents/scripts/papercut-debt-sensor.mjs`（测 debt）→ `node .agents/scripts/papercut-debt-controller.mjs`（确定性选本轮唯一目标；源码/数据库面条目被 scope gate 拦下等授权）→ 按 `.agents/skills/papercut-fix/SKILL.md` 执行（改完 debt 应恰好 -1）。判定与排序口径单源 `.agents/loop/papercut-debt/DESIGN.md`，改口径先改设计文件
 - **追溯**：git 即审计——文档随代码同 commit、上线打 `release/<日期>` tag，`git log` 全链路可查；多人评审暂缓，git 历史即评审记录
-- **级别**：L0 例行 ｜ L1 实现级（页面 / 交互 / 样式等，未命中 L2/L3）｜ L2 规则 / 契约（编码权威 / 共享契约 / 既有接口语义 / 全局横切口径，触达面闭集见 `.agents/commands/new-task.md` §级别判断）｜ L3 数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）；混合改动就高不就低
-- **风险泳道（混合治理）**：级别即风险级（L0 最低 → L3 最高），按级选道——**L0 / L1 协作道（敏捷优先）**：L0 豁免 intent 直接 commit；L1 已确认 intent + 极简 plan 即动工，独立复核不设同步前置，审计异步补（check-loop、事后 review 兜底）；**L2 / L3 防御道（严谨优先）**：同步确认门——spec 确认通过方可起草 plan、plan 确认后方可动手（闭环规则 1-2），L3 加新会话独立复核，未确认不放行。intent frontmatter 以 `risk_level`（=级别）落机器可读标记；批量代录与 AI 自治（confirm-doc `--batch` / `--auto`，trust-mode Standard｜Trusted）均限协作道 L0/L1，协作道勾触达红线会被 check-loop 判「红线判低」hard 拦截
-- **探索泳道（experiment/ 前缀分支，Explore-to-Harden，2026-09-30 hybrid-governance-explore-hardening）**：experiment/ 前缀分支上的 PoC 任务在 intent frontmatter 加 `阶段: exploring` 标记——提交/推送门降级 advisory（pre-commit 闭环配对、pre-push 闭环扫描报告不阻断）；L0/L1 的 draft intent 允许 spec/plan 起草与确认先于入口确认（stage-gates 起草门泳道豁免，「先起草后确认」）。**转正（合入 main）必须过加固门**：pre-push 对目标 refs/heads/main 以 `check-loop --hardening` 运行——exploring 任务的 intent 须为 approved/done、同名 plan 在场且收口（L2/L3 另须同名 spec），未收口 hard 阻断；探索作废走显式放弃态 superseded/cancelled（出列不加固）。诚实边界：分支名不进 commit——experiment/* 分支上暂存 intent 缺「阶段: exploring」由 pre-commit「泳道完整性」门禁拦截（2026-10-01 drift-hardening），残余暴露面仅剩绕过本地钩子的提交（`--no-verify` 禁令纪律覆盖）
-- **Trusted 自动泳道（2026-09-30 hybrid-governance-explore-hardening）**：trust-mode.json = Trusted（level 2）时，confirm-doc 的非 TTY 单份调用对 L0/L1 文档**免旗标**（无需 `--delegated` 原话 / `--auto`）自动按 AI 自治放行（台账 source=ai-auto-trust-L2）；L2/L3 与 incidents 仍须人工，Standard / Strict 不隐式（fail-closed）
+- **级别**：L1 实现级（未命中 L2/L3；新需求的入口是 plan）｜ L2 规则 / 契约（编码权威 / 共享契约 / 既有接口语义 / 全局横切口径，触达面闭集见 `.agents/commands/new-task.md` §级别判断）｜ L3 数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）；混合改动就高不就低
+- **风险泳道（混合治理）**：级别即风险级（L1 最低 → L3 最高），按级选道——**L1 协作道（敏捷优先）**：一份 plan 即入口，不另立 intent，独立复核不设同步前置，审计异步补（check-loop、事后 review 兜底）；**L2 / L3 防御道（严谨优先）**：同步确认门——spec 确认通过方可起草 plan、plan 确认后方可动手（闭环规则 1-2），L3 加新会话独立复核，未确认不放行。intent frontmatter 以 `risk_level`（=级别）落机器可读标记；批量代录与 AI 自治（confirm-doc `--batch` / `--auto`，trust-mode Standard｜Trusted）均限协作道 L1，协作道勾触达红线会被 check-loop 判「红线判低」hard 拦截
+- **探索泳道（experiment/ 前缀分支，Explore-to-Harden，2026-09-30 hybrid-governance-explore-hardening）**：experiment/ 前缀分支上的 PoC 任务在 intent frontmatter 加 `阶段: exploring` 标记——提交/推送门降级 advisory（pre-commit 闭环配对、pre-push 闭环扫描报告不阻断）；L1 的 draft intent 允许 spec/plan 起草与确认先于入口确认（stage-gates 起草门泳道豁免，「先起草后确认」）。**转正（合入 main）必须过加固门**：pre-push 对目标 refs/heads/main 以 `check-loop --hardening` 运行——exploring 任务的 intent 须为 approved/done、同名 plan 在场且收口（L2/L3 另须同名 spec），未收口 hard 阻断；探索作废走显式放弃态 superseded/cancelled（出列不加固）。诚实边界：分支名不进 commit——experiment/* 分支上暂存 intent 缺「阶段: exploring」由 pre-commit「泳道完整性」门禁拦截（2026-10-01 drift-hardening），残余暴露面仅剩绕过本地钩子的提交（`--no-verify` 禁令纪律覆盖）
+- **Trusted 自动泳道（2026-09-30 hybrid-governance-explore-hardening）**：trust-mode.json = Trusted（level 2）时，confirm-doc 的非 TTY 单份调用对 L1 文档**免旗标**（无需 `--delegated` 原话 / `--auto`）自动按 AI 自治放行（台账 source=ai-auto-trust-L2）；L2/L3 与 incidents 仍须人工，Standard / Strict 不隐式（fail-closed）
 
 ## 执行模型
 
@@ -54,6 +59,19 @@
 4. **敏感信息**：pre-commit 的 commit-check 扫描密钥。
 5. **双源与台账**：doctor 核对 managed / owned 的 sha；引擎改动改包源 `templates/` 再 `sync`。
 6. **台账不可变**（2026-10-02 ledger-ci-invariant）：`confirmations.jsonl` 历史行禁删改（append-only 前缀不变量，机器门 = CI 历史全扫 + pre-commit `--staged` 前置）；误写/修正只能**追加补偿行**，篡改历史属审计事件（`git revert` 整个提交后重新追加）。
+7. **台账并发三形态与修剪通道**（2026-10-12，台账是尾部追加形态，撞三种正常协作）：
+
+   | 形态 | 机制 | 用法 |
+   |---|---|---|
+   | 多人/多分支合并冲突 | `.gitattributes` 的 `.agents/*.jsonl merge=jsonl-union` → `git-merge-jsonl.mjs` 并集去重（两侧行全保留，无冲突可解） | 需目标仓 `.gitattributes` 有该行 + 本机 `git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"`（`init` 自动配） |
+   | 单机多 worktree 并行 append | 确认行**默认**写分片 `.agents/confirmations.d/<doc>.jsonl`（2026-10-13 ledger-shard-default），各写各的互不覆盖；`--no-shard` / `CONFIRM_SHARDED=0` 回退主台账；里程碑可选跑 `compact-ledgers.mjs [--execute]` 并回主台账 | 分片默认**依赖 doc 链口径**（`kit.json` 须 `policyVersion: 8`+）：缺锚时自动回退主台账并出 ℹ️（存量装户行为零变化）；显式 `--shard` 缺锚仍参数期直接拒 |
+   | 所有者明令删某批文档 | **特许修剪**：同笔提交 `.agents/ledger-prune-manifest.json`（`{ts, authority, reason, removes:[被删行 sha256], docs:[家族名]}`），门禁逐行对账放行 | 无 manifest 的删/改/重排**仍全拦** |
+
+   哈希链的域是「同一 doc 的逻辑序」而非文件物理序——并发 append / 并集合并 / 分片归并都不会打断它；就地改行、删行、插行三类篡改照拦。诚实边界：manifest 是可写文件，**刻意伪造即可让任意删行合法化**（与「台账本地可写」同级），本通道只把「顺手手改」抬到「提交一份可被 git 历史对质的凭据」。
+
+   > **存量装户迁移动作**：`merge=jsonl-union` 属 `.gitattributes`，而该文件是**项目自持（owned）**、`sync` 永不覆盖——升级后**不会自动获得**，需手动在目标仓 `.gitattributes` 补两行：`.agents/*.jsonl merge=jsonl-union` 与 `.agents/confirmations.d/*.jsonl merge=jsonl-union`（2026-10-13 ledger-shard-default 起分片为默认写入口径，分片行漏配则并行分支合并分片仍走文本冲突）。driver 是本机态配置、不跨机共享（漏配退化为文本冲突，不静默丢数据但要人工解）。
+
+   > **冲突自愈兜底**：gitattributes 行或 driver 漏配退化为文本冲突时，跑 `node .agents/scripts/resolve-merge-conflicts.mjs` 一键消解派生面——`workflow/INDEX.md` 冲突取当前侧后全量重生成 + `git add`；`.agents/` 下 `*.jsonl`（主台账与 `confirmations.d/` 分片同判定面）UU/AA 双方并集去重 + `git add`；删除/改删型（DD/UD/AU/DU）不写入只提示人工裁决，业务代码冲突原样保留交人收尾。
 
 其余检查（占位符、引用、模块字段、常驻面预算、量化签名、阶段索引、适配器断线、引擎脚本测试覆盖（检查 20，包源环境——新增引擎脚本默认必须带 `.test.mjs`，库件/工具须登记 `.agents/scripts-test-exempt.txt`，2026-10-01 gate-script-test-coverage））只在 `audit` 不是 `false` 时出警告。
 

package/templates/workflow/incidents/_TEMPLATE.md

@@ -2,12 +2,15 @@
 状态: open
 级别: L1
 发现: YYYY-MM-DD
+来源: <self | user | test | monitor——谁发现，见 .agents/workflow-enums.txt incident.source.all>
+影响环境: <dev | staging | prod | none——缺陷触达的环境，none=未触达运行环境>
 模块: <词表之一，见 .agents/workflow-modules.txt>
 沉淀: <可选：复盘沉淀到 wiki 的相对仓根路径，如 wiki/项目规范/权限收敛方案.md；不沉淀写「无」，留空待 check-loop 提醒；关单时可跑 node .agents/scripts/draft-sediment.mjs 自动抽草稿并回写本字段>
 ---
 # INCIDENT — <日期 主题>
 <!-- 复制为 YYYY-MM-DD-<主题>.md；线上或实测发现的功能缺陷都记录，历史 BUG 可回填 -->
-<!-- frontmatter 受限子集（2026-09-13）：状态∈open/fixed/closed（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；闭环引擎启用前的回填件加一行 `流程: legacy`（豁免级别/配对检查）；正文不再写状态/级别/发现行 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈open/fixed/closed（严格枚举，附注写备注键）；级别∈L1/L2/L3；闭环引擎启用前的回填件加一行 `流程: legacy`（豁免级别/配对检查；存量 L0 件同样改 L1 或标 `流程: legacy`）；正文不再写状态/级别/发现行 -->
+<!-- 归因两键（2026-10-13 自 Shipyard 回灌 incident-attribution；归因检查 B6b 落地后编号以 check-loop.mjs 头部清单为准）：新建件必填、锚前存量不回填；「来源」是缺陷发现方（供来源×环境交叉表机器复算，替代逐件人工判读），「影响环境」写实际触达环境（未触达写 none） -->
 
 ## 时间线
 - <发现 → 定位 → 止血 → 恢复，带时刻>

package/templates/workflow/intents/_TEMPLATE.md

@@ -1,6 +1,7 @@
 ---
 状态: draft
 级别: L1
+预判: <可选：kind=<require|fix|verify|review|deploy> level=<L1|L2|L3>>
 日期: YYYY-MM-DD
 模块: <词表之一，见 .agents/workflow-modules.txt>
 沉淀: <可选：沉淀到 wiki 的相对仓根路径，如 wiki/项目规范/权限收敛方案.md；不沉淀写「无」，留空待 check-loop 提醒；关单时可跑 node .agents/scripts/draft-sediment.mjs 自动抽草稿并回写本字段>
@@ -8,8 +9,9 @@
 ---
 # INTENT — <主题>
 <!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->
-<!-- frontmatter 受限子集（2026-09-13）：每行 `键: 值`；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->
-<!-- 探索泳道（可选，2026-09-30 hybrid-governance-explore-hardening）：experiment/ 前缀分支上的 PoC 任务在 frontmatter 加「阶段: exploring」——提交/推送门降级 advisory，spec/plan 可先于本入口确认起草（限 L0/L1）；转正合入 main 前须收口（本档 approved/done + 同名 plan/spec 在场，check-loop --hardening 加固门），或显式放弃（superseded/cancelled） -->
+<!-- frontmatter 受限子集（2026-09-13）：每行 `键: 值`；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->
+<!-- 探索泳道（可选，2026-09-30 hybrid-governance-explore-hardening）：experiment/ 前缀分支上的 PoC 任务在 frontmatter 加「阶段: exploring」——提交/推送门降级 advisory，spec/plan 可先于本入口确认起草（限 L1）；转正合入 main 前须收口（本档 approved/done + 同名 plan/spec 在场，check-loop --hardening 加固门），或显式放弃（superseded/cancelled） -->
+<!-- 预判（可选，2026-10-13 自 Shipyard 回灌 prejudgment-ledger）：定级时先做结构化预判，结果如实写「预判: kind=<require|fix|verify|review|deploy> level=<L1|L2|L3>」——intents≡require、incidents≡fix；与实际落位不符时 check-loop 路由预判一致性检查（B6b 落地后编号以 check-loop.mjs 头部清单为准）出 WARN 留账。缺字段零告警（存量宽容不回填，不做强制前置）——advisory 灰度口径 -->
 
 ## 背景与问题
 <为什么做；写明需求来源（工单 / 沟通记录 / 待办事项）>

package/templates/workflow/papercuts.md

@@ -2,6 +2,8 @@
 
 > `.agents/commands/`、`.agents/roles/` 或已装技能在真实任务中卡住、误导、缺步骤时记一行，**不当场顺手改**。
 > 同一文件命中第 2 次或用户点名时，升级为 docs 修复 commit。
+> **分片（2026-10-13 ledger-shard-ledgers）**：数据行按月存 `workflow/papercuts.d/<YYYY-MM>.md`（本文件只留说明与表头）。追加一行用 `node .agents/scripts/ledger-shards.mjs --append papercuts --row "<行>"`（缺省按行内日期定月，`--month` 可覆盖）；读侧（`papercut-debt-sensor.mjs` 等）自动合并主台账 ∪ 全部分片，无需改动。手工编辑分片亦可，但须自带表头。
+> **存量债回路**：未升级条目累积 = 存量债，清理跑 papercut 回路（传感器测 debt → 控制器选目标 → `papercut-fix` 技能执行），口径单源 `.agents/loop/papercut-debt/DESIGN.md`。
 
 | 日期 | 位置 | 症状 | 拟修 |
 |------|------|------|------|

package/templates/workflow/plans/_TEMPLATE.md

@@ -5,25 +5,30 @@
 ---
 # PLAN — <与入口文档同名主题>
 <!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->
-<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L0/L1/L2/L3；正文不再写状态/级别行 -->
+<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3；正文不再写状态/级别行 -->
 <!-- L1 极简形态（Quick-Plan，与 fill-plan.mjs 单源一致）：单/少文件微改动只填「改动方案」+「约束与风险」+「验证计划」三节（L1 主节标题模板正文用「改动面」，fill-plan 生成「改动方案」——check-loop 证据校验对 改动面/任务拆解/改动方案 三种节名均识别为声明文件来源）——改动方案逐条列改哪个文件做什么（判据细节直接写进条目），验证计划一行静态门 + 按需 UI 实测；任务拆解/执行顺序仅 L1 多文件多步骤时保留 -->
+<!-- L1 直达（2026-10-13 自 Shipyard 回灌）：新单用 fill-plan.mjs --level L1，本文件即入口，不另立 intent（无同名 intent/incident 时起草门放行；文件已在则级别以文件为准，禁用 --level L1 放行存量 L2 plan）。修复类另保留 ../incidents/ 同名件 -->
 <!-- 待澄清标记（2026-10-12 needs-clarification）：判据不明 / 依赖不确定 / 用户没说的细节，照实写一行
      `- 待澄清：<你卡在哪>`，不要猜（语义说明同 specs 模板：占位符=忘了填，本标记=我不知道）。
      起草不拦，draft→approved 确认时仍挂着会被 confirm-doc 拒绝；解决后改行首为 `- 已澄清：` 或删行。 -->
 
-对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）
-对应 spec：../specs/YYYY-MM-DD-<主题>.md（L1 可省略）
+对应入口：L1 = 本 plan。修复类另保留 ../incidents/YYYY-MM-DD-<主题>.md。L2/L3 = ../intents/YYYY-MM-DD-<主题>.md
+对应 spec：../specs/YYYY-MM-DD-<主题>.md（仅 L2/L3）
 
 ## 改动面（L1 极简形态主节；L2/L3 可作任务拆解的汇总或删本节）
 - <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』」>
+<!-- build.md 确认的改动清单确认后回填本节落盘（对话留痕仅供当次）——改动面 + 任务勾选态 + git status = 会话重入三锚（2026-10-11 session-context，自 Shipyard 回灌） -->
 
 ## 任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）
-1. <任务>
+<!-- 任务即勾选态（2026-10-11 session-context，自 Shipyard 回灌）：完成一项立刻勾选并回填留痕；压缩 / 新会话续作先读本表勾选态 + git status 重建进度，禁凭记忆补勾 -->
+- [ ] 1. <任务>
    - 判据：<怎样算完成；尽量对应一个测试或可复现操作>
    - 风险：低 / 中 / 高（<原因>）
-2. <任务>
+   - 留痕：（勾选时回填 commit SHA / 测试名 / 实测输出）
+- [ ] 2. <任务>
    - 判据：…
    - 风险：…
+   - 留痕：…
 
 ## 执行顺序（L2/L3 必填；L1 单文件微改动删本节）
 <1 → 2 → 3；标注依赖关系>

package/templates/workflow/regression-checklist.md

@@ -10,6 +10,7 @@
 3. **模块上线/走查后**：为该模块补关键路径条目
 4. 条目过时（功能下线/行为变更）时删除或改写，不保留失效条目
 5. **新增防复发条目落点优先级**：自动化用例 > 脚本化断言 > 人工步骤（仅剩视觉/交互断言无法脚本化时）
+6. **分片（2026-10-13 ledger-shard-ledgers）**：「防复发验证」节的数据行按月存 `workflow/regression-checklist.d/<YYYY-MM>.md`（该节是唯一 append-only 追加区；上方模块节为稳定参考内容，留守本文件）。追加一行用 `node .agents/scripts/ledger-shards.mjs --append regression-checklist --row "<行>"`；读侧自动合并主台账 ∪ 全部分片。
 
 ## 回归必过