agentic-flow-kit 1.8.7 → 2.0.0

package/README.md

@@ -1,175 +1,140 @@
 # agentic-flow-kit
 
-AI-Native 闭环工作流 + wiki 知识层脚手架。`flow-kit init` 一条命令为新项目装好整套项目级 AI 工作流引擎：8 个阶段命令、3 个子智能体角色契约、git 门禁钩子（闭环配对 / 敏感信息扫描 / 条件构建 / 规则面预算）、kb 跨语料检索、workflow 实时看板、intents→specs→plans→incidents 文档闭环、wiki 知识库三件套、**多人/多 worktree 台账并发治理**（并集合并 / 分片归并 / 特许修剪）。
+AI-Native 工作流驱动开发引擎的独立安装器。把现行仓的 `.agents/` 引擎、git 门禁、宿主适配层与 `wiki`/`workflow` 数据资产脚手架，从零生成到任意项目；功能与现行引擎保持 parity。
 
-**装完本地可跑**：日常闭环（门禁钩子 / 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 会自动挂好。
+- 零运行时依赖：只用 Node.js ≥ 22 内置模块。
+- 指定 agent：一次可装一个或多个宿主壳（命令 / 角色 / 规则 / hooks 接线）。
+- 可选语言：`--lang zh-CN`（默认）或 `--lang en`；语言包覆盖文档、提示词、记忆文件、脚手架与安装器输出。
+- 幂等升级：`.agents/install-manifest.json` 记录版本、宿主、语言与文件哈希；冲突默认跳过，`--force` 才覆盖。
 
-## English
-
-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 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.
-
-```bash
-npx agentic-flow-kit init --stack node --hosts claude,cursor
-npx agentic-flow-kit doctor
-```
+## 快速开始
 
-## 60 秒路径
+kit 源码独立于业务仓，位于 `E:/Demo/cli-tools/agentic-flow-kit`。在目标项目根运行：
 
 ```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，然后提交。配对没齐、验收没勾、确认指纹对不上，钩子会拒绝这次提交。
+node E:/Demo/cli-tools/agentic-flow-kit/bin/flow-kit.mjs install \
+  --agent trae --agent codebuddy \
+  --lang zh-CN \
+  --stack dotnet \
+  --target .
 ```
 
-## 五条硬规则
-
-新装的 `kit.json` 写 `audit: false` 与 `policyVersion: 12`（v1–v12 全锚，新装空台账零回溯负担）：check-loop 只阻断配对、验收勾验、确认留痕，外加发版提交树上仍未收口的文档。敏感信息在 pre-commit，双源和台账在 doctor / sync。`audit` 缺省（升级来的旧台账）保持全量卫生警告；自己装一份 dogfood 时可显式置 `audit: true`。豁免日期只在 `.agents/scripts/policy.mjs` 的 `policyVersion` 表里改（当前生效规则的可读视图在 `workflow/effective-policy.md`，policy 变更后重生成并随同提交）。
-
-可选红线用 `add-gate`：`dotnet-ca`、`node-layer`、`py-import`、`generated-readonly`、`test-protect`。约定见 `modules/gates/README.md`。
-
-**门禁信任档**（`.agents/kit.json` 的 `gateTrust`）：默认 `project` —— gate 安装锚失配只 WARN（装户对门有最终所有权，锚只提供可见性）。多仓或组织场景改成 `org`，失配即 `doctor` FAIL（exit 1），对齐托管策略的组织级强制。缺键或非法值一律回退 `project`，不会因写错而变严。
-
-**待澄清标记**：起草 intent / spec / plan 时不确定的地方照实写一行 `- 待澄清：<你卡在哪>`，不要猜——「我不知道」是负责，猜是失职（与检查 2 的模板占位符语义相反：占位符是忘了填）。起草门不拦（零阻塞），但 `draft→approved` 确认时仍挂着未澄清项会被 `confirm-doc` 拒绝落账（2026-10-18 立项跳对称化起 intents 同口径挂门——intent 是后链全部文档的种子；存量无标记零回溯）。解决后把行首改成 `- 已澄清：`（保留行，留痕曾不清楚过）或删行。
-
-**关于「确认门」的诚实边界**：确认门是**留痕机制，不是防伪机制**。`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 | 确认行**默认**写分片 `.agents/confirmations.d/<doc>.jsonl`（2026-10-13 ledger-shard-default），各写各的；`--no-shard` / `CONFIRM_SHARDED=0` 回退主台账；里程碑可选跑 `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` 会自动配；漏配则退化为文本冲突（**不静默丢数据，但需人工解**）。
-
-> **存量装户迁移指引（级别 L0 退役，`level.all` 收敛为 `L1 L2 L3`）**：升级前已按 L0 定级的存量文档，`sync` 升级后把 frontmatter `级别: L0` 改为 `L1`，或在行首加 `流程: legacy`（存量豁免通路，跳过级别/配对检查）——不改会被 incident 级别枚举校验出 WARN「级别缺失」，且 `--batch` / `--auto` 自治门按 suspect 拒（fail-closed）。
-
-> **存量装户迁移指引（policyVersion 升 12 + 生效规则视图）**：`kit.json` 属项目自持（owned）、`sync` 永不覆盖——`policyVersion` 升 12 由装户自选时机（v12 全锚生效日 = 发布当日 advisory 档 / 发布次日 hard 档，锚前存量不追溯）。升级后跑一次 `node .agents/scripts/gen-effective-policy.mjs` 把生成的 `workflow/effective-policy.md` 随同提交：该文件是生效规则的入库视图，`verify` 的 effective-policy 门对缺文件判漂移（新装由 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
-
-# 只读校验（包内置 check-loop 引擎跑闭环结构检查；--strict 把 advisory 也判红，--json 机器可读）
-npx agentic-flow-kit validate
-
-# 包出新版后升级（未改动→覆盖；本地已改→跳过并报告，--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
+npx agentic-flow-kit install --agent claude --lang en --target .
 ```
 
