agentic-flow-kit 1.8.2 → 2.0.0

package/templates/engine/.agents/commands/deploy.md

@@ -0,0 +1,52 @@
+---
+description: Deploy 阶段:合入清单(静态门 + 配对检查 + 回归 + DB + 授权 + PR 审查合并)
+stage: Deploy
+triggers:
+  - "跑下 release"
+  - "可以上了"
+  - "准备上线"
+approval_required: true
+next: .agents/commands/maintain.md(仅事故时)
+---
+
+# Deploy · 合入清单
+
+L1 已在 `.agents/commands/new-task.md` §L1 快速道关单，不打开本文件。本文件从 L2/L3 合入起。
+**口径（owner 2026-10-29）**：不走 tag/24h 观察仪式——合入 = PR 创建 $\rightarrow$ 审查 $\rightarrow$ 回归 $\rightarrow$ 合并 $\rightarrow$ 归档（release tag 与发布观察台账已退役，历史查 git）。
+
+## 1. 静态门 (Static Gates)
+1. `node .agents/scripts/verify.mjs --full`（口径见头注）全绿 $\rightarrow$ 记录证据；任一失败 $\rightarrow$ **HALT** $\rightarrow$ 回 `stages.md` Build 章。环境细节见 `.agents/notes/runtime-env.md` §1, §2
+
+## 2. 文档闭环 (Documentation Audit)
+1. **配对检查 (L2/L3)**: `intents/`(或 `incidents/`) $\leftrightarrow$ `specs/` $\leftrightarrow$ `plans/` 三件同名齐全，状态全 `done`
+2. **修复类专项**: incident 三件套 [结构性修复 / 防复发验证 / 规范条目] 完整 $\text{AND}$ 状态 `closed`；根因属门禁/规范缺位 $\rightarrow$ 已立新 intent 追踪
+3. **裁定回填核对**: 有裁定回填改动过 done 文档 $\rightarrow$ 已同批补录重确认补偿行（`maintain.md` §4.4）$\rightarrow$ 否则 pre-push 指纹硬门拦截
+4. **合入收口自查**: **合并前**核对 `workflow/` 四目录无本批应关未关的在途件（合并树上仍 `draft`/`approved` 即先关单再合入）
+**Output**: 闭环审计通过证据
+
+## 3. 回归与数据库 (Regression & DB)
+1. **路径验证**: `workflow/regression-checklist.md` 涉及模块关键路径全过
+2. **自动化验证**: 项目测试用例全过 (禁跳过失败用例)；历史同类 incident 防复发条目逐条过
+3. **DB 变更 (L3 专项)**: 迁移 SQL $\leftrightarrow$ 实体映射一致；记录 [备份点] + [回滚 SQL 路径]；**回滚 SQL 必须在 dev 演练执行过** (未演练 $\rightarrow$ 视为无预案 $\rightarrow$ **HALT**)
+
+## 4. 合入授权与 PR (Authorization & PR)
+1. **用户授权**: 仅接受用户本人在对话内一句 "上" 或同义确认
+2. **PR 创建**: 面板评审触发口径以 `.agents/commands/pr-review.md` 为准（满足其触发规则才跑），再 `node .agents/scripts/pr-create.mjs create --source <分支> --target <目标> --title "<Conventional Commits 中文>" --body-file <file>`——描述带 Test 三件证据（Summary / Evidence / Merge Danger，形态见 `review.md`）；自动评审门已退役（2026-11-09），pr-create 仅转调 tfs-pr；手动面板跑过时在 Evidence 追加一行 `面板评审：<runId>（Important n / Nit n / Pre-existing n）`
+3. **审查**: 按 `.agents/commands/review.md` 分级评审（逻辑 → 安全 → 对照 spec/plan）——审查不通过不合并
+4. **合并留痕**: 记录 PR 号 + 合并 commit SHA；发布流水线执行（若有）由用户在平台人工审批
+**Output**: PR 审查记录 + 合并 SHA
+
+## 5. 归档与异常回落 (Closeout & Fallback)
+1. **归档**: 终态家族归档由 `confirm-doc` 关单自动完成，本阶段核对归档发生
+2. **异常回落**: 上线后异常 $\rightarrow$ `workflow/incidents/` $\rightarrow$ `maintain.md` (止血方案用户拍板；禁跨智能体协作推送修复)
+
+## 🚫 禁止项
+| 操作 | 后果 | 例外 |
+|---|---|---|
+| 无演练回滚 | → 视为无预案 | 必须在 dev 验证回滚 SQL |
+| 绕过 test 关单 | → 拦截合入 | 文档先在 test 阶段置 done |
+| 审查未过合并 | → 违反门禁前置 | P0 未清零禁合并 |
+| 委派回滚决策 | → 违反安全策略 | 回滚决策必须主 Agent + 用户 |
+
+## 🛠️ 辅助工具
+版本回退 = 平台侧 revert 合并 PR/commit

