agentic-flow-kit 0.8.0 → 0.9.1

package/README.md

@@ -1,69 +1,93 @@
-# agentic-flow-kit
-
-AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套。
-
-**装完即自包含**：引擎文件拷贝进项目（零 npm 运行时依赖，Node ≥ 18 即可跑），clone 后只差 `git config core.hooksPath .githooks`——init 会自动挂好。
-
-## 快速开始
-
-```bash
-cd <你的项目根>
-npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 显式确认安装
-# 或直接给参数
-npx agentic-flow-kit init --stack node --hosts zcode,opencode
-
-# 体检（布局 / git 钩子 / managed 台账 / 索引漂移 / check-loop）
-npx agentic-flow-kit doctor
-
-# 包出新版后升级（未改动→覆盖；本地已改→跳过并报告，--force 才覆盖；owned 永不触碰）
-npx agentic-flow-kit sync
-
-# 后补宿主 / 装门禁（dotnet-ca：Clean Architecture 红线守卫，装后归项目）
-npx agentic-flow-kit add-host opencode
-npx agentic-flow-kit add-gate dotnet-ca
-```
-
-| 选项 | 说明 |
-|------|------|
-| `--stack` | `dotnet` / `node` / `python` / `go` / `none`（默认 none）——**门禁配置三处**：commit-check 条件编译检查（暂存对应扩展名时 commit 前自动构建）+ **质量检测**（`checks`：lint / 类型检查 / vet 等秒级确定性检查，存在对应配置文件（tsconfig / eslint / ruff / go.mod 等）才启用，没有则自动跳过；测试不放提交门——关单在 test.md 阶段门）、settings.json 自检验命令权限、AGENTS.md「项目适配区」命令预填 |
-| `--hosts` | `zcode` / `opencode` / `trae` / `omp` 逗号多选（默认 zcode）——生成对应宿主薄适配层；zcode/omp 为本地配置自动进 .gitignore |
-| `--board-port` | workflow 看板端口（默认 8933） |
-| `--dir` | 目标项目根（默认当前目录） |
-| `--force` | 覆盖已存在的同名文件（默认保守跳过） |
-
-init 不问项目名 / 描述：`AGENTS.md` 只生成「AI工作流 + Wiki」两章骨架 + 「项目适配区」；技术栈经 `--stack` 传入只用于门禁配置（编译检查与自检验命令初值），密钥白名单等其余细节在 `.agents/hooks/commit-check.config.json` 里按项目填。
-
-## 装了什么
-
-```
-.agents/            阶段命令×8 / 角色契约×3 / 门禁钩子 / 引擎脚本（检索·索引·看板·预算·聚合）/ 技能×2 / settings.json / kit.json 台账
-.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
-AGENTS.md           项目规范骨架（项目段占位待填）
-modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考实现，装进项目后归项目）
-```
-
-**两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
-
-**升级语义（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 后同步刷新其记账。
-
-## 设计原则
-
-- **权威单源**：角色行为只在 `.agents/roles/`，流程只在 `.agents/commands/`，宿主适配层是纯转发薄层——换宿主不换流程。
-- **门禁即 git 钩子**：不依赖任何 agent 客户端自觉；项目专属门禁挂 `.agents/hooks/local-pre-commit`。
-- **中文优先**：文档协议、命令、检查输出全中文；frontmatter 受限子集供机器断言。
-- 抽取自真实项目长期运转的引擎（某真实项目），dogfooding 是后续路线（sync 升级 / add-host / add-gate / npm 发布）的一部分。
-- **威胁模型（2026-09-27 init-p1-batch）**：勿在不可信仓库运行 `init` / `doctor` / `sync`——三命令在执行目标侧 `.agents/scripts/` 脚本（生成器 / 校验器）前有供应链防线：脚本内容与包源渲染值（LF 归一 sha）一致才执行，失配即显式跳过提示，不执行不下结论。**防线不覆盖 git 钩子面**：预植的 `.githooks/`、`.agents/hooks/` 仍会被保留挂载，并在你自己的首次 git 操作时执行——不可信仓库请先审查/清除预置件再 init。
-
-## 路线
-
-- [x] v0.1.0：init（flags 模式）+ doctor + 4 宿主适配 + dotnet-ca 门禁模块
-- [x] v0.2.0：sync 升级（未动覆盖 / 已改跳过报告 + `--force` / 生成器锚点重写）+ add-host / add-gate
-- [x] v0.2.0 已发布：npm view agentic-flow-kit（npx agentic-flow-kit init 即用；默认镜像源用户需等 npmmirror 同步或 --registry npmjs）
-- [x] v0.2.1：Shipyard 回流第二笔（模板引用去死链 + owned 台账记账策略：add-gate 接线刷新 + sync 盘面自愈）+ 全项目审查修复（量化台账 fail-loud / 生成器锚点与 ENOENT 守卫 / sync 跳过件持续报告 / P4 清账 / metrics glob 词表收口）——已发布
-- [x] v0.3.0：init 交互升级（序号菜单 + ANSI 色彩降级 + ts/js 技术栈别名归一 node）+ AGENTS.md 骨架探测补齐（已存在无标记时文末追加，原内容保留）+ wiki 模板预置 7 主题内容目录 + 关单 verify 固定编排（npm test + check-loop 一键过门，非绿不关单）+ workflow 看板纸墨视觉改版
-- [x] v0.3.1：doctor 修复——Windows 无 sh 环境（PowerShell）把 sh ENOENT 误报成 check-loop hard-block（探测分流：明示「未跑勿当作通过」，git 钩子门禁不受影响）
-- [x] v0.4.0：看板端口自动上探（基端口起探首个可用端口，多项目并行不冲突；`/api/board` 自报 pid/startedAt，root 比对识别本项目、他人进程不动手不 kill）+ 跨平台入口 `ensure-board.mjs` 取代 Windows 专属 `ensure-board.ps1`（Windows/Linux/macOS 零依赖单入口）
-- [x] v0.5.0：跨宿主适配层同步工具 `flow-kit sync-hosts`（B-b 方案：薄适配正文 = 权威源正文段 + frontmatter 保留宿主特化 + `--apply` 单向同步不动 frontmatter）+ `flow-kit doctor` §6.7 装户侧正文漂移检查（包源环境 §6.7 skipped 避免噪音）——跨平台冒烟由 CI 跑 Linux，Windows / macOS 由本地手测（不入 npm test）
-- [ ] v0.5.1（待发布）：init 安装器 P1×4 收口——POSIX 钩子执行位（render 落盘 0755 + sync chmod + doctor §3 失效可发现）；fresh init 生成器先跑后记账（不再必现 owned FAIL / exit 1）；目标侧脚本执行供应链防线（init/doctor/sync 只执行与包源渲染值 sha 一致的目标侧脚本，失配显式跳过）；init/add-gate 记账 LF 归一
+# agentic-flow-kit
+
+AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套。
+
+**装完即自包含**：引擎文件拷贝进项目（零 npm 运行时依赖，Node ≥ 18 即可跑），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.
+
+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.
+
+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.
+
+```bash
+npx agentic-flow-kit init --stack node --hosts claude,cursor
+npx agentic-flow-kit doctor
+```
+
+## 60 秒路径
+
+```bash
+npx agentic-flow-kit init --stack node --hosts claude
+# 按 .agents/commands/plan.md 写一份 L1 intent 与同名 plan（状态先保持 draft）
+node .agents/scripts/confirm-doc.mjs workflow/intents/<文件>.md   # 终端里键入「可以」
+# 改代码，git add，然后提交。配对没齐、验收没勾、确认指纹对不上，钩子会拒绝这次提交。
+```
+
+## 五条硬规则
+
+新装的 `kit.json` 写 `audit: false` 与 `policyVersion: 2`：check-loop 只阻断配对、验收勾验、确认留痕，外加发版提交树上仍未收口的文档。敏感信息在 pre-commit，双源和台账在 doctor / sync。`audit` 缺省（升级来的旧台账）保持全量卫生警告。本仓库显式 `audit: true`。豁免日期只在 `.agents/scripts/policy.mjs` 的 `policyVersion` 表里改。
+
+可选红线用 `add-gate`：`dotnet-ca`、`node-layer`、`py-import`、`generated-readonly`。约定见 `modules/gates/README.md`。
+
+## 快速开始
+
+```bash
+cd <你的项目根>
+npx agentic-flow-kit init                        # 交互模式：宿主 → 技术栈 → 端口 → 显式确认安装
+# 或直接给参数
+npx agentic-flow-kit init --stack node --hosts zcode,opencode
+
+# 体检（布局 / git 钩子 / managed 台账 / 索引漂移 / check-loop）
+npx agentic-flow-kit doctor
+
+# 包出新版后升级（未改动→覆盖；本地已改→跳过并报告，--force 才覆盖；owned 永不触碰）
+npx agentic-flow-kit sync
+
+# 后补宿主 / 装门禁（dotnet-ca：Clean Architecture 红线守卫，装后归项目）
+npx agentic-flow-kit add-host opencode
+npx agentic-flow-kit add-gate dotnet-ca
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--stack` | `dotnet` / `node` / `python` / `go` / `none`（默认 none）——**门禁配置三处**：commit-check 条件编译检查（暂存对应扩展名时 commit 前自动构建）+ **质量检测**（`checks`：lint / 类型检查 / vet 等秒级确定性检查，存在对应配置文件（tsconfig / eslint / ruff / go.mod 等）才启用，没有则自动跳过；测试不放提交门——关单在 test.md 阶段门）、settings.json 自检验命令权限、AGENTS.md「项目适配区」命令预填 |
+| `--hosts` | `zcode` / `opencode` / `trae` / `omp` / `claude` / `cursor` / `codex` 逗号多选（默认 zcode）。zcode/omp 为本地配置，自动进 .gitignore。Claude Code 加载 `.claude/commands` 与 `.claude/agents`；Cursor 加载 `.cursor/commands`；Codex 读仓库根 `AGENTS.md` 与 `.codex/skills/`，`.codex/commands` 是同形薄转发 |
+| `--board-port` | workflow 看板端口（默认 8933） |
+| `--dir` | 目标项目根（默认当前目录） |
+| `--force` | 覆盖已存在的同名文件（默认保守跳过） |
+
+init 不问项目名 / 描述：`AGENTS.md` 只生成「AI工作流 + Wiki」两章骨架 + 「项目适配区」；技术栈经 `--stack` 传入只用于门禁配置（编译检查与自检验命令初值），密钥白名单等其余细节在 `.agents/hooks/commit-check.config.json` 里按项目填。
+
+## 装了什么
+
+```
+.agents/            阶段命令×8 / 角色契约×3 / 门禁钩子 / 引擎脚本（检索·索引·看板·预算·聚合）/ 技能×2 / settings.json / kit.json 台账
+.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
+AGENTS.md           项目规范骨架（项目段占位待填）
+modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考实现，装进项目后归项目）
+```
+
+**两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
+
+**升级语义（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 后同步刷新其记账。
+
+## 设计原则
+
+- **权威单源**：角色行为只在 `.agents/roles/`，流程只在 `.agents/commands/`，宿主适配层是纯转发薄层——换宿主不换流程。
+- **门禁即 git 钩子**：不依赖任何 agent 客户端自觉；项目专属门禁挂 `.agents/hooks/local-pre-commit`。
+- **中文优先**：文档协议、命令、检查输出全中文；frontmatter 受限子集供机器断言。
+- 抽取自真实项目长期运转的引擎（某真实项目），dogfooding 是后续路线（sync 升级 / add-host / add-gate / npm 发布）的一部分。
+- **威胁模型（2026-09-27 init-p1-batch）**：勿在不可信仓库运行 `init` / `doctor` / `sync`——三命令在执行目标侧 `.agents/scripts/` 脚本（生成器 / 校验器）前有供应链防线：脚本内容与包源渲染值（LF 归一 sha）一致才执行，失配即显式跳过提示，不执行不下结论。**防线不覆盖 git 钩子面**：预植的 `.githooks/`、`.agents/hooks/` 仍会被保留挂载，并在你自己的首次 git 操作时执行——不可信仓库请先审查/清除预置件再 init。
+
+## 当前能力（已发布 0.8.0）
+
+版本沿革写在 `CHANGELOG.md`。0.8.0 已包含：init / doctor / sync / add-host / add-gate、四套技术栈门禁初值、宿主薄适配、确认门、check-loop 16 项、看板端口上探、opencode 命令 `wf-` 前缀、pre-commit managed 台账快检。
+
+仓库里还没打进版本号的增量：`audit` 档（新装默认 false）、`policyVersion`、检查 17（发版树上的未收口文档）、检查 18（委派台账对账）、检查 19（逐阶段审计）、逐阶段前置门（起草门 / 确认门 / done 前置门）、claude / cursor / codex 薄适配、`node-layer` / `py-import` / `generated-readonly` 三个可选门禁、fresh init 冒烟。效果数字等有外部仓库跑过再记，不在这次。
+
+活跃层里 2026-09-23 至 09-28 的 approved / open 文档没有在这次改成 done 或 closed。那些文件的确认指纹绑着当时的正文，关单要逐份 `confirm-doc`。