-## 执行面：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 "可以"
+node .agents/scripts/check-local-gates.mjs --fix
+node E:/Demo/cli-tools/agentic-flow-kit/bin/flow-kit.mjs doctor --target .
 ```
 
-| 命令 | 干什么 | 谁是单源 |
-|------|--------|----------|
-| `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` 漏判语义，钩子照样拦。
+| 命令 | 作用 |
+|---|---|
+| `install` | 从零安装；可重复 `--agent`，也可 `--agents a,b,c` |
+| `add-host <host>` | 已安装仓追加宿主壳（同时接受 `--agent <host>`） |
+| `upgrade` | 按 manifest 记录的宿主/语言/栈重放模板；冲突默认跳过 |
+| `doctor` | 校验 manifest、文件在位、git 配置、`.gitattributes`、五钩子、宿主接线、Node 版本；`--deep` 再跑 `check-local-gates.mjs` |
+| `list-hosts` | 列出支持的宿主 |
 
+通用选项：
 
 | 选项 | 说明 |
-|------|------|
-| `--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）。七个宿主一律入库（2026-10-05 起 zcode/omp 撤销 localOnly——换宿主不丢文件、CI 克隆面与本仓一致）；zcode 的会话级液态草稿（`.zcode/drafts/`、`.zcode/plans/`）是本机态、不该入库——init 不再自动写这条规则，请自行加进 `.gitignore`（本仓实例见根 `.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 / 门禁钩子 / 引擎脚本（检索·索引·看板·预算·聚合·判定流水）/ 技能×3 / 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
-AGENTS.md           项目规范骨架（项目段占位待填）
-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`——七门 GATES 编排：语法自检 / 测试【有根 package.json 才跑】/ 编排脚本检查 / 常驻面预算 / 生效规则视图漂移 / check-loop 闭环硬门 / 台账不变量历史全扫，逐门 pass/fail、任一门红即红；门清单见 `node .agents/scripts/verify.mjs --list`）。本地 git 钩子可被 `--no-verify` 绕过，远端门兜底；该文件归装户自持（owned），`flow-kit sync` 永不覆盖，非 GitHub 装户可删。其他 CI（GitLab / Jenkins / Azure DevOps…）等价接入 = 同一入口命令 + 服务端分支策略：
+|---|---|
+| `--target <dir>` | 目标项目根，默认当前目录 |
+| `--lang zh-CN\|en` | 语言包，默认 `zh-CN` |
+| `--stack dotnet\|node\|empty` | 项目栈 profile；缺省按 `.sln`/`.csproj`/`package.json` 探测 |
+| `--name <name>` | 渲染 `{{projectName}}`，默认目标目录名 |
+| `--dry-run` | 只打印计划，不写盘 |
+| `--force` | 覆盖冲突/非本工具安装的既有文件 |
+| `--no-git-config` | 不自动写三条例行 git 配置 |
+| `--track-hosts` | 不把本机宿主目录写进 `.gitignore` |
+
+## 宿主
+
+v1 支持 10 个现行宿主：
+
+| 宿主 | 目录 | 说明 |
+|---|---|---|
+| `trae` | `.trae/` | 命令 / 角色 / 规则 / hooks.json |
+| `codebuddy` | `.codebuddy/` | 命令 / 角色 / 规则 / 技能 / settings / 记忆 |
+| `claude` | `.claude/` + 根 `CLAUDE.md` | 命令 / 角色 / settings / 根记忆 |
+| `opencode` | `.opencode/` | 命令 / 角色 |
+| `qwen` | `.qwen/` | 命令 / 角色 / settings |
+| `pi` | `.pi/` | 角色 / 扩展 / settings |
+| `cline` | `.cline/` | workflows / 角色 YAML / hook |
+| `commandcode` | `.commandcode/` | 命令 / 角色 / settings |
+| `qoder` | `.qoder/` | 命令 / 角色 / settings |
+| `zcode` | `.zcode/` | 角色 / config / workflows |
+
+宿主壳全部是指针壳：正文权威仍在 `.agents/commands/`、`.agents/roles/`、`.agents/skills/`，安装器不复制正文，避免双源漂移。
+
+## 模板 / Profile / State 三层
+
+| 层 | 位置 | 内容 |
+|---|---|---|
+| engine | `templates/engine/` | `.agents/` 通用引擎（commands / skills / roles / hooks / scripts / config / pipelines / tests / board / notes） |
+| profile | `templates/profiles/<stack>/` | 栈相关配置与 `AGENTS.md`：`test-impact-map.json`、`lane-surfaces.txt`、`rule-budgets.txt`、`workflow-modules.txt`、`commit-check.config.json`、`delete-guard-allowlist.txt` |
+| scaffold | `templates/scaffold/` | `wiki/` 目录骨架 + INDEX + 看板；`workflow/` 状态机骨架 + 空台账 + `_TEMPLATE.md` |
+| git | `templates/git/` | `.githooks/` 五钩子、`.gitattributes` 合并块、`.gitignore` 运行态块 |
+| locale | `locales/<lang>/overrides/` | 按目标路径镜像的语言覆盖；缺省回退模板 |
+
+运行态（`cache/`、`tmp/`、`*.jsonl` 台账、`confirmations.d/`、`workflow/archive`、`.agents/tools/`）不打包，由引擎在装户内产生。
+
+## 冲突与升级
+
+- 目标文件不存在 → 创建。
+- 目标文件存在且哈希等于 manifest → 更新。
+- 目标文件存在但哈希不等于 manifest（装后被改）→ 冲突跳过；`--force` 覆盖。
+- 目标文件存在且不在 manifest（非本工具安装）→ 跳过；`--force` 覆盖。
+- `.gitattributes` / `.gitignore` 用带标记的合并块，重复执行不会重复追加。
+
+## 语言
+
+- `zh-CN`：模板原文即中文。
+- `en`：`locales/en/overrides/` 覆盖命令、角色、技能入口、宿主指针壳、记忆文件、`wiki`/`workflow` 脚手架与安装器输出。
+- 机器协议与锚点（例如 `wiki/INDEX.md` 的生成锚点、`_TEMPLATE.md` 的节标题）保持中文原样，避免破坏生成器与门禁解析；英文包只翻译人类可读面。
+- `runtime-env.md`、`gate-diet.md` 等环境/历史长文暂回退中文；按需在 `locales/en/overrides/.agents/notes/` 补译。
+
+## 迁移与 parity
+
+本工具的模板由 `tools/extract-from-project.mjs` 从现行仓一次性提取；`tools/parity-report.mjs` 只读对比模板与现行引擎/宿主/git 面。当前结果：
+
+- 350 个对比对：342 完全一致，7 处刻意差异，0 个现行跟踪文件未被覆盖：
+  1. `engine.json` 用 `{{installedAt}}` / `{{hostsJson}}` / `{{stack}}` / `{{language}}` 占位；
+  2. `check-local-gates.mjs`：dotnet 与 `TEST_DB_CONN` 检查只在 `stack=dotnet` 时执行；
+  3. `check-scripts-syntax.mjs`：缺失 `scripts/verify` 时跳过（存在但为空仍 fail-closed）；
+  4. `verify.mjs`：按 `engine.json options.stack` 过滤 dotnet/Vue 专用 product 门，node 栈追加 `npm test`；
+  5. `.githooks/pre-push`：宿主接线面扩到 10 宿主；
+  6. `.agents/board/dev-tour.html`：项目名改为 `{{projectName}}` 占位；
+  7. `check-ledger-invariant.mjs`：本仓历史基线哈希在新仓解析不出时按无基线处理，避免装户报警。
+- `verify-ui/features/` 是装户业务特性地图，只保留空目录占位，不随通用引擎打包。
+
+本仓迁移策略：先保留现行 `.agents`/`.githooks`/宿主目录；其他项目安装验证完成后，再在本仓卸载现行引擎并安装本工具（届时用 `--force` 采用现有文件）。
+
+## 开发
 
 ```bash
-node .agents/scripts/verify.mjs                    # 远端门本体（工程在子目录时加 --test-cmd "<项目测试命令>"）
-npx agentic-flow-kit validate --strict --json      # 可选加一道：包内置引擎只读结构校验（warning 也判红，stdout 机器可读）
+node tools/extract-from-project.mjs --project E:/Git/Shipyard.Material   # 重新提取模板（一次性迁移工具）
+node tools/make-en-host-overrides.mjs                                     # 重新生成英文宿主指针壳
+node tools/parity-report.mjs --project E:/Git/Shipyard.Material          # 对比现行引擎
+node --test tests/*.test.mjs                                              # 安装器测试
 ```
 
