agentic-flow-kit 1.8.7 → 2.1.0

package/templates/_agents/scripts/mechanism-retire-watch.mjs

@@ -1,183 +0,0 @@
-#!/usr/bin/env node
-// mechanism-retire-watch.mjs — 机制退役催办自动化（2026-10-14 源仓 L5 自举接线 1b/1c；2026-10-16 回灌 kit）
-// 用途：读机制台账「退役阈值/最近触发」+ judgments 聚合，阈值触达自动产动作项——让机制的「死」与「生」同样强制。
-//   自动化的是**感知/排序**（谁触达了阈值），处置仍人放行（改状态/删代码走人 + 一进一出）。
-// 口径单源：.agents/mechanism-registry.md 列序（机制|门禁位置|触发统计口径|退役阈值|最近触发|状态|处置期限）
-//   与 .agents/judgments.jsonl（check-loop 每次真实运行落账，per-rule WARN/BLOCK 计数）。
-// 判定（确定性，无 LLM）：
-//   ① 现役行 + 阈值形态「连续 N 月 = 0」+ 口径列含「规则名」→ 以有数据的末月为终点取 N 个日历月，缺月不算零命中，全 0 即触达 → 动作项。
-//   ② 待退役行 + 处置期限为日期且已过 → 动作项（逾期）。
-//   ③ 其余阈值形态（不退役主干 / 使用率型 / 数据源型）→ 非自动可判，仅计数，交人工月判。
-//   缺月不算零命中（2026-10-15 源仓修正）：漏跑数月后陈旧月份不得凑成「连续」——日历窗口内有缺月即
-//   交人工判，不产触达动作（与 agg-judgments --retire-candidates 的「数据月」口径互补：彼按有数据月，
-//   此按日历连续）。
-// 退出码恒 0（催办报告不该阻断调度器；测量失败打 [ERROR] 行）。
-// 用法：node .agents/scripts/mechanism-retire-watch.mjs [--json] [--root <仓库根>] [--now <ISO 日期>]
-// 测试：node .agents/scripts/mechanism-retire-watch.test.mjs（纯函数 evaluate 进程内断言）
-// kit 适配（源仓→kit）：台账路径 `.agents/config/mechanism-registry.md` → kit 平铺
-//   `.agents/mechanism-registry.md`（同 check-registry.mjs 检查 22 口径）。
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { aggFromRows } from './agg-judgments.mjs';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const argv = process.argv.slice(2);
-const argOf = (k) => { const i = argv.indexOf(k); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : ''; };
-const asJson = argv.includes('--json');
-const ROOT = path.resolve(argOf('--root') || path.join(SCRIPT_DIR, '..', '..'));
-const NOW = argOf('--now') ? new Date(argOf('--now')) : new Date();
-
-const REGISTRY_REL = path.join('.agents', 'mechanism-registry.md');
-const LEDGER_REL = path.join('.agents', 'judgments.jsonl');
-
-// parseRegistry(text)：7 列管道表 → 行对象数组。列序固定（check-loop §22 按此解析）。
-export function parseRegistry(text) {
-  const rows = [];
-  for (const l of String(text).split(/\r?\n/)) {
-    if (!/^\|/.test(l)) continue;
-    if (/^\|[\s:|-]+\|?\s*$/.test(l)) continue; // 分隔行
-    const cells = l.split('|').slice(1, -1).map((c) => c.trim());
-    if (cells.length !== 7) continue;
-    if (cells[0] === '机制') continue; // 表头
-    const [name, gate, criterion, threshold, lastTrigger, status, deadline] = cells;
-    rows.push({ name, gate, criterion, threshold, lastTrigger, status, deadline });
-  }
-  return rows;
-}
-
-// ruleNamesOf(criterion)：从「触发统计口径」列抽「」内规则名（/ 分隔）。无「」= 无法自动映射。
-export function ruleNamesOf(criterion) {
-  const names = [];
-  for (const m of String(criterion).matchAll(/「([^」]+)」/g)) {
-    for (const n of m[1].split('/')) {
-      const t = n.trim();
-      if (t) names.push(t);
-    }
-  }
-  return names;
-}
-
-// zeroMonthsOf(threshold)：阈值形态「连续 N 月 = 0」→ N；否则 null（非自动可判）。
-export function zeroMonthsOf(threshold) {
-  const m = String(threshold).match(/连续\s*(\d+)\s*月\s*=\s*0/);
-  return m ? Number(m[1]) : null;
-}
-
-// localDay(d)：本地日历日 YYYY-MM-DD。期限比较不用 UTC 零点，避免北京时 08:00 后把当天判逾期。
-export function localDay(d) {
-  const dt = d instanceof Date ? d : new Date(d);
-  const m = String(dt.getMonth() + 1).padStart(2, '0');
-  const day = String(dt.getDate()).padStart(2, '0');
-  return `${dt.getFullYear()}-${m}-${day}`;
-}
-
-// calendarWindow(endYm, n)：以有数据的末月为终点，向前取 n 个日历月（含终点）。
-export function calendarWindow(endYm, n) {
-  const [y, m] = String(endYm).split('-').map(Number);
-  const out = [];
-  for (let i = n - 1; i >= 0; i--) {
-    const d = new Date(Date.UTC(y, m - 1 - i, 1));
-    out.push(`${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`);
-  }
-  return out;
-}
-
-// evaluate(registryRows, judgmentRows, now)：纯函数——产动作项。测试进程内断言。
-export function evaluate(registryRows, judgmentRows, now = new Date()) {
-  const { byMonth } = aggFromRows(judgmentRows || [], null);
-  const months = Object.keys(byMonth).sort(); // 升序
-  const actions = [];
-  const notAuto = [];
-
-  for (const r of registryRows) {
-    if (r.status === '已退役') continue;
-
-    if (r.status === '待退役') {
-      const d = String(r.deadline).match(/\d{4}-\d{2}-\d{2}/);
-      if (d && localDay(now) > d[0]) {
-        actions.push({ kind: 'overdue', name: r.name, detail: `待退役处置期限 ${d[0]} 已过（今 ${localDay(now)}）——按台账维护纪律「退役动作」当日删代码+测试+更新本表` });
-      } else if (!d) {
-        actions.push({ kind: 'no-deadline', name: r.name, detail: `待退役但处置期限非日期（${r.deadline || '空'}）——补时间表或改回现役` });
-      }
-      continue;
-    }
-
-    // 现役
-    const n = zeroMonthsOf(r.threshold);
-    const rules = ruleNamesOf(r.criterion);
-    if (n === null) { notAuto.push({ name: r.name, reason: '阈值形态非「连续 N 月 = 0」' }); continue; }
-    if (!rules.length) { notAuto.push({ name: r.name, reason: '口径列未列规则名（无法映射 judgments）' }); continue; }
-    if (months.length < n) { notAuto.push({ name: r.name, reason: `judgments 仅 ${months.length} 月 < 阈值 ${n} 月（数据不足）` }); continue; }
-
-    // 日历连续：缺月不算零命中（漏跑数月后陈旧月份不得凑成「连续」）。
-    const window = calendarWindow(months[months.length - 1], n);
-    const missing = window.filter((ym) => !byMonth[ym]);
-    if (missing.length) {
-      notAuto.push({ name: r.name, reason: `日历窗口 ${window.join(' / ')} 缺月 ${missing.join(' / ')}（断档不算零命中）` });
-      continue;
-    }
-    const hits = window.map((ym) => {
-      const cell = byMonth[ym].rules;
-      let c = 0;
-      for (const rule of rules) {
-        const e = cell[rule];
-        if (e) c += (e.WARN || 0) + (e.BLOCK || 0);
-      }
-      return { ym, count: c };
-    });
-    const total = hits.reduce((s, h) => s + h.count, 0);
-    if (total === 0) {
-      actions.push({ kind: 'threshold', name: r.name, detail: `连续 ${n} 月零触发（${window.join(' / ')}；规则 ${rules.join('、')}）——阈值触达，评估退役（改状态「待退役」并填处置期限）` });
-    }
-  }
-  return { actions, notAuto, months, monthCount: months.length };
-}
-
-function readJudgments(root) {
-  const p = path.join(root, LEDGER_REL);
-  if (!fs.existsSync(p)) return { rows: [], missing: true };
-  const rows = [];
-  for (const line of fs.readFileSync(p, 'utf8').split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    try { rows.push(JSON.parse(line)); } catch { /* 坏行跳过，不中断 */ }
-  }
-  return { rows, missing: false };
-}
-
-function main() {
-  const regPath = path.join(ROOT, REGISTRY_REL);
-  if (!fs.existsSync(regPath)) {
-    console.error(`[ERROR] mechanism-retire-watch: 台账不存在 ${REGISTRY_REL}`);
-    if (asJson) console.log(JSON.stringify({ error: 'registry-missing', actions: [] }, null, 2));
-    process.exit(0);
-  }
-  const registryRows = parseRegistry(fs.readFileSync(regPath, 'utf8'));
-  const { rows: judgmentRows, missing } = readJudgments(ROOT);
-  const { actions, notAuto, monthCount } = evaluate(registryRows, judgmentRows, NOW);
-
-  if (asJson) {
-    console.log(JSON.stringify({ registryRows: registryRows.length, judgmentMonths: monthCount, judgmentsMissing: missing, actions, notAuto }, null, 2));
-    return;
-  }
-
-  console.log(`# 机制退役催办（${NOW.toISOString()}）`);
-  console.log('');
-  console.log(`台账 ${REGISTRY_REL}｜机制行 ${registryRows.length}｜judgments 月数 ${monthCount}${missing ? '（台账缺失——尚无运行记录）' : ''}`);
-  console.log('');
-  if (!actions.length) {
-    console.log('✅ 无阈值触达 / 无逾期——本轮无动作项。');
-  } else {
-    console.log(`## 动作项 ${actions.length} 条`);
-    for (const a of actions) console.log(`- [${a.kind}] ${a.name}：${a.detail}`);
-  }
-  if (notAuto.length) {
-    console.log('');
-    console.log(`## 非自动可判（${notAuto.length} 条，交人工月判）`);
-    for (const x of notAuto) console.log(`- ${x.name}：${x.reason}`);
-  }
-  console.log('');
-  console.log('> 处置仍人放行：改状态/删代码走人 + 一进一出（台账维护纪律）。本报告不自动改文件。');
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] || '').href) main();

