agentic-flow-kit 1.4.0 → 1.6.0

package/modules/hosts/trae/commands/wf-sync-hosts.md

@@ -13,16 +13,16 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 > 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
 > 目标根取 `--dir <目录>` > 当前目录。
 
-## 何时跑
+## 1. 何时跑
 
 - 改 `templates/_agents/commands/*.md` 正文后（11 个 commands 文件）
 - 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
 - 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
 - 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
 
-## 怎么跑
+## 2. 怎么跑
 
-### 默认 `--diff`（仅报告）
+### 2.1 默认 `--diff`（仅报告）
 
 ```
 node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
@@ -36,7 +36,7 @@ flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或
 - **⚠️ 权威源声明但薄适配缺失** — `add-host <h>` 接管后跑 `--apply` 才会装（apply 不自动创建）
 - **⚠️ 孤儿薄适配（权威源无对应文件）** — 历史残留或宿主特化，apply 不删
 
-### `--apply` 单向同步
+### 2.2 `--apply` 单向同步
 
 ```
 node bin/flow-kit.mjs sync-hosts --apply
@@ -44,7 +44,7 @@ node bin/flow-kit.mjs sync-hosts --apply
 
 按权威源正文覆盖薄适配正文段；薄适配原 frontmatter 保留（trae name: wf-X、opencode 描述、zcode/omp 中文风格各自不动）。apply 不反向同步——薄适配手改了正文也会被覆盖（这是设计选择，避免漂移方向歧义）。
 
-### 自验
+### 2.3 自验
 
 ```
 npm test                                       # 含 sync-hosts.test.mjs 8 场景
@@ -52,7 +52,7 @@ node bin/flow-kit.mjs doctor                   # 装户跑 §7.x PASS；包源
 sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已探测分流
 ```
 
-## 边界（不要做）
+## 3. 边界（不要做）
 
 - 不要 `--apply` 反向同步（写权威源）：权威源是真相，薄适配手改会被覆盖——这是设计，apply 前先看 `--diff`
 - 不要删除孤儿薄适配：可能是宿主特化或历史残留，apply 不动
@@ -60,14 +60,14 @@ sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已
 - 不要把「避免与权威版本漂移」明文加回去——这是旧契约的指针风格，已被 B-b 正文副本取代
 - 装了新宿主后跑 `--apply`：新宿主目录空白，apply 不会自动创建薄适配（薄适配须经 `add-host <h>` 接管）
 
