agentic-flow-kit 0.5.0 → 0.7.0

package/templates/_agents/hooks/check-pairing-incremental.sh

@@ -1,16 +1,20 @@
 #!/bin/sh
-# 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan
+# 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan（L2/L3 另须同名 spec）
 # 目的：把 check-loop.sh「配对断裂」hard-block 的发现时机从 pre-push 提前到 commit
 # （papercut 2026-09-15：maintain.md 只写「incident≡intent 免另立 intent」，未把配 plan 写成显式步骤，
-#  按文档字面执行三次 commit 全绿、push 才爆红，只能后补）
-# 口径与 check-loop.sh 对齐：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名；
-# 同 commit 携带 plan 合法（检查的是工作区文件存在，staged 新建 plan 同样命中）。
-# 已知边界：legacy 豁免读的是工作区文件而非暂存 blob——add 后又改工作区时可能误豁免/误拦（逐文件取 blob 的 fork 成本大于收益，接受）。
+#  按文档字面执行三次 commit 全绿、push 才爆红，只能后补；
+#  2026-09-27 audit-gate-hardening 补齐 spec 档——此前只查 plan，L2/L3 缺 spec 仍要拖到 push 才爆红）
+# 口径与 check-loop.sh 对齐：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名，
+# L2/L3 级别另须 workflow/specs/ 同名（check-loop 检查 1 同款分档）；
+# 同 commit 携带 plan/spec 合法（检查的是工作区文件存在，staged 新建同样命中）。
+# 已知边界：legacy 豁免与级别读取均基于工作区文件而非暂存 blob——add 后又改工作区时可能误豁免/误拦（逐文件取 blob 的 fork 成本大于收益，接受）。
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
 fail=0