-真正的「门」在服务端分支保护（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 后同步刷新其记账。
-
-## 设计原则
-
-- **权威单源**：角色行为只在 `.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。
-
-## 当前能力
-
-**能力清单的单一真相源是 `CHANGELOG.md`**——每个已发布版本带什么、为什么这么带，都在那里。本节只讲当前语义，不重复枚举版本特性（此前列举导致 README 与实际发布内容长期漂移，2026-10-08 已收敛到单源）。
-
-当前语义四点：
-
-- **门禁面**：check-loop 26 项检查 + 3x（分道：默认硬门 / `--hygiene` 卫生段 / `--all`，权威清单见引擎头部）+ `.githooks/` 五个钩子（pre-commit / pre-push / commit-msg / post-commit / pre-merge-commit），门禁逻辑不依赖 agent 客户端自觉。
-- **闭环面**：intents → specs → plans → incidents 四态文档链 + 确认台账（`.agents/confirmations.jsonl` 及默认分片）+ 逐阶段前置门（起草门 / 确认门 / done 前置门）+ **台账并发三形态**（并集合并 / 分片写入与 compact 归并 / 特许修剪）与按 doc 逻辑序的哈希链（见上文「台账并发」段）+ 终态件同名家族滚动归档（关单即归档，kb 检索覆盖归档件）。
-- **观测面**：`workflow/INDEX.md`（检索索引）、`workflow/DASHBOARD.md`（红绿灯仪表盘）、`workflow/metrics.md`（月度快照）、`workflow/effective-policy.md`（生效规则视图）与判定流水 `.agents/judgments.jsonl`（机制月度对账数据底座）——**观测面非门禁**，红灯是「看」的不是「拦」的。
-- **执行面**：`route`（手动路由的机器面：定级 + 泳道 + 下一阶段 + 入口 md）与 `run`（自动流水线薄壳转发装户状态机）；判据单源在装户 `.agents/scripts/level-criteria.mjs`，md 改为引用它而非承载判据散文（见上文「执行面」段）。
-
-版本号与已发布能力看 `package.json` 的 `version` 与 `CHANGELOG.md`；仓库当前工作流实况看 `workflow/INDEX.md`。
+agentic-flow-kit/
+├── bin/flow-kit.mjs
+├── src/{cli,install,hosts,render,git}/
+├── templates/{engine,hosts,profiles,scaffold,git}/
+├── locales/{zh-CN,en}/
+├── schemas/
+├── tests/
+└── tools/
+```

