agentic-flow-kit 1.7.0 → 1.7.16

package/src/executor.test.mjs

@@ -0,0 +1,292 @@
+// 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('L0|L1|L2|L3'), l.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/gates.test.mjs

@@ -121,6 +121,23 @@ function run(script, dir, env = {}) {
   check('generated 暂存改区外、工作区改区内 → exit 0', ok.status === 0, ok.stderr);
   fs.rmSync(dir, { recursive: true, force: true });
 }
+{
+  const dir = repo();
+  stage(dir, 'src/app.mjs', 'export const fix = 1;\n');
+  stage(dir, 'tests/app.test.mjs', "import { fix } from '../src/app.mjs';\n");
+  const bad = run('modules/gates/test-protect/check-test-protect.mjs', dir);
+  check('test-protect 测试与代码同框 → exit 1', bad.status === 1 && bad.stderr.includes('test-protect'), bad.stderr);
+  const allowed = run('modules/gates/test-protect/check-test-protect.mjs', dir, { FLOW_KIT_ALLOW_TEST_EDIT: '1' });
+  check('test-protect FLOW_KIT_ALLOW_TEST_EDIT=1 → exit 0', allowed.status === 0, allowed.stderr);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+{
+  const dir = repo();
+  stage(dir, 'tests/app.test.mjs', "import { fix } from '../src/app.mjs';\n");
+  const ok = run('modules/gates/test-protect/check-test-protect.mjs', dir);
+  check('test-protect 纯测试提交 → exit 0', ok.status === 0, ok.stderr);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
 
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/src/init.mjs

@@ -6,7 +6,7 @@ import readline from 'node:readline';
 import { execSync, spawnSync } from 'node:child_process';
 import { renderTree, renderContent, sha256, scriptTrusted, listTree } from './render.mjs';
 import { HOSTS, STACKS, STACK_ALIASES, settingsJson, commitCheckConfig, pickStackVars, isOwned, srcTemplatePath, TEMPLATE_DRIFT_EXCLUDE } from './profiles.mjs';
-import { doctor } from './doctor.mjs';
+import { doctor, GATE_TRUST_DEFAULT } from './doctor.mjs';
 
 function fail(msg) {
   console.error(`❌ ${msg}`);
@@ -263,6 +263,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');
   }
@@ -327,6 +334,12 @@ export async function init(args, pkgRoot) {
     policyVersion: 2,
     // 新装默认只跑硬规则。缺省（旧台账无此字段）在 check-loop 里仍是全量，避免升级后卫生检查突然消失。
     audit: false,
+    // 门禁信任档（2026-10-12 gate-trust-level）：默认 'project' —— gate 安装锚失配只 WARN，
+    // 装户对门有最终所有权（1.7.11 起现状，此处只是把隐式默认显式命名）。多仓/组织场景改 'org'
+    // 即让失配升 FAIL（doctor exit 1），对齐 managed policy 的组织级强制。
+    // ⚠️ 默认值取 gateTrustOf / GATE_TRUST_DEFAULT 而非字面量：判据单源在 doctor.mjs（§6.6b 消费），
+    // 两处各写一份字符串即漂移面（N3 教训）。
+    gateTrust: GATE_TRUST_DEFAULT,
     createdAt: new Date().toISOString(),
     options: { hosts, stack: opt.stack, boardPort: String(opt.boardPort) },
     managed,

package/src/init.test.mjs

@@ -136,6 +136,25 @@ check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\
   fs.rmSync(tmp, { recursive: true, force: true });
 }
 
+// ---- ⑨ 引擎基线不下发（装户端内容清理后：包源径基线的键命名空间与装户盘面不一致，下发即污染）----
+{
+  const src = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-lock-src-'));
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-lock-tgt-'));
+  fs.mkdirSync(path.join(src, '_agents', 'scripts'), { recursive: true });
+  fs.writeFileSync(path.join(src, '_agents', 'scripts', 'gate.mjs'), '// 正常模板件\n');
+  fs.writeFileSync(path.join(src, '_agents', 'engine-lock.json'), '{"files":{}}\n');
+  const rels = listTree(src);
+  check('⑨listTree 排除 .agents/engine-lock.json（枚举面无基线）',
+    rels.includes('.agents/scripts/gate.mjs') && !rels.includes('.agents/engine-lock.json'),
+    JSON.stringify(rels));
+  const t = renderTree(src, tmp, {}, { force: true });
+  check('⑨renderTree 不落盘 .agents/engine-lock.json（written 无基线、目标不生成）',
+    !t.written.some((w) => w.rel === '.agents/engine-lock.json') && !fs.existsSync(path.join(tmp, '.agents', 'engine-lock.json')),
+    JSON.stringify(t.written.map((w) => w.rel)));
+  fs.rmSync(src, { recursive: true, force: true });
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node src/init.test.mjs');

package/src/instance-ref.test.mjs

@@ -0,0 +1,62 @@
+// instance-ref.test.mjs — 引擎/文档实例引用不变量门（2026-10-11 engine-output-provenance）。
+// 公理：引擎面向用户的输出是证据性的——引用的每个出处装户必须可解析（README「不伪造」柱）。
+// 此前 check-lane-surface.mjs 阻断消息与 check-loop.mjs WARN 引用包源仓专属的 specs/incidents/papercuts
+// 实例文档（装户随包只有 _TEMPLATE 与骨架，路径悬空）——本门把不变量机器化：
+//   包源随包下发件（引擎脚本 + 命令/角色/协议文档）不得引用「实例专属的带日期文档路径」。
+// 判据形态（宁可窄不可误伤）：
+//   /(incidents|specs|intents|plans)\/20\d{2}-/   带日期的实例文档路径（目录前缀引用合法——
+//                                                  new-task.md「立 incident（workflow/incidents/）」不受影响）
+//   /papercuts(\.md)?\s+20\d{2}/                  papercuts 条目按日期引用（papercuts-cleanup-batch
+//                                                  事件名不带空格+日期，不命中）
+// 例外：*.test.mjs 夹具里的合法日期文件名；board/（第三方 vendor）。出处一律写「包源仓 git 历史
+// 与 CHANGELOG」——立法时间点保留，可解析指针删除。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PATTERNS = [
+  { re: /(incidents|specs|intents|plans)\/20\d{2}-/g, why: '实例带日期文档路径' },
+  { re: /papercuts(\.md)?\s+20\d{2}/g, why: 'papercuts 条目日期引用' },
+];
+const EXTS = new Set(['.mjs', '.sh', '.cjs', '.md', '.txt', '.json']);
+const SKIP_DIR = new Set(['board', '.git', 'node_modules', 'cache']);
+
+function* walk(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) yield* walk(path.join(dir, e.name)); continue; }
+    if (!EXTS.has(path.extname(e.name))) continue;
+    if (e.name.endsWith('.test.mjs')) continue; // 夹具日期文件名合法
+    yield path.join(dir, e.name);
+  }
+}
+
+const targets = [
+  ...walk(path.join(ROOT, 'templates')),
+  ...fs.readdirSync(path.join(ROOT, 'src')).filter((f) => f.endsWith('.mjs') && !f.endsWith('.test.mjs')).map((f) => path.join(ROOT, 'src', f)),
+  ...fs.readdirSync(path.join(ROOT, 'bin')).filter((f) => f.endsWith('.mjs')).map((f) => path.join(ROOT, 'bin', f)),
+  ...fs.readdirSync(path.join(ROOT, 'scripts')).filter((f) => f.endsWith('.mjs')).map((f) => path.join(ROOT, 'scripts', f)),
+];
+
+const hits = [];
+let scanned = 0;
+for (const abs of targets) {
+  scanned++;
+  const lines = fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    for (const { re, why } of PATTERNS) {
+      re.lastIndex = 0;
+      if (re.test(lines[i])) hits.push(`${path.relative(ROOT, abs)}:${i + 1}（${why}）`);
+    }
+  }
+}
+
+if (hits.length) {
+  console.log(`FAIL 引擎/文档存在实例专属引用（装户径路径悬空）——${hits.length} 处：`);
+  for (const h of hits) console.log(`  - ${h}`);
+  console.log('修法：出处改写为「留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径」；用法示例用 <日期> 占位。');
+  process.exit(1);
+}
+console.log(`PASS 实例引用不变量：${scanned} 份随包源文件零实例专属日期引用`);
+console.log(`\n合计: PASS 1 / FAIL 0`);
+process.exit(0);

