agentic-flow-kit 1.7.16 → 1.8.1

package/templates/_agents/mechanism-registry.md

@@ -0,0 +1,27 @@
+# 机制使用量台账 (Mechanism Usage Registry)
+
+> 门禁棘轮的出口：每个门禁机制的「触发统计口径 + 退役阈值 + 状态」单源登记于此。
+> **台账的目的不是记录而是强制处置**：新增门禁机制须登记一行（一进一出，并点名它替代/合并的
+> 既有机制，无替代则说明增量理由）；机制退役时状态改「已退役」并在最近触发列留档；
+> 低频机制按退役阈值降级。
+> 列序固定：机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限。
+> 本表归装户自持运营（sync 永不覆盖，同 metric-claims.txt 口径）；kit 引擎做 WARN 级格式校验
+> （check-loop 检查 22：列数 / 状态枚举 / 待退役处置期限——advisory 不阻断，永不 hard），
+> 对账纪律靠下方「维护纪律」人工执行；判定数据面由 check-loop 每次真实运行自动落账到
+> `.agents/judgments.jsonl`（judgment-ledger，本地 gitignore），月度聚合经 agg-judgments.mjs 查账。
+
+| 机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限 |
+|---|---|---|---|---|---|---|
+| 确认指纹对账（示例行） | check-loop 检查 15 | hard「指纹不配对/确认内容漂移」计数（月，经 agg-judgments 查判定流水） | 不退役（防伪造确认主干） | 示例：建门留档见包源仓 git 历史与 CHANGELOG | 现役 | — |
+| 触达面判低门（示例行） | check-lane-surface（pre-commit/CI 泳道完整性） | hard「触达面判低/产品契约面」计数（月） | 不退役（级别闭环主干） | 示例：在用 | 现役 | — |
+
+> 以上两行为**示例行**，只示范登记口径，不参与装户对账；装户按自有机制增删行，
+> 首次对账时可将示例行替换为真实运营数据。
+
+## 维护纪律
+
+- **一进一出**：新增门禁机制必须同时在本表登记，并点名它替代/合并的既有机制（无替代则说明增量理由）。
+- **月度对账**：每月初按「触发统计口径」列刷新计数（半自动：`node .agents/scripts/agg-judgments.mjs`
+  查判定流水 `.agents/judgments.jsonl`——check-loop 每次真实运行自动落账，替代人工 grep 输出；
+  git log 统计口径不变）；达到阈值的行改「待退役」并填处置期限。
+- **退役动作**：状态改「已退役」当日删除机制代码 + 其测试 + 本表更新，同一提交完成（不留死代码）。

package/templates/_agents/rule-budgets.txt

@@ -1,7 +1,7 @@
-# 常驻面体积预算（单源：check-loop.sh 检查 13（--all，WARN）与 .githooks/pre-commit（--staged，硬拦）共读）
+# 常驻面体积预算（单源：check-hygiene 检查 13（--all，WARN）与 .githooks/pre-commit（--staged，硬拦）共读）
 # 格式：<路径或 glob> <上限字节>；路径以 / 结尾表示目录合计。上限 = 当前实测 + 余量。
 # 超限含义：常驻面只增不减——须先删除或下沉被取代条目再增（一进一出）。
-# 本文件会被 core.autocrlf 检出为 CRLF，读取方（rule-budget.sh）已显式去 \r，禁止依赖行尾格式。
+# 本文件会被 core.autocrlf 检出为 CRLF，读取方（rule-budget.mjs）按 /\r?\n/ 切分天然容 \r，禁止依赖行尾格式。
 # 口径：预算比较用「索引 / 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 步进）；目录合计未超不动。

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