package/modules/gates/README.md

@@ -0,0 +1,24 @@
+# 门禁模块
+
+可选红线。`flow-kit add-gate <名>` 把模块里除元数据外的文件平铺进 `.agents/hooks/`，并把 `local-pre-commit.line` 的那一行追加到 `.agents/hooks/local-pre-commit`。装完归项目所有，`sync` 不覆盖。
+
+## 约定
+
+| 文件 | 作用 |
+|---|---|
+| `check-*.mjs` 或其他脚本 | 拷入 `.agents/hooks/`，由 pre-commit 调用 |
+| `local-pre-commit.line` | 一行挂载命令，不拷入项目；已有相同行则不重复 |
+| `README.md` | 只留在包内 |
+
+脚本只看暂存区，退出码非 0 即拦住这次提交。不要在模块里放子目录。
+
+## 现有模块
+
+| 名 | 拦住什么 |
+|---|---|
+| `dotnet-ca` | Clean Architecture 分层红线（参考实现） |
+| `node-layer` | `src/` 引用 `tests/`、`test/`、`__tests__/` |
+| `py-import` | 业务 `.py` 引用 `tests` / `test` 包 |
+| `generated-readonly` | 手改 `GENERATED:BEGIN` 与 `GENERATED:END` 之间的行 |
+
+项目自己的红线复制其中一个目录，改判断，再用 `add-gate` 装上。

