agentic-flow-kit 1.7.0 → 1.7.16

package/src/rule-budget.test.mjs

@@ -0,0 +1,103 @@
+// rule-budget.test.mjs — 纯包源预算自检门（2026-10-11 budget-self-check）——关闭「纯包源仓不跑装户预算门」盲区。
+// 背景：常驻面预算单源 templates/_agents/rule-budgets.txt（装户命名空间），此前只在装户侧强制
+// （pre-commit --staged 硬拦 / check-loop 13 --all warning）；v1.7.1 起本仓纯包源（5ca9e8c 删装副本）、
+// 两处都不跑——bb69e19/418960a 重构净增 78B 把 .agents/commands/ 推到 65581B > 65536B，包源侧零暴露，
+// 装户首提被硬拦才发现（2026-10-11 S1 冒烟）。本套件把同一张预算表映射到包源路径核对，npm test / CI
+// 直接拦超限——模板增长不再静默入包。run-tests 盘面 glob 自动挂载本套件。
+// 口径（对照 templates/_agents/scripts/rule-budget.sh 单源，勿两处漂移）：
+//   字节 = LF 归一（工作树读入去 \r\n——等价 fsize 的 git cat-file 口径，core.autocrlf 检出形态无关）；
+//   目录合计 = 扁平 glob（直接子文件，不入子目录）；pat=首空格前 / lim=末空格后；lim 非纯数字行跳过；
+//   # 注释与空行跳过。
+// 与装户门的口径差异（诚实声明）：
+//   - AGENTS.md 是渲染模板：装户拿到的是占位符展开后的文件，渲染形态权威仍在装户门；本套件按全部
+//     STACKS 渲染取 max（BOARD_PORT 按最坏 5 位端口）做包源侧近似——单源复用 profiles/render，不复制命令表。
+//   - fail-loud 项（装户侧是 skip，包源侧是打包回归——表不随包或常驻面失踪 = 装户门整体变暗）：
+//     预算表缺失 / 解析 0 行 / 映射目标不存在 / 文件 glob 零命中。装户侧专属面（无包源对应）SKIP 并注记。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderContent } from './render.mjs';
+import { STACKS, pickStackVars } from './profiles.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BUDGETS = path.join(ROOT, 'templates', '_agents', 'rule-budgets.txt');
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+const lfBytes = (abs) => Buffer.byteLength(fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n'), 'utf8');
+
+// ---- 预算表（缺失即 fail-loud：装户门会整体变暗）----
+if (!fs.existsSync(BUDGETS)) {
+  console.log('FAIL R0 预算表缺失 templates/_agents/rule-budgets.txt——装户侧 pre-commit/检查13 将整体 skip');
+  process.exit(1);
+}
+const rows = [];
+for (const line of fs.readFileSync(BUDGETS, 'utf8').split('\n')) {
+  const t = line.replace(/\r/g, '');   // 表文件检出即 CRLF——显式去 \r（rule-budget.sh 同款）
+  if (!t || t.startsWith('#')) continue;
+  const i = t.indexOf(' ');
+  if (i < 0) continue;
+  const pat = t.slice(0, i);
+  const lim = t.slice(t.lastIndexOf(' ') + 1);
+  if (!/^\d+$/.test(lim)) continue;    // 非纯数字 lim 跳过（sh case 同款）
+  rows.push({ pat, lim: Number(lim) });
+}
+check('R1 预算表解析非空', rows.length > 0, `仅 ${rows.length} 行——表被清空即盲区复活`);
+
+// ---- 映射：装户命名空间 → 包源路径（新预算行若只属装户侧，在此登记映射或留 SKIP）----
+function mapToPkg(pat) {
+  if (pat === 'AGENTS.md') return 'templates/AGENTS.md';
+  if (pat.startsWith('.agents/')) return 'templates/_agents/' + pat.slice('.agents/'.length);
+  return null;
+}
+
+const REMEDY = '处置沿先例：压缩版本括号/措辞（71e0b0e、v1.7.10 三处），或在 rule-budgets.txt 注明理由调预算（512B 步进）';
+
+for (const { pat, lim } of rows) {
+  const rel = mapToPkg(pat);
+  if (!rel) { console.log(`SKIP ${pat}——装户侧专属面，无包源对应`); continue; }
+  const abs = path.join(ROOT, rel);
+  if (pat.endsWith('/')) {
+    // 目录合计：扁平直接子文件，不入子目录（sh `for f in "$pat"*` + [ -f ] 同款）
+    if (!fs.existsSync(abs)) { check(`R-dir ${pat} 目标存在`, false, `${rel} 缺失`); continue; }
+    const files = fs.readdirSync(abs, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => e.name);
+    const total = files.reduce((s, n) => s + lfBytes(path.join(abs, n)), 0);
+    check(`R-dir ${rel} 合计 ${total}B ≤ ${lim}B（${files.length} 文件）`, total <= lim, `超 ${total - lim}B。${REMEDY}`);
+  } else if (pat.includes('*')) {
+    // 文件 glob：仅支持 dir 内后缀形（*.md）——与 sh glob 展开同效
+    const dir = path.dirname(abs);
+    const base = path.basename(pat);
+    const suffix = base.slice(base.indexOf('*') + 1);
+    const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(suffix)) : [];
+    if (files.length === 0) { check(`R-glob ${pat} 有命中`, false, `${dir} 下无 *${suffix}——常驻面失踪或映射失效`); continue; }
+    const sizes = files.map((n) => ({ n, b: lfBytes(path.join(dir, n)) }));
+    const over = sizes.filter((s) => s.b > lim);
+    const maxS = sizes.slice().sort((a, b) => b.b - a.b)[0];
+    check(`R-glob ${path.dirname(rel)}/${base} ${sizes.length} 份，最大 ${maxS.n} ${maxS.b}B ≤ ${lim}B`, over.length === 0,
+      `${over.map((s) => `${s.n}=${s.b}B 超 ${s.b - lim}B`).join('；')}。${REMEDY}`);
+  } else {
+    if (!fs.existsSync(abs)) { check(`R-file ${pat} 目标存在`, false, `${rel} 缺失`); continue; }
+    const b = lfBytes(abs);
+    check(`R-file ${rel} = ${b}B ≤ ${lim}B`, b <= lim, `超 ${b - lim}B。${REMEDY}`);
+  }
+}
+
+// ---- AGENTS.md 渲染近似（装户渲染形态 = 占位符展开；包源侧按全部栈取 max）----
+const agentsRow = rows.find((r) => r.pat === 'AGENTS.md');
+if (agentsRow) {
+  const tpl = fs.readFileSync(path.join(ROOT, 'templates', 'AGENTS.md'), 'utf8');
+  let worst = { stack: '-', b: 0 };
+  for (const stack of Object.keys(STACKS)) {
+    const text = renderContent(tpl, { BOARD_PORT: '99999', ...pickStackVars(stack) });
+    const b = Buffer.byteLength(text.replace(/\r\n/g, '\n'), 'utf8');
+    if (b > worst.b) worst = { stack, b };
+  }
+  check(`R-render templates/AGENTS.md 渲染 max(${worst.stack}) ${worst.b}B ≤ ${agentsRow.lim}B`, worst.b <= agentsRow.lim,
+    `超 ${worst.b - agentsRow.lim}B——渲染形态超限装户门同样会拦，先压模板正文。${REMEDY}`);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/src/sync-hosts.mjs

@@ -26,8 +26,10 @@ function splitFm(text) {
 }
 
 // bodySha：剥离 frontmatter 后的正文段 sha256（缺失返 null）；正文 LF 归一（2026-09-27 closing-coverage：
-// CRLF/LF 盘面同值——权威源与薄适配行尾不一致不再误报漂移，与 doctor §6.7 同口径）
-function bodySha(p) {
+// CRLF/LF 盘面同值——权威源与薄适配行尾不一致不再误报漂移）。
+// 单源 export（2026-10-11 bodysha-single-source）：doctor §6.7 checkAdapterDrift 复用——此前 doctor
+// 内联第二份实现靠注释约束同口径，收敛为单源 import 消灭漂移面。
+export function bodySha(p) {
   try {
     const { body } = splitFm(fs.readFileSync(p, 'utf8'));
     return sha256(Buffer.from(body.replace(/\r\n/g, '\n'), 'utf8'));
@@ -45,10 +47,8 @@ function listMd(dir) {
 // pairsFor：权威源文件 → 薄适配 rel 列表（映射单源见 profiles.mjs#HOSTS.commandPrefix）
 //   commands 权威源 → 带 commandPrefix 的宿主各一份（<dir>/commands/<prefix><name>.md）
 //   roles    权威源 → 全部宿主 agents 各一份
-// hostDirOf：宿主 → 适配目录名。包源布局 = 宿主键（modules/hosts/opencode/…）；装户布局 = HOSTS[h].dir
-// （项目根下 .opencode/…，带点）——2026-10-07 sync-hosts-target-fix 加装户支持时引入。
-// hostFilter（2026-10-09 sync-hosts-root-coverage）：宿主级过滤（多根模式下「项目根宿主点」根只扫
-//   实际存在 dir 的宿主——不存在=没装该宿主点，不算缺失不算漂移）。
+// hostDirOf：宿主 → 适配目录名。包源调用传入 (h) => h，配对落在 modules/hosts/<宿主键>/。
+// hostFilter：宿主级过滤。调用方只扫实际存在的宿主目录时传入。
 function pairsFor(authRel, hostDirOf = (h) => h, hostFilter = null) {
   const out = [];
   const norm = authRel.split(path.sep).join('/');
@@ -72,12 +72,9 @@ function pairsFor(authRel, hostDirOf = (h) => h, hostFilter = null) {
 
 // diffHosts：权威源正文段 vs 薄适配正文段的漂移分析（B-b 语义；pure function）。
 // authorityRoot：权威源根（含 commands/ + roles/）
-// 多根对账（2026-10-09 sync-hosts-root-coverage）：adapterRoots = [{root, hostDirOf, hostFilter?, label?}]——
-//   包源布局传两根（modules/hosts 宿主键形态 + 项目根 HOSTS.dir 形态宿主点）；装户布局单根。
-//   向后兼容：旧单根入参 adaptersRoot/hostDirOf 归一为单元素数组。
-//   根因教训（engine-quality-round2 B1）：包源布局此前只扫 modules/hosts，项目根宿主点（本仓 .zcode/）
-//   完全不在扫描面——bb69e19「81 对全对齐」声明漏掉 .zcode 三份（独立复核 P2-3 实证）。
-// hostDirOf：宿主 → 适配目录名（默认宿主键 = 包源布局；装户布局传 (h) => HOSTS[h].dir）
+// adapterRoots = [{root, hostDirOf, hostFilter?, label?}]。只扫 modules/hosts。
+// 向后兼容：旧单根入参 adaptersRoot/hostDirOf 归一为单元素数组。
+// hostDirOf：宿主 → 适配目录名（默认宿主键）
 // 返回：{ drift, inSync, authorityMissing, adapterOrphans, faces }
 // drift 条目自带 root（applyForward 按它定位适配文件）；faces = 对账面自描述行（防不可解释的「N 对」）
 export function diffHosts(opts) {
@@ -194,55 +191,35 @@ function applyForward({ authorityRoot }, drift) {
 export function syncHosts(args, pkgRoot) {
   let apply = false;
   let json = false;
+  let strict = false;
   let dir = null;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--diff') apply = false;
     else if (a === '--apply') apply = true;
     else if (a === '--json') json = true;
+    else if (a === '--strict') strict = true;
     else if (a === '--dir') { dir = args[++i]; if (!dir) fail('--dir 缺少参数（目标项目根）'); }
     else fail(`未知选项：${a}（flow-kit sync-hosts --help）`);
   }
   if (!pkgRoot) fail('sync-hosts 缺少 pkgRoot（开发模式入口）');
 
-  // 目标根：--dir > cwd > pkgRoot（兜底）。
-  // 2026-10-07 sync-hosts-target-fix：此前恒用 pkgRoot——装户里跑 `flow-kit sync-hosts` 时 pkgRoot
-  // 解析为**包安装目录**，于是 doctor §7.x 报漂移、照提示跑 `--apply` 会去改包源仓（装户自己的适配层纹丝不动）。
+  // 目标根：--dir > cwd > pkgRoot。只认包源仓（templates/_agents + modules/hosts）。
+  // 装户仓的宿主文件由 init / add-host 写入，不在这里把 .agents 再当成第二份权威源。
   const target = path.resolve(dir || process.cwd() || pkgRoot);
-  // 布局判定（与 doctor.checkAdapterDrift 同口径）：
-  //   包源（templates/_agents 与 modules/hosts 同时存在）→ 权威源 = <target>/templates/_agents
-  //     薄适配根（2026-10-09 sync-hosts-root-coverage 多根）= ① modules/hosts（宿主键形态，全宿主）
-  //     + ② 项目根 HOSTS.dir 实际存在的宿主点（如本仓 .zcode/——此前不在扫描面，bb69e19「81 对全对齐」
-  //     漏掉其三份，独立复核 P2-3 实证）；不存在 = 没装该宿主点，不算缺失。
-  //   装户（其余）→ 权威源 = <target>/.agents，薄适配根 = <target>（宿主目录 .opencode/.trae/… 直接位于项目根）
-  const isSourceRepo = fs.existsSync(path.join(target, 'templates', '_agents'))
-    && fs.existsSync(path.join(target, 'modules', 'hosts'));
-  const authorityRoot = isSourceRepo ? path.join(target, 'templates', '_agents') : path.join(target, '.agents');
-  const adapterRoots = isSourceRepo
-    ? [
-        { root: path.join(target, 'modules', 'hosts'), hostDirOf: (h) => h, label: 'modules/hosts' },
-        {
-          root: target,
-          hostDirOf: (h) => (HOSTS[h] && HOSTS[h].dir) || h,
-          hostFilter: (h) => HOSTS[h] && fs.existsSync(path.join(target, HOSTS[h].dir)),
-          label: '项目根宿主点',
-        },
-      ]
-    : [{
-        root: target,
-        hostDirOf: (h) => (HOSTS[h] && HOSTS[h].dir) || h,
-        hostFilter: (h) => HOSTS[h] && fs.existsSync(path.join(target, HOSTS[h].dir)),
-        label: '项目根宿主点',
-      }];
-  if (!fs.existsSync(authorityRoot)) {
-    fail(`未找到权威源目录：${authorityRoot}——目标根 ${target} 既非包源（无 templates/_agents）也非装户（无 .agents）；用 --dir <项目根> 指定`);
+  const authorityRoot = path.join(target, 'templates', '_agents');
+  const hostsRoot = path.join(target, 'modules', 'hosts');
+  if (!fs.existsSync(authorityRoot) || !fs.existsSync(hostsRoot)) {
+    fail(`sync-hosts 只在包源仓运行（需要 templates/_agents 与 modules/hosts）。目标根 ${target} 不是包源仓。装户的宿主文件由 init / add-host 写入。`);
   }
-  const layout = isSourceRepo ? '包源' : '装户';
+  const adapterRoots = [
+    { root: hostsRoot, hostDirOf: (h) => h, label: 'modules/hosts' },
+  ];
   const result = diffHosts({ authorityRoot, adapterRoots });
 
   if (apply && result.drift.length > 0) {
     const { synced } = applyForward({ authorityRoot }, result.drift);
-    console.log(`▶ flow-kit sync-hosts --apply → ${target}（${layout}布局）`);
+    console.log(`▶ flow-kit sync-hosts --apply → ${target}（包源）`);
     console.log(`  对账面：${result.faces.join(' + ')}`);
     console.log(`  按权威源正文覆盖薄适配正文段 ${synced.length} 份（薄适配 frontmatter 不动）：`);
     for (const rel of synced) console.log(`    - ${rel}`);
@@ -254,8 +231,27 @@ export function syncHosts(args, pkgRoot) {
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
   } else {
-    console.log(`▶ flow-kit sync-hosts --diff → ${target}（${layout}布局）`);
+    console.log(`▶ flow-kit sync-hosts --diff → ${target}（包源）`);
     printDiff(result);
   }
+  // --strict（B4，2026-10-13）：漂移**报告器**变机器门。
+  // 背景：source-sync-check 删除后，跨宿主正文漂移只剩人工跑一次 --diff，CI 里无任何调用点——
+  //   而改权威源要同步 N 份薄适配，人工 grep 易漏（本次评审前 10 份薄适配就带着漂移）。
+  //   默认仍返回 0（保持「报告器」语义，人工跑不因漂移而失败）；CI 用 --strict 把漂移变成红。
+  // 口径：**只判「跑一次 --apply 就能归零」的两项**（正文漂移 + 权威源缺失）。
+  //   孤儿薄适配不判红——--apply 按设计不删它（可能是宿主特化/历史残留），
+  //   把它算红就是一条机器无法自愈的假红，按本仓「假阳性即噪声」纪律不能设成门（仍照常报告）。
+  if (strict) {
+    const fixable = result.drift.length + result.authorityMissing.length;
+    if (fixable > 0) {
+      console.error(`[跨宿主漂移 strict] 正文漂移 ${result.drift.length} · 权威源缺失 ${result.authorityMissing.length}`
+        + `${result.adapterOrphans.length ? `（另有孤儿薄适配 ${result.adapterOrphans.length} 份，按设计不判红）` : ''}`
+        + '——须先 flow-kit sync-hosts --apply 再提交');
+      return 1;
+    }
+    if (result.adapterOrphans.length) {
+      console.log(`  ℹ️ 孤儿薄适配 ${result.adapterOrphans.length} 份（--apply 按设计不删，故 strict 不判红；确为残留请手工删）`);
+    }
+  }
   return 0;
 }

package/src/sync-hosts.test.mjs

@@ -4,7 +4,7 @@
 // 判据：①全对齐 → inSync=28, drift 空 ②权威源改 → drift 列 ③apply → 正文一致，frontmatter 各自保留
 // ④薄适配 frontmatter 手改 → 不进 drift ⑤薄适配正文手改 → drift 列，apply 覆盖
 // ⑥薄适配缺失 → authorityMissing 列；apply 不自动创建
-// ⑦--json ⑧孤儿薄适配 ⑨装户布局（--dir / cwd 指向装户根 → 按 .agents ↔ 宿主目录比对）
+// ⑦--json ⑧孤儿薄适配 ⑨非包源根拒绝（不把 .agents 当权威源）
 // 用法：node src/sync-hosts.test.mjs
 import fs from 'node:fs';
 import path from 'node:path';
@@ -78,7 +78,18 @@ syncHosts(process.argv.slice(2), root);
   return spawnSync(process.execPath, [driver, '--dir', fixtureRoot, ...extra], { encoding: 'utf8', ...opts });
 }
 
-// 不传 --dir 形态：把 cwd 设为 fixture（验「默认当前目录」解析；装户布局靠 cwd 判定）
+// runSyncHostsExit：与 CLI 同口径**传播退出码**（cli.mjs 会 process.exit(syncHosts(...))）。
+//   上面的 runSyncHosts driver 丢弃返回值，故退出码恒 0——不能用来断言 --strict 判红（B4）。
+function runSyncHostsExit(fixtureRoot, extra = []) {
+  const driver = path.join(fixtureRoot, 'driver-exit.mjs');
+  W(driver, `import { syncHosts } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync-hosts.mjs')).href)};
+const code = syncHosts(process.argv.slice(2), ${JSON.stringify(fixtureRoot)});
+process.exit(typeof code === 'number' ? code : 0);
+`);
+  return spawnSync(process.execPath, [driver, '--dir', fixtureRoot, ...extra], { encoding: 'utf8' });
+}
+
+// 不传 --dir 形态：把 cwd 设为 fixture（验「默认当前目录」解析）
 function runSyncHostsByCwd(fixtureRoot, extra = []) {
   const driver = path.join(fixtureRoot, 'driver.mjs');
   W(driver, `import { syncHosts } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync-hosts.mjs')).href)};
@@ -192,39 +203,23 @@ syncHosts(process.argv.slice(2), root);
   check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')) && fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-legacy.md')));
 }
 
-// ============ 场景 9：装户布局（.agents 为权威源 + 宿主目录为薄适配，无 templates/modules）============
-// 2026-10-07 sync-hosts-target-fix：此前目标根恒为 pkgRoot（= 包安装目录），装户跑 sync-hosts
-// 会去改包源仓。本场景钉住「--dir / cwd 指向装户根 → 按装户布局比对」。
+// ============ 场景 9：非包源根拒绝（.agents 不再当权威源，宿主文件保持原样）============
 {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-inst-'));
  W(path.join(root, '.agents/commands/test.md'),
  `---\ndescription: Test 阶段\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
- W(path.join(root, '.opencode/commands/wf-test.md'),
- `---\ndescription: Test · opencode\n---\n\n# Test · v1\n\n旧正文 test v1\n`);
- W(path.join(root, '.trae/commands/wf-test.md'),
- `---\nname: wf-test\ndescription: Test · trae\n---\n\n# Test · v1\n\n旧正文 test v1\n`);
+ const hostBody = `---\ndescription: Test · opencode\n---\n\n# Test · v1\n\n旧正文 test v1\n`;
+ W(path.join(root, '.opencode/commands/wf-test.md'), hostBody);
 
- // 9a：--dir 指向装户根 → 布局判定「装户」，列出 2 处漂移
  const r1 = runSyncHosts(root, ['--diff']);
  const out1 = r1.stdout + r1.stderr;
- check('S9 装户布局：--dir 指向装户根 → 头部标「装户布局」', /装户布局/.test(out1), out1);
- check('S9 装户布局：列出 2 处正文漂移', /正文段漂移（2/.test(out1), out1);
- // 未装宿主（claude/cursor/codex）目录不存在 → 不算「缺失」（否则装户刷屏 + apply 恒 exit 1）
- check('S9 装户布局：未装宿主不进「权威源声明但薄适配缺失」', !/权威源声明但薄适配缺失/.test(out1), out1);
+ check('S9 非包源根 --diff：拒绝且点明只在包源仓运行', r1.status !== 0 && /只在包源仓运行/.test(out1), out1);
+ check('S9 非包源根 --diff：不改宿主文件', R(path.join(root, '.opencode/commands/wf-test.md')) === hostBody, out1);
 
- // 9b：不传 --dir（cwd = 装户根）→ 同样命中装户布局（旧行为会误指包源）
- const r2 = runSyncHostsByCwd(root, ['--diff']);
+ const r2 = runSyncHostsByCwd(root, ['--apply']);
  const out2 = r2.stdout + r2.stderr;
- check('S9 cwd 默认：装户布局解析正确（不再误指包源）', /装户布局/.test(out2) && !/包源布局/.test(out2), out2);
-
- // 9c：apply → 正文段对齐、薄适配 frontmatter 保留
- const r3 = runSyncHosts(root, ['--apply']);
- const out3 = r3.stdout + r3.stderr;
- const bodyOf = (p) => { const t = R(p); const m = t.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/); return t.slice(m ? m[0].length : 0); };
- check('S9 装户布局 apply：opencode 正文段对齐', bodyOf(path.join(root, '.opencode/commands/wf-test.md')) === bodyOf(path.join(root, '.agents/commands/test.md')), out3);
- check('S9 装户布局 apply：trae frontmatter 保留（name: wf-test）', /^---\nname: wf-test/m.test(R(path.join(root, '.trae/commands/wf-test.md'))), out3);
- // 未装宿主不计缺失 → apply 摘要「权威源缺失：0」且 exit 0
- check('S9 装户布局 apply：未装宿主不计缺失 → 权威源缺失 0 且 exit 0', /权威源缺失：0/.test(out3) && r3.status === 0, `status=${r3.status}\n${out3}`);
+ check('S9 cwd 为装户根 --apply：同样拒绝', r2.status !== 0 && /只在包源仓运行/.test(out2), out2);
+ check('S9 cwd 为装户根 --apply：宿主文件未被改写', R(path.join(root, '.opencode/commands/wf-test.md')) === hostBody, out2);
 }
 
 {
@@ -237,43 +232,59 @@ syncHosts(process.argv.slice(2), root);
   check('实仓薄适配无缺失无正文漂移', r.authorityMissing.length === 0 && r.drift.length === 0, `missing=${r.authorityMissing.length} drift=${r.drift.length} ${sample}`);
 }
 
-// ============ 场景 10-12：包源布局多根对账（2026-10-09 sync-hosts-root-coverage，B1）============
-// 根因教训（bb69e19「81 对全对齐」漏 .zcode 三份，独立复核 P2-3）：包源布局此前只扫 modules/hosts，
-// 项目根 HOSTS.dir 形态宿主点（本仓 .zcode/）不在扫描面。三场景钉住：漂移可检出 / apply 可修复且
-// frontmatter 保留 / 对账面自描述行在案。
+// ============ 场景 10：包源仓不扫描项目根宿主点（.zcode 等不是第二对账面）============
 {
-  // S10：包源 fixture + 项目根 .zcode/agents 漂移（正文旧 + frontmatter zcode 风格）→ --diff 报漂移
   const fx = mkFixture();
-  W(path.join(fx, '.zcode/agents/implementer.md'),
-    `---\nname: implementer\ndescription: zcode 本仓风格\n---\n\n# Implementer · v0\n\n旧版正文 implementer v0\n`);
+  const zcodeBody = `---\nname: implementer\ndescription: zcode 本仓风格\n---\n\n# Implementer · v0\n\n旧版正文 implementer v0\n`;
+  W(path.join(fx, '.zcode/agents/implementer.md'), zcodeBody);
   const r = runSyncHosts(fx, ['--diff']);
   const out = r.stdout + r.stderr;
-  check('S10 项目根宿主点漂移：--diff 报 .zcode/agents/implementer.md',
-    out.includes('.zcode/agents/implementer.md') && /正文段漂移/.test(out), out.slice(0, 600));
-  check('S10 对账面自描述：含「项目根宿主点（1 宿主）」', /对账面：.*项目根宿主点（1 宿主）/.test(out), out.split('\n').slice(0, 4).join('\n'));
-
-  // S11：--apply 修复项目根漂移——正文覆盖为权威源、frontmatter 保留、漂移归零
-  const r2 = runSyncHosts(fx, ['--apply']);
-  const out2 = r2.stdout + r2.stderr;
-  const synced = /- \.zcode\/agents\/implementer\.md/.test(out2);
-  const fixed = R(path.join(fx, '.zcode/agents/implementer.md'));
-  check('S11 --apply 同步清单含 .zcode 条目', synced, out2.slice(0, 500));
-  check('S11 --apply 正文覆盖 + frontmatter 保留',
-    fixed.includes('权威源正文 implementer v1') && fixed.includes('description: zcode 本仓风格'),
-    fixed.slice(0, 200));
-  check('S11 --apply 后漂移归零', /正文漂移：\s*0/.test(out2), out2.slice(-300));
+  check('S10 对账面只有 modules/hosts', /对账面：modules\/hosts/.test(out) && !/项目根宿主点/.test(out), out.split('\n').slice(0, 6).join('\n'));
+  check('S10 项目根 .zcode 漂移不入报告', !out.includes('.zcode/agents/implementer.md'), out.slice(0, 500));
+  runSyncHosts(fx, ['--apply']);
+  check('S10 --apply 不改写项目根 .zcode', R(path.join(fx, '.zcode/agents/implementer.md')) === zcodeBody);
 }
 
+// ============ 场景 11：--strict 把漂移报告器变成机器门（B4）============
+// 背景：source-sync-check 删除后，跨宿主正文漂移只剩人工跑一次 --diff，CI 里无任何调用点——
+//   而改权威源要同步 N 份薄适配，人工 grep 易漏（本仓评审前就带着 10 份漂移）。
+//   默认 --diff 仍恒 exit 0（人工跑不因漂移失败），--strict 才判红，供 CI 当门。
 {
-  // S12：装户布局 faces 自描述（回归钉住——装户单根 label=项目根宿主点，行为不变）
-  const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-adopter-'));
-  W(path.join(fx, '.agents/roles/implementer.md'),
-    `---\ndescription: Implementer 角色契约\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
-  W(path.join(fx, '.zcode/agents/implementer.md'),
-    `---\nname: implementer\ndescription: zcode\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
-  const r = runSyncHostsByCwd(fx, ['--diff']);
-  const out = r.stdout + r.stderr;
-  check('S12 装户布局：faces 单根自描述 + 对齐 1 对', /对账面：项目根宿主点（1 宿主）/.test(out) && /正文对齐：\s*1\s*对/.test(out), out.slice(0, 400));
+  const fx = mkFixture();
+  // 先 --apply 归零：夹具出厂状态未必干净（默认就可能带孤儿/缺失），
+  // 「--strict 在无漂移时 exit 0」这句话得先有个干净盘面才成立。
+  runSyncHosts(fx, ['--apply']);
+  const clean = runSyncHostsExit(fx, ['--diff', '--strict']);
+  check('S11 无漂移 + --strict → exit 0', clean.status === 0, `status=${clean.status} ${(clean.stdout + clean.stderr).slice(0, 300)}`);
+
+  // 制造一处薄适配正文漂移
+  const anyAdapter = fs.readdirSync(path.join(fx, 'modules/hosts'), { withFileTypes: true })
+    .filter((d) => d.isDirectory()).map((d) => d.name);
+  let broke = null;
+  for (const host of anyAdapter) {
+    const cmdDir = path.join(fx, 'modules/hosts', host, 'commands');
+    if (!fs.existsSync(cmdDir)) continue;
+    const f = fs.readdirSync(cmdDir).find((x) => x.endsWith('.md'));
+    if (!f) continue;
+    const abs = path.join(cmdDir, f);
+    fs.appendFileSync(abs, '\n手改一行，权威源没有这段。\n');
+    broke = `${host}/commands/${f}`;
+    break;
+  }
+  check('S11 夹具确实制造了漂移', !!broke, '未找到可改的薄适配');
+
+  const loose = runSyncHostsExit(fx, ['--diff']);
+  check('S11 有漂移但默认 --diff 仍 exit 0（报告器语义不变）', loose.status === 0, `status=${loose.status}`);
+  check('S11 默认 --diff 仍报告漂移', (loose.stdout + loose.stderr).includes('正文段漂移'), loose.stdout.slice(0, 300));
+
+  const strict = runSyncHostsExit(fx, ['--diff', '--strict']);
+  const sout = strict.stdout + strict.stderr;
+  check('S11 有漂移 + --strict → exit 1（CI 机器门）', strict.status === 1, `status=${strict.status}`);
+  check('S11 strict 报错点名修法（sync-hosts --apply）', sout.includes('--apply') && sout.includes('strict'), sout.slice(-300));
+
+  runSyncHosts(fx, ['--apply']);
+  const after = runSyncHostsExit(fx, ['--diff', '--strict']);
+  check('S11 --apply 归零后 --strict 回到 exit 0', after.status === 0, `status=${after.status}`);
 }
 
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);

package/src/trae-hooks.test.mjs

@@ -39,6 +39,17 @@ const runHook = (command, cwd) => {
   return { decision, reason, raw: r.stdout || '', status: r.status };
 };
 
+// 门禁在位桩（2026-10-09 装户端内容清理后）：纯包源仓无 .githooks/——hook 第二道关卡
+// （commit/push 前置 .githooks/*）在仓内必判「门禁未执行」。①/②/②附 的 token 边界断言
+// 需要「门禁通过」语境：造临时目录放通过型桩门禁当 cwd；③ 另用空目录保留「缺失 → 门禁未执行」deny。
+const GATE_FIXTURE = fs.mkdtempSync(path.join(os.tmpdir(), 'trae-hook-gates-'));
+fs.mkdirSync(path.join(GATE_FIXTURE, '.githooks'));
+for (const name of ['pre-commit', 'pre-push']) {
+  const stub = path.join(GATE_FIXTURE, '.githooks', name);
+  fs.writeFileSync(stub, '#!/usr/bin/env bash\nexit 0\n');
+  fs.chmodSync(stub, 0o755);
+}
+
 // ---- ① 强推 token 化（P1-B2）----
 {
   const cases = [
@@ -54,7 +65,7 @@ const runHook = (command, cwd) => {
     ['dotnet build --force', 'none', '非 push 命令带 --force 不误拦'],
   ];
   for (const [cmd, expect, label] of cases) {
-    const r = runHook(cmd);
+    const r = runHook(cmd, GATE_FIXTURE);
     check(`①${label}（${cmd}）→ ${expect === 'none' ? '放行' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -79,7 +90,7 @@ const runHook = (command, cwd) => {
     ['git commit -m "fix: 修复"', 'none'], // commit 走 .githooks 链（本仓有钩子且全绿）；deny 门本身不应拦 commit
   ];
   for (const [cmd, expect] of cases) {
-    const r = runHook(cmd, PKG_ROOT); // cwd=本仓：git commit 场景能找到 .githooks
+    const r = runHook(cmd, GATE_FIXTURE); // cwd=桩门禁目录：git commit 能通过第二道关卡，只测 deny/ask 门
     check(`②${cmd} → ${expect === 'none' ? '不因 deny/ask 门拦' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -94,7 +105,7 @@ const runHook = (command, cwd) => {
     ['git commit -m "真正要拦的消息"', 'none', '普通消息照常'],
   ];
   for (const [cmd, expect, label] of cases) {
-    const r = runHook(cmd, PKG_ROOT);
+    const r = runHook(cmd, GATE_FIXTURE);
     check(`②附 ${label} → ${expect === 'none' ? '不误拦' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -112,4 +123,5 @@ const runHook = (command, cwd) => {
 }
 
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+fs.rmSync(GATE_FIXTURE, { recursive: true, force: true });
 process.exit(fail ? 1 : 0);

package/src/validate.mjs

@@ -0,0 +1,72 @@
+// flow-kit validate：只读校验装户盘面（2026-10-10 validate-entry；对照 OpenSpec validate 形态：
+// 只读 + 0/1 退出码 + --strict/--json）。
+// 语义：用**包内置** check-loop 引擎（templates/_agents/scripts/check-loop.mjs 的 runCheckLoop，
+// isMain 主守卫保证 import 零副作用）对目标仓 workflow/ 闭环跑全部 20 项检查——不执行装户侧
+// .agents/scripts/*（供应链面：判定引擎随包版本走、目标侧零代码执行；doctor 走另一极：scriptGuard
+// 先验后跑装户侧脚本，两命令互补不重复）。root 经 runCheckLoop({root}) 传入，spawnGit 以 cwd:ROOT
+// 落在目标仓——tracked 过滤按目标仓 HEAD 算，与 git 钩子看到的提交面一致。
+// 只读范围：check-loop 自身仅有的两处落盘都在 .agents/cache/ 运行时缓存（gate-stats 需 --gate-stats
+// 才触发、added-dates 缓存 best-effort），且该目录已 gitignore——本命令不改任何文档与台账。
+// 不暴露 --rev：runCheckLoop 中 rev 与 root 互斥（提交时点判定属钩子链职责，validate 只看盘面现状）。
+// 输出契约：check-loop 的 HARD-BLOCK/WARN 两段式原样走 stderr（稳定输出契约，消费者 .githooks/pre-push）；
+// stdout 只承载本命令的汇总行 / --json——机器消费者按 stdout 解析，人按 stderr 读明细。
+// 退出码：blocker → 1；--strict 下 advisory warning 同样 → 1（判据单源 validateExit，纯函数可单测）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// 退出码判定单源（独立 export 供单元测试）：引擎 exitCode 非 0 → 1；--strict 时 warning 也红；
+// 结果缺失（引擎调用异常路径）fail-closed → 1。
+export function validateExit(result, strict) {
+  if (!result || result.exitCode !== 0) return 1;
+  if (strict && (result.warnings || []).length > 0) return 1;
+  return 0;
+}
+
+export async function validate(args, pkgRoot) {
+  let target = process.cwd();
+  let strict = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') target = path.resolve(args[++i]);
+    else if (args[i] === '--strict') strict = true;
+    else if (args[i] === '--json') json = true;
+    else {
+      console.error(`validate: 未知参数 ${args[i]}——用法 flow-kit validate [--strict] [--json] [--dir <目录>]`);
+      process.exit(1);
+    }
+  }
+
+  // 装户盘面前置：枚举单源（workflow-enums.txt 等）都在 .agents/ 下，无装副本则引擎无从判定——
+  // 先给指引再红，不产出「20 项全断档」的噪音墙
+  if (!fs.existsSync(path.join(target, '.agents'))) {
+    const msg = `缺 .agents/——validate 校验 flow-kit 装户盘面，先跑 npx agentic-flow-kit init`;
+    if (json) console.log(JSON.stringify({ target, strict, checkLoopExitCode: null, exitCode: 1, blockers: [msg], warnings: [] }, null, 2));
+    else console.error(`❌ validate: ${target} ${msg}`);
+    process.exit(1);
+  }
+
+  // 动态 import 包内置引擎：pkgRoot = npx 缓存 / 全局安装 / 仓内直跑三种形态下都指向包源模板
+  const engineUrl = pathToFileURL(path.join(pkgRoot, 'templates', '_agents', 'scripts', 'check-loop.mjs')).href;
+  const { runCheckLoop } = await import(engineUrl);
+  const result = runCheckLoop({ root: target });
+  const code = validateExit(result, strict);
+
+  if (json) {
+    console.log(JSON.stringify({
+      target,
+      strict,
+      checkLoopExitCode: result.exitCode,
+      exitCode: code,
+      blockers: result.blockers,
+      warnings: result.warnings,
+    }, null, 2));
+  } else {
+    const n = (result.blockers || []).length;
+    const w = (result.warnings || []).length;
+    if (code === 0) console.log(`✅ flow-kit validate 通过——blocker 0 / warning ${w}${w ? '（advisory 不阻断；--strict 可把 warning 判红）' : ''}`);
+    else if (result.exitCode !== 0) console.log(`❌ flow-kit validate 未通过——blocker ${n} / warning ${w}（明细见上方 HARD-BLOCK / WARN 输出）`);
+    else console.log(`❌ flow-kit validate（--strict）未通过——warning ${w} 条判红（默认退出码 0，advisory 不阻断）`);
+  }
+  process.exit(code);
+}

package/src/validate.test.mjs

@@ -0,0 +1,95 @@
+// validate.test.mjs — flow-kit validate 断言（2026-10-10 validate-entry）。
+// 两层：validateExit 纯函数直测（退出码判据单源）+ 端到端 spawn 真 CLI（bin/flow-kit.mjs validate，
+// --json 断言 stdout 可解析、退出码契约、缺 .agents/ 指引、未知参数用法错）。
+// fixture 沿 check-loop.test.mjs 同款：临时根（workflow 四目录 + .agents/ + 枚举单源内联 8 键），
+// 自包含、不依赖真实 git 与 workflow 文档。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { validateExit } from './validate.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = path.join(ROOT, 'bin', 'flow-kit.mjs');
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+
+// ---- validateExit 纯函数（判据单源）----
+check('V1 blocker → 1', validateExit({ exitCode: 1, blockers: ['x'], warnings: [] }, false) === 1);
+check('V2 干净 → 0', validateExit({ exitCode: 0, blockers: [], warnings: [] }, false) === 0);
+check('V3 warning 非 strict → 0', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, false) === 0);
+check('V4 warning + strict → 1', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, true) === 1);
+check('V5 引擎结果缺失 fail-closed → 1', validateExit(null, false) === 1 && validateExit(undefined, true) === 1);
+
+// ---- fixture（枚举单源内联，同 check-loop.test.mjs#ENUMS_FIXTURE）----
+const ENUMS_FIXTURE = [
+  'doc.status.all=draft approved done superseded cancelled',
+  'doc.status.confirmed=approved done superseded cancelled',
+  'doc.status.active=draft approved',
+  'doc.status.terminal=done superseded cancelled',
+  'doc.status.abandoned=superseded cancelled',
+  'incident.status.all=open fixed closed',
+  'incident.status.active=open',
+  'level.all=L0 L1 L2 L3',
+].join('\n') + '\n';
+
+const mkfix = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-'));
+  for (const s of ['intents', 'specs', 'plans', 'incidents']) {
+    fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  }
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'), ENUMS_FIXTURE);
+  return d;
+};
+
+const runValidate = (dir, args = []) => spawnSync(process.execPath, [CLI, 'validate', '--dir', dir, ...args], {
+  cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+});
+const stdoutOf = (r) => r.stdout || '';
+const stderrOf = (r) => r.stderr || '';
+
+// ---- 端到端：绿盘面（空四目录 + 枚举单源）----
+const green = mkfix();
+const rg = runValidate(green, ['--json']);
+let greenJson = null;
+try { greenJson = JSON.parse(stdoutOf(rg)); } catch { /* 解析失败在断言里报 */ }
+check('V6 绿盘面 exit 0', rg.status === 0, `exit=${rg.status}\n${stdoutOf(rg)}\n${stderrOf(rg).slice(0, 300)}`);
+check('V7 --json stdout 可解析且 blockers 空', !!greenJson && Array.isArray(greenJson.blockers) && greenJson.blockers.length === 0, stdoutOf(rg).slice(0, 300));
+check('V8 --json 契约字段在位', !!greenJson && greenJson.exitCode === 0 && greenJson.checkLoopExitCode === 0 && greenJson.strict === false && typeof greenJson.target === 'string', JSON.stringify(greenJson));
+// --strict 契约端到端：同一盘面 fixture 恒产出 advisory warning（装副本骨架件缺失类，绿判不受其扰），
+// 非 strict 绿（V6 已证）、strict 判红且 checkLoopExitCode 保持 0——判红来源是 strict 规则而非引擎
+const rs = runValidate(green, ['--json', '--strict']);
+let strictJson = null;
+try { strictJson = JSON.parse(stdoutOf(rs)); } catch { /* 同上 */ }
+check('V9 --strict 把 advisory warning 判红（checkLoopExitCode 仍 0）',
+  rs.status === 1 && !!strictJson && strictJson.exitCode === 1 && strictJson.checkLoopExitCode === 0 && strictJson.strict === true && strictJson.warnings.length > 0,
+  `exit=${rs.status}\n${stdoutOf(rs).slice(0, 300)}`);
+
+// ---- 端到端：红盘面（同名配对断档：intent 无同名 spec/plan → 检查 1 hard-block）----
+const red = mkfix();
+fs.writeFileSync(path.join(red, 'workflow', 'intents', '2026-01-01-solo.md'),
+  '---\nstatus: draft\nlevel: L1\n---\n# INTENT — solo\n');
+const rr = runValidate(red, ['--json']);
+let redJson = null;
+try { redJson = JSON.parse(stdoutOf(rr)); } catch { /* 同上 */ }
+check('V10 配对断档 exit 1', rr.status === 1, `exit=${rr.status}\n${stdoutOf(rr).slice(0, 300)}\n${stderrOf(rr).slice(0, 500)}`);
+check('V11 --json blockers 非空且明细走 stdout JSON', !!redJson && redJson.blockers.length > 0, stdoutOf(rr).slice(0, 300));
+
+// ---- 指引与用法错 ----
+const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-bare-'));
+const rb = runValidate(bare);
+check('V12 缺 .agents/ → exit 1 且给 init 指引', rb.status === 1 && /init/.test(stderrOf(rb)), `exit=${rb.status}\n${stderrOf(rb).slice(0, 300)}`);
+const ru = runValidate(green, ['--bogus']);
+check('V13 未知参数 → exit 1 用法行', ru.status === 1 && /用法/.test(stderrOf(ru)), `exit=${ru.status}\n${stderrOf(ru).slice(0, 300)}`);
+
+// ---- 清理 ----
+for (const d of [green, red, bare]) fs.rmSync(d, { recursive: true, force: true });
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);