agentic-flow-kit 1.8.7 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 agentic-flow-kit contributors
+Copyright (c) 2026 dc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,175 +1,209 @@
 # 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 / 技能接线），按各宿主原生规范落盘。
+- 技能单源：技能正文只保留在 `.agents/skills/`；原生支持技能的宿主生成指针壳，其余宿主生成 `wf-skills` 索引。
+- 模型按角色配置：安装时探测宿主配置 / 环境变量（可选只读 CLI），按 `code` / `judgment` / `review` 推荐，也可 `--model` 或 TUI 手填。
+- 可选语言：`--lang zh-CN`（默认）或 `--lang en`；语言包覆盖文档、提示词、记忆文件、脚手架与安装器输出。
+- 幂等升级：`.agents/install-manifest.json` 记录版本、宿主、语言与文件哈希；冲突默认跳过，`--force` 才覆盖。
+- 交互式 TUI 向导：交互终端不带参数直接运行进入菜单（安装 / 升级 / 追加宿主 / 体检 / 宿主列表），零依赖；非交互终端自动降级为编号问答或打印帮助。
 
-## 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 秒路径
+在目标项目根运行：
 
 ```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，然后提交。配对没齐、验收没勾、确认指纹对不上，钩子会拒绝这次提交。
+npx agentic-flow-kit 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 是后链全部文档的种子；存量无标记零回溯）。解决后把行首改成 `- 已澄清：`（保留行，留痕曾不清楚过）或删行。
+从本仓库源码运行时，把 `npx agentic-flow-kit` 换成 `node <仓库路径>/bin/flow-kit.mjs`。
 
-**关于「确认门」的诚实边界**：确认门是**留痕机制，不是防伪机制**。`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 首跑种子；存量不补跑则该门红一次，补跑即绿）。
-
-## 快速开始
+也可以用交互式向导：在交互终端不带任何参数直接运行，进入 TUI 菜单，按提示选宿主 / 语言 / 栈与开关：
 
 ```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
 ```
 