package/templates/_agents/scripts/mechanism-retire-watch.test.mjs

@@ -1,114 +0,0 @@
-#!/usr/bin/env node
-// mechanism-retire-watch.test.mjs — 1b 机制退役催办纯函数套件（2026-10-14 L5 自举接线 1b）
-// parseRegistry / ruleNamesOf / zeroMonthsOf / evaluate 进程内断言。
-import { parseRegistry, ruleNamesOf, zeroMonthsOf, evaluate } from './mechanism-retire-watch.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 : ''}`); }
-};
-
-// ---- S1 parseRegistry ----
-{
-  const text = [
-    '| 机制 | 门禁位置 | 触发统计口径 | 退役阈值 | 最近触发 | 状态 | 处置期限 |',
-    '|---|---|---|---|---|---|---|',
-    '| 甲门 | check-loop §1 | WARN「甲规则」计数（月） | 连续 6 月 = 0 → 评估退役 | 2026-10 在用 | 现役 | — |',
-    '| 乙门 | check-loop §2 | hard 计数 | 不退役（主干） | 2026-10 | 现役 | — |',
-    '| 丙门 | check-loop §3 | WARN 计数 | 连续 6 月 = 0 | 2026-10 | 待退役 | 2026-01-01 |',
-    '| 坏行 | 少列 |',
-  ].join('\n');
-  const rows = parseRegistry(text);
-  check('S1 只取 7 列数据行（表头/分隔/坏行剔除）', rows.length === 3, String(rows.length));
-  check('S1 列序正确', rows[0].name === '甲门' && rows[0].status === '现役' && rows[0].deadline === '—', JSON.stringify(rows[0]));
-  check('S1 待退役行期限解析', rows[2].status === '待退役' && rows[2].deadline === '2026-01-01');
-}
-
-// ---- S2 ruleNamesOf ----
-check('S2 单规则名', ruleNamesOf('WARN「模板未填」计数（月）').join(',') === '模板未填');
-check('S2 斜杠分隔多规则', ruleNamesOf('WARN「预判类型不符/预判级别不符/预判字段不可解析」计数').join(',') === '预判类型不符,预判级别不符,预判字段不可解析');
-check('S2 无「」→ 空', ruleNamesOf('hard/WARN 计数（月）').length === 0);
-
-// ---- S3 zeroMonthsOf ----
-check('S3 连续 6 月 = 0', zeroMonthsOf('连续 6 月 = 0 → 评估退役') === 6);
-check('S3 带前缀仍解析', zeroMonthsOf('WARN 命中连续 6 月 = 0 且新增预判字段停滞 → 评估退役') === 6);
-check('S3 非零阈值形态 → null', zeroMonthsOf('不退役（防伪主干）') === null);
-check('S3 使用率型 → null', zeroMonthsOf('<10% 且无新增 → 退役双协议') === null);
-
-// ---- S4 evaluate：阈值触达 ----
-{
-  const reg = [{ name: '甲门', criterion: 'WARN「甲规则」计数', threshold: '连续 2 月 = 0 → 评估退役', status: '现役', deadline: '—' }];
-  const j = [
-    { ts: '2026-08-01T00:00:00Z', rules: [{ rule: '甲规则', level: 'WARN', count: 0 }] },
-    { ts: '2026-09-01T00:00:00Z', rules: [] },
-  ];
-  const r = evaluate(reg, j, new Date('2026-10-14'));
-  check('S4 连续 2 月零触发 → 动作项', r.actions.length === 1 && r.actions[0].kind === 'threshold', JSON.stringify(r.actions));
-  check('S4 动作项含窗口与规则名', /2026-08 \/ 2026-09/.test(r.actions[0].detail) && /甲规则/.test(r.actions[0].detail), r.actions[0].detail);
-}
-
-// ---- S5 evaluate：窗口内有触发 → 不产动作项 ----
-{
-  const reg = [{ name: '甲门', criterion: 'WARN「甲规则」计数', threshold: '连续 2 月 = 0', status: '现役', deadline: '—' }];
-  const j = [
-    { ts: '2026-08-01T00:00:00Z', rules: [{ rule: '甲规则', level: 'WARN', count: 1 }] },
-    { ts: '2026-09-01T00:00:00Z', rules: [] },
-  ];
-  const r = evaluate(reg, j, new Date('2026-10-14'));
-  check('S5 窗口内命中 → 无动作项', r.actions.length === 0, JSON.stringify(r.actions));
-}
-
-// ---- S6 evaluate：数据不足 / 无规则名 → notAuto ----
-{
-  const reg = [
-    { name: '甲门', criterion: 'WARN「甲规则」计数', threshold: '连续 6 月 = 0', status: '现役', deadline: '—' },
-    { name: '乙门', criterion: 'hard 计数', threshold: '连续 6 月 = 0', status: '现役', deadline: '—' },
-    { name: '丙门', criterion: 'WARN「丙规则」计数', threshold: '不退役（主干）', status: '现役', deadline: '—' },
-  ];
-  const j = [{ ts: '2026-09-01T00:00:00Z', rules: [] }];
-  const r = evaluate(reg, j, new Date('2026-10-14'));
-  check('S6 数据不足 → notAuto', r.notAuto.some((x) => x.name === '甲门' && /数据不足/.test(x.reason)), JSON.stringify(r.notAuto));
-  check('S6 无规则名 → notAuto', r.notAuto.some((x) => x.name === '乙门' && /未列规则名/.test(x.reason)));
-  check('S6 非零阈值形态 → notAuto', r.notAuto.some((x) => x.name === '丙门' && /非「连续/.test(x.reason)));
-  check('S6 无动作项', r.actions.length === 0);
-}
-
-// ---- S7 evaluate：待退役逾期 / 缺期限 ----
-{
-  const reg = [
-    { name: '甲门', criterion: '', threshold: '', status: '待退役', deadline: '2026-01-01' },
-    { name: '乙门', criterion: '', threshold: '', status: '待退役', deadline: '下批次' },
-    { name: '丙门', criterion: '', threshold: '', status: '已退役', deadline: '—' },
-  ];
-  const r = evaluate(reg, [], new Date('2026-10-14'));
-  check('S7 逾期 → overdue', r.actions.some((a) => a.kind === 'overdue' && a.name === '甲门'), JSON.stringify(r.actions));
-  check('S7 非日期期限 → no-deadline', r.actions.some((a) => a.kind === 'no-deadline' && a.name === '乙门'));
-  check('S7 已退役行跳过', !r.actions.some((a) => a.name === '丙门'));
-}
-// ---- S7b：期限当天不逾期（本地日，不当天 08:00 后提前催）----
-{
-  const reg = [{ name: '甲门', criterion: '', threshold: '', status: '待退役', deadline: '2026-10-14' }];
-  const now = new Date(2026, 9, 14, 9, 0, 0);
-  const r = evaluate(reg, [], now);
-  check('S7b 期限当天本地 09:00 不逾期', r.actions.length === 0, JSON.stringify(r.actions));
-}
-// ---- S4b：有数据月不连续 → 缺月不算零命中 ----
-{
-  const reg = [{ name: '甲门', criterion: 'WARN「甲规则」计数', threshold: '连续 2 月 = 0 → 评估退役', status: '现役', deadline: '—' }];
-  const j = [
-    { ts: '2026-08-01T00:00:00Z', rules: [] },
-    { ts: '2026-10-01T00:00:00Z', rules: [] },
-  ];
-  const r = evaluate(reg, j, new Date('2026-10-14T00:00:00Z'));
-  check('S4b 8 月与 10 月之间缺 9 月 → 不产退役动作', r.actions.length === 0, JSON.stringify(r.actions));
-  check('S4b 缺月记入 notAuto', r.notAuto.some((x) => x.name === '甲门' && /缺月/.test(x.reason) && /2026-09/.test(x.reason)), JSON.stringify(r.notAuto));
-}
-
-// ---- S8 空入参 ----
-check('S8 空台账 → 无动作项', evaluate([], [], new Date()).actions.length === 0);
-check('S8 null judgments 不 throw', evaluate([], null, new Date()).actions.length === 0);
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/papercut-debt-controller.mjs

