agentic-flow-kit 1.7.15 → 1.8.0

package/src/executor.mjs

@@ -0,0 +1,262 @@
+// flow-kit route / run —— 手动路由与自动流水线（2026-10-13 flow-kit-route）
+//
+// 这是引擎从「骨架」到「执行器」的两条新命令。分工（硬约定）：
+//   **代码留在装户 .agents/scripts/**，包 CLI 只做**薄壳转发与判定面**——执行体不搬家（决策 A）。
+//   **md 指令与 md 子代理仍装在装户**（.agents/commands、.agents/roles、modules/hosts）：宿主读它们，
+//   包 CLI 不复制、不改写、不解释它们的正文。
+//
+// ── route（手动路由的机器面）──────────────────────────────────────────
+// 此前定级只以散文存在于 .agents/commands/new-task.md；AI 每次判级都可能不同，门禁无从校验判低守约。
+// 本命令把「能被机器判定的部分」抽出来（判据单源 = .agents/scripts/level-criteria.mjs），
+// 给出：建议档位 + 判据清单 + 下一阶段 + 该读的 md 指令路径。
+// **诚实边界**：级别是**意图面**的语义判定（「一处定义、多处消费」），机器判不了语义——本命令只兜
+//   「就高不就低」与「路径下限」（.agents/level-hints.txt，装户自持、内容项目私有）。
+//   未配置 hints 时按 L1 起步并提示补配置，**绝不假装判得出**。
+//
+// ── run（自动流水线薄壳）─────────────────────────────────────────────
+// 直接转发装户的 pipeline-run 状态机（start/next/status/watch/abort），不复制其逻辑：
+//   状态机唯一实现在 .agents/scripts/pipeline-run.mjs，工单协议与人件门语义见 .agents/commands/pipeline-run.md。
+//   薄壳只做：定位装户脚本 → 透传参数与退出码。**绝不 spawn AI 会话、永不伪造原话、永不带 --no-verify**。
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const AGENT_SCRIPTS_REL = '.agents/scripts';
+
+function parseArgs(args) {
+  const o = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      // `--k=v` 与 `--k v` 等价（--dir=<path> 这类写法必须能解析，否则寻址参数被静默忽略）
+      const eq = a.indexOf('=');
+      if (eq > 2) { o[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+      const k = a.slice(2);
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('--')) o[k] = true;
+      else { o[k] = next; i++; }
+    } else o._.push(a);
+  }
+  return o;
+}
+
+function resolveTarget(o) {
+  return path.resolve(typeof o.dir === 'string' ? o.dir : process.cwd());
+}
+
+function fail(msg, code = 1) { console.error('❌ ' + msg); process.exit(code); }
+
+// 装户脚本存在性判定（薄壳不做「自动 sync 装一遍」——那会静默改用户盘面，fail-loud 指向处置动作）
+function requireInstalledScript(target, rel) {
+  const abs = path.join(target, ...rel.split('/'));
+  if (!fs.existsSync(abs)) {
+    fail(`未找到 ${rel}——当前目录不是已安装 flow-kit 的项目，或安装被部分清理。\n   处置：cd 到项目根，或执行 flow-kit init / flow-kit sync 补齐。`);
+  }
+  return abs;
+}
+
+// 读装户权威路由表（B5，2026-10-13）：`new-task.md` §3 有一行机器可读注释
+//   <!-- route-kinds: require=plan.md | fix=maintain.md | ... -->
+// 包 CLI **不再自带一份映射**——此前 STAGE_ENTRY 硬编码在包里，装户改入口文件名而不动包，
+// route 就会把 AI 指向一个不存在的 md（双源漂移）。权威表就在宿主 AI 也在读的 md 里，一处即两处用。
+//   读不到 → 回落到包内 DEFAULT_ROUTE_TABLE 并登记降级（老版本装户无该行，不静默假装取到单源）。
+const DEFAULT_ROUTE_TABLE = {
+  require: 'plan.md', fix: 'maintain.md', verify: 'test.md',
+  review: 'review.md', deploy: 'deploy.md',
+};
+const ROUTE_TABLE_LINE = /<!--\s*route-kinds:\s*([^>]*?)-->/;
+
+// route-kinds 行的**唯一解析器**——两个消费方共用：装户面 loadRouteTable（判定该读哪个 md）与
+//   包源 help 的 routeKindList（列 kind 值域）。此前 help 自带第二份 kind 列表，装户改 kind 时
+//   help 与判定面会漂移（与 GATE_LIST 同纪律：列表一律从权威面派生，不手写第二份）。
+function parseRouteTable(mdAbs) {
+  const m = fs.readFileSync(mdAbs, 'utf8').match(ROUTE_TABLE_LINE);
+  const table = {};
+  for (const part of String(m ? m[1] : '').split('|')) {
+    const kv = part.trim().match(/^([a-z]+)\s*=\s*([\w.-]+\.md)$/);
+    if (kv) table[kv[1]] = kv[2];
+  }
+  if (!Object.keys(table).length) throw new Error('route-kinds 行未解析出任何 kind');
+  return table;
+}
+
+function loadRouteTable(target, degradations) {
+  const p = path.join(target, '.agents', 'commands', 'new-task.md');
+  try {
+    return { table: parseRouteTable(p), source: 'new-task.md' };
+  } catch (e) {
+    degradations.push({ code: 'route-table-fallback', detail: `读不到装户 .agents/commands/new-task.md 的 route-kinds 机器单源（${String(e?.message || e).split('\n')[0]}）——kind→入口回落包内默认表，装户升级 flow-kit sync 后生效` });
+    return { table: { ...DEFAULT_ROUTE_TABLE }, source: 'fallback' };
+  }
+}
+
+// 包源 help 的 kind 值域：读包源权威 md（templates/_agents/commands/new-task.md）的 route-kinds 行，
+//   与装户面 loadRouteTable 共用同一解析器。读不到（包源缺该行/文件）回落包内默认表，不阻断 help。
+export function routeKindList(pkgRoot) {
+  try {
+    return Object.keys(parseRouteTable(path.join(pkgRoot, 'templates', '_agents', 'commands', 'new-task.md')));
+  } catch {
+    return Object.keys(DEFAULT_ROUTE_TABLE);
+  }
+}
+
+// laneOfDoc：调装户 stage-gates.mjs 的单源泳道取法。返回 { key, source, reason }
+//   source='stage-gates.mjs' → 真取到单源；source='fallback' → 装户缺该脚本或取不到，按档位直接回落
+//   （fail-soft，不阻断路由）。**reason 区分「文件不存在」与「存在但 import 失败」**（2026-10-13
+//   executor-review）——两者曾被合并成一句「缺失」，实测把「装户脚本依赖缺失导致 import 报错」诊断成
+//   「未安装」，排障方向直接被带偏。
+async function laneOfDoc(target, level) {
+  const p = path.join(target, ...`${AGENT_SCRIPTS_REL}/stage-gates.mjs`.split('/'));
+  if (!fs.existsSync(p)) {
+    return { key: fallbackLane(level), source: 'fallback', reason: '装户 .agents/scripts/stage-gates.mjs 不存在（未安装或版本更早）' };
+  }
+  try {
+    const mod = await import(pathToFileURL(p).href);
+    if (typeof mod.laneOfDoc === 'function') {
+      const got = mod.laneOfDoc(level);
+      if (got === 'low' || got === 'high' || got === 'suspect') return { key: got, source: 'stage-gates.mjs', reason: '' };
+      return { key: fallbackLane(level), source: 'fallback', reason: `装户 stage-gates.mjs 未返回合法泳道值（返回 ${JSON.stringify(got)}）` };
+    }
+    return { key: fallbackLane(level), source: 'fallback', reason: '装户 stage-gates.mjs 未导出 laneOfDoc（版本不匹配）' };
+  } catch (e) {
+    // 注意：这里必须把真实原因带出去——「脚本在但装不起来」与「脚本不在」是两回事。
+    const why = String(e?.message || e).split('\n')[0];
+    return { key: fallbackLane(level), source: 'fallback', reason: `装户 stage-gates.mjs 存在但 import 失败：${why}` };
+  }
+}
+
+const fallbackLane = (level) => ((rankOfLevel(level)) >= 2 ? 'high' : 'low');
+const rankOfLevel = (level) => ({ L0: 0, L1: 1, L2: 2, L3: 3 }[String(level || '').toUpperCase()] ?? 0);
+
+export async function route(args) {
+  const o = parseArgs(args);
+  const target = resolveTarget(o);
+  const scriptsDir = path.join(target, ...AGENT_SCRIPTS_REL.split('/'));
+  // 降级可见通道（2026-10-13 degradation-channel）：此前同一命令里混用四种「缺失」策略——
+  //   判据单源缺 → fail-loud；stage-gates 缺 → 静默回落泳道；enums 缺 → 静默用自带表；
+  //   hints 缺 → 静默按 L1 起步。**只有 laneSource 一个字段对外可见**，--json 消费方拿到的是同一份静默。
+  // 口径：fail-loud 的判据单源缺失仍在最前面（改配置比没配置危险），此后**所有软回落一律登记进
+  //   degradations**，文本与 --json 走同一个通道——降级必须可见，但不因此阻断定级（路由不该因为
+  //   词表缺失整个挂掉）。
+  const degradations = [];
+
+  // 判据单源在装户面（随模板下发、随 sync 升级）——包不复制判据，避免双源漂移
+  const critPath = path.join(scriptsDir, 'level-criteria.mjs');
+  if (!fs.existsSync(critPath)) {
+    fail(`未找到 .agents/scripts/level-criteria.mjs（级别判据单源）。\n   该文件随 1.7.15+ 下发；若你的项目更早，执行 flow-kit sync 升级。`);
+  }
+  const crit = await import(pathToFileURL(critPath).href);
+
+  // 枚举单源（模块值域 / kind 集合）：同样在装户面
+  let levelList = crit.LEVELS;
+  let modules = [];
+  try {
+    const enumsMod = await import(pathToFileURL(path.join(scriptsDir, 'workflow-enums.mjs')).href);
+    const enums = enumsMod.loadEnums(path.join(scriptsDir, '..', 'workflow-enums.txt'));
+    if (Array.isArray(enums['level.all']) && enums['level.all'].length) levelList = enums['level.all'];
+    else degradations.push({ code: 'enums-missing-key', detail: '.agents/workflow-enums.txt 无 level.all 键——档位值域回落判据单源自带表' });
+  } catch (e) {
+    degradations.push({ code: 'enums-fallback', detail: `读不到 .agents/workflow-enums.txt（${String(e?.message || e).split('\n')[0]}）——档位值域回落判据单源自带表，不阻断定级` });
+  }
+  const modFile = path.join(target, '.agents', 'workflow-modules.txt');
+  if (fs.existsSync(modFile)) {
+    modules = fs.readFileSync(modFile, 'utf8').split(/\r?\n/)
+      .map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+  }
+
+  // 路由表从装户权威 md 读（B5）：kind 闭集随之以装户为准，包内不再硬编码 kind 列表
+  const route = loadRouteTable(target, degradations);
+  const kind = typeof o.kind === 'string' ? o.kind : '';
+  if (kind && !Object.keys(route.table).includes(kind)) {
+    fail(`--kind 须为 ${Object.keys(route.table).join('|')}（实际「${kind}」，值域读自 ${route.source}）`);
+  }
+
+  const files = typeof o.files === 'string'
+    ? o.files.split(/[,，]/).map((s) => s.trim()).filter(Boolean)
+    : [];
+  const proposed = typeof o.level === 'string' ? o.level.toUpperCase() : '';
+  if (proposed && !levelList.includes(proposed)) {
+    fail(`--level 须为 ${levelList.join('|')}（实际「${proposed}」）`);
+  }
+
+  const a = crit.assessLevel(target, { files, proposed });
+  const level = a.level || 'L1';
+  // 泳道取法沿装户 stage-gates 单源（laneOfDoc：级别单字段协议），不在本文件复刻 low/high 口径。
+  //   装户无 stage-gates.mjs（老版本未升级）→ fail-soft 回退默认（判 L2/L3 → high），并登记降级。
+  const laneKey = await laneOfDoc(target, level);
+  if (laneKey.source === 'fallback') {
+    degradations.push({ code: 'lane-source-fallback', detail: `${laneKey.reason || '装户 .agents/scripts/stage-gates.mjs 缺失或 laneOfDoc 不可用'}——泳道按档位回落判定（建议 flow-kit sync 升级）` });
+  }
+  if (a.hintsConfigured === false) {
+    degradations.push({ code: 'level-hints-empty', detail: `.agents/level-hints.txt 未配置（缺失或为空）→ 机器面给不出档位提示，本次按 ${level} 起步；该清单登记「哪些路径一碰就至少是 L2/L3」（项目私有，只收 L2/L3 两档）` });
+  }
+  if (a.underHint) {
+    degradations.push({ code: 'under-hint-proposed', detail: `建议档 ${a.proposed} 低于路径提示下限 ${a.hintLevel}（命中：${(a.matched || []).slice(0, 4).join('、')}）——已按就高不就低取 ${a.hintLevel}，建议复核` });
+  }
+  const lane = laneKey.key === 'high' ? '防御道（同步确认门）' : '协作道（快车道）';
+  const entry = route.table[kind] || route.table.require;
+
+  if (o.json) {
+    console.log(JSON.stringify({
+      level, lane, laneKey: laneKey.key, laneSource: laneKey.source, kind: kind || '(未定)',
+      files, proposed: a.proposed, hintLevel: a.hintLevel, matched: a.matched,
+      underHint: a.underHint, hintsConfigured: a.hintsConfigured,
+      // 路由表来源（B5）：'new-task.md' = 真取到装户机器单源；'fallback' = 包内兜底表（已登记降级）
+      routeTableSource: route.source,
+      // 降级统一出口（消费方判「这次路由是否在降级态」只需看这一个字段，不必逐个猜 source 字段）
+      degraded: degradations.length > 0, degradations,
+      nextStage: entry, nextCommand: `.agents/commands/${entry}`,
+      modules,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`flow-kit route — 手动路由判定（机器面）\n`);
+  console.log(crit.routeAdvice(level, a));
+  console.log('');
+  console.log(`泳道：${lane}`);
+  if (kind) console.log(`入口指令：.agents/commands/${entry}（kind=${kind}）`);
+  else console.log(`入口指令：未定 —— 先判 kind（require 新需求 / fix 修复 / verify 验证 / review 评审 / deploy 上线）`);
+  console.log(`  new-task 阶段索引：.agents/commands/new-task.md`);
+  if (degradations.length) {
+    console.log('');
+    console.log(`⚠️ 降级运行（${degradations.length} 项——机器面能给的部分比完整态少，逐条点名）：`);
+    for (const d of degradations) console.log(`  · [${d.code}] ${d.detail}`);
+  }
+  console.log('');
+  console.log('本命令只给机器可判的部分。**定级仍需语义判断**——按上面自查句逐条判；');
+  console.log('不确定就高不就低。要走全自动六阶段闭环另用：flow-kit run start "<需求>"');
+}
+
+// 薄壳自有参数：这些是包 CLI 的选项，**不**透传给装户状态机（状态机有自己的参数协议）
+const SHELL_ONLY_KEYS = new Set(['dir']);
+
+export function runPipeline(args) {
+  const o = parseArgs(args);
+  const sub = o._[0];
+  // 用法校验先于脚本存在性校验：先告诉用户「怎么用」，再谈装没装（反过来会拿安装问题盖住用法）
+  if (!sub) {
+    fail('用法：flow-kit run <start|next|status|watch|abort> [...]\n' +
+         '   驱动协议与停机点语义见 .agents/commands/pipeline-run.md（该文件是宿主面权威，本命令只透传）。');
+  }
+  const target = resolveTarget(o);
+  const script = requireInstalledScript(target, `${AGENT_SCRIPTS_REL}/pipeline-run.mjs`);
+  // 透传 = 用户给的参数原样交给装户状态机，但**剔除薄壳自有参数**（--dir 是包面寻址，不是状态机参数）
+  const passthrough = [];
+  for (let i = args.indexOf(sub) + 1; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2).split('=')[0];
+      if (SHELL_ONLY_KEYS.has(k)) {
+        if (!a.includes('=') && args[i + 1] !== undefined && !args[i + 1].startsWith('--')) i++;
+        continue;
+      }
+    }
+    passthrough.push(a);
+  }
+  const r = spawnSync(process.execPath, [script, sub, ...passthrough], {
+    cwd: target, stdio: 'inherit', windowsHide: true,
+  });
+  process.exit(r.status ?? 1);
+}

package/src/executor.test.mjs

@@ -0,0 +1,295 @@
+// executor.test.mjs — flow-kit route / run 薄壳套件（2026-10-13 flow-kit-route）
+// 方法：子进程 driver 调真实 src/executor.mjs（route 内部会 process.exit，隔离到子进程才能测退出码与 stdout）；
+//       装户 fixture 只放薄壳**依赖面**文件（level-criteria.mjs 真拷、stage-gates/pipeline-run 用哨兵 stub）。
+// 覆盖：route 档位与入口映射 / hints 抬档与 underHint / 泳道真取装户单源（缺失时回落并标注）/
+//       --kind·--level 非法值 fail-loud / 缺判据单源 fail-loud / --json 机读面 /
+//       run 参数·退出码透传 / run 缺子命令用法提示 / run 缺 pipeline-run 指向 init-sync。
+// 用法：node src/executor.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, pathToFileURL } from 'node:url';
+
+const SRC = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(SRC, '..');
+const REAL_CRIT = path.join(PKG, 'templates/_agents/scripts/level-criteria.mjs');
+const REAL_ENUMS_MJS = path.join(PKG, 'templates/_agents/scripts/workflow-enums.mjs');
+const REAL_ENUMS_TXT = path.join(PKG, 'templates/_agents/workflow-enums.txt');
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`  ok  ${name}`); }
+  else { failCount++; console.error(`FAIL  ${name}${detail ? ' — ' + detail : ''}`); }
+}
+const W = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content, 'utf8'); };
+
+// 装户 fixture：判据单源与枚举单源真拷；stage-gates / pipeline-run 用哨兵 stub（证明薄壳是「调用装户」而非自带实现）
+//   withEnums 默认 true = 完整装户面。降级通道（2026-10-13）要求能断言「完整态无降级」，
+//   若夹具恒缺枚举单源，enums-fallback 会恒真、该断言即假护栏。
+function mkProject({ withCrit = true, withStageGates = true, withEnums = true, withRouteTable = true, laneKey = null, hints = null, modules = null } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-exec-'));
+  const S = path.join(root, '.agents', 'scripts');
+  if (withCrit) fs.mkdirSync(S, { recursive: true }), fs.copyFileSync(REAL_CRIT, path.join(S, 'level-criteria.mjs'));
+  if (withStageGates) {
+    // 默认哨兵：按 L2/L3 → high 的常规口径（写在被写入的 stub 文件里，在装户侧求值）
+    const body = laneKey
+      ? `return ${JSON.stringify(laneKey)};`
+      : `return (level === 'L2' || level === 'L3') ? 'high' : 'low';`;
+    W(path.join(S, 'stage-gates.mjs'), `export function laneOfDoc(level){ ${body} }\n`);
+  }
+  if (hints !== null) W(path.join(root, '.agents', 'level-hints.txt'), hints);
+  if (modules !== null) W(path.join(root, '.agents', 'workflow-modules.txt'), modules);
+  if (withEnums) {
+    fs.mkdirSync(S, { recursive: true });
+    fs.copyFileSync(REAL_ENUMS_MJS, path.join(S, 'workflow-enums.mjs'));
+    fs.copyFileSync(REAL_ENUMS_TXT, path.join(root, '.agents', 'workflow-enums.txt'));
+  }
+  // 完整装户必带 route-kinds 机器单源（B5）：kind→入口映射的权威在 new-task.md，包内不再自带一份
+  if (withRouteTable) {
+    fs.mkdirSync(path.join(root, '.agents', 'commands'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.agents/commands/new-task.md'),
+      '## 3. 路由判断\n\n<!-- route-kinds: require=plan.md | fix=maintain.md | verify=test.md | review=review.md | deploy=deploy.md -->\n', 'utf8');
+  }
+  return root;
+}
+
+function runCli(args, cwd) {
+  // win32 绝对路径必须转 file:// URL，否则 ESM loader 判 ERR_UNSUPPORTED_ESM_URL_SCHEME（protocol 'e:'）
+  const href = pathToFileURL(path.join(SRC, 'executor.mjs')).href;
+  const driver = `import(${JSON.stringify(href)})`
+    + `.then(m=>m.${args[0] === 'run' ? 'runPipeline' : 'route'}(${JSON.stringify(args.slice(1))}))`;
+  return spawnSync(process.execPath, ['-e', driver], { cwd, encoding: 'utf8', windowsHide: true });
+}
+const route = (args, cwd) => runCli(['route', ...args], cwd);
+const run = (args, cwd) => runCli(['run', ...args], cwd);
+
+// ============ 场景 1：无 hints（默认装户）→ L1 起步 + 明示未配置 ============
+{
+  const r = mkProject();
+  const x = route(['--kind', 'require'], r);
+  check('S1 exit=0', x.status === 0, `status=${x.status} ${x.stderr}`);
+  check('S1 给出 L1', x.stdout.includes('建议级别：L1'));
+  check('S1 明示机器面给不出档位（不假装判得出）', x.stdout.includes('未配置') && x.stdout.includes('L1 起步'));
+  check('S1 带 level-hints.txt 路径指引', x.stdout.includes('.agents/level-hints.txt'));
+  check('S1 输出 L1 负例面', x.stdout.includes('单模块内部重构'));
+  check('S1 输出自查句', x.stdout.includes('能否列出'));
+  check('S1 kind=require → plan.md 入口', x.stdout.includes('.agents/commands/plan.md'));
+  check('S1 泳道=协作道', x.stdout.includes('泳道：协作道'));
+}
+
+// ============ 场景 2：kind → 入口 md 映射（五个值全覆盖） ============
+{
+  const r = mkProject();
+  const map = { require: 'plan.md', fix: 'maintain.md', verify: 'test.md', review: 'review.md', deploy: 'deploy.md' };
+  for (const [kind, md] of Object.entries(map)) {
+    const x = route(['--kind', kind, '--json'], r);
+    const j = JSON.parse(x.stdout);
+    check(`S2 kind=${kind} → ${md}`, j.nextCommand === `.agents/commands/${md}`, JSON.stringify(j.nextCommand));
+  }
+  const none = JSON.parse(route(['--json'], r).stdout);
+  check('S2 未给 kind → 默认 require 且显式标记未定', none.kind === '(未定)' && none.nextStage === 'plan.md');
+  check('S2 未给 kind 的文本面提示先判 kind', route([], r).stdout.includes('先判 kind'));
+}
+
+// ============ 场景 3：hints 抬档 + underHint ============
+{
+  const r = mkProject({ hints: 'L3 ^src/db/migrations/.*\\.sql$\nL2 ^src/contracts/\n' });
+  const hit = route(['--files', 'src/db/migrations/001_init.sql', '--json'], r);
+  const hj = JSON.parse(hit.stdout);
+  check('S3 hints 命中抬到 L3', hj.level === 'L3' && hj.hintLevel === 'L3');
+  check('S3 matched 带命中证据', hj.matched.length > 0 && hj.matched[0].includes('001_init.sql'), JSON.stringify(hj.matched));
+  check('S3 L2 hints 抬到 L2', JSON.parse(route(['--files', 'src/contracts/t.ts', '--json'], r).stdout).level === 'L2');
+  const low = JSON.parse(route(['--level', 'L1', '--files', 'src/db/migrations/002_x.sql', '--json'], r).stdout);
+  check('S3 建议档低于下限 → underHint=true', low.underHint === true);
+  check('S3 就高不就低：level 仍取下限 L3', low.level === 'L3');
+  check('S3 文本面输出改判警告', route(['--level', 'L1', '--files', 'src/db/migrations/002_x.sql'], r).stdout.includes('低于路径提示下限'));
+  const miss = JSON.parse(route(['--files', 'src/ui/b.tsx', '--json'], r).stdout);
+  check('S3 未命中 → L1 且 hintLevel 空', miss.level === 'L1' && miss.hintLevel === '' && miss.matched.length === 0);
+  check('S3 多文件逗号/中文逗号切分', JSON.parse(route(['--files', 'src/a.ts,src/contracts/t.ts', '--json'], r).stdout).level === 'L2');
+  // 寻址：--dir=<path> 与 --dir <path> 等价（后者被 parseArgs 消费后不能落进 files）
+  const eqDir = route([`--dir=${r}`, '--kind', 'require', '--files', 'src/contracts/t.ts', '--json'], os.tmpdir());
+  check('S3 --dir= 形式定位装户根', JSON.parse(eqDir.stdout).level === 'L2', eqDir.stderr);
+  check('S3 --dir 不被误当改动文件', JSON.parse(eqDir.stdout).files.length === 1, eqDir.stdout);
+}
+
+// ============ 场景 4：泳道真取装户单源 ============
+{
+  // 哨兵：装户 laneOfDoc 对 L1 返回 low、对 L2 返回 high —— 若薄壳自带实现（按档写死），
+  // 换成「L2 返回 low」的哨兵即可测出：薄壳必须问装户，不能自己判。
+  const r = mkProject({ laneKey: null });
+  W(path.join(r, '.agents', 'scripts', 'stage-gates.mjs'),
+    'export function laneOfDoc(level){ return level === "L2" ? "low" : "high"; }\n');
+  const j = JSON.parse(route(['--kind', 'require', '--level', 'L2', '--json'], r).stdout);
+  check('S4 泳道取装户单源返回值（不按档写死）', j.laneKey === 'low', `laneKey=${j.laneKey}`);
+  check('S4 laneSource 标明单源', j.laneSource === 'stage-gates.mjs', j.laneSource);
+  check('S4 low → 协作道', j.lane === '协作道（快车道）');
+  const j2 = JSON.parse(route(['--level', 'L3', '--json'], r).stdout);
+  check('S4 high → 防御道', j2.laneKey === 'high' && j2.lane.includes('防御道'));
+
+  // 单源返回非法值 → 不假装取到，回落并标注
+  const bad = mkProject();
+  W(path.join(bad, '.agents', 'scripts', 'stage-gates.mjs'), 'export function laneOfDoc(){ return "banana"; }\n');
+  const bj = JSON.parse(route(['--level', 'L2', '--json'], bad).stdout);
+  check('S4 单源返回非法值 → 回落', bj.laneKey === 'high' && bj.laneSource === 'fallback', JSON.stringify(bj.laneKey));
+
+  // 单源缺失 → 回落 + 降级通道可见（2026-10-13 degradation-channel：文本与 JSON 同一出口）
+  const miss = mkProject({ withStageGates: false });
+  const mx = route(['--level', 'L2'], miss);
+  check('S4 单源缺失 → 回落标注', mx.stdout.includes('lane-source-fallback'), mx.stdout.slice(-200));
+  check('S4 降级文本面统一出口', mx.stdout.includes('降级运行'));
+  check('S4 缺单源不阻断路由（仍给档位与入口）', mx.stdout.includes('建议级别：L2') && mx.status === 0);
+  const mj = JSON.parse(route(['--level', 'L2', '--json'], miss).stdout);
+  check('S4 缺单源时 JSON 面标 fallback', mj.laneSource === 'fallback');
+  check('S4 JSON 降级数组含 lane-source-fallback', mj.degraded === true && mj.degradations.some((d) => d.code === 'lane-source-fallback'), JSON.stringify(mj.degradations));
+}
+
+// ============ 场景 4b：降级通道完整性（此前四种缺失策略混用、只有 laneSource 可见）============
+{
+  const codesOf = (proj, args) => JSON.parse(route(args.concat(['--json']), proj).stdout).degradations.map((d) => d.code);
+
+  // 判据单源齐全、无 hints → level-hints-empty 必须登记（此前对 JSON 消费方完全静默）
+  const noHints = mkProject();
+  const c1 = codesOf(noHints, ['--level', 'L1']);
+  check('S4b 未配 hints → 降级登记 level-hints-empty', c1.includes('level-hints-empty'), JSON.stringify(c1));
+  check('S4b 配了 hints 后不再报该降级', (() => {
+    fs.writeFileSync(path.join(noHints, '.agents', 'level-hints.txt'), '# x\nL2 ^src/db/\n');
+    return !codesOf(noHints, ['--level', 'L1']).includes('level-hints-empty');
+  })());
+
+  // 枚举单源缺失 → enums-fallback（此前静默用自带表）
+  const noEnums = mkProject({ withEnums: false });
+  check('S4b 枚举缺失 → 降级登记 enums-fallback', codesOf(noEnums, ['--level', 'L1']).includes('enums-fallback'), JSON.stringify(codesOf(noEnums, ['--level', 'L1'])));
+
+  // 建议档低于 hints 下限 → under-hint-proposed（此前仅 warning 字段，无统一出口）
+  const under = mkProject();
+  fs.writeFileSync(path.join(under, '.agents', 'level-hints.txt'), 'L3 ^src/db/\n');
+  const c3 = codesOf(under, ['--level', 'L1', '--files', 'src/db/schema.sql']);
+  check('S4b 判低 → 降级登记 under-hint-proposed 且仍按就高不就低取 L3', c3.includes('under-hint-proposed')
+    && JSON.parse(route(['--level', 'L1', '--files', 'src/db/schema.sql', '--json'], under).stdout).level === 'L3', JSON.stringify(c3));
+
+  // 完整态（hints + 枚举 + 单源齐全）→ degraded=false，降级数组为空
+  const full = mkProject();
+  fs.writeFileSync(path.join(full, '.agents', 'level-hints.txt'), 'L2 ^src/db/\n');
+  const fj = JSON.parse(route(['--level', 'L1', '--json'], full).stdout);
+  check('S4b 完整态无降级', fj.degraded === false && fj.degradations.length === 0, JSON.stringify(fj.degradations));
+}
+
+// ============ 场景 5：非法输入 fail-loud ============
+{
+  const r = mkProject();
+  const k = route(['--kind', 'bogus'], r);
+  check('S5 非法 kind exit=1', k.status === 1);
+  check('S5 非法 kind 报文列合法值', k.stderr.includes('require|fix|verify|review|deploy'), k.stderr);
+  const l = route(['--level', 'L9'], r);
+  check('S5 非法 level exit=1 且列闭集', l.status === 1 && l.stderr.includes('L1|L2|L3'), l.stderr);
+  // L0 已退役（2026-10-13 自源仓收敛系列 1 回灌）：--level L0 按非法档 fail-loud（枚举 fixture 已收敛 L1-L3）
+  const l0 = route(['--level', 'L0'], r);
+  check('S5b 已退役的 L0 exit=1 且报文即闭集', l0.status === 1 && l0.stderr.includes('--level 须为 L1|L2|L3'), l0.stderr);
+  const nc = mkProject({ withCrit: false });
+  const n = route([], nc);
+  check('S5 缺判据单源 exit=1', n.status === 1);
+  check('S5 缺判据单源指向 sync 升级（不自动改盘面）', n.stderr.includes('flow-kit sync'), n.stderr);
+  const badHints = route(['--files', 'src/a.ts'], mkProject({ hints: 'L9 ^src/\n' }));
+  check('S5 非法 hints 配置 → exit=1 且报错定位', badHints.status === 1 && badHints.stderr.includes('level-hints.txt'));
+}
+
+// ============ 场景 6：--json 机读面 ============
+{
+  const r = mkProject({ hints: 'L2 ^src/contracts/\n', modules: '# 注释\nbilling\norder\n' });
+  const x = route(['--kind', 'fix', '--files', 'src/contracts/t.ts', '--json'], r);
+  check('S6 exit=0 且 stdout 是纯 JSON', x.status === 0 && (() => { try { JSON.parse(x.stdout); return true; } catch { return false; } })(), x.stdout.slice(0, 120));
+  const j = JSON.parse(x.stdout);
+  check('S6 字段齐备', ['level', 'lane', 'laneKey', 'laneSource', 'kind', 'files', 'proposed', 'hintLevel', 'matched', 'underHint', 'hintsConfigured', 'nextStage', 'nextCommand', 'modules']
+    .every((k) => k in j), Object.keys(j).join(','));
+  check('S6 modules 读装户词表（去注释）', Array.isArray(j.modules) && j.modules.length === 2 && !j.modules.includes('# 注释'), JSON.stringify(j.modules));
+  check('S6 JSON 面不含人读散文（判据面归单源）', !x.stdout.includes('能否列出'));
+}
+
+// ============ 场景 7：run 透传（参数 + 退出码 + cwd） ============
+{
+  const r = mkProject();
+  W(path.join(r, '.agents', 'scripts', 'pipeline-run.mjs'),
+    'const a = process.argv.slice(2);\n'
+    + 'console.log("STUB_PIPE " + JSON.stringify(a) + " cwd=" + process.cwd());\n'
+    + 'process.exit(a[0] === "boom" ? 7 : 0);\n');
+  const st = run(['status'], r);
+  check('S7 status 透传成功 exit=0', st.status === 0, st.stderr);
+  check('S7 参数原样送达装户状态机', st.stdout.includes('STUB_PIPE ["status"]'), st.stdout.trim());
+  check('S7 cwd = 装户根', st.stdout.includes(path.resolve(r).replace(/\\/g, '\\')), st.stdout.trim());
+  const nx = run(['next'], r);
+  check('S7 next 透传', nx.stdout.includes('["next"]'));
+  const bo = run(['boom'], r);
+  check('S7 装户非零退出码原样回传', bo.status === 7, `status=${bo.status}`);
+  const args = run(['start', '给导入功能加审计字段'], r);
+  check('S7 含空格的需求原话不被拆词', args.stdout.includes('["start","给导入功能加审计字段"]'), args.stdout.trim());
+  const withDir = run(['status', '--dir', r], os.tmpdir());
+  check('S7 --dir 被薄壳消费、不透传状态机', withDir.stdout.includes('["status"]'), withDir.stdout.trim());
+  check('S7 --dir 仍定位到装户根', withDir.stdout.includes('STUB_PIPE') && withDir.status === 0, withDir.stderr);
+  const dirEq = run([`--dir=${r}`, 'status'], os.tmpdir());
+  check('S7 --dir= 形式同样被消费', dirEq.stdout.includes('["status"]'), dirEq.stdout.trim());
+}
+
+// ============ 场景 8：run 的 fail-loud 与边界 ============
+{
+  const r = mkProject();
+  const noSub = run([], r);
+  check('S8 缺子命令 exit=1', noSub.status === 1);
+  check('S8 缺子命令列子命令闭集', noSub.stderr.includes('start|next|status|watch|abort'), noSub.stderr);
+  check('S8 缺子命令指向宿主面驱动协议权威', noSub.stderr.includes('.agents/commands/pipeline-run.md'), noSub.stderr);
+  const bare = mkProject();
+  fs.unlinkSync(path.join(bare, '.agents', 'scripts', 'level-criteria.mjs'));
+  const miss = run(['status'], bare);
+  check('S8 缺 pipeline-run exit=1', miss.status === 1);
+  check('S8 缺脚本指向 init/sync（不静默装一遍）', miss.stderr.includes('flow-kit init') && miss.stderr.includes('flow-kit sync'), miss.stderr);
+  const notInstalled = run(['status'], mkProject({ withCrit: false }));
+  check('S8 非装户目录 → 明确报未安装', notInstalled.stderr.includes('不是已安装 flow-kit 的项目'), notInstalled.stderr);
+}
+
+// ============ 场景 9：薄壳纪律 —— 包面不复制判据/不自带实现 ============
+{
+  const ex = fs.readFileSync(path.join(SRC, 'executor.mjs'), 'utf8');
+  check('S9 包面不硬编码判据散文', !ex.includes('聚合投影键') && !ex.includes('能否列出'));
+  check('S9 包面不硬编码泳道 low/high 口径', !/level === 'L2' \|\| level === 'L3'/.test(ex));
+  // 纪律只查**代码里的引用形式**（引号包裹的实参），不查注释散文——注释里出现「不带 --no-verify」是
+  // 纪律声明本身，不是违规；把它也算违规等于逼人删掉自述。
+  check('S9 薄壳代码不出现 --no-verify 实参', !ex.includes("'--no-verify'") && !ex.includes('"--no-verify"'));
+  check('S9 薄壳不 spawn AI 会话', !/claude|codex|opencode|gemini/.test(ex));
+  check('S9 判据单源从装户面动态载入（不在包内拷一份）', ex.includes('level-criteria.mjs') && ex.includes('import('));
+}
+
+// ============ 场景 4c：kind→入口读装户权威表（B5：包内不再自带一份映射）============
+{
+  // ① 默认夹具带 route-kinds 行 → routeTableSource 应为 new-task.md（非兜底）
+  const r = mkProject();
+  fs.mkdirSync(path.join(r, '.agents', 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(r, '.agents', 'commands', 'new-task.md'),
+    '## 3. 路由判断\n\n<!-- route-kinds: require=plan.md | fix=maintain.md | verify=test.md | review=review.md | deploy=deploy.md -->\n', 'utf8');
+  const j = JSON.parse(route(['--kind', 'fix', '--json'], r).stdout);
+  check('S4c 路由表取自装户 new-task.md（非兜底）', j.routeTableSource === 'new-task.md', j.routeTableSource);
+  check('S4c kind=fix → 入口取自权威表', j.nextStage === 'maintain.md', j.nextStage);
+
+  // ② 装户把入口改了个名（模拟项目自定义）→ 包必须跟随，不得仍指向旧名
+  fs.writeFileSync(path.join(r, '.agents', 'commands', 'new-task.md'),
+    '<!-- route-kinds: require=plan.md | fix=hotfix.md | verify=test.md | review=review.md | deploy=deploy.md -->\n', 'utf8');
+  const j2 = JSON.parse(route(['--kind', 'fix', '--json'], r).stdout);
+  check('S4c 装户改入口名 → 包跟随权威表（无第二份硬编码）', j2.nextStage === 'hotfix.md', j2.nextStage);
+
+  // ③ 权威表读不到 → 回退包内默认表 + 登记降级（老版本装户无该行，不静默假装）
+  const r3 = mkProject({ withRouteTable: false });
+  const j3 = JSON.parse(route(['--kind', 'require', '--json'], r3).stdout);
+  check('S4c 无 route-kinds 行 → 回落 + 登记 route-table-fallback',
+    j3.routeTableSource === 'fallback' && j3.nextStage === 'plan.md'
+      && j3.degradations.some((d) => d.code === 'route-table-fallback'), JSON.stringify(j3.degradations));
+
+  // ④ kind 闭集随权威表走：表里没有的 kind 判红，报文点明值域来源
+  const r4 = mkProject();
+  fs.writeFileSync(path.join(r4, '.agents', 'commands', 'new-task.md'),
+    '<!-- route-kinds: require=plan.md | ship=deploy.md -->\n', 'utf8');
+  const bad = route(['--kind', 'fix'], r4);
+  check('S4c 权威表无该 kind → exit 1 且值域读自权威表',
+    bad.status === 1 && bad.stderr.includes('require|ship') && bad.stderr.includes('new-task.md'), bad.stderr);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

package/src/fresh-init.test.mjs

@@ -24,7 +24,7 @@ const r = spawnSync(process.execPath, [
 const out = `${r.stdout || ''}${r.stderr || ''}`;
 check('fresh init exit 0', r.status === 0, `exit=${r.status}\n${out.split('\n').slice(-30).join('\n')}`);
 const kit = JSON.parse(fs.readFileSync(path.join(dir, '.agents', 'kit.json'), 'utf8'));
-check('新装 audit 为 false 且 policyVersion 为 2', kit.audit === false && kit.policyVersion === 2, JSON.stringify({ audit: kit.audit, policyVersion: kit.policyVersion }));
+check('新装 audit 为 false 且 policyVersion 为 12（2026-10-13 B6b-2 回灌对齐源仓 v12：新装即带全锚——§21–26 六段 + §3x + 复核上下文；新装空台账零回溯）', kit.audit === false && kit.policyVersion === 12, JSON.stringify({ audit: kit.audit, policyVersion: kit.policyVersion }));
 // 模板下发感知初始锚（2026-10-06 template-downstream）：有包源模板对应的 owned 条目带 srcSha256＝
 // 包源模板原文 LF 归一 sha；生成器目标（INDEX.md 类）排除出感知面无该键
 {

package/src/init.mjs

@@ -243,9 +243,11 @@ export async function init(args, pkgRoot) {
   }
 
   // 4) .gitignore 追加（缺哪条补哪条）。2026-10-05 起七个宿主一律 localOnly:false，
-  // 宿主目录不再自动进 .gitignore——实际只补 .agents/cache/ 这条运行时缓存。
+  // 宿主目录不再自动进 .gitignore——补 .agents/cache/ 运行时缓存与 .agents/judgments.jsonl
+  // 判定流水（2026-10-13 judgment-ledger 回灌 B4：check-loop 每次真实运行追加的本机运行判定，
+  // 各机各自产生不跨机共享，月度聚合经 agg-judgments.mjs）。
   const giPath = path.join(target, '.gitignore');
-  const giNeed = ['.agents/cache/', ...(hosts.filter((h) => HOSTS[h].localOnly).map((h) => `${HOSTS[h].dir}/`))];
+  const giNeed = ['.agents/cache/', '.agents/judgments.jsonl', ...(hosts.filter((h) => HOSTS[h].localOnly).map((h) => `${HOSTS[h].dir}/`))];
   let giText = fs.existsSync(giPath) ? fs.readFileSync(giPath, 'utf8') : '';
   const giAdd = giNeed.filter((l) => !giText.split(/\r?\n/).some((x) => x.trim() === l));
   if (giAdd.length) {
@@ -263,6 +265,13 @@ export async function init(args, pkgRoot) {
       execSync('git config merge.ours.driver true', { cwd: target, stdio: 'pipe' });
       console.log('  已启用 merge.ours driver（.gitattributes 的 merge=ours 生效）');
     } catch { /* 可选配置，失败不阻断 */ }
+    try {
+      // 台账并集合并 driver（2026-10-12 ledger-merge-driver）：确认台账是尾部追加形态，多人/多 worktree
+      // 并行时默认合并会给文本冲突，人工「整取一侧」会静默丢确认行。配了 driver 后合并 = 并集去重。
+      // 本机态配置不跨机共享（与 core.hooksPath 同款性质）——漏配则退化为文本冲突，不静默丢数据。
+      execSync('git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"', { cwd: target, stdio: 'pipe' });
+      console.log('  已启用 merge.jsonl-union driver（台账 .agents/*.jsonl 合并走并集去重，不再文本冲突）');
+    } catch { /* 可选配置，失败不阻断 */ }
   } catch {
     console.log('  ⚠️ 目标不是 git 仓库——钩子未挂载；git init 后手动执行：git config core.hooksPath .githooks');
   }
@@ -324,7 +333,11 @@ export async function init(args, pkgRoot) {
   fs.writeFileSync(kitPath, `${JSON.stringify({
     kit: 'agentic-flow-kit',
     version: pkg.version,
-    policyVersion: 2,
+    // policyVersion 12（2026-10-13 B6b-2 回灌对齐源仓 v12）：新装即带全锚——v9–v12 = incidentRegrSince /
+    // specVerifSince / attributionSince / convergenceSince / convergenceHardSince / reviewerSince
+    // （§21–26 六段 + §3x 防复发证据门 + 复核上下文子检）。新装空台账零回溯：各段锚前存量豁免、空仓零
+    // 噪声；v1–v11 存量装户不受影响（缺键 → 对应消费段整体跳过）。
+    policyVersion: 12,
     // 新装默认只跑硬规则。缺省（旧台账无此字段）在 check-loop 里仍是全量，避免升级后卫生检查突然消失。
     audit: false,
     // 门禁信任档（2026-10-12 gate-trust-level）：默认 'project' —— gate 安装锚失配只 WARN，
@@ -340,6 +353,17 @@ export async function init(args, pkgRoot) {
   }, null, 2)}\n`);
   console.log(`  kit.json 台账：managed ${managed.length} 份 ｜ owned ${ownedFinal.length} 份（版本 ${pkg.version}）`);
 
+  // 生效规则视图种子（2026-10-13 verify-gates 回灌）：verify.mjs `effective-policy` 门 --check 对缺文件
+  // 判漂移（红）——源仓等价物是该生成物随生成器同笔入库；kit 新装由 init 首跑种子，保证 fresh 装户
+  // 首个 verify 不被卡。**必须在 kit.json 落盘之后**：渲染读 loadKitPolicy（.agents/kit.json 的
+  // policyVersion），先跑会按回落 v1 种子、装完即与 v12 视图漂移（fresh 实测）。本文件不入 owned 台账
+  // （生成器重写面，非模板渲染件），不受 P1-2「先跑后记账」约束；视图日期 = 安装日，--check 按磁盘
+  // 视图日期重渲染，跨锚日字节稳定。
+  if (guardRun('.agents/scripts/gen-effective-policy.mjs')) {
+    const genPolicy = runNode(target, '.agents/scripts/gen-effective-policy.mjs');
+    console.log(genPolicy.ok ? '  已生成 workflow/effective-policy.md（生效规则视图——policy 变更后重生成并随同提交）' : `  ⚠️ gen-effective-policy 失败：${genPolicy.out.split('\n')[0]}`);
+  }
+
   // 8) 自检（kit.json 已按生成后盘面记账——doctor §6.6 应全绿，fresh init 以 exit 0 收场）
   // 输出语义（p2-batch1 P2-4）：doctor 打印在异步端口回调里、晚于本横幅——脚本化消费方按退出码判定
   console.log('▶ flow-kit doctor（安装产物已就位；体检 FAIL 时本命令 exit 1，产物无损——按 FAIL 项处置）');