-## 执行面：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
+npx agentic-flow-kit 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` | 覆盖已存在的同名文件（默认保守跳过） |
+|---|---|
+| `--target <dir>` | 目标项目根，默认当前目录 |
+| `--lang zh-CN\|en` | 语言包，默认 `zh-CN` |
+| `--stack dotnet\|node\|typescript\|rust\|go\|java\|empty` | 项目栈 profile；缺省按根目录标记探测：`.sln`/`.csproj` → dotnet，`Cargo.toml` → rust，`go.mod` → go，`pom.xml`/`build.gradle` → java，`tsconfig.json` → typescript，`package.json` → node |
+| `--tier lean\|standard\|enterprise` | 安装档位。`lean` 不生成 CI，适合小项目；`standard`（默认）生成 CI；`enterprise` 另启用加固配置（sandbox / 凭据读拒绝 / MCP 白名单 / 版本基线） |
+| `--hardened` | 等价于 `--tier enterprise`；加固配置写入 `.claude/settings.json`，其中 managed-only 键需由平台/IT 以 managed settings 部署才不可覆盖 |
+| `--name <name>` | 渲染 `{{projectName}}`，默认目标目录名 |
+| `--dry-run` | 只打印计划，不写盘 |
+| `--force` | 覆盖冲突/非本工具安装的既有文件 |
+| `--no-git-config` | 不自动写三条例行 git 配置 |
+| `--track-hosts` | 不把本机宿主目录写进 `.gitignore` |
+| `--model [host:]role=<id>` | 可重复。指定模型角色；`role` 为 `code` / `judgment` / `review`，省略宿主则全局生效 |
+| `--model-mode recommend\|detect\|inherit` | `recommend`（默认，探测 + 推荐）、`detect`（强制重新探测）、`inherit`（全部继承宿主默认） |
+| `--probe-models` | 允许执行宿主注册表中声明的只读模型列表命令（1.5s 超时，失败静默） |
+| `--no-model-config` | 跳过模型探测 / 注入，也不写 `.agents/config/model-roles.local.json` |
+
+## 宿主
+
+v1 支持 10 个现行宿主：
 
-init 不问项目名 / 描述：`AGENTS.md` 只生成「AI工作流 + Wiki」两章骨架 + 「项目适配区」；技术栈经 `--stack` 传入只用于门禁配置（编译检查与自检验命令初值），密钥白名单等其余细节在 `.agents/hooks/commit-check.config.json` 里按项目填。
+| 宿主 | 命令 | 子代理 | 技能 | hooks | 模型注入 |
+|---|---|---|---|---|---|
+| `trae` | `.trae/commands/` | `.trae/agents/*.md` | index → `wf-skills` | `hooks.json` | 否 |
+| `codebuddy` | `.codebuddy/commands/` | `.codebuddy/agents/*.md` | native `.codebuddy/skills/<name>/SKILL.md` | `settings.json` | 否 |
+| `claude` | `.claude/commands/` | `.claude/agents/*.md`（`model`） | native `.claude/skills/<name>/SKILL.md` | `settings.json` | 是（`inherit` / 别名） |
+| `opencode` | `.opencode/commands/` | `.opencode/agents/*.md`（`model`） | native `.opencode/skills/<name>/SKILL.md` | 插件式（保持现状） | 是（省略 = 继承） |
+| `qwen` | `.qwen/commands/` | `.qwen/agents/*.md`（`model`） | shared `.agents/skills`（不复制） | `settings.json` | 是（`inherit`） |
+| `pi` | 无 | `.pi/agents/*.md`（`model`） | index → `.pi/SKILLS.md` | `extensions/` | 是（网关 ID，无 `inherit`） |
+| `cline` | `.cline/workflows/` | `.cline/agents/*.yml` | index → `wf-skills` | `hooks/` 适配器 | 否 |
+| `commandcode` | `.commandcode/commands/` | `.commandcode/agents/*.md`（`model`） | shared `.agents/skills`（不复制） | `settings.json` | 是（`inherit`） |
+| `qoder` | `.qoder/commands/` | `.qoder/agents/*.md` | index → `wf-skills` | `settings.json` | 否 |
+| `zcode` | `.zcode/workflows/*.dwf.ts` | `.zcode/agents/*.md` | index → `wf-skills` | `config.json` | 否 |
+
+宿主壳全部是指针壳：正文权威仍在 `.agents/commands/`、`.agents/roles/`、`.agents/skills/`，安装器不复制正文，避免双源漂移。
+
+技能安装分三种模式（由注册表 `skills.mode` 驱动）：
+
+- **native**：宿主会自行发现 `<宿主目录>/skills/<name>/SKILL.md`。安装器按 `.agents/skills/*/SKILL.md` 的语言覆盖后内容动态生成指针壳（原生 frontmatter + 指向权威正文），不手写 22 × N 份静态副本。
+- **shared**：宿主原生读取 `.agents/skills`（Qwen、Command Code）。不生成宿主技能副本，只生成 `wf-skills` 索引入口。
+- **index**：无法确认原生技能目录的宿主生成一个索引（有命令目录时是 `wf-skills.md`，否则是 `SKILLS.md`），逐行列出技能名、描述与 `.agents/skills/<name>/SKILL.md` 路径。
+
+## 模型配置
+
+安装器按三个角色为子代理选模型：
+
+| 角色 | 用途 | 典型分工 |
+|---|---|---|
+| `code` | 实现 / 改代码 | 低成本、高吞吐（如 `haiku` / `sonnet`） |
+| `judgment` | 判断 / 规划 / 仲裁 | 强推理（如 `opus`） |
+| `review` | 独立复核 | 强推理，且建议与 `code` 不同 |
+
+解析优先级（高 → 低）：
+
+1. CLI `--model [host:]role=<id>`
+2. TUI 交互选择
+3. 已存在的 `.agents/config/model-roles.local.json`（宿主级 > 角色级）
+4. 探测 + 内置推荐
+5. 宿主 `inherit`
+
+探测来源：
+
+- 宿主配置：如 `~/.claude/settings.json`、`~/.qwen/settings.json`（JSONC 容错）。
+- 环境变量：如 `ANTHROPIC_MODEL`、`CLAUDE_CODE_SUBAGENT_MODEL`、`QWEN_MODEL`。
+- 只读 CLI：仅注册表中声明且已核实的命令（当前为 Command Code 的 `--list-models`）；默认不执行，交互安装或 `--probe-models` 才启用，1.5s 超时，失败静默。
+- 内置推荐：只写已核实的别名（当前仅 Claude 的 `sonnet` / `haiku` / `opus`），不合成未知模型 ID。
+
+解析结果写入 `.agents/config/model-roles.local.json`（用户所有，不进 manifest、升级不覆盖）；宿主子代理的 `model` 字段在渲染与语言覆盖之后注入，manifest 哈希记录最终文本。升级时若本地配置缺失（例如被 gitignore 后换机），会从已安装子代理的 `model` 字段回收，避免把用户已配置的模型静默改回 `inherit`。仅注册表声明了 `agents.modelField` 的宿主会注入；其余宿主只在输出与本地配置中记录角色模型，并提示该宿主不支持按角色指定子代理模型。
+
+`review` 与 `code` 解析为同一模型时给出 `REVIEW_SAME_AS_CODE` 警告（不阻断安装）；`doctor` 也会对现有配置做同样提示；本地配置与已安装子代理的 `model` 字段不一致时，doctor 报 `model drift`，要求先按 `.agents/skills/model-upgrade/SKILL.md` 评测再升级。
+
+## 治理、评测与记忆
+
+安装后的引擎在静态门之外还带一层 AI-Native 治理面（全部零依赖）：
+
+| 面 | 入口 | 作用 |
+|---|---|---|
+| 行为评测 | `.agents/scripts/agent-eval.mjs` + `.agents/skills/eval/` | 技能/命令/角色/模型变更后，用固定任务集跑 A/B，凭证绑定“评测敏感面”的内容签名；CI 先 `--advisory`，稳定后转硬门 |
+| 测试不可弱化 | `.agents/hooks/pre-write-check.cjs` §2.5 + `fix-task.mjs` | 修复窗口内禁改既有测试；新建复现测试放行；`TEST-GUARD-ALLOW:` 留逃生口 |
+| 离线梦境 | `.agents/scripts/dream-run.mjs` | 归档、索引、主张依据、**经验回放**、**记忆表示**、**注入层预算**、结果指标 |
+| 经验日志 | `.agents/scripts/session-log.mjs` | 记录 failure/correction/refusal，供 dreaming 对照纠错 |
+| 记忆表示 | `.agents/scripts/memory-wiki.mjs` | 从 claims/incidents/session-logs 生成 `wiki/_memory/` 链接地图 |
+| 注入层预算 | `.agents/scripts/memory-tier.mjs` | 200 行 / 25KB 上限；只出上浮候选，不自动改 |
+| 单写者租约 | `.agents/scripts/path-lease.mjs` | 并行 agent 写同一页面前加租约，防共享页丢事实 |
+| 结果指标 | `.agents/scripts/outcome-metrics.mjs` | 首次过门率、复核采纳率、逃逸缺陷、评测通过率、返工占比 |
+| 闭环状态机 | `.agents/scripts/check-pipeline-state.mjs` | stage/stopType 闭包检查；真实端到端 run 仍需小任务验证 |
+
+`--tier standard`（默认）会生成 `azure-pipelines.yml` 与 `.github/workflows/ci.yml`，在 `verify --full` 之后跑上述 advisory 检查；`lean` 不生成 CI，`enterprise` 另装加固配置。未完成项与验收口径见 [BACKLOG.md](BACKLOG.md)。
+
+## 模板 / Profile / State 三层
+
+| 层 | 位置 | 内容 |
+|---|---|---|
+| engine | `templates/engine/` | `.agents/` 通用引擎（commands / skills / roles / hooks / scripts / config / pipelines / tests / board / notes） |
+| profile | `templates/profiles/<stack>/` | 栈相关 `AGENTS.md`。栈：`dotnet` / `node` / `typescript` / `rust` / `go` / `java` / `empty` |
+| scaffold | `templates/scaffold/` | `wiki/` 目录骨架 + INDEX + 看板；`workflow/` 状态机骨架 + 空台账 + `_TEMPLATE.md` |
+| git | `templates/git/` | `.githooks/` 五钩子、`.gitattributes` 合并块、`.gitignore` 运行态块 |
+| host-meta | `templates/host-meta/` | 宿主原生技能指针 / 技能索引模板；按能力动态生成，不参与 `templates/hosts/` 静态枚举 |
+| locale | `locales/<lang>/overrides/` | 按目标路径镜像的语言覆盖；缺省回退模板 |
+
+运行态（`cache/`、`tmp/`、`*.jsonl` 台账、`confirmations.d/`、`workflow/archive`、`.agents/tools/`）不打包，由引擎在装户内产生。
+
+## 冲突与升级
+
+- 目标文件不存在 → 创建。
+- 目标文件存在且哈希等于 manifest → 更新。
+- 目标文件存在但哈希不等于 manifest（装后被改）→ 冲突跳过；`--force` 覆盖。
+- 目标文件存在且不在 manifest（非本工具安装）→ 跳过；`--force` 覆盖。
+- `.gitattributes` / `.gitignore` 用带标记的合并块，重复执行不会重复追加。
 
-## 装了什么
+## 语言
 
-```
-.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 参考实现，装进项目后归项目）
-```
+- `zh-CN`：模板原文即中文。
+- `en`：`locales/en/overrides/` 覆盖命令、角色、技能入口、宿主指针壳、记忆文件、`wiki`/`workflow` 脚手架与安装器输出。
+- 机器协议与锚点（例如 `wiki/INDEX.md` 的生成锚点、`_TEMPLATE.md` 的节标题）保持中文原样，避免破坏生成器与门禁解析；英文包只翻译人类可读面。
+- `runtime-env.md`、`gate-diet.md` 等环境/历史长文暂回退中文；按需在 `locales/en/overrides/.agents/notes/` 补译。
 
-**两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
+## 迁移与 parity
 
-## CI 远端门与离线安装
+本工具的模板由 `tools/extract-from-project.mjs` 从现行仓一次性提取；`tools/parity-report.mjs` 只读对比模板与现行引擎/宿主/git 面。当前结果：
 
-**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…）等价接入 = 同一入口命令 + 服务端分支策略：
+- 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`/`typescript` 在 `package.json` 有 `test` 脚本时追加 `npm test`，`rust` 追加 `cargo test`，`go` 追加 `go test ./...`，`java` 按 `pom.xml` 或 Gradle 追加测试门；
+  5. `.githooks/pre-push`：宿主接线面扩到 10 宿主；
+  6. `.agents/board/dev-tour.html`：项目名改为 `{{projectName}}` 占位；
+  7. `check-ledger-invariant.mjs`：本仓历史基线哈希在新仓解析不出时按无基线处理，避免装户报警。
+- `verify-ui/features/` 是装户业务特性地图，只保留空目录占位，不随通用引擎打包。
 