package/templates/engine/.agents/commands/maintain.md

@@ -0,0 +1,76 @@
+---
+description: Maintain 阶段:立 incident + 复盘三件套(修复 / 防复发 / 规范条目)
+stage: Maintain
+triggers:
+  - "立个 incident"
+  - "线上出事了"
+  - "记一笔 incident"
+  - "出事了,根因 xxx"
+delegation:
+  - role: implementer
+    instructions: .agents/roles/implementer.md
+    when: 用户已选定止血或结构性修复方案,复现路径与授权文件均明确,且任务满足角色契约
+    required: false
+    fallback: main
+approval_required: true
+next: .agents/commands/stages.md Plan 章(若复盘需要新 intent)
+---
+
+# Maintain · 立 incident + 复盘三件套
+
+L1 且不是线上事故、复发、数据或契约：只做 §1 立档，然后回 `.agents/commands/new-task.md` §L1 快速道。§0 止血和 §2 复盘三件套留给线上事故和 L2/L3。incident 仍然要立。
+
+## 0. 紧急止血 (Active Incident)
+**Input**: 故障现象 / 日志
+**Process**:
+1. **诊断**: 读日志 + 代码 $\rightarrow$ 给出 [止血选项 (回退/回滚/热修/降级)] + [影响面/耗时]
+2. **执行**: 方案由用户拍板 $\rightarrow$ AI 仅执行选定方案 (禁自行推送修复)
+3. **验证**: 热修后跑 `node .agents/scripts/verify.mjs --scope`（口径见头注）
+**Output**: 服务恢复 $\rightarrow$ 进复盘流程
+
+## 1. 起草 incident
+**Input**: 止血完成后的故障上下文
+**Process**:
+1. **同类检索**: `node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents` $\rightarrow$ 引用既有防复发条目
+2. **创建文档**: 复制 `_TEMPLATE.md` $\rightarrow$ `workflow/incidents/{name}.md`
+3. **填写内容**: [时间线 (发现$\rightarrow$恢复)] / [影响面] / [根因 (深层原因)] / [门禁失效分析]
+**Output**: `workflow/incidents/{name}.md` (Status: Draft)
+
+## 2. 起草复盘三件套 (The Trio)
+**Requirement**: 三件套缺一不可，防复发承诺禁止仅停留在文档中。
+**Process**:
+1. **结构性修复**: 记录 [修复 commit SHA + 文件清单] $\rightarrow$ 判定是否需立新 intent (根因属门禁缺位/规范未落地 $\rightarrow$ 强制立 `workflow/intents/`)。**攻击前提**：同一前提下两种修法都过不了同一道验证时，停下把前提本身写下来直接测试——防「换皮修复」混过复盘
+2. **防复发验证**: 必须落地为 [自动化用例 / `stages.md` Test 章步骤 / `regression-checklist.md` 条目]；fixed/closed 建档日起 check-loop §3x 硬拦「无自动化用例/回归清单引用」（禁「已人工验证」）
+3. **规范条目**: 按照优先级落点：`regression-checklist.md` $\rightarrow$ `hooks/` $\rightarrow$ `skills/` $\rightarrow$ `notes/` $\rightarrow$ `commands/` (禁落 root `AGENTS.md`)。**修复强度阶梯**：落点序是位置序，强度序另判——架构收口/钩子/CI > 自动化用例 > 规范文本；落规范文本时必须在复盘写明「为什么更强的层级拦不住」
+**Output**: 落地验证计划 + 规范变更记录
+
+## 3. 确认与落地
+本节从线上事故和 L2/L3 起。
+**Process**:
+1. **HALT**: 输出 incident + 三件套草稿 $\rightarrow$ 等待用户确认
+2. **确认分步**: incident 草稿 / spec / plan 分别独立确认 (禁合并)
+3. **前置校验**: L2/L3 确认前 $\rightarrow$ `fill-spec`/`confirm-doc` 校验「时间线含用户确认」留痕 $\rightarrow$ 未过则回补
+4. **落地执行**:
+   - **配 plan**: 必须建立同名 `workflow/plans/{name}.md` (incident $\equiv$ intent, 但 plan 不可免)
+   - **实施修复**: L1 $\rightarrow$ 回 `.agents/commands/new-task.md` §L1 快速道（同名 L1 plan 即入口，不进 `stages.md`）；L2/L3 $\rightarrow$ `stages.md` Design $\rightarrow$ Build $\rightarrow$ Test 章
+   - **三件套落地**: 执行 §2 中的验证与规范变更
+**Next**: 若需追踪系统性问题 $\rightarrow$ `.agents/commands/stages.md` Plan 章立新 intent
+
+## 4. 确认后关单
+**Process**:
+1. **状态迁移**: `open` $\rightarrow$ `fixed` (三件套落地) $\rightarrow$ `closed` (防复发验证通过)
+2. **落态入口**: `confirm-doc.mjs` 逐跳迁移（口径见 `new-task.md` 快速道第 4 步）
+3. **对账**: `check-loop 15` 校验 [关单编辑 $\rightarrow$ closed 确认] 的顺序
+4. **关单后裁定回填**: done/closed 文档确需回填裁定 $\rightarrow$ 改正文**同批**在 `.agents/confirmations.jsonl` 追加**重确认补偿行**——同 doc+stage、fingerprint=改后内容指纹 (bindingSha256)、prev 沿用原行、quote=用户裁定原话 (source: chat-delegated)；append-only 不改历史行，check-loop 15 按末次 done 行生效 (重确认场景)。注意 `confirm-doc` 对终态文档无前向跳转，补偿行直接追加台账。**生成器**：`node .agents/scripts/append-compensation.mjs <doc...> --quote "<用户原话>"`，手搓哈希会被 s15 内容漂移门拦 
+
+## 🚫 禁止项
+| 操作 | 后果 / 机器行为 | 例外 |
+|---|---|---|
+| 承诺停留在文档 | → 视为未闭环 | 必须落地为代码/脚本/ checklist |
+| 根 AGENTS 落地 | → 违反单源纪律 | 必须下沉至 notes/commands/hooks |
+| 状态单跳 | check-loop 15 拦截 | 必须 fixed $\rightarrow$ closed |
+| 关单后改正文不补录 | check-loop 15 指纹漂移拦截 | 裁定回填须同批补录重确认补偿行 (见 §4.4) |
+
+## 🛠️ 辅助工具
+- **根因诊断**: `diagnosing-bugs` 诊断循环
+- **事故定性**: `triage` 状态机思路

