agentic-flow-kit 0.4.0 → 0.6.0

package/templates/_agents/commands/build.md

@@ -31,7 +31,8 @@ next: .agents/commands/test.md
    - L2/L3 按 4 节填写:任务拆解(每个任务有判据) / 风险评估 / 执行顺序 / 遗留项
    - L1 默认极简两节:改动面(逐条文件+做什么) / 验证方式(一行静态门+按需 UI 实测)；仅多文件多步骤时再加任务拆解/执行顺序
    - 仍须与入口文档同名落盘
-3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件),且相邻同 quote 连跑触发 check-loop 15 并录告警(见 workflow/papercuts.md 2026-09-28)
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
 4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 
 ### 进计划模式列改动
@@ -40,6 +41,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 +64,28 @@ next: .agents/commands/test.md
 
 - 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
 
+## 改权威源后必跑（薄适配同步防漏）
+
+- 改 `templates/_agents/{commands,roles}/*.md` 正文后跑 `node bin/flow-kit.mjs sync-hosts --diff` → 拍板 → `--apply` 单向同步（只动正文段，frontmatter 不动）；口径与边界详见 `.agents/commands/sync-hosts.md`
+
+## 改 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 未执行；孤儿说明装副本独有（可能是装户配置，不删）
+- **新增 managed 类文件须经 init/sync 登记，禁手动双写绕过台账**——手工同时写 `templates/_agents/` 与 `.agents/` 会绕过台账登记，使该文件永远不被 sync 升级（`doctor` 台账覆盖率检查会拦；见 incidents/2026-09-26-managed-ledger-adopt 复盘）
+- 门禁边界（pre-commit 双源一致性）：比较工作树非暂存区——两侧改好、分两笔提交不拦（最终一致即可）；包源删除文件退化为「孤儿」只报告不拦，删包源须手动清理装副本残件（复核 P2-2 声明，2026-09-27 gate-hardening-p2-batch）
+- 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`（如有）逐条说明如何满足
@@ -50,5 +51,6 @@ next: .agents/commands/build.md
 ## 确认后
 
 - spec 状态 draft → approved
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
 - 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 - 进 `next: .agents/commands/build.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)
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 {{BOARD_PORT}}）；不开看板不影响任务流程。
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
 
 ### 0. 紧急止血(仍在事故中时)
 
@@ -86,6 +86,5 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
 
 ## 确认后
 
-- incident 状态 → fixed(三件套全落地)
-- 防复发用例通过后 → closed
+- incident 状态 → fixed(三件套全落地)；防复发用例通过后 → closed——两跳均走确认门 `node .agents/scripts/confirm-doc.mjs <path>`（open→fixed / fixed→closed，无单跳；2026-09-28 起 check-loop 15 对账，AI 不得直改状态）
 - 若需新 intent → 进 `next: .agents/commands/plan.md`

package/templates/_agents/commands/plan.md

@@ -16,11 +16,12 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 
 ## 执行
 
-> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 {{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 微改动可省非目标/约束两节，不硬填）
@@ -28,6 +29,8 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
 
+   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
+
 ## 技能辅助(可选,宿主级 skills)
 
 - 需求模糊、判据写不出时:用 `grilling`/`grill-me` 拷问需求,答完回填 6 节

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. 切库冒烟(切换 / 新增目标库后必跑)
 
@@ -74,7 +75,8 @@ node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1
 - **关单**（日常闭环点，不依赖是否上 prod）:
   - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」，intent → done；同名 spec（若有）仍 approved → done
-  - 修复：防复发验证已落地，incident → closed
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - 修复：防复发验证已落地，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`「自做任务结果表」记一行（修复类不重复记）
 - L1：本阶段结束，不进 deploy

package/templates/_agents/hooks/check-pairing-incremental.sh

@@ -1,16 +1,20 @@
 #!/bin/sh
-# 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan
+# 闭环配对（增量版）：本次暂存的 intents/ incidents/ 入口文档必须已有同名 plan（L2/L3 另须同名 spec）
 # 目的：把 check-loop.sh「配对断裂」hard-block 的发现时机从 pre-push 提前到 commit
 # （papercut 2026-09-15：maintain.md 只写「incident≡intent 免另立 intent」，未把配 plan 写成显式步骤，
-#  按文档字面执行三次 commit 全绿、push 才爆红，只能后补）
-# 口径与 check-loop.sh 对齐：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名；
-# 同 commit 携带 plan 合法（检查的是工作区文件存在，staged 新建 plan 同样命中）。
-# 已知边界：legacy 豁免读的是工作区文件而非暂存 blob——add 后又改工作区时可能误豁免/误拦（逐文件取 blob 的 fork 成本大于收益，接受）。
+#  按文档字面执行三次 commit 全绿、push 才爆红，只能后补；
+#  2026-09-27 audit-gate-hardening 补齐 spec 档——此前只查 plan，L2/L3 缺 spec 仍要拖到 push 才爆红）
+# 口径与 check-loop.sh 对齐：入口文档（intents/ incidents/ 直下 .md）↔ workflow/plans/ 同名，
+# L2/L3 级别另须 workflow/specs/ 同名（check-loop 检查 1 同款分档）；
+# 同 commit 携带 plan/spec 合法（检查的是工作区文件存在，staged 新建同样命中）。
+# 已知边界：legacy 豁免与级别读取均基于工作区文件而非暂存 blob——add 后又改工作区时可能误豁免/误拦（逐文件取 blob 的 fork 成本大于收益，接受）。
 
 cd "$(git rev-parse --show-toplevel)" || exit 1
 
 fail=0
-for f in $(git diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
+# -c core.quotepath=off：quotepath 默认 true 时非 ASCII 路径被引号转义（"workflow/\346..."），
+# ^workflow/ 前缀匹配失配 → 门禁静默跳过——教训与修法同 check-wiki-ledger.sh（2026-09-27 gate-coverage）
+for f in $(git -c core.quotepath=off diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow/(intents|incidents)/[^/]+\.md$' | grep -v '_TEMPLATE\.md$'); do
   # 闭环引擎启用前的回填件带「流程: legacy」豁免配对检查（与 check-loop 同口径）
   if grep -q '^流程: legacy' "$f"; then
     continue
@@ -22,9 +26,18 @@ for f in $(git diff --cached --name-only --diff-filter=ACMR | grep -E '^workflow
     echo "  L1 极简 plan 只需「改动面 + 验证方式」两节（复制 workflow/plans/_TEMPLATE.md）"
     fail=1
   fi
+  lvl=$(sed -n 's/^级别:[[:space:]]*//p' "$f" | head -1)
+  if [ "$lvl" = "L2" ] || [ "$lvl" = "L3" ]; then
+    if [ ! -f "workflow/specs/$base.md" ]; then
+      echo "闭环配对（增量）— BLOCK:"
+      echo "  入口缺同名 spec: $f（级别 $lvl 须三件套，应在 workflow/specs/$base.md）"
+      echo "  与 pre-push check-loop 检查 1 同口径——先起草 spec 走 design.md，再提交"
+      fail=1
+    fi
+  fi
 done
 
 if [ $fail -ne 0 ]; then
-  echo "pre-commit: 入口文档缺同名 plan，提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）" >&2
+  echo "pre-commit: 入口文档配对不全（plan / L2-L3 spec），提交已阻止（与 pre-push check-loop 同口径，发现时机提前到 commit）" >&2
 fi
 exit $fail

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/roles/implementer.md

@@ -1,5 +1,7 @@
 # Implementer
 
+> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：

package/templates/_agents/roles/independent-reviewer.md

@@ -1,5 +1,7 @@
 # Independent Reviewer
 
+> 公共角色契约（本文件）：`.agents/roles/independent-reviewer.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/independent-reviewer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。

package/templates/_agents/roles/ui-verifier.md

@@ -1,5 +1,7 @@
 # UI Verifier
 
+> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（`.opencode/` / `.trae/` / `.zcode/` 下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
 ## 职责
 
 对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。

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

package/templates/_agents/scripts/agg-delegations.cjs

@@ -4,7 +4,7 @@
  * 输出各月指标（一次通过率 / 平均返工次数 / 主兜底占比）、并发扩容门判定、可粘贴的月度快照行。
  * 结果取值：一次通过 | 返工×N | 主兜底 | 返工待修（未闭环，不计入率）。
  * 用法：node .agents/scripts/agg-delegations.cjs [--month=YYYY-MM]（默认输出全部月份 + 全量累计）
- * 门槛定义见 workflow/delegations.md §并发扩容门槛，两处须同步改。
+ * 门槛定义见 workflow/delegations.md §并发扩容门槛（doc 为权威，脚本向文档对齐——2026-09-27 board-kb-p1）。
  */
 'use strict';
 const fs = require('fs');
@@ -88,8 +88,11 @@ function countIncidents() {
   return byMonth;
 }
 
-// 门槛（与 workflow/delegations.md §并发扩容门槛 同步）
-const GATE = { minSample: 20, minPassRate: 0.9, maxAvgRework: 0.3, minDelegated: 5, maxFallbackRate: 0.1 };
+// 门槛（2026-09-27 board-kb-p1 对齐 workflow/delegations.md §并发扩容门槛声明——doc 为权威）：
+//   月度口径项：一次完成率 ≥90% ｜ 月度返工次数 = 0 ｜ 无主兜底信号（=0）（旧「平均返工≤0.3 / 兜底≤10%」为宽松分叉，退役）
+//   样本护栏项（脚本侧统计可信度门槛，非口径分叉）：月样本量 ≥20 ｜ 委派样本 ≥5
+//   连续性：扩容需「本月 + 上一自然月」连续两月月度口径全达标（delegations.md「连续两个月」）
+const GATE = { minSample: 20, minPassRate: 0.9, minDelegated: 5 };
 
 function metrics(rows) {
   // 未知结果（结果列拼错/漏填）单列计数，不混进「待修」——待修=未闭环，未知=记录本身有问题（2026-09-24 口径分离）
@@ -126,29 +129,26 @@ function fmtNum(x) {
   return x == null ? '—' : x.toFixed(2);
 }
 
-function gate(m, incidents) {
+// gateMonth：单月门槛判定（pure，供测试）——口径项 + 样本护栏项分开列
+function gateMonth(m) {
   const items = [];
-  items.push({ no: 1, ok: m.total >= GATE.minSample, desc: `样本量 ${m.total}/${GATE.minSample}` });
-  items.push({
-    no: 2,
-    ok: m.passRate != null && m.passRate >= GATE.minPassRate,
-    desc: `一次通过率 ${fmtRate(m.passRate)}≥90%`,
-  });
-  items.push({
-    no: 3,
-    ok: m.avgRework != null && m.avgRework <= GATE.maxAvgRework,
-    desc: `平均返工 ${fmtNum(m.avgRework)}≤0.3`,
-  });
-  const delegOk = m.delegatedValid >= GATE.minDelegated && m.fallbackRate != null && m.fallbackRate <= GATE.maxFallbackRate;
-  items.push({
-    no: 4,
-    ok: delegOk,
-    desc: `委派样本 ${m.delegatedValid}≥5 且主兜底 ${fmtRate(m.fallbackRate)}≤10%`,
-  });
-  items.push({ no: 5, ok: null, desc: '门禁不失守（人工对照当月 incident 定性）' });
-  const hardOk = items.filter((i) => i.ok !== null).every((i) => i.ok);
-  const bad = items.filter((i) => i.ok === false).map((i) => i.no).join('+');
-  return { items, verdict: hardOk ? '✅（待人工确认门5）' : `❌ 未达标项:${bad}` };
+  items.push({ no: 1, ok: m.total >= GATE.minSample, desc: `样本量 ${m.total}/${GATE.minSample}`, kind: '样本护栏' });
+  items.push({ no: 2, ok: m.passRate != null && m.passRate >= GATE.minPassRate, desc: `一次完成率 ${fmtRate(m.passRate)}≥90%`, kind: '口径' });
+  items.push({ no: 3, ok: m.reworkSum === 0, desc: `月度返工次数 ${m.reworkSum}=0`, kind: '口径' });
+  items.push({ no: 4, ok: m.fallback === 0, desc: `主兜底 ${m.fallback}=0（无主兜底信号）`, kind: '口径' });
+  items.push({ no: 5, ok: m.delegatedValid >= GATE.minDelegated, desc: `委派样本 ${m.delegatedValid}≥5`, kind: '样本护栏' });
+  items.push({ no: 6, ok: null, desc: '门禁不失守（人工对照当月 incident 定性）', kind: '人工' });
+  return { items, monthOk: items.filter((i) => i.ok !== null).every((i) => i.ok) };
+}
+
+// expansionVerdict：连续两个月扩容判定（pure，供测试）——本月与上一自然月 monthOk 均真才「可扩容」；
+// prevMissing = 无上月数据（首月/断档）；items 供未达标项列出
+function expansionVerdict(monthOk, prevOk, prevMissing, items) {
+  if (monthOk && prevOk) return '✅ 连续两月达标（可扩容，待人工确认门6）';
+  if (monthOk && prevMissing) return '⚠️ 本月达标（连续性 1/2——上月无数据）';
+  if (monthOk) return '⚠️ 本月达标（连续性 1/2——上月未达标）';
+  const bad = (items || []).filter((i) => i.ok === false).map((i) => i.no).join('+');
+  return `❌ 未达标（连续性中断）：${bad || '月度口径项未全过'}`;
 }
 
 function main() {
@@ -165,14 +165,18 @@ function main() {
   console.log(`# 量化证据聚合（${argMonth || '全部月份'}） 生成于 ${new Date().toISOString().slice(0, 10)}\n`);
 
   const snapshotRows = [];
+  const monthResults = new Map(); // ym → { monthOk }（连续两月判定用）
   for (const ym of months) {
     const m = metrics(byMonth[ym]);
-    const g = gate(m, incidents[ym] || 0);
+    const { items, monthOk } = gateMonth(m);
+    monthResults.set(ym, monthOk);
+    const prevYm = (() => { const [y, mo] = ym.split('-').map(Number); const d = new Date(Date.UTC(y, mo - 2, 1)); return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`; })();
+    const verdict = expansionVerdict(monthOk, monthResults.get(prevYm), !months.includes(prevYm), items);
     console.log(`## ${ym}`);
     console.log(`  有效任务 ${m.total}（待修 ${m.pending}${m.unknown ? `、未知结果 ${m.unknown}` : ''}）｜一次通过 ${m.pass}（${fmtRate(m.passRate)}）｜返工总次数 ${m.reworkSum}（平均 ${fmtNum(m.avgRework)}）｜主兜底 ${m.fallback}/${m.delegatedValid}（${fmtRate(m.fallbackRate)}）｜incident ${incidents[ym] || 0} 起`);
-    for (const i of g.items) console.log(`  门${i.no} ${i.ok === null ? '[人工]' : i.ok ? '✅' : '❌'} ${i.desc}`);
-    console.log(`  扩容门判定：${g.verdict}\n`);
-    snapshotRows.push(`| ${ym} | ${m.total} | ${fmtRate(m.passRate)} | ${fmtNum(m.avgRework)} | ${fmtRate(m.fallbackRate)} | ${incidents[ym] || 0} | ${g.verdict} | 样本含待修${m.pending}${m.unknown ? `、未知${m.unknown}` : ''} |`);
+    for (const i of items) console.log(`  门${i.no}[${i.kind}] ${i.ok === null ? '[人工]' : i.ok ? '✅' : '❌'} ${i.desc}`);
+    console.log(`  扩容门判定：${verdict}\n`);
+    snapshotRows.push(`| ${ym} | ${m.total} | ${fmtRate(m.passRate)} | ${fmtNum(m.avgRework)} | ${fmtRate(m.fallbackRate)} | ${incidents[ym] || 0} | ${verdict} | 样本含待修${m.pending}${m.unknown ? `、未知${m.unknown}` : ''} |`);
   }
 
   if (!argMonth && rows.length) {
@@ -189,4 +193,9 @@ function main() {
   }
 }
 
-main();
+// isMain 守卫 + 纯函数导出（board-kb-p1：gateMonth / expansionVerdict 供测试 import，import 不执行 main）
+if (require.main === module) {
+  main();
+} else {
+  module.exports = { parseResult, metrics, gateMonth, expansionVerdict, GATE };
+}