-```bash
-node .agents/scripts/verify.mjs                    # 远端门本体（工程在子目录时加 --test-cmd "<项目测试命令>"）
-npx agentic-flow-kit validate --strict --json      # 可选加一道：包内置引擎只读结构校验（warning 也判红，stdout 机器可读）
-```
+本仓迁移策略：先保留现行 `.agents`/`.githooks`/宿主目录；其他项目安装验证完成后，再在本仓卸载现行引擎并安装本工具（届时用 `--force` 采用现有文件）。
 
-真正的「门」在服务端分支保护（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
+node tools/extract-from-project.mjs --project 项目目录   # 重新提取模板（一次性迁移工具）
+node tools/make-en-host-overrides.mjs                                     # 重新生成英文宿主指针壳
+node tools/parity-report.mjs --project 项目目录          # 对比现行引擎
+node --test tests/*.test.mjs                                              # 安装器测试
 ```
 
-`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 已收敛到单源）。
-
-当前语义四点：
+```
+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/
+```
 
-- **门禁面**：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`。
+[MIT](LICENSE) © dc

package/bin/flow-kit.mjs

@@ -1,4 +1,9 @@
 #!/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) => {
+  // 预期内的用户错误（code 已标注）只打印消息；未预期错误保留堆栈便于定位。
+  if (err?.code) console.error(err.message);
+  else console.error(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});

package/locales/en/installer.json

@@ -0,0 +1,110 @@
+{
+  "help": "agentic-flow-kit v{{version}}\n\nUsage:\n  flow-kit install --agent <host> [--agent <host>...] [--lang zh-CN|en] [--stack dotnet|node|typescript|rust|go|java|empty] [--tier lean|standard|enterprise] [--hardened] [--target <dir>] [--model [host:]role=<id>] [--model-mode recommend|detect|inherit] [--probe-models] [--no-model-config] [--dry-run] [--force] [--no-git-config] [--track-hosts]\n  flow-kit add-host <host> [--target <dir>] [--model [host:]role=<id>] [--model-mode recommend|detect|inherit] [--probe-models] [--no-model-config] [--dry-run] [--force]\n  flow-kit upgrade [--target <dir>] [--model [host:]role=<id>] [--model-mode recommend|detect|inherit] [--probe-models] [--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\nModel roles: code (implementation) / judgment (reasoning) / review (independent verification; prefer different from code)\n\nExample:\n  node cli-tools/agentic-flow-kit/bin/flow-kit.mjs install --agent claude --lang en --model claude:code=haiku --model claude:review=opus --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.badModel": "Invalid --model: {{value}} (expected [host:]role=<id>; roles: code / judgment / review)",
+  "error.noManifest": "Engine is not installed in the target; run install first",
+  "error.noHostsInManifest": "No hosts recorded in manifest; run install first",
+  "error.badTier": "Invalid --tier: {{value}} (expected lean / standard / enterprise)",
+  "listHosts.title": "Supported hosts:",
+  "tui.title": "agentic-flow-kit wizard",
+  "tui.menuQuestion": "Select an action",
+  "tui.menu.install": "Install",
+  "tui.menu.upgrade": "Upgrade",
+  "tui.menu.addHost": "Add host",
+  "tui.menu.doctor": "Doctor",
+  "tui.menu.listHosts": "List hosts",
+  "tui.menu.quit": "Quit",
+  "tui.hint.moveEnter": "Up/Down to select, Enter to confirm",
+  "tui.hint.toggle": "Space to toggle, Enter to confirm",
+  "tui.hostsQuestion": "Select hosts to install",
+  "tui.langQuestion": "Select language",
+  "tui.stackQuestion": "Select stack",
+  "tui.optsQuestion": "Select install options",
+  "tui.opt.gitConfig": "Configure git gates (recommended)",
+  "tui.opt.dryRun": "dry-run: print the plan only, write nothing",
+  "tui.opt.force": "Force overwrite conflicting files",
+  "tui.detected": "detected",
+  "tui.detectedFile": "detected {{file}}",
+  "tui.stack.dotnet": ".NET",
+  "tui.stack.node": "Node.js",
+  "tui.stack.typescript": "TypeScript",
+  "tui.stack.rust": "Rust",
+  "tui.stack.go": "Go",
+  "tui.stack.java": "Java",
+  "tui.stack.empty": "Unspecified",
+  "tui.currentStack": "current",
+  "tui.upgradeStackQuestion": "Select the stack for this upgrade",
+  "tui.installed": "installed",
+  "tui.planTitle": "Install plan",
+  "tui.plan.target": "Target: {{target}}",
+  "tui.plan.hosts": "Hosts: {{hosts}}",
+  "tui.plan.lang": "Language: {{lang}}",
+  "tui.plan.stack": "Stack: {{stack}}",
+  "tui.confirmInstall": "Start install?",
+  "tui.confirmUpgrade": "Start upgrade?",
+  "tui.askDoctor": "Run doctor right after install?",
+  "tui.running": "Running…",
+  "tui.done": "Done",
+  "tui.dryDone": "Dry-run done, nothing written",
+  "tui.doctorQuestion": "Select doctor mode",
+  "tui.doctor.normal": "Standard checks",
+  "tui.doctor.deep": "Deep checks (includes check-local-gates)",
+  "tui.addHostQuestion": "Select hosts to add",
+  "tui.backOrQuit": "Back to menu?",
+  "tui.errorTitle": "Error",
+  "tui.yes": "Yes",
+  "tui.no": "No",
+  "tui.inputNumber": "Type a number and press Enter:",
+  "tui.toggleNumber": "Number toggles a choice, empty Enter finishes:",
+  "tui.invalidNumber": "Invalid number, try again",
+  "tui.minSelection": "Select at least {{min}}",
+  "install.models": "Models: {{models}}",
+  "install.modelWarning": "Model warning: {{host}} {{role}} equals the implementation model; heterogeneous review unavailable",
+  "install.localModels": "Local model config: {{path}}",
+  "install.tier": "Tier: {{tier}} (hardened: {{hardened}})",
+  "doctor.modelConfigInvalid": "model-roles.local.json cannot be parsed",
+  "doctor.reviewSameAsCode": "review equals code; heterogeneous review unavailable",
+  "doctor.tier": "Tier: {{tier}}",
+  "doctor.ciMissing": "Missing CI template: {{paths}} (ignorable for tier=lean)",
+  "doctor.guaranteeGap": "Host {{host}} does not support {{capability}}; this guarantee can only be advisory, not a deterministic gate",
+  "doctor.modelDrift": "Model drift: {{host}}/{{role}} installed {{installed}} != local {{local}}; run the model-upgrade eval before upgrading",
+  "doctor.hardenedHint": "Hardened config contains managed-only keys; deploy it as managed settings so it cannot be overridden",
+  "tui.model.useRecommended": "Use recommended models for {{host}}?",
+  "tui.model.role": "Select the {{role}} model",
+  "tui.model.role.code": "implementation (code)",
+  "tui.model.role.judgment": "judgment",
+  "tui.model.role.review": "review",
+  "tui.model.recommended": "recommended",
+  "tui.model.inherit": "inherit (follow main model)",
+  "tui.model.manual": "Enter manually…",
+  "tui.model.skip": "Skip (leave unspecified)",
+  "tui.model.manualPrompt": "Model ID:",
+  "tui.model.invalid": "Model ID cannot be empty",
+  "tui.model.allowProbe": "Run {{host}}'s read-only model list command?",
+  "tui.model.sameAsCode": "review equals code; heterogeneous review unavailable",
+  "tui.plan.models": "Models: {{models}}",
+  "tui.hint.typeEnter": "Type, then press Enter",
+  "host.skillPointer": "Authoritative skill: `{{path}}`. This file is a pointer shell; read the authoritative source at execution time. Relative paths (scripts/, references/, …) resolve from that directory.",
+  "host.skillsIndexTitle": "# Skills index",
+  "host.skillsIndexDescription": "Skills index; authoritative bodies live under .agents/skills/",
+  "host.skillsIndexLine": "- `{{name}}` — {{description}} (authoritative: `{{path}}`)",
+  "host.skillsIndexEmpty": "(no skills)"
+}

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