package/src/jscpd-drift.test.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// jscpd-drift.test.mjs — jscpd 漂移检查的纯函数 + 夹具回归（2026-10-12 jscpd-drift-gate）
+// 不真跑 jscpd、不联网：runJscpd 走真 worktree + npx，离线不可靠且慢；本套件只钉判据纯函数与
+// --no-run 端到端（基线可解析性）。真跑路径由 CI 的 workflow_dispatch 手动 job 覆盖。
+// 用法：node src/jscpd-drift.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'jscpd-drift.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
+};
+
+const mod = await import(pathToFileURL(SCRIPT).href);
+const { loadBaseline, parseReport, compareDrift, pickRef, DRIFT_WARN_PCT, DRIFT_FAIL_PCT } = mod;
+
+const tmp = (name, content) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `jscpd-drift-test-${name}-`));
+  const f = path.join(dir, 'baseline.json');
+  fs.writeFileSync(f, content, 'utf8');
+  return f;
+};
+const cleanup = (...fs_) => fs_.forEach((f) => fs.rmSync(path.dirname(f), { recursive: true, force: true }));
+
+// ---- 场景 1：真实基线可解析（消费端接的是本仓锚，不是夹具）----
+{
+  const r = loadBaseline();
+  check('场景 1：本仓基线可解析且六键齐', r.ok, r.error);
+  check('场景 1：基线含 commit 锚 + 复现命令 + 日期',
+    r.ok && !!r.baseline.commit && !!r.baseline.command && !!r.baseline.date,
+    r.ok ? JSON.stringify(r.baseline) : 'load 失败');
+  check('场景 1：默认阈值单调（0 < warn ≤ fail）',
+    DRIFT_WARN_PCT > 0 && DRIFT_FAIL_PCT >= DRIFT_WARN_PCT, `${DRIFT_WARN_PCT} / ${DRIFT_FAIL_PCT}`);
+  check('场景 1：基线重复率在合理区间（0 < pct ≤ 100）',
+    r.ok && r.baseline.totals.duplicatedLinesPct > 0 && r.baseline.totals.duplicatedLinesPct <= 100,
+    r.ok ? String(r.baseline.totals.duplicatedLinesPct) : '');
+}
+
+// ---- 场景 2：fail-loud —— 判据的输入坏了必须可见（红线：无判定依据不产噪声，但也绝不静默）----
+{
+  const missing = tmp('missing', '{}');
+  check('场景 2：totals 缺键 → fail-loud 且点名缺哪些键',
+    !loadBaseline(missing).ok && /缺键或非法/.test(loadBaseline(missing).error), loadBaseline(missing).error);
+  cleanup(missing);
+
+  const noCommit = tmp('nocommit', JSON.stringify({ totals: { sources: 1, lines: 2, clones: 1, duplicatedLines: 1, duplicatedLinesPct: 1, duplicatedTokensPct: 1 }, command: 'x' }));
+  check('场景 2：缺 commit 锚 → fail-loud（基线量的是哪一版无法对质）',
+    !loadBaseline(noCommit).ok && /commit/.test(loadBaseline(noCommit).error), loadBaseline(noCommit).error);
+  cleanup(noCommit);
+
+  const noCmd = tmp('nocmd', JSON.stringify({ totals: { sources: 1, lines: 2, clones: 1, duplicatedLines: 1, duplicatedLinesPct: 1, duplicatedTokensPct: 1 }, commit: 'abc1234' }));
+  check('场景 2：缺复现命令 → fail-loud（口径不可复现）',
+    !loadBaseline(noCmd).ok && /command/.test(loadBaseline(noCmd).error), loadBaseline(noCmd).error);
+  cleanup(noCmd);
+
+  const bad = tmp('bad', '{ not json');
+  check('场景 2：JSON 不可解析 → fail-loud', !loadBaseline(bad).ok && /解析失败/.test(loadBaseline(bad).error), loadBaseline(bad).error);
+  cleanup(bad);
+
+  const absent = path.join(os.tmpdir(), 'jscpd-drift-nonexistent-baseline.json');
+  check('场景 2：文件不存在 → fail-loud（不是「无数据即 OK」）', !loadBaseline(absent).ok, loadBaseline(absent).error);
+
+  const neg = tmp('neg', JSON.stringify({ totals: { sources: 1, lines: 2, clones: -1, duplicatedLines: 1, duplicatedLinesPct: 1, duplicatedTokensPct: 1 }, commit: 'a', command: 'b' }));
+  check('场景 2：负数值 → fail-loud', !loadBaseline(neg).ok, loadBaseline(neg).error);
+  cleanup(neg);
+}
+
+// ---- 场景 3：parseReport 跨版本字段探测 ----
+{
+  check('场景 3：小写字段路径命中', parseReport({ statistics: { total: { sources: 2, lines: 10, clones: 1, duplicatedLines: 3, duplicatedLinesPct: 30, duplicatedTokensPct: 20 } } })?.duplicatedLinesPct === 30);
+  check('场景 3：驼峰字段路径命中（jscpd Statistics/Total/DuplicatedLinesPct）',
+    parseReport({ Statistics: { Total: { Sources: 2, Lines: 10, Clones: 1, DuplicatedLines: 3, DuplicatedLinesPct: 30, DuplicatedTokensPct: 20 } } })?.duplicatedLinesPct === 30);
+  check('场景 3：jscpd 5.4.1 实测字段路径命中（statistics.total.percentage / percentageTokens）',
+    parseReport({ statistics: { total: { sources: 116, lines: 26228, clones: 231, duplicatedLines: 2029, percentage: 7.736, percentageTokens: 6.398 } } })?.duplicatedLinesPct === 7.736);
+  check('场景 3：5.x 与早期 duplicatedLinesPct 混用时逐路径取首个有限数',
+    parseReport({ statistics: { total: { duplicatedLinesPct: 7.49, percentage: 7.736 } } })?.duplicatedLinesPct === 7.736);
+  check('场景 3：结构不可识别 → null（不猜、不用 0 冒充）',
+    parseReport({ foo: 1 }) === null && parseReport(null) === null && parseReport({}) === null);
+  const partial = parseReport({ statistics: { total: { sources: 2 } } });
+  check('场景 3：部分键缺失 → 其余为 null（compareDrift 据此判 unknown）',
+    partial.duplicatedLinesPct === null && partial.sources === 2, JSON.stringify(partial));
+}
+
+// ---- 场景 4：compareDrift 四态 ----
+{
+  check('场景 4：持平（Δ0）→ ok', compareDrift(7.49, 7.49).level === 'ok');
+  check('场景 4：下降（Δ<0）→ ok 且不报抬升', compareDrift(7.49, 6.0).level === 'ok' && compareDrift(7.49, 6.0).deltaPct < 0);
+  const warn = compareDrift(7.49, 8.60);
+  check('场景 4：Δ+1.11pct → warn（越过 warn 阈值，未到 fail）',
+    warn.level === 'warn' && Math.abs(warn.deltaPct - 1.11) < 1e-9 && warn.lines.some((l) => /抬升（>\+1pct）/.test(l)), JSON.stringify(warn));
+  const high = compareDrift(7.49, 11.0);
+  check('场景 4：Δ+3.51pct → high 且提示立 intent 收敛（指回 incidents 克隆分叉采集点）',
+    high.level === 'high' && high.lines.some((l) => /立 intent 收敛/.test(l)) && high.lines.some((l) => /克隆分叉/.test(l)), JSON.stringify(high));
+  const unknown = compareDrift(7.49, null);
+  check('场景 4：实测取不到 → unknown（既不判 OK 也不判红——拿不到数据不是「没退化」的证据）',
+    unknown.level === 'unknown' && unknown.deltaPct === null, JSON.stringify(unknown));
+  const custom = compareDrift(10, 11, 0.5, 2.0);
+  check('场景 4：自定义阈值生效（Δ+1.0 在 0.5/2.0 档下仍为 warn）', custom.level === 'warn', JSON.stringify(custom));
+}
+
+// ---- 场景 4b：实测面选 commit（这条判据错则脚本退化为「自我复读」）----
+{
+  check('场景 4b：默认比对 HEAD 而非基线 commit（扫基线 commit 必得 Δ=0，等于没测）',
+    pickRef(false, '9e0cbc5') === 'HEAD', pickRef(false, '9e0cbc5'));
+  check('场景 4b：--verify-baseline 才复扫基线 commit（口径自查，与漂移判定分离）',
+    pickRef(true, '9e0cbc5') === '9e0cbc5', pickRef(true, '9e0cbc5'));
+}
+
+// ---- 场景 5：--no-run 端到端（真实基线；不出网、零 jscpd 依赖）----
+{
+  const r = spawnSync(process.execPath, [SCRIPT, '--no-run'], { cwd: ROOT, encoding: 'utf8' });
+  check('场景 5：--no-run → exit 0 且打印基线数值', r.status === 0 && /重复 7\.49%/.test(r.stdout), `exit=${r.status}\n${r.stdout}${r.stderr}`);
+  const j = spawnSync(process.execPath, [SCRIPT, '--no-run', '--json'], { cwd: ROOT, encoding: 'utf8' });
+  let parsed = null;
+  try { parsed = JSON.parse(j.stdout); } catch { /* 断言下方给出 */ }
+  check('场景 5：--no-run --json → 机器可读且 totals 齐',
+    j.status === 0 && parsed && parsed.ok === true && parsed.baseline && parsed.baseline.clones > 0, j.stdout);
+  check('场景 5：--json 输出含基线 commit 锚（可对质「量的是哪一版」）',
+    parsed && parsed.note && parsed.note.includes('基线 commit'), JSON.stringify(parsed));
+}
+
+// ---- 场景 6：阈值参数校验与未知参数 ----
+{
+  const bad = spawnSync(process.execPath, [SCRIPT, '--warn-pct', '5', '--fail-pct', '1', '--no-run'], { cwd: ROOT, encoding: 'utf8' });
+  check('场景 6：warn > fail → exit 1', bad.status === 1, `exit=${bad.status}\n${bad.stderr}`);
+  const nan = spawnSync(process.execPath, [SCRIPT, '--warn-pct', 'abc', '--no-run'], { cwd: ROOT, encoding: 'utf8' });
+  check('场景 6：非数值阈值 → exit 1', nan.status === 1, `exit=${nan.status}\n${nan.stderr}`);
+  const unknownArg = spawnSync(process.execPath, [SCRIPT, '--wat'], { cwd: ROOT, encoding: 'utf8' });
+  check('场景 6：未知参数 → exit 1 且给用法', unknownArg.status === 1 && /用法/.test(unknownArg.stderr), `exit=${unknownArg.status}\n${unknownArg.stderr}`);
+  const badBase = spawnSync(process.execPath, [SCRIPT, '--baseline', path.join(os.tmpdir(), 'no-such-baseline.json'), '--no-run'], { cwd: ROOT, encoding: 'utf8' });
+  check('场景 6：基线坏 → exit 1 且报错（不静默跳过）', badBase.status === 1 && /基线/.test(badBase.stderr), `exit=${badBase.status}\n${badBase.stderr}`);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+if (fail) { console.log('\n用法：node src/jscpd-drift.test.mjs'); process.exit(1); }
+process.exit(0);

package/src/profiles.mjs

@@ -113,6 +113,9 @@ export function isOwned(rel) {
   return rel === 'AGENTS.md' || rel === '.gitattributes' || rel.startsWith('workflow/') || rel.startsWith('wiki/')
     || rel.startsWith('.agents/notes/')
     || rel === '.agents/workflow-modules.txt' || rel === '.agents/rule-budgets.txt'
+    // level-hints.txt（2026-10-13 flow-kit-route）：风险级别**路径下限**清单，内容项目私有（照抄别人的
+    //   清单等于没登记），故归装户自持、sync 永不覆盖——与 lane-surfaces.txt 同款性质。
+    || rel === '.agents/level-hints.txt'
     || rel === '.agents/metric-claims.txt' || rel === '.agents/metric-derivers.cjs'
     || rel === '.agents/metric-derivers.mjs'
     || rel === '.agents/hooks/local-pre-commit'

package/src/render.mjs

@@ -43,6 +43,9 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false, protectSe
         continue;
       }
       const rel = relOf(abs, srcRoot);
+      // 引擎基线不是模板：键在 templates/_agents/…，下发成 .agents/engine-lock.json 会让装户
+      // 拿包源路径对账。排除该落点，包源基线留在模板目录。
+      if (rel === '.agents/engine-lock.json') continue;
       const target = path.join(targetRoot, rel);
       fs.mkdirSync(path.dirname(target), { recursive: true });
       if (fs.existsSync(target) && !force) {
@@ -58,7 +61,7 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false, protectSe
       if (raw.length < 512 * 1024 && !raw.includes(0)) {
         // 文本面 LF 归一（2026-09-27 closing-coverage）：模板盘面 CRLF（autocrlf 检出 / 编辑器写入）与
         // LF 克隆渲染出同一字节、同一 sha——fresh sha、装户落盘、kit.json 台账三方跨环境稳定；
-        // sync/doctor/source-sync-check 的读取侧归一（shaText）与本处写盘归一同口径闭合
+        // sync/doctor 的读取侧归一（shaText）与本处写盘归一同口径闭合
         const replaced = renderContent(raw.toString('utf8').replace(/\r\n/g, '\n'), vars);
         if (replaced.includes('{{')) {
           for (const m of replaced.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) {
@@ -118,6 +121,8 @@ export function listTree(srcRoot) {
         walk(abs);
         continue;
       }
+      // 引擎基线不下发（命名空间错配会致装户全员误报——同 renderTree 排除，见 check-engine-integrity.mjs）
+      if (relOf(abs, srcRoot) === '.agents/engine-lock.json') continue;
       out.push(relOf(abs, srcRoot).split(path.sep).join('/'));
     }
   })(srcRoot);