agentic-flow-kit 0.7.0 → 0.9.0

package/README.md

@@ -4,6 +4,34 @@ AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命
 
 **装完即自包含**：引擎文件拷贝进项目（零 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
@@ -26,7 +54,7 @@ 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 |
+| `--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` | 覆盖已存在的同名文件（默认保守跳过） |
@@ -56,14 +84,10 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 - 抽取自真实项目长期运转的引擎（某真实项目），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 归一
+## 当前能力（已发布 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`

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

@@ -0,0 +1,57 @@
+---
+description: Deploy 阶段:prod 上线清单(静态门 + 配对检查 + 回归 + DB + 授权 + 24h 观察；文档关单在 test)
+---
+
+# Deploy · 上线清单
+
+> 仅 prod。文档关单（验收勾验 / intent done）在 `test.md`，本阶段不重复关单。个人工作流:唯一授权人是用户本人——上线授权 = 用户一句确认 + `release/<日期>` tag 留痕,追溯靠 git,不依赖第二人审批。
+> 环境定位:dev 为开发自测;staging 即人工验证环境(不设独立发布门);prod 上线必须过本清单。
+
+## 1. 静态门(必跑,全过方可继续)
+
+同 `test.md` §1(静态门全集:`项目构建命令` / `项目测试命令` / `项目类型检查命令` 与项目自有门禁;含环境注记与 Windows 取码注记),逐条跑完再继续。
+
+## 2. 文档闭环(必查)
+
+- L2 / L3 变更:入口文档(`workflow/intents/` 或 `workflow/incidents/`) + `workflow/specs/` + `workflow/plans/` 三件同名配对齐全；intent/spec/plan 状态为 done（test 已关单）。若仍为 approved，先回 `test.md` 补关单再上
+- 若属修复:`workflow/incidents/` 同时须满足复盘三件套完整(结构性修复 / 防复发验证 / 规范条目)，状态 closed
+- 新 intent 是否已立:根因属门禁缺位 / 规范未落地 / 系统性问题时强制立(即使修复已完成)
+
+## 3. 回归清单(必过)
+
+- `workflow/regression-checklist.md` 中涉及模块的关键路径条目全过
+- 项目自动化测试用例全过(`项目测试命令`;不得跳过失败用例)
+- 历史同类 incident 的防复发验证条目(清单「防复发验证」节)逐条过
+
+## 4. 数据库(若涉及 schema 变更)
+
+- 迁移 SQL 已按项目约定的 schema 变更流程验证并留档
+- 实体映射与迁移 SQL 已人工核对一致
+- 备份点已记录 + 回滚 SQL 就绪(L3 且含 schema 变更时强制)
+
+## 5. 上线授权(用户本人最后一关)
+
+- 授权人:用户本人(个人工作流,无第二审批人);对话内一句"上"即授权
+- 授权记录:打 `release/<日期>` tag + commit SHA——tag 是「prod 跑的是哪个 commit」的追溯依据,`git log` 可查
+- 发布流水线(可选):若项目 CI/CD 配置了人工审批卡点,按提示在流水线平台自行批准;批准人仍是本人,不构成第二人评审
+- 回滚决策人:用户本人
+- 回滚预案(按 L3 类型分叉):含 schema 变更 → <备份点 + 回滚 SQL 路径>;仅运行时 / 管线(无 schema,如认证管线 / DI 注册 / 中间件) → 回退上一 `release/<日期>` tag + 配置开关回退
+- 回滚 SQL 必须在 dev 演练执行过(没跑过的回滚脚本等于没有);回退版本类预案须确认上一 tag 可复现构建
+
+## 6. 上线后观察(用户观察,Maintain 阶段接手)
+
+- 观察期:上线后 24h;由用户观察错误率 / 延迟 / 关键业务流(无监控时人工看)
+- 闭环宣告:用户确认无异常后才算闭环;AI 不得自行宣告
+- 异常回落:超阈值 → 生成 `workflow/incidents/YYYY-MM-DD-<主题>.md`,进 `maintain.md`(止血方案用户拍板,见 maintain.md §0)
+- 事故响应:单用途账号 + 最小权限;不得跨智能体协作推送修复(参考 Anthropic 教训)
+
+## 子代理调用约定
+
+- 上线清单、回滚方案、授权、tag 与事故决策均由主智能体处理,本阶段不委派子智能体;回滚方案(尤其含数据回滚 SQL)涉及数据安全,不得以通用实现子智能体代替主智能体判断与用户确认。
+
+## 确认后
+
+- 打 `release/<日期>` tag（commit SHA 可追溯）
+- 上线 + 用户观察 24h
+- 用户确认无异常 → prod 闭环（文档 done 应已在 test 写好；若漏写在此补勾验收并置 done）
+- 异常 → 进 `next: .agents/commands/maintain.md`

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

@@ -0,0 +1,42 @@
+---
+description: Design 阶段:起 spec(L2/L3 强制,L1 可省略)
+---
+
+# Design · 起 spec
+
+> L2/L3 强制;L1 可省略(直接跳 `next: build.md`)。
+
+## 执行
+
+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`
+   - **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`（如有）逐条说明如何满足
+   - 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
+   - **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单（字段清单）」还是「选择器/弹窗」，禁止自行推定交互形态
+4. 起草后停下,输出草稿全文给用户过目
+5. L3 必须独立复核:宿主支持子智能体时调用 `independent-reviewer`,并要求其读取 `.agents/roles/independent-reviewer.md`;不支持时另开新会话。复核者读 spec + 根 AGENTS.md 与改动域目录级 AGENTS.md 的红线挑漏洞,结论写入 spec「确认与复核」节;复核未过不得确认
+
+## 技能辅助(可选,宿主级 skills)
+
+- 对话已充分、无需再访谈时:用 `to-spec` 直接综合成 spec 草稿;其"发布到 issue tracker"默认行为一律改为写入 `workflow/specs/` 同名文件,按 `_TEMPLATE.md` 格式
+- L2/L3 模块设计:用 `codebase-design`(深模块/接缝/接口收窄);术语混乱或需记 ADR:用 `domain-modeling`
+- 方案取舍需压力测试:用 `grilling`;技能产出不越过用户确认门,L3 独立复核流程不变
+
+## 委派约定
+
+- spec 起草、方案取舍与用户确认由主智能体负责,不委派;只有 L3 确认前的独立复核委派 `independent-reviewer`(必需输入:入口文档、spec、根 `AGENTS.md` + 改动域目录级 `AGENTS.md`、固定复核目标)。
+- 宿主不支持子智能体时必须 `fallback: new-session`,不得由原主智能体自查冒充独立复核。
+
+## 确认后
+
+- 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 失去分辨力））。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`