@@ -2,6 +2,7 @@
 /* agg-delegations: 量化证据聚合
  * 读 workflow/delegations.md 两张结果表（按表头签名识别：委派表含「被委派方」列、自做表=日期+任务一句话；不依赖 ## 节标题）+ 扫 workflow/incidents/ 按月计数，
  * 输出各月指标（一次通过率 / 平均返工次数 / 主兜底占比 / **产出接受率**）、并发扩容门判定、可粘贴的月度快照行。
+ * 分片感知（2026-10-13 ledger-shard-ledgers 回灌）：读侧文本 = 主台账 ∪ delegations.d/*.md，单源 = ledger-shards.mjs。
  * 结果取值：一次通过 | 返工×N | 返工×N（门禁噪声）| 主兜底 | 返工待修（未闭环，不计入率）。
  *   门禁噪声档（2026-10-08 selfmeasure-and-modularize）：剥离「返工由门禁面而非设计面触发」的形态——
  *   扩容门第 3 项只对设计返工判 =0，门禁噪声返工单列观测。存量行零回填（旧四档解析逐条不变）。
@@ -95,15 +96,28 @@ function splitTables(text) {
   return tables;
 }
 
+// 分片读侧文本（2026-10-13 ledger-shard-ledgers 回灌）：单源 = ledger-shards.readLedgerText
+// （主台账 ∪ delegations.d/*.md，月序即时间序）。.cjs 不能静态 import .mjs、require(esm) 需
+// Node≥20.19（engines ≥18 不假设）——CLI 入口以 import() 装载后注入此变量再进 main；
+// 库调用方（gen-workflow-dashboard）经 opts.text 显式注入合并文本。两者都缺位 → 回落主台账直读
+// （与旧签名行为一致，不静默造数）。
+let shardReadText = null;
 // 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)) {
+  let text;
+  if (typeof opts.text === 'string') {
+    text = opts.text; // 库调用方注入的合并文本（读侧单源 = ledger-shards.readLedgerText）
+  } else if (!fs.existsSync(ledger)) {
     if (opts.soft) return [];
     fail(`找不到 ${ledger}`);
+  } else if (shardReadText) {
+    try { text = shardReadText(root, 'delegations'); } // 分片感知读（fail-loud 包装：单分片读失败不静默吞）
+    catch (err) { if (opts.soft) return []; fail(`台账读取失败: ${ledger} (${err.message})`); }
+  } else {
+    text = fs.readFileSync(ledger, 'utf8');
   }
-  const text = fs.readFileSync(ledger, 'utf8');
   const tables = splitTables(text);
   const delegated = parseTableRows(tables.delegated.join('\n')).map((c) => ({
     scope: '委派',
@@ -278,7 +292,11 @@ function main() {
 
 // isMain 守卫 + 纯函数导出（board-kb-p1：gateMonth / expansionVerdict 供测试 import，import 不执行 main）
 if (require.main === module) {
-  main();
+  // 分片读侧装载（2026-10-13 ledger-shard-ledgers）：动态 import 后进 main；装载失败 fail-loud
+  // （指标缺数会喂错扩容门，不静默退化主台账直读）。
+  import('./ledger-shards.mjs')
+    .then((m) => { shardReadText = m.readLedgerText; main(); })
+    .catch((err) => fail(`ledger-shards.mjs 装载失败: ${err.message}`));
 } else {
   module.exports = { parseResult, parseVerdict, metrics, gateMonth, expansionVerdict, fmtAccept, GATE, ACCEPT_MIN_SAMPLE, readLedger };
 }

package/templates/_agents/scripts/agg-gate-stats.mjs

@@ -8,7 +8,7 @@
 // 门禁数与质量指标负相关，但此前无任何数据能回答「该加门还是该拆门」（metrics/DASHBOARD 全部指标
 // 100% 指向产出物、0 条指向门禁自身）。加门是焦虑驱动的唯一理性反应，因为拆门没有依据。
 //
-// 耗时口径**含子进程时间**（检查 11 调两个生成器 --check、检查 13 调 sh rule-budget.sh）——
+// 耗时口径**含子进程时间**（检查 11 调两个生成器 --check、检查 13 调 rule-budget.mjs）——
 // 门禁真实成本本就要含子进程，不做剔除；输出中显式标注防误读为「纯计算耗时」。
 // 坏行容忍跳过（与 confirmations.jsonl / delegations 台账同容错口径）。
 // 用法：node .agents/scripts/agg-gate-stats.mjs [--days 30]
@@ -84,13 +84,13 @@ function main() {
   const { runs, list, noiseTop, dead, costTotal } = aggregate(rows, Date.now(), Number.isFinite(days) ? days : null);
 
   if (!runs || !list.length) {
-    console.log('门禁 ROI：未采集——跑 `node .agents/scripts/check-loop.mjs --gate-stats` 后重试');
+    console.log('门禁 ROI：未采集——跑 `node .agents/scripts/check-loop.mjs --all --gate-stats` 后重试（--all 全段成本面；2026-10-13 分道后裸跑只记硬门段）');
     console.log('（数据落 .agents/cache/gate-stats.jsonl，该目录已 gitignore；首次采集后本表才有内容）');
     return;
   }
 
   console.log(`# 门禁 ROI 聚合（窗口 ${days} 天 / 有效样本 ${runs} 次运行）\n`);
-  console.log('耗时口径**含子进程时间**（检查 11 调生成器 --check、检查 13 调 sh rule-budget.sh）——门禁真实成本，不做剔除。\n');
+  console.log('耗时口径**含子进程时间**（检查 11 调生成器 --check、检查 13 调 rule-budget.mjs）——门禁真实成本，不做剔除。\n');
   console.log('| 检查 | 名称 | 命中/运行 | 拦截 | 警告 | 累计耗时 | 均耗时 | 每次命中警告数 |');
   console.log('|------|------|-----------|------|------|----------|--------|----------------|');
   for (const a of list) {

package/templates/_agents/scripts/agg-judgments.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// agg-judgments.mjs — check-loop 判定流水月度聚合（2026-10-11 judgment-ledger）
+// 用法：node .agents/scripts/agg-judgments.mjs [--month=YYYY-MM]
+// 源：.agents/judgments.jsonl（check-loop.mjs 每次真实运行追加一行，本地 gitignore；
+//     缺文件 = 尚无运行记录，提示后 exit 0——与 delegations 台账「必在」不同，这是渐积数据）。
+// 消费：mechanism-registry 月度对账（.agents/mechanism-registry.md「触发统计口径」列的 WARN/BLOCK 计数）
+//     与 advisory→hard 升格 / 退役判定的直接查账面——替代原「人工 grep check-loop 输出」。
+// 测试：node .agents/scripts/agg-judgments.test.mjs（纯函数 aggFromRows 进程内断言）
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(SCRIPT_DIR, '..', '..');
+const LEDGER = path.join(ROOT, '.agents', 'judgments.jsonl');
+
+const argMonth = (process.argv.find((a) => a.startsWith('--month=')) || '').split('=')[1] || null;
+
+// aggFromRows(rows, month)：按月×规则×级别聚合。rows = 已解析的台账行数组；
+// month = 'YYYY-MM' 过滤（null = 全部）。输出 { byMonth: { 'YYYY-MM': { runs, rules: { rule: { WARN, BLOCK } } } } }。
+export function aggFromRows(rows, month = null) {
+  const byMonth = {};
+  for (const row of rows || []) {
+    if (typeof row.ts !== 'string' || !/^\d{4}-\d{2}/.test(row.ts)) continue;
+    const ym = row.ts.slice(0, 7);
+    if (month && ym !== month) continue;
+    const b = (byMonth[ym] ||= { runs: 0, rules: {} });
+    b.runs++;
+    for (const r of Array.isArray(row.rules) ? row.rules : []) {
+      if (!r || typeof r.rule !== 'string') continue;
+      const cell = (b.rules[r.rule] ||= { WARN: 0, BLOCK: 0 });
+      if (r.level === 'WARN') cell.WARN += r.count || 0;
+      else if (r.level === 'BLOCK') cell.BLOCK += r.count || 0;
+    }
+  }
+  return { byMonth };
+}
+
+function readRows() {
+  if (!fs.existsSync(LEDGER)) return null;
+  const rows = [];
+  let bad = 0;
+  for (const line of fs.readFileSync(LEDGER, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      bad++;
+    }
+  }
+  return { rows, bad };
+}
+
+function main() {
+  const read = readRows();
+  if (!read) {
+    console.error(`agg-judgments: ${path.relative(ROOT, LEDGER)} 不存在——尚无运行记录（check-loop 真实运行一次即有一行）`);
+    process.exit(0);
+  }
+  const { byMonth } = aggFromRows(read.rows, argMonth);
+  const months = Object.keys(byMonth).sort();
+  if (!months.length) {
+    console.log(`agg-judgments: ${argMonth || '全部月份'} 无记录（台账共 ${read.rows.length} 行）`);
+    return;
+  }
+  for (const ym of months) {
+    const b = byMonth[ym];
+    console.log(`📅 ${ym}｜运行 ${b.runs} 次`);
+    const rules = Object.keys(b.rules).sort();
+    if (!rules.length) { console.log('    （无规则判定）'); continue; }
+    for (const rule of rules) {
+      const { WARN, BLOCK } = b.rules[rule];
+      console.log(`    ${rule.padEnd(24)} WARN×${WARN}  BLOCK×${BLOCK}`);
+    }
+  }
+  if (read.bad) console.error(`agg-judgments: 跳过坏行 ${read.bad}（JSON 解析失败，不中断聚合）`);
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('agg-judgments.mjs');
+if (isMain) main();

package/templates/_agents/scripts/agg-judgments.test.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// agg-judgments.test.mjs — 判定流水聚合纯函数套件（2026-10-11 judgment-ledger）
+// aggFromRows 进程内断言：按月分桶 / --month 过滤 / WARN·BLOCK 计数 / 坏 rules 字段容忍。
+import { aggFromRows } from './agg-judgments.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 ROWS = [
+  { ts: '2026-10-01T01:00:00Z', mode: 'hard', rules: [{ rule: '三件套不全', level: 'WARN', count: 2 }] },
+  { ts: '2026-10-02T01:00:00Z', mode: 'hygiene', rules: [{ rule: '三件套不全', level: 'WARN', count: 1 }, { rule: '配对断裂', level: 'BLOCK', count: 1 }] },
+  { ts: '2026-09-30T01:00:00Z', mode: 'hard', rules: [{ rule: '归因缺字段', level: 'WARN', count: 3 }] },
+  { ts: '2026-10-03T01:00:00Z', mode: 'hard', rules: [] },
+  { ts: 'bad-ts', mode: 'hard', rules: [] },
+  { ts: '2026-10-04T01:00:00Z', mode: 'hard', rules: 'not-array' },
+];
+
+// ---- S1 按月分桶 + 计数 ----
+{
+  const { byMonth } = aggFromRows(ROWS);
+  check('S1 两个月桶（坏 ts 行不计）', Object.keys(byMonth).sort().join(',') === '2026-09,2026-10', JSON.stringify(Object.keys(byMonth)));
+  check('S1 2026-10 运行 4 次', byMonth['2026-10'].runs === 4, String(byMonth['2026-10'].runs));
+  check('S1 跨行同规则 WARN 累加（2+1=3）', byMonth['2026-10'].rules['三件套不全'].WARN === 3, JSON.stringify(byMonth['2026-10'].rules));
+  check('S1 BLOCK 计数独立', byMonth['2026-10'].rules['配对断裂'].BLOCK === 1);
+  check('S1 2026-09 归因缺字段 WARN×3', byMonth['2026-09'].rules['归因缺字段'].WARN === 3);
+  check('S1 空 rules 行只计 runs', byMonth['2026-10'].runs === 4 && byMonth['2026-10'].rules['配对断裂'].WARN === 0);
+}
+
+// ---- S2 month 过滤 ----
+{
+  const { byMonth } = aggFromRows(ROWS, '2026-09');
+  check('S2 过滤单月只留 2026-09', Object.keys(byMonth).join(',') === '2026-09' && byMonth['2026-09'].runs === 1);
+  check('S2 过滤无命中 → 空桶', aggFromRows(ROWS, '2025-01').byMonth['2025-01'] === undefined);
+}
+
+// ---- S3 空入参 ----
+check('S3 空行数组 → 空 byMonth', Object.keys(aggFromRows([]).byMonth).length === 0);
+check('S3 null 入参不 throw', Object.keys(aggFromRows(null).byMonth).length === 0);
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/archive-sweep.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+// archive-sweep — workflow 终态件滚动归档（2026-10-09；2026-10-13 修锚；B9 自 Shipyard.Material
+//   回灌——判定面逐字对齐，出处沿革留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径）
+// **归档单位 = 同名家族**（intent/spec/plan/incident 同名文件同进同退）：check-loop 检查 1 的结构配对
+//   是「家族双向在场」审计——intent 缺 spec/plan、spec/plan 缺 intent、incident 缺 plan/spec 均为
+//   hard-block（源仓首批按单篇准入产生数十处配对断裂的返工实证，留痕在包源仓 git 历史与 CHANGELOG）。
+//   家族任一成员不满足条件（非终态/未满窗/被活跃引用/无日期），整族留守。
+// 终态时间三级锚（2026-10-13 修锚）：confirmations 终态行 ts（精确）→ **内容 last-touch**（回退）→ 文件名日期
+// 回退级原用 git last-touch，会被批量提交系统性污染：实例仓曾发生大规模 frontmatter 迁移与两步式
+// 留痕补录（数百文件量级），把存量老文档的 last-touch 集体刷成当日 → 21 天窗口恒不满足、活跃目录
+// 只进不出。修法：回退级改「最后一次**正文**变更」——frontmatter-only 提交（状态/确认指纹/备注行增删改）
+// 不计入，因其不改变文档的实质内容与归档安全性（归档只依赖终态 + 无活跃引用，二者均由当前 frontmatter
+// 与引用扫描独立判定）。污染事件与修锚实测数据留痕在包源仓 git 历史与 CHANGELOG。
+// 判定：逐提交比对 blob，剥 frontmatter 区后正文逐字节相同 → 视为 frontmatter-only，跳过。
+// 归档形态：git mv → workflow/archive/<家族最晚终态月>/{类型}/，整族同批 = 整体退出活跃面——
+//   check-loop 配对门 / gen-workflow-index / kb-search 活跃语料均只扫四目录直下，归档不产生配对断裂
+//   （check-ledger-invariant 已归档感知：台账行原路径未命中再探 workflow/archive/*/）。
+//   差异收敛（B10a 随动）：kb-search 已同源仓扩 archive/<批次>/<type> 检索覆盖——归档件退出活跃目录
+//   但不退出 kb 检索面，防复发不丢历史。
+// 用法：
+// node .agents/scripts/archive-sweep.mjs # dry-run（缺省），--window 21
+// node .agents/scripts/archive-sweep.mjs --window 21 --execute # git mv 执行
+// 验证：node .agents/scripts/archive-sweep.test.mjs
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readLedgerRows } from './ledger-loader.mjs';
+
+const DIRS = ['intents', 'specs', 'plans', 'incidents'];
+export const TERMINAL = new Set(['done', 'superseded', 'cancelled', 'closed']);
+export const ACTIVE = new Set(['draft', 'approved', 'open', 'fixed']);
+
+export function parseStatus(text) {
+  const lines = text.split(/\r?\n/);
+  const end = lines.indexOf('---', 1);
+  for (let i = 1; i < (end === -1 ? Math.min(lines.length, 15) : end); i++) {
+    const s = /^状态:\s*(\S+)/.exec(lines[i]);
+    if (s) return s[1];
+  }
+  return '';
+}
+
+// bodyOf(text)：剥 frontmatter 区（首 --- 至闭合 ---）后的正文，CRLF 归一。
+// 用途：判定一次提交是否只动了 frontmatter（状态/确认指纹/备注）——此类提交不改变文档实质内容，
+// 不应刷新「内容 last-touch」（2026-10-13 修锚，见文件头注释）。无 frontmatter → 全文即正文。
+export function bodyOf(text) {
+  const norm = String(text).replace(/\r\n/g, '\n');
+  const lines = norm.split('\n');
+  if (!/^---\s*$/.test(lines[0] || '')) return norm;
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) return lines.slice(i + 1).join('\n');
+  }
+  return norm; // 未闭合 → 保守视全文为正文（宁可刷新，不误判为 frontmatter-only）
+}
+
+// 纯函数：候选分析（fixture 测试直接驱动；docs 项 = { rel, file, dir, text }）
+// 归档单位 = 同名家族：家族候选 ⇔ 全成员终态 + 全成员有终态时间且超窗 + 无成员被活跃引用
+export function analyze({ docs, ledgerTs = {}, lastTouch = {}, activeTexts = [], windowDays = 21, today = Date.now() }) {
+  const referenced = new Set();
+  const fams = new Map();
+  for (const d of docs) {
+    if (d.file.startsWith('_TEMPLATE')) continue;
+    if (!fams.has(d.file)) fams.set(d.file, []);
+    fams.get(d.file).push(d);
+  }
+  for (const text of activeTexts) for (const file of fams.keys()) if (text.includes(file)) referenced.add(file);
+
+  const active = [];
+  const terminal = [];
+  const candidates = [];
+  const tooRecent = [];
+  const noDate = [];
+  for (const [, members] of fams) {
+    const enriched = members.map((d) => {
+      const st = parseStatus(d.text);
+      const tTime = ledgerTs[d.rel] || lastTouch[d.rel] || /^(\d{4}-\d{2}-\d{2})/.exec(d.file)?.[1] || '';
+      const src = ledgerTs[d.rel] ? 'ledger' : lastTouch[d.rel] ? 'git' : 'name';
+      return { ...d, st, tTime, src };
+    });
+    const allTerminal = enriched.every((x) => TERMINAL.has(x.st));
+    const refd = enriched.some((x) => referenced.has(x.file));
+    const undated = enriched.filter((x) => !x.tTime);
+    const recent = enriched.filter((x) => x.tTime && Math.floor((today - new Date(x.tTime).getTime()) / 864e5) <= windowDays);
+    const archivable = allTerminal && !refd && !undated.length && !recent.length;
+    for (const x of enriched) {
+      if (TERMINAL.has(x.st)) terminal.push(x);
+      if (ACTIVE.has(x.st)) active.push(x);
+    }
+    if (!archivable) {
+      if (undated.length) noDate.push(...undated);
+      if (recent.length) tooRecent.push(...recent);
+      continue;
+    }
+    const month = enriched.map((x) => x.tTime).sort().pop().slice(0, 7); // 家族最晚终态月，整族同批
+    for (const x of enriched) candidates.push({ ...x, month });
+  }
+  return { active, terminal, candidates, referenced, tooRecent, noDate };
+}
+
+export function buildDocList(root, dirs = DIRS) {
+  const docs = [];
+  for (const d of dirs) {
+    const dir = path.join(root, 'workflow', d);
+    if (!fs.existsSync(dir)) continue; // 目录缺失（fixture / 部分类型未建）→ 跳过，不抛
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      const rel = `workflow/${d}/${f}`;
+      docs.push({ rel, file: f, dir: d, text: fs.readFileSync(path.join(dir, f), 'utf8') });
+    }
+  }
+  return docs;
+}
+
+function loadLedgerTs(root) {
+  const out = {};
+  // 台账统一视图（主台账+分片透明合并，坏行跳过）。源仓走 ledger-loader.loadAllConfirmations
+  // （同 doc|stage|fingerprint 键去重取末次）；kit 读侧单源 = readLedgerRows（不去重）。对本判据
+  // 无语义差：loadLedgerTs 取「每 doc 终态行最大日期」，同键末次行的日期 ≥ 该键其余行，两侧 max
+  // 恒等——不为锚查询给 loader 加第二个出口（读侧出口越少越不易漂移）。
+  for (const e of readLedgerRows(root)) {
+    if (TERMINAL.has(e.stage) && e.doc) {
+      const d = (e.ts || '').slice(0, 10);
+      if (d && (!out[e.doc] || d > out[e.doc])) out[e.doc] = d;
+    }
+  }
+  return out;
+}
+
+// loadLastTouch(root)：每篇 workflow 文档的「最后一次正文变更」日期（YYYY-MM-DD）。
+// 逐提交（新→旧）取该文件的 blob 与上一版比对：正文（bodyOf）逐字节相同 → frontmatter-only 提交，
+// 跳过不记；正文有变 → 记该提交日期并停止追踪该文件（新→旧遍历，首遇即最近一次正文变更）。
+// 批量迁移/补录提交（只改状态与确认指纹）因此不再刷新锚——2026-10-13 修锚的核心。
+// 实现：单次 `git log --raw` 拿「提交 × 文件 × 前后 blob sha」，再按需 `git cat-file --batch` 取内容
+// （同 blob 内容天然去重，批量提交里数十文件多为同一份 frontmatter 改写，实际读取量远小于文件数）。
+export function loadLastTouch(root) {
+  const out = {};
+  const raw = execFileSync('git', ['log', '--raw', '--no-renames', '--format=%x01%cI', '--', 'workflow'], {
+    cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024,
+  });
+  // 收集待比对项：按 path 分组，保留**全部**历史条目（新→旧），逐条比对直到找到正文变更
+  const byPath = new Map();
+  for (const entry of raw.split('\u0001')) {
+    const lines = entry.split('\n');
+    const date = (lines[0] || '').slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue;
+    for (const line of lines.slice(1)) {
+      // `:<oldmode> <newmode> <oldsha> <newsha> <status>\t<path>`
+      const m = /^:\d+ \d+ ([0-9a-f]+) ([0-9a-f]+) [A-Z]\d*\t(.+)$/.exec(line);
+      if (!m) continue;
+      const [, oldSha, newSha, p] = m;
+      if (!byPath.has(p)) byPath.set(p, []);
+      byPath.get(p).push({ date, oldSha, newSha });
+    }
+  }
+  // 批量取 blob 内容（--batch 一次喂全部 sha，输出 `<full-sha> blob <size>\n<content>\n`）
+  // 注意：--batch 回显**完整** sha，而输入是 core.abbrev 缩写——按输入顺序回填，键用请求时的缩写，
+  // 否则 blobs.get(缩写) 恒 miss → 全部走保守回退（2026-10-13 实测踩中）。
+  const shas = [...new Set([...byPath.values()].flat().flatMap((x) => [x.oldSha, x.newSha]).filter((s) => s && !/^0+$/.test(s)))];
+  const blobs = new Map();
+  if (shas.length) {
+    const outBuf = execFileSync('git', ['cat-file', '--batch'], {
+      cwd: root, input: shas.join('\n') + '\n', maxBuffer: 512 * 1024 * 1024,
+    });
+    // 按 header 行切分（内容可能含任意字节，故按 size 精确切片）；第 i 个响应 ↔ shas[i]
+    let pos = 0;
+    let idx = 0;
+    while (pos < outBuf.length && idx < shas.length) {
+      const nl = outBuf.indexOf(0x0a, pos);
+      if (nl === -1) break;
+      const header = outBuf.toString('utf8', pos, nl);
+      const hm = /^([0-9a-f]+) blob (\d+)$/.exec(header);
+      if (!hm) { pos = nl + 1; continue; }
+      const size = Number(hm[2]);
+      const start = nl + 1;
+      blobs.set(shas[idx], outBuf.toString('utf8', start, start + size));
+      pos = start + size + 1; // 跳过内容后的换行
+      idx++;
+    }
+  }
+  // 逐 path 新→旧扫描：首个「正文有变」的提交日期即内容 last-touch；全为 frontmatter-only → 不记
+  // （调用方回退到文件名日期）。新增文件（oldSha 全 0）→ 该次提交即首次入库，记为正文变更。
+  for (const [p, entries] of byPath) {
+    for (const { date, oldSha, newSha } of entries) {
+      // 全 0 sha（新增文件，git 按 core.abbrev 输出 7 位 `0000000`）→ 首次入库即正文变更
+      if (/^0+$/.test(oldSha)) { out[p] = date; break; }
+      const before = blobs.get(oldSha);
+      const after = blobs.get(newSha);
+      // 取不到内容（异常态）→ 保守记为正文变更（宁可刷新，不误跳过）
+      if (before === undefined || after === undefined) { out[p] = date; break; }
+      if (bodyOf(before) !== bodyOf(after)) { out[p] = date; break; }
+    }
+  }
+  return out;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const execute = argv.includes('--execute');
+  const wArg = argv.find((a) => a.startsWith('--window='));
+  const windowDays = wArg ? Number(wArg.split('=')[1]) : 21;
+  if (!Number.isFinite(windowDays) || windowDays < 0) {
+    console.error('archive-sweep: --window 须为非负数字');
+    process.exit(2);
+  }
+  const root = process.cwd();
+  const docs = buildDocList(root);
+  const r = analyze({
+    docs,
+    ledgerTs: loadLedgerTs(root),
+    lastTouch: loadLastTouch(root),
+    activeTexts: docs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+    windowDays,
+  });
+  const byDir = {};
+  for (const d of DIRS) byDir[d] = r.candidates.filter((x) => x.dir === d).length;
+  const fams = new Set(r.candidates.map((x) => x.file));
+  console.log(`窗口 ${windowDays} 天｜候选 ${r.candidates.length} 篇 / ${fams.size} 族（${JSON.stringify(byDir)}）｜活跃 ${r.active.length}｜未满窗 ${r.tooRecent.length}｜被活跃引用排除 ${r.referenced.size}｜无日期 ${r.noDate.length}`);
+  if (!execute) {
+    for (const x of r.candidates) console.log(`  [dry] ${x.rel} → workflow/archive/${x.month}/${x.dir}/${x.file}`);
+    console.log('dry-run 结束（加 --execute 执行 git mv）');
+    return;
+  }
+  let moved = 0;
+  for (const x of r.candidates) {
+    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 });
+    moved++;
+  }
+  console.log(`execute 完成：git mv ${moved} 篇 → workflow/archive/<家族最晚终态月>/`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith('archive-sweep.mjs')) main();

