agentic-flow-kit 1.7.0 → 1.7.16

package/README.md

@@ -1,14 +1,14 @@
 # agentic-flow-kit
 
-AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套。
+AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套、**多人/多 worktree 台账并发治理**（并集合并 / 分片归并 / 特许修剪）。
 
-**装完即自包含**：引擎文件拷贝进项目（零 npm 运行时依赖，Node ≥ 18 即可跑），clone 后只差 `git config core.hooksPath .githooks`——init 会自动挂好。
+**装完本地可跑**：日常闭环（门禁钩子 / check-loop / fill-* / confirm-doc / kb 检索 / 看板）走项目内 `.agents/scripts/`，零 npm 运行时依赖，Node ≥ 18 即可跑；升级 / 体检 / 装门禁（`sync` / `doctor` / `add-host` / `add-gate`）走 `npx agentic-flow-kit`。clone 后只差 `git config core.hooksPath .githooks`——init 会自动挂好。
 
 ## English
 
-agentic-flow-kit installs a self-contained AI workflow into a repository: stage commands, role contracts, git hooks, and an intent → spec → plan → incident trail. After `init`, the project does not need this package at runtime. Node ≥ 18 is enough.
+agentic-flow-kit installs a project-level AI workflow into a repository: stage commands, role contracts, git hooks, and an intent → spec → plan → incident trail. After `init`, day-to-day loop work (hooks, check-loop, confirm-doc, retrieval) runs from the in-repo `.agents/scripts/` with zero npm runtime dependencies; Node ≥ 18 is enough. Lifecycle operations — `sync` / `doctor` / `add-host` / `add-gate` — go through `npx agentic-flow-kit`.
 
-The product is the hook, not another prompt pack. Five rules always block a bad push: paired docs, checked acceptance, a confirmation ledger, secret scanning, and the managed/owned ledger. Other hygiene checks are warnings, and a fresh install sets `audit: false` so only those five stay in the way. Omit `audit` on an older ledger and the full check set stays on.
+The product is the hook, not another prompt pack. Five blocking surfaces, split across tools: check-loop blocks unpaired docs, unchecked acceptance criteria, missing confirmation trace, and release-time unclosed docs; secret scanning sits in pre-commit; the managed/owned ledger and dual-source drift are checked by `doctor` / `sync`, not by the push gate. Other hygiene checks are warnings, and a fresh install sets `audit: false` so only the blocking set stays in the way. Omit `audit` on an older ledger and the full check set stays on. The Chinese section above is the single source of truth for this split.
 
 Hosts: `zcode`, `opencode`, `trae`, `omp`, `claude`, `cursor`, `codex`. Claude Code loads `.claude/commands` and `.claude/agents`. Cursor loads `.cursor/commands`. Codex reads the repo `AGENTS.md` and `.codex/skills/flow-kit`; the `.codex/commands` files are the same thin forwards for explicit reference.
 
