agentic-flow-kit 1.8.2 → 2.0.0

package/src/executor.mjs

@@ -1,262 +0,0 @@
-// 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

@@ -1,295 +0,0 @@
-// 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

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-// 空 git 仓库 fresh init --hosts claude：doctor 必须 exit 0，kit 写 audit:false，薄适配落盘。
-import { spawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const git = process.platform === 'win32' ? 'git.exe' : 'git';
-let pass = 0;
-let fail = 0;
-const check = (name, cond, detail = '') => {
-  if (cond) { pass++; console.log(`PASS  ${name}`); }
-  else { fail++; console.log(`FAIL  ${name}${detail ? `\n      ${detail}` : ''}`); }
-};
-
-const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-fresh-'));
-spawnSync(git, ['init', '-q'], { cwd: dir });
-const r = spawnSync(process.execPath, [
-  path.join(ROOT, 'bin', 'flow-kit.mjs'), 'init',
-  '--stack', 'none', '--hosts', 'claude', '--board-port', '8941', '--dir', dir,
-], { encoding: 'utf8', timeout: 120000 });
-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 为 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 类）排除出感知面无该键
-{
-  const { createHash } = await import('node:crypto');
-  const tplAnchor = (rel) => kit.owned.find((f) => f.rel === rel);
-  const shaOf = (buf) => createHash('sha256').update(buf).digest('hex');
-  const agents = tplAnchor('AGENTS.md');
-  const srcRaw = fs.readFileSync(path.join(ROOT, 'templates', 'AGENTS.md'), 'utf8').replace(/\r\n/g, '\n');
-  check('新装 owned 模板条目带 srcSha256 且等于包源原文 sha（AGENTS.md）',
-    agents && typeof agents.srcSha256 === 'string' && agents.srcSha256 === shaOf(Buffer.from(srcRaw, 'utf8')),
-    JSON.stringify(agents || null));
-  check('新装生成器目标无锚（wiki/INDEX.md 排除出感知面）',
-    tplAnchor('wiki/INDEX.md') !== undefined && tplAnchor('wiki/INDEX.md').srcSha256 === undefined);
-  const cfg = tplAnchor('.agents/hooks/commit-check.config.json');
-  check('新装无包源模板对应条目无锚（生成类配置不参与感知）', cfg !== undefined && cfg.srcSha256 === undefined);
-  const rb = tplAnchor('.agents/rule-budgets.txt');
-  check('新装 _agents 前缀翻译参与感知（rule-budgets 带锚）', rb !== undefined && typeof rb.srcSha256 === 'string');
-  // CI 远端门模板（2026-10-07 adopter-ci-github）：.github → _github 通用点前缀翻译 + owned 落盘带锚
-  const ci = tplAnchor('.github/workflows/kit-ci.yml');
-  const ciSrc = fs.readFileSync(path.join(ROOT, 'templates', '_github', 'workflows', 'kit-ci.yml'), 'utf8').replace(/\r\n/g, '\n');
-  check('新装 CI 远端门模板落盘且 kit.json owned 带锚（srcSha256 == 包源 LF 归一 sha）',
-    fs.existsSync(path.join(dir, '.github', 'workflows', 'kit-ci.yml'))
-    && ci !== undefined && ci.srcSha256 === shaOf(Buffer.from(ciSrc, 'utf8')),
-    JSON.stringify(ci || null));
-  const ciText = fs.readFileSync(path.join(dir, '.github', 'workflows', 'kit-ci.yml'), 'utf8');
-  check('新装 CI 模板引用统一入口 verify.mjs、含分支策略人工边界提示且无 Tab 缩进',
-    ciText.includes('node .agents/scripts/verify.mjs') && ciText.includes('branch protection') && !ciText.includes('\t'));
-}
-check('claude 命令与角色薄适配落盘',
-  fs.existsSync(path.join(dir, '.claude', 'commands', 'wf-plan.md'))
-  && fs.existsSync(path.join(dir, '.claude', 'agents', 'implementer.md')));
-const hooks = spawnSync(git, ['config', 'core.hooksPath'], { cwd: dir, encoding: 'utf8' });
-check('钩子已挂到 .githooks', hooks.stdout.trim() === '.githooks', hooks.stdout);
-fs.rmSync(dir, { recursive: true, force: true });
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);