-## 不在本次同步范围
+## 4. 不在本次同步范围
 
 - trae 钩子（`modules/hosts/trae/hooks/*.cjs`）— 独立演进的工程件
 - trae 规则（`modules/hosts/trae/rules/*.md`）— 同上
 - 包源 .agents/scripts/*.cjs（pre-commit 等钩子）— 同步由 `flow-kit sync` 走 managed 台账负责
 
-## 相关留痕
+## 5. 相关留痕
 
 - intent：`workflow/intents/2026-09-25-cross-host-sync.md`
 - plan：`workflow/plans/2026-09-25-cross-host-sync.md`（含 B-b 方案拍板）
-- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）
+- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）

package/modules/hosts/trae/commands/wf-test.md

@@ -47,20 +47,19 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - 复核者读入口文档(intent / incident) + spec + plan + diff,判断变更意图与风险
 - 复核意见交用户定性(采纳 / 驳回);采纳项回 `build.md` 修改
 
-## 子代理调用约定
+## 5. 子代理调用约定
 
 - 静态门不委派;UI 实测委派 `ui-verifier`(静态门通过后)、独立复核委派 `independent-reviewer`,均要求读取对应 `.agents/roles/*.md`;宿主不支持时按 frontmatter `fallback`(reviewer 必须另开新会话,不得主智能体自查冒充)。
 - 子智能体只返回证据与结论——失败项修复仍回 `build.md`,不得在 Test 阶段顺手改代码;修复后重跑本阶段,全过后用户确认再关单。
 
-## 确认后
+## 6. 确认后（关单）
 
-- 输出测试报告(通过项 / 失败项)
-- 失败项已修复并复测通过
+- 输出测试报告(通过项 / 失败项);失败项已修复并复测通过。
 - **关单**（日常闭环点，不依赖是否上 prod）:
   - 关单前一键过门：`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**`--doc` 把测试绿凭证绑到本单**——不带它落下的绿行不给任何单背书，confirm-doc 前置与检查 8 对账只认带本单 `--doc` 的绿行（仅 v6+ 生效）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
-  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent $\rightarrow$ done；同名 spec/Quick-Plan（若有）仍 approved $\rightarrow$ done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
+  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent → done；同名 spec/Quick-Plan（若有）仍 approved → done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
   - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
-**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（两形态 / 逐件+逐件原话 / done 内容绑定（关单编辑先于 done 确认、confirm-doc 是最后一次写入）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
   - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
   - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
   - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）

package/modules/hosts/zcode/agents/implementer.md

@@ -6,7 +6,7 @@ description: 在已批准且边界明确的工作包内实现改动或补测试
 
 > 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（各宿主目录下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
-## 职责
+## 1. 职责
 
 执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
 
@@ -15,7 +15,7 @@ description: 在已批准且边界明确的工作包内实现改动或补测试
 - 编写或调整任务直接要求的测试
 - 修复与任务直接相关的编译错误
 
-## 必需输入
+## 2. 必需输入
 
 开始前必须获得：
 
@@ -26,7 +26,7 @@ description: 在已批准且边界明确的工作包内实现改动或补测试
 
 任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
 
-## 行为边界
+## 3. 行为边界
 
 - 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
 - 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
@@ -35,13 +35,13 @@ description: 在已批准且边界明确的工作包内实现改动或补测试
 - 不执行提交、推送、发布、数据迁移或破坏性操作。
 - 不顺手重构、格式化或清理与任务无关的代码。
 
-## 验证
+## 4. 验证
 
 - 运行任务指定的最小相关检查。
 - 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
 - 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
 
-## 输出
+## 5. 输出
 
 返回给主智能体：
 
@@ -49,4 +49,3 @@ description: 在已批准且边界明确的工作包内实现改动或补测试
 2. 每个文件的改动摘要
 3. 已运行的验证及结果
 4. 未解决的阻塞或剩余风险
-

package/modules/hosts/zcode/agents/independent-reviewer.md

@@ -6,11 +6,11 @@ description: 只读独立复核（spec 或实现 diff）；不改动文件、不
 
 > 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（各宿主目录下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
-## 职责
+## 1. 职责
 
 在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。
 
-## 必需输入
+## 2. 必需输入
 
 开始前必须获得：
 
@@ -21,7 +21,7 @@ description: 只读独立复核（spec 或实现 diff）；不改动文件、不
 
 输入不足以确定范围时，停止并向主智能体报告。
 
-## 行为边界
+## 3. 行为边界
 
 - 只读，不修改任何仓库文件。
 - 不替用户决定问题定性、方案取舍、合入或上线。
@@ -30,7 +30,7 @@ description: 只读独立复核（spec 或实现 diff）；不改动文件、不
 - 不把样式偏好、假设性风险或既有无关问题包装成缺陷。
 - 无法验证的事项明确标为未验证，不声称已经通过。
 
-## 复核重点
+## 4. 复核重点
 
 1. 实现是否满足入口文档和验收标准
 2. 是否违反根 `AGENTS.md` 与改动域目录级 `AGENTS.md` 的架构、数据和所在域红线
@@ -38,7 +38,7 @@ description: 只读独立复核（spec 或实现 diff）；不改动文件、不
 4. 是否缺少能防止回归的验证
 5. 是否存在数据丢失、安全、权限或发布风险
 
-## 输出
+## 5. 输出
 
 按严重度输出问题清单：
 
@@ -46,4 +46,4 @@ description: 只读独立复核（spec 或实现 diff）；不改动文件、不
 - `P1`：功能错误、明确回归或违反项目硬约束
 - `P2`：非阻断但有证据的维护性问题
 
-每项必须包含：位置、问题、证据、建议。没有发现时明确输出“未发现阻断问题”，并列出未验证范围。
+每项必须包含：位置、问题、证据、建议。没有发现时明确输出"未发现阻断问题"，并列出未验证范围。

package/modules/hosts/zcode/agents/ui-verifier.md

@@ -6,11 +6,11 @@ description: 浏览器实测 UI 改动（只读验证、不留脏数据）；结
 
 > 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（各宿主目录下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
 
-## 职责
+## 1. 职责
 
 对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
 
-## 必需输入
+## 2. 必需输入
 
 开始前必须获得：
 
@@ -21,7 +21,7 @@ description: 浏览器实测 UI 改动（只读验证、不留脏数据）；结
 
 缺少可观察的预期结果时，停止并向主智能体报告。
 
-## 执行
+## 3. 执行
 
 1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
 2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
@@ -30,14 +30,14 @@ description: 浏览器实测 UI 改动（只读验证、不留脏数据）；结
 5. 收集控制台、网络请求、DOM 数据或截图等证据。
 6. 结束时关闭本次启动的后台进程。
 
-## 行为边界
+## 4. 行为边界
 
 - 不修改代码、配置、测试数据或工作流文档。
 - 不自行修复发现的问题；将失败证据交还主智能体。
 - 不使用生产环境或真实业务数据。
 - 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
 
-## 输出
+## 5. 输出
 
 返回：
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "agentic-flow-kit",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {
     "test": "node src/run-tests.mjs",
+    "lint": "eslint .",
     "prepack": "node -e \"require('fs').rmSync('templates/_agents/cache',{recursive:true,force:true})\" && node scripts/check-pack-eol.mjs"
   },
   "bin": {
@@ -41,5 +42,9 @@
   "bugs": {
     "url": "https://github.com/zerosloney/agentic-flow-kit/issues"
   },
-  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme"
+  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "eslint": "^9.39.4"
+  }
 }

package/src/doctor.mjs

@@ -10,7 +10,7 @@ import { isOwned, HOSTS, pickStackVars, srcTemplatePath, templateDriftOf, TEMPLA
 // 宿主目录映射（与 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(([k, v]) => [v.dir, v.commandPrefix]);
+const HOST_CMD_DIR = Object.entries(HOSTS).filter(([, v]) => v.commandPrefix).map(([, v]) => [v.dir, v.commandPrefix]);
 
 function sh(cmd, cwd) {
   try {

package/src/init.test.mjs

@@ -83,7 +83,7 @@ check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'init-p1-'));
   const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
   const vars = { BOARD_PORT: '8933' };
-  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
+  renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
   // P1-1：renderTree 落盘执行位——win32 下 statSync().mode 无 0o111 语义（恒 0666 系），
   // 断言「writeFileSync 带 mode 参数不炸 + POSIX 语义表达」；真值在 POSIX CI 腿验证
   const hookStat = fs.statSync(path.join(tmp, '.githooks', 'pre-commit'));

package/src/run-tests.mjs

@@ -1,6 +1,9 @@
-// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
+// run-tests.mjs — 全套测试入口（npm test）：lint 首步 + CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
 // 顺序执行、任一非零整体失败（exit 1）。check-loop 套件自 2026-09-26 check-loop-node 起为 node 实现
 // （check-loop.test.mjs 由下方 glob 自动发现——旧 bash 特判与「无 sh 跳过」提示随迁移退役）。
+// lint 首步（2026-10-08 engine-quality-batch）：eslint 仅 devDependency（包源仓）——检测到未安装时
+// 显式打印 skip 后继续（裸 checkout 未 npm install 场景的可诊断性；装户仓无本编排器不涉及），
+// 已安装但报错则 fail-closed 计入失败。
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -25,6 +28,17 @@ const nodeSuites = [
 ];
 
 let failed = 0;
+
+// lint 首步：eslint 可用性探测 = require.resolve 于包源仓 node_modules（裸 checkout 解析失败 → 显式跳过）
+console.log('\n===== lint（eslint .）=====');
+const eslintEntry = spawnSync(process.execPath, ['-e', "require.resolve('eslint')"], { cwd: ROOT, encoding: 'utf8' });
+if (eslintEntry.status !== 0) {
+  console.log('[lint] skipped: eslint not installed（npm install 后启用；仅包源仓场景）');
+} else {
+  const r = spawnSync(process.execPath, [path.join(ROOT, 'node_modules/eslint/bin/eslint.js'), '.'], { cwd: ROOT, stdio: 'inherit' });
+  if (r.status !== 0) failed++;
+}
+
 for (const rel of nodeSuites) {
   console.log(`\n===== ${rel} =====`);
   const r = spawnSync(process.execPath, [path.join(ROOT, rel)], { cwd: ROOT, stdio: 'inherit' });

package/src/sync-hosts.mjs

@@ -47,93 +47,113 @@ function listMd(dir) {
 //   roles    权威源 → 全部宿主 agents 各一份
 // hostDirOf：宿主 → 适配目录名。包源布局 = 宿主键（modules/hosts/opencode/…）；装户布局 = HOSTS[h].dir
 // （项目根下 .opencode/…，带点）——2026-10-07 sync-hosts-target-fix 加装户支持时引入。
-function pairsFor(authRel, hostDirOf = (h) => h) {
+// hostFilter（2026-10-09 sync-hosts-root-coverage）：宿主级过滤（多根模式下「项目根宿主点」根只扫
+//   实际存在 dir 的宿主——不存在=没装该宿主点，不算缺失不算漂移）。
+function pairsFor(authRel, hostDirOf = (h) => h, hostFilter = null) {
   const out = [];
   const norm = authRel.split(path.sep).join('/');
+  // 条目带 h（宿主键）——faces 计数用「实际生成配对 > 0 的宿主数」（复核 P2-2：存在但空的宿主点
+  // 目录此前被计入「N 宿主」，对账面自描述轻微夸大）
   if (norm.startsWith('commands/') && norm.endsWith('.md')) {
     const name = norm.slice('commands/'.length, -'.md'.length);
     for (const [h, v] of Object.entries(HOSTS)) {
-      if (v.commandPrefix) out.push({ adapterRel: `${hostDirOf(h)}/commands/${v.commandPrefix}${name}.md` });
+      if (hostFilter && !hostFilter(h)) continue;
+      if (v.commandPrefix) out.push({ h, adapterRel: `${hostDirOf(h)}/commands/${v.commandPrefix}${name}.md` });
     }
   } else if (norm.startsWith('roles/') && norm.endsWith('.md')) {
     const name = norm.slice('roles/'.length, -'.md'.length);
-    for (const h of Object.keys(HOSTS)) out.push({ adapterRel: `${hostDirOf(h)}/agents/${name}.md` });
+    for (const h of Object.keys(HOSTS)) {
+      if (hostFilter && !hostFilter(h)) continue;
+      out.push({ h, adapterRel: `${hostDirOf(h)}/agents/${name}.md` });
+    }
   }
   return out;
 }
 
 // diffHosts：权威源正文段 vs 薄适配正文段的漂移分析（B-b 语义；pure function）。
 // authorityRoot：权威源根（含 commands/ + roles/）
-// adaptersRoot：薄适配根（含 <h>/{agents,commands}/）
+// 多根对账（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）
-// 返回：{ drift, inSync, authorityMissing, adapterOrphans, note }
-// drift = 正文段 sha 不一致（权威源改 / 薄适配手改 都计入；不区分方向）
-// inSync = 正文段 sha 对齐的文件对数
-// authorityMissing = 权威源声明但薄适配文件不存在（apply 不自动创建——薄适配须经 add-host 接管）
-// adapterOrphans = 薄适配存在但权威源无对应文件（apply 不删——可能是宿主特化或历史残留）
-export function diffHosts({ authorityRoot, adaptersRoot, hostDirOf = (h) => h }) {
-  if (!fs.existsSync(authorityRoot)) return { drift: [], inSync: 0, authorityMissing: [], adapterOrphans: [], note: `权威源根不存在：${authorityRoot}` };
+// 返回：{ drift, inSync, authorityMissing, adapterOrphans, faces }
+// drift 条目自带 root（applyForward 按它定位适配文件）；faces = 对账面自描述行（防不可解释的「N 对」）
+export function diffHosts(opts) {
+  const authorityRoot = opts.authorityRoot;
+  const roots = opts.adapterRoots || [{ root: opts.adaptersRoot, hostDirOf: opts.hostDirOf || ((h) => h), label: null }];
+  if (!fs.existsSync(authorityRoot)) return { drift: [], inSync: 0, authorityMissing: [], adapterOrphans: [], faces: [], note: `权威源根不存在：${authorityRoot}` };
 
   const drift = [];
+  const adapterOrphans = [];
   let inSync = 0;
   const adapterSeen = new Set();
   const authorityMissing = [];
+  const faces = [];
 
-  // 扫权威源 commands/ + roles/
-  for (const sub of ['commands', 'roles']) {
-    const subAbs = path.join(authorityRoot, sub);
-    for (const f of listMd(subAbs)) {
-      const authRel = `${sub}/${f}`;
-      const authAbs = path.join(authorityRoot, authRel);
-      const authSha = bodySha(authAbs);
-      const pairs = pairsFor(authRel, hostDirOf);
-      if (pairs.length === 0) continue;
-      for (const { adapterRel } of pairs) {
-        adapterSeen.add(adapterRel);
-        const adapterAbs = path.join(adaptersRoot, adapterRel);
-        const adapterSha = bodySha(adapterAbs);
-        if (adapterSha === null) {
-          // 未安装的宿主不算「缺失」——那是没装，不是漂移（2026-10-07：装户只装部分宿主时，
-          // 旧行为会把未装宿主的全部适配文件列成 authorityMissing，装户 --apply 恒 exit 1 且刷屏）
-          if (fs.existsSync(path.dirname(adapterAbs))) authorityMissing.push({ authRel, adapterRel });
-          continue;
+  for (const spec of roots) {
+    const { root, hostDirOf, hostFilter, label } = spec;
+    const rootHosts = new Set(); // 该根实际生成配对 > 0 的宿主（faces 计数口径，复核 P2-2）
+    // 扫权威源 commands/ + roles/
+    for (const sub of ['commands', 'roles']) {
+      const subAbs = path.join(authorityRoot, sub);
+      for (const f of listMd(subAbs)) {
+        const authRel = `${sub}/${f}`;
+        const authAbs = path.join(authorityRoot, authRel);
+        const authSha = bodySha(authAbs);
+        const pairs = pairsFor(authRel, hostDirOf, hostFilter);
+        if (pairs.length === 0) continue;
+        for (const { h, adapterRel } of pairs) {
+          rootHosts.add(h);
+          adapterSeen.add(adapterRel);
+          const adapterAbs = path.join(root, adapterRel);
+          const adapterSha = bodySha(adapterAbs);
+          if (adapterSha === null) {
+            // 未安装的宿主不算「缺失」——那是没装，不是漂移（2026-10-07：装户只装部分宿主时，
+            // 旧行为会把未装宿主的全部适配文件列成 authorityMissing，装户 --apply 恒 exit 1 且刷屏）
+            if (fs.existsSync(path.dirname(adapterAbs))) authorityMissing.push({ authRel, adapterRel });
+            continue;
+          }
+          if (authSha === adapterSha) { inSync++; continue; }
+          drift.push({ authRel, adapterRel, authSha, adapterSha, root });
         }
-        if (authSha === adapterSha) { inSync++; continue; }
-        drift.push({ authRel, adapterRel, authSha, adapterSha });
       }
     }
-  }
 
-  // 扫薄适配找孤儿（权威源无对应文件）
-  const adapterOrphans = [];
-  for (const h of Object.keys(HOSTS)) {
-    for (const sub of ['agents', 'commands']) {
-      const subAbs = path.join(adaptersRoot, hostDirOf(h), sub);
-      for (const f of listMd(subAbs)) {
-        const adapterRel = `${hostDirOf(h)}/${sub}/${f}`;
-        if (adapterSeen.has(adapterRel)) continue;
-        let authGuess;
-        const prefix = HOSTS[h] && HOSTS[h].commandPrefix;
-        if (sub === 'commands' && prefix && f.startsWith(prefix)) {
-          // 命令层薄适配带宿主 commandPrefix（2026-09-28：opencode 对齐 trae 后两宿主同口径）
-          authGuess = `commands/${f.slice(prefix.length)}`;
-        } else if (sub === 'agents') {
-          authGuess = `roles/${f}`;
-        } else {
-          authGuess = `commands/${f}`;
+    faces.push(label ? `${label}（${rootHosts.size} 宿主）` : `${root}（${rootHosts.size} 宿主）`);
+    // 扫薄适配找孤儿（权威源无对应文件）
+    for (const h of Object.keys(HOSTS)) {
+      if (hostFilter && !hostFilter(h)) continue;
+      for (const sub of ['agents', 'commands']) {
+        const subAbs = path.join(root, hostDirOf(h), sub);
+        for (const f of listMd(subAbs)) {
+          const adapterRel = `${hostDirOf(h)}/${sub}/${f}`;
+          if (adapterSeen.has(adapterRel)) continue;
+          let authGuess;
+          const prefix = HOSTS[h] && HOSTS[h].commandPrefix;
+          if (sub === 'commands' && prefix && f.startsWith(prefix)) {
+            // 命令层薄适配带宿主 commandPrefix（2026-09-28：opencode 对齐 trae 后两宿主同口径）
+            authGuess = `commands/${f.slice(prefix.length)}`;
+          } else if (sub === 'agents') {
+            authGuess = `roles/${f}`;
+          } else {
+            authGuess = `commands/${f}`;
+          }
+          adapterOrphans.push({ adapterRel, authGuess });
         }
-        adapterOrphans.push({ adapterRel, authGuess });
       }
     }
   }
 
-  return { drift, inSync, authorityMissing, adapterOrphans };
+  return { drift, inSync, authorityMissing, adapterOrphans, faces };
 }
 
 // printDiff：人类可读 diff 报告（B-b 语义：正文段比对 + frontmatter 双方不动）
 function printDiff(result) {
-  const { drift, inSync, authorityMissing, adapterOrphans, note } = result;
+  const { drift, inSync, authorityMissing, adapterOrphans, note, faces } = result;
   if (note) console.log(`ℹ️  ${note}\n`);
+  if (faces && faces.length) console.log(`  对账面：${faces.join(' + ')}`);
   console.log(`  正文对齐：${inSync} 对`);
   if (authorityMissing.length) {
     console.log(`  权威源声明但薄适配缺失（${authorityMissing.length}，apply 不自动创建——薄适配须经 add-host 接管）：`);
@@ -152,12 +172,13 @@ function printDiff(result) {
 }
 
 // applyForward：把权威源正文段同步到薄适配（保留薄适配原 frontmatter）
+// 漂移条目自带 root（多根对账，2026-10-09 sync-hosts-root-coverage）——按它定位适配文件。
 // 返回：{ synced: [{adapterRel}] }
-function applyForward({ authorityRoot, adaptersRoot }, drift) {
+function applyForward({ authorityRoot }, drift) {
   const synced = [];
-  for (const { authRel, adapterRel } of drift) {
+  for (const { authRel, adapterRel, root } of drift) {
     const authAbs = path.join(authorityRoot, authRel);
-    const adapterAbs = path.join(adaptersRoot, adapterRel);
+    const adapterAbs = path.join(root, adapterRel);
     const authText = fs.readFileSync(authAbs, 'utf8');
     const adapterText = fs.readFileSync(adapterAbs, 'utf8');
     const { body } = splitFm(authText);
@@ -189,26 +210,43 @@ export function syncHosts(args, pkgRoot) {
   // 解析为**包安装目录**，于是 doctor §7.x 报漂移、照提示跑 `--apply` 会去改包源仓（装户自己的适配层纹丝不动）。
   const target = path.resolve(dir || process.cwd() || pkgRoot);
   // 布局判定（与 doctor.checkAdapterDrift 同口径）：
-  //   包源（templates/_agents 与 modules/hosts 同时存在）→ 权威源 = <target>/templates/_agents，薄适配根 = <target>/modules/hosts
+  //   包源（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 adaptersRoot = isSourceRepo ? path.join(target, 'modules', 'hosts') : target;
+  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 layout = isSourceRepo ? '包源' : '装户';
-  // 适配目录名：包源 = 宿主键（modules/hosts/opencode/…）；装户 = HOSTS[h].dir（项目根下 .opencode/…）
-  const hostDirOf = isSourceRepo ? (h) => h : (h) => (HOSTS[h] && HOSTS[h].dir) || h;
-  const result = diffHosts({ authorityRoot, adaptersRoot, hostDirOf });
+  const result = diffHosts({ authorityRoot, adapterRoots });
 
   if (apply && result.drift.length > 0) {
-    const { synced } = applyForward({ authorityRoot, adaptersRoot }, result.drift);
+    const { synced } = applyForward({ authorityRoot }, result.drift);
     console.log(`▶ flow-kit sync-hosts --apply → ${target}（${layout}布局）`);
+    console.log(`  对账面：${result.faces.join(' + ')}`);
     console.log(`  按权威源正文覆盖薄适配正文段 ${synced.length} 份（薄适配 frontmatter 不动）：`);
     for (const rel of synced) console.log(`    - ${rel}`);
-    const after = diffHosts({ authorityRoot, adaptersRoot, hostDirOf });
+    const after = diffHosts({ authorityRoot, adapterRoots });
     console.log(`  同步后正文对齐：${after.inSync} 对；权威源缺失：${after.authorityMissing.length}；正文漂移：${after.drift.length}`);
     return after.drift.length === 0 && after.authorityMissing.length === 0 ? 0 : 1;
   }

package/src/sync-hosts.test.mjs

@@ -149,7 +149,7 @@ syncHosts(process.argv.slice(2), root);
   const r = runSyncHosts(fx, ['--diff']);
   const out = r.stdout + r.stderr;
   check('S5 薄适配正文手改 → 正文段漂移 1', /正文段漂移（1/.test(out), out);
-  const r2 = runSyncHosts(fx, ['--apply']);
+  runSyncHosts(fx, ['--apply']);
   check('S5 apply 后：薄适配正文回到权威源（含「权威源正文 implementer v1」）', /权威源正文 implementer v1/.test(R(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'))));
   check('S5 apply 不污染权威源（权威源仍 v1）', !R(path.join(fx, 'templates/_agents/roles/implementer.md')).includes('薄适配手改'));
   // apply 后再 diff 一次，diff 应显示"无漂移"
@@ -164,7 +164,7 @@ syncHosts(process.argv.slice(2), root);
   const r = runSyncHosts(fx, ['--diff']);
   const out = r.stdout + r.stderr;
   check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/wf-build.md'), out);
-  const r2 = runSyncHosts(fx, ['--apply']);
+  runSyncHosts(fx, ['--apply']);
   check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-build.md')));
 }
 
@@ -174,7 +174,7 @@ syncHosts(process.argv.slice(2), root);
   const r = runSyncHosts(fx, ['--json']);
   const out = r.stdout + r.stderr;
   let parsed = null;
-  try { parsed = JSON.parse(out); } catch {}
+  try { parsed = JSON.parse(out); } catch { /* 非 JSON 输出时 parsed 保持 null */ }
   check('S7 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.drift));
   check('S7 --json 含 inSync = 17', parsed && parsed.inSync === 17, parsed ? JSON.stringify({ inSync: parsed && parsed.inSync, missing: parsed && parsed.authorityMissing }) : 'null');
 }