package/templates/engine/.agents/commands/new-task.md

@@ -0,0 +1,89 @@
+# New Task · 闭环总入口
+
+> **⛔ 顺序**：先定级 → 先落三件套 → 逐份确认 → 才写代码。禁「先改后补档」（= 绕过确认门；违者双落 incident+papercuts）。细则与强度说明：`.agents/notes/process-order-rule.md`。
+
+## 1. 风险定级 (Step 0: 先定级再路由)
+
+| 泳道 | 级别 | 判据 | 确认与审计口径 |
+|---|---|---|---|
+| **协作道** | **L1** 实现级 | 未命中 L2/L3 的实现级改动 | 一份 plan 即入口（来源 / 目标 / 红线 / 改动 / 验证 / 验收）。不另立 intent。独立复核不设同步前置；`--batch` 仅 L1 |
+| **防御道** | **L2** 规则/契约 | 见 §L2 触达面闭集 | 同步确认门：spec 确认 $\rightarrow$ plan 确认 $\rightarrow$ 动手 |
+| | **L3** 数据/运行时结构 | schema / 迁移 SQL / DI 链 / 认证与中间件管线 | 同 L2 + spec 新会话独立复核，未确认不放行 |
+
+> **两问定级**：结构面（schema / 迁移 SQL / DI / 认证管线）→ L3；契约或共享口径 → L2；两者都没有 → L1。不要按严重程度从 L1 往上滑。
+> **提问分型**：能跑出来/查出来的（行为/时序/布局/输出/存量/eval 可区分）先原型/查库/跑 eval，禁停下来问；只有产品/偏好判断才升级确认。与 STOP 线正交（可实验不豁免红线）。
+> **落位**: L1 写在 plan frontmatter `级别`；L2/L3 写在 intent。
+> **判低拦截**: L1 plan 或 intent 勾触达红线 → check-loop「红线判低」hard 拦 → 升到 L2/L3 并补同名 spec。
+
+### L2 触达面 (闭集，命中任一即 L2)
+
+| # | 类别 | 判据 |
+|---|---|---|
+| 1 | **编码权威** | 一处生成、多处消费的编码/命名/取号规则 |
+| 2 | **共享契约** | 跨模块共享的基类 / DTO 形状 / 公共接口签名 |
+| 3 | **既有接口语义** | 既有参数或端点的行为变化（失效变生效、默认值/钳制口径改变） |
+| 4 | **全局横切口径** | 错误响应出口、分页与校验口径、聚合投影键 |
+
+> **负例 (落 L1)**: 纯页面表现/文案/布局/交互实现；纯新增端点或参数且行为不变；单模块内部重构且无对外契约变化；纯新增页面/路由且无共享契约；单模块内部组件拆分；模块内新增类型/常量且不跨模块消费。
+> **自查句**: 能否列出 $\ge 2$ 个实际行为受影响的消费方（模块/端点/页面；仅签名可见、行为不变不算）？能 $\rightarrow$ L2。
+> **默认档**: 红线全不勾即 L1。判级只回答「是否命中 L2 四类或 L3 结构面」。
+
+## 1b. todo 播种
+
+定级后、动手前，把所选命令的步骤标题**逐字复制**到 todo 列表首项；不另写摘要。跳过的步骤保留在列表里并写 `skip: <理由>`。todo 是执行契约，命令文件是 playbook——本页不复制步骤正文（单源）。
+
+## 1c. 阶段联动协议（进入即装载 + 自动衔接）
+
+- **进入即装载**：进入任一阶段指令时，先读该阶段绑定技能的 SKILL.md（正文单源在技能侧，本表只放指针）：
+
+| 阶段 | 进入即装载 |
+|---|---|
+| Plan（intent） | `grilling`（追问压实背景/目标/非目标） |
+| Design（spec） | `grilling`（歧义清单 / 方案压力测试）；按需 `codebase-design` / `domain-modeling`；分叉比选 `arena`；必读输入见 `stages.md` Design §2 |
+| Build | 无强制技能（实现委派走 `implementer` 角色） |
+| Test | 涉前端改动 `verify-ui`；L2/L3 独立复核 `review-method` |
+| Deploy | 无（走清单与上线授权门） |
+| Maintain | `why`（根因证据链） |
+| Review（横切） | `review-method`；高风险 diff `interrogate`；影响面 `blast-radius` |
+
+- **自动衔接**：阶段完成（确认门通过 + 留痕提交入库）后**自动进入 frontmatter `next` 指向的下一阶段指令**，不等用户催促。
+- **人件门不自动越过**：自动流转仅指阶段衔接与技能装载——每阶段的 HALT 确认、pipeline-run 的 `await-confirm`、上线授权（deploy 的「上」）到点即停，等用户放行原话。
+
+## L0 极简道
+
+判据（全机器可判）：产品面 ≤5 文件；未命中 §1 L2 闭集/L3 结构面；非数据维护 SQL 执行；不新增依赖/构建步骤（引擎/wiki 面本就豁免）。
+判据重叠取 L0。
+流程：定级 → 改码 → `node .agents/scripts/verify.mjs --face`/`--scope` 绿 → 单笔 commit；消息体含一行 `L0: <判据>`（机器可 grep）。
+
+## L1 快速道
+
+命中 L2 或 L3 就离开本页。L1 做到下面 6 步为止，不打开 `stages.md`。
+
+> **接手/恢复**：先读 `.agents/skills/session-resume/SKILL.md` 重建当前态，再走下面 6 步。
+
+1. **定级**：用 §1 两问和 L2 闭集。未命中即 L1，`级别` 写在 plan frontmatter。完成标准：plan 头里的级别与两问结论一致。
+2. **检索**：`node .agents/scripts/kb-search.mjs --scope workflow --module <token> "<关键词>"`。命中的 incident 根因写进下一步 plan 的自查。完成标准：命令跑过；命中根因备写进 plan，无命中粘贴脚本输出即可（免另写说明）。命中同功能 spec / features $\rightarrow$ 按 `workflow/README.md`「同功能续作」改原件不新建。
+3. **立 plan**：`node .agents/scripts/fill-plan.mjs --level L1 --topic <主题> --output workflow/plans/<YYYY-MM-DD>-<主题>.md`。可加 `--lite`（三节：入口 / 改动方案 / 验证与验收；条件：第 2 步检索无 incident 命中且红线全不勾），缺省仍为五节。填实入口（来源、目标、红线）、改动方案、约束与风险、验证计划、验收标准，并把第 2 步的检索结果写进自查。frontmatter `模块` 改成主导模块。不写 intent，不写预判字段。完成标准：所选模板各节有正文（五节或 lite 三节）、检索结论已入 plan；验收写不出可测试判据就停；红线要么勾中升 L2/L3，要么明确不勾。
+4. **确认后动手**：`node .agents/scripts/confirm-doc.mjs <plan> --delegated "<用户原话>"` 把 draft 收到 approved（确认门口径单源：逐件调用禁并录、逐件原话禁复用、逐跳迁移禁单跳），然后再改代码。只改 plan 列出的文件。四条红线：不提交密钥或 `.env`、不用 `--no-verify`、最小改动、偏离 plan 先停。**承诺面锁定**：approved 之后改「承诺面」（验收判据文本 / 红线 / 目标 / 改动方案）须先让用户重新点头并重录承诺面指纹——重确认口令见 `workflow/README.md`「承诺面绑定」；否则关单被拒、推送被检查 15 hard 拦（勾验收 + 证据回填不算改承诺）。改完不单独提交：验证（第 5 步）绿后按第 6 步连跳 done 并与代码同笔提交。改码前开 /tour 全景，每批刷新（skills/dev-tour）。完成标准：改动留在工作区，plan 仍是 approved。
+5. **验证**：`node .agents/scripts/verify.mjs --scope`（口径见头注）。有前端改动再打开 `.agents/skills/verify-ui/SKILL.md`。失败就改代码，不在本页改门禁。完成标准：命令退出码 0，前端改动另有实测证据。
+6. **关单＝单笔提交**：`node .agents/scripts/confirm-doc.mjs <plan> --delegated "<用户原话>"` 连续再跳一次把 approved 收到 done，随后单笔提交——plan(done) + 代码 + 确认分片 + verify 凭证同一笔入库，L1 无独立关单提交。仅 plan 独立关单场景（代码已在前笔入库）才打开 `.agents/skills/shipyard-workflow-closeout/SKILL.md`。完成标准：plan 为 done，单笔提交已入库。
+
+下面才打开别的文件：委派 implementer → `stages.md` Build §3；改了库连接 → `stages.md` Test §2；全量首跑红、隔离重跑转绿 → `stages.md` Test §1；L2/L3 独立复核 → `stages.md` Test §4。
+
+## 2. 级别子路由（纯指针）
+
+任务类型路由**单源** = 根 `AGENTS.md` §4。修复类按级别分流**单源** = `.agents/commands/maintain.md` §3（L1 立档后回本页 §L1 快速道；L2/L3 走 `stages.md` Design → Build → Test 章；根因属门禁/规范缺位另立同名 intent）。
+
+## 3. intent 豁免规则
+
+| 场景 | 判据 | 处理 |
+|---|---|---|
+| **AI-Native 引擎面** | 根 `AGENTS.md` §4 引擎面豁免口径 | 豁免三件套（intent/spec/plan 与确认门），Conventional Commits 直接 commit；触及业务代码的部分按其级别走 |
+| **wiki 文档调整** | 根 `AGENTS.md` §4「wiki 豁免」 | 豁免三件套（intent/spec/plan 与确认门），`docs(wiki)` 直接 commit；数据维护 SQL 执行与业务代码不豁免 |
+| **bootstrap 类改动** | 引入规则本身 | 豁免 intent，commit message 显式声明 `bootstrap` |
+
+## 4. 闭环兜底
+
+- **门禁清单**: 以 `.githooks/` / `.agents/hooks/` / `.agents/scripts/check-loop.mjs` 头部注释为准（本文不复述）。
+- **hard-block**: 清单单源 = check-loop 头注；配对断裂与回路断档已降 WARN，自查走 closeout skill §0。
+- **禁令**: 本地钩子是本地机器门，禁 `--no-verify`（见根 `AGENTS.md`）。

