agentic-flow-kit 1.8.2 → 2.0.0

package/src/doctor.mjs

@@ -1,629 +0,0 @@
-// flow-kit doctor：安装体检——布局 / git 钩子 / managed 台账 / 占位符残留 / 索引漂移 / check-loop
-import fs from 'node:fs';
-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, srcTemplatePath, templateDriftOf, TEMPLATE_DRIFT_EXCLUDE } from './profiles.mjs';
-import { bodySha } from './sync-hosts.mjs';
-// 委派台账分片感知读（2026-10-13 ledger-shard-ledgers 回灌）：快照新鲜度判读的台账文本
-// = 主台账 ∪ delegations.d/*.md，读侧单源复用随包模板模块（§6.5 数据行迁入分片后仍可判陈旧）。
-import { readLedgerText } from '../templates/_agents/scripts/ledger-shards.mjs';
-
-// 宿主目录映射（与 src/profiles.mjs#HOSTS 同源：装副本目录名前缀带点）
-const HOST_DIR = Object.fromEntries(Object.entries(HOSTS).map(([k, v]) => [k, v.dir]));
-// 命令层薄适配宿主：[装副本目录名, 文件名前缀]（单源 profiles.mjs#HOSTS.commandPrefix；与 sync-hosts pairsFor 同口径）
-const HOST_CMD_DIR = Object.entries(HOSTS).filter(([, v]) => v.commandPrefix).map(([, v]) => [v.dir, v.commandPrefix]);
-
-function sh(cmd, cwd) {
-  try {
-    return { ok: true, out: execSync(cmd, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }) };
-  } catch (e) {
-    return { ok: false, out: String((e.stdout || '') + (e.stderr || '')) };
-  }
-}
-
-function portInUse(port) {
-  return new Promise((resolve) => {
-    const s = net.connect({ port: Number(port), host: '127.0.0.1', timeout: 400 });
-    s.on('connect', () => { s.destroy(); resolve(true); });
-    s.on('error', () => resolve(false));
-    s.on('timeout', () => { s.destroy(); resolve(false); });
-  });
-}
-
-export function doctor(args, pkgRoot) {
-  let target = process.cwd();
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i]);
-  }
-  const results = []; // {level:'PASS'|'WARN'|'FAIL', msg}
-  const add = (level, msg) => results.push({ level, msg });
-
-  // 1. Node 版本
-  const major = Number(process.versions.node.split('.')[0]);
-  if (major >= 18) add('PASS', `Node ${process.versions.node}（≥18）`);
-  else add('FAIL', `Node ${process.versions.node} 过低（引擎脚本需 ≥18）`);
-
-  // 2. 目录布局
-  const required = [
-    'AGENTS.md',
-    '.agents/commands/new-task.md',
-    '.agents/roles/implementer.md',
-    '.agents/roles/independent-reviewer.md',
-    '.agents/roles/ui-verifier.md',
-    '.agents/scripts/check-loop.sh',
-    '.agents/scripts/kb-search.mjs',
-    '.agents/scripts/gen-workflow-index.mjs',
-    '.agents/scripts/gen-wiki-board.mjs',
-    '.agents/scripts/workflow-board-server.mjs',
-    '.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',
-    '.githooks/post-commit',
-    '.githooks/pre-merge-commit',
-    'workflow/README.md',
-    'workflow/intents/_TEMPLATE.md',
-    'workflow/specs/_TEMPLATE.md',
-    'workflow/plans/_TEMPLATE.md',
-    'workflow/incidents/_TEMPLATE.md',
-    'wiki/INDEX.md',
-  ];
-  const missing = required.filter((p) => !fs.existsSync(path.join(target, p)));
-  if (missing.length === 0) add('PASS', `目录布局完整（${required.length} 个关键路径）`);
-  else add('FAIL', `布局缺失：${missing.join('、')}`);
-
-  // 3. git 仓库与钩子
-  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（钩子已挂载）');
-      // 执行位检查（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）');
-  }
-
-  // 4. kit.json managed 台账（sha 校验：本地改动 → WARN，缺失 → FAIL）
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) {
-    add('WARN', '无 .agents/kit.json（非 flow-kit 安装或旧版手动安装）');
-  } else {
-    try {
-      const kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-      let ok = 0;
-      let modified = 0;
-      const gone = [];
-      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, '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} 份校验通过`);
-      if (modified) add('WARN', `managed 本地改动 ${modified} 份（升级时 flow-kit sync 会要求合并）`);
-      if (gone.length) add('FAIL', `managed 文件缺失：${gone.join('、')}`);
-    } catch (e) {
-      add('FAIL', `kit.json 解析失败：${e.message}`);
-    }
-  }
-
-  // 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}`) : []);
-  const phHits = [];
-  for (const rel of phFiles) {
-    const p = path.join(target, rel);
-    if (!fs.existsSync(p)) continue;
-    const txt = fs.readFileSync(p, 'utf8');
-    for (const m of txt.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) phHits.push(`${rel}: {{${m[1]}}}`);
-  }
-  if (phHits.length === 0) add('PASS', '无占位符残留');
-  else add('WARN', `占位符残留 ${phHits.length} 处（init 变量缺失或需手改）：${phHits.slice(0, 5).join('；')}${phHits.length > 5 ? ' …' : ''}`);
-
-  // 6. workflow 索引漂移
-  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 重生成`);
-  }
-
-  // 6b. wiki 索引漂移（2026-10-10：镜像 §6 workflow 侧——wiki INDEX 计数/映射表/看板 DATA 原本无任何
-  //     机器校验，装户手改生成区或忘跑 gen-wiki-board 只有肉眼能发现；workflow 侧有 doctor + check-loop 11
-  //     双路，wiki 侧此前是单路都没有）。存在性先行：旧装户无此脚本 = 既有「静默跳过」语义（同 §6.5 口径）
-  if (fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
-    const wikiGuard = scriptGuard('.agents/scripts/gen-wiki-board.mjs');
-    if (!wikiGuard.ok) {
-      add('WARN', `wiki/INDEX.md 漂移检查跳过——${wikiGuard.note}（供应链防线）`);
-    } else {
-      const wb = spawnSync(process.execPath, ['.agents/scripts/gen-wiki-board.mjs', '--check'], { cwd: target, encoding: 'utf8' });
-      if (wb.status === 0) add('PASS', 'wiki/INDEX.md 与看板无漂移');
-      else add('WARN', `wiki/INDEX.md 或看板漂移——跑 node .agents/scripts/gen-wiki-board.mjs 重生成`);
-    }
-  }
-
-  // 6.5 delegations 台账结构（量化层非门禁：结构漂移曾静默吞掉全部记录，2026-09-24）
-  // 存在性先行（复核 P2-2）：旧装户无此脚本 = 既有「静默跳过」语义，不产生防线 WARN 噪音
-  if (fs.existsSync(path.join(target, '.agents/scripts/agg-delegations.cjs'))) {
-    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.5b delegations 月度聚合快照新鲜度（p0-gate-noise-batch：回写无门致快照 3 周未更新）
-  const snapFresh = checkDelegationSnapshotFreshness(target);
-  if (snapFresh.skipped) {
-    add('PASS', `delegations 快照新鲜度检查跳过（${snapFresh.note}）`);
-  } else if (snapFresh.stale) {
-    add('WARN', `delegations 月度快照陈旧（台账至 ${snapFresh.ledgerMonth}，快照至 ${snapFresh.snapshotMonth || '缺失'}）——跑 agg-delegations.cjs 更新 §月度聚合快照`);
-  } else {
-    add('PASS', `delegations 月度快照最新（${snapFresh.snapshotMonth}）`);
-  }
-
-  // 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 刷台账 / 包源改了装副本未同步；须手动同步装副本后跑 npx agentic-flow-kit sync 刷台账`);
-    if (ownedRes.gone.length) add('FAIL', `owned 文件缺失：${ownedRes.gone.join('、')}——sync 恢复或手动恢复`);
-  }
-
-  // 6.6b gate 安装锚校验（2026-10-11 P3-1 gate 防改锚）：add-gate 给逐字拷贝安装的 gate 脚本写
-  //      srcSha256＝安装时刻包源 sha（见 src/add-gate.mjs 头注）；sync 只按包源刷新模板条目锚，gate 条目
-  //      解析不到包源模板（srcTemplatePath→null 提前 return）故锚恒定 → 盘面 sha ≠ 锚即「装后手改」。
-  //      设计依据：2026-10-10 调研结论「gate 装户可改、hard 项缺防改」——sync 对 owned 的 sha256 按盘面
-  //      自愈使手改不留痕，本项补上可见性。不阻断（沿用「先 WARN 升级 FAIL」渐进路径）：装户对门有最终
-  //      所有权，锚只提供可见性，有意改动知悉即可。
-  const gateRes = checkGateAnchors(target);
-  // 出账分级按信任档（2026-10-12 gate-trust-level）：project 档 = WARN 永久可见（装户对门有最终
-  // 所有权）；org 档 = FAIL（doctor exit 1，组织级强制位）。两种档位的**文案主干逐字相同**——
-  // 升档只改级别与追加一句「本仓已声明 org 档」，不改判据、不改修复指引（作者照同一套指引修即可）。
-  const orgMode = gateRes.trust === 'org';
-  const trustNote = orgMode ? '【本仓 kit.json gateTrust=org：组织级强制档，失配属 FAIL】' : '【本仓 kit.json gateTrust=project：项目自治档，失配属 WARN；改 org 可升级为强制】';
-  if (gateRes.error) {
-    add('WARN', `gate 安装锚校验跳过（kit.json 解析失败：${gateRes.error}）`);
-  } else if (gateRes.skipped) {
-    add('PASS', `gate 安装锚校验跳过（无带锚 gate 条目——旧装户重装 add-gate 后生效）`);
-  } else if (gateRes.mismatch.length === 0 && gateRes.gone.length === 0) {
-    add('PASS', `gate 安装锚 ${gateRes.total} 份无失配`);
-  } else {
-    const lv = orgMode ? 'FAIL' : 'WARN';
-    if (gateRes.mismatch.length) add(lv, `gate 安装锚失配 ${gateRes.mismatch.length} 份：${gateRes.mismatch.join('、')}——.agents/hooks/ 门禁脚本与安装时包源 sha 不一致（手改会永久留痕）${orgMode ? '（org 档即不可接受）' : '；有意改动知悉即可'}（重装重锚：flow-kit add-gate <门名> --force；恢复原版：从包源 modules/gates/ 拷回）${trustNote}`);
-    if (gateRes.gone.length) add(lv, `gate 带锚文件缺失 ${gateRes.gone.length} 份：${gateRes.gone.join('、')}——门禁已不在盘面（失效${orgMode ? '；org 档即不可接受' : ''}）；恢复：flow-kit add-gate <门名> --force 或从包源 modules/gates/ 拷回${trustNote}`);
-  }
-
-  // 6.7 跨宿主薄适配正文段漂移校验（2026-09-25 cross-host-sync 立法）
-  //     装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（.zcode/.omp/.opencode/.trae）下的
-  //     {agents,commands}/*.md 是薄适配。按正文段 sha 比对（B-b 语义，frontmatter 不计入漂移），
-  //     commands 层按 profiles.mjs#HOSTS.commandPrefix 前缀映射（2026-09-28 起 opencode/trae 同 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 注册表内宿主薄适配，B-b 语义）`);
-  } else {
-    add('WARN', `跨宿主薄适配正文漂移 ${adapterRes.drift} 对——权威源 .agents 与宿主薄适配正文段 sha 不一致。刷新用 flow-kit add-host <宿主> --force（flow-kit sync 不更新宿主适配；sync-hosts 只在包源仓比对 templates/_agents 与 modules/hosts）。`);
-  }
-
-  // 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）后重跑`);
-    }
-  }
-
-  // 6.9 模板下发感知（2026-10-06 template-downstream，只读 advisory——与 sync 出账同判据
-  //     profiles.templateDriftOf 单源；doctor 不写 kit.json，两次 sync 之间持续回显，sync 后自然消隐）。
-  //     语义：源仓模板已演进且盘面未跟随 → WARN 提醒（owned 归项目所有，不自动覆盖）；首次引入 WARN。
-  //     旧装户 owned[] 无 srcSha256 → no-anchor 静默跳过（无判定依据不产出告警），下次 sync 写锚后生效。
-  const tplRes = checkTemplateDrift(target, pkgRoot);
-  if (tplRes.skipped) {
-    if (tplRes.note) add('PASS', `模板感知跳过（${tplRes.note}）`);
-  } else if (tplRes.stale.length === 0) {
-    add('PASS', `模板感知 ${tplRes.total} 份无陈旧分歧（源仓模板与上次同步锚一致或盘面已跟随）`);
-  } else {
-    add('WARN', `模板感知：源仓 ${tplRes.stale.length} 份模板自上次同步后有演进且盘面未跟随：${tplRes.stale.join('、')}——如需跟随从包源 templates/ 拷贝；有意定制可忽略（跑 flow-kit sync 刷新锚后本项静默）`);
-  }
-
-  // 6.10 level-hints 配置体检（2026-10-13 hint-doctor）——非法档位/正则此前只在**跑 flow-kit route 时**
-  //     才抛 LEVEL_HINTS_INVALID，而 route 是可选调用 → 写错的清单能静默存活很久。写错配置比没配置危险：
-  //     没配置会提示补，写错会误判档位。故给一条主动体检通道。
-  //     口径纪律：doctor 不复刻解析器（复刻＝判据双源漂移），spawn 装户 level-criteria.mjs 的 --check
-  //     入口（判据单源仍是 parseLevelHints 一份）。
-  {
-    const hr = checkLevelHints(target);
-    if (hr.skipped) add('PASS', `level-hints 体检跳过（${hr.note}）`);
-    else if (hr.ok) add('PASS', `level-hints 配置合法（${hr.note}）`);
-    else add('FAIL', `level-hints 配置有误——非法档位或正则会让 flow-kit route fail-loud 抛错、按错误下限定级：\n${hr.detail}`);
-  }
-
-  // 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 {
-    // 判定流水守卫（2026-10-13 judgment-ledger 回灌 B4）：doctor 是体检探针而非门裁决点，
-    // 不落 .agents/judgments.jsonl（同 validate.mjs 口径；裁决链 = CLI/pre-push/CI/verify 正常落账）
-    // --all 显式全量（2026-10-13 分道后裸跑=默认硬门）：doctor 是体检面，advisory 计数沿分道前全量口径。
-    const cl = spawnSync(process.execPath, ['.agents/scripts/check-loop.mjs', '--all'],
-      { cwd: target, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_NO_LEDGER: '1' } });
-    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 警告）` : ''}`);
-    } else {
-      add('FAIL', `check-loop 有 hard-block：\n${String(cl.stderr || '').split('\n').slice(0, 8).join('\n')}`);
-    }
-  }
-
-  // 8. 看板端口（信息级）
-  const kit = fs.existsSync(kitPath) ? JSON.parse(fs.readFileSync(kitPath, 'utf8')) : null;
-  const port = kit?.options?.boardPort || '8933';
-  portInUse(port).then((inUse) => {
-    print(results);
-    console.log(inUse
-      ? `ℹ️  看板端口 ${port} 已有监听（ensure-board 探活：本项目看板复用/旧代码重启，他人进程不 kill 自动上探，见 workflow/README.md）`
-      : `ℹ️  看板端口 ${port} 空闲（看板默认不拉起；需要时手动 .agents/scripts/ensure-board.mjs（跨平台）或 node .agents/scripts/workflow-board-server.mjs）`);
-    process.exit(results.some((r) => r.level === 'FAIL') ? 1 : 0);
-  });
-}
-
-// checkLevelHints（2026-10-13 hint-doctor）：.agents/level-hints.txt 的**主动**体检。
-// 为什么不能靠 route：非法档位/ERE 此前只在跑 flow-kit route 时才抛 LEVEL_HINTS_INVALID，
-//   而 route 是可选调用 → 写错的清单能静默存活很久，直到某次碰巧路由才炸（写错配置比没配置危险）。
-// 口径纪律：doctor **不复刻解析器**（复刻＝判据双源漂移），改为 spawn 装户 .agents/scripts/
-//   level-criteria.mjs 的 --check 入口——parseLevelHints 永远只有一份实现。
-// 三态：skipped（无判据单源＝1.7.15 前旧装户，不产出告警）/ ok（含未配置=默认空）/ 配置有误。
-export function checkLevelHints(target) {
-  const script = path.join(target, '.agents', 'scripts', 'level-criteria.mjs');
-  if (!fs.existsSync(script)) return { skipped: true, ok: true, note: '无 .agents/scripts/level-criteria.mjs——1.7.15 之前版本无此判据单源' };
-  const r = spawnSync(process.execPath, [script, '--check', path.join(target, '.agents', 'level-hints.txt')], {
-    cwd: target, encoding: 'utf8',
-  });
-  // spawn 本身失败（ENOENT/EACCES/超时被杀）时 status 为 null 且 stderr 可能为空——
-  //   不区分会把「体检脚本跑不起来」误报成「配置有误」，排障方向直接被带偏（2026-10-13 executor-review）。
-  if (r.error) return { skipped: false, ok: false, detail: `无法执行体检脚本 ${path.basename(script)}：${r.error.message}` };
-  if (r.status === 0) return { skipped: false, ok: true, note: String(r.stdout || '').trim() || '通过' };
-  if (r.status === null) return { skipped: false, ok: false, detail: `体检脚本异常终止（无退出码，signal=${r.signal || '未知'}）——无法判定 level-hints 是否合法` };
-  return {
-    skipped: false,
-    ok: false,
-    detail: String(r.stderr || '').split('\n').slice(0, 6).join('\n').trim(),
-  };
-}
-
-function print(results) {
-  const icon = { PASS: '✅', WARN: '⚠️ ', FAIL: '❌' };
-  for (const r of results) console.log(`${icon[r.level]} ${r.msg}`);
-  const fails = results.filter((r) => r.level === 'FAIL').length;
-  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 };
-}
-
-// ---- 门禁信任档（2026-10-12 gate-trust-level）----
-// 单源：本文件（doctor §6.6b 判定 + init.mjs 写 kit.json 默认值，两处 import 同一份——
-// 装户侧不消费（kit.json 是包源 CLI 写的台账），故不落 templates/_agents/scripts/policy.mjs：
-// 放那边会让装副本带一个它自己不用的判据，两处真值反而更多。两档语义：
-//   'project'（默认）：gate 安装锚失配 = **WARN**。装户对门有最终所有权——锚只提供可见性，
-//     有意改动知悉即可。这是 1.7.11 起的现状，本档只是把隐式默认显式命名为「项目自治」。
-//   'org'：失配 = **FAIL**（doctor exit 1）。给多仓/组织场景一个真实的强制位——对齐 Claude Code 的
-//     managed policy + allowManagedHooksOnly（组织级强制 + 可屏蔽项目自定义 hook）。
-// 为什么**不把默认改成 org**：本仓诚实边界声明写明「门禁关不掉通道」（台账可写、哈希链防不住整文件
-// 重写）。把可见性升成强制而不同步补上「组织侧锚源的不可篡改性」，等于宣称一个关不掉的通道能关——
-// 那比 WARN 更不可信。默认档与现行为逐字一致（零行为变化），要升的人显式改 kit.json 并自行承担
-// 「组织必须同步管住锚来源」的责任。
-// 非法值 / 缺键（旧台账）→ 回退 'project'（= 零行为变化，**绝不因非法配置变严**）。
-export const GATE_TRUST_LEVELS = ['project', 'org'];
-export const GATE_TRUST_DEFAULT = 'project';
-export function gateTrustOf(kit) {
-  const v = kit && kit.gateTrust;
-  return GATE_TRUST_LEVELS.includes(v) ? v : GATE_TRUST_DEFAULT;
-}
-
-// gate 安装锚校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-10-11 P3-1 gate 防改锚）
-// 判据：kit.owned 中 rel 以 .agents/hooks/ 开头且带 srcSha256 的条目（＝add-gate 逐字拷贝安装的 gate 脚本，
-// 锚语义见 src/add-gate.mjs 头注），按 LF 归一算盘面 sha（与 checkOwnedDrift 同口径）比对锚。
-// local-pre-commit 须排除：它是合并接线件，其 srcSha256 由 init/sync 按「模板语义」写（≠ 逐字拷贝锚），
-// 且盘面含各门挂载行——纳入必恒失配误报。
-// 不阻断（默认 'project' 档）：装户对门有最终所有权，锚只提供可见性（2026-10-10 调研
-// 「gate 装户可改、hard 项缺防改」结论）。'org' 档（2026-10-12 gate-trust-level，判据单源
-// policy.mjs#gateTrustOf）下失配升 FAIL —— 多仓/组织场景的组织级强制位，对齐 managed policy。
-// 返回：{ total, mismatch, gone, skipped, error?, trust }
-export function checkGateAnchors(target) {
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) return { total: 0, mismatch: [], gone: [], skipped: true };
-  let kit;
-  try {
-    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  } catch (e) {
-    return { total: 0, mismatch: [], gone: [], skipped: true, error: e.message };
-  }
-  const trust = gateTrustOf(kit); // 缺键/非法 → 'project'（零行为变化）
-  const owned = Array.isArray(kit.owned) ? kit.owned : [];
-  const anchored = owned.filter((f) => f.rel.startsWith('.agents/hooks/')
-    && f.rel !== '.agents/hooks/local-pre-commit' // 合并接线件，srcSha256 是模板语义锚，非逐字拷贝锚（见上）
-    && typeof f.srcSha256 === 'string' && f.srcSha256);
-  if (anchored.length === 0) return { total: 0, mismatch: [], gone: [], skipped: true, trust };
-  const mismatch = [];
-  const gone = [];
-  for (const f of anchored) {
-    const p = path.join(target, f.rel);
-    if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
-    // sha 按 LF 归一口径（同 checkOwnedDrift）：CRLF 盘面（autocrlf 检出）与锚不误报
-    const h = createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-    if (h !== f.srcSha256) mismatch.push(f.rel);
-  }
-  return { total: anchored.length, mismatch, gone, skipped: false, trust };
-}
-
-// 模板下发感知（2026-10-06 template-downstream）：只读判据——owned 模板条目三方 sha 比对，
-// 判定单源 profiles.templateDriftOf（与 sync 出账同源，防两处字面量漂移）。恒不写 kit.json。
-// 返回 { skipped, note?, total, stale[] }：skipped=true 时 note 说明原因（无 kit / 无 owned /
-// 无锚——旧装户静默不追溯）；total＝参与比对的条目数；stale＝stale-drift 的 rel 清单。
-export function checkTemplateDrift(target, pkgRoot) {
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) return { skipped: true, note: 'kit.json 不存在', total: 0, stale: [] };
-  let kit;
-  try {
-    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  } catch (e) {
-    return { skipped: true, note: `kit.json 解析失败：${e.message}`, total: 0, stale: [] };
-  }
-  if (!pkgRoot) return { skipped: true, note: '无包源根', total: 0, stale: [] };
-  const owned = Array.isArray(kit.owned) ? kit.owned : [];
-  if (owned.length === 0) return { skipped: true, note: 'kit.json 无 owned 条目', total: 0, stale: [] };
-  const shaText = (p) => createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
-  const stale = [];
-  let total = 0;
-  let anchored = 0;
-  for (const f of owned) {
-    if (TEMPLATE_DRIFT_EXCLUDE.has(f.rel)) continue;
-    const src = srcTemplatePath(pkgRoot, f.rel);
-    if (!src) continue;
-    total++;
-    if (typeof f.srcSha256 !== 'string' || !f.srcSha256) continue; // no-anchor：旧装户静默跳过
-    anchored++;
-    const srcCur = shaText(src);
-    const diskPath = path.join(target, f.rel);
-    const disk = fs.existsSync(diskPath) ? shaText(diskPath) : null;
-    if (templateDriftOf({ disk, srcRecord: f.srcSha256, srcCur }) === 'stale-drift') stale.push(f.rel);
-  }
-  if (anchored === 0) return { skipped: true, note: 'owned 模板条目均无 srcSha256 锚（旧装户，下次 sync 写锚后生效）', total: 0, stale: [] };
-  return { skipped: false, total, stale };
-}
-
-// 跨宿主薄适配正文段漂移校验（独立 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 不计入漂移）；commands 层映射走 HOSTS.commandPrefix 前缀（2026-09-28 起
-// opencode 与 trae 同为 wf- 前缀，单源见 profiles.mjs；roles 层映射全宿主无前缀）。
-// 返回：{ 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 同源）
-  // splitFm/bodySha 单源复用 sync-hosts（2026-10-11 bodysha-single-source：此前内联第二份实现靠
-  // 注释约束同口径，收敛为 import 消灭漂移面）
-  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/* → 每个带 commandPrefix 的宿主 commands/<prefix><name>.md（单源 profiles.mjs#HOSTS）；
-      //             roles/*    → 4 宿主 agents/<name>.md（无前缀）
-      const targets = [];
-      if (sub === 'commands') {
-        for (const [dir, prefix] of HOST_CMD_DIR) targets.push([dir, 'commands', `${prefix}${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 };
-}
-
-// delegations 月度聚合快照新鲜度（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-29 p0-gate-noise-batch）
-// 返回：{ stale, ledgerMonth, snapshotMonth, skipped, note? }
-//   - skipped=true：delegations.md 不存在 / 无台账数据行 → doctor 记 PASS（跳过），不误报 fresh 装户
-//   - stale=true：快照行缺失 或 快照最新月 < 台账数据行最新月
-//   - ledgerMonth：台账数据行首列（YYYY-MM-DD）中最大 YYYY-MM
-//   - snapshotMonth：快照行首列（YYYY-MM）中最大 YYYY-MM（无快照行则 null）
-export function checkDelegationSnapshotFreshness(target) {
-  const file = path.join(target, 'workflow', 'delegations.md');
-  if (!fs.existsSync(file)) return { stale: false, ledgerMonth: null, snapshotMonth: null, skipped: true, note: 'delegations.md 不存在' };
-  let text;
-  // 分片感知读（2026-10-13 ledger-shard-ledgers）：text = 主台账 ∪ delegations.d/*.md——数据行迁入
-  // 分片后 ledgerMonth 仍取全量数据行最大月，快照陈旧判定不失效（读侧单源 = ledger-shards.readLedgerText）。
-  try { text = readLedgerText(target, 'delegations'); } catch { return { stale: false, ledgerMonth: null, snapshotMonth: null, skipped: true, note: 'delegations.md 不可读' }; }
-  const lines = text.split(/\r?\n/);
-  let ledgerMonth = null;
-  let snapshotMonth = null;
-  let hasDataRows = false;
-  for (const line of lines) {
-    if (!/^\s*\|/.test(line)) continue;
-    const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
-    if (!cells.length) continue;
-    // 台账数据行：首列 = YYYY-MM-DD
-    if (/^\d{4}-\d{2}-\d{2}$/.test(cells[0])) {
-      hasDataRows = true;
-      const m = cells[0].slice(0, 7);
-      if (!ledgerMonth || m > ledgerMonth) ledgerMonth = m;
-      continue;
-    }
-    // 快照行：首列 = YYYY-MM（与数据行正则互斥）
-    if (/^\d{4}-\d{2}$/.test(cells[0])) {
-      const m = cells[0];
-      if (!snapshotMonth || m > snapshotMonth) snapshotMonth = m;
-    }
-  }
-  if (!hasDataRows) return { stale: false, ledgerMonth: null, snapshotMonth: null, skipped: true, note: '台账无数据行' };
-  if (!snapshotMonth) return { stale: true, ledgerMonth, snapshotMonth: null, skipped: false };
-  if (snapshotMonth < ledgerMonth) return { stale: true, ledgerMonth, snapshotMonth, skipped: false };
-  return { stale: false, ledgerMonth, snapshotMonth, skipped: false };
-}