agentic-flow-kit 0.3.1 → 0.5.0

package/src/sync-hosts.test.mjs

@@ -0,0 +1,170 @@
+// sync-hosts.test.mjs — flow-kit sync-hosts B-b 语义四场景（2026-09-25）
+// 方法：迷你 fixture 包根（权威源 templates/_agents + 薄适配 modules/hosts/<h>/{agents,commands}/
+//       与权威源正文段一致，frontmatter 各异）+ 子进程 driver 调真实 sync-hosts（隔离 process.exit）
+// 判据：①全对齐 → inSync=28, drift 空  ②权威源改 → drift 列  ③apply → 正文一致，frontmatter 各自保留
+//       ④薄适配 frontmatter 手改 → 不进 drift  ⑤薄适配正文手改 → drift 列，apply 覆盖
+//       ⑥薄适配缺失 → authorityMissing 列；apply 不自动创建
+// 用法：node src/sync-hosts.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SRC_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { failCount++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+const W = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content); };
+const R = (p) => fs.readFileSync(p, 'utf8');
+
+// ---- fixture 包根：权威源 + 4 宿主薄适配（正文段与权威源一致，frontmatter 各异） ----
+function mkFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-'));
+  // 权威源（2 commands + 1 role，简化测试体量；权威源也带 frontmatter 保证 body 段含前导空行，与薄适配对齐）
+  W(path.join(root, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'templates/_agents/roles/implementer.md'),
+    `---\ndescription: Implementer 角色契约\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 薄适配：commands 权威源 → opencode + trae（trae 加 wf- 前缀 + name）
+  W(path.join(root, 'modules/hosts/opencode/commands/build.md'),
+    `---\ndescription: Build · opencode 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: Build · trae 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/commands/test.md'),
+    `---\ndescription: Test · opencode 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-test.md'),
+    `---\nname: wf-test\ndescription: Test · trae 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  // roles 权威源 → 4 宿主 agents（omp/zcode 中文风格 + trae name）
+  W(path.join(root, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: 在已批准工作包内实现\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/omp/agents/implementer.md'),
+    `---\nname: implementer\ndescription: omp 本机风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: opencode 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/trae/agents/implementer.md'),
+    `---\nname: implementer\ndescription: trae 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 孤儿薄适配：权威源无对应文件
+  W(path.join(root, 'modules/hosts/opencode/commands/orphan.md'), '# orphan\n');
+  return root;
+}
+
+// ---- 子进程 driver：调真实 sync-hosts ----
+function runSyncHosts(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)};
+const root = ${JSON.stringify(fixtureRoot)};
+syncHosts(process.argv.slice(2), root);
+`);
+  return spawnSync(process.execPath, [driver, ...extra], { encoding: 'utf8' });
+}
+
+// ============ 场景 1：全对齐（正文段与权威源一致，frontmatter 各异）→ drift 空 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S1 全对齐：正文对齐 8 对（2 commands×2 适配 + 1 role×4 宿主）', /正文对齐：\s*8\s*对/.test(out), out);
+  check('S1 全对齐：报告无漂移', /无漂移/.test(out), out);
+  check('S1 全对齐：exit 0', r.status === 0, `status=${r.status}`);
+}
+
+// ============ 场景 2：权威源改了正文，薄适配未跟 → drift 列 4 处（build→opencode+trae, test→opencode+trae）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  W(path.join(fx, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S2 权威源改了 → 正文漂移 4（build×2 + test×2）', /正文段漂移（4/.test(out), out);
+  check('S2 列出 opencode/commands/build.md', out.includes('commands/build.md → opencode/commands/build.md'), out);
+  check('S2 列出 trae/commands/wf-build.md（trae wf- 前缀映射）', out.includes('commands/build.md → trae/commands/wf-build.md'), out);
+  check('S2 正文对齐 = 4（1 role × 4 宿主 implementer 未改）', /正文对齐：\s*4\s*对/.test(out), out);
+  check('S2 exit 0（diff 模式不阻断）', r.status === 0);
+}
+
+// ============ 场景 3：apply 后正文段 sha 一致，frontmatter 各自保留 ============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  const r = runSyncHosts(fx, ['--apply']);
+  const out = r.stdout + r.stderr;
+  check('S3 apply：报告同步 2 份（opencode + trae）', /按权威源正文覆盖薄适配正文段\s*2\s*份/.test(out), out);
+  check('S3 apply：opencode 正文已同步到 v2', R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：trae 正文已同步到 v2', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：opencode frontmatter 保留（仍无 name 字段）', !R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).match(/^name:/m));
+  check('S3 apply：trae frontmatter 保留（仍含 name: wf-build）', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).match(/^name:\s*wf-build/m) !== null);
+  check('S3 apply：权威源不动', R(path.join(fx, 'templates/_agents/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：再次 diff 应显示对齐 8', true); // 二次扫描由 sync-hosts 内部做
+}
+
+// ============ 场景 4：薄适配 frontmatter 手改 → 不进 drift（正文段比对不受影响）============
+{
+  const fx = mkFixture();
+  // trae frontmatter description 改成"自定义"——正文段未动
+  W(path.join(fx, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: trae 自定义描述\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S4 frontmatter 差异不计正文段漂移', /正文对齐：\s*8\s*对/.test(out) && /无漂移/.test(out), out);
+}
+
+// ============ 场景 5：薄适配正文手改 → drift 列出，apply 覆盖（不污染权威源）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: zcode 风格\n---\n\n# Implementer · v1\n\n薄适配手改 implementer v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S5 薄适配正文手改 → 正文段漂移 1', /正文段漂移（1/.test(out), out);
+  const r2 = 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 应显示"无漂移"
+  const r3 = runSyncHosts(fx, ['--diff']);
+  check('S5 apply 后再 diff 应无漂移', /无漂移/.test(r3.stdout + r3.stderr), r3.stdout + r3.stderr);
+}
+
+// ============ 场景 6：薄适配文件不存在 → authorityMissing 列出，apply 不创建 ============
+{
+  const fx = mkFixture();
+  fs.rmSync(path.join(fx, 'modules/hosts/opencode/commands/build.md'));
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/build.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/build.md')));
+}
+
+// ============ 场景 7：--json 机器可读输出 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--json']);
+  const out = r.stdout + r.stderr;
+  let parsed = null;
+  try { parsed = JSON.parse(out); } catch {}
+  check('S7 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.drift));
+  check('S7 --json 含 inSync = 8', parsed && parsed.inSync === 8, parsed ? JSON.stringify(parsed) : 'null');
+}
+
+// ============ 场景 8：孤儿薄适配（权威源无对应文件）→ adapterOrphans 列，apply 不删 ============
+{
+  const fx = mkFixture();
+  // orphan.md 已在 mkFixture 写入
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S8 孤儿薄适配 → adapterOrphans 列', /孤儿薄适配（/.test(out) && out.includes('opencode/commands/orphan.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

package/src/sync.mjs

@@ -74,6 +74,7 @@ export function sync(args, pkgRoot) {
       }
       const diskSha = fs.existsSync(disk) ? sha256(fs.readFileSync(disk)) : null;
       if (diskSha === null) {
+        fs.mkdirSync(path.dirname(disk), { recursive: true }); // 父目录可能整目录缺失（如 localOnly 宿主目录被清），copyfile 不建目录
         fs.copyFileSync(freshFile.abs, disk);
         restored.push(rel);
         managedNew.push({ rel, sha256: freshFile.sha });

package/src/sync.test.mjs

@@ -242,5 +242,15 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S12 有刷新报告', out.includes('owned 台账哈希按盘面刷新 1 份'), out);
 }
 
+// ============ 场景 13：managed 连同父目录整目录缺失 → 恢复并重建父目录（恢复分支 mkdir，2026-09-25） ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  fs.rmSync(path.join(t, '.zcode'), { recursive: true, force: true });
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S13 整目录缺失的 managed 被恢复（父目录重建）', R(path.join(t, '.zcode/h.txt')) === 'host v2 777\n', out);
+  check('S13 恢复有报告标记', out.includes('恢复缺失'), out);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/templates/AGENTS.md

@@ -19,7 +19,7 @@
 
 ### 子智能体
 
-公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。
+公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。多工作包编排（自动加载）：跑编排 / plan 执行多工作包时，读 `.agents/workflows/` 编排脚本按机制文档执行——stages 表（依赖分层 / 并行 / 重试 / gate）+ `steps/` 自定义步骤扩展点，见 `.agents/workflows/_TEMPLATE.md`。
 
 ### 门禁与提交
 
@@ -31,7 +31,7 @@
 ### 检索、看板与量化
 
 - 跨语料检索：`node .agents/scripts/kb-search.mjs "<词>"`（workflow 节级定位 + wiki 全文）；活跃流程读 `workflow/INDEX.md`（状态变更后 `node .agents/scripts/gen-workflow-index.mjs` 重生成）。
-- workflow 看板（可选，默认不拉起）：需要时手动跑 `.agents/scripts/ensure-board.ps1`，然后访问 http://127.0.0.1:{{BOARD_PORT}}（只读预警层，非门禁）。
+- workflow 看板（可选，默认不拉起）：需要时手动跑 `node .agents/scripts/ensure-board.mjs`（跨平台，Windows/Linux/macOS 通用），端口从基端口 {{BOARD_PORT}} 起自动上探首个可用（多项目并行不冲突），链接以脚本输出为准（只读预警层，非门禁）。
 - 委派 / 自做结果留痕 `workflow/delegations.md`（聚合 `node .agents/scripts/agg-delegations.cjs`）；命令 / 技能卡壳记 `workflow/papercuts.md`，不当场顺手改。
 
 ### 验证与关单

package/templates/_agents/commands/build.md

@@ -40,6 +40,7 @@ next: .agents/commands/test.md
    - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `node .agents/scripts/kb-search.mjs --scope workflow --module <token> "<关键词>"`——命中 incident 的根因 / 防复发条目列入改动自查
    - 列改动文件清单(读后改 vs 新建)
    - 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
+   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（见 incidents/2026-09-25-wf-runtime 复盘）
    - 标注触达红线(对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）)
 6. 停下,等用户确认改动清单
 
@@ -62,9 +63,28 @@ next: .agents/commands/test.md
 
 - 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
 
+## 改权威源后必跑（薄适配同步防漏）
+
+- 改 `templates/_agents/commands/*.md` 或 `templates/_agents/roles/*.md` 正文后 → 跑 `node bin/flow-kit.mjs sync-hosts --diff` 看正文段漂移 → 用户拍板 → `node bin/flow-kit.mjs sync-hosts --apply` 单向同步（薄适配正文 = 权威源正文，frontmatter 不动）；详见 `.agents/commands/sync-hosts.md`
+- 改 frontmatter（薄适配特化字段如 trae `name: wf-X`）不需同步——apply 只动正文段
+- 改 trae 钩子 / 规则 / 包源其他文件不在本工具范围
+
+## 改 doctor / check-loop 后必跑（三处口径对账）
+
+- 改 `src/doctor.mjs` 加新 § 检查项 → 跑 `node .agents/scripts/gate-checklist.mjs --diff` 看 doctor ↔ check-loop 对照表
+- 改 `.agents/scripts/check-loop.sh` 加新 § 检查项 → 同上
+- 任一处有而另一边无 → 工具报"缺点"，由用户拍板是否补齐（不自动同步，B-b 决策）；详见 `.agents/commands/gate-checklist.md`
+
+## 改包源后必跑（装户面同步一致性）
+
+- 改 `templates/_agents/*` 包源后 → 跑 `node .agents/scripts/source-sync-check.mjs --diff` 看装副本 `.agents/` 是否同步（缺失 / 孤儿 / 漂移三类差异）
+- 漂移说明包源改了装副本未跟；缺失说明新增文件 init 未执行；孤儿说明装副本独有（可能是装户配置，不删）
+- B-b 决策「只报告不修复」；详见 `.agents/commands/source-sync-check.md`
+
 ## 子代理调用约定
 
 - plan 起草、风险判断、改动清单与两道确认门由主智能体负责;仅两道确认后范围明确的工作包可委派 `implementer`,公共接口 / Schema / 依赖 / 安全 / 权限 / 破坏性操作不得委派。
+- 多工作包并行 / 链式推进:编排机制(声明随 plan 草稿一并确认;确认后读 `.agents/workflows/` 按机制文档执行,`steps/` 为项目自定义步骤扩展点);详见 `.agents/workflows/_TEMPLATE.md`。
 - 子智能体返回后,主智能体须检查 diff 与授权文件范围、确认未覆盖既有修改并重跑相关验证;不支持子智能体时 `fallback: main`,验收标准不变。
 
 ## 确认后

package/templates/_agents/commands/design.md

@@ -28,6 +28,7 @@ next: .agents/commands/build.md
    - **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
    - **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
 3. 起草 spec:
+   - **填空工具先跑**：`node .agents/scripts/fill-spec.mjs --level <L1|L2|L3> --topic <主题> --output workflow/specs/<date>-<主题>.md`——输出含 frontmatter 5 字段 + 5 节正文（功能行为/数据流/系统改动/约束遵守映射/风险评估）的草稿；AI 据此填实
    - 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
    - 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
    - 约束映射必须对照根 `AGENTS.md`「Working rules」与改动域目录级 `AGENTS.md`（如有）逐条说明如何满足

package/templates/_agents/commands/gate-checklist.md

@@ -0,0 +1,91 @@
+---
+description: 三处口径一致性检查（doctor §检查项 ↔ check-loop §检查项，显式配对登记表 + 断档/未登记告警）
+stage: helper（横向工具，不占 6 阶段）
+triggers:
+  - "三处口径对账"
+  - "改了 doctor 后跑这个"
+  - "改了 check-loop 后跑这个"
+  - "扫一下口径一致性"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: 用户已确认同步范围（发现断档/未登记后修 doctor / check-loop / 登记表时）
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/build.md（缺点属 build 改 doctor / check-loop 未对账导致的，修复后回 build）
+---
+
+# Gate-Checklist · 三处口径一致性（显式配对登记表）
+
+> `src/doctor.mjs` § 检查项 ↔ `.agents/scripts/check-loop.sh` § 检查项，按脚本内 **PAIRS 登记表**对照。
+> 任何一处加新检查项，另一处不会自动同步——本工具报「未登记」；检查项被删/改号而登记未跟报「断档」。
+> 只报告不修复（B-b 决策）：缺点暴露给用户拍板，本工具不自动同步；exit 恒 0。
+
+## 何时跑
+
+- 改 `src/doctor.mjs` 加新 § 检查项后（同时须登记 PAIRS）
+- 改 `.agents/scripts/check-loop.sh` 加新 § 检查项后（同时须登记 PAIRS）
+- 怀疑两处口径不一致时
+- 不跑：仅改既有检查项的提示文案（不动 § 项与登记表）
+
+## 登记表纪律（契约）
+
+`templates/_agents/scripts/gate-checklist.mjs` 内 **PAIRS** 是配对单源，三选一登记：
+
+| 形态 | 写法 | 含义 |
+|------|------|------|
+| 直接配对 | `{ doctor: 'N', cl: 'M' }` | 同一检查两处实现 |
+| 声明独有 | `{ doctor: 'N', cl: null }` | doctor 装户体检面，无 check-loop 对应（原 intent 拍板只报告不修复） |
+| 经 §7 覆盖 | `{ doctor: '7', cl: 'M' }` | doctor §7 整体运行 check-loop，#M 自动流入 doctor |
+
+- 加新 § 检查项不登记 → 工具报「未登记」（新检查项没对账——核心信号）
+- 删/改检查项不动登记表 → 工具报「断档」
+- 关键词匹配已退役（2026-09-25 registry 重写：实测 18×14 项只匹配 2、28 条噪声缺点，真漏点不可见）
+
+## 怎么跑
+
+```bash
+node .agents/scripts/gate-checklist.mjs --diff   # 人类可读（默认）
+node .agents/scripts/gate-checklist.mjs --json   # 机器可读
+```
+
+输出四段：总览计数 → 对照表（登记表展开）→ 断档（如有）→ 未登记（如有）；全绿时输出「登记完整」。
+
+### 输出示例
+
+```
+▶ flow-kit gate-checklist --diff（显式配对登记表）
+  doctor §检查项: 12  |  check-loop §检查项: 14  |  直接配对 2 + 经 §7 覆盖 12 + 声明独有 9
+  对照表（登记表展开）:
+    ✓ §5 占位符残留 ↔ #2 模板字段占位符残留(YYYY-MM-DD / <主题> 等…)（占位符残留）
+    ● §1 Node 版本（声明独有：Node 版本——装户体检独有）
+    ✓ §7 check-loop ↔ #1 入口文档/spec/plan 同名配对(…（经 §7 整体运行覆盖）
+  ✅ 登记完整（0 断档 / 0 未登记）
+```
+
+### 自验
+
+```bash
+node .agents/scripts/gate-checklist.test.mjs   # 13 场景全过
+npm test                                       # 含 gate-checklist 套件
+```
+
+## 边界（不要做）
+
+- 不要把「登记完整」当作强制门 —— B-b 决策「只报告不修复」：断档/未登记暴露给 follow-up，exit 恒 0
+- 不要改 doctor / check-loop 检查项来消音 —— 登记表才是该改的地方（配对 / 独有 / 经 §7 三选一）
+- 不要扩展到看板告警 —— 看板当前无告警规则（gen-wiki-board.mjs 不做判定），扩展超出范围
+- 不要绕过登记直接改解析正则 —— 解析面只认 doctor `// N.` 节注释与 check-loop `// N.` 项注释（.mjs 头部清单，fallback 旧装户 .sh `# N.`）
+
+## 不在本次同步范围
+
+- `.agents/board/` 看板告警（无告警规则）
+- `wiki/知识沉淀总览.html` 渲染（数据来源是 workflow/INDEX.md 与 wiki 目录，非本工具对照）
+- `flow-kit sync` managed 台账追踪（gate-checklist 不在 managed 范围）
+
+## 相关留痕
+
+- intent（登记表重写）：`workflow/intents/2026-09-25-gate-checklist-registry.md`
+- intent（工具首建）：`workflow/intents/2026-09-25-gate-checklist.md`
+- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（owned 漂移未对账，催生本工具）

package/templates/_agents/commands/maintain.md

@@ -24,7 +24,7 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），链接 http://127.0.0.1:{{BOARD_PORT}} ；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
 
 ### 0. 紧急止血(仍在事故中时)
 

package/templates/_agents/commands/plan.md

@@ -16,11 +16,12 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 powershell -NoProfile -File .agents/scripts/ensure-board.ps1（幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器），链接 http://127.0.0.1:{{BOARD_PORT}} ；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
 
 1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
 2. 否则起草新 intent:
    - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
+   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 5 字段 + 7 节正文（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准）的草稿；AI 据此填实，模板与节标题机器保证不出错
    - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
    - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
    - 按 6 节填写:背景与问题 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线（L1 微改动可省非目标/约束两节，不硬填）

package/templates/_agents/commands/review.md

@@ -43,6 +43,7 @@ next: .agents/commands/build.md（仅 P0 / P1 未清时；清零后经用户确
 - **Create/Update 校验同口径**：Create 已有校验 Update 必须同口径；被引用的标识符字段禁改
 - **查询分页与状态语义**：分页参数范围校验 + 服务层钳制；非法状态与不存在分离(按项目统一错误口径,如 400 / 404)
 - **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
+- **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步 4 宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
 
 ## P2 建议（提醒，不拦合入）
 

package/templates/_agents/commands/source-sync-check.md

@@ -0,0 +1,103 @@
+---
+description: 装户面同步一致性检查（包源 templates/_agents/ vs 装副本 .agents/ 三类差异：缺失 / 孤儿 / 漂移）
+stage: helper（横向工具，不占 6 阶段）
+triggers:
+  - "改了包源同步了吗"
+  - "装了装副本同步了吗"
+  - "扫一下装户面漂移"
+  - "source-sync 跑一下"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: 用户已确认同步范围（发现漂移后修包源或装副本时）
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/build.md（漂移属 build 改包源未同步导致的，修复后回 build）
+---
+
+# Source-Sync-Check · 装户面同步一致性
+
+> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告：缺失 / 孤儿 / 漂移。
+> managed 文件由 `flow-kit sync` 跟踪；owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带（结构级差异）。
+
+## 何时跑
+
+- 改 `templates/_agents/*` 包源后
+- 怀疑装副本未跟包源更新
+- 体检装副本完整性（清理前 / 发版前）
+- 不跑：仅改装副本 `.agents/*`（B-b 决策「只报告」+ 不反向同步）
+
+## 怎么跑
+
+### 默认 `--diff`（仅报告）
+
+```
+node .agents/scripts/source-sync-check.mjs --diff
+node .agents/scripts/source-sync-check.mjs --json                       # 机器可读
+node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>   # 自定义路径
+```
+
+输出三类：
+- **缺失**（missing）——包源有 / 装副本无（如新增文件 init 未执行）
+- **孤儿**（orphan）——包源无 / 装副本有（如历史残留 / 用户本地添加）
+- **漂移**（drift）——两者都有但 sha 不一致（如包源改了装副本未跟）
+
+**排除**：
+- `templates/_agents/cache/`（运行时缓存，与 `flow-kit sync` 既有约定一致）
+- `.agents/kit.json` / `.agents/settings.json`（init 渲染产物，不属双源）
+
+### 输出示例
+
+```
+▶ flow-kit source-sync-check --diff
+  包源 (templates/_agents/) 49 份  |  装副本 (.agents/) 49 份
+  缺失（包源有 / 装副本 无）1：
+    - scripts/source-sync-check.mjs
+  孤儿（包源无 / 装副本 有）1：
+    - hooks/commit-check.config.json
+  漂移（包源装副本都有但 sha 不一致）3：
+    - commands/maintain.md  pkg=3782b695…  tgt=26203f7b…
+    - notes/runtime-env.md  pkg=aedde1ba…  tgt=ad08441e…
+    - scripts/ensure-board.mjs  pkg=e66653b0…  tgt=b6f3cc9b…
+```
+
+### 自验
+
+```
+node .agents/scripts/source-sync-check.test.mjs   # 11 场景全过
+npm test                                            # 含 source-sync-check 套件
+flow-kit doctor                                     # 10/0/0
+```
+
+## 边界（不要做）
+
+- 不要自动化同步（B-b 决策「只报告不修复」——与 `gate-checklist` 同源）
+- 不改 managed 台账跟踪逻辑（`sync.mjs` 不动）
+- 不改 owned 漂移校验（`doctor.mjs` §6.6 不动）
+- 不反向同步——装副本独自有文件（如 hooks/commit-check.config.json）可能是装户配置，不应被删
+- 不检查 4 宿主 `modules/hosts/` 薄适配漂移（那是 `flow-kit sync-hosts` 范围）
+
+## 当前已识别的真实漂点（首次实测，2026-09-25）
+
+- **缺失**：本工具写完后未同步装副本（预期内——随本次 commit 解决）
+- **孤儿**：`.agents/hooks/commit-check.config.json`（装副本独有，疑似装户配置）
+- **漂移**：`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
+
+修复留后续 incident / intent 跟踪（不在本次范围）。
+
+## 与既有工具的关系
+
+| 工具 | 作用域 | 算法 |
+|---|---|---|
+| `flow-kit sync` | managed 文件（kit.json 台账跟踪）| 三态覆盖 + 加新 + 报错缺 |
+| `flow-kit doctor` §6.6 | owned 文件（kit.owned 哈希比对）| 盘面 sha vs 台账哈希 |
+| **`flow-kit source-sync-check`** | **所有文件结构（包源 ↔ 装副本全集）** | **sha 全量比对 + 缺失/孤儿分类** |
+
+三者互补，不重叠。
+
+## 相关留痕
+
+- intent：`workflow/intents/2026-09-25-source-sync-check.md`
+- plan：`workflow/plans/2026-09-25-source-sync-check.md`
+- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（包源改了装副本未同步——本工具预防性体检）

package/templates/_agents/commands/sync-hosts.md

@@ -0,0 +1,79 @@
+---
+description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 + 单向 apply；frontmatter 不动）
+stage: helper（横向工具，不占 6 阶段）
+triggers:
+  - "同步宿主适配层"
+  - "改了角色契约要不要同步"
+  - "扫一下宿主漂移"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: 用户已确认同步范围与策略（仅 apply 大批同主题漂移时委托）
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的，修复后回 build）
+---
+
+# Sync-Hosts · 跨宿主适配层正文段同步
+
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（trae commands 加 `name: wf-X`、opencode/zcode/omp 各自原描述）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+
+## 何时跑
+
+- 改 `templates/_agents/commands/*.md` 正文后（8 个 commands 文件）
+- 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
+- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
+- 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
+
+## 怎么跑
+
+### 默认 `--diff`（仅报告）
+
+```
+node bin/flow-kit.mjs sync-hosts --diff
+node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+```
+
+输出三类：
+- **正文对齐 N 对** — sha 一致，无需处理
+- **正文段漂移 N（权威源 vs 薄适配 sha 不一致）** — `--apply` 同步方向；不区分"权威源改了"或"薄适配手改了"，由用户拍板
+- **⚠️ 权威源声明但薄适配缺失** — `add-host <h>` 接管后跑 `--apply` 才会装（apply 不自动创建）
+- **⚠️ 孤儿薄适配（权威源无对应文件）** — 历史残留或宿主特化，apply 不删
+
+### `--apply` 单向同步
+
+```
+node bin/flow-kit.mjs sync-hosts --apply
+```
+
+按权威源正文覆盖薄适配正文段；薄适配原 frontmatter 保留（trae name: wf-X、opencode 描述、zcode/omp 中文风格各自不动）。apply 不反向同步——薄适配手改了正文也会被覆盖（这是设计选择，避免漂移方向歧义）。
+
+### 自验
+
+```
+npm test                                       # 含 sync-hosts.test.mjs 8 场景
+node bin/flow-kit.mjs doctor                   # 装户跑 §7.x PASS；包源跑 §7.x skipped
+sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已探测分流
+```
+
+## 边界（不要做）
+
+- 不要 `--apply` 反向同步（写权威源）：权威源是真相，薄适配手改会被覆盖——这是设计，apply 前先看 `--diff`
+- 不要删除孤儿薄适配：可能是宿主特化或历史残留，apply 不动
+- 不要改 frontmatter 让 sha 凑齐：frontmatter 是宿主特化字段（trae name: wf-X 等），工具不参与
+- 不要把「避免与权威版本漂移」明文加回去——这是旧契约的指针风格，已被 B-b 正文副本取代
+- 装了新宿主后跑 `--apply`：新宿主目录空白，apply 不会自动创建薄适配（薄适配须经 `add-host <h>` 接管）
+
+## 不在本次同步范围
+
+- trae 钩子（`modules/hosts/trae/hooks/*.cjs`）— 独立演进的工程件
+- trae 规则（`modules/hosts/trae/rules/*.md`）— 同上
+- 包源 .agents/scripts/*.cjs（pre-commit 等钩子）— 同步由 `flow-kit sync` 走 managed 台账负责
+
+## 相关留痕
+
+- 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 包源环境跳过）

package/templates/_agents/commands/test.md

@@ -33,6 +33,7 @@ next: L1 关单结束 ；L2/L3 上 prod 时 → .agents/commands/deploy.md
 项目测试命令                                       # 自动化测试
 项目类型检查命令                                  # 前端类型检查/构建(涉及前端时跑)
 node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1 即先修台账再继续:跑 gen-wiki-board.mjs 补索引/看板;pre-commit 已按增量自动拦,此行用于改完即验)
+node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 owned 漂移 + §6.7 跨宿主薄适配正文漂移(装户环境；包源环境 §6.7 skipped)
 ```
 
 > **环境注记**：本地服务占用构建产物导致编译失败、多会话并行时「谁跑静态门 / 提交谁先停服务」等约定——如有,见项目注记 `.agents/notes/runtime-env.md` §2,跑静态门前先过一眼。
@@ -41,7 +42,7 @@ node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1
 
 任一失败 → 不进 UI 实测,回 `build.md` 修复;失败难复现(偶发/跨层)时先用 `diagnosing-bugs` 技能走诊断循环(红→最小化→假设→插桩→修复→回归),修复仍回 `build.md`。
 
-> **门禁 / 看板 / wiki 脚本改动**(`.agents/scripts/`、`.agents/hooks/`、`.agents/board/`):按改动对象跑对应 fixture 回归,须全绿——闭环门禁 `sh .agents/scripts/check-loop.test.sh`、wiki 生成器 `node .agents/scripts/gen-wiki-board.test.mjs`、提交前 hook 测试(如有);涉及看板告警规则时,用同批 workflow fixture 双跑 `check-loop.sh` 与看板 `/api/board`,断言 hard-block 集合被看板告警覆盖(防口径分叉)。
+> **门禁 / 看板 / wiki 脚本改动**(`.agents/scripts/`、`.agents/hooks/`、`.agents/board/`):按改动对象跑对应 fixture 回归,须全绿——闭环门禁 `node .agents/scripts/check-loop.test.mjs`、wiki 生成器 `node .agents/scripts/gen-wiki-board.test.mjs`、提交前 hook 测试(如有);涉及看板告警规则时,用同批 workflow fixture 双跑 `check-loop`（经 shim 或 .mjs 直跑）与看板 `/api/board`,断言 hard-block 集合被看板告警覆盖(防口径分叉)。
 
 ## 2. 切库冒烟(切换 / 新增目标库后必跑)
 

package/templates/_agents/notes/runtime-env.md

@@ -11,7 +11,7 @@
 
 - API：<端口 / 进程名 / 启动停止命令>
 - 前端：<端口 / 启动命令>
-- workflow 看板：{{BOARD_PORT}}（`node .agents/scripts/workflow-board-server.mjs`，只读）
+- workflow 看板：8933（`node .agents/scripts/workflow-board-server.mjs`，只读）
 
 ## 3. 数据与密钥
 

package/templates/_agents/rule-budgets.txt

@@ -5,4 +5,4 @@
 # 口径：预算比较用「索引 / HEAD 字节」（git cat-file，LF 归一）；禁用工作区 wc -c 核对（CRLF 膨胀）。
 AGENTS.md 7680
 .agents/commands/*.md 8192
-.agents/commands/ 49152
+.agents/commands/ 65536