package/bin/flow-kit.mjs

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
-import { run } from '../src/cli.mjs';
+import { main } from '../src/cli/main.mjs';
 
-run(process.argv.slice(2));
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});

package/locales/en/installer.json

@@ -0,0 +1,25 @@
+{
+  "help": "agentic-flow-kit v{{version}}\n\nUsage:\n  flow-kit install --agent <host> [--agent <host>...] [--lang zh-CN|en] [--stack dotnet|node|empty] [--target <dir>] [--dry-run] [--force] [--no-git-config] [--track-hosts]\n  flow-kit add-host <host> [--target <dir>] [--dry-run] [--force]\n  flow-kit upgrade [--target <dir>] [--dry-run] [--force]\n  flow-kit doctor [--target <dir>] [--deep] [--fix]\n  flow-kit list-hosts\n\nHosts: trae, codebuddy, claude, opencode, qwen, pi, cline, commandcode, qoder, zcode\n\nExample:\n  node cli-tools/agentic-flow-kit/bin/flow-kit.mjs install --agent trae --agent codebuddy --lang en --target .\n",
+  "install.start": "▶ {{command}} → {{target}}",
+  "install.plan": "  hosts={{hosts}} stack={{stack}} lang={{lang}} planned={{count}} files",
+  "install.dryRun": "  (dry-run: print the plan only, write nothing)",
+  "install.create": "create",
+  "install.update": "update",
+  "install.skip": "skip",
+  "install.conflict": "conflict",
+  "install.summary": "Done: created {{create}} / updated {{update}} / merged {{merge}} / skipped {{skip}} / conflicts {{conflict}}",
+  "install.manifest": "manifest: {{path}}",
+  "install.gitConfig": "Configured git gates: core.hooksPath / merge.ours.driver / merge.jsonl-union.driver",
+  "install.gitSkip": "Git config skipped (not a repository or --no-git-config); run the three config commands after cloning",
+  "install.next": "Next: node .agents/scripts/check-local-gates.mjs --fix",
+  "doctor.manifestMissing": "missing .agents/install-manifest.json; run flow-kit install first",
+  "doctor.fileMissing": "file registered in manifest is missing",
+  "doctor.unknownHost": "host template not found",
+  "doctor.ok": "doctor passed ({{total}} checks)",
+  "doctor.fail": "doctor failed: {{failed}}/{{total}} checks",
+  "error.noHosts": "No host specified. Use --agent <host>; available: {{hosts}}",
+  "error.unknownHost": "Unknown host: {{name}}. Available: {{hosts}}",
+  "error.noManifest": "Engine is not installed in the target; run install first",
+  "error.noHostsInManifest": "No hosts recorded in manifest; run install first",
+  "listHosts.title": "Supported hosts:"
+}

package/locales/en/overrides/.agents/commands/deploy.md