package/templates/engine/.agents/commands/pipeline-run.md

@@ -0,0 +1,56 @@
+---
+description: pipeline-run 自动化驱动入口——单命令驱动六阶段闭环（工单协议+机器门+原话代录）；与手动阶段路由二选一，禁混用
+stage: entry
+triggers:
+  - "pipeline-run"
+  - "跑执行器"
+  - "全自动跑"
+approval_required: true
+fallback: 主智能体亲自做 AI 槽位（工单由主智能体完成，不依赖子智能体）
+next: 按 run 停机点循环推进至 done
+---
+
+# pipeline-run · 全自动闭环执行器入口
+
+阶段机已对齐 commands 手册。与手动阶段路由二选一，禁混用。
+
+> **保留待用**：暂零 run（`cache/pipeline-runs/` 空）但不退役；启用前先跑一次小任务验证状态机。
+
+> **分工**：确定性部分由 `pipeline-run.mjs` 状态机驱动（fill-* $\rightarrow$ confirm-doc $\rightarrow$ verify.mjs $\rightarrow$ git，退出码全记录）；AI 槽位按工单协议执行；人件门到点即停、原话代录；宿主禁自行改状态。
+
+## 1. 驱动协议 (Protocol)
+
+**Input**: 需求原文
+**Process**:
+1. **启动**: `node .agents/scripts/pipeline-run.mjs start "<需求原文>"` (可预判加 `--hint "kind=… level=… module=…"`)
+2. **循环读停机点**: stdout 末行机器标记 `PIPELINE-STOP <type> …` $\rightarrow$ 按 type 分流:
+
+| 停机类型 | 动作 | 回跑命令 |
+|---|---|---|
+| `work-order <runId> <工单id>` | 读工单全文 $\rightarrow$ **按单干活** (见下表) | `next` (implement/fix 须 `--files "a,b"`) |
+| `await-confirm <runId> <doc>` | **人件门**: 转述要点索确认 $\rightarrow$ 用户放行后 | `next --delegated "<用户原话>"` (逐字原话) |
+| `gate-fail <runId> <stage>` | 读 problems 原因 $\rightarrow$ 修复后原路重跑 | `next` (禁绕门/禁 `--no-verify`) |
+| `done <runId>` | 汇报总结 (阶段条/门数/提交链) | 流程结束 |
+| `aborted <runId>` | 汇报放弃态与留档位置 | 流程结束 |
+
+### 工单类型执行矩阵
+
+| 工单类型 | 执行要求 | 进入即装载（联动，见 new-task §1c） |
+|---|---|---|
+| **triage** | 判级回填 `next --triage "kind=… level=… module=… topic=<英文kebab>"` (就高不就低) | 无；kb 检索同 new-task §L1 快速道第 2 步 |
+| **draft** | 起草指定文档 | intent→`grilling`；spec→`stages.md` Design §2「必读输入」+ `grilling`（分叉比选 `arena`）；plan→无 |
+| **implement / fix** | 按授权文件实现 $\rightarrow$ **偏离即停** (公共接口/计划外文件/新依赖 $\rightarrow$ 停机上报，不自行放行) | 无强制技能；fix 类根因不明先 `why` |
+| **review / closeout** | 按单产出并写入指定位 (review-only 汇报后 `--done` 收尾) | review→`review-method`（高风险 diff +`interrogate`）；closeout→`shipyard-workflow-closeout`（§0 关单自核） |
+
+3. **放弃**: 用户明确不做 $\rightarrow$ `abort --run <id> --to superseded|cancelled --delegated "<原话>"` (approved 文档逐份走 confirm-doc --to)
+4. **观测** (可选): `status [--run <id>] [--json]` 全量事件流水 / `watch` 终端轮询视图
+
+## 🚫 硬纪律 (违反即协议破坏)
+
+| 操作 | 后果 / 机器行为 | 例外 |
+|---|---|---|
+| 直改 workflow 状态 | → 绕过唯一迁移入口（confirm-doc） | 宿主永不直改 frontmatter |
+| 编造/复用原话 | → 台账 `confirmations.jsonl` 对质暴露 | `--delegated` 必须是当次对话原话 |
+| 带病推进 | 修复环超限 (3 次) 停机交人工 | verify 非绿不关单 |
+| 写 run 文件 | → 与机器事实冲突 | 宿主只读不写 |
+| 自动放行人件门 | `await-confirm` 须转述要点、拿到用户放行原话后才 `next --delegated` | 自动触发仅指阶段衔接与技能装载 (new-task §1c 联动协议)，任何人件门永不自动越过 |