package/modules/gates/generated-readonly/README.md

@@ -0,0 +1,13 @@
+# generated-readonly
+
+暂存 diff 若改到 `GENERATED:BEGIN` 与 `GENERATED:END` 之间的行，提交失败。生成器自己重写时：
+
+```sh
+FLOW_KIT_ALLOW_GENERATED=1 git commit
+```
+
+```sh
+npx agentic-flow-kit add-gate generated-readonly
+```
+
+标记写在文件正文里。`workflow/INDEX.md` 与 `wiki/INDEX.md` 的生成区已经带这对标记。

package/modules/gates/generated-readonly/check-generated.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// 暂存 diff 不得改写 GENERATED:BEGIN / GENERATED:END 之间的行。
+// 区间按索引里的文件计算（git show :path），不读工作区。
+// 生成器重写该区域时设 FLOW_KIT_ALLOW_GENERATED=1。
+import { spawnSync } from 'node:child_process';
+
+if (process.env.FLOW_KIT_ALLOW_GENERATED === '1') process.exit(0);
+
+const git = process.platform === 'win32' ? 'git.exe' : 'git';
+const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
+if (listed.status !== 0) {
+  console.error('check-generated: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
+  process.exit(1);
+}
+const diff = spawnSync(git, ['diff', '--cached', '-U0', '--'], { encoding: 'utf8' });
+if (diff.status !== 0) process.exit(1);
+
+function rangesOf(text) {
+  const out = [];
+  let start = -1;
+  String(text).split(/\n/).forEach((line, i) => {
+    if (line.includes('GENERATED:BEGIN')) start = i + 1;
+    else if (line.includes('GENERATED:END') && start > 0) {
+      out.push([start, i + 1]);
+      start = -1;
+    }
+  });
+  return out;
+}
+
+const files = new Map();
+let cur = null;
+for (const line of String(diff.stdout).split(/\n/)) {
+  const name = /^diff --git a\/(.+?) b\//.exec(line);
+  if (name) { cur = name[1]; if (!files.has(cur)) files.set(cur, []); continue; }
+  const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+  if (hunk && cur) files.get(cur).push([Number(hunk[1]), hunk[2] === undefined ? 1 : Number(hunk[2])]);
+}
+
+let bad = 0;
+for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
+  const norm = rel.split('\\').join('/');
+  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
+  if (shown.status !== 0) {
+    console.error(`${norm}: 读不到暂存内容`);
+    bad += 1;
+    continue;
+  }
+  const text = shown.stdout;
+  const ranges = rangesOf(text);
+  if (!ranges.length) continue;
+  for (const [start, len] of files.get(norm) || []) {
+    const from = start;
+    const to = len === 0 ? start : start + len - 1;
+    if (!ranges.some(([s, e]) => !(to < s || from > e))) continue;
+    console.error(`${norm}: 暂存改动落入 GENERATED 区（${ranges.map(([s, e]) => `${s}-${e}`).join('、')}）。生成器重写时设 FLOW_KIT_ALLOW_GENERATED=1`);
+    bad += 1;
+    break;
+  }
+}
+process.exit(bad ? 1 : 0);