@@ -0,0 +1,52 @@
+---
+description: "Deploy stage: merge checklist (static gates + pairing check + regression + DB + authorization + PR review merge)"
+stage: Deploy
+triggers:
+  - "run the release"
+  - "we can ship it"
+  - "get ready to go live"
+approval_required: true
+next: .agents/commands/maintain.md (incidents only)
+---
+
+# Deploy · Merge Checklist
+
+L1 is already closed out in `.agents/commands/new-task.md` §L1 Fast Track; this file is not opened for L1. This file starts from L2/L3 merges.
+**Policy (owner 2026-10-29)**: no tag/24h observation ritual — merge = PR creation $\rightarrow$ review $\rightarrow$ regression $\rightarrow$ merge $\rightarrow$ archive (release tags and the release-observation ledger are retired; see git for history).
+
+## 1. Static Gates
+1. `node .agents/scripts/verify.mjs --full` (policy in the header note) all green $\rightarrow$ record evidence; any failure $\rightarrow$ **HALT** $\rightarrow$ return to the Build chapter in `stages.md`. Environment details in `.agents/notes/runtime-env.md` §1, §2
+
+## 2. Documentation Audit
+1. **Pairing check (L2/L3)**: `intents/` (or `incidents/`) $\leftrightarrow$ `specs/` $\leftrightarrow$ `plans/` all three present under the same name, all with status `done`
+2. **Fix-type special case**: incident trio [structural fix / recurrence-prevention verification / rule entry] complete $\text{AND}$ status `closed`; if the root cause is a missing gate/rule $\rightarrow$ a new intent has been filed to track it
+3. **Ruling backfill check**: if a ruling backfill modified a done document $\rightarrow$ re-confirmation compensation lines were backfilled in the same batch (`maintain.md` §4.4) $\rightarrow$ otherwise the pre-push fingerprint hard gate blocks it
+4. **Merge closeout self-check**: **before merging**, verify that none of the four `workflow/` directories contain in-flight items that should have been closed in this batch (anything still `draft`/`approved` on the merge tree must be closed before merging)
+**Output**: evidence that the closed-loop audit passed
+
+## 3. Regression & DB
+1. **Path verification**: all key paths of the affected modules in `workflow/regression-checklist.md` pass
+2. **Automated verification**: all project test cases pass (do not skip failing cases); recurrence-prevention entries for historical incidents of the same kind pass one by one
+3. **DB change (L3 special case)**: migration SQL $\leftrightarrow$ entity mapping consistent; record [backup point] + [rollback SQL path]; **the rollback SQL must have been executed in a dev rehearsal** (not rehearsed $\rightarrow$ treated as having no contingency plan $\rightarrow$ **HALT**)
+
+## 4. Authorization & PR
+1. **User authorization**: only accept the user themself saying "上" (go) or an equivalent confirmation in the conversation
+2. **PR creation**: the panel-review trigger policy follows `.agents/commands/pr-review.md` (run it only when its trigger rules are met), then `node .agents/scripts/pr-create.mjs create --source <branch> --target <target> --title "<Conventional Commits in Chinese>" --body-file <file>` — the description carries the three Test evidence items (Summary / Evidence / Merge Danger, format in `review.md`); the automated review gate is retired (2026-11-09), and pr-create only delegates to tfs-pr; if a manual panel review was run, append one line to Evidence: `面板评审：<runId>（Important n / Nit n / Pre-existing n）`
+3. **Review**: graded review per `.agents/commands/review.md` (logic $\rightarrow$ security $\rightarrow$ against spec/plan) — do not merge if the review fails
+4. **Merge record**: record the PR number + merge commit SHA; release pipeline execution (if any) is manually approved by the user on the platform
+**Output**: PR review record + merge SHA
+
+## 5. Closeout & Fallback
+1. **Archive**: archiving of the terminal-state family is done automatically by the `confirm-doc` closeout; this stage verifies that archiving occurred
+2. **Exception fallback**: post-release exception $\rightarrow$ `workflow/incidents/` $\rightarrow$ `maintain.md` (the user decides the stop-the-bleeding plan; no cross-agent collaborative push of fixes)
+
+## 🚫 Prohibitions
+| Operation | Consequence | Exception |
+|---|---|---|
+| Rollback without rehearsal | $\rightarrow$ treated as no contingency plan | Must verify rollback SQL in dev |
+| Bypass test closeout | $\rightarrow$ blocks merge | Documents must be set to done in the test stage first |
+| Merge with failed review | $\rightarrow$ violates gate prerequisites | No merging while P0 is nonzero |
+| Delegate rollback decisions | $\rightarrow$ violates security policy | Rollback decisions must involve the main Agent + the user |
+
+## 🛠️ Auxiliary Tools
+Version rollback = platform-side revert of the merged PR/commit

package/locales/en/overrides/.agents/commands/maintain.md