package/templates/engine/.agents/commands/pr-review.md

@@ -0,0 +1,30 @@
+---
+description: PR 面板评审——多子代理找 bug + 独立投票 + 台账
+stage: review（横切）
+triggers:
+  - "评审这个 PR"
+  - "跑 PR 面板评审"
+  - "pr-review"
+---
+
+# PR Review · 面板评审
+
+## 触发规则
+
+满足任一条，跑面板评审；均不满足，走 `.agents/commands/review.md` 分级评审，禁跑面板：
+- diff 触及信任边界 / 数据面 / 公共契约
+- 合 main 前
+- 疑难回归需多镜头交叉验证
+
+## 流程
+
+脚本：`.agents/scripts/pr-review.mjs`（子命令细节 `--help`）。按序执行，禁跳步：
+
+1. `plan --base <ref> --head <ref>`；高风险快检加 `--fast`（单镜头档）。现场落 `.agents/tmp/pr-review/<runId>/`（run.json / briefs / tasks.json）
+2. 按 `tasks.json` 并行派 finder / verifier 子代理；角色契约见 `.agents/roles/pr-finder.md`、`pr-verifier.md`、`pr-adjudicator.md`
+3. 依序执行：`collect` → `verify` → `adjudicate`（escalated 项）→ `dispose` → `summary`
+
+## 落账
+
+- 台账 artifact + 月度一行写 `workflow/reviews.d/`（append-only）。
+- 已跑评审的 PR，在 PR Evidence 追加一行：`面板评审：<runId>（Important n / Nit n / Pre-existing n）`。