@@ -1,141 +0,0 @@
-#!/usr/bin/env node
-// papercut-debt-controller.mjs — 回路控制器（2026-10-07 papercut-debt 回路 Phase D；B10a 自
-//   Shipyard.Material 回灌——排序键与 scope gate 逐字对齐，出处沿革留痕在包源仓 git 历史与 CHANGELOG）
-// 用途：把传感器的测量变成"本轮修哪一条"。确定性选取，无随机、无 LLM 判断。
-// 口径单源：.agents/loop/papercut-debt/DESIGN.md §3（改排序键先改设计文件）。
-// 排序键（依次比较）：① 命中次数降序（台账文件头自身规则：第 2 次命中须升级为 docs 修复）
-//                ② 日期降序（近期痛点更可能仍成立）      ③ 原行序升序（完全平手时保可复现）
-// Scope gate：拟修明确指向 backend/ frontend/ tests/ wiki/ sqlcmd/ db_tool，或含 数据库/DDL/DROP 字样的条目本轮跳过
-//   （执行器边界＝文档面，见 DESIGN §4）。跳过的条目照列，供人工决定是否单独授权。
-// 单轮只取 1 条：独立复核有成本（L2/L3 须独立复核），一次给 3 条审不动。
-// 用法：node .agents/scripts/papercut-debt-controller.mjs [--json] [--top <n>] [--root <仓库根>]
-// 退出码：0 正常（含"无目标"与"全部被 scope gate 拦"）；2 = 测量不可用（debt 未知）。
-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 argv = process.argv.slice(2);
-const argOf = (k) => { const i = argv.indexOf(k); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : ''; };
-const asJson = argv.includes('--json');
-const TOP = Math.max(1, Number(argOf('--top')) || 3);
-const ROOT = path.resolve(argOf('--root') || path.join(SCRIPT_DIR, '..', '..'));
-
-// Scope gate 关键词：命中即视为「要改源码 / 连库」，超出文档面授权
-const OUT_OF_SCOPE = /(^|[^\w/])(backend|frontend|tests|wiki)\/|sqlcmd|db_tool\.py|数据库|DDL|\bDROP\b/i;
-// 「同上 X」承接上一行的路径，无法独立判定存在性——需人读后定性，不作为自动目标
-const STALE_RE = /^同上两处|^同上/;
-
-// 口径单源在传感器（settled = ✅ 或 ⏸带理由；stale 判定也在传感器）。
-//   本脚本刻意**不复制**任何判定正则，而是 import 传感器复用其扫描面——两处各判一次必然漂移
-//   （首轮实证：传感器按 ✅ 判债、控制器也按 ✅ 选目标，⏸ 暂缓条目被反复选中导致空转——
-//   留痕在包源仓 git 历史与 CHANGELOG）。
-//   传感器 main() 仅在直接执行时运行，import 时只导出 scan()。
-import { scan as sensorScan } from './papercut-debt-sensor.mjs';
-
-function measure() {
-  const ledger = path.join(ROOT, 'workflow', 'papercuts.md');
-  if (!fs.existsSync(ledger)) throw new Error(`台账不存在: ${ledger}`);
-  // 复用传感器解析面（含 ✅ / ⏸带理由 / 命中次数 / stale 判定），此处只做排序与 scope gate。
-  const rows = sensorScan(ROOT).map((r) => ({
-    ...r,
-    // scope gate 需读全文：location + proposedFix（拟修列可能含管道符，传感器已并回）
-    fullText: `${r.location} ${r.proposedFix}`,
-  }));
-  return { ledger, rows };
-}
-
-function rank(a, b) {
-  if (a.hits !== b.hits) return b.hits - a.hits;
-  if (a.date !== b.date) return a.date < b.date ? 1 : -1; // 日期降序
-  return a.line - b.line;                                   // 原行序升序
-}
-
-function gateReason(r) {
-  const m = r.fullText.match(OUT_OF_SCOPE);
-  if (!m) return null;
-  return `拟修触及源码/数据库面（命中「${(m[2] || m[1] || m[0]).trim()}」）`;
-}
-
-function main() {
-  let m;
-  try {
-    m = measure();
-  } catch (e) {
-    console.error(`[ERROR] papercut-debt-controller: 测量不可用——${e.message}`);
-    if (asJson) console.log(JSON.stringify({ error: e.message, target: null }, null, 2));
-    process.exit(2);
-  }
-
-  const unresolved = m.rows.filter((r) => !r.settled);
-  const debt = unresolved.length;
-  const inScope = [];
-  const skipped = [];
-  const needsHuman = [];
-  for (const r of unresolved) {
-    const why = gateReason(r);
-    if (why) { skipped.push({ ...r, skipReason: why }); continue; }
-    // stale 与「同上 X」承接行：需要人读后定性（已失效 / 或需重定位），不作为自动修复目标
-    const isStale = r.stale;
-    const isDangling = STALE_RE.test(r.location);
-    if (isStale || isDangling) {
-      needsHuman.push({ ...r, needReason: isStale ? '位置列路径已不存在，需确认是否已失效' : '「同上」承接行，路径需从上条解析后才能判定' });
-      continue;
-    }
-    inScope.push(r);
-  }
-  inScope.sort(rank);
-  const target = inScope[0] || null;
-  const queue = inScope.slice(0, TOP);
-
-  if (asJson) {
-    console.log(JSON.stringify({
-      ledger: path.relative(ROOT, m.ledger).split(path.sep).join('/'),
-      debt, total: m.rows.length,
-      target, queue,
-      skippedOutOfScope: skipped,
-      needsHuman,
-      achieved: debt === 0,
-    }, null, 2));
-    return;
-  }
-
-  console.log(`控制器 —— debt ${debt} · 在选 ${inScope.length} · scope-gate 拦下 ${skipped.length} · 待人工定性 ${needsHuman.length}`);
-  if (debt === 0) {
-    console.log('✅ debt = 0，设定点已达成——本轮无目标，执行器不应动手。');
-    return;
-  }
-  if (!target) {
-    console.log('⚠️ 所有未升级条目均被 scope gate 拦下（执行器边界＝文档面）——需人工决定是否单独授权。');
-    for (const s of skipped) console.log(`  L${s.line} [${s.date}] ${s.location} —— ${s.skipReason}`);
-    return;
-  }
-
-  console.log('');
-  console.log('本轮目标（top-1）:');
-  console.log(`  行号      L${target.line}（workflow/papercuts.md）`);
-  console.log(`  日期      ${target.date}`);
-  console.log(`  命中次数  ${target.hits}`);
-  console.log(`  位置      ${target.location}`);
-  console.log(`  症状      ${target.symptom.slice(0, 200)}${target.symptom.length > 200 ? '…' : ''}`);
-  console.log(`  拟修      ${target.proposedFix.slice(0, 300)}${target.proposedFix.length > 300 ? '…' : ''}`);
-  console.log('');
-  console.log(`后续候选（本轮不做，供你改指令时直接点名）:`);
-  for (const q of queue.slice(1)) {
-    console.log(`  L${q.line} [${q.date}] hits=${q.hits} ${q.location}`);
-  }
-  if (skipped.length) {
-    console.log('');
-    console.log('已按 scope gate 跳过（要改源码/连库，需你单独授权）:');
-    for (const s of skipped) console.log(`  L${s.line} [${s.date}] ${s.location} —— ${s.skipReason}`);
-  }
-  if (needsHuman.length) {
-    console.log('');
-    console.log('待人工定性（不作为自动目标——请读后定性：判失效则标 ⏸ 暂缓+理由，判仍成立则补出可执行拟修）:');
-    for (const h of needsHuman) console.log(`  L${h.line} [${h.date}] ${h.location} —— ${h.needReason}`);
-  }
-  console.log('');
-  console.log('下一步：按 .agents/skills/papercut-fix/SKILL.md 执行（改完跑验证门，debt 应恰好 -1）。');
-}
-
-main();