@@ -0,0 +1,76 @@
+---
+description: "Maintain stage: file an incident + retrospective trio (fix / recurrence prevention / rule entry)"
+stage: Maintain
+triggers:
+  - "file an incident"
+  - "production is down"
+  - "log an incident"
+  - "something broke, root cause xxx"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: the user has chosen the stop-the-bleeding or structural fix plan, the reproduction path and authorized files are clear, and the task meets the role contract
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/stages.md Plan chapter (if the retrospective needs a new intent)
+---
+
+# Maintain · File an Incident + Retrospective Trio
+
+For L1 that is not a production incident, a recurrence, data, or a contract change: do only §1 (file the document), then return to `.agents/commands/new-task.md` §L1 Fast Track. §0 stop-the-bleeding and §2 the retrospective trio are reserved for production incidents and L2/L3. An incident must still be filed.
+
+## 0. Active Incident (Emergency Stop-the-Bleeding)
+**Input**: failure symptoms / logs
+**Process**:
+1. **Diagnose**: read logs + code $\rightarrow$ provide [stop-the-bleeding options (revert/rollback/hotfix/degrade)] + [impact surface / time cost]
+2. **Execute**: the user decides the plan $\rightarrow$ AI only executes the chosen plan (no self-initiated pushing of fixes)
+3. **Verify**: after the hotfix, run `node .agents/scripts/verify.mjs --scope` (policy in the header note)
+**Output**: service restored $\rightarrow$ enter the retrospective flow
+
+## 1. Draft the Incident
+**Input**: failure context after stop-the-bleeding completes
+**Process**:
+1. **Similar-case search**: `node .agents/scripts/kb-search.mjs "<keyword>" --scope workflow --type incidents` $\rightarrow$ cite existing recurrence-prevention entries
+2. **Create document**: copy `_TEMPLATE.md` $\rightarrow$ `workflow/incidents/{name}.md`
+3. **Fill in content**: [timeline (discovery$\rightarrow$recovery)] / [impact surface] / [root cause (underlying reason)] / [gate-failure analysis]
+**Output**: `workflow/incidents/{name}.md` (Status: Draft)
+
+## 2. Draft the Retrospective Trio (The Trio)
+**Requirement**: all three items are mandatory; recurrence-prevention commitments must not remain only in documents.
+**Process**:
+1. **Structural fix**: record [fix commit SHA + file list] $\rightarrow$ decide whether a new intent is needed (if the root cause is a missing gate / unimplemented rule $\rightarrow$ mandatory `workflow/intents/`). **Attack the premise**: when under the same premise two fix approaches both fail the same verification, stop and write down the premise itself and test it directly — prevent "reskinned fixes" from slipping through the retrospective
+2. **Recurrence-prevention verification**: must land as [automated test case / `stages.md` Test chapter step / `regression-checklist.md` entry]; from the day a fixed/closed document is filed, check-loop §3x hard-blocks "no automated test case / regression-checklist reference" (no "manually verified")
+3. **Rule entry**: landing priority order: `regression-checklist.md` $\rightarrow$ `hooks/` $\rightarrow$ `skills/` $\rightarrow$ `notes/` $\rightarrow$ `commands/` (root `AGENTS.md` is prohibited). **Fix-strength ladder**: the landing order is positional; strength is judged separately — architectural consolidation/hooks/CI > automated test cases > rule text; when landing as rule text, the retrospective must state "why the stronger tier cannot block it"
+**Output**: landing verification plan + rule change record
+
+## 3. Confirmation & Landing
+This section starts from production incidents and L2/L3.
+**Process**:
+1. **HALT**: output the incident + trio drafts $\rightarrow$ wait for user confirmation
+2. **Stepwise confirmation**: incident draft / spec / plan confirmed independently (no combining)
+3. **Pre-check**: before L2/L3 confirmation $\rightarrow$ `fill-spec`/`confirm-doc` verifies that "the timeline includes user confirmation" is recorded $\rightarrow$ if not, backfill
+4. **Landing execution**:
+   - **Pair with plan**: must create a same-named `workflow/plans/{name}.md` (incident $\equiv$ intent, but plan cannot be omitted)
+   - **Implement the fix**: L1 $\rightarrow$ return to `.agents/commands/new-task.md` §L1 Fast Track (the same-named L1 plan is the entry; do not enter `stages.md`); L2/L3 $\rightarrow$ `stages.md` Design $\rightarrow$ Build $\rightarrow$ Test chapters
+   - **Land the trio**: execute the verification and rule changes from §2
+**Next**: if systemic issues need tracking $\rightarrow$ `.agents/commands/stages.md` Plan chapter to file a new intent
+
+## 4. Closeout After Confirmation
+**Process**:
+1. **Status transitions**: `open` $\rightarrow$ `fixed` (trio landed) $\rightarrow$ `closed` (recurrence-prevention verification passed)
+2. **State entry point**: `confirm-doc.mjs` migrates step by step (policy in `new-task.md` Fast Track step 4)
+3. **Reconciliation**: `check-loop 15` verifies the order of [closeout edit $\rightarrow$ closed confirmation]
+4. **Ruling backfill after closeout**: if a done/closed document genuinely needs a ruling backfilled $\rightarrow$ change the body and in the **same batch** append a **re-confirmation compensation line** to `.agents/confirmations.jsonl` — same doc+stage, fingerprint = post-edit content fingerprint (bindingSha256), prev uses the original line, quote = the user's ruling verbatim (source: chat-delegated); append-only, do not alter historical lines; check-loop 15 takes effect based on the last done line (re-confirmation scenario). Note that `confirm-doc` has no forward transition for terminal-state documents, so append the compensation line directly to the ledger. **Generator**: `node .agents/scripts/append-compensation.mjs <doc...> --quote "<user's verbatim words>"`; hand-crafted hashes are blocked by the s15 content-drift gate
+
+## 🚫 Prohibitions
+| Operation | Consequence / machine behavior | Exception |
+|---|---|---|
+| Commitment stays in documents | $\rightarrow$ treated as not closed | Must land as code/script/checklist |
+| Landing in root AGENTS | $\rightarrow$ violates single-source discipline | Must push down to notes/commands/hooks |
+| Single-hop status | check-loop 15 blocks | Must be fixed $\rightarrow$ closed |
+| Editing the body after closeout without backfill | check-loop 15 fingerprint-drift block | Ruling backfill must include re-confirmation compensation lines in the same batch (see §4.4) |
+
+## 🛠️ Auxiliary Tools
+- **Root-cause diagnosis**: `diagnosing-bugs` diagnostic loop
+- **Incident triage**: `triage` state-machine approach

package/locales/en/overrides/.agents/commands/new-task.md