package/templates/engine/.agents/commands/review.md

@@ -0,0 +1,93 @@
+---
+description: 代码评审标准（按风险分级：机器兜底 + AI 自查出清单，用户决策定性和合入）
+stage: review（横切：合入前使用，不占 6 阶段之一）
+triggers:
+  - "评审一下"
+  - "过 review 标准"
+  - "按评审标准过一遍"
+delegation:
+  - role: independent-reviewer
+    instructions: .agents/roles/independent-reviewer.md
+    when: 机器门禁完成且复核目标与 diff 基准已固定（L2 / L3 强制独立复核：独立子智能体或新会话，不得回退主智能体自查）
+    required: true
+approval_required: true
+next: P0/P1 未清时 L1 → .agents/commands/new-task.md §L1 快速道改代码；L2/L3 → .agents/commands/stages.md Build 章。清零后经用户确认合入
+---
+
+# Review · 分级评审
+
+> **三分工**：机器门禁自动拦（无需人守）$\rightarrow$ AI 复核出分级清单 $\rightarrow$ 用户定性/合入；禁互相代替（AI 禁下合入定性，用户禁被代判）。
+> **独立性**：L2/L3 必须用独立子智能体或新会话，禁原作者自查冒充。
+
+## P0 必拦 (Block)
+
+| 检查项 | 判据 (Invariant) | 机器兜底 | AI 自查 |
+|---|---|---|---|
+| **架构红线** | 分层依赖方向约束（领域/应用层禁引基础设施实现） | `.agents/hooks/` 架构门禁 | 豁免清单外的引用 |
+| **审计字段** | 公共审计字段由统一基础设施自动写入，禁业务代码手写 | 审计字段门禁 (比对新增加值) | 无 |
+| **删除拦截** | 删前必须查子级/业务引用，被引用时按统一口径报错 | 删除门禁 (调用点 vs allowlist) | 每个调用点核对删前查引用 |
+| **入参校验** | 必填判空、范围校验、非法输入按统一口径拒绝 | 项目验证测试 | 覆盖盲区自查 |
+| **L2/L3 无 spec** | 拒收，先回 `workflow/specs/` 立 spec 确认 | `confirm-doc` →done 门（L2/L3 intent 须同名 spec 已确认） | 无 |
+
+## P1 应拦 (Self-check)
+
+| 检查项 | 判据 (Invariant) | 备注 |
+|---|---|---|
+| **DB 命名与迁移** | 遵循表/字段/外键命名规范与 schema 变更流程 | 禁擅自引入未采用迁移机制 |
+| **前端形态** | 新增/编辑与大数据量选择遵循组件约定 | 弹层 vs 跳页、选择器形态、表格样式 |
+| **表单** | 可选字段空值归一化后提交 | 禁改后端 DTO 规避校验 |
+| **状态管理** | store 调 API，组件只调 store | 无 |
+| **API 入参边界** | 写操作禁 `[FromBody]` 绑定领域实体（一律 DTO） | 入参 DTO 禁含主键与审计字段 |
+| **导入信任边界** | 导入端点服务端全量复验，禁信任客户端 | 解析失败进错误行汇总，禁静默丢弃 |
+| **Create/Update 同口径** | Create 校验 Update 必须同口径 | 被引用的标识符字段禁改 |
+| **分页与状态语义** | 分页参数范围校验 + 服务层钳制 | 非法状态与不存在分离 (400/404) |
+| **spec 承诺落地** | spec §测试用例须真落到测试或验证脚本 | 常驻断言禁写成随时间增长的行数常量 |
+| **薄适配漂移** | 宿主 `agents/`、`commands/` 保持指针壳，正文只在 `.agents/roles/` 与 `.agents/commands/` | 人工核对壳引用权威路径且正文不过厚 |
+| **影响面证明** | 小 diff 的「安全因为 X」须跑代码证明，不靠口头 | 按 `.agents/skills/blast-radius/SKILL.md` 走；证明脚本随 PR 或落 `tmp/` |
+
+## P2 建议 (Advisory)
+
+- 注释完整性（复杂逻辑处补注释）
+- Conventional Commits 中文（feat / fix / docs / style / refactor / perf / chore）
+- 历史同类 incident 复盘三件套是否补齐
+- **纯样式直接丢弃，不列为 P2**；仅“命名/注释导致错误调用或契约误读”按行为问题上报。
+
+## 执行流程 (Process)
+
+**Input**: 待评审 diff + 固定基准 (SHA/分支)
+**Process**:
+1. **机器门禁**: pre-commit / pre-push / `stages.md` Test 静态门全过 (无需人守)
+2. **AI 复核**: 委派 `independent-reviewer` $\rightarrow$ 聚焦 P0 未覆盖项 + 全部 P1 (P2 视精力)；独立性、落盘与跨模型口径以 `.agents/roles/independent-reviewer.md`「复核口径」为准（本节场景=合入评审，本文不复述）
+   - **方法**: `.agents/skills/review-method/SKILL.md`
+   - **防误报**: 每条 finding 过 `review-verification-protocol`
+   - **模型选择**: 取 `model-roles.json`（本地覆盖 `.local.json` 优先，皆空 = 宿主默认）；跨模型阶梯与降级以 `.agents/roles/independent-reviewer.md` Constraints 为准。换模型前按 `delegations.md` 跑 3 个已定性 bug 回归
+   - **高风险 diff**: 叠加 `.agents/skills/interrogate/SKILL.md`（不替代上面的单一独立复核）
+3. **用户决策**: 问题定性 (误报驳回 / P0 必修 / P1,P2 裁量) + 合入时机
+**Output**: 分级问题清单 + 修复建议 $\rightarrow$ 用户确认合入
+**Next**: P0/P1 未清时，L1 回 `.agents/commands/new-task.md` §L1 快速道改代码；L2/L3 回 `stages.md` Build 章。清零后经用户确认合入。
+
+## PR 面板评审（pr-review，2026-11-06 建；2026-11-09 自动门退役）
+
+> 面板退役为**手动工具**（owner 指令）：pre-push / CI / pr-create 不再强制评审台账；触发口径以 `.agents/commands/pr-review.md` 为准。分档 Important/Nit/Pre-existing、纯样式丢弃的口径不变。
+
+## PR 体三件套（合入叙事约定）
+
+开 PR 时 body 固定三节，各答一个合入决策要素，缺一不可（Azure DevOps 无技能钩子，本节即约定单源）：
+
+| 节 | 答 | 形态 |
+|---|---|---|
+| **Summary** | 这是什么改动 | 1-4 条：为什么改、改了什么，指向关键模块/文件——必须来自实际 diff，写实际行为不写意图修辞 |
+| **Evidence** | 证据呢 | 实际运行的测试/构建/手工验证（Before/After 对照：改前红改后绿的测试对、同视角前后截图）；挂绿凭证或实测证据路径，须可点开复核；没运行就明确写「未运行」及原因，禁编造。走面板评审时追加一行：`面板评审：<runId>（Important n / Nit n / Pre-existing n；全部 fixed/waived/deferred/recorded）` |
+| **Merge Danger** | 风险多大 | **Door**: 影响面（API / DB / 配置 / 权限 / 兼容性），无风险写「无」，禁省略；**Blast Radius**: 一词（局部 / 模块 / 全局）；**Rollback**: 回滚方式与风险，必填 |
+
+体积超预算（pre-push advisory；覆盖须 `PR_SIZE_OK=1` 并在 Tradeoffs 写理由）、diff 大、overlap 非空或不可逆变更 → body 另加 **Tradeoffs** 段：真实 diff 规模 + 为什么仍这样做。
+
+写不出「Door=无 + 局部」时即触发一次定级复核。
+
+> 分发型技能（如 `tfs-pr`）自带同款模板，那是其**无约定宿主的缺省值**；本仓以本节为准。
+
+## 🚫 禁止项
+| 操作 | 后果 / 机器行为 | 例外 |
+|---|---|---|
+| L2/L3 主智能体自查 | → 独立性失效 | 必须委派 `independent-reviewer` 或新会话 |
+| P0 未清合入 | → 拦截 | 必须清零后经用户确认 |