@@ -21,6 +21,7 @@ npx agentic-flow-kit doctor
 
 ```bash
 npx agentic-flow-kit init --stack node --hosts claude
+git add -A && git commit -m "feat: bootstrap——安装 agentic-flow-kit 工作流引擎"   # 先入库装户产物：此刻无活跃入口，泳道门仅 advisory
 # 按 .agents/commands/plan.md 写一份 L1 intent 与同名 plan（状态先保持 draft）
 node .agents/scripts/confirm-doc.mjs workflow/intents/<文件>.md   # 终端里键入「可以」
 # 改代码，git add，然后提交。配对没齐、验收没勾、确认指纹对不上，钩子会拒绝这次提交。
@@ -28,11 +29,27 @@ node .agents/scripts/confirm-doc.mjs workflow/intents/<文件>.md   # 终端里
 
 ## 五条硬规则
 
-新装的 `kit.json` 写 `audit: false` 与 `policyVersion: 2`：check-loop 只阻断配对、验收勾验、确认留痕，外加发版提交树上仍未收口的文档。敏感信息在 pre-commit，双源和台账在 doctor / sync。`audit` 缺省（升级来的旧台账）保持全量卫生警告。本仓库显式 `audit: true`。豁免日期只在 `.agents/scripts/policy.mjs` 的 `policyVersion` 表里改。
+新装的 `kit.json` 写 `audit: false` 与 `policyVersion: 2`：check-loop 只阻断配对、验收勾验、确认留痕，外加发版提交树上仍未收口的文档。敏感信息在 pre-commit，双源和台账在 doctor / sync。`audit` 缺省（升级来的旧台账）保持全量卫生警告；自己装一份 dogfood 时可显式置 `audit: true`。豁免日期只在 `.agents/scripts/policy.mjs` 的 `policyVersion` 表里改。
 
-可选红线用 `add-gate`：`dotnet-ca`、`node-layer`、`py-import`、`generated-readonly`。约定见 `modules/gates/README.md`。
+可选红线用 `add-gate`：`dotnet-ca`、`node-layer`、`py-import`、`generated-readonly`、`test-protect`。约定见 `modules/gates/README.md`。
 
-**关于「确认门」的诚实边界**：确认门是**留痕机制，不是防伪机制**。`confirm-doc.mjs` 把确认事件写进 `.agents/confirmations.jsonl`（append-only，入 git），check-loop 据此对账——但台账是本地可写文件，**刻意手改台账仍可伪造**。门禁的实际作用是把「顺手绕过」抬到「主动伪造」（两者性质不同、可事后对质），而非关闭通道。仓库自身的引擎注释对此有完整声明（见 `.agents/scripts/stage-gates.mjs` 头部信任边界段）。委托代录（`--delegated`）的台账行如实记 `source` 与用户原话供事后对质，永不伪装 TTY 确认。
+**门禁信任档**（`.agents/kit.json` 的 `gateTrust`）：默认 `project` —— gate 安装锚失配只 WARN（装户对门有最终所有权，锚只提供可见性）。多仓或组织场景改成 `org`，失配即 `doctor` FAIL（exit 1），对齐托管策略的组织级强制。缺键或非法值一律回退 `project`，不会因写错而变严。
+
+**待澄清标记**：起草 spec / plan 时不确定的地方照实写一行 `- 待澄清：<你卡在哪>`，不要猜——「我不知道」是负责，猜是失职（与检查 2 的模板占位符语义相反：占位符是忘了填）。起草门不拦（零阻塞），但 `draft→approved` 确认时仍挂着未澄清项会被 `confirm-doc` 拒绝落账。解决后把行首改成 `- 已澄清：`（保留行，留痕曾不清楚过）或删行。
+
+**关于「确认门」的诚实边界**：确认门是**留痕机制，不是防伪机制**。`confirm-doc.mjs` 把确认事件写进 `.agents/confirmations.jsonl`（append-only，入 git），check-loop 据此对账——但台账是本地可写文件，**刻意手改台账仍可伪造**。门禁的实际作用是把「顺手绕过」抬到「主动伪造」（两者性质不同、可事后对质），而非关闭通道。引擎注释对此有完整声明（见包源 `templates/_agents/scripts/stage-gates.mjs` 头部信任边界段；装户径同份在 `.agents/scripts/stage-gates.mjs`）。委托代录（`--delegated`）的台账行如实记 `source` 与用户原话供事后对质，永不伪装 TTY 确认。
+
+**台账并发（三形态，2026-10-12）**：台账是尾部追加形态，天然撞三种**正常协作**。引擎对每种各有机制，且一律按「正常协作不报红、篡改照拦」设计——门禁若因正常协作持续 hard 拦，唯一出路就是 `--no-verify`，那等于门禁自己废掉自己。
+
+| 形态 | 机制 |
+|---|---|
+| 多人/多分支合并冲突 | `.gitattributes` 的 `merge=jsonl-union` → 并集去重，两侧行全保留、无冲突可解（此前人工解的常见错法是「整取一侧」——静默丢掉另一侧的确认行） |
+| 单机多 worktree 并行 append | `confirm-doc --shard` 写 `.agents/confirmations.d/<doc>.jsonl`，各写各的；里程碑跑 `compact-ledgers.mjs --execute` 并回主台账 |
+| 所有者明令删某批文档 | **特许修剪**：同笔提交 `.agents/ledger-prune-manifest.json`（逐行 sha256 + 授权 + 理由），门禁逐行对账放行；无 manifest 的删/改/重排仍全拦 |
+
+哈希链的域是「**同一 doc 的逻辑序**」而非文件物理序（生效日锚，缺键回退旧口径，存量零变化），因此上面三种协作都不打断它；就地改行、删行、插行三类篡改照拦。诚实边界：manifest 是可写文件，**刻意伪造即可让任意删行合法化**——与「台账本地可写」同级，本通道只把「顺手手改」抬到「提交一份可被 git 历史对质的凭据」。
+
+> **存量装户迁移动作（升级后必做）**：`merge=jsonl-union` 属 `.gitattributes`，而该文件是**项目自持（owned）**、`sync` 永不覆盖——升级后**不会自动获得**。需手动在目标仓 `.gitattributes` 补一行 `.agents/*.jsonl merge=jsonl-union`。driver 是本机态配置、不跨机共享，`init` 会自动配；漏配则退化为文本冲突（**不静默丢数据，但需人工解**）。
 
 ## 快速开始
 
@@ -45,6 +62,9 @@ npx agentic-flow-kit init --stack node --hosts zcode,opencode
 # 体检（布局 / git 钩子 / managed 台账 / 索引漂移 / check-loop）
 npx agentic-flow-kit doctor
 
+# 只读校验（包内置 check-loop 引擎跑闭环结构检查；--strict 把 advisory 也判红，--json 机器可读）
+npx agentic-flow-kit validate
+
 # 包出新版后升级（未改动→覆盖；本地已改→跳过并报告，--force 才覆盖；owned 永不触碰）
 npx agentic-flow-kit sync
 
@@ -53,6 +73,30 @@ npx agentic-flow-kit add-host opencode
 npx agentic-flow-kit add-gate dotnet-ca
 ```
 
+## 执行面：route（手动路由）+ run（自动流水线）
+
+装完之后，CLI 不止管装，还管跑。**md 指令与 md 子代理仍装在装户项目里**（`.agents/commands/`、`.agents/roles/`），宿主读它们；执行代码也留在装户 `.agents/scripts/`，包只做**薄壳转发与判定面**——不复制、不改写、不解释装户的正文。
+
+```bash
+# 手动路由的机器面：定级 + 判据清单 + 泳道 + 下一阶段 + 该读哪个 md
+npx agentic-flow-kit route --kind require --level L1 --files "src/a.ts,src/b.ts"
+npx agentic-flow-kit route --files "src/db/migrations/001_init.sql" --json   # 机读面
+
+# 自动流水线：薄壳转发装户 pipeline-run 状态机（参数与退出码原样透传）
+npx agentic-flow-kit run start "给导入功能加审计字段"
+npx agentic-flow-kit run next --delegated "可以"
+```
+
+| 命令 | 干什么 | 谁是单源 |
+|------|--------|----------|
+| `route` | 按改动文件给出建议档位、判据清单、泳道（协作道 / 防御道）、`kind` 对应的入口 md | 判据 = `.agents/scripts/level-criteria.mjs`；泳道 = `.agents/scripts/stage-gates.mjs` 的 `laneOfDoc` |
+| `run` | `start` / `next` / `status` / `watch` / `abort` 五个子命令原样转发 | 状态机 = `.agents/scripts/pipeline-run.mjs`；驱动协议 = `.agents/commands/pipeline-run.md` |
+
+**诚实边界（重要）**：级别是**意图面**的语义判定（「一处定义、多处消费」），机器判不了语义。机器只兜两件它真能兜的事——**就高不就低**（混档取高）与**路径下限**。路径下限登记在 `.agents/level-hints.txt`（装户自持、内容项目私有、`sync` 永不覆盖、**默认空**）；未配置时 `route` 按 L1 起步并提示补配置，**绝不假装判得出**。该清单写错会直接报错退出——写错配置比没配置危险：没配置会提示，写错会误判。
+
+定级纪律最终仍由 lane-surface 触达面门在**提交面**兜底：`route` 漏判语义，钩子照样拦。
+
+
 | 选项 | 说明 |
 |------|------|
 | `--stack` | `dotnet` / `node` / `python` / `go` / `none`（默认 none）——**门禁配置三处**：commit-check 条件编译检查（暂存对应扩展名时 commit 前自动构建）+ **质量检测**（`checks`：lint / 类型检查 / vet 等秒级确定性检查，存在对应配置文件（tsconfig / eslint / ruff / go.mod 等）才启用，没有则自动跳过；测试不放提交门——关单在 test.md 阶段门）、settings.json 自检验命令权限、AGENTS.md「项目适配区」命令预填 |
@@ -67,6 +111,7 @@ init 不问项目名 / 描述：`AGENTS.md` 只生成「AI工作流 + Wiki」两
 
 ```
 .agents/            阶段命令×8 / 角色契约×3 / 门禁钩子 / 引擎脚本（检索·索引·看板·预算·聚合）/ 技能×2 / settings.json / kit.json 台账
+                    + level-criteria.mjs（级别判据机器单源）/ level-hints.txt（项目自持的路径下限清单，默认空）
 .githooks/          pre-commit（通用门禁编排+项目门禁挂载点）/ pre-push（闭环断档）/ commit-msg / post-commit / pre-merge-commit
 workflow/           intents/specs/plans/incidents 模板×4 + README 协议 + 台账三件（delegations/papercuts/regression-checklist）
 wiki/               INDEX 骨架 + 知识沉淀总览 + drafts-archive
@@ -76,6 +121,32 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 
 **两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
 
+## CI 远端门与离线安装
+
+**CI 远端门**：init 已把 `.github/workflows/kit-ci.yml` 写进装户仓（GitHub Actions：checkout 后复跑 `node .agents/scripts/verify.mjs`——测试【有根 package.json 才跑】+ 闭环校验，任一非零即红）。本地 git 钩子可被 `--no-verify` 绕过，远端门兜底；该文件归装户自持（owned），`flow-kit sync` 永不覆盖，非 GitHub 装户可删。其他 CI（GitLab / Jenkins / Azure DevOps…）等价接入 = 同一入口命令 + 服务端分支策略：
+
+```bash
+node .agents/scripts/verify.mjs                    # 远端门本体（工程在子目录时加 --test-cmd "<项目测试命令>"）
+npx agentic-flow-kit validate --strict --json      # 可选加一道：包内置引擎只读结构校验（warning 也判红，stdout 机器可读）
+```
+
+真正的「门」在服务端分支保护（Settings → Branches：要求 PR + 状态检查绿才可合并）——该配置带不进仓库文件，一次性人工动作，机器不校验。
+
+**离线 / 内网安装**：本包零运行时依赖（package.json 无 `dependencies`），tarball 自包含，离线装机不拖依赖树：
+
+```bash
+# 外网机取包（或从 npm 镜像站直接下载 tgz）
+npm pack agentic-flow-kit@<版本>                   # 产出 agentic-flow-kit-<版本>.tgz
+
+# 内网机安装（二选一）
+npm install -g ./agentic-flow-kit-<版本>.tgz       # 全局：之后直接用 flow-kit 命令
+npm install ./agentic-flow-kit-<版本>.tgz          # 项目内：之后用 npx flow-kit init
+
+# 批量内网：tgz publish 进内网 registry（verdaccio / nexus…），之后照常 npx agentic-flow-kit init
+```
+
+`npx <tgz 路径>` 直跑不经安装在部分 npm 版本有子进程 stdio 不回显的问题（实测 exit 0 但无输出），离线场景请走上述安装后调用。
+
 **升级语义（sync）**：managed 文件三方比对（台账 sha / 磁盘 sha / 新版渲染 sha）——未改动 → 直接覆盖新版；本地已改 → 跳过并报告（`--force` 才覆盖，git diff 自查差异；跳过件的台账保持包侧基线，后续每次 sync 持续报告，不会在下次升级被静默覆盖——消除报告的办法：`--force` 覆盖，或把本地内容改回与新版一致）；改动恰好等于新版 → 视为已最新。包内新增文件自动安装；包内已删文件仅报告不删盘；缺失的 managed 文件自动恢复。INDEX / wiki 看板等生成器目标不比对 sha，收尾重跑生成器走锚点重写。门禁模块（add-gate 装入）归项目所有，sync 永不覆盖。add-host 对已存在的宿主文件保守跳过且不入台账——后续 sync 不升级（仅报告「已存在未入台账」），要纳入包管理用 `--force` 覆盖。owned 件归项目所有、sync 永不覆盖；其台账哈希仅记账不约束，sync 每次按盘面自愈刷新（手改后无须手工对账），add-gate 接线 local-pre-commit 后同步刷新其记账。
 
 ## 设计原则
@@ -90,10 +161,11 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 
 **能力清单的单一真相源是 `CHANGELOG.md`**——每个已发布版本带什么、为什么这么带，都在那里。本节只讲当前语义，不重复枚举版本特性（此前列举导致 README 与实际发布内容长期漂移，2026-10-08 已收敛到单源）。
 
-当前语义三点：
+当前语义四点：
 
 - **门禁面**：check-loop 20 项检查 + `.githooks/` 五个钩子（pre-commit / pre-push / commit-msg / post-commit / pre-merge-commit），门禁逻辑不依赖 agent 客户端自觉。
-- **闭环面**：intents → specs → plans → incidents 四态文档链 + 确认台账（`.agents/confirmations.jsonl`）+ 逐阶段前置门（起草门 / 确认门 / done 前置门）。
+- **闭环面**：intents → specs → plans → incidents 四态文档链 + 确认台账（`.agents/confirmations.jsonl`）+ 逐阶段前置门（起草门 / 确认门 / done 前置门）+ **台账并发三形态**（并集合并 / 分片写入与 compact 归并 / 特许修剪）与按 doc 逻辑序的哈希链（见上文「台账并发」段）。
 - **观测面**：`workflow/INDEX.md`（检索索引）、`workflow/DASHBOARD.md`（红绿灯仪表盘）、`workflow/metrics.md`（月度快照）——**观测面非门禁**，红灯是「看」的不是「拦」的。
+- **执行面**：`route`（手动路由的机器面：定级 + 泳道 + 下一阶段 + 入口 md）与 `run`（自动流水线薄壳转发装户状态机）；判据单源在装户 `.agents/scripts/level-criteria.mjs`，md 改为引用它而非承载判据散文（见上文「执行面」段）。
 
 版本号与已发布能力看 `package.json` 的 `version` 与 `CHANGELOG.md`；仓库当前工作流实况看 `workflow/INDEX.md`。

package/modules/gates/README.md

@@ -20,5 +20,6 @@
 | `node-layer` | `src/` 引用 `tests/`、`test/`、`__tests__/` |
 | `py-import` | 业务 `.py` 引用 `tests` / `test` 包 |
 | `generated-readonly` | 手改 `GENERATED:BEGIN` 与 `GENERATED:END` 之间的行 |
+| `test-protect` | fix/调试提交里测试文件与被测代码同框改动（豁免：`FLOW_KIT_ALLOW_TEST_EDIT=1`） |
 
 项目自己的红线复制其中一个目录，改判断，再用 `add-gate` 装上。

package/modules/gates/test-protect/README.md

@@ -0,0 +1,23 @@
+# test-protect
+
+暂存 diff 若同时包含「测试文件」与「非测试文件」（即测试与代码同框改动），提交失败。
+
+fix/调试任务中，测试是「bug 已修」的证据；证据与结论同一次改动 = 自证，闭环失去意义。此门禁把
+「fix 不得改测试」从提示语变成机器红线，不依赖 agent 客户端自觉。
+
+```sh
+npx agentic-flow-kit add-gate test-protect
+```
+
+**测试文件识别**（脚本头部 CONFIG 可按项目扩展）：
+
+- 目录面：`tests/`、`__tests__/`、`test/`、`spec/`（任意层级）
+- 文件面：`*.test.*`、`*.spec.*`、`_test_*.py`（python pytest 风格）
+
+**豁免**（不是漏洞，是显式语义）：
+
+- 纯测试提交（只改测试文件，无代码同框）——新增/修正测试本身合法。
+- 显式声明 `FLOW_KIT_ALLOW_TEST_EDIT=1 git commit`——对应 plan 中显式标注「本次需同步演进测试」
+  （测试先行 / 行为断言变更）。门禁只判暂存面事实，语义归显式声明，不读任务元数据。
+
+**不拦截**：merge 提交无暂存 diff；工作区未暂存改动（提交面之外）。

package/modules/gates/test-protect/check-test-protect.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// test-protect — 防 agent 自证清白时弱化测试（2026-10-10 调研 P1 test-protect）。
+// 语义：fix/调试任务中，同一提交不得既改被测代码又改它的测试文件——测试是「bug 已修」的证据，
+//       证据与结论同一次改动 = 自证，闭环失去意义（Anthropic playbook Stage 4：fix 任务禁止改测试文件）。
+// 判定范围：本次提交的暂存 diff（git diff --cached --name-only），只拦「测试文件」与「非测试文件」同框出现。
+// 豁免：
+//   - 显式声明 `FLOW_KIT_ALLOW_TEST_EDIT=1 git commit`（对应 plan 中显式标注「本次需同步改测试」——测试先行、行为断言变更属于合法测试演进）。
+//   - 纯测试提交（只改测试文件，无被测代码同框）——新增/修正测试本身合法。
+//   - 测试文件自身之间的改动（如 fixture、helper 互改）。
+// 设计（对照调研 P1）：独立 add-gate 模块，不进 check-loop 核心检查面（20 项纪律）；pre-commit 挂载点走 local-pre-commit，
+//       不依赖 agent 客户端自觉。本脚本不读任务元数据（plan 状态 / frontmatter）——门禁只判暂存面事实，语义归环境变量显式声明。
+// 实现零依赖、纯 Node ≥18。
+
+import { spawnSync } from 'node:child_process';
+
+// 测试文件识别：常见测试目录/文件命名。装户可按项目在脚本头部 CONFIG 扩展。
+// 目录面：tests/、__tests__/、test/、spec/（仓库根或任意层级）；文件面：*.test.*、*.spec.*、_test.*（python pytest 风格）。
+const TEST_DIR_RE = /(^|\/)(tests?|__tests__|spec|test)\//i;
+const TEST_FILE_RE = /\.(test|spec)\.[^.]+$/i;
+const PYTEST_FILE_RE = /(^|\/)_?test_[^/]+\.py$/i;
+
+function isTestFile(rel) {
+  const n = rel.replace(/\\/g, '/');
+  if (TEST_DIR_RE.test(n)) return true;
+  if (TEST_FILE_RE.test(n)) return true;
+  if (PYTEST_FILE_RE.test(n)) return true;
+  return false;
+}
+
+function git(args, cwd) {
+  const p = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return { exit: p.status ?? 1, stdout: p.stdout || '', stderr: p.stderr || '' };
+}
+
+function main() {
+  const root = process.env.FLOW_KIT_GIT_ROOT || process.cwd();
+  // 只判暂存 diff（提交面）；工作区未暂存改动不拦（与 generated-readonly / node-layer 同口径：暂存面即提交意图）
+  const r = git(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], root);
+  if (r.exit !== 0) {
+    console.error('❌ test-protect：git diff --cached 失败（' + (r.stderr.trim() || '未知错误') + '）');
+    process.exit(1);
+  }
+  const files = r.stdout.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+  if (!files.length) return; // 无暂存改动（如 merge 提交）不拦
+
+  const tests = files.filter(isTestFile);
+  const nonTests = files.filter((f) => !isTestFile(f));
+  if (!tests.length || !nonTests.length) return; // 纯测试提交 / 纯代码提交都合法
+
+  if (process.env.FLOW_KIT_ALLOW_TEST_EDIT === '1') {
+    console.log('ℹ️  test-protect：FLOW_KIT_ALLOW_TEST_EDIT=1 显式放行（测试与代码同框改动）');
+    return;
+  }
+
+  const sample = tests.slice(0, 5).join('、') + (tests.length > 5 ? ` 等 ${tests.length} 个` : '');
+  const codeSample = nonTests.slice(0, 3).join('、') + (nonTests.length > 3 ? ` 等 ${nonTests.length} 个` : '');
+  console.error(`❌ test-protect：提交同时改动测试与代码——「测试文件」${sample} 与「非测试文件」${codeSample} 同框。`);
+  console.error('   fix/调试任务中，测试是 bug 已修的证据；证据与结论同一次改动 = 自证，闭环失去意义。');
+  console.error('   若本提交确实需要同步演进测试（测试先行 / 行为断言变更），显式声明后重试：');
+  console.error('     FLOW_KIT_ALLOW_TEST_EDIT=1 git commit');
+  process.exit(1);
+}
+
+main();

package/modules/gates/test-protect/local-pre-commit.line

@@ -0,0 +1 @@
+node .agents/hooks/check-test-protect.mjs

package/modules/hosts/README.md

@@ -0,0 +1,57 @@
+# 宿主适配层
+
+七个宿主的薄适配层。`flow-kit init --hosts <列表>` / `flow-kit add-host <宿主>` 把对应目录铺进装户仓，
+`sync` 随包升级。权威源是 `templates/_agents/{commands,roles}/*.md`，本目录是**纯转发薄层**——
+换宿主不换流程。
+
+## 约定
+
+每个宿主目录两子层：
+
+| 层 | 文件 | 说明 |
+|---|---|---|
+| `agents/` | `<角色>.md` | 角色契约薄适配（全宿主无前缀，文件名 = 权威源文件名） |
+| `commands/` | `<prefix><命令>.md` | 命令层薄适配，文件名统一带宿主前缀（见下），避免裸占宿主顶层命名空间 |
+
+`commandPrefix`（`src/profiles.mjs#HOSTS` 单源）：opencode / trae / claude / cursor / codex 用 `wf-`；
+zcode / omp 无该字段——只有角色层适配，不参与 commands 权威源映射。
+
+## 现有宿主
+
+| 宿主 | 装户目录 | commands 层 | 宿主怎么读 |
+|---|---|---|---|
+| `zcode` | `.zcode/` | 无（仅角色） | `.zcode/agents/*.md` |
+| `opencode` | `.opencode/` | `wf-*` | `.opencode/{agents,commands}/*.md` |
+| `trae` | `.trae/` | `wf-*` | `.trae/{agents,commands}/*.md` |
+| `omp` | `.omp/` | 无（仅角色） | `.omp/agents/*.md` |
+| `claude` | `.claude/` | `wf-*` | `.claude/commands` + `.claude/agents` |
+| `cursor` | `.cursor/` | `wf-*` | `.cursor/commands` |
+| `codex` | `.codex/` | `wf-*` | 仓库根 `AGENTS.md` + `.codex/skills/`；`.codex/commands` 是同形薄转发，供显式引用 |
+
+> codex 另有 `skills/` 子层（宿主级技能辅助），见 `modules/hosts/codex/skills/`。
+
+七个宿主一律入库（2026-10-05 起撤销 localOnly）——换宿主不丢文件、CI 克隆面一致。zcode 的会话级
+液态草稿（`.zcode/drafts/`、`.zcode/plans/`）是本机态、不该入库，init 不自动写这条规则，装户自行加进
+`.gitignore`。
+
+## 对账
+
+权威源改一处，要同步到 N 份薄适配——人工 grep 易漏：
+
+```bash
+flow-kit sync-hosts --diff     # 权威源 vs 薄适配漂移报告（默认，不改盘面）
+flow-kit sync-hosts --apply    # 单向同步：权威源 → 薄适配（不反向，避免污染权威源）
+```
+
+包源仓（含 `templates/_agents` + `modules/hosts`）与装户仓（含 `.agents`）两种布局都可用——
+同一命令两处口径一致。装户侧等价体检在 `flow-kit doctor`（跨宿主薄适配正文段漂移校验）。
+
+## 加一个新宿主
+
+1. 在 `src/profiles.mjs#HOSTS` 注册：`dir`（装户目录名，带点）、`commandPrefix`（有命令层才填）。
+2. 建 `modules/hosts/<宿主>/`：`agents/*.md` 三角色薄适配（从现有宿主拷一份改 frontmatter/调用约定）；
+   有命令层再加 `commands/<prefix>*.md`。
+3. 权威源（`templates/_agents/{commands,roles}/`）不动——薄适配只转发，不复刻判据。
+4. 跑 `flow-kit sync-hosts --diff` 自查新增薄适配与权威源对齐；`npm test`（含 sync-hosts 套件与
+   doctor 跨宿主校验回归）。
+5. README「现有宿主」表与 `cli.mjs` HELP 的宿主清单随动。

package/modules/hosts/claude/commands/wf-build.md

@@ -12,7 +12,7 @@ description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码
 
 起草 intent / spec / plan 任一件后，**在输出草稿全文前先给三件要点总览**（各一件：目标 / 关键取舍 /
 验收判据 diff，合计 ≤12 行）——用户一次看整体再逐件拍板，省三次盲确认的上下文切换。
-确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录、禁复用同句）。本阶段总览侧重：plan 任务拆解与两道确认门位置。
+确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录；摘要可复用——分辨力由 scope+指纹承担，2026-10-09 起）。本阶段总览侧重：plan 任务拆解与两道确认门位置。
 
 ## 1. 执行
 
@@ -23,7 +23,7 @@ description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码
    - 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
    - L2/L3 按 4 节填写:改动方案 / 任务拆解(每个任务有判据) / 执行顺序 / 验证计划（与 fill-plan.mjs 单源一致）
    - L1 使用 Quick-Plan 极简三节:改动方案 / 约束与风险(原 Spec 核心) / 验证计划；多文件多步骤时可补任务拆解/执行顺序
-3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28。
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件代录**:`--delegated "<授权摘要>"` 每件单独一次——摘要为人类可读留痕,复用同句不削弱判据(分辨力由落账自动记录的改动面 `scope{files,sha256}` 与文档指纹承担,2026-10-09 起)。
    **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 一次一份多份并录被拒 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)。
 
@@ -33,7 +33,7 @@ description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码
    - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `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 复盘）
+   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（仅包源/dogfood 双形态仓适用；纯装户仓 owned 即项目自有文件，无此步）
    - 标注触达红线(对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）)
 6. 停下,等用户确认改动清单。
 
@@ -56,32 +56,13 @@ description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码
 
 - 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
 
-## 4. 改权威源后必跑（薄适配同步防漏）
-
-- 改 `templates/_agents/{commands,roles}/*.md` 正文后跑 `node bin/flow-kit.mjs sync-hosts --diff` → 拍板 → `--apply` 单向同步（只动正文段，frontmatter 不动）；口径与边界详见 `.agents/commands/sync-hosts.md`
-- 改根 `AGENTS.md`（owned 常驻面）后跑 `node .agents/scripts/edit-face-check.mjs`——工作树面快检（阶段索引/引用/预算 advisory），别等提交门才发觉砍坏（2026-10-09 B2）
-
-## 5. 改 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`
-
-## 6. 改包源后必跑（装户面同步一致性）
-
-- 改 `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`
-
-## 7. 子代理调用约定
+## 4. 子代理调用约定
 
 - plan 起草、风险判断、改动清单与两道确认门由主智能体负责;仅两道确认后范围明确的工作包可委派 `implementer`,公共接口 / Schema / 依赖 / 安全 / 权限 / 破坏性操作不得委派。
 - 多工作包并行 / 链式推进:编排机制(声明随 plan 草稿一并确认;确认后读 `.agents/workflows/` 按机制文档执行,`steps/` 为项目自定义步骤扩展点);详见 `.agents/workflows/_TEMPLATE.md`。
 - 子智能体返回后,主智能体须检查 diff 与授权文件范围、确认未覆盖既有修改并重跑相关验证;不支持子智能体时 `fallback: main`,验收标准不变。
 
-## 8. 确认后
+## 5. 确认后
 
 - plan 状态 → done（实现完成；intent / spec 关单在 test）
 - commit：L1+ 入口文档 / spec / plan 随代码同一提交（Conventional Commits 中文 feat/fix/refactor/perf）；docs 豁免与 bootstrap 可单独 `docs(*)`

package/modules/hosts/claude/commands/wf-deploy.md

@@ -41,6 +41,7 @@ description: Deploy 阶段:prod 上线清单(静态门 + 配对检查 + 回归 +
 ## 6. 上线后观察(用户观察,Maintain 阶段接手)
 
 - 观察期:上线后 24h;由用户观察错误率 / 延迟 / 关键业务流(无监控时人工看)
+- 异常判据(观察期退出规则):项目口径填 `workflow/regression-checklist.md`——无监控时的最低判据:错误日志 / 异常告警 / 关键业务流失败**任一出现即触发 §5 回滚预案,不等 24h**;无异常满 24h 方可闭环
 - 闭环宣告:用户确认无异常后才算闭环;AI 不得自行宣告
 - 异常回落:超阈值 → 生成 `workflow/incidents/YYYY-MM-DD-<主题>.md`,进 `maintain.md`(止血方案用户拍板,见 maintain.md §0)
 - 事故响应:单用途账号 + 最小权限;不得跨智能体协作推送修复(参考 Anthropic 教训)

package/modules/hosts/claude/commands/wf-design.md

@@ -10,15 +10,16 @@ description: Design 阶段:起 spec(L2/L3 强制,L1 可省略)
 
 起草 intent / spec / plan 任一件后，**在输出草稿全文前先给三件要点总览**（各一件：目标 / 关键取舍 /
 验收判据 diff，合计 ≤12 行）——用户一次看整体再逐件拍板，省三次盲确认的上下文切换。
-确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录、禁复用同句）。本阶段总览侧重：spec 方案取舍与 L3 复核安排。
+确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录；摘要可复用——分辨力由 scope+指纹承担，2026-10-09 起）。本阶段总览侧重：spec 方案取舍与 L3 复核安排。
 
 ## 1. 执行
 
 1. 确认同名入口文档已批准：新需求为 approved intent，修复为已确认的 incident 草稿；否则拒绝，分别回 `plan.md` / `maintain.md`（2026-09-30 起机器强制：fill-spec / confirm-doc 对前置未过直接拒绝 exit 2、不落盘不记账）。
-2. 级别判断(对照 AGENTS.md 第 3 条):
-   - **L1**(实现级改动,未命中 L2/L3)→ 走快车道,省略 spec,直接跳 `next: build.md` 起草 Quick-Plan
-   - **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
-   - **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
+2. 级别判断(对照 AGENTS.md 第 3 条;判据单源 = `.agents/scripts/level-criteria.mjs`，**本文件只承载流程映射，不复述判据闭集**):
+   - **L1**（未命中 L2/L3）→ 快车道：省略 spec，直接跳 `next: build.md` 起草 Quick-Plan
+   - **L2**（触达面闭集见单源 `L2_SURFACES`）→ 必须有 spec
+   - **L3**（结构面闭集见单源 `L3_SURFACES`）→ 必须有 spec + **新会话独立复核**
+   - 判哪一档：逐条对照单源的 `L2_SURFACES` / `L3_SURFACES` / `L1_NEGATIVES`，不要凭记忆——判据只读单源一处
 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`(与入口文档同名)
@@ -43,6 +44,6 @@ description: Design 阶段:起 spec(L2/L3 强制,L1 可省略)
 ## 4. 确认后
 
 - spec 状态 draft → approved
-- **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件调用+逐件原话 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
+- **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件代录（摘要可复用——分辨力由 scope+指纹承担）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 - 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 - 进 `next: .agents/commands/build.md`

package/modules/hosts/claude/commands/wf-gate-checklist.md

@@ -74,6 +74,4 @@ npm test                                       # 含 gate-checklist 套件
 
 ## 6. 相关留痕
 
-- 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 漂移未对账，催生本工具）
+- 立法出处：2026-09-25（登记表重写 + 工具首建；父事件 = owned 漂移未对账，催生本工具）——留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径

package/modules/hosts/claude/commands/wf-new-task.md

@@ -20,7 +20,21 @@ description: AI-Native 闭环总入口:6 阶段指令索引(Plan→Design→Buil
 
 ## 2. 风险定级(第 0 步,先定级再路由)
 
-动工前先按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
+**第 0 步先取机器面下界(必跑,不是可选提示)**:
+
+```bash
+flow-kit route --files <预计改动面…> --kind require|fix|verify|review|deploy
+```
+
+- **不给 `--files` 就拿不到路径下限**——机器面此时只能按 L1 起步并在降级栏点名,等于白跑;
+  故定级前先把**预计改动面**列出来(不必精确到最终 diff,给到目录/文件前缀即可)。
+- 跑完**再**按 §4 逐条语义判级:机器只给「就高不就低 + 路径下限」,「一处定义、多处消费」仍要你判。
+- **确实跳过**时必须写明理由(入口文档备注或当场告知用户)——判低的后果由两道门兜:
+  起草面 `check-lane-surface` 命中路径下限无合格入口即拦,提交面同门再拦一次。
+  **诚实边界**:机器**无法**发现你没跑 route——定级发生在改动面确定之前,没有可比对的记录面,
+  详见 [ARCHITECTURE §5](../ARCHITECTURE.md) 与 CHANGELOG 1.7.16 B3 条。
+
+动工前按下表定风险级 L0-L3(就高不就低;判据细则见下节「级别判断」),级别即风险级,决定走哪条泳道——确认放事前,还是审计补事后:
 
 | 泳道 | 级别 | 确认与审计口径 |
 |------|------|---------------|
@@ -33,6 +47,10 @@ description: AI-Native 闭环总入口:6 阶段指令索引(Plan→Design→Buil
 
 ## 3. 路由判断
 
+<!-- route-kinds: require=plan.md | fix=maintain.md | verify=test.md | review=review.md | deploy=deploy.md -->
+<!-- ↑ 本行是 kind→入口指令的**机器单源**：`flow-kit route` 读它得出「该读哪个 md」，不再在包内自带一份映射。
+     增删 kind 或改入口文件名只改这一行（判据单源 level-criteria.mjs 的纪律同源）。 -->
+
 - **自动化驱动（并列入口,可选）**:一句话全程走 [pipeline-run.md](pipeline-run.md)——状态机驱动+工单协议+原话代录,与下述手动路由二选一,同一任务不混用
 - **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
 - **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
@@ -45,28 +63,31 @@ description: AI-Native 闭环总入口:6 阶段指令索引(Plan→Design→Buil
 
 ## 4. 级别判断(AGENTS.md 第 3 条)
 
-| 级别 | 改什么 | 流程 |
-|------|--------|------|
-| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
-| L1 | **实现级改动**(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行；无确认来源只迁移不落账 |
-| L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
-| L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
-
-> 级别判定同上表"改什么"列;混合改动按最高档定级。
-
-**L2 触达面**(闭集,命中任一即 L2;本体不改但改其输入域 / 调用点校验同样命中):
-
-1. **编码权威**:项目内「一处生成、多处消费」的编码 / 命名 / 取号规则(编码模板、序列发生器、命名空间与去重约束——具体清单按项目 AGENTS.md)
-2. **共享契约**:跨模块共享的基类 / DTO 形状、跨模块公共接口签名
-3. **既有接口语义**:既有参数或端点的行为变化(由失效变生效、默认值或钳制口径改变)
-4. **全局横切口径**:错误响应出口、分页与校验口径、聚合投影键
+> **判据单源 = [`.agents/scripts/level-criteria.mjs`](../scripts/level-criteria.mjs)**,本节**不复述判据**。
+> 要看判据全文,或要机器可判的部分(路径下限 / 就高不就低 / 混档取高),直接:
+>
+> ```bash
+> flow-kit route --files <改动文件…>      # 定级 + 下一阶段 + 该读哪个 md
+> ```
+>
+> 单源导出:`LEVELS` `LEVEL_MEANING`(档位语义) / `L2_SURFACES`(四类触达面闭集) / `L3_SURFACES`(结构面) /
+> `L1_NEGATIVES`(判低红线) / `SELF_CHECK`(自查句) / `assessLevel` `hintLevelFor` `parseLevelHints` `routeAdvice`。
+>
+> 路径下限清单(装户 owned,默认空):`.agents/level-hints.txt`,每行 `L2 <ERE>` / `L3 <ERE>`,登记「哪些路径一碰就至少是此档」。
 
-> **负例(落 L1)**:纯页面表现 / 文案 / 布局 / 交互实现;纯新增端点或参数且既有行为不变;单模块内部重构且无对外契约变化。
-> **自查句**:能否列出 ≥2 个受影响的消费方(模块 / 端点 / 页面)?能 → L2。
-> 先例:本仓 `workflow/specs/`、`workflow/intents/` 下同类历史(kb 检索主题词)。
+**本表只承载流程**(「改什么」判据以单源为准,别在本表增删判据):
 
-> **L1 是默认档**:红线全不勾即 L1,无需正列举——判级只回答「是否命中 L2 四类或 L3 结构面」。
-> **L3 的「DI 链」按组合根与运行时管线理解**:DI 注册、中间件/认证管线、服务构造器依赖变更(先例:本仓 workflow/ 留痕中无 schema 变更仍定 L3 的同类历史)。
+| 级别 | 单源语义(摘要) | 流程 |
+|------|-----------------|------|
+| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
+| L1 | 实现级改动(未命中 L2/L3) | 快车道:液态草稿(.zcode/drafts) → 实现 → 固化(`solidify-task.mjs`)——用户确认后带 `--delegated "<原话>"` 执行;无确认来源只迁移不落账 |
+| L2 | 规则 / 契约(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
+| L3 | 数据与运行时结构(结构面闭集见单源 `L3_SURFACES`) | 同 L2 + spec 新会话独立复核 |
+
+> 混合改动按最高档定级(就高不就低);**L1 是默认档**——判级只回答「是否命中单源 `L2_SURFACES` 或
+> `L3_SURFACES`」,负例(`L1_NEGATIVES`)命中即不得升档;自查句:`SELF_CHECK`。
+> 机器兜得住的只有「就高不就低」与路径下限;「一处定义、多处消费」是**语义**判定,由你按单源逐条判,
+> 漏判由 lane-surface 触达面门在提交面兜。先例:`workflow/specs/`、`workflow/intents/` 下同类历史(kb 检索主题词)。
 
 ## 5. intent 豁免(避免小改动也走完整闭环)
 

package/modules/hosts/claude/commands/wf-plan.md

@@ -20,7 +20,7 @@ description: Plan 阶段:立 intent(需求来源 / 目标 / 约束 / 触达红
    - 红线勾选对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填。
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认。
-   **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件调用+逐件原话 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
+   **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件代录（摘要可复用——分辨力由 scope+指纹承担）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 
 ## 2. 技能辅助(可选,宿主级 skills)
 

package/modules/hosts/claude/commands/wf-review.md

@@ -32,7 +32,7 @@ description: 代码评审标准（按风险分级：机器兜底 + AI 自查出
 - **Create/Update 校验同口径**：Create 已有校验 Update 必须同口径；被引用的标识符字段禁改
 - **查询分页与状态语义**：分页参数范围校验 + 服务层钳制；非法状态与不存在分离(按项目统一错误口径,如 400 / 404)
 - **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
-- **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步注册表内全部宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
+- **跨宿主薄适配正文漂移**：包源仓改 `templates/_agents/{commands,roles}/*.md` 后跑 `flow-kit sync-hosts --apply`，单向同步 `modules/hosts/<h>/{agents,commands}/*.md`。装户由 `flow-kit doctor` §6.7 检查（包源环境跳过）；装户刷新宿主文件用 `flow-kit add-host <宿主> --force`（`sync` 不更新宿主适配，`sync-hosts` 不在装户根运行）
 
 ## 3. P2 建议（提醒，不拦合入）
 

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

@@ -6,27 +6,22 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 
 # Sync-Hosts · 跨宿主适配层正文段同步
 
-> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
-> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）；**修漂移用同一条命令**
-> `flow-kit sync-hosts --apply`——2026-10-07 起按**目标根**自动判布局（含 `templates/_agents` + `modules/hosts` → 包源：
-> 比 `templates/_agents` ↔ `modules/hosts/<宿主键>/`；含 `.agents` → 装户：比 `.agents` ↔ 项目根下 `<宿主点目录>/`），
-> 目标根取 `--dir <目录>` > 当前目录。
+> 本命令只在包源仓运行（需要 `templates/_agents` 与 `modules/hosts`）。改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
+> 装户的宿主文件由 `init` / `add-host` 写入。装户漂移由 `flow-kit doctor` §6.7 报告（包源环境跳过）；刷新用 `flow-kit add-host <宿主> --force`。`flow-kit sync` 不更新宿主适配。
 
 ## 1. 何时跑
 
 - 改 `templates/_agents/commands/*.md` 正文后（11 个 commands 文件）
 - 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
-- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
-- 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
+- 不跑：装户仓（本命令会拒绝）；仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
 
 ## 2. 怎么跑
 
 ### 2.1 默认 `--diff`（仅报告）
 
 ```
-node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑）
+node bin/flow-kit.mjs sync-hosts --diff      # 包源仓（在包源根跑，或 --dir <包源根>）
 node bin/flow-kit.mjs sync-hosts --json      # 机器可读
-flow-kit sync-hosts --diff                   # 装户仓（在装户根跑；或用 --dir <项目根> 指定）
 ```
 
 输出三类：
@@ -46,9 +41,8 @@ node bin/flow-kit.mjs sync-hosts --apply
 ### 2.3 自验
 
 ```
-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 已探测分流
+npm test                                       # 含 sync-hosts.test.mjs
+node bin/flow-kit.mjs doctor                   # 包源环境 §6.7 skipped
 ```
 
 ## 3. 边界（不要做）
@@ -63,10 +57,8 @@ sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已
 
 - trae 钩子（`modules/hosts/trae/hooks/*.cjs`）— 独立演进的工程件
 - trae 规则（`modules/hosts/trae/rules/*.md`）— 同上
-- 包源 .agents/scripts/*.cjs（pre-commit 等钩子）— 同步由 `flow-kit sync` 走 managed 台账负责
+- 门禁脚本与钩子（`templates/_agents/scripts`、`templates/_githooks`）— 由 `flow-kit sync` 按 managed 台账下发，不走 sync-hosts
 
 ## 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 包源环境跳过）
+- 立法出处：2026-09-25 cross-host-sync（intent/plan，含 B-b 方案拍板；父事件 = wf-runtime 双源纪律教训，规范 §7.x 包源环境跳过）——留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径