agentic-flow-kit 0.4.0 → 0.6.0

package/src/cli.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-// flow-kit CLI 入口：init（安装）/ sync（升级）/ add-host（补宿主）/ add-gate（装门禁）/ doctor（体检）/ help
+// flow-kit CLI 入口：init（安装）/ sync（升级）/ add-host（补宿主）/ add-gate（装门禁）/ doctor（体检）/ sync-hosts（跨宿主同步）/ help
 import { init } from './init.mjs';
 import { doctor } from './doctor.mjs';
 import { sync } from './sync.mjs';
+import { syncHosts } from './sync-hosts.mjs';
 import { addHost } from './add-host.mjs';
 import { addGate } from './add-gate.mjs';
 import { readFileSync } from 'node:fs';
@@ -21,7 +22,11 @@ export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚
                             owned 文件永不触碰）
   flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp（已存在文件跳过且不入台账，--force 接管）
   flow-kit add-gate <门禁>  装门禁模块并接线 local-pre-commit（当前：dotnet-ca；装后归项目所有）
-  flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / check-loop
+  flow-kit sync-hosts       跨宿主适配层同步：templates/_agents/{commands,roles}/*.md 权威源 vs
+                            modules/hosts/<h>/{agents,commands}/*.md 薄适配——默认 --diff 输出报告；
+                            --apply 单向同步（权威→薄适配，不反向避免污染）；
+                            改一处权威源要同步 N 份薄适配，人工 grep 易漏
+  flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / 跨宿主漂移 / check-loop
 
 init 选项（全部可选，均有默认值）：
   --stack <技术栈>     dotnet | node（ts/js） | python | go | none（默认 none；ts/js/typescript/javascript
@@ -35,6 +40,7 @@ init 选项（全部可选，均有默认值）：
   --force              覆盖已存在的同名文件（默认保守跳过）
 
 sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装内容）；add-gate 选项：--dir <目录>、--force。
+sync-hosts 选项：--diff（默认，仅报告，不修改）/ --apply（单向同步到薄适配）/ --json（机器可读输出）。
 
 示例：
   npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 确认安装
@@ -42,6 +48,8 @@ sync / add-host 选项：--dir <目录>、--force（覆盖本地已改 / 已装
   npx agentic-flow-kit sync                        # 包出新版后升级（本地改过的 managed 文件会跳过并报告）
   npx agentic-flow-kit add-host opencode           # 后补宿主
   npx agentic-flow-kit add-gate dotnet-ca          # 装 Clean Architecture 门禁
+  npx agentic-flow-kit sync-hosts --diff           # 看权威源 vs 薄适配漂移
+  npx agentic-flow-kit sync-hosts --apply          # 单向同步到薄适配
 
 装完即自包含：项目不依赖本包运行；AGENTS.md 生成「AI工作流 + Wiki」骨架，项目细节在「项目适配区」自填。`;
 
@@ -67,6 +75,11 @@ export function run(argv) {
     sync(argv.slice(1), PKG_ROOT);
     return;
   }
+  if (cmd === 'sync-hosts') {
+    const code = syncHosts(argv.slice(1), PKG_ROOT);
+    if (typeof code === 'number') process.exit(code);
+    return;
+  }
   if (cmd === 'add-host') {
     addHost(argv.slice(1), PKG_ROOT);
     return;

package/src/doctor.mjs

@@ -4,6 +4,11 @@ import path from 'node:path';
 import { execSync, spawnSync } from 'node:child_process';
 import net from 'node:net';
 import { createHash } from 'node:crypto';
+import { listTree, scriptTrusted } from './render.mjs';
+import { isOwned, HOSTS, pickStackVars } from './profiles.mjs';
+
+// 宿主目录映射（与 src/profiles.mjs#HOSTS 同源：装副本目录名前缀带点）
+const HOST_DIR = Object.fromEntries(Object.entries(HOSTS).map(([k, v]) => [k, v.dir]));
 
 function sh(cmd, cwd) {
   try {
@@ -50,8 +55,12 @@ export function doctor(args, pkgRoot) {
     '.agents/board/index.html',
     '.agents/hooks/commit-check.cjs',
     '.agents/workflow-modules.txt',
+    '.agents/workflow-enums.txt',
     '.agents/rule-budgets.txt',
     '.agents/settings.json',
+    '.agents/workflows/_TEMPLATE.md',
+    '.agents/scripts/check-loop.mjs',
+    '.agents/scripts/confirm-doc.mjs',
     '.githooks/pre-commit',
     '.githooks/pre-push',
     '.githooks/commit-msg',
@@ -72,7 +81,20 @@ export function doctor(args, pkgRoot) {
   const isRepo = sh('git rev-parse --git-dir', target).ok;
   if (isRepo) {
     const hp = sh('git config core.hooksPath', target);
-    if (hp.ok && hp.out.trim() === '.githooks') add('PASS', 'core.hooksPath=.githooks（钩子已挂载）');
+    if (hp.ok && hp.out.trim() === '.githooks') {
+      add('PASS', 'core.hooksPath=.githooks（钩子已挂载）');
+      // 执行位检查（init-p1-batch P1-1）：POSIX 上 git 对不可执行钩子静默跳过、全部门禁失效且原不可发现；
+      // win32 无执行位语义（mode 恒 0666 系），跳过本检查
+      if (process.platform !== 'win32') {
+        try {
+          const hookDir = path.join(target, '.githooks');
+          const noExec = fs.readdirSync(hookDir)
+            .filter((f) => fs.statSync(path.join(hookDir, f)).isFile())
+            .filter((f) => !(fs.statSync(path.join(hookDir, f)).mode & 0o111));
+          if (noExec.length) add('FAIL', `钩子缺执行位（POSIX 上 git 静默跳过不可执行钩子，门禁全部失效）：${noExec.join('、')}——执行 chmod +x .githooks/*`);
+        } catch { /* .githooks 目录缺失由 §2 布局检查覆盖 */ }
+      }
+    }
     else add('FAIL', `core.hooksPath 当前为「${(hp.ok ? hp.out : '').trim() || '未设置'}」——执行 git config core.hooksPath .githooks`);
   } else {
     add('WARN', '不在 git 仓库内——钩子未挂载（git init 后执行 git config core.hooksPath .githooks）');
@@ -91,7 +113,7 @@ export function doctor(args, pkgRoot) {
       for (const f of kit.managed || []) {
         const p = path.join(target, f.rel);
         if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
-        const h = createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+        const h = createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex'); // LF 归一（closing-coverage：跨 checkout 稳定，同 sync shaText 口径）
         if (h === f.sha256) ok++; else modified++;
       }
       add('PASS', `kit.json v${kit.version}：managed ${ok + modified} 份校验通过`);
@@ -102,6 +124,35 @@ export function doctor(args, pkgRoot) {
     }
   }
 
+  // 4.5 台账覆盖率（2026-09-26 managed-ledger-adopt）：§4 只遍历台账条目做双向校验，
+  //     从不反向问「盘上还有谁没登记」——15 份 managed 类文件曾因此长期游离台账外，sync 只报不修。
+  //     本项由 pkgRoot 包源枚举应有 managed 清单（排除 isOwned）与台账取差集，补上「盘上有、台账无」一侧。
+  //     首次引入用 WARN：doctor 的 pkgRoot 是包安装目录，装户可能落后于包版本（包内新增 managed 件
+  //     在装户 sync 前必然未登记），直接 FAIL 会让存量装户升级包后一跑 doctor 即挂。
+  //     沿用本仓库三次先例（doctor-owned-drift / workflows-check / adapter 薄适配漂移均先 WARN）。
+  {
+    const covRes = checkLedgerCoverage(target, pkgRoot);
+    if (covRes.skipped) {
+      add('PASS', `台账覆盖率检查跳过（${covRes.note || '无包源模板'}）`);
+    } else if (covRes.missing.length === 0) {
+      add('PASS', `台账覆盖率完整（${covRes.total} 份 managed 全在册）`);
+    } else {
+      const shown = covRes.missing.slice(0, 5).join('、');
+      add('WARN', `台账覆盖率缺口 ${covRes.missing.length} 份——盘上 managed 类文件未登记进 kit.json，包源改动不会同步到装副本；跑 node bin/flow-kit.mjs sync 收养（内容等于新版才登记）${covRes.missing.length > 5 ? `：${shown} …` : `：${shown}`}`);
+    }
+  }
+
+  // scriptGuard（init-p1-batch P1-3 供应链防线）：spawn 目标侧脚本前校验其与包源渲染值（LF 归一）一致——
+  // 失配说明预置/被改动，不可信：调用方记 WARN 跳过（fail-visible，不执行也不下通过结论）。
+  // 无 pkgRoot（理论路径）不设防；vars 从 kit.json options 重建（与 sync 同源构造）。
+  const scriptGuard = (rel) => {
+    if (!pkgRoot) return { ok: true, note: '' };
+    let opts = null;
+    try { opts = JSON.parse(fs.readFileSync(kitPath, 'utf8')).options; } catch { /* 无/坏台账→用默认 vars */ }
+    const vars = { BOARD_PORT: String(opts?.boardPort || '8933'), ...pickStackVars(opts?.stack) };
+    return scriptTrusted({ pkgRoot, target, rel, vars });
+  };
+
   // 5. 占位符残留
   const phFiles = ['AGENTS.md', 'workflow/README.md', '.agents/notes/runtime-env.md']
     .concat(fs.existsSync(path.join(target, '.agents/commands')) ? fs.readdirSync(path.join(target, '.agents/commands')).filter((f) => f.endsWith('.md')).map((f) => `.agents/commands/${f}`) : []);
@@ -116,25 +167,91 @@ export function doctor(args, pkgRoot) {
   else add('WARN', `占位符残留 ${phHits.length} 处（init 变量缺失或需手改）：${phHits.slice(0, 5).join('；')}${phHits.length > 5 ? ' …' : ''}`);
 
   // 6. workflow 索引漂移
-  const idx = spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs', '--check'], { cwd: target, encoding: 'utf8' });
-  if (idx.status === 0) add('PASS', 'workflow/INDEX.md 无漂移');
-  else add('WARN', `workflow/INDEX.md 漂移——跑 node .agents/scripts/gen-workflow-index.mjs 重生成`);
+  const idxGuard = scriptGuard('.agents/scripts/gen-workflow-index.mjs');
+  if (!idxGuard.ok) {
+    add('WARN', `workflow/INDEX.md 漂移检查跳过——${idxGuard.note}（供应链防线）`);
+  } else {
+    const idx = spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs', '--check'], { cwd: target, encoding: 'utf8' });
+    if (idx.status === 0) add('PASS', 'workflow/INDEX.md 无漂移');
+    else add('WARN', `workflow/INDEX.md 漂移——跑 node .agents/scripts/gen-workflow-index.mjs 重生成`);
+  }
 
   // 6.5 delegations 台账结构（量化层非门禁：结构漂移曾静默吞掉全部记录，2026-09-24）
+  // 存在性先行（复核 P2-2）：旧装户无此脚本 = 既有「静默跳过」语义，不产生防线 WARN 噪音
   if (fs.existsSync(path.join(target, '.agents/scripts/agg-delegations.cjs'))) {
-    const agg = spawnSync(process.execPath, ['.agents/scripts/agg-delegations.cjs'], { cwd: target, encoding: 'utf8' });
-    if (agg.status === 0) add('PASS', 'delegations 台账结构有效（agg 可解析）');
-    else add('WARN', `delegations 台账结构漂移——${String(agg.stderr || agg.stdout || '').split('\n')[0]}`);
+    const aggGuard = scriptGuard('.agents/scripts/agg-delegations.cjs');
+    if (!aggGuard.ok) {
+      add('WARN', `delegations 台账结构检查跳过——${aggGuard.note}（供应链防线）`);
+    } else {
+      const agg = spawnSync(process.execPath, ['.agents/scripts/agg-delegations.cjs'], { cwd: target, encoding: 'utf8' });
+      if (agg.status === 0) add('PASS', 'delegations 台账结构有效（agg 可解析）');
+      else add('WARN', `delegations 台账结构漂移——${String(agg.stderr || agg.stdout || '').split('\n')[0]}`);
+    }
+  }
+
+  // 6.6 owned 漂移校验（kit.owned 列表盘面 sha 不一致；engine 双源纪律对 owned 走「项目自持 + 哈希记账不约束」，
+  //     漂移信号靠本校验给装户可见性。2026-09-25 wf-runtime 复盘：包源改了装副本未同步 = 漂移但 sync 不报。）
+  const ownedRes = checkOwnedDrift(target);
+  if (ownedRes.error) {
+    add('WARN', `owned 校验跳过（kit.json 解析失败：${ownedRes.error}）`);
+  } else if (ownedRes.skipped) {
+    add('PASS', 'owned 校验跳过（kit.json 无 owned 条目）');
+  } else if (ownedRes.total === 0) {
+    add('PASS', 'owned 校验跳过（kit.json 无 owned 条目）');
+  } else if (ownedRes.drift === 0 && ownedRes.gone.length === 0) {
+    add('PASS', `owned ${ownedRes.total} 份无漂移（装副本与台账 sha 对齐）`);
+  } else {
+    // owned 漂移已严化为 FAIL（2026-09-25 doctor-owned-drift-strict 复盘；首次引入用 WARN，installed 装户吃过警告后升级）
+    if (ownedRes.drift) add('FAIL', `owned 漂移 ${ownedRes.drift} 份——装副本手改未跑 sync 刷台账 / 包源改了装副本未同步；须手动同步装副本后跑 node bin/flow-kit.mjs sync 刷台账（见 incidents/2026-09-25-wf-runtime 复盘）`);
+    if (ownedRes.gone.length) add('FAIL', `owned 文件缺失：${ownedRes.gone.join('、')}——sync 恢复或手动恢复`);
+  }
+
+  // 6.7 跨宿主薄适配正文段漂移校验（2026-09-25 cross-host-sync，参见 workflows/intents/2026-09-25-cross-host-sync.md）
+  //     装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（.zcode/.omp/.opencode/.trae）下的
+  //     {agents,commands}/*.md 是薄适配。按正文段 sha 比对（B-b 语义，frontmatter 不计入漂移），
+  //     trae commands 加 wf- 前缀映射。首次引入为 WARN（沿用 wf-runtime 复盘「先 WARN 升级 FAIL」路径），
+  //     待装户升级视反馈升级 FAIL。包源侧对应工具是 flow-kit sync-hosts（src/sync-hosts.mjs）。
+  const adapterRes = checkAdapterDrift(target);
+  if (adapterRes.skipped) {
+    add('PASS', `跨宿主薄适配校验跳过（${adapterRes.note || '权威源目录不存在'}）`);
+  } else if (adapterRes.drift === 0) {
+    add('PASS', `跨宿主薄适配 ${adapterRes.total} 对无正文漂移（装副本引擎 vs 4 宿主薄适配，B-b 语义）`);
+  } else {
+    add('WARN', `跨宿主薄适配正文漂移 ${adapterRes.drift} 对——权威源与薄适配正文段 sha 不一致；按 .agents/commands/sync-hosts.md 跑 flow-kit sync-hosts --apply 单向同步薄适配正文（frontmatter 不动）；装户可在 bin/flow-kit.mjs sync 时一并修复`);
+  }
+
+  // 6.8 workflows 编排脚本 lint（stages 表解析校验：role/step/after 引用、无环、三形态互斥、数值枚举；
+  //     2026-09-25 workflows-linter 把 _TEMPLATE.md「解析校验先行」从 prose 变机器门。首次引入 WARN
+  //     （沿用 wf-runtime 复盘「先 WARN 升级 FAIL」渐进路径），装户吃过警告后可升 FAIL。
+  //     旧版装户 sync 前 .agents/scripts/workflows-check.mjs 不存在 → 自然跳过不误报）
+  // 6.8 workflows 编排脚本 lint（stages 表解析校验：role/step/after 引用、无环、三形态互斥、数值枚举；
+  //     2026-09-25 workflows-linter 把 _TEMPLATE.md「解析校验先行」从 prose 变机器门。首次引入 WARN
+  //     （沿用 wf-runtime 复盘「先 WARN 升级 FAIL」渐进路径），装户吃过警告后可升 FAIL。
+  //     旧版装户 sync 前 .agents/scripts/workflows-check.mjs 不存在 → 既有「静默跳过」语义保留（存在性先行，
+  //     复核 P2-2），防线只拦「存在但与包源不符」）
+  const wfExists = fs.existsSync(path.join(target, '.agents/scripts/workflows-check.mjs')) && fs.existsSync(path.join(target, '.agents/workflows'));
+  const wfGuard = wfExists ? scriptGuard('.agents/scripts/workflows-check.mjs') : { ok: true, note: '' };
+  if (wfExists && !wfGuard.ok) {
+    add('WARN', `workflows 编排脚本 lint 跳过——${wfGuard.note}（供应链防线）`);
+  } else if (wfExists) {
+    const wf = spawnSync(process.execPath, ['.agents/scripts/workflows-check.mjs'], { cwd: target, encoding: 'utf8' });
+    if (wf.status === 0) {
+      const warnN = (String(wf.stdout || '').match(/- ⚠️ W\d/g) || []).length;
+      add('PASS', `workflows 编排脚本 lint 干净${warnN ? `（${warnN} 条 advisory 告警）` : ''}`);
+    } else {
+      const firstHit = String(wf.stdout || wf.stderr || '').split('\n').find((l) => / E\d/.test(l)) || `exit ${wf.status}`;
+      add('WARN', `workflows 编排脚本 lint 未过——${firstHit.trim()}；修 .agents/workflows/ 编排脚本（role/step/after 引用、三形态、retries）后重跑`);
+    }
   }
 
-  // 7. check-loop——先探 sh 可用性（对齐 run-tests.mjs 先例）：Windows PowerShell 常无 sh，
-  //    ENOENT 曾被吞进 hard-block 分支报成空原因假警报（incident 2026-09-24-doctor-sh-enoent）。
-  //    git 钩子门禁不受此影响——git 以自带 sh 执行钩子，与用户 PATH 无关。
-  const shProbe = spawnSync('sh', ['-c', 'true'], { encoding: 'utf8' });
-  if (shProbe.status !== 0) {
-    add('WARN', '环境无 sh——check-loop 未跑，勿当作通过；装 Git Bash / WSL 后重跑 doctor（git 钩子门禁不受影响，git 以自带 sh 执行）');
+  // 7. check-loop——2026-09-26 check-loop-node 起 node 实现直跑（sh 版曾需先探 sh 可用性：Windows
+  //    PowerShell 常无 sh，ENOENT 曾被吞进 hard-block 分支报成空原因假警报，incident 2026-09-24-doctor-sh-enoent；
+  //    迁移后无 sh 依赖，探针退役。check-loop.sh 为兼容 shim，pre-push 钩子路径照常）
+  const clGuard = scriptGuard('.agents/scripts/check-loop.mjs');
+  if (!clGuard.ok) {
+    add('WARN', `check-loop 跳过——${clGuard.note}（供应链防线：目标侧脚本与包源渲染值不符，不执行不下结论）`);
   } else {
-    const cl = spawnSync('sh', ['.agents/scripts/check-loop.sh'], { cwd: target, encoding: 'utf8' });
+    const cl = spawnSync(process.execPath, ['.agents/scripts/check-loop.mjs'], { cwd: target, encoding: 'utf8' });
     if (cl.status === 0) {
       const warnTxt = String(cl.stderr || '').trim();
       add('PASS', `check-loop 干净${warnTxt ? `（${warnTxt.split('\n').filter((l) => l.includes('WARN')).length} 条 advisory 警告）` : ''}`);
@@ -162,3 +279,116 @@ function print(results) {
   const warns = results.filter((r) => r.level === 'WARN').length;
   console.log(`\ndoctor：${results.length - fails - warns} PASS ｜ ${warns} WARN ｜ ${fails} FAIL`);
 }
+
+export function checkLedgerCoverage(target, pkgRoot) {
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) return { missing: [], total: 0, skipped: true, note: 'kit.json 不存在' };
+  let kit;
+  try {
+    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  } catch (e) {
+    return { missing: [], total: 0, skipped: true, note: `kit.json 解析失败：${e.message}` };
+  }
+  if (!Array.isArray(kit.managed)) return { missing: [], total: 0, skipped: true, note: 'kit.json 无 managed 条目' };
+  // 无包源 = 装户环境：盘上没有 templates/，无法枚举应有清单，跳过
+  const tmplRoot = path.join(pkgRoot || '', 'templates');
+  if (!pkgRoot || !fs.existsSync(tmplRoot)) return { missing: [], total: 0, skipped: true, note: '无包源模板（templates/ 不存在）' };
+
+  // 应有清单 = 模板树 + 台账宿主层，排除 owned（与 src/sync.mjs 的 fresh 计算口径一致）
+  const expected = new Set(listTree(tmplRoot));
+  const hosts = Array.isArray(kit.options?.hosts) ? kit.options.hosts : [];
+  for (const h of hosts) {
+    if (!HOST_DIR[h]) continue;
+    const hostRoot = path.join(pkgRoot, 'modules', 'hosts', h);
+    if (!fs.existsSync(hostRoot)) continue;
+    for (const rel of listTree(hostRoot)) expected.add(`${HOST_DIR[h]}/${rel}`);
+  }
+  const ledger = new Set(kit.managed.map((f) => f.rel));
+  const missing = [...expected].filter((rel) => !ledger.has(rel) && !isOwned(rel)).sort();
+  return { missing, total: ledger.size, skipped: false };
+}
+
+// owned 漂移校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-25 wf-runtime 复盘）
+// 返回：{ drift, gone, total, skipped, error? }
+//   - skipped=true：kit.json 不存在或解析失败/无 owned 字段
+//   - drift：盘面 sha != kit.owned sha 的文件数
+//   - gone：盘面缺失的文件 rel 列表
+//   - total：kit.owned 列表总文件数
+export function checkOwnedDrift(target) {
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) return { drift: 0, gone: [], total: 0, skipped: true };
+  let kit;
+  try {
+    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  } catch (e) {
+    return { drift: 0, gone: [], total: 0, skipped: true, error: e.message };
+  }
+  const owned = Array.isArray(kit.owned) ? kit.owned : [];
+  if (owned.length === 0) return { drift: 0, gone: [], total: 0, skipped: true };
+  let drift = 0;
+  const gone = [];
+  for (const f of owned) {
+    const p = path.join(target, f.rel);
+    if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
+    // sha 按 LF 归一口径（同 rule-budgets「索引/HEAD 字节」约定）：盘面 CRLF（autocrlf 检出）与克隆检出 LF
+    // 须同值，否则跨环境必漂移（CI 克隆 §6.6 必红——2026-09-27 gate-coverage 复核 P1-1 根因；owned 均为文本件）
+    const h = createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+    if (h !== f.sha256) drift++;
+  }
+  return { drift, gone, total: owned.length, skipped: false };
+}
+
+// 跨宿主薄适配正文段漂移校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-25 cross-host-sync）
+// 装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（zcode→.zcode、omp→.omp、
+// opencode→.opencode、trae→.trae）下 {agents,commands}/*.md 是薄适配。按正文段 sha 比对
+// （B-b 语义；frontmatter 不计入漂移）；trae commands 加 wf- 前缀映射。
+// 返回：{ drift, total, skipped, note? }
+//   - skipped=true：权威源目录不存在 / 包源环境 / 无 .md 文件
+//   - drift：权威源正文段与薄适配正文段 sha 不一致的对数
+//   - total：参与比对的对数（权威源文件 × 适配数）
+export function checkAdapterDrift(target) {
+  const authorityRoot = path.join(target, '.agents');
+  if (!fs.existsSync(authorityRoot)) return { drift: 0, total: 0, skipped: true, note: '.agents 目录不存在' };
+  // 包源环境检测：包源仓库同时含 templates/ 与 modules/，装户不应有；包源下跑 doctor §7.x 永远是
+  // drift（装副本是历史 init 渲染产物，不会随包源改动而重渲），无信息价值——直接 skip
+  if (fs.existsSync(path.join(target, 'templates', '_agents')) && fs.existsSync(path.join(target, 'modules', 'hosts'))) {
+    return { drift: 0, total: 0, skipped: true, note: '包源环境（templates/ + modules/ 同时存在）——§7.x 仅在装户环境有意义' };
+  }
+  // 4 宿主目录映射（与顶层 HOST_DIR 同源）
+  const splitFm = (text) => {
+    const m = String(text || '').match(/^---\r?\n([\s\S]*?\r?\n)---\r?\n?([\s\S]*)$/);
+    if (!m) return { fm: '', body: String(text || '') };
+    return { fm: `---\n${m[1]}---\n`, body: m[2] };
+  };
+  const bodySha = (p) => {
+    // 正文段 LF 归一后哈希（closing-coverage：与 sync-hosts bodySha 同口径，CRLF/LF 盘面不误报漂移）
+    try { return createHash('sha256').update(splitFm(fs.readFileSync(p, 'utf8')).body.replace(/\r\n/g, '\n'), 'utf8').digest('hex'); } catch { return null; }
+  };
+  let total = 0;
+  let drift = 0;
+  const listMd = (dir) => fs.existsSync(dir) && fs.statSync(dir).isDirectory() ? fs.readdirSync(dir).filter((f) => f.endsWith('.md')) : [];
+  for (const sub of ['commands', 'roles']) {
+    const subAbs = path.join(authorityRoot, sub);
+    for (const f of listMd(subAbs)) {
+      const authRel = `${sub}/${f}`;
+      const authSha = bodySha(path.join(authorityRoot, authRel));
+      const name = f.slice(0, -'.md'.length);
+      // 构建映射：commands/* → opencode/commands/<name>.md + trae/commands/wf-<name>.md；roles/* → 4 宿主 agents/<name>.md
+      const targets = [];
+      if (sub === 'commands') {
+        targets.push([HOST_DIR.opencode, 'commands', `${name}.md`], [HOST_DIR.trae, 'commands', `wf-${name}.md`]);
+      } else {
+        for (const h of Object.keys(HOST_DIR)) targets.push([HOST_DIR[h], 'agents', `${name}.md`]);
+      }
+      for (const [hostDir, subDir, fileName] of targets) {
+        const adapterAbs = path.join(target, hostDir, subDir, fileName);
+        const adapterSha = bodySha(adapterAbs);
+        if (adapterSha === null) continue; // 缺失不在 drift 统计（apply 不自动创建）
+        total++;
+        if (authSha !== adapterSha) drift++;
+      }
+    }
+  }
+  if (total === 0) return { drift: 0, total: 0, skipped: true, note: '权威源无 commands/roles .md 文件' };
+  return { drift, total, skipped: false };
+}

package/src/gate-dotnet-ca.test.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// gate-dotnet-ca.test.mjs — dotnet-ca 门禁模块判定回归（2026-09-27 host-gates-p1，incident 三件套「防复发验证」落点）
+// 方法：fixture 临时 git 仓构造 CONFIG 指向的最小目录树，复制包源 check-architecture.sh 并按场景改 CONFIG，
+//       spawn sh 跑门禁断言 exit 码与输出。三场景对位三个 P1：
+//       ①豁免清单多值生效（P1-B1：旧 tr ':' '|' 造 "A|B" BRE 字面量永不命中）
+//       ②CONTROLLERS_DIR 缺失 fail-closed（P1-B3：旧 2>/dev/null 静默放行）
+//       ③csproj 缺失 fail-closed（随 B3：旧 glob 展开失败静默放行）
+// 用法：node src/gate-dotnet-ca.test.mjs（npm test 随跑）
+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';
+
+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 PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GATE_SRC = path.join(PKG_ROOT, 'modules', 'gates', 'dotnet-ca', 'check-architecture.sh');
+
+// mkfixture：最小 dotnet 目录树（Application/API/Domain/Infrastructure/Controllers）+ 可覆盖 CONFIG
+function mkfixture(configOverride = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'gate-ca-test-'));
+  const dirs = {
+    APP_DIR: 'backend/src/App.Application',
+    API_DIR: 'backend/src/App.API',
+    DBCTX_FILE: 'backend/src/App.Infrastructure/Data/AppDbContext.cs',
+    DOMAIN_ENTITIES_DIR: 'backend/src/App.Domain/Entities',
+    CONTROLLERS_DIR: 'backend/src/App.API/Controllers',
+  };
+  for (const rel of Object.values(dirs)) fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true }); // 文件型键取父目录；目录型键随后显式建
+  fs.mkdirSync(path.join(root, dirs.APP_DIR), { recursive: true });
+  fs.mkdirSync(path.join(root, dirs.API_DIR), { recursive: true });
+  fs.mkdirSync(path.join(root, dirs.DOMAIN_ENTITIES_DIR), { recursive: true });
+  fs.mkdirSync(path.join(root, dirs.CONTROLLERS_DIR), { recursive: true });
+  fs.writeFileSync(path.join(root, dirs.DBCTX_FILE), 'class AppDbContext { }\n');
+  const cfg = {
+    ...Object.fromEntries(Object.entries(dirs).map(([k, v]) => [k, v])),
+    DBCTX_CLASS: 'AppDbContext',
+    INFRA_USING: 'using App.Infrastructure',
+    EXEMPT_CTRL: 'ExemptedA:ExemptedB',
+    SHARED_TYPES: '',
+    ...configOverride,
+  };
+  // 包源脚本 CONFIG 段替换：按「^KEY=" 任意到行尾」整行重写（值含 / 且行尾带注释——不用值内正则）；
+  // EXEMPT_CTRL/SHARED_TYPES 行尾有注释，重写时保留注释语义（测试值自带说明则省略）
+  let script = fs.readFileSync(GATE_SRC, 'utf8');
+  for (const [k, v] of Object.entries(cfg)) {
+    script = script.replace(new RegExp(`^${k}=.*$`, 'm'), `${k}="${v}"`);
+  }
+  const scriptPath = path.join(root, 'check-architecture.sh');
+  fs.writeFileSync(scriptPath, script);
+  // fixture 需为 git 仓（脚本首行 git rev-parse --show-toplevel）
+  spawnSync('git', ['init', '-q', '.'], { cwd: root });
+  return { root, scriptPath, dirs };
+}
+const runGate = (root, scriptPath) => spawnSync('sh', [scriptPath], { cwd: root, encoding: 'utf8' });
+// ctrlWrite：往 fixture 的 Controllers 目录写文件（目录可能尚未创建）
+const ctrlWrite = (root, dirs, name, content) => {
+  fs.mkdirSync(path.join(root, dirs.CONTROLLERS_DIR), { recursive: true });
+  fs.writeFileSync(path.join(root, dirs.CONTROLLERS_DIR, name), content);
+};
+// addCsproj：补干净 csproj（fail-closed 后红线 1 先查 csproj——不写则走不到目标断言）
+const addCsproj = (root, dirs) => fs.writeFileSync(path.join(root, dirs.APP_DIR, 'App.Application.csproj'), '<Project Sdk="Microsoft.NET.Sdk" />\n');
+
+// ---- ① 豁免清单多值（P1-B1）----
+{
+  const { root, scriptPath, dirs } = mkfixture();
+  addCsproj(root, dirs);
+  // API 层两处 DbContext 引用：一个在豁免 Controller 文件、一个在普通 Controller——豁免只应放过前者
+  ctrlWrite(root, dirs, 'ExemptedAController.cs', '// AppDbContext 直接引用（豁免）\n');
+  ctrlWrite(root, dirs, 'OrdersController.cs', '// AppDbContext 直接引用（应拦）\n');
+  const r = runGate(root, scriptPath);
+  check('①多值豁免生效：ExemptedA 文件行不出现、Orders 行出现（违例 exit 1）',
+    r.status === 1 && !r.stderr.includes('ExemptedAController') && r.stderr.includes('OrdersController'),
+    `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+// ①附：干净树（豁免命中全部 DbContext 引用）→ 红线 3 不拦（整体 exit 0 需其余红线干净）
+{
+  const { root, scriptPath, dirs } = mkfixture();
+  addCsproj(root, dirs);
+  ctrlWrite(root, dirs, 'ExemptedAController.cs', '// AppDbContext\n');
+  ctrlWrite(root, dirs, 'ExemptedBController.cs', '// AppDbContext\n');
+  const r = runGate(root, scriptPath);
+  check('①两个豁免 Controller 全命中 → 红线 3 零输出 exit 0', r.status === 0 && !r.stderr, `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- ② CONTROLLERS_DIR 缺失 fail-closed（P1-B3）----
+{
+  const { root, scriptPath, dirs } = mkfixture({ CONTROLLERS_DIR: 'backend/src/App.API/NotThere' });
+  addCsproj(root, dirs);
+  const r = runGate(root, scriptPath);
+  check('②Controllers 目录缺失 → fail-closed exit 1 点名目标（旧代码静默放行）',
+    r.status === 1 && r.stderr.includes('NotThere') && r.stderr.includes('fail-closed'),
+    `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- ③ csproj 缺失 fail-closed（随 B3）----
+{
+  const { root, scriptPath } = mkfixture();
+  // Application 目录存在但无 .csproj（glob 展开失败形态）
+  const r = runGate(root, scriptPath);
+  check('③Application 无 csproj → fail-closed exit 1（旧代码静默放行）',
+    r.status === 1 && r.stderr.includes('csproj') && r.stderr.includes('fail-closed'),
+    `exit=${r.status}\n${r.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+// ③附：有 csproj 且干净 → 过红线 1
+{
+  const { root, scriptPath, dirs } = mkfixture();
+  fs.writeFileSync(path.join(root, dirs.APP_DIR, 'App.Application.csproj'), '<Project Sdk="Microsoft.NET.Sdk" />\n');
+  const r = runGate(root, scriptPath);
+  check('③干净 csproj 存在 → 整体 exit 0', r.status === 0, `exit=${r.status}\n${r.stderr}`);  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);