agentic-flow-kit 0.2.0 → 0.2.1

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /* agg-delegations: 量化证据聚合
- * 读 workflow/delegations.md 两张结果表（委派结果 / 自做任务结果）+ 扫 workflow/incidents/ 按月计数，
+ * 读 workflow/delegations.md 两张结果表（按表头签名识别：委派表含「被委派方」列、自做表=日期+任务一句话；不依赖 ## 节标题）+ 扫 workflow/incidents/ 按月计数，
  * 输出各月指标（一次通过率 / 平均返工次数 / 主兜底占比）、并发扩容门判定、可粘贴的月度快照行。
  * 结果取值：一次通过 | 返工×N | 主兜底 | 返工待修（未闭环，不计入率）。
  * 用法：node .agents/scripts/agg-delegations.cjs [--month=YYYY-MM]（默认输出全部月份 + 全量累计）
@@ -26,8 +26,7 @@ function parseTableRows(sectionText) {
     .split(/\r?\n/)
     .filter((l) => /^\|/.test(l.trim()))
     .map((l) => l.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim()))
-    .filter((cols) => cols.length >= 2 && !/^[-: ]+$/.test(cols[1])) // 去表头分隔行
-    .filter((cols) => !/^\s*$/.test(cols[0]) && /^\d{4}-\d{2}-\d{2}$/.test(cols[0])); // 只留数据行（首列是日期）
+    .filter((cols) => !/^\s*$/.test(cols[0]) && /^\d{4}-\d{2}-\d{2}$/.test(cols[0])); // 只留数据行（首列是日期；表头/分隔行随之滤除）
 }
 
 function parseResult(raw) {
@@ -40,29 +39,43 @@ function parseResult(raw) {
   return { kind: 'unknown', rework: 0 };
 }
 
-function readLedger() {
-  if (!fs.existsSync(LEDGER)) fail(`找不到 ${LEDGER}`);
-  const text = fs.readFileSync(LEDGER, 'utf8');
-  const sections = {};
+// splitTables：按表头签名识别两张结果表——节标题只服务人类阅读，表头才是数据边界
+// （2026-09-24 修复：曾按 `## 委派结果` 节标题定位，节结构漂移时已有记录被静默读成「台账为空」）
+function splitTables(text) {
+  const tables = { delegated: [], self: [] };
   let cur = null;
   for (const line of text.split(/\r?\n/)) {
-    const h = line.match(/^## (.+)$/);
-    if (h) cur = h[1].trim();
-    if (cur) (sections[cur] = sections[cur] || []).push(line);
+    if (!/^\s*\|/.test(line)) { cur = null; continue; } // 表体边界：连续 | 行；断开即出表
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (cells.some((c) => c.startsWith('被委派方'))) { cur = 'delegated'; continue; } // 委派表表头
+    if (cells[0] === '日期' && cells.some((c) => c.startsWith('任务一句话'))) { cur = 'self'; continue; } // 自做表表头（委派表已被上一行截走）
+    if (cur) tables[cur].push(line); // 表体行（含分隔行——parseTableRows 会滤掉）
   }
-  const delegated = parseTableRows((sections['委派结果'] || []).join('\n')).map((c) => ({
+  return tables;
+}
+
+function readLedger() {
+  if (!fs.existsSync(LEDGER)) fail(`找不到 ${LEDGER}`);
+  const text = fs.readFileSync(LEDGER, 'utf8');
+  const tables = splitTables(text);
+  const delegated = parseTableRows(tables.delegated.join('\n')).map((c) => ({
     scope: '委派',
     date: c[0],
     actor: c[1],
     result: c[3] || '',
   }));
-  const selfDone = parseTableRows((sections['自做任务结果'] || []).join('\n')).map((c) => ({
+  const selfDone = parseTableRows(tables.self.join('\n')).map((c) => ({
     scope: '自做',
     date: c[0],
     actor: '主智能体',
     result: c[2] || '',
   }));
-  return delegated.concat(selfDone);
+  const rows = delegated.concat(selfDone);
+  // 零数据行时区分「台账真空」与「结构漂移」：有日期开头的数据行却识别不到表 → fail-loud，不再静默「台账为空」
+  if (!rows.length && /^\s*\|\s*\d{4}-\d{2}-\d{2}\s*\|/m.test(text)) {
+    fail(`台账结构漂移：${LEDGER} 存在日期开头的数据行但未识别到结果表（委派表表头须含「被委派方」列，自做表表头须为「日期 | 任务一句话 | 结果 | 备注」）`);
+  }
+  return rows;
 }
 
 function countIncidents() {
@@ -79,8 +92,11 @@ function countIncidents() {
 const GATE = { minSample: 20, minPassRate: 0.9, maxAvgRework: 0.3, minDelegated: 5, maxFallbackRate: 0.1 };
 
 function metrics(rows) {
-  const valid = rows.filter((r) => parseResult(r.result).kind !== 'pending' && parseResult(r.result).kind !== 'unknown');
-  const pending = rows.length - valid.length;
+  // 未知结果（结果列拼错/漏填）单列计数，不混进「待修」——待修=未闭环，未知=记录本身有问题（2026-09-24 口径分离）
+  const kinds = rows.map((r) => parseResult(r.result).kind);
+  const valid = rows.filter((_, i) => kinds[i] !== 'pending' && kinds[i] !== 'unknown');
+  const pending = kinds.filter((k) => k === 'pending').length;
+  const unknown = kinds.filter((k) => k === 'unknown').length;
   let pass = 0, reworkSum = 0, fallback = 0;
   for (const r of valid) {
     const p = parseResult(r.result);
@@ -92,6 +108,7 @@ function metrics(rows) {
   return {
     total: valid.length,
     pending,
+    unknown,
     pass,
     passRate: valid.length ? pass / valid.length : null,
     reworkSum,
@@ -152,16 +169,16 @@ function main() {
     const m = metrics(byMonth[ym]);
     const g = gate(m, incidents[ym] || 0);
     console.log(`## ${ym}`);
-    console.log(`  有效任务 ${m.total}（待修 ${m.pending}）｜一次通过 ${m.pass}（${fmtRate(m.passRate)}）｜返工总次数 ${m.reworkSum}（平均 ${fmtNum(m.avgRework)}）｜主兜底 ${m.fallback}/${m.delegatedValid}（${fmtRate(m.fallbackRate)}）｜incident ${incidents[ym] || 0} 起`);
+    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} |`);
+    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}` : ''} |`);
   }
 
   if (!argMonth && rows.length) {
     const m = metrics(rows);
     console.log(`## 全量累计`);
-    console.log(`  有效任务 ${m.total}（待修 ${m.pending}）｜一次通过 ${fmtRate(m.passRate)}｜平均返工 ${fmtNum(m.avgRework)}｜主兜底 ${fmtRate(m.fallbackRate)}｜incident 合计 ${Object.values(incidents).reduce((a, b) => a + b, 0)} 起\n`);
+    console.log(`  有效任务 ${m.total}（待修 ${m.pending}${m.unknown ? `、未知结果 ${m.unknown}` : ''}）｜一次通过 ${fmtRate(m.passRate)}｜平均返工 ${fmtNum(m.avgRework)}｜主兜底 ${fmtRate(m.fallbackRate)}｜incident 合计 ${Object.values(incidents).reduce((a, b) => a + b, 0)} 起\n`);
   }
 
   console.log(`## 可粘贴快照行（粘到 workflow/delegations.md §月度聚合快照）`);

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// agg-delegations.cjs 的 fixture 驱动测试（2026-09-24 随「台账结构漂移静默吞数据」修复引入）
+// 被测脚本以 __dirname 定位台账，故复制脚本进临时根（<tmp>/.agents/scripts/）后以 cwd=<tmp> 运行。
+// 断言：①节标题缺失但表头合规 → 数据照常入账（本次事故形态回归）；②日期数据行在但表头不可识别 → exit 1 fail-loud；
+//       ③空台账（表头合规、无数据行）→ exit 0 且提示为空。
+// 用法：node .agents/scripts/agg-delegations.test.mjs（在仓库任意目录执行均可）
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(SCRIPT_DIR, 'agg-delegations.cjs');
+const USAGE = '用法：node .agents/scripts/agg-delegations.test.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 mkfix = (ledgerText) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agg-delegations-test-'));
+  fs.mkdirSync(path.join(root, '.agents', 'scripts'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'workflow', 'incidents'), { recursive: true });
+  fs.writeFileSync(path.join(root, 'workflow', 'delegations.md'), ledgerText, 'utf8');
+  fs.copyFileSync(SRC, path.join(root, '.agents', 'scripts', 'agg-delegations.cjs'));
+  return root;
+};
+const runAgg = (root) => spawnSync(process.execPath, [path.join(root, '.agents', 'scripts', 'agg-delegations.cjs')], { cwd: root, encoding: 'utf8' });
+
+// ---- 场景 1：无 `## ` 节标题、表头合规（2026-09-24 事故形态）→ 数据照常入账 ----
+{
+  const root = mkfix([
+    '# 量化证据台账（fixture）',
+    '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 |',
+    '|------|----------------|------------|------|------|',
+    '| 2026-09-23 | general-purpose(子代理) | 示例委派任务 | 一次通过 | fixture |',
+    '| 2026-09-24 | executor(子代理) | 结果列拼错的示例行 | 成功 | fixture |',
+    '',
+  ].join('\n'));
+  const r = runAgg(root);
+  check('场景 1：节标题缺失 + 表头合规 → exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 1：数据行入账（有效任务 1，非「台账为空」）', /有效任务 1（/.test(r.stdout) && !r.stdout.includes('台账为空'), r.stdout);
+  check('场景 1：未知结果单列计数（不混入待修，2026-09-24 口径分离）', r.stdout.includes('待修 0、未知结果 1'), r.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 2：日期数据行在但表头不可识别 → fail-loud（不再静默「台账为空」）----
+{
+  const root = mkfix([
+    '# 量化证据台账（fixture）',
+    '',
+    '| when | who | what | result | note |',
+    '|------|-----|------|--------|------|',
+    '| 2026-09-23 | executor | 表头被改的行 | 一次通过 | fixture |',
+    '',
+  ].join('\n'));
+  const r = runAgg(root);
+  check('场景 2：表头不可识别 → exit 1', r.status === 1, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 2：报错点名结构漂移', (r.stderr || '').includes('结构漂移'), r.stderr);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- 场景 3：空台账（表头合规、无数据行）→ exit 0 且提示为空 ----
+{
+  const root = mkfix([
+    '# 量化证据台账（fixture）',
+    '',
+    '## 委派结果',
+    '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 |',
+    '|------|----------------|------------|------|------|',
+    '',
+    '## 自做任务结果',
+    '',
+    '| 日期 | 任务一句话 | 结果 | 备注 |',
+    '|------|------------|------|------|',
+    '',
+  ].join('\n'));
+  const r = runAgg(root);
+  check('场景 3：空台账 → exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  check('场景 3：提示台账为空', r.stdout.includes('台账为空'), r.stdout);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) {
+  console.log(`\n${USAGE}`);
+  process.exit(1);
+}
+process.exit(0);

package/templates/_agents/scripts/check-loop.sh

@@ -25,6 +25,8 @@
 # 上限=瘦身后实测+余量,新增须先删除或下沉——一进一出)
 # 14. 新 done 的 spec/plan 须在 git 历史里出现过 `状态: approved`(确认环节留痕,2026-09-22 papercut;
 # 生效 2026-09-23=规则发布次日,不追溯发布当日已在途文档,口径同检查 12)[warning]
+#    2026-09-23 裁定演进(源自 Shipyard 回流):本检查恒为 advisory,永不升级 hard-block;确认后主智能体须立即
+#    docs(*) 提交 approved 留痕(根 AGENTS.md 提交约定),本警告即「遗漏提交」提醒——直跳 done 无留痕仍属流程瑕疵,仅提示
 #
 # 文档协议（2026-09-13 结构化改造,papercut #4 防复发）:
 #   状态/级别/日期/发现/流程/确认结果/确认时间 等机器字段一律由文件头 YAML frontmatter（受限子集）承载:
@@ -763,6 +765,8 @@ fi
 # --- 14. 新 done 的 spec/plan 须在 git 历史里出现过 approved(确认环节留痕)[warning] ---
 # 规则生效 2026-09-22(papercut 2026-09-22,用户点名):`approved` 是确认环节的机器可见态,`done` 只在关单出现;
 # 从 draft 直跳 done 会让确认环节在文档里消失——而检查 5 视 approved/done 同权,此前无任何门禁能发现跳态。
+# 2026-09-23 裁定演进(源自 Shipyard 回流):此警告恒为 advisory、永不升级 hard-block;确认后 docs(*) 提交留痕为必做
+# (根 AGENTS.md 提交约定),本警告即「遗漏提交」提醒。备注含「存量确认态豁免（…）」声明者出账(口径同检查 8)。
 # 作用域:日期 ≥ 2026-09-23(生效次日,不追溯发布当日已在途的并行文档;存量同理——避免对无法诚实补正的旧件刷屏,
 # 口径同检查 12:frontmatter 日期/发现 → 文件名前缀回退)。
 # 判据:当前状态为 done 的文件,须在 git 历史中至少有一个提交版本的**行首**出现过 `状态: approved`
@@ -781,6 +785,8 @@ if git rev-parse --git-dir >/dev/null 2>&1 && git rev-parse -q --verify HEAD >/d
  2026-09-2[3-9]|2026-09-[3-9][0-9]|2026-1[0-2]-[0-3][0-9]|202[7-9]-*|20[3-9][0-9]-*|2[1-9][0-9][0-9]-*) ;;
  *) continue ;;
  esac
+ # 出账:备注含「存量确认态豁免（…）」声明者跳过(口径同检查 8 的存量对账豁免;留痕规则生效前的存量 done 件)
+ [ -n "$(grep -m1 '存量确认态豁免（' "$f" 2>/dev/null)" ] && continue
  [ -n "$(git log -1 --format=%H -G'^状态:[[:space:]]*approved' -- "$f" 2>/dev/null)" ] && continue
  warnings="$warnings
 - [WARN 确认态缺失] $base 状态已 done 但 git 历史中从未出现行首「状态: approved」——确认环节未留痕(draft 直跳 done)"