@@ -0,0 +1,89 @@
+# New Task · Closed-Loop Entry Point
+
+> **⛔ Order**: grade first → file the trio first → confirm each item → only then write code. "Change first, document later" is prohibited (= bypassing the confirmation gate; violators record both incident+papercuts). Details and strength rationale: `.agents/notes/process-order-rule.md`.
+
+## 1. Risk Grading (Step 0: Grade Before Routing)
+
+| Lane | Level | Criterion | Confirmation & audit policy |
+|---|---|---|---|
+| **Coordination lane** | **L1** implementation | Implementation-level change that misses L2/L3 | A single plan is the entry point (source / goal / red lines / changes / verification / acceptance). No separate intent. No synchronous prerequisite for independent review; `--batch` is L1-only |
+| **Defense lane** | **L2** rule/contract | See §L2 closed set | Synchronous confirmation gates: spec confirmation $\rightarrow$ plan confirmation $\rightarrow$ start work |
+| | **L3** data/runtime structure | schema / migration SQL / DI chain / auth and middleware pipeline | Same as L2 + spec independently reviewed in a new session; no go-ahead until confirmed |
+
+> **Two-question grading**: structural surface (schema / migration SQL / DI / auth pipeline) → L3; contract or shared policy → L2; neither → L1. Do not slide upward from L1 based on severity.
+> **Question typing**: if it can be run/checked out (behavior/timing/layout/output/existing data/eval distinguishable), prototype/query the DB/run eval first; do not stop to ask. Only product/preference judgments escalate to confirmation. Orthogonal to the STOP line (experimentation does not exempt red lines).
+> **Placement**: L1 is written into the plan frontmatter `级别`; L2/L3 into the intent.
+> **Under-grading block**: if an L1 plan or intent checks a touched red line → check-loop "red-line under-grading" hard block → escalate to L2/L3 and add a same-named spec.
+
+### L2 Touched Surface (Closed Set; Hitting Any One Means L2)
+
+| # | Category | Criterion |
+|---|---|---|
+| 1 | **Coding authority** | Coding/naming/numbering rules generated once and consumed in many places |
+| 2 | **Shared contract** | Cross-module shared base classes / DTO shapes / public interface signatures |
+| 3 | **Existing interface semantics** | Behavior changes to existing parameters or endpoints (disabled becomes enabled, default/clamping policy changes) |
+| 4 | **Global cross-cutting policy** | Error response exit points, pagination and validation policy, aggregate projection keys |
+
+> **Negative examples (fall to L1)**: pure page presentation/copy/layout/interaction implementation; purely new endpoints or parameters with unchanged behavior; single-module internal refactoring with no external contract change; purely new pages/routes with no shared contract; single-module internal component splitting; module-internal new types/constants not consumed across modules.
+> **Self-check sentence**: can you list $\ge 2$ actual consumers whose behavior is affected (module/endpoint/page; signature-only visibility with unchanged behavior does not count)? If yes $\rightarrow$ L2.
+> **Default tier**: if no red line is checked, it is L1. Grading only answers "does it hit the four L2 categories or an L3 structural surface".
+
+## 1b. Todo Seeding
+
+After grading and before starting work, **copy verbatim** the step headings of the chosen command into the first item of the todo list; do not write a separate summary. Keep skipped steps in the list and write `skip: <reason>`. The todo is the execution contract; the command file is the playbook — this page does not duplicate the step body (single source).
+
+## 1c. Stage Coupling Protocol (Load on Entry + Auto-Chaining)
+
+- **Load on entry**: when entering any stage command, first read the SKILL.md of the skill bound to that stage (the body lives single-source on the skill side; this table only holds pointers):
+
+| Stage | Load on entry |
+|---|---|
+| Plan (intent) | `grilling` (questioning to solidify background/goals/non-goals) |
+| Design (spec) | `grilling` (ambiguity checklist / solution stress test); `codebase-design` / `domain-modeling` as needed; `arena` for branching comparison; required inputs see `stages.md` Design §2 |
+| Build | No mandatory skill (implementation delegation goes through the `implementer` role) |
+| Test | `verify-ui` for frontend changes; `review-method` for L2/L3 independent review |
+| Deploy | None (follow the checklist and the go-live authorization gate) |
+| Maintain | `why` (root-cause evidence chain) |
+| Review (cross-cutting) | `review-method`; `interrogate` for high-risk diffs; `blast-radius` for impact surface |
+
+- **Auto-chaining**: after a stage completes (confirmation gate passed + trace commit landed), **automatically proceed to the next-stage command pointed to by the frontmatter `next`** without waiting for the user to prompt.
+- **Human gates are never crossed automatically**: automatic flow refers only to stage chaining and skill loading — every stage's HALT confirmation, pipeline-run's `await-confirm`, and go-live authorization (deploy's "上") stop at their points and wait for the user's verbatim go-ahead.
+
+## L0 Minimal Path
+
+Criteria (all machine-checkable): product surface ≤5 files; misses the §1 L2 closed set/L3 structural surface; not a data-maintenance SQL execution; no new dependencies/build steps (the engine/wiki surface is already exempt).
+Overlapping criteria: take L0.
+Flow: grade → change code → `node .agents/scripts/verify.mjs --face`/`--scope` green → single commit; the message body includes a line `L0: <criterion>` (machine-greppable).
+
+## L1 Fast Track
+
+If L2 or L3 is hit, leave this page. L1 stops at the following 6 steps and does not open `stages.md`.
+
+> **Takeover/resume**: first read `.agents/skills/session-resume/SKILL.md` to rebuild the current state, then follow the 6 steps below.
+
+1. **Grade**: use the two questions in §1 and the L2 closed set. If nothing is hit, it is L1; write `级别` in the plan frontmatter. Completion criterion: the level in the plan header matches the two-question conclusion.
+2. **Search**: `node .agents/scripts/kb-search.mjs --scope workflow --module <module> "<keyword>"`. Write the root causes of hit incidents into the self-check of the plan in the next step. Completion criterion: the command was run; hit root causes are prepared for the plan, and with no hits it is enough to paste the script output (no separate explanation needed). Hit same-feature spec / features $\rightarrow$ modify the original per `workflow/README.md` "same-feature continuation" instead of creating new.
+3. **File the plan**: `node .agents/scripts/fill-plan.mjs --level L1 --topic <topic> --output workflow/plans/<YYYY-MM-DD>-<topic>.md`. `--lite` may be added (three sections: entry / change approach / verification and acceptance; conditions: step 2 search has no incident hits and no red line is checked); the default remains five sections. Fill in the entry (source, goal, red lines), change approach, constraints and risks, verification plan, acceptance criteria, and write the step 2 search results into the self-check. Change the frontmatter `模块` to the leading module. Do not write an intent, do not write prediction fields. Completion criterion: each section of the chosen template has a body (five sections or lite's three), the search conclusion is in the plan; if acceptance cannot be written as a testable criterion, stop; red lines are either checked and escalated to L2/L3, or explicitly unchecked.
+4. **Start after confirmation**: `node .agents/scripts/confirm-doc.mjs <plan> --delegated "<user's verbatim words>"` moves draft to approved (confirmation gate policy single-source: call per item, no combining; use each item's own verbatim words, no reuse; migrate step by step, no single hop), then change code. Only change files listed in the plan. Four red lines: do not commit secrets or `.env`, do not use `--no-verify`, minimal change, stop first when deviating from the plan. **Commitment-surface lock**: after approval, changing the "commitment surface" (acceptance criteria text / red lines / goal / change approach) requires the user to nod again and re-record the commitment-surface fingerprint — the re-confirmation password is in `workflow/README.md` "commitment-surface binding"; otherwise closeout is rejected and push is hard-blocked by check 15 (checking acceptance + backfilling evidence does not count as changing commitments). Do not commit separately after changes: once verification (step 5) is green, jump to done per step 6 and commit in the same commit as the code. Before changing code, open the /tour overview and refresh it every batch (skills/dev-tour). Completion criterion: changes remain in the working tree, and the plan is still approved.
+5. **Verify**: `node .agents/scripts/verify.mjs --scope` (policy in the header note). If there are frontend changes, also open `.agents/skills/verify-ui/SKILL.md`. If it fails, change the code; do not change the gate on this page. Completion criterion: command exit code 0, and frontend changes additionally have measured evidence.
+6. **Closeout = single commit**: `node .agents/scripts/confirm-doc.mjs <plan> --delegated "<user's verbatim words>"` jumps one more step to move approved to done, then make a single commit — plan(done) + code + confirmation shard + verify credentials land in one commit; L1 has no separate closeout commit. Only in the plan-independent-closeout scenario (code already landed in a previous commit) open `.agents/skills/shipyard-workflow-closeout/SKILL.md`. Completion criterion: the plan is done and the single commit has landed.
+
+Only then open other files: delegate implementer → `stages.md` Build §3; changed DB connection → `stages.md` Test §2; full-suite first run red, isolated rerun green → `stages.md` Test §1; L2/L3 independent review → `stages.md` Test §4.
+
+## 2. Level Sub-Routing (Pointer Only)
+
+Task-type routing **single source** = root `AGENTS.md` §4. Fix-type level routing **single source** = `.agents/commands/maintain.md` §3 (after L1 files the document, return to this page §L1 Fast Track; L2/L3 go to `stages.md` Design → Build → Test chapters; if the root cause is a missing gate/rule, file a same-named intent separately).
+
+## 3. Intent Exemption Rules
+
+| Scenario | Criterion | Handling |
+|---|---|---|
+| **AI-Native engine surface** | Root `AGENTS.md` §4 engine-surface exemption policy | Exempt from the trio (intent/spec/plan and confirmation gates); commit directly with Conventional Commits; parts touching business code follow their level |
+| **wiki document adjustment** | Root `AGENTS.md` §4 "wiki exemption" | Exempt from the trio (intent/spec/plan and confirmation gates); commit directly with `docs(wiki)`; execution of data-maintenance SQL and business code are not exempt |
+| **bootstrap-type changes** | Introducing the rules themselves | Exempt from intent; explicitly declare `bootstrap` in the commit message |
+
+## 4. Closed-Loop Backstop
+
+- **Gate checklist**: refer to the header comments of `.githooks/` / `.agents/hooks/` / `.agents/scripts/check-loop.mjs` (not restated here).
+- **hard-block**: checklist single source = check-loop header comment; pairing breaks and loop gaps have been downgraded to WARN; self-check goes through closeout skill §0.
+- **Prohibition**: local hooks are local machine gates; `--no-verify` is prohibited (see root `AGENTS.md`).