package/templates/_agents/scripts/papercut-debt-controller.test.mjs

@@ -1,127 +0,0 @@
-#!/usr/bin/env node
-// papercut-debt-controller.test.mjs — 回路控制器 fixture（B10a 自源仓回灌随件测试；源仓无直测，
-//   kit 侧按「新增引擎脚本默认必须带同名 .test.mjs」立——排序键与 scope gate 防再同步漂移）
-// 覆盖：排序键三序（命中次数降序 > 日期降序 > 原行序升序）/ scope gate（源码/数据库面拦下照列）/
-//   stale 与「同上」承接行转待人工定性 / debt=0 达成态 / 全员被拦警示态 / 口径单源（不复制判定正则）/
-//   CLI 退出码（0 正常含无目标；2 测量不可用）与 --json 形状
-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 CLI = path.join(SCRIPT_DIR, 'papercut-debt-controller.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 mkroot = () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'papercut-ctrl-'));
-  // 位置列引用的文档面文件须真实存在——否则传感器 stale 判定（位置列路径全不存在）会把
-  // 条目转 needsHuman，排序键 / scope gate 场景测不到目标选取
-  for (const p of ['.agents/commands', '.agents/scripts']) {
-    fs.mkdirSync(path.join(root, ...p.split('/')), { recursive: true });
-  }
-  fs.writeFileSync(path.join(root, '.agents', 'commands', 'a.md'), '# a\n', 'utf8');
-  fs.writeFileSync(path.join(root, '.agents', 'commands', 'b.md'), '# b\n', 'utf8');
-  fs.writeFileSync(path.join(root, '.agents', 'commands', 'c.md'), '# c\n', 'utf8');
-  fs.mkdirSync(path.join(root, 'workflow'), { recursive: true });
-  return root;
-};
-const HEADER = '| 日期 | 位置 | 症状 | 拟修 |\n|------|------|------|------|\n';
-const writeLedger = (root, text) => fs.writeFileSync(path.join(root, 'workflow', 'papercuts.md'), text, 'utf8');
-const run = (root, ...extra) => spawnSync(process.execPath, [CLI, '--root', root, ...extra], { encoding: 'utf8' });
-
-// ---- S1 排序键：命中次数降序 > 日期降序 > 原行序升序 ----
-{
-  const root = mkroot();
-  writeLedger(root, HEADER
-    + '| 2026-10-01 | `.agents/commands/a.md` | 症状早 | 拟修早 |\n'                       // 行序 1，日期早，hits=1
-    + '| 2026-10-05 | `.agents/commands/b.md` | 症状新 | 拟修新 |\n'                       // 行序 2，日期新，hits=1 → 日期降序胜
-    + '| 2026-10-03 | `.agents/commands/c.md` | 第 2 次命中：症状复发 | 拟修复发 |\n');    // hits=2 → 恒胜
-  const r = run(root, '--json');
-  const j = JSON.parse(r.stdout || '{}');
-  check('S1a exit 0', r.status === 0, `status=${r.status} stderr=${String(r.stderr).slice(0, 120)}`);
-  check('S1b 主排序键 = 命中次数降序', j.target?.location === '`.agents/commands/c.md`', JSON.stringify(j.target?.location));
-  check('S1c 平手时日期降序（近期优先）', j.queue?.[1]?.location === '`.agents/commands/b.md`', JSON.stringify(j.queue?.map((q) => q.location)));
-  check('S1d 再平手原行序升序', j.queue?.[2]?.location === '`.agents/commands/a.md`');
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S2 scope gate：拟修触及源码/数据库面 → 拦下照列（不选为目标）----
-{
-  const root = mkroot();
-  writeLedger(root, HEADER
-    + '| 2026-10-01 | `.agents/commands/a.md` | 文档面症状 | 补一段说明 |\n'
-    + '| 2026-10-02 | `backend/api/x.py` | 源码面症状 | 修校验逻辑 |\n'
-    + '| 2026-10-03 | `tests/` | 测试面症状 | 补用例（涉及 DDL） |\n');
-  const r = run(root, '--json');
-  const j = JSON.parse(r.stdout || '{}');
-  check('S2a exit 0（含全部被拦态）', r.status === 0);
-  check('S2b scope gate 拦下 2 条（backend/ + tests/DDL）', j.skippedOutOfScope?.length === 2, JSON.stringify(j.skippedOutOfScope?.map((s) => s.location)));
-  check('S2c 在选目标只含文档面条目', j.target?.location === '`.agents/commands/a.md`', JSON.stringify(j.target?.location));
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S3 stale 与「同上」承接行 → needsHuman（不作为自动目标）----
-{
-  const root = mkroot();
-  writeLedger(root, HEADER
-    + '| 2026-10-01 | `.agents/commands/a.md` | 文档面症状甲 | 拟修甲 |\n'
-    + '| 2026-10-02 | `.agents/scripts/gone.mjs` | 路径已不存在 | 定性失效 |\n'
-    + '| 2026-10-03 | 同上两处 | 承接上行 | 定性重定位 |\n');
-  const r = run(root, '--json');
-  const j = JSON.parse(r.stdout || '{}');
-  check('S3a stale 与「同上」行转待人工', j.needsHuman?.length === 2, JSON.stringify(j.needsHuman?.map((h) => h.location)));
-  check('S3b 待人工条目不进 queue', !j.queue?.some((q) => q.location === '.agents/scripts/gone.mjs' || q.location === '同上两处'));
-  check('S3c 文档面条目照常在选', j.target?.location === '`.agents/commands/a.md`');
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S4 debt = 0：achieved 态（本轮无目标）----
-{
-  const root = mkroot();
-  writeLedger(root, HEADER
-    + '| 2026-10-01 | `.agents/commands/a.md` | 症状 | 拟修 ✅ 已升级修复(2026-10-02): 已改 |\n');
-  const r = run(root, '--json');
-  const j = JSON.parse(r.stdout || '{}');
-  check('S4a debt=0 → achieved true 且无目标', r.status === 0 && j.achieved === true && j.target === null && j.debt === 0,
-    JSON.stringify({ debt: j.debt, achieved: j.achieved }));
-  const r2 = run(root);
-  check('S4b 人读口径出「设定点已达成」', /设定点已达成/.test(r2.stdout));
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S5 全员被 scope gate 拦 → 警示态、exit 0 ----
-{
-  const root = mkroot();
-  writeLedger(root, HEADER + '| 2026-10-01 | `backend/api/x.py` | 源码面症状 | 修校验逻辑 |\n');
-  const r = run(root);
-  check('S5a 全员被拦：exit 0 + 需人工授权警示', r.status === 0 && /scope gate 拦下/.test(r.stdout) && /需人工决定是否单独授权/.test(r.stdout),
-    JSON.stringify({ status: r.status, stdout: String(r.stdout).slice(0, 200) }));
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S6 测量不可用：exit 2（debt 未知）----
-{
-  const root = mkroot();
-  const r = run(root, '--json');
-  const j = JSON.parse(r.stdout || '{}');
-  check('S6a 台账缺失 → exit 2 + error JSON', r.status === 2 && j.target === null && typeof j.error === 'string',
-    JSON.stringify({ status: r.status, error: j.error }));
-  fs.rmSync(root, { recursive: true, force: true });
-}
-
-// ---- S7 kit 适配钉子：口径单源（控制器不复制传感器判定正则）----
-{
-  const src = fs.readFileSync(CLI, 'utf8');
-  check('S7a 控制器 import 传感器 scan（不复制判定面）', /import\s*\{\s*scan as sensorScan\s*\}\s*from\s*'\.\/papercut-debt-sensor\.mjs'/.test(src));
-  check('S7b 控制器不复制 ✅/⏸ 判定正则', !/'✅'|"✅"/.test(src.replace(/^\/\/.*$/gm, '')));
-}
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);