@@ -188,7 +188,7 @@ syncHosts(process.argv.slice(2), root);
   check('S8 孤儿薄适配 → adapterOrphans 列', /孤儿薄适配（/.test(out) && out.includes('opencode/commands/orphan.md'), out);
   check('S8 opencode 孤儿带 wf- 前缀 → 反推权威源去掉前缀', out.includes('opencode/commands/wf-legacy.md（推测权威源：commands/legacy.md）'), out);
   check('S8 opencode 孤儿不带前缀 → 原样反推 commands/<file>', out.includes('opencode/commands/orphan.md（推测权威源：commands/orphan.md）'), out);
-  const r2 = runSyncHosts(fx, ['--apply']);
+  runSyncHosts(fx, ['--apply']);
   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')));
 }
 
@@ -237,5 +237,44 @@ 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 保留 / 对账面自描述行在案。
+{
+  // 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 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));
+}
+
+{
+  // 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));
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/src/sync.test.mjs

@@ -39,7 +39,7 @@ function mkFixture() {
 }
 
 // ---- v1 安装态（managed 台账与盘面对应 v1 渲染产物）----
-function mkTarget(fixtureRoot) {
+function mkTarget(_fixtureRoot) {
   const t = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-target-'));
   const files = {
     '.agents/scripts/keep.txt': 'keep v2\n',