package/modules/gates/generated-readonly/local-pre-commit.line

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

package/modules/gates/node-layer/README.md

@@ -0,0 +1,9 @@
+# node-layer
+
+暂存的 `src/**/*.{js,mjs,cjs,jsx,ts,tsx}` 不得 `import` / `require` `tests/`、`test/` 或 `__tests__/`。
+
+```sh
+npx agentic-flow-kit add-gate node-layer
+```
+
+装进 `.agents/hooks/` 后归项目所有。目录名或更多禁引路径直接改脚本里的判断。

package/modules/gates/node-layer/check-node-layer.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// 暂存区内 src/ 下的脚本不得引用 tests/、test/ 或 __tests__/。
+// 正文只读索引（git show :path），不读工作区。
+import { spawnSync } from 'node:child_process';
+
+const git = process.platform === 'win32' ? 'git.exe' : 'git';
+const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
+if (listed.status !== 0) {
+  console.error('check-node-layer: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
+  process.exit(1);
+}
+const re = /['"](?:[^'"]*\/)?(?:tests?|__tests__)(?:\/[^'"]*)?['"]/;
+let bad = 0;
+for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
+  const norm = rel.split('\\').join('/');
+  if (!norm.startsWith('src/') || !/\.(?:[cm]?js|jsx|tsx?)$/.test(norm)) continue;
+  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
+  if (shown.status !== 0) {
+    console.error(`${norm}: 读不到暂存内容`);
+    bad += 1;
+    continue;
+  }
+  shown.stdout.split(/\n/).forEach((line, i) => {
+    if (!re.test(line)) return;
+    console.error(`${norm}:${i + 1}: src 不得引用 tests/、test/ 或 __tests__/`);
+    bad += 1;
+  });
+}
+process.exit(bad ? 1 : 0);

