agentic-flow-kit 1.7.16 → 1.8.1

package/templates/_agents/scripts/ledger-shards.test.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// ledger-shards.test.mjs — 分片读写单源 fixture（2026-10-13 ledger-shard-ledgers，自源仓回灌）
+// 覆盖：数据行判定（含节限定）/ 月提取 / 主台账∪分片读 / 迁移幂等 / 追加 / 表头自带 / fail-loud
+// kit 适配：表头签名用 kit 模板形态（delegations 末列「合入结论」、regression-checklist「incident | 条目 | 落点」）；
+//   S22 钉住 kit 适配（分片渲染须出 kit 表头、不出源仓表头——防再同步漂移）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  LEDGERS, isDataRow, inScope, monthOf, readLedger, readLedgerText,
+  splitMain, appendRows, shardPathFor, renderShard,
+} from './ledger-shards.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(), 'ledger-shards-'));
+  fs.mkdirSync(path.join(root, 'workflow'), { recursive: true });
+  return root;
+};
+const wf = (root, ...p) => path.join(root, 'workflow', ...p);
+
+// ---- S1 数据行判定：表格式（delegations/papercuts）----
+{
+  check('S1a delegations 数据行命中', isDataRow('delegations', '| 2026-10-01 | ui-verifier | 任务 | 一次通过 | 备注 |'));
+  check('S1b delegations 表头排除', !isDataRow('delegations', '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  check('S1c delegations 分隔行排除', !isDataRow('delegations', '|------|----------------|------------|------|------|----------|'));
+  check('S1d papercuts 数据行命中', isDataRow('papercuts', '| 2026-10-11 | `.agents/x.mjs` | 症状 | 拟修 |'));
+  check('S1e papercuts 表头排除', !isDataRow('papercuts', '| 日期 | 位置 | 症状 | 拟修 |'));
+  check('S1f 说明行不命中', !isDataRow('papercuts', '> 说明文字，非数据行'));
+}
+
+// ---- S2 节限定：regression-checklist 只迁「防复发验证」节 ----
+{
+  check('S2a 防复发验证节在范围内', inScope('regression-checklist', '防复发验证'));
+  check('S2b 模块节不在范围内', !inScope('regression-checklist', '回归必过'));
+  check('S2c 无 section 限定的台账恒在范围', inScope('delegations', '任意节') && inScope('papercuts', ''));
+  check('S2d 防复发数据行命中', isDataRow('regression-checklist', '| 2026-09-11 某事故 | 条目 | 落点 |'));
+  check('S2e 防复发表头排除', !isDataRow('regression-checklist', '| incident | 条目 | 落点 |'));
+}
+
+// ---- S3 月提取 ----
+{
+  check('S3a 表格式取首列日期月', monthOf('delegations', '| 2026-10-01 | x |') === '2026-10');
+  check('S3b 无日期返回空', monthOf('delegations', '| 无日期 | x |') === '');
+}
+
+// ---- S4 读：主台账 ∪ 分片 ----
+{
+  const root = mkroot();
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n\n| 日期 | 位置 | 症状 | 拟修 |\n|------|------|------|------|\n| 2026-10-01 | 主表行 | s | f |\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-09.md'), renderShard('papercuts', []) + '| 2026-09-01 | 分片行 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S4a 主台账 + 分片都读到', r.main.includes('主表行') && r.shards.length === 1 && r.all.includes('分片行'));
+  check('S4b all 含两侧', r.all.includes('主表行') && r.all.includes('分片行'));
+  check('S4c readLedgerText 等价 all', readLedgerText(root, 'papercuts') === r.all);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S5 读：分片按文件名排序（月序 = 时间序）----
+{
+  const root = mkroot();
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-10.md'), '| 2026-10-01 | 十月 | s | f |\n', 'utf8');
+  fs.writeFileSync(wf(root, 'papercuts.d', '2026-09.md'), '| 2026-09-01 | 九月 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S5 分片按文件名排序（09 在 10 前）', r.shards[0].file === '2026-09.md' && r.shards[1].file === '2026-10.md');
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S6 读：无分片目录 → 等价原读法（向后兼容）----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n| 2026-10-01 | 行 | s | f |\n', 'utf8');
+  const r = readLedger(root, 'papercuts');
+  check('S6 无分片目录 → shards 空、all = main', r.shards.length === 0 && r.all === r.main);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S7 迁移：主台账数据行按月迁出，非数据行保留 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '# 台账', '', '> 说明', '',
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 九月行 | s | f |',
+    '| 2026-10-01 | 十月行 | s | f |',
+    '| 2026-10-02 | 十月行2 | s | f |', '',
+  ].join('\n'), 'utf8');
+  const r = splitMain(root, 'papercuts');
+  check('S7a 迁移计数正确', r.moved['2026-09'] === 1 && r.moved['2026-10'] === 2, JSON.stringify(r.moved));
+  const main = fs.readFileSync(wf(root, 'papercuts.md'), 'utf8');
+  check('S7b 主台账保留说明与表头、无数据行', main.includes('# 台账') && main.includes('| 日期 |') && !main.includes('九月行') && !main.includes('十月行'));
+  check('S7c 分片自带表头', fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8').includes('| 日期 | 位置 | 症状 | 拟修 |'));
+  check('S7d 分片含数据行', fs.readFileSync(wf(root, 'papercuts.d', '2026-10.md'), 'utf8').includes('十月行2'));
+  // 迁移后读回：数据不丢
+  const back = readLedgerText(root, 'papercuts');
+  check('S7e 迁移后读回数据完整', back.includes('九月行') && back.includes('十月行') && back.includes('十月行2'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S8 迁移幂等：二次 split 无数据行可迁 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '| 日期 | 位置 | 症状 | 拟修 |\n|------|------|------|------|\n| 2026-10-01 | 行 | s | f |\n', 'utf8');
+  splitMain(root, 'papercuts');
+  const r2 = splitMain(root, 'papercuts');
+  check('S8 二次迁移 0 行（幂等）', Object.keys(r2.moved).length === 0, JSON.stringify(r2.moved));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S9 节限定迁移：regression-checklist 只迁防复发节 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'regression-checklist.md'), [
+    '# 回归清单', '',
+    '## 回归必过', '',
+    '| 模块 | 条目 | 依据 |', '|------|------|------|',
+    '| 模块条目（不迁） | x | y |', '',
+    '## 防复发验证', '',
+    '| incident | 条目 | 落点 |', '|----------|------|------|',
+    '| 2026-09-11 某事故 | 条目 | 落点 |', '',
+  ].join('\n'), 'utf8');
+  const r = splitMain(root, 'regression-checklist');
+  check('S9a 只迁防复发节 1 行', r.moved['2026-09'] === 1, JSON.stringify(r.moved));
+  const main = fs.readFileSync(wf(root, 'regression-checklist.md'), 'utf8');
+  check('S9b 模块节条目留守', main.includes('| 模块条目（不迁） | x | y |'));
+  check('S9c 防复发数据行已迁出', !main.includes('2026-09-11 某事故'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S10 appendRows：追加进指定月分片，缺表头则补 ----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 新行 | s | f |']);
+  const p = shardPathFor(root, 'papercuts', '2026-10');
+  check('S10a 分片文件已建', fs.existsSync(p));
+  const txt = fs.readFileSync(p, 'utf8');
+  check('S10b 自带表头 + 数据行', txt.includes('| 日期 | 位置 | 症状 | 拟修 |') && txt.includes('新行'));
+  appendRows(root, 'papercuts', ['| 2026-10-14 | 第二行 | s | f |']);
+  const txt2 = fs.readFileSync(p, 'utf8');
+  check('S10c 二次追加不重复表头', (txt2.match(/\| 日期 \| 位置/g) || []).length === 1 && txt2.includes('第二行'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S11 appendRows：显式 month 覆盖（无日期行）----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 无日期行 | s | f |'], { month: '2026-10' });
+  check('S11 显式 month 生效', fs.existsSync(shardPathFor(root, 'papercuts', '2026-10')));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S12 fail-loud：无法确定月 → 抛（不静默吞）----
+{
+  const root = mkroot();
+  let thrown = null;
+  try { appendRows(root, 'papercuts', ['| 无日期行 | s | f |']); } catch (e) { thrown = e; }
+  check('S12 无日期且未传 month → 抛错', thrown !== null && /无法确定分片月/.test(thrown.message));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S13 fail-loud：分片目录读取异常 → 抛 ----
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), '# 台账\n', 'utf8');
+  fs.mkdirSync(wf(root, 'papercuts.d'), { recursive: true });
+  fs.mkdirSync(wf(root, 'papercuts.d', 'bad.md')); // 目录冒充分片 → readFileSync EISDIR
+  let thrown = null;
+  try { readLedger(root, 'papercuts'); } catch (e) { thrown = e; }
+  check('S13 分片读失败 → 抛（不静默吞）', thrown !== null && /分片读取失败/.test(thrown.message));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S14 台账清单单源：三个台账都在册 ----
+{
+  check('S14 三台账在册', Object.keys(LEDGERS).sort().join(',') === 'delegations,papercuts,regression-checklist');
+}
+
+// ---- S15 delegations 双表分组：分片须两张表头都带且行归入正确表 ----
+// （2026-10-13 源仓迁移实测踩中：只带一张表头 → splitTables 把另一张的行按错表解析，240 任务塌成 100）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '# 台账', '',
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    '| 2026-09-01 | ui-verifier | 委派任务 | 一次通过 | 备注 | |',
+    '',
+    '## 自做任务结果', '',
+    '| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|------------|------|------|----------|',
+    '| 2026-09-02 | 自做任务 | 一次通过 | 备注 | |',
+    '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  check('S15a 分片含委派表头（kit 形态）', shard.includes('| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  check('S15b 分片含自做表头（kit 形态）', shard.includes('| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |'));
+  // 委派行须在委派表头之后、自做表头之前
+  const iDeleg = shard.indexOf('被委派方(模型)');
+  const iSelf = shard.indexOf('| 日期 | 任务一句话');
+  const iRow = shard.indexOf('委派任务');
+  check('S15c 委派行归入委派表（表头之后、自做表头之前）', iDeleg < iRow && iRow < iSelf, `deleg=${iDeleg} row=${iRow} self=${iSelf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S16 renderShard 分组：有行时不出空表头 ----
+{
+  const onlyDeleg = renderShard('delegations', [{ line: '| 2026-09-01 | a | b | c | d | e |', section: '委派结果' }]);
+  check('S16a 只有委派行 → 不出自做表头', onlyDeleg.includes('被委派方(模型)') && !onlyDeleg.includes('| 日期 | 任务一句话'));
+  const onlySelf = renderShard('delegations', [{ line: '| 2026-09-01 | b | c | d | e |', section: '自做任务结果' }]);
+  check('S16b 只有自做行 → 不出委派表头', !onlySelf.includes('被委派方(模型)') && onlySelf.includes('| 日期 | 任务一句话'));
+  const empty = renderShard('delegations', []);
+  check('S16c 无行 → 出全部表头（空分片骨架）', empty.includes('被委派方(模型)') && empty.includes('| 日期 | 任务一句话'));
+}
+
+// ---- S17 幂等：分片已存在时重跑 split 不重复追加 ----
+// （2026-10-13 源仓实测踩中：无去重时二次 split 把 58 行重复写入，120 行 vs 62 行）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 行A | s | f |',
+    '| 2026-09-02 | 行B | s | f |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const after1 = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  // 模拟「主台账被还原后重跑」（分片仍在）
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 行A | s | f |',
+    '| 2026-09-02 | 行B | s | f |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const after2 = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  check('S17 重跑 split 不重复追加（幂等）', after1 === after2, `len1=${after1.length} len2=${after2.length}`);
+  const rows = after2.split(/\r?\n/).filter((l) => /^\| 20/.test(l));
+  check('S17b 行数仍为 2', rows.length === 2, `rows=${rows.length}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S18 appendRows 幂等：同行走两次只落一次 ----
+{
+  const root = mkroot();
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 同行 | s | f |']);
+  appendRows(root, 'papercuts', ['| 2026-10-13 | 同行 | s | f |']);
+  const txt = fs.readFileSync(shardPathFor(root, 'papercuts', '2026-10'), 'utf8');
+  const rows = txt.split(/\r?\n/).filter((l) => /^\| 20/.test(l));
+  check('S18 同行走两次只落一次', rows.length === 1, `rows=${rows.length}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S19 嵌入 `|` 的行不丢（2026-10-13 源仓实测踩中：4 行因列数虚高被 renderShard 丢弃）----
+{
+  const root = mkroot();
+  const weird = '| 2026-09-17 | `.agents/x.mjs` | 正则 `[:=]\\s*["\']?` 含字面竖线 | 拟修 |';
+  fs.writeFileSync(wf(root, 'papercuts.md'), [
+    '| 日期 | 位置 | 症状 | 拟修 |', '|------|------|------|------|',
+    '| 2026-09-01 | 正常行 | s | f |',
+    weird, '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'papercuts');
+  const shard = fs.readFileSync(wf(root, 'papercuts.d', '2026-09.md'), 'utf8');
+  check('S19a 嵌入竖线的行不丢', shard.includes('含字面竖线'), shard.slice(0, 200));
+  check('S19b 正常行也在', shard.includes('正常行'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S20 多表按节归属：委派行（含嵌入竖线）仍归委派表 ----
+{
+  const root = mkroot();
+  const weirdDeleg = '| 2026-09-01 | ui-verifier | 任务含 `a|b` 竖线 | 一次通过 | 备注 | |';
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    weirdDeleg, '',
+    '## 自做任务结果', '',
+    '| 日期 | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|------------|------|------|----------|',
+    '| 2026-09-02 | 自做任务 | 一次通过 | 备注 | |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  const iDeleg = shard.indexOf('被委派方(模型)');
+  const iSelf = shard.indexOf('| 日期 | 任务一句话');
+  const iWeird = shard.indexOf('任务含');
+  check('S20 嵌入竖线的委派行仍归委派表', iDeleg < iWeird && iWeird < iSelf, `deleg=${iDeleg} weird=${iWeird} self=${iSelf}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S21 分片须带节标题（wf-journal.delegationSectionRows 的节门）----
+// （2026-10-13 源仓实测踩中：只带表头 → 节门读侧读到 0 行 → 静默漏报）
+{
+  const root = mkroot();
+  fs.writeFileSync(wf(root, 'delegations.md'), [
+    '## 委派结果', '',
+    '| 日期 | 被委派方(模型) | 任务一句话 | 结果 | 备注 | 合入结论 |',
+    '|------|----------------|------------|------|------|----------|',
+    '| 2026-09-01 | ui-verifier | 委派任务 | 一次通过 | 备注 | |', '',
+  ].join('\n'), 'utf8');
+  splitMain(root, 'delegations');
+  const shard = fs.readFileSync(wf(root, 'delegations.d', '2026-09.md'), 'utf8');
+  check('S21a 分片带 `## 委派结果` 节标题', /^##\s+委派结果\s*$/m.test(shard), shard.slice(0, 120));
+  // 复刻 wf-journal.delegationSectionRows 的节门判据（不 break 形态）
+  let inSec = false;
+  let rows = 0;
+  for (const line of shard.split(/\r?\n/)) {
+    if (/^##\s+/.test(line)) { inSec = /^##\s+委派结果\s*$/.test(line); continue; }
+    if (!inSec || !/^\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+    if (!cells.length || cells.every((c) => /^[-: ]*$/.test(c))) continue;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(cells[0])) continue;
+    rows++;
+  }
+  check('S21b 节门口径能读到分片行', rows === 1, `rows=${rows}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S22 kit 适配钉子：分片渲染出 kit 表头、不出源仓表头 ----
+// （kit delegations 两表末列 =「合入结论」、regression-checklist 表头 =「incident | 条目 | 落点」；
+//   再自源仓同步本模块时若把源仓表头带回来，此组先红）
+{
+  const deleg = renderShard('delegations', []);
+  check('S22a delegations 分片骨架出「合入结论」表头', deleg.includes('合入结论') && !deleg.includes('返工原因'));
+  const regr = renderShard('regression-checklist', []);
+  check('S22b regression-checklist 分片骨架出 kit 表头', regr.includes('| incident | 条目 | 落点 |') && !regr.includes('来源 incident'));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/level-criteria.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // level-criteria.mjs — 风险级别判定的**机器单源**（2026-10-13 flow-kit-route）
 //
-// 为什么有它：风险级别（L0-L3）此前只以**散文**形态存在于 `new-task.md`「级别判断」节——
+// 为什么有它：风险级别（L1-L3；2026-10-13 L0 退役，自源仓收敛系列 1 回灌）此前只以**散文**形态存在于 `new-task.md`「级别判断」节——
 // L2 四类触达面、L3 结构面、负例、自查句全都写给人读。后果有二：
 //   ① 定级是纯自由心证，AI 每次判级都可能不同，门禁无从校验「判低」是否守约；
 //   ② 想让 CLI 接管路由（`flow-kit route`），就没有可执行的判据可调，只能复读 md。
@@ -19,13 +19,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const LEVELS = ['L0', 'L1', 'L2', 'L3'];
+export const LEVELS = ['L1', 'L2', 'L3'];
 export const HINTS_REL = '.agents/level-hints.txt';
 
 // 档位语义（new-task.md 引用本段，不复述——单源纪律）
 export const LEVEL_MEANING = {
-  L0: '文档/样式微调（无行为影响）——直接 commit，豁免 intent',
-  L1: '实现级改动（未命中 L2/L3）——快车道：轻量 intent/plan + 实现',
+  L1: '实现级改动（未命中 L2/L3）——一份 plan 即入口（协作道，不另立 intent）',
   L2: '规则/契约（一处改、多处依赖）——入口文档 + spec + plan 三件套',
   L3: '数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）——同 L2 + spec 新会话独立复核',
 };
@@ -71,10 +70,10 @@ export function maxLevel(a, b) {
 // parseLevelHints：读 hints 清单。行格式 `L3 <ERE>`，ERE 为 grep -E 兼容正则，匹配仓库相对路径（/ 分隔）。
 //   非法档位 / 语法错误的行 → fail-loud 抛错（防静默空洞：写错配置比没配置更危险——没配置会提示，写错会误判）。
 // 三条收紧（2026-10-13 executor-review，全部来自实测复现，不是假想）：
-//   ① **只收 L2 / L3**。本清单语义是「哪些路径一碰就至少是 L2/L3」，L0/L1 行不构成任何门槛——
+//   ① **只收 L2 / L3**。本清单语义是「哪些路径一碰就至少是 L2/L3」，L1 行不构成任何门槛——
 //      而此前接受 L0 会被提交面判低门当真：`L0 ^docs/` 会让纯文档提交被硬拦，修法还让人
-//      「升级至 L0 及以上」（L0 即最低档，荒谬）。写这种行的人本意多半是「这里是 L0 区」，
-//      那正是不该登记的面——故按写错配置处理，fail-loud 点名。
+//      「升级至 L0 及以上」（L0 即最低档，荒谬；该档位已随 2026-10-13 L0 退役整体消失）。
+//      写这种行的人本意多半是「这里是低风险区」，那正是不该登记的面——故按写错配置处理，fail-loud 点名。
 //   ② **行内 `#` 注释 fail-loud**。ERE 取整行剩余部分（`(\S.*)$`），所以 `L3 ^a\.sql$  # 注释`
 //      会把注释编进正则：若路径含 `$` 锚点，该条**永不命中**且无任何报错——路径下限与提交面兜底
 //      同时静默失效，而 `--check` 还报「N 条有效」。这正是随包模板原先示例的写法（评审实测）。
@@ -92,7 +91,7 @@ export function parseLevelHints(text) {
     const re = m[2];
     if (level !== 'L2' && level !== 'L3') {
       errs.push(`第 ${i + 1} 行：档位只能是 L2 或 L3（实际 ${level}）——本清单只登记「一碰就至少是中/高风险面」的路径下限；`
-        + `L0/L1 不构成门槛，登记了只会让提交面判低门对无关改动出手。若本意是「这里是低风险区」，那就不该登记`);
+        + `L1 不构成门槛（L0 已退役），登记了只会让提交面判低门对无关改动出手。若本意是「这里是低风险区」，那就不该登记`);
       return;
     }
     // 行内注释检测：空白后的未转义 #。ERE 里的 `#` 若被转义（\#）或前面不是空白（形如 `^src/#old/`）则放行。
@@ -171,7 +170,7 @@ export function routeAdvice(level, _ctx = {}) {
     lines.push(`【L3 结构面】`);
     for (const s of L3_SURFACES) lines.push(`  · ${s}`);
   }
-  if (L === 'L1' || L === 'L0') {
+  if (L === 'L1') {
     lines.push('');
     lines.push(`【负例 · 命中即不得升 L2/L3】`);
     for (const s of L1_NEGATIVES) lines.push(`  · ${s}`);
@@ -220,7 +219,7 @@ if (process.argv[1] && path.resolve(process.argv[1]).endsWith(path.join('scripts
     const r = checkHintsFile(path.resolve(file));
     if (r.ok === false) {
       console.error(`[level-hints 配置有误] ${file}\n${String(r.error).split('\n').map((l) => `  ${l}`).join('\n')}`);
-      console.error('  修法：按 `<档位> <ERE>` 格式修正（档位 ∈ L0-L3，ERE 为 grep -E 兼容正则）——'
+      console.error('  修法：按 `<档位> <ERE>` 格式修正（档位 ∈ L2|L3，ERE 为 grep -E 兼容正则）——'
         + '写错配置比没配置危险：没配置会提示补配置，写错会误判档位');
       process.exit(1);
     }

package/templates/_agents/scripts/level-criteria.test.mjs

@@ -29,14 +29,14 @@ const throwsCode = (fn, code) => {
 
 // ============ 场景 1：档位闭集与排序原语 ============
 {
-  check('S1 档位闭集为 L0-L3', JSON.stringify(C.LEVELS) === JSON.stringify(['L0', 'L1', 'L2', 'L3']));
-  check('S1 rankOf 大小写不敏感', C.rankOf('l2') === 2 && C.rankOf('L3') === 3 && C.rankOf('L0') === 0);
-  check('S1 rankOf 非法档返回 null', C.rankOf('L9') === null && C.rankOf('') === null && C.rankOf(undefined) === null);
+  check('S1 档位闭集为 L1-L3（L0 已退役）', JSON.stringify(C.LEVELS) === JSON.stringify(['L1', 'L2', 'L3']));
+  check('S1 rankOf 大小写不敏感', C.rankOf('l2') === 1 && C.rankOf('L3') === 2);
+  check('S1 rankOf 非法档返回 null（含已退役的 L0）', C.rankOf('L9') === null && C.rankOf('L0') === null && C.rankOf('') === null && C.rankOf(undefined) === null);
   check('S1 maxLevel 取高', C.maxLevel('L1', 'L3') === 'L3' && C.maxLevel('L3', 'L1') === 'L3');
   check('S1 maxLevel 同档幂等', C.maxLevel('L2', 'L2') === 'L2');
   check('S1 maxLevel 单边非法时取合法侧', C.maxLevel('L9', 'L2') === 'L2' && C.maxLevel('L1', 'L9') === 'L1');
   check('S1 maxLevel 双边非法返回空串（不假装判得出）', C.maxLevel('L9', 'X') === '');
-  check('S1 maxLevel 小写输入归一为大写', C.maxLevel('l0', 'l2') === 'L2');
+  check('S1 maxLevel 小写输入归一为大写', C.maxLevel('l1', 'l2') === 'L2');
 }
 
 // ============ 场景 2：hints 解析 —— 注释/空行/CRLF/档位前缀 ============
@@ -160,8 +160,10 @@ const throwsCode = (fn, code) => {
   const l3 = C.routeAdvice('L3', { hintsConfigured: true });
   check('S7 L3 同时输出 L2 触达面与 L3 结构面', C.L2_SURFACES.every((s) => l3.includes(s)) && C.L3_SURFACES.every((s) => l3.includes(s)));
 
+  // L0 已退役（2026-10-13 自源仓收敛系列 1 回灌）：不在 LEVELS 闭集 → routeAdvice 只报「未知档」，
+  // 不再有语义行、也不产生下溢（下溢概念随 L0 退役消失）。
   const l0 = C.routeAdvice('L0', { hintsConfigured: true });
-  check('S7 L0 归一为语义行（无下溢）', l0.includes('建议级别：L0'));
+  check('S7 已退役的 L0 → 无语义行（未知档），不产生下溢', l0.includes('建议级别：L0 —— （未知档）') && !l0.includes('【负例'));
 
   // 2026-10-13 executor-review：hints 未配置 / 低于下限两条**状态**信息已移出 routeAdvice，
   //   改由 route 的降级块（executor.mjs degradations）单一输出——原实现把同一事实在文本面打两遍。

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

@@ -0,0 +1,141 @@
+#!/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();