-for f in $(git diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
+# -c core.quotepath=off：quotepath 默认 true 时非 ASCII 路径被引号转义（"workflow/\346..."），
+# ^workflow/ 前缀匹配失配 → 门禁静默跳过——教训与修法同 check-wiki-ledger.sh（2026-09-27 gate-coverage）
+for f in $(git -c core.quotepath=off diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
   # 闭环引擎启用前的回填件带「流程: legacy」豁免配对检查（与 check-loop 同口径）
   if grep -q '^流程: legacy' "$f"; then
     continue
@@ -22,9 +26,18 @@ for f in $(git diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow
     echo "  L1 极简 plan 只需「改动面 + 验证方式」两节（复制 workflow/plans/_TEMPLATE.md）"
     fail=1
   fi
+  lvl=$(sed -n 's/^级别:[[:space:]]*//p' "$f" | head -1)
+  if [ "$lvl" = "L2" ] || [ "$lvl" = "L3" ]; then
+    if [ ! -f "workflow/specs/$base.md" ]; then
+      echo "闭环配对（增量）— BLOCK:"
+      echo "  入口缺同名 spec: $f（级别 $lvl 须三件套，应在 workflow/specs/$base.md）"
+      echo "  与 pre-push check-loop 检查 1 同口径——先起草 spec 走 design.md，再提交"
+      fail=1
+    fi
+  fi
 done
 
 if [ $fail -ne 0 ]; then
-  echo "pre-commit: 入口文档缺同名 plan，提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）" >&2
+  echo "pre-commit: 入口文档配对不全（plan / L2-L3 spec），提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）" >&2
 fi
 exit $fail

package/templates/_agents/metric-claims.txt

@@ -0,0 +1,81 @@
+# 量化断言「指标签名」单源登记表（check-loop 检查 16 共读）
+#
+# 背景（2026-09-28 claim-exceeds-fix）：结论文档里跨文档引用的量化值若各自手写，
+# 极易在事实变更后不同步——本仓已实证：同一指标在一处改了、另一处没改，
+# 而「五处文件同步」这句话本身无人核对（该单真正被门禁抓住的方式，是事后人工复核）。
+# 本表把「哪个指标、当前取值多少」收敛为单源，供 check-loop 检查 16 对账。
+#
+# 用法：活跃态文档（draft/approved/open）引用某个已登记指标时，按**签名形态**书写，
+# 检查 16 会实时取数比对。签名形态：\{\{指标名\}\}（双花括号包裹指标名，小写点分）。
+#   例（下面是「讲语法」，故加反斜杠转义；**写真断言时不加反斜杠**）：
+#     本仓台账共 \{\{ledger.lines\}\} 行，其中无 batch 字段 \{\{ledger.linesWithoutBatch\}\} 行。
+# 写作时**不要手写数字**——写完跑 check-loop，工具会把实时值填进提示里供你替换。
+# 转义按「逐个出现」生效：同一行里 \{\{x\}\} 是示意、\{\{y\}\} 是真断言时，只豁免前者。
+# （本例的指标名曾写成 ledger.total / ledger.noBatch 两个**并不存在**的名字——本表不被
+#   检查 16 扫描（它是 .txt 非 .md），故这类笔误不会被自动抓到，只能靠复核。已据实更正。）
+#
+# 为什么用显式签名而非全文数字扫描（据实说明，非偷懒）：
+#   本仓活跃文档中「N 行 / N 条 / N 份」类表述有 49 处（实测：活跃态 21 份文档逐行计），绝大多数是**历史叙述**
+#   （描述某次提交当时的规模，天然不会随当前事实变化）。全文扫描会对这些正确的
+#   历史叙述产生大量假阳性——而 check-loop.mjs 已把「无判定依据的行不产出不可
+#   消除噪声」立为红线（沿 2026-09-27 audit-gate-hardening P3 教训：噪声淹没真漏点）。
+#   故本检查**只校验显式声明的签名**：假阳性恒为 0，代价是覆盖面依赖作者登记。
+#
+# 格式：每行 `<指标名> = <取数表达式>`；`#` 开头为注释；空行忽略。
+# 取数表达式（闭集，全部本地确定性、零网络）：
+#   ledger.lines          台账 .agents/confirmations.jsonl 的非空行数
+#   ledger.linesWithoutBatch   台账中不含 "batch" 字段的行数（schema 演进前历史行）
+#   ledger.linesWithBatch      台账中含 "batch" 字段的行数
+#   docs.count.<sub>      workflow/<sub> 下文档份数——**与文档扫描同口径**：以数字开头的
+#                         .md、排除 _TEMPLATE.md、且仓库模式下只计 HEAD 已跟踪件
+#                         （故并行会话的未跟踪新档不计入）；sub ∈ intents/specs/plans/incidents
+#   docs.count.all        上述四类合计
+# ── 新增指标（2026-09-28 adopter-derivers 起）────────────────────────────────
+# 分两层取数，**内置优先**：
+#   ① 引擎内置 8 个指标（下表）——装户零配置即用，不需要做任何事。
+#   ② 项目自有指标——写 `.agents/metric-derivers.cjs`（**owned**，sync 永不覆盖），
+#      用 CommonJS 导出 `derivers` 对象（指标名 → 取数函数），并在此表加同名一行。
+#      **后缀必须是 `.cjs`、写法必须是 CommonJS**（`module.exports`）。
+#      为什么不用 `.mjs`：引擎用 `require()` 同步载入，而 `require(esm)` 仅在
+#      Node ≥20.19 / ≥22.12 可用——**实测 Node 18.20 / 20.18 / 22.11 全部
+#      ERR_REQUIRE_ESM**，而本仓 engines 声明 `>=18.0.0`。故 `.cjs` 是唯一
+#      全版本可用的形态（同步、零版本依赖）。
+#      旧的 `.mjs` 路径已弃用：若残留在盘上，检查 16 会**明确提示迁移**。
+#
+# 示例 `.agents/metric-derivers.cjs`：
+#     module.exports = {
+#       derivers: {
+#         'my.migrations': (ctx) => ctx.glob('backend/migrations/*.sql').length,
+#         'my.apiCount':   (ctx) => ctx.countFiles('src/api', (f) => f.endsWith('.controller.ts')),
+#       },
+#     };
+# ctx 提供（同步，免你重复造轮子；其余请自行 `require('node:fs')`）：
+#     ctx.root                    仓库根绝对路径
+#     ctx.read(rel)               读文本文件（LF 归一），不存在返回 ''
+#     ctx.glob(pattern)           极简 glob（* / **），返回相对路径数组
+#     ctx.countFiles(dir, pred)   递归计数（可传谓词）
+#
+# 三条硬约定（违反即 fail-loud）：
+#   1. **必须是同步函数**（返回 number，不得 async/Promise）——本检查零网络、要求本地确定性
+#   2. 必须**确定性**：不得依赖网络、不得依赖当前时间
+#   3. 返回值须为**有限数字**（Number.isFinite）
+#
+# 失败语义（**绝不静默降级**）：模块语法错 / 抛异常 / 未导出 derivers / 返回值非法
+#   → 一律出 `[WARN 装户取数器载入失败]` 或 `[WARN 指标取数失败]`，**不会**退化成
+#   「只用内置指标」——否则你会误以为「忘了登记」而查不到真因。
+# 指标名与内置同名时：**内置优先**，你的定义被忽略（会出 advisory 明示）。
+#
+# 注：本检查**不设取数超时**——请让取数器保持轻量（秒级）。死循环会拖慢门禁。
+# 另：装户模块的「取数器」在引擎侧（check-loop.mjs，managed）；本表与 derivers.cjs 同归 owned。
+#
+# 注意：不登记 advisory 总数类指标——它由 check-loop 自身产出（检查 16 是其一部分），
+# 自引用会让「报告本身改变被报告的数」，产生不可稳定对账的循环。
+
+ledger.lines = ledger.lines
+ledger.linesWithoutBatch = ledger.linesWithoutBatch
+ledger.linesWithBatch = ledger.linesWithBatch
+docs.count.intents = docs.count.intents
+docs.count.specs = docs.count.specs
+docs.count.plans = docs.count.plans
+docs.count.incidents = docs.count.incidents
+docs.count.all = docs.count.all

package/templates/_agents/roles/implementer.md

@@ -1,5 +1,7 @@
 # Implementer
 
+> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：

package/templates/_agents/roles/independent-reviewer.md

@@ -1,5 +1,7 @@
 # Independent Reviewer
 
+> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。

package/templates/_agents/roles/ui-verifier.md

@@ -1,5 +1,7 @@
 # UI Verifier
 
+> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。

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

@@ -4,7 +4,7 @@
  * 输出各月指标（一次通过率 / 平均返工次数 / 主兜底占比）、并发扩容门判定、可粘贴的月度快照行。
  * 结果取值：一次通过 | 返工×N | 主兜底 | 返工待修（未闭环，不计入率）。
  * 用法：node .agents/scripts/agg-delegations.cjs [--month=YYYY-MM]（默认输出全部月份 + 全量累计）
- * 门槛定义见 workflow/delegations.md §并发扩容门槛，两处须同步改。
+ * 门槛定义见 workflow/delegations.md §并发扩容门槛（doc 为权威，脚本向文档对齐——2026-09-27 board-kb-p1）。
  */
 'use strict';
 const fs = require('fs');
@@ -88,8 +88,11 @@ function countIncidents() {
   return byMonth;
 }
 
-// 门槛（与 workflow/delegations.md §并发扩容门槛 同步）
-const GATE = { minSample: 20, minPassRate: 0.9, maxAvgRework: 0.3, minDelegated: 5, maxFallbackRate: 0.1 };
+// 门槛（2026-09-27 board-kb-p1 对齐 workflow/delegations.md §并发扩容门槛声明——doc 为权威）：
+//   月度口径项：一次完成率 ≥90% ｜ 月度返工次数 = 0 ｜ 无主兜底信号（=0）（旧「平均返工≤0.3 / 兜底≤10%」为宽松分叉，退役）
+//   样本护栏项（脚本侧统计可信度门槛，非口径分叉）：月样本量 ≥20 ｜ 委派样本 ≥5
+//   连续性：扩容需「本月 + 上一自然月」连续两月月度口径全达标（delegations.md「连续两个月」）
+const GATE = { minSample: 20, minPassRate: 0.9, minDelegated: 5 };
 
 function metrics(rows) {
   // 未知结果（结果列拼错/漏填）单列计数，不混进「待修」——待修=未闭环，未知=记录本身有问题（2026-09-24 口径分离）
@@ -126,29 +129,26 @@ function fmtNum(x) {
   return x == null ? '—' : x.toFixed(2);
 }
 
-function gate(m, incidents) {
+// gateMonth：单月门槛判定（pure，供测试）——口径项 + 样本护栏项分开列
+function gateMonth(m) {
   const items = [];
-  items.push({ no: 1, ok: m.total >= GATE.minSample, desc: `样本量 ${m.total}/${GATE.minSample}` });
-  items.push({
-    no: 2,
-    ok: m.passRate != null && m.passRate >= GATE.minPassRate,
-    desc: `一次通过率 ${fmtRate(m.passRate)}≥90%`,
-  });
-  items.push({
-    no: 3,
-    ok: m.avgRework != null && m.avgRework <= GATE.maxAvgRework,
-    desc: `平均返工 ${fmtNum(m.avgRework)}≤0.3`,
-  });
-  const delegOk = m.delegatedValid >= GATE.minDelegated && m.fallbackRate != null && m.fallbackRate <= GATE.maxFallbackRate;
-  items.push({
-    no: 4,
-    ok: delegOk,
-    desc: `委派样本 ${m.delegatedValid}≥5 且主兜底 ${fmtRate(m.fallbackRate)}≤10%`,
-  });
-  items.push({ no: 5, ok: null, desc: '门禁不失守（人工对照当月 incident 定性）' });
-  const hardOk = items.filter((i) => i.ok !== null).every((i) => i.ok);
-  const bad = items.filter((i) => i.ok === false).map((i) => i.no).join('+');
-  return { items, verdict: hardOk ? '✅（待人工确认门5）' : `❌ 未达标项:${bad}` };
+  items.push({ no: 1, ok: m.total >= GATE.minSample, desc: `样本量 ${m.total}/${GATE.minSample}`, kind: '样本护栏' });
+  items.push({ no: 2, ok: m.passRate != null && m.passRate >= GATE.minPassRate, desc: `一次完成率 ${fmtRate(m.passRate)}≥90%`, kind: '口径' });
+  items.push({ no: 3, ok: m.reworkSum === 0, desc: `月度返工次数 ${m.reworkSum}=0`, kind: '口径' });
+  items.push({ no: 4, ok: m.fallback === 0, desc: `主兜底 ${m.fallback}=0（无主兜底信号）`, kind: '口径' });
+  items.push({ no: 5, ok: m.delegatedValid >= GATE.minDelegated, desc: `委派样本 ${m.delegatedValid}≥5`, kind: '样本护栏' });
+  items.push({ no: 6, ok: null, desc: '门禁不失守（人工对照当月 incident 定性）', kind: '人工' });
+  return { items, monthOk: items.filter((i) => i.ok !== null).every((i) => i.ok) };
+}
+
+// expansionVerdict：连续两个月扩容判定（pure，供测试）——本月与上一自然月 monthOk 均真才「可扩容」；
+// prevMissing = 无上月数据（首月/断档）；items 供未达标项列出
+function expansionVerdict(monthOk, prevOk, prevMissing, items) {
+  if (monthOk && prevOk) return '✅ 连续两月达标（可扩容，待人工确认门6）';
+  if (monthOk && prevMissing) return '⚠️ 本月达标（连续性 1/2——上月无数据）';
+  if (monthOk) return '⚠️ 本月达标（连续性 1/2——上月未达标）';
+  const bad = (items || []).filter((i) => i.ok === false).map((i) => i.no).join('+');
+  return `❌ 未达标（连续性中断）：${bad || '月度口径项未全过'}`;
 }
 
 function main() {
@@ -165,14 +165,18 @@ function main() {
   console.log(`# 量化证据聚合（${argMonth || '全部月份'}） 生成于 ${new Date().toISOString().slice(0, 10)}\n`);
 
   const snapshotRows = [];
+  const monthResults = new Map(); // ym → { monthOk }（连续两月判定用）
   for (const ym of months) {
     const m = metrics(byMonth[ym]);
-    const g = gate(m, incidents[ym] || 0);
+    const { items, monthOk } = gateMonth(m);
+    monthResults.set(ym, monthOk);
+    const prevYm = (() => { const [y, mo] = ym.split('-').map(Number); const d = new Date(Date.UTC(y, mo - 2, 1)); return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`; })();
+    const verdict = expansionVerdict(monthOk, monthResults.get(prevYm), !months.includes(prevYm), items);
     console.log(`## ${ym}`);
     console.log(`  有效任务 ${m.total}（待修 ${m.pending}${m.unknown ? `、未知结果 ${m.unknown}` : ''}）｜一次通过 ${m.pass}（${fmtRate(m.passRate)}）｜返工总次数 ${m.reworkSum}（平均 ${fmtNum(m.avgRework)}）｜主兜底 ${m.fallback}/${m.delegatedValid}（${fmtRate(m.fallbackRate)}）｜incident ${incidents[ym] || 0} 起`);
-    for (const i of g.items) console.log(`  门${i.no} ${i.ok === null ? '[人工]' : i.ok ? '✅' : '❌'} ${i.desc}`);
-    console.log(`  扩容门判定：${g.verdict}\n`);
-    snapshotRows.push(`| ${ym} | ${m.total} | ${fmtRate(m.passRate)} | ${fmtNum(m.avgRework)} | ${fmtRate(m.fallbackRate)} | ${incidents[ym] || 0} | ${g.verdict} | 样本含待修${m.pending}${m.unknown ? `、未知${m.unknown}` : ''} |`);
+    for (const i of items) console.log(`  门${i.no}[${i.kind}] ${i.ok === null ? '[人工]' : i.ok ? '✅' : '❌'} ${i.desc}`);
+    console.log(`  扩容门判定：${verdict}\n`);
+    snapshotRows.push(`| ${ym} | ${m.total} | ${fmtRate(m.passRate)} | ${fmtNum(m.avgRework)} | ${fmtRate(m.fallbackRate)} | ${incidents[ym] || 0} | ${verdict} | 样本含待修${m.pending}${m.unknown ? `、未知${m.unknown}` : ''} |`);
   }
 
   if (!argMonth && rows.length) {
@@ -189,4 +193,9 @@ function main() {
   }
 }
 
-main();
+// isMain 守卫 + 纯函数导出（board-kb-p1：gateMonth / expansionVerdict 供测试 import，import 不执行 main）
+if (require.main === module) {
+  main();
+} else {
+  module.exports = { parseResult, metrics, gateMonth, expansionVerdict, GATE };
+}

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

@@ -87,6 +87,38 @@ const runAgg = (root) => spawnSync(process.execPath, [path.join(root, '.agents',
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 4-5：扩容门口径（2026-09-27 board-kb-p1 对齐 delegations.md：返工 0 / 无主兜底 / 连续两月）----
+//     纯函数经 module.exports require（isMain 守卫后 import 不执行 main）
+import { createRequire } from 'node:module';
+const requireCjs = createRequire(import.meta.url);
+const { metrics, gateMonth, expansionVerdict } = requireCjs(path.join(SCRIPT_DIR, 'agg-delegations.cjs'));
+
+// 场景 4：审查反例——30 任务、2 主兜底、平均返工 0.25（旧口径四门全过，声明口径下必须 ❌）
+{
+  const rows = [
+    ...Array.from({ length: 22 }, (_, i) => ({ scope: '委派', result: '一次通过' })),
+    ...Array.from({ length: 6 }, (_, i) => ({ scope: '委派', result: '返工×1' })),
+    { scope: '委派', result: '主兜底' }, { scope: '委派', result: '主兜底' },
+  ];
+  const m = metrics(rows);
+  const g = gateMonth(m);
+  check('场景 4：反例（2 主兜底 + 平均返工 0.25）门3 返工=0 ❌', g.items.find((i) => i.no === 3).ok === false, JSON.stringify(g.items));
+  check('场景 4：反例门4 主兜底=0 ❌ 且 monthOk=false（声明口径下不达标）',
+    g.items.find((i) => i.no === 4).ok === false && g.monthOk === false, `monthOk=${g.monthOk}`);
+  const good = metrics([{ scope: '自做', result: '一次通过' }, { scope: '委派', result: '一次通过' }]);
+  const g2 = gateMonth(good);
+  check('场景 4：返工 0 + 无主兜底月 → 口径项全 ✅（样本护栏项单独列出）',
+    g2.items.filter((i) => i.kind === '口径').every((i) => i.ok === true) && g2.items.find((i) => i.no === 1).ok === false,
+    JSON.stringify(g2.items));
+}
+// 场景 5：连续两月判定四态
+{
+  check('场景 5：本月+上月均达标 → ✅ 可扩容', expansionVerdict(true, true, false, []).includes('✅'));
+  check('场景 5：本月达标、上月无数据 → ⚠️ 1/2', expansionVerdict(true, undefined, true, []).includes('⚠️'));
+  check('场景 5：本月达标、上月未达标 → ⚠️ 1/2', expansionVerdict(true, false, false, []).includes('⚠️'));
+  check('场景 5：本月未达标 → ❌ 且列出未达标项号', expansionVerdict(false, true, false, [{ no: 3, ok: false }, { no: 4, ok: false }]).match(/❌.*3\+4/));
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);