package/modules/gates/node-layer/local-pre-commit.line

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

package/modules/gates/py-import/README.md

@@ -0,0 +1,9 @@
+# py-import
+
+暂存的业务 `.py`（路径中不含 `tests/` 或 `test/`）不得出现行首 `import tests`、`from tests`、`import test`、`from test`。
+
+```sh
+npx agentic-flow-kit add-gate py-import
+```
+
+这是边界的一个窄实现。更细的分层用项目自己的 import linter，按 `modules/gates/README.md` 的平铺约定挂上。

package/modules/gates/py-import/check-py-import.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// 暂存的业务 .py（不在 tests/ 或 test/ 下）不得 import tests 或 test。
+// 正文只读索引（git show :path），不读工作区。
+import { spawnSync } from 'node:child_process';
+
+const git = process.platform === 'win32' ? 'git.exe' : 'git';
+const listed = spawnSync(git, ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8' });
+if (listed.status !== 0) {
+  console.error('check-py-import: git diff --cached 失败（需在 git 仓库的暂存区上运行）');
+  process.exit(1);
+}
+const re = /^\s*(?:import|from)\s+(?:tests?|test)\b/;
+let bad = 0;
+for (const rel of listed.stdout.split(/\n/).map((s) => s.trim()).filter(Boolean)) {
+  const norm = rel.split('\\').join('/');
+  if (!norm.endsWith('.py')) continue;
+  if (norm.split('/').some((seg) => seg === 'tests' || seg === 'test')) continue;
+  const shown = spawnSync(git, ['show', `:${norm}`], { encoding: 'utf8' });
+  if (shown.status !== 0) {
+    console.error(`${norm}: 读不到暂存内容`);
+    bad += 1;
+    continue;
+  }
+  shown.stdout.split(/\n/).forEach((line, i) => {
+    if (!re.test(line)) return;
+    console.error(`${norm}:${i + 1}: 业务代码不得 import tests 或 test`);
+    bad += 1;
+  });
+}
+process.exit(bad ? 1 : 0);

package/modules/gates/py-import/local-pre-commit.line

@@ -0,0 +1 @@
+node .agents/hooks/check-py-import.mjs

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

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

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

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

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

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

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

@@ -0,0 +1,79 @@
+---
+description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码)
+---
+
+# Build · 起 plan + 写代码
+
+> AI 起草 plan,用户确认;进计划模式列改动,用户确认;最后才动代码。两道确认门。
+
+## 执行
+
+### 起草 plan
+
+1. 确认同名入口文档（approved intent 或已确认的 incident）+ spec（若 L2/L3）均已确认；否则回上一阶段（fill/confirm 未过即拒）
+2. 起草 plan:
+   - 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
+   - L2/L3 按 4 节填写:任务拆解(每个任务有判据) / 风险评估 / 执行顺序 / 遗留项
+   - L1 默认极简两节:改动面(逐条文件+做什么) / 验证方式(一行静态门+按需 UI 实测)；仅多文件多步骤时再加任务拆解/执行顺序
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 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 失去分辨力））。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 口径)
+
+### 进计划模式列改动
+
+5. **不要直接动代码**。先进「计划模式」:
+   - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `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. 停下,等用户确认改动清单
+
+### 实现
+
+7. 确认后按 plan 顺序推进;每个任务对照判据自验。若任务满足 `.agents/roles/implementer.md` 的边界,主智能体可将单个工作包连同必读材料、授权文件和验收条件委派给 `implementer`;否则由主智能体执行
+8. 自验:按改动域跑 `项目构建命令` / `项目类型检查命令` / `项目测试命令`(对应编译 / 前端类型检查 / 自动化测试;静态门全集见 `test.md` §1)
+9. **项目架构红线**:数据访问模式、公共字段写入等以根与目录级 `AGENTS.md`(如有)红线为准,不自创旁路
+10. **L3 且含 schema 变更时**:schema 变更走项目约定的维护方式(人工 SQL / 迁移工具,以目录级 `AGENTS.md` 或 spec 约束为准),不得擅自引入项目未采用的迁移机制（仅运行时 / 管线类 L3 无此约束）
+11. 实现中若需偏离已确认的 plan(改公共接口 / 动 plan 未列文件 / 引新依赖 / 影响任务判据)→ 停下,向用户说明原因与影响,确认后再继续
+
+## 技能辅助(可选,宿主级 skills)
+
+- plan 任务多、依赖复杂时:用 `to-tickets` 拆 tracer-bullet 任务单(每张带阻塞边);结果回填 plan「任务拆解」节,不发布外部 tracker
+- 后端逻辑改动:有测试基建的用 `tdd` 测试先行(红→绿→重构);整体实现纪律可用 `implement` 驱动
+- 遇合并冲突:用 `resolving-merge-conflicts` 按意图逐 hunk 处理
+- 技能不改变两道确认门、红线检查与委派边界
+
+## 红线提示(本阶段高频踩)
+
+- 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `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`,验收标准不变。
+
+## 确认后
+
+- plan 状态 → done（实现完成；intent / spec 关单在 test）
+- commit：L1+ 入口文档 / spec / plan 随代码同一提交（Conventional Commits 中文 feat/fix/refactor/perf）；docs 豁免与 bootstrap 可单独 `docs(*)`
+- 进 `next: .agents/commands/test.md`