agentic-flow-kit 1.7.15 → 1.7.16

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

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// level-criteria.mjs — 风险级别判定的**机器单源**（2026-10-13 flow-kit-route）
+//
+// 为什么有它：风险级别（L0-L3）此前只以**散文**形态存在于 `new-task.md`「级别判断」节——
+// L2 四类触达面、L3 结构面、负例、自查句全都写给人读。后果有二：
+//   ① 定级是纯自由心证，AI 每次判级都可能不同，门禁无从校验「判低」是否守约；
+//   ② 想让 CLI 接管路由（`flow-kit route`），就没有可执行的判据可调，只能复读 md。
+// 本文件把「**能被机器判定的部分**」从散文里抽出来做成单源，md 改为引用本文件而非承载判据。
+//
+// 分工（诚实声明——不是所有判据都能机器判定，别指望本文件替代判断力）：
+//   机器可判：档位闭集与就高不就低、**路径级最低档提示**（level-hints.txt）、混档取高、自查句与负例的**输出**。
+//   机器不可判：「一处定义、多处消费」是**语义**性质——同一条路径改了可能只是修文案、也可能是改编码权威。
+//     因此本文件对语义面**只给判据清单与自查句，不产出断言**。缺 hints 配置时按 L1 起步并提示补配置，
+//     绝不假装判得出。
+//
+// 路径提示清单（`.agents/level-hints.txt`，装户 owned）：`L3 <ERE>` / `L2 <ERE>` 每行一条，
+//   命中即该改动**至少**是此档。缺文件或清单为空 = 纯语义定级（本文件全程静默，不阻断）。
+//   语义参照 `lane-surfaces.txt`（那是「提交面」的触达判据，本文件是「意图面」的档位提示，两者不同档）。
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const LEVELS = ['L0', '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 + 实现',
+  L2: '规则/契约（一处改、多处依赖）——入口文档 + spec + plan 三件套',
+  L3: '数据与运行时结构（schema / 迁移 SQL / DI 链 / 认证与中间件管线）——同 L2 + spec 新会话独立复核',
+};
+
+// L2 四类触达面（闭集，机器不判定语义，只作为判据清单输出给人与 AI）
+export const L2_SURFACES = [
+  '编码权威：一处生成、多处消费的编码/命名/取号规则（具体清单按项目 AGENTS.md）',
+  '共享契约：跨模块共享的基类/DTO 形状、跨模块公共接口签名',
+  '既有接口语义：既有参数或端点的行为变化（失效变生效、默认值或钳制口径改变）',
+  '全局横切口径：错误响应出口、分页与校验口径、聚合投影键',
+];
+
+// L3 结构面
+export const L3_SURFACES = [
+  'schema / 数据模型定义',
+  '迁移 SQL（schema 变更、数据修复）',
+  'DI 链：注册、构造器依赖、组合根',
+  '认证与中间件管线',
+];
+
+// 落 L1 的负例（判低红线：命中即不得定 L2/L3）
+export const L1_NEGATIVES = [
+  '纯页面表现 / 文案 / 布局 / 交互实现',
+  '纯新增端点或参数，且既有行为不变',
+  '单模块内部重构，且无对外契约变化',
+];
+
+// 自查句（人/AI 定级时的判定式，机器只输出不裁决）
+export const SELF_CHECK = '能否列出 ≥2 个受影响的消费方（模块 / 端点 / 页面）？能 → 至少 L2。';
+
+export function rankOf(level) {
+  const i = LEVELS.indexOf(String(level || '').toUpperCase());
+  return i < 0 ? null : i;
+}
+
+export function maxLevel(a, b) {
+  const ra = rankOf(a), rb = rankOf(b);
+  if (ra === null) return rb === null ? '' : String(b).toUpperCase();
+  if (rb === null) return String(a).toUpperCase();
+  return LEVELS[Math.max(ra, rb)];
+}
+
+// parseLevelHints：读 hints 清单。行格式 `L3 <ERE>`，ERE 为 grep -E 兼容正则，匹配仓库相对路径（/ 分隔）。
+//   非法档位 / 语法错误的行 → fail-loud 抛错（防静默空洞：写错配置比没配置更危险——没配置会提示，写错会误判）。
+// 三条收紧（2026-10-13 executor-review，全部来自实测复现，不是假想）：
+//   ① **只收 L2 / L3**。本清单语义是「哪些路径一碰就至少是 L2/L3」，L0/L1 行不构成任何门槛——
+//      而此前接受 L0 会被提交面判低门当真：`L0 ^docs/` 会让纯文档提交被硬拦，修法还让人
+//      「升级至 L0 及以上」（L0 即最低档，荒谬）。写这种行的人本意多半是「这里是 L0 区」，
+//      那正是不该登记的面——故按写错配置处理，fail-loud 点名。
+//   ② **行内 `#` 注释 fail-loud**。ERE 取整行剩余部分（`(\S.*)$`），所以 `L3 ^a\.sql$  # 注释`
+//      会把注释编进正则：若路径含 `$` 锚点，该条**永不命中**且无任何报错——路径下限与提交面兜底
+//      同时静默失效，而 `--check` 还报「N 条有效」。这正是随包模板原先示例的写法（评审实测）。
+//      注释请单独成行；确需匹配路径里的 `#` 写 `\#`。
+//   ③ 档位大写归一：只接受 `L2` / `L3`（原正则 `L[0-3]` 已含大小写外的写法，见下）。
+export function parseLevelHints(text) {
+  const out = [];
+  const errs = [];
+  String(text || '').split(/\r?\n/).forEach((raw, i) => {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) return;
+    const m = line.match(/^(L[0-3])\s+(\S.*)$/i);
+    if (!m) { errs.push(`第 ${i + 1} 行：格式须为 \`L2 <ERE>\` 或 \`L3 <ERE>\`（实际「${line.slice(0, 40)}」）`); return; }
+    const level = m[1].toUpperCase();
+    const re = m[2];
+    if (level !== 'L2' && level !== 'L3') {
+      errs.push(`第 ${i + 1} 行：档位只能是 L2 或 L3（实际 ${level}）——本清单只登记「一碰就至少是中/高风险面」的路径下限；`
+        + `L0/L1 不构成门槛，登记了只会让提交面判低门对无关改动出手。若本意是「这里是低风险区」，那就不该登记`);
+      return;
+    }
+    // 行内注释检测：空白后的未转义 #。ERE 里的 `#` 若被转义（\#）或前面不是空白（形如 `^src/#old/`）则放行。
+    const inline = /(^|\s)#/.exec(re);
+    if (inline) {
+      errs.push(`第 ${i + 1} 行：ERE 与行内注释不得同一行（实际「${line.slice(0, 40)}」）——注释会被编进正则，`
+        + `若含 $ 锚点则该条永不命中且无任何报错；请把注释放到上一行单独成行（确需匹配路径里的 # 请写 \\#）`);
+      return;
+    }
+    try {
+      out.push({ level, re, rx: new RegExp(re), source: line });
+    } catch (e) {
+      errs.push(`第 ${i + 1} 行：正则语法错误（${e.message}）`);
+    }
+  });
+  if (errs.length) {
+    const e = new Error(`${HINTS_REL} 配置有误：\n  - ${errs.join('\n  - ')}`);
+    e.code = 'LEVEL_HINTS_INVALID';
+    throw e;
+  }
+  return out;
+}
+
+export function loadLevelHints(root = process.cwd()) {
+  const p = path.join(root, ...HINTS_REL.split('/'));
+  if (!fs.existsSync(p)) return { hints: [], missing: true };
+  return { hints: parseLevelHints(fs.readFileSync(p, 'utf8')), missing: false };
+}
+
+// hintLevelFor：路径命中的**最低档**提示（多条命中取最高）。无命中返回 ''。
+export function hintLevelFor(hints, files) {
+  let hit = '';
+  const hitRe = [];
+  for (const f of files || []) {
+    const norm = String(f).replace(/\\/g, '/').replace(/^\.\//, '');
+    for (const h of hints) {
+      if (h.rx.test(norm)) { hit = maxLevel(hit, h.level); hitRe.push(`${h.level}←${norm}`); }
+    }
+  }
+  return { level: hit, matched: [...new Set(hitRe)] };
+}
+
+// assessLevel：定级判定面。输入 = 改动文件 + 调用方给的建议档；输出 = 机器可判的部分。
+//   语义面（是否「一处定义多处消费」）**不由本函数裁决**——它只保证：hints 提示档是下限、混档取高。
+export function assessLevel(root, { files = [], proposed = '' } = {}) {
+  const { hints, missing } = loadLevelHints(root);
+  const { level: hintLevel, matched } = hintLevelFor(hints, files);
+  const finalLevel = maxLevel(hintLevel, proposed);
+  return {
+    level: finalLevel,
+    hintLevel,
+    matched,
+    proposed: proposed ? String(proposed).toUpperCase() : '',
+    hintsConfigured: !missing && hints.length > 0,
+    // 调用方给的建议档若低于 hint 下限 → 提示；不硬拦（判级纪律仍由 lane-surface 触达面门在提交面兜）
+    underHint: !!(hintLevel && rankOf(proposed) !== null && rankOf(proposed) < rankOf(hintLevel)),
+  };
+}
+
+// routeAdvice：给人/AI 的**判据面**文本（route 命令直接输出这份）。
+//   2026-10-13 executor-review：原先这里还兼报「hints 未配置」「建议档低于下限」两条**状态**信息，
+//   而 route 的降级块（executor.mjs degradations）讲的是同一件事 → 文本模式把同一事实打了两遍。
+//   口径：**判据归本函数、状态归降级块**，单一出口。故 ctx（原 hintsConfigured / underHint /
+//   hintLevel / matched）保留在签名里仅为兼容既有调用方，本函数不再读取——故参数名带下划线前缀。
+export function routeAdvice(level, _ctx = {}) {
+  const L = String(level || 'L1').toUpperCase();
+  const lines = [];
+  lines.push(`建议级别：${L} —— ${LEVEL_MEANING[L] || '（未知档）'}`);
+  if (L === 'L2' || L === 'L3') {
+    lines.push('');
+    lines.push(`【L2 触达面 · 闭集，逐条判】`);
+    for (const s of L2_SURFACES) lines.push(`  · ${s}`);
+  }
+  if (L === 'L3') {
+    lines.push('');
+    lines.push(`【L3 结构面】`);
+    for (const s of L3_SURFACES) lines.push(`  · ${s}`);
+  }
+  if (L === 'L1' || L === 'L0') {
+    lines.push('');
+    lines.push(`【负例 · 命中即不得升 L2/L3】`);
+    for (const s of L1_NEGATIVES) lines.push(`  · ${s}`);
+  }
+  lines.push('');
+  lines.push(`【自查句】${SELF_CHECK}`);
+  lines.push('提示：级别是**意图面**的语义判定（「一处定义、多处消费」），机器只兜「就高不就低」与路径下限。');
+  return lines.join('\n');
+}
+
+// ---- 体检入口（2026-10-13 hint-doctor）------------------------------------
+// 为什么需要：非法 hints 此前只在**跑 flow-kit route 时**才抛 LEVEL_HINTS_INVALID，而 route 是
+//   可选调用 → 写错的清单能静默存活很久，直到某天有人碰巧路由一次才炸。写错配置比没配置危险
+//   （没配置会提示补，写错会误判），故给 doctor 一条**主动体检**通道。
+// 口径纪律：doctor 不自己复刻解析器（复刻=判据双源漂移），改为 spawn 本文件执行本节——
+//   解析逻辑永远只有 parseLevelHints 一份。
+//   用法：node level-criteria.mjs --check <清单路径>
+//   退出码：0 通过（含文件缺失/空清单＝未启用）；1 配置有误（stderr 出逐行原因）。无参数 → 退出 2。
+export function checkHintsFile(file) {
+  if (!fs.existsSync(file)) return { configured: false, entries: 0, note: '文件不存在（默认空＝纯语义定级）' };
+  const text = fs.readFileSync(file, 'utf8');
+  let hints;
+  try {
+    hints = parseLevelHints(text);
+  } catch (e) {
+    return { configured: true, ok: false, entries: 0, error: e.message, code: e.code || 'LEVEL_HINTS_INVALID' };
+  }
+  return {
+    configured: true,
+    ok: true,
+    entries: hints.length,
+    levels: [...new Set(hints.map((h) => h.level))].sort(),
+  };
+}
+
+// CLI 自运行守卫：仅当本文件被直接执行时进入体检模式（被 import 时不跑——库用法不受影响）
+if (process.argv[1] && path.resolve(process.argv[1]).endsWith(path.join('scripts', 'level-criteria.mjs'))) {
+  const argv = process.argv.slice(2);
+  const at = argv.indexOf('--check');
+  if (at >= 0) {
+    const file = argv[at + 1];
+    if (!file || argv[at + 1].startsWith('--')) {
+      console.error('用法：node level-criteria.mjs --check <level-hints.txt 路径>');
+      process.exit(2);
+    }
+    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 兼容正则）——'
+        + '写错配置比没配置危险：没配置会提示补配置，写错会误判档位');
+      process.exit(1);
+    }
+    console.log(r.configured
+      ? `level-hints：${r.entries} 条有效（${(r.levels || []).join('/') || '—'}）`
+      : `level-hints：未配置（${r.note}）`);
+    process.exit(0);
+  }
+}

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

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+// level-criteria.test.mjs — 级别判据机器单源套件（2026-10-13 flow-kit-route）
+// 覆盖：档位闭集 / rankOf·maxLevel 边界 / hints 解析（注释·空行·CRLF·分隔）/ 非法 hints fail-loud /
+//       路径下限与多命中取高 / assessLevel 就高不就低与 underHint / hints 缺失·为空两态 /
+//       routeAdvice 分档输出面（负例·触达面·结构面·未配置提示）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const C = await import(pathToFileURL(path.join(SCRIPT_DIR, 'level-criteria.mjs')).href);
+
+let pass = 0, fail = 0;
+const check = (name, ok, detail = '') => {
+  if (ok) { pass++; console.log(`  ok  ${name}`); }
+  else { fail++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+};
+
+const mkRoot = () => fs.mkdtempSync(path.join(os.tmpdir(), 'level-criteria-'));
+const wHints = (root, text) => {
+  const p = path.join(root, ...C.HINTS_REL.split('/'));
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, text, 'utf8');
+};
+const throwsCode = (fn, code) => {
+  try { fn(); return ''; } catch (e) { return e.code === code ? 'ok' : `code=${e.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 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');
+}
+
+// ============ 场景 2：hints 解析 —— 注释/空行/CRLF/档位前缀 ============
+{
+  const txt = [
+    '# 注释行',
+    '',
+    '   ',
+    'L2 ^src/contracts/',
+    'L3 ^src/db/migrations/.*\\.sql$',
+    '\tL2 \uFEFFsrc/gen/',   // 前导空白 + BOM 残留（Windows 编辑器常见）
+  ].join('\r\n');
+  const hints = C.parseLevelHints(txt);
+  check('S2 解析出 3 条（注释/空行不计）', hints.length === 3, `实得 ${hints.length}`);
+  check('S2 首条档位与正则正确', hints[0].level === 'L2' && hints[0].re === '^src/contracts/');
+  check('S2 CRLF 不污染正则', hints[1].rx.test('src/db/migrations/001_init.sql'));
+  check('S2 空白/BOM 前缀被 trim 掉', hints[2].rx.test('src/gen/x.ts'), `re=${hints[2].re}`);
+  check('S2 无命中项不抛', C.parseLevelHints('# 全是注释\n\n').length === 0);
+}
+
+// ============ 场景 3：非法 hints fail-loud（写错配置比没配置危险） ============
+{
+  check('S3 非法档位行报 LEVEL_HINTS_INVALID', throwsCode(() => C.parseLevelHints('L9 ^src/'), 'LEVEL_HINTS_INVALID') === 'ok');
+  check('S3 缺正发行报 LEVEL_HINTS_INVALID', throwsCode(() => C.parseLevelHints('L2'), 'LEVEL_HINTS_INVALID') === 'ok');
+  check('S3 正则语法错报 LEVEL_HINTS_INVALID', throwsCode(() => C.parseLevelHints('L2 ^src/(['), 'LEVEL_HINTS_INVALID') === 'ok');
+  let msg = '';
+  try { C.parseLevelHints('L9 ^src/\nL2 ^ok/'); } catch (e) { msg = e.message; }
+  check('S3 报文含清单路径与行号定位', msg.includes(C.HINTS_REL) && msg.includes('第 1 行'), msg);
+  let msg2 = '';
+  try { C.parseLevelHints('L2 ^ok/\n\nL2 ^bad/([\nL9 x'); } catch (e) { msg2 = e.message; }
+  check('S3 一次聚合全部坏行行号', msg2.includes('第 3 行') && msg2.includes('第 4 行'), msg2);
+  check('S3 合法行不报错（只聚合坏行）', !msg2.includes('第 2 行'), msg2);
+
+  // 2026-10-13 executor-review 两条实测 Major 的回归锁：
+  // ① 行内 `#` 注释会被编进 ERE → 含 $ 锚点时该条永不命中且**无任何报错**，
+  //    路径下限与提交面兜底同时静默失效（原随包模板示例就是这个写法）。
+  let c1 = '';
+  try { C.parseLevelHints('L3 ^src/db/migrations/.*\\.sql$   # 迁移 SQL'); } catch (e) { c1 = e.message; }
+  check('S3 行内 # 注释 → fail-loud（否则该条永不命中且静默）',
+    c1.includes('LEVEL_HINTS_INVALID') || c1.includes('行内注释'), c1);
+  check('S3 行内注释报文点名该行并给出正确写法', c1.includes('第 1 行') && c1.includes('单独成行'), c1);
+  check('S3 转义 \\# 视为路径字符而非注释', C.parseLevelHints('L2 ^src/\\#old/').length === 1);
+  check('S3 路径里的 #（前非空白）不算注释', C.parseLevelHints('L2 ^src/#old/').length === 1);
+
+  // ② L0/L1 档被原实现接受，而提交面判低门会当真：`L0 ^docs/` 让纯文档提交被硬拦，
+  //    修法还让人「升级至 L0 及以上」（L0 即最低档）。只收 L2/L3。
+  let c2 = '';
+  try { C.parseLevelHints('L0 ^docs/'); } catch (e) { c2 = e.message; }
+  check('S3 L0 档 → fail-loud（本清单只登记 L2/L3 下限）', c2.includes('只能是 L2 或 L3'), c2);
+  check('S3 L1 档同样被拒', throwsCode(() => C.parseLevelHints('L1 ^src/'), 'LEVEL_HINTS_INVALID') === 'ok');
+  check('S3 拒绝低档时说明理由（登记低档只会让提交面门出手）', c2.includes('噪声') || c2.includes('不构成门槛'), c2);
+}
+
+// ============ 场景 4：路径下限与多命中取高 ============
+{
+  const hints = C.parseLevelHints(['L2 ^src/contracts/', 'L3 ^src/db/migrations/.*\\.sql$', 'L2 ^docs/api\\.md$'].join('\n'));
+  check('S4 单命中取该档', C.hintLevelFor(hints, ['src/contracts/types.ts']).level === 'L2');
+  check('S4 多文件多档取最高', C.hintLevelFor(hints, ['src/contracts/a.ts', 'src/db/migrations/002_x.sql']).level === 'L3');
+  check('S4 未命中返回空串', C.hintLevelFor(hints, ['src/ui/button.tsx']).level === '');
+  check('S4 反斜杠路径归一为 /', C.hintLevelFor(hints, ['src\\contracts\\a.ts']).level === 'L2');
+  check('S4 ./ 前缀剥离', C.hintLevelFor(hints, ['./src/contracts/a.ts']).level === 'L2');
+  // ERE 按「仓库相对路径」语义写，`^` 锚定即不命中绝对路径 —— 这是契约不是漏洞：
+  // 命中绝对路径说明清单写成了无锚 ERE，容易误伤同名目录。
+  check('S4 `^` 锚定规则不命中绝对路径（清单契约=仓库相对路径）',
+    C.hintLevelFor(hints, ['C:/repo/src/db/migrations/003_y.sql']).level === '');
+  check('S4 无锚 ERE 命中子串（清单作者自选口径）',
+    C.hintLevelFor(C.parseLevelHints('L3 migrations/.*\\.sql$'), ['C:/repo/src/db/migrations/003_y.sql']).level === 'L3');
+  const m = C.hintLevelFor(hints, ['src/contracts/a.ts', 'src/db/migrations/002_x.sql']);
+  check('S4 matched 给出命中证据', m.matched.length === 2 && m.matched.some((s) => s.includes('src/contracts/a.ts')), JSON.stringify(m.matched));
+  check('S4 matched 去重', new Set(m.matched).size === m.matched.length);
+  check('S4 空输入不抛', C.hintLevelFor(hints, []).level === '' && C.hintLevelFor([], ['a']).level === '');
+}
+
+// ============ 场景 5：assessLevel —— 就高不就低 / underHint / 两态配置 ============
+{
+  const r = mkRoot();
+  wHints(r, 'L3 ^src/db/migrations/.*\\.sql$\n');
+  const noProposed = C.assessLevel(r, { files: ['src/db/migrations/001_init.sql'] });
+  check('S5 无建议档时按 hint 抬档', noProposed.level === 'L3' && noProposed.hintLevel === 'L3');
+  check('S5 无建议档不算 underHint（无档可低）', noProposed.underHint === false);
+  check('S5 hintsConfigured=true', noProposed.hintsConfigured === true);
+
+  const up = C.assessLevel(r, { files: ['src/db/migrations/001_init.sql'], proposed: 'L3' });
+  check('S5 建议档≥下限 → 不提示', up.underHint === false && up.level === 'L3');
+
+  const down = C.assessLevel(r, { files: ['src/db/migrations/001_init.sql'], proposed: 'L1' });
+  check('S5 建议档低于下限 → underHint=true', down.underHint === true);
+  check('S5 就高不就低：仍取 L3（建议档只作提示不压档）', down.level === 'L3');
+  check('S5 proposed 归一为大写回显', down.proposed === 'L1');
+
+  const noHit = C.assessLevel(r, { files: ['src/ui/button.tsx'], proposed: 'L2' });
+  check('S5 无命中时尊重建议档', noHit.level === 'L2' && noHit.hintLevel === '' && noHit.underHint === false);
+}
+
+// ============ 场景 6：hints 缺失 vs 为空 —— 两态都算「未配置」但不崩 ============
+{
+  const missing = C.assessLevel(mkRoot(), { files: ['src/a.ts'] });
+  check('S6 文件缺失 → hintsConfigured=false', missing.hintsConfigured === false);
+  check('S6 文件缺失 → 按 L1 起步（不假装判得出）', missing.level === '' && missing.hintLevel === '');
+
+  const empty = mkRoot();
+  wHints(empty, '# 只有注释\n');
+  const e = C.assessLevel(empty, { files: ['src/a.ts'], proposed: 'L2' });
+  check('S6 清单存在但为空 → hintsConfigured=false', e.hintsConfigured === false);
+  check('S6 空清单不压建议档', e.level === 'L2');
+}
+
+// ============ 场景 7：routeAdvice 分档输出面 ============
+{
+  const l1 = C.routeAdvice('L1', { hintsConfigured: true });
+  check('S7 L1 输出负例清单', C.L1_NEGATIVES.every((s) => l1.includes(s)));
+  check('S7 L1 不输出 L2/L3 触达面', !l1.includes('共享契约') && !l1.includes('迁移 SQL'));
+  check('S7 一律输出自查句', l1.includes(C.SELF_CHECK));
+  check('S7 一律声明机器边界（语义面不由机器裁决）', l1.includes('语义'));
+
+  const l2 = C.routeAdvice('L2', { hintsConfigured: true });
+  check('S7 L2 输出四类触达面', C.L2_SURFACES.every((s) => l2.includes(s)));
+  check('S7 L2 不输出 L3 结构面', !l2.includes('DI 链：注册'));
+  check('S7 L2 不输出负例面', !l2.includes('【负例'));
+
+  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)));
+
+  const l0 = C.routeAdvice('L0', { hintsConfigured: true });
+  check('S7 L0 归一为语义行（无下溢）', l0.includes('建议级别：L0'));
+
+  // 2026-10-13 executor-review：hints 未配置 / 低于下限两条**状态**信息已移出 routeAdvice，
+  //   改由 route 的降级块（executor.mjs degradations）单一输出——原实现把同一事实在文本面打两遍。
+  //   判据面留在本函数，状态面归降级块；此处锁死「不再重复」。
+  const un = C.routeAdvice('L1', { hintsConfigured: false });
+  check('S7 routeAdvice 不再输出 hints 状态（降级块唯一出口）',
+    !un.includes('未配置') && !un.includes('机器面给不出档位提示'), un);
+  const under = C.routeAdvice('L3', { hintsConfigured: true, underHint: true, proposed: 'L1', hintLevel: 'L3', matched: ['L3←src/db/migrations/001_init.sql'] });
+  check('S7 routeAdvice 不再输出 underHint 状态（降级块唯一出口）',
+    !under.includes('低于路径提示下限') && !under.includes('src/db/migrations/001_init.sql'), under);
+  check('S7 但判据面照常输出（自查句 + 机器边界声明）',
+    under.includes(C.SELF_CHECK) && under.includes('语义'), under);
+
+  check('S7 未知档位标注未知而非假装', C.routeAdvice('L9', {}).includes('（未知档）'));
+  check('S7 空档位回落 L1', C.routeAdvice('', {}).includes('建议级别：L1'));
+}
+
+// ============ 场景 8：单源纪律 —— md 不再承载判据散文 ============
+{
+  const cmdPath = path.join(SCRIPT_DIR, '..', 'commands', 'new-task.md');
+  const md = fs.readFileSync(cmdPath, 'utf8');
+  check('S8 new-task.md 指向判据单源', md.includes('level-criteria.mjs'));
+  check('S8 new-task.md 登记 level-hints.txt', md.includes('.agents/level-hints.txt'));
+  check('S8 new-task.md 不再内嵌 L2 四类触达面散文', !md.includes('聚合投影键'));
+  check('S8 new-task.md 不再内嵌判低负例散文', !md.includes('单模块内部重构且无对外契约变化'));
+  check('S8 new-task.md 不再内嵌自查句原文', !md.includes('能否列出 ≥2 个受影响的消费方'));
+
+  // 过期指针回归：§级别判断 已改为「引用单源」，别处再指向它就是指向一个不再承载判据的章节。
+  // （改写该节时同步发现 design.md 与 fill-intent.mjs 两处指针，测试锁死免得日后再长出来。）
+  const design = fs.readFileSync(path.join(SCRIPT_DIR, '..', 'commands', 'design.md'), 'utf8');
+  const fillIntent = fs.readFileSync(path.join(SCRIPT_DIR, 'fill-intent.mjs'), 'utf8');
+  const cmdsDir = path.join(SCRIPT_DIR, '..', 'commands');
+  const cmdHits = fs.readdirSync(cmdsDir)
+    .filter((f) => f.endsWith('.md'))
+    .filter((f) => fs.readFileSync(path.join(cmdsDir, f), 'utf8').match(/§\s*级别判断|new-task\.md[^）)]*级别判断/));
+  check('S8 无 md 指令指向已改写的 §级别判断', cmdHits.length === 0, cmdHits.join(','));
+  check('S8 design.md 指向判据单源', design.includes('level-criteria.mjs'));
+  check('S8 fill-intent 不再指向 §级别判断', !fillIntent.includes('§级别判断'));
+
+  // 面扩到 md 之外：首轮改写漏掉的三处（pipeline-run 工单 / check-lane-surface 门禁报文 /
+  // lane-surfaces.txt 头注释）都在 .mjs 与 .txt 里，只扫 commands/*.mjs 会漏。扫描整个装户面。
+  const AGENTS_DIR = path.join(SCRIPT_DIR, '..');
+  const stale = [];
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.name === 'scripts' && dir !== AGENTS_DIR) continue; // 避免重复扫
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) { if (e.name !== 'node_modules' && e.name !== 'cache') walk(abs); continue; }
+      if (!/\.(mjs|txt|md|json)$/.test(e.name)) continue;
+      if (e.name.endsWith('.test.mjs')) continue; // 含本文件（顶层 await 环境下不能用 __filename）
+      const t = fs.readFileSync(abs, 'utf8');
+      if (/new-task\.md[^\n]{0,40}§\s*级别判断/.test(t)) stale.push(path.relative(AGENTS_DIR, abs).replace(/\\/g, '/'));
+    }
+  };
+  walk(AGENTS_DIR);
+  check('S8 装户面无指向 §级别判断的过期指针', stale.length === 0, stale.join(','));
+
+  // 判据**散文本身**的回归（2026-10-13 executor-review）：原护栏只锁 new-task.md 里 3 个字面串，
+  //   于是判据换了措辞就能在别处重新长回来——实测 design.md 与 fill-intent.mjs 各存了一份
+  //   （后者把 L2 列成五项，单源是四项）。故改为**按单源词条扫判级面**：单源与本测试之外，
+  //   凡列举/复述判据闭集的文件即判红。
+  //   扫描面 = 会指导判级的两类件（命令 md + 起草工具脚本）；不含 level-hints.txt——那是路径
+  //   示例文件，其注释里提到「迁移 SQL」「DI 链」是路径举例，不是判据复述。
+  const CRITERIA_TERMS = ['编码权威', '共享契约', '既有接口语义', '全局横切口径', 'DI 链', '认证与中间件管线'];
+  const ALLOW = new Set(['level-criteria.mjs', 'level-criteria.test.mjs']);
+  const proseHits = [];
+  const scanProse = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, e.name);
+      const rel = path.relative(AGENTS_DIR, abs).replace(/\\/g, '/');
+      if (e.isDirectory()) { if (e.name !== 'node_modules' && e.name !== 'cache') scanProse(abs); continue; }
+      if (!/\.(mjs|md)$/.test(e.name)) continue;
+      if (e.name.endsWith('.test.mjs') || ALLOW.has(e.name)) continue;
+      // 只扫判级面：命令 md + 起草工具（fill-*）。其余脚本引用单源属正常。
+      if (!/^commands\//.test(rel) && !/^scripts\/fill-/.test(rel)) continue;
+      const t = fs.readFileSync(abs, 'utf8');
+      const hit = CRITERIA_TERMS.filter((w) => t.includes(w));
+      if (hit.length) proseHits.push(`${rel} → ${hit.join('/')}`);
+    }
+  };
+  scanProse(AGENTS_DIR);
+  check('S8 判级面不复述判据闭集（词条只在单源一处）', proseHits.length === 0, proseHits.join(' | '));
+  check('S8 design.md 只留流程映射 + 指向单源',
+    design.includes('L2_SURFACES') && design.includes('L3_SURFACES') && proseHits.every((h) => !h.startsWith('commands/design.md')),
+    proseHits.filter((h) => h.startsWith('commands/design.md')).join('|'));
+  check('S8 fill-intent 触达红线改为对照单源（不再自带五项/四项清单）',
+    fillIntent.includes('L2_SURFACES') && fillIntent.includes('L3_SURFACES'), '');
+
+  // B3：route 曾是「可绕旁路」——装户面唯一提及只是 §4 里一行 bash 提示，无任何必跑语义，
+  //   而机器又无法发现它没被调用（定级早于改动面确定，无可比对的记录面，见 ARCHITECTURE §5）。
+  //   故把接线强度锁在**流程文本**上：必跑标记 + 不给 --files 拿不到下限 + 跳过须写理由 + 兜底门。
+  const nt = fs.readFileSync(path.join(SCRIPT_DIR, '..', 'commands', 'new-task.md'), 'utf8');
+  check('S8 new-task.md 定级第 0 步标注必跑 route（非可选提示）', /必跑/.test(nt) && /flow-kit route --files/.test(nt));
+  check('S8 new-task.md 说明不给 --files 就拿不到路径下限', nt.includes('不给 `--files` 就拿不到路径下限'));
+  check('S8 new-task.md 要求跳过时写明理由', nt.includes('写明理由'));
+  check('S8 new-task.md 点名提交面兜底门', nt.includes('check-lane-surface'));
+  check('S8 new-task.md 声明机器无法发现跳过（诚实边界）', nt.includes('无法**发现'));
+}
+
+// ============ 场景 9：装户模板面 —— level-hints.txt 随模板下发且默认为空 ============
+{
+  const tpl = path.join(SCRIPT_DIR, '..', 'level-hints.txt');
+  const ok = fs.existsSync(tpl);
+  check('S9 模板带 level-hints.txt', ok);
+  if (ok) {
+    const txt = fs.readFileSync(tpl, 'utf8');
+    check('S9 默认无有效条目（内容项目私有）', C.parseLevelHints(txt).length === 0);
+    check('S9 说明格式为 `<档位> <ERE>`', txt.includes('`<档位> <ERE>`'), txt.slice(0, 200));
+    check('S9 含被注释掉的 L2/L3 示例行', /#\s*L3\s+\^/.test(txt) && /#\s*L2\s+\^/.test(txt));
+    check('S9 说明默认留空与项目私有立场', txt.includes('默认留空') && txt.includes('项目私有'));
+  }
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/pipeline-run.mjs

@@ -271,7 +271,9 @@ function changedFiles(ctx, run) {
 }
 
 // 脚本自身管理的运行态路径——confirm/gate/gen-index 副产物，不属宿主越权面（沙箱演练实证，2026-10-02）
-const RUNTIME_OWNED = ['.agents/cache/', '.agents/confirmations.jsonl', 'workflow/INDEX.md'];
+// confirmations.d/ 亦为运行态副产物（2026-10-12 ledger-shard-write 的 `--shard` 写入面）——
+// 不加会让 --shard 的确认行被沙箱越权检查误判为「宿主改了台账」。
+const RUNTIME_OWNED = ['.agents/cache/', '.agents/confirmations.jsonl', '.agents/confirmations.d/', 'workflow/INDEX.md'];
 
 function checkAuthorized(ctx, run, filesCsv) {
   const listed = String(filesCsv || '').split(/[,，]/).map((s) => s.trim().replace(/\\/g, '/')).filter(Boolean);
@@ -338,7 +340,7 @@ function advance(ctx, run, opt) {
           issueWO(ctx, run, wo(run, {
             kind: 'triage', title: '判级与分类', goal: '读需求与 new-task.md 判级闭集，输出 kind/level/module/topic',
             instructions: [
-              '1. 读 .agents/commands/new-task.md §级别判断（L2 触达面闭集 / L1 默认档 / L3 结构面）',
+              '1. 读 .agents/scripts/level-criteria.mjs 判据单源（L2_SURFACES 触达面闭集 / L1 默认档 / L3_SURFACES 结构面；new-task.md 只承载流程表，判据一律看单源；机器面可先跑 `flow-kit route --kind require` 取路径下限提示）',
               `2. 对需求定级：「${run.requirement}」${run.hint ? `（预判参考：${run.hint}）` : ''}`,
               '3. 回填：next --triage "kind=require|fix|verify|review|deploy level=L0-L3 module=<词表> topic=<英文kebab>"',
             ],

package/templates/_agents/scripts/policy.mjs

@@ -119,6 +119,34 @@ export const POLICIES = {
     // 消费方：check-loop 检查 15 的 scope 子项（台账行 ts ≥ 本值才判）。
     scopeSince: '2026-10-09T11:24:43Z',
   },
+  // 版本 8 = 版本 7 的全部键 + ledgerDocChainSince（台账哈希链的**链域**从「文件物理序」改为
+  // 「按 doc 的逻辑序」，2026-10-12 ledger-doc-chain）。
+  // 为什么改：原链 prevHash = 物理上一行的 hash，隐含「台账是单写者顺序追加」的前提。三种并发形态
+  //   全部破坏它——① 两进程并发 append 读到同一末行 → 同 prevHash 分叉；② git merge 并集（见
+  //   git-merge-jsonl.mjs）后 B 侧行被追加到 A 尾部之后 → A 侧链被劈开；③ 分片归并 compact 把分片行
+  //   插进主台账中部 → 断链。且这三者都是**正常协作**,不是篡改——让正常协作长期撞 hard 门,门禁就会被
+  //   绕过（--no-verify），治理失效。
+  // 为什么按 doc 分域：台账行的天然主键是 doc（每行 = 某份文档的一次确认）。**同一 doc 内的先后有语义，
+  //   doc 之间的先后没有语义**。把链的域对齐语义域是对既有判据的修正，不是削弱——就地改行、删行、
+  //   插行三类篡改在 doc 链下一律仍被抓住（见 check-loop 检查 15）。
+  // 本版本只加一个开关键：**缺键（v1-v7）时写入侧与校验侧都走旧物理链口径**，存量台账零变化、零新增告警。
+  // 粒度取「时刻」而非日期（同 scopeSince / verifyDocSince 的教训）：本日已有一批旧口径行写入，
+  //   日期粒度会把它们纳入新受审范围、产出不可消退告警。
+  // 消费方：confirm-doc appendLedger（写入侧取前驱）+ check-loop 检查 15（校验侧按行分域）。
+  8: {
+    moduleSince: '2026-09-22',
+    check14Since: '2026-09-26',
+    confirmDocsEffective: '2026-09-27',
+    confirmIncidentsEffective: '2026-09-28',
+    bindingTs: '2026-09-28',
+    check17UnclosedAfter: '0.8.0',
+    stageGateSince: '2026-09-29',
+    riskLevelSince: '2026-10-01',
+    verifySince: '2026-10-07',
+    verifyDocSince: '2026-10-08T09:37:35Z',
+    scopeSince: '2026-10-09T11:24:43Z',
+    ledgerDocChainSince: '2026-10-12T07:20:00Z',
+  },
 };
 
 export function loadKitPolicy(root) {
@@ -180,6 +208,25 @@ export function ledgerChainHash(row, prevHash) {
   return createHash('sha256').update((prevHash || '') + JSON.stringify(row)).digest('hex');
 }
 
+// ---- 台账 doc 链前驱（2026-10-12 ledger-doc-chain）----
+// 单源：confirm-doc appendLedger（写入侧取前驱）与 check-loop 检查 15（校验侧判接续）共用同一语义。
+//   ledgerDocChainActive(policy)：锚存在且为合法 ISO 时刻 → 新口径生效；缺键（v1-v7）→ 旧物理链。
+//   ledgerDocChainPrev(rows, doc)：rows 为物理序的已解析台账行，返回该 doc **最后一个带 hash 行**的
+//   hash，无则 ''（链段重启）。取不到带 hash 的行时返回 ''，与旧口径「末行无 hash → ''」同向。
+// 为什么不做去重/合并：去重是**口径变更**（会改漏斗计数），属分片功能同批生效，不在本步。
+export function ledgerDocChainActive(policy) {
+  const s = policy && policy.ledgerDocChainSince;
+  return typeof s === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(s);
+}
+
+export function ledgerDocChainPrev(rows, doc) {
+  for (let i = (rows && rows.length ? rows.length : 0) - 1; i >= 0; i--) {
+    const r = rows[i];
+    if (r && r.doc === doc && typeof r.hash === 'string') return r.hash;
+  }
+  return '';
+}
+
 // ---- 台账 scope（机器派生改动面，2026-10-09 审查 A1 干净版）----
 // scopeDigest(files) = {files, sha256}：files 归一（反斜杠→posix）、去重、排序；sha256 = files.join('\n') 的摘要。
 // **单源**（confirm-doc 落账侧构造与 check-loop 检查 15 校验侧重算共用——防两处归一/排序口径漂移，

package/templates/_agents/scripts/stage-gates.mjs

@@ -25,6 +25,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { loadKitPolicy } from './policy.mjs';
+import { readLedgerRows } from './ledger-loader.mjs';
 
 export const ENTRY_STATUSES = ['approved', 'done'];
 export const INCIDENT_STATUSES = ['open', 'fixed', 'closed'];
@@ -48,16 +49,10 @@ function readBody(abs) {
 }
 
 // readLedger：confirmations.jsonl 追加式台账（坏行容忍跳过；与 check-loop 检查 15 同容错口径）
+// 读法收敛到 ledger-loader 单源（2026-10-12 ledger-loader-p1）：本函数此前自持 readFileSync+parse
+// 复刻，与其余 5 处各写各的——分片台账落地时逐处加分支必然漏改。签名与返回值不变。
 export function readLedger(root) {
-  const p = path.join(root, '.agents', 'confirmations.jsonl');
-  let text = '';
-  try { text = fs.readFileSync(p, 'utf8'); } catch { return []; }
-  const out = [];
-  for (const line of text.split('\n')) {
-    if (!line.trim()) continue;
-    try { out.push(JSON.parse(line)); } catch { /* 坏行跳过 */ }
-  }
-  return out;
+  return readLedgerRows(root);
 }
 
 // judgeDoc：状态枚举 + 机器事实源判定（供入口 / spec 复用）

package/templates/_agents/scripts/wf-journal.test.mjs

@@ -139,7 +139,7 @@ const STAGES = parseStages(`| id | after | role | step | task | files | accept |
     const j = path.join(os.tmpdir(), `wfj-real-${Date.now()}.jsonl`);
     const r = spawnSync(process.execPath, [JOURNAL_CLI, 'status', '--wf', 'pipeline-closing', '--journal', j], { encoding: 'utf8', cwd: ROOT });
     check('S9 真实 pipeline-closing：confirm 为 human 形态且无 journal 时 author 首层就绪',
-      !!confirm && confirm.human && !confirm.role && stages.length >= 10
+      !!confirm && confirm.human && !confirm.role && stages.length >= 9
         && r.status === 0 && /就绪（第 0 层.*author/.test(r.stdout),
       JSON.stringify({ confirm, out: r.stdout }));
     fs.rmSync(j, { force: true });