package/templates/_agents/scripts/archive-sweep.test.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// archive-sweep.test.mjs — analyze 纯函数 fixture（2026-10-09；2026-10-13 加 bodyOf 与内容锚回归；B9 自 Shipyard.Material 回灌）
+import { analyze, parseStatus, bodyOf, loadLastTouch } from './archive-sweep.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 doc = (dir, file, st) => ({ rel: `workflow/${dir}/${file}`, file, dir, text: `---\n状态: ${st}\n---\n# t\n` });
+const daysAgo = (n) => new Date(Date.now() - n * 864e5).toISOString().slice(0, 10);
+
+// 场景 1：状态解析（CRLF 容忍）
+check('parseStatus 基础+CRLF', parseStatus('---\r\n状态: done\r\n---\nx') === 'done' && parseStatus('---\n状态: open\n') === 'open');
+
+// 场景 1b：bodyOf——剥 frontmatter（2026-10-13 修锚的判定基元）
+{
+  const a = '---\n状态: approved\n级别: L1\n---\n\n# T\n\n正文 A\n';
+  const b = '---\n状态: done\n确认指纹: abc\n级别: L1\n---\n\n# T\n\n正文 A\n';
+  check('bodyOf：frontmatter-only 变更 → 正文相等', bodyOf(a) === bodyOf(b));
+  const c = '---\n状态: done\n级别: L1\n---\n\n# T\n\n正文 B\n';
+  check('bodyOf：正文变更 → 正文不等', bodyOf(b) !== bodyOf(c));
+  check('bodyOf：无 frontmatter → 全文即正文', bodyOf('# T\n\n正文\n') === '# T\n\n正文\n');
+  check('bodyOf：未闭合 frontmatter → 保守返回全文', bodyOf('---\n状态: done\n正文\n') === '---\n状态: done\n正文\n');
+  check('bodyOf：CRLF 归一', bodyOf('---\r\n状态: done\r\n---\r\n正文\r\n') === bodyOf('---\n状态: done\n---\n正文\n'));
+}
+
+// 场景 2：终态/活跃分类 + 模板排除
+{
+  const docs = [doc('intents', 'a.md', 'done'), doc('plans', 'b.md', 'draft'), doc('intents', '_TEMPLATE.md', 'draft'), doc('incidents', 'c.md', 'closed')];
+  const r = analyze({ docs, windowDays: 21 });
+  check('分类：终态 2 / 活跃 1 / 模板排除', r.terminal.length === 2 && r.active.length === 1 && !JSON.stringify(r).includes('_TEMPLATE'));
+}
+
+// 场景 3：窗口过滤（台账 ts 优先于 git 回退）
+{
+  const docs = [doc('specs', 'old.md', 'done'), doc('specs', 'new.md', 'done')];
+  const r = analyze({
+    docs, windowDays: 21,
+    ledgerTs: { 'workflow/specs/old.md': daysAgo(30) },
+    lastTouch: { 'workflow/specs/old.md': daysAgo(2), 'workflow/specs/new.md': daysAgo(2) },
+  });
+  check('窗口：台账 30 天入候选、git 2 天未满窗', r.candidates.length === 1 && r.candidates[0].file === 'old.md' && r.candidates[0].src === 'ledger' && r.tooRecent.length === 1);
+}
+
+// 场景 4：活跃引用排除（git 回退源）+ 无时间源兜底文件名日期
+{
+  const docs = [doc('intents', '2026-09-01-refd.md', 'done'), doc('intents', '2026-09-01-fallback.md', 'done')];
+  const r = analyze({
+    docs, windowDays: 21,
+    activeTexts: ['参见 ../intents/2026-09-01-refd.md 的结论'],
+    lastTouch: { 'workflow/intents/2026-09-01-fallback.md': daysAgo(30) },
+  });
+  check('引用排除 + git 回退源入候选', r.candidates.length === 1 && r.candidates[0].file === '2026-09-01-fallback.md' && r.candidates[0].src === 'git' && r.referenced.has('2026-09-01-refd.md'));
+}
+
+// 场景 4b：台账/git 均无时间源 → 文件名日期兜底
+{
+  const r = analyze({ docs: [doc('specs', '2026-09-01-nodate.md', 'done')], windowDays: 21 });
+  check('文件名日期兜底', r.candidates.length === 1 && r.candidates[0].src === 'name' && r.candidates[0].month === '2026-09');
+}
+
+// 场景 5：归档月份取终态时间当月
+{
+  const r = analyze({ docs: [doc('plans', '2026-09-03-x.md', 'done')], windowDays: 21, ledgerTs: { 'workflow/plans/2026-09-03-x.md': '2026-09-05' } });
+  check('归档月 = 终态时间当月', r.candidates[0] !== undefined && r.candidates[0].month === '2026-09');
+}
+
+// 场景 6：家族原子——intent 未终态锚住同名家族整族留守；全终态家族整族入候选
+{
+  const docs = [
+    doc('intents', '2026-09-05-live.md', 'approved'),
+    doc('plans', '2026-09-05-live.md', 'done'),
+    doc('intents', '2026-09-04-family.md', 'done'),
+    doc('specs', '2026-09-04-family.md', 'done'),
+    doc('plans', '2026-09-04-family.md', 'done'),
+  ];
+  const r = analyze({
+    docs, windowDays: 21,
+    ledgerTs: { 'workflow/plans/2026-09-05-live.md': daysAgo(30), 'workflow/intents/2026-09-04-family.md': daysAgo(30), 'workflow/specs/2026-09-04-family.md': daysAgo(30), 'workflow/plans/2026-09-04-family.md': daysAgo(30) },
+  });
+  check('家族原子：非终态 intent 整族留守', r.candidates.length === 3 && !r.candidates.some((x) => x.file === '2026-09-05-live.md'));
+  check('家族原子：全终态家族三成员同批', r.candidates.filter((x) => x.file === '2026-09-04-family.md').length === 3);
+}
+
+// 场景 7：loadLastTouch 集成——真实 git 仓库，钉住「frontmatter-only 提交不刷新内容锚」
+// （2026-10-13 修锚回归：原实现用 git last-touch，被批量迁移/补录提交污染 → 21 天窗口恒不满足。
+//  本场景同时覆盖 cat-file --batch 回显完整 sha 而输入为缩写这一踩坑点——键错则全部走保守回退。）
+{
+  const { execFileSync } = await import('node:child_process');
+  const os = await import('node:os');
+  const path = await import('node:path');
+  const fs = await import('node:fs');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archive-sweep-git-'));
+  const git = (...a) => execFileSync('git', a, { cwd: root, encoding: 'utf8' });
+  git('init', '-q');
+  git('config', 'user.email', 't@t');
+  git('config', 'user.name', 't');
+  const dir = path.join(root, 'workflow', 'plans');
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, '2026-09-01-x.md');
+  const commit = (msg, date) => {
+    git('add', '-A');
+    execFileSync('git', ['commit', '-q', '-m', msg], { cwd: root, env: { ...process.env, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date } });
+  };
+  // ① 首次入库（正文 v1）
+  fs.writeFileSync(p, '---\n状态: draft\n级别: L1\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c1', '2026-09-01T10:00:00+08:00');
+  // ② frontmatter-only（状态 draft→approved）
+  fs.writeFileSync(p, '---\n状态: approved\n级别: L1\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c2', '2026-09-20T10:00:00+08:00');
+  // ③ frontmatter-only（approved→done + 确认指纹）
+  fs.writeFileSync(p, '---\n状态: done\n级别: L1\n确认指纹: abc\n---\n\n# T\n\n正文 v1\n', 'utf8');
+  commit('c3', '2026-09-28T10:00:00+08:00');
+  const rel = 'workflow/plans/2026-09-01-x.md';
+  const t1 = loadLastTouch(root);
+  check('loadLastTouch：frontmatter-only 提交不刷新锚（锚停在正文变更日 2026-09-01）',
+    t1[rel] === '2026-09-01', `got ${t1[rel]}`);
+  // ④ 正文变更 → 锚前移到该日
+  fs.writeFileSync(p, '---\n状态: done\n级别: L1\n确认指纹: abc\n---\n\n# T\n\n正文 v2\n', 'utf8');
+  commit('c4', '2026-10-05T10:00:00+08:00');
+  const t2 = loadLastTouch(root);
+  check('loadLastTouch：正文变更刷新锚（2026-10-05）', t2[rel] === '2026-10-05', `got ${t2[rel]}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -0,0 +1,37 @@
+// check-attribution.mjs — 检查 24：incident 归因字段核查 [warning]（2026-10-13 B6b-2 自 Shipyard.Material
+//   check-loop-sections/s24-incident-attribution.mjs 回灌；段体判据逐字对齐，出处沿革留痕在包源仓 git
+//   历史与 CHANGELOG——装户径不引实例路径）
+// 背景（incident-attribution）：incident 无「来源」标准字段，「来源×环境」分布只能逐件人工判读，
+// 两轮口径相抵不可机器复算。本段把归因变成机器校验收敛面：模板新增「来源:」/「影响环境:」两枚枚举键
+// （单源 .agents/workflow-enums.txt incident.source.all / incident.env.all），
+// 锚起的件「发现」日 ≥ attributionSince（policy v9；v1–v8 缺键 → 整段跳过）时必填且值须在枚举内 → 否则 WARN。
+// 只查字段存在性与枚举合法性，不判读内容（判读留给 gen-workflow-metrics 的机器复算表）。
+// 存量豁免：发现日 < 锚 → 整体跳过；`流程: legacy` 回填件 → 跳过（同检查 3 口径）。
+// kit 适配（源仓→kit 逐条）：告警文案里的枚举单源路径平铺 .agents/config/workflow-enums.txt → .agents/workflow-enums.txt。
+import path from 'node:path';
+
+export function run(ctx) {
+  const { ENUMS, inSet, docFiles, fmGet, kitPolicy, warnings } = ctx;
+  // --- 24. incident 归因字段核查 [warning]（锚 attributionSince）---
+  {
+    const anchor = kitPolicy.attributionSince;
+    if (anchor) {
+      const KEY_SOURCE = '来源';
+      const KEY_ENV = '影响环境';
+      for (const inc of docFiles('incidents')) {
+        const name = path.basename(inc);
+        if (fmGet(inc, '流程') === 'legacy') continue; // 回填件豁免（同检查 3）
+        // 生效日锚：发现日优先、缺则取文件名前缀（与检查 12 moduleSince 同款退化）
+        let d = fmGet(inc, '发现') || fmGet(inc, '日期');
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) d = /^\d{4}-\d{2}-\d{2}/.test(name) ? name.slice(0, 10) : '';
+        if (!d || d < anchor) continue; // 锚前存量不回填
+        const src = fmGet(inc, KEY_SOURCE);
+        const env = fmGet(inc, KEY_ENV);
+        if (!src) warnings.push(`- [WARN 归因缺字段] ${name} 缺「${KEY_SOURCE}:」字段（${anchor} 起新建 incident 必填，取值见 .agents/workflow-enums.txt incident.source.all）`);
+        else if (!inSet(src, ENUMS['incident.source.all'])) warnings.push(`- [WARN 归因非法值] ${name}「${KEY_SOURCE}: ${src}」不在枚举（${ENUMS['incident.source.all'].join('/')}）`);
+        if (!env) warnings.push(`- [WARN 归因缺字段] ${name} 缺「${KEY_ENV}:」字段（${anchor} 起新建 incident 必填，取值见 .agents/workflow-enums.txt incident.env.all）`);
+        else if (!inSet(env, ENUMS['incident.env.all'])) warnings.push(`- [WARN 归因非法值] ${name}「${KEY_ENV}: ${env}」不在枚举（${ENUMS['incident.env.all'].join('/')}）`);
+      }
+    }
+  }
+}