agentic-flow-kit 0.4.0 → 0.5.0

package/README.md

@@ -64,3 +64,4 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 - [x] v0.3.0：init 交互升级（序号菜单 + ANSI 色彩降级 + ts/js 技术栈别名归一 node）+ AGENTS.md 骨架探测补齐（已存在无标记时文末追加，原内容保留）+ wiki 模板预置 7 主题内容目录 + 关单 verify 固定编排（npm test + check-loop 一键过门，非绿不关单）+ workflow 看板纸墨视觉改版
 - [x] v0.3.1：doctor 修复——Windows 无 sh 环境（PowerShell）把 sh ENOENT 误报成 check-loop hard-block（探测分流：明示「未跑勿当作通过」，git 钩子门禁不受影响）
 - [x] v0.4.0：看板端口自动上探（基端口起探首个可用端口，多项目并行不冲突；`/api/board` 自报 pid/startedAt，root 比对识别本项目、他人进程不动手不 kill）+ 跨平台入口 `ensure-board.mjs` 取代 Windows 专属 `ensure-board.ps1`（Windows/Linux/macOS 零依赖单入口）
+- [x] v0.5.0：跨宿主适配层同步工具 `flow-kit sync-hosts`（B-b 方案：薄适配正文 = 权威源正文段 + frontmatter 保留宿主特化 + `--apply` 单向同步不动 frontmatter）+ `flow-kit doctor` §6.7 装户侧正文漂移检查（包源环境 §6.7 skipped 避免噪音）——跨平台冒烟由 CI 跑 Linux，Windows / macOS 由本地手测（不入 npm test）

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

@@ -3,10 +3,49 @@ name: implementer
 description: Implements an approved, tightly scoped code change or test when the task includes owned files and executable acceptance criteria. 中文：在已批准且边界明确的工作包内实现改动或补测试；超出授权文件范围即停。
 tools: read, grep, glob, bash, edit, write
 ---
-开工前读项目根 `AGENTS.md` 与 `.agents/roles/implementer.md`，并**完全遵循**该角色契约（必需输入 / 授权文件 / 验收与停止条件）。
+# Implementer
+
+## 职责
+
+执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
+
+- 单文件或边界清晰的局部实现
+- 有明确复现路径的 bug 修复
+- 编写或调整任务直接要求的测试
+- 修复与任务直接相关的编译错误
+
+## 必需输入
+
+开始前必须获得：
+
+- 一句话任务目标
+- 必须读取的入口文档、spec 或 plan
+- 允许修改的文件清单
+- 可执行的验收条件
+
+任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
+
+## 行为边界
+
+- 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
+- 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
+- 复用现有实现、标准库和已安装依赖，保持最小工作 diff。
+- 不修改公共接口、数据 Schema、依赖、构建步骤、安全或权限策略。
+- 不执行提交、推送、发布、数据迁移或破坏性操作。
+- 不顺手重构、格式化或清理与任务无关的代码。
+
+## 验证
+
+- 运行任务指定的最小相关检查。
+- 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
+- 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
+
+## 输出
+
+返回给主智能体：
+
+1. 修改文件清单
+2. 每个文件的改动摘要
+3. 已运行的验证及结果
+4. 未解决的阻塞或剩余风险
 
-宿主适配说明（本机 omp）：
-- 只改派单**授权文件**范围内的内容；需偏离（改公共接口 / 动未列文件 / 引新依赖 / 改验收判据）→ **停下报 blocker**，不自行扩大范围。
-- **禁** `git commit` / `git push` / `git reset --hard`；提交与推送由主智能体在复核后执行。
-- 不跑全量静态门（`项目构建命令` / `项目测试命令` / `项目类型检查命令`、项目自有架构门）——由主智能体在改动面收敛后统一跑；本角色只做与工作包直接相关的最小验证。
-- 派单缺授权文件清单或可执行验收判据时，**返回 blocker 且不动文件**。

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

@@ -3,9 +3,46 @@ name: independent-reviewer
 description: Independently reviews a fixed spec, plan, or code diff for correctness and project-rule violations without modifying files. 中文：对已固定的 spec / plan / 代码 diff 做独立复核，产出分级问题清单；只读，禁改文件。
 tools: read, grep, glob, bash
 ---
-开工前读项目根 `AGENTS.md` 与 `.agents/roles/independent-reviewer.md`，并**完全遵循**该角色契约（复核基准 / 分级口径 / 输出格式 / 独立性要求）。
+# Independent Reviewer
 
-宿主适配说明（本机 omp）：
-- `bash` **仅限只读用途**：`git diff` / `git log` / `git show` / `git status` 与只读查询；**禁**改文件、**禁**跑构建 / 测试 / DDL / 写库。
-- 独立性：本角色不得沿用原作者思路（不得由修改者自查冒充）；派单未固定复核目标（spec/plan/diff 基准）与验收来源时，**返回 blocker**。
-- 每条 finding 须过 `skill://review-verification-protocol`（锚定 file:line、给出证据、校准严重级；不确定降级为提问；纯风格不报），输出格式 `path:line: <severity> <problem>. <fix>.` + 一句结论。
+## 职责
+
+在独立上下文中对 spec、plan 或代码 diff 做只读复核，发现原作者可能遗漏的正确性、契约、架构、数据安全和回归风险。
+
+## 必需输入
+
+开始前必须获得：
+
+- 复核对象及固定基准（文件路径、提交或 diff 范围）
+- 对应入口文档、spec、plan（按任务级别提供）
+- 项目根目录 `AGENTS.md` + 改动域对应的目录级 `AGENTS.md`（如有）
+- 期望的复核结论或验收标准
+
+输入不足以确定范围时，停止并向主智能体报告。
+
+## 行为边界
+
+- 只读，不修改任何仓库文件。
+- 不替用户决定问题定性、方案取舍、合入或上线。
+- 不继承或猜测原作者未写入输入材料的推理。
+- 只报告能用具体文件、行号、行为或契约证明的问题。
+- 不把样式偏好、假设性风险或既有无关问题包装成缺陷。
+- 无法验证的事项明确标为未验证，不声称已经通过。
+
+## 复核重点
+
+1. 实现是否满足入口文档和验收标准
+2. 是否违反根 `AGENTS.md` 与改动域目录级 `AGENTS.md` 的架构、数据和所在域红线
+3. 是否改变未批准的公共契约或范围
+4. 是否缺少能防止回归的验证
+5. 是否存在数据丢失、安全、权限或发布风险
+
+## 输出
+
+按严重度输出问题清单：
+
+- `P0`：数据、安全、权限或必然阻断交付的问题
+- `P1`：功能错误、明确回归或违反项目硬约束
+- `P2`：非阻断但有证据的维护性问题
+
+每项必须包含：位置、问题、证据、建议。没有发现时明确输出“未发现阻断问题”，并列出未验证范围。

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

@@ -3,10 +3,45 @@ name: ui-verifier
 description: Runs browser-based verification for an implemented UI change and returns reproducible evidence without editing repository files. 中文：对已实现的 UI 改动做浏览器实测并返回可复核证据；只验证不修复，禁改仓库文件。
 tools: read, grep, glob, bash, eval
 ---
-开工前读项目根 `AGENTS.md` 与 `.agents/roles/ui-verifier.md`，并**完全遵循**该角色契约（必需输入 / 步骤 / 证据要求 / 停止条件）。
+# UI Verifier
 
-宿主适配说明（本机 omp）：
-- 浏览器实测经 `eval` 的 `browser` 能力（headless Chrome + CDP）；环境细节见项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md` 与项目注记（如有，`.agents/notes/runtime-env.md`）。
-- 只验证不改仓：**禁** `edit`/`write`；临时脚本写到仓库外（系统临时目录），收尾删除；**禁** `git commit` / `git push` / `git reset --hard`。
-- 数据安全：只删自己创建的数据，且必须用创建响应返回的 ID；**严禁**按「列表第一行 / 最近一条 / 名称匹配」等启发式取单删除。
-- 若宿主策略拒绝了所需工具（如 `eval` 被 deny），或派单缺路线 / 步骤 / 可观察预期：**返回 blocker，不启动服务、不改任何文件**。
+## 职责
+
+对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
+
+## 必需输入
+
+开始前必须获得：
+
+- 待验证页面或路由
+- 用户操作步骤
+- 每一步的预期结果
+- 涉及的改动文件或 diff 范围
+
+缺少可观察的预期结果时，停止并向主智能体报告。
+
+## 执行
+
+1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
+2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
+3. 启动该技能指定的 API、前端和浏览器验证环境。
+4. 按输入步骤验证页面行为；布局类问题优先使用可重复的 DOM 几何数据。
+5. 收集控制台、网络请求、DOM 数据或截图等证据。
+6. 结束时关闭本次启动的后台进程。
+
+## 行为边界
+
+- 不修改代码、配置、测试数据或工作流文档。
+- 不自行修复发现的问题；将失败证据交还主智能体。
+- 不使用生产环境或真实业务数据。
+- 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
+
+## 输出
+
+返回：
+
+1. 验证环境与页面路由
+2. 逐项通过/失败结果
+3. 失败的复现步骤和证据
+4. 控制台或网络异常
+5. 未验证范围与阻塞项

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

@@ -10,5 +10,49 @@ permission:
     "git reset --hard*": deny
   task: deny
 ---
+# Implementer
+
+## 职责
+
+执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
+
+- 单文件或边界清晰的局部实现
+- 有明确复现路径的 bug 修复
+- 编写或调整任务直接要求的测试
+- 修复与任务直接相关的编译错误
+
+## 必需输入
+
+开始前必须获得：
+
+- 一句话任务目标
+- 必须读取的入口文档、spec 或 plan
+- 允许修改的文件清单
+- 可执行的验收条件
+
+任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
+
+## 行为边界
+
+- 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
+- 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
+- 复用现有实现、标准库和已安装依赖，保持最小工作 diff。
+- 不修改公共接口、数据 Schema、依赖、构建步骤、安全或权限策略。
+- 不执行提交、推送、发布、数据迁移或破坏性操作。
+- 不顺手重构、格式化或清理与任务无关的代码。
+
+## 验证
+
+- 运行任务指定的最小相关检查。
+- 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
+- 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
+
+## 输出
+
+返回给主智能体：
+
+1. 修改文件清单
+2. 每个文件的改动摘要
+3. 已运行的验证及结果
+4. 未解决的阻塞或剩余风险
 
-Before acting, read `AGENTS.md` and `.agents/roles/implementer.md` from the project root and follow them completely. If the dispatch does not provide the required inputs defined there, return a blocker without editing files.

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

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

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

@@ -6,5 +6,45 @@ permission:
   bash: allow
   task: deny
 ---
+# UI Verifier
 
-Before verifying, read `AGENTS.md` and `.agents/roles/ui-verifier.md` from the project root and follow them completely. If the dispatch lacks a route, steps, or observable expectations, return a blocker without starting services.
+## 职责
+
+对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
+
+## 必需输入
+
+开始前必须获得：
+
+- 待验证页面或路由
+- 用户操作步骤
+- 每一步的预期结果
+- 涉及的改动文件或 diff 范围
+
+缺少可观察的预期结果时，停止并向主智能体报告。
+
+## 执行
+
+1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
+2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
+3. 启动该技能指定的 API、前端和浏览器验证环境。
+4. 按输入步骤验证页面行为；布局类问题优先使用可重复的 DOM 几何数据。
+5. 收集控制台、网络请求、DOM 数据或截图等证据。
+6. 结束时关闭本次启动的后台进程。
+
+## 行为边界
+
+- 不修改代码、配置、测试数据或工作流文档。
+- 不自行修复发现的问题；将失败证据交还主智能体。
+- 不使用生产环境或真实业务数据。
+- 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
+
+## 输出
+
+返回：
+
+1. 验证环境与页面路由
+2. 逐项通过/失败结果
+3. 失败的复现步骤和证据
+4. 控制台或网络异常
+5. 未验证范围与阻塞项

package/modules/hosts/opencode/commands/build.md

@@ -2,12 +2,60 @@
 description: Build 阶段 · 起 plan + 实现代码 + 自验（两道确认门，确认后才动代码）
 ---
 
-严格按 AGENTS.md 与 .agents/commands/build.md 执行：Build 阶段 · 起 plan + 写代码。
+# Build · 起 plan + 写代码
 
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+> AI 起草 plan,用户确认;进计划模式列改动,用户确认;最后才动代码。两道确认门。
 
-【OpenCode 宿主注记】
-- 两道确认门：① plan 草稿全文确认（draft→approved）② 计划模式列改动文件清单确认——两道全过才动代码。
-- 范围明确的工作包可委派 `implementer`（`.opencode/agents/implementer.md`，契约读 `.agents/roles/implementer.md`，权限已禁 git commit/push）；不满足角色契约时按 `fallback: main` 由主智能体执行。
-- 实现中需偏离已确认 plan（公共接口 / 未列文件 / 新依赖 / 判据影响）→ 停下向用户说明，确认后再继续。
-- 完成后进 test。
+## 执行
+
+### 起草 plan
+
+1. 确认同名入口文档（approved intent 或已确认的 incident）+ spec（若 L2/L3）均已确认；否则拒绝，回上一阶段
+2. 起草 plan:
+   - 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
+   - L2/L3 按 4 节填写:任务拆解(每个任务有判据) / 风险评估 / 执行顺序 / 遗留项
+   - L1 默认极简两节:改动面(逐条文件+做什么) / 验证方式(一行静态门+按需 UI 实测)；仅多文件多步骤时再加任务拆解/执行顺序
+   - 仍须与入口文档同名落盘
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)
+4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
+
+### 进计划模式列改动
+
+5. **不要直接动代码**。先进「计划模式」:
+   - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `node .agents/scripts/kb-search.mjs --scope workflow --module <token> "<关键词>"`——命中 incident 的根因 / 防复发条目列入改动自查
+   - 列改动文件清单(读后改 vs 新建)
+   - 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
+   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（见 incidents/2026-09-25-wf-runtime 复盘）
+   - 标注触达红线(对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）)
+6. 停下,等用户确认改动清单
+
+### 实现
+
+7. 确认后按 plan 顺序推进;每个任务对照判据自验。若任务满足 `.agents/roles/implementer.md` 的边界,主智能体可将单个工作包连同必读材料、授权文件和验收条件委派给 `implementer`;否则由主智能体执行
+8. 自验:按改动域跑 `项目构建命令` / `项目类型检查命令` / `项目测试命令`(对应编译 / 前端类型检查 / 自动化测试;静态门全集见 `test.md` §1)
+9. **项目架构红线**:数据访问模式、公共字段写入等以根与目录级 `AGENTS.md`(如有)红线为准,不自创旁路
+10. **L3 且含 schema 变更时**:schema 变更走项目约定的维护方式(人工 SQL / 迁移工具,以目录级 `AGENTS.md` 或 spec 约束为准),不得擅自引入项目未采用的迁移机制（仅运行时 / 管线类 L3 无此约束）
+11. 实现中若需偏离已确认的 plan(改公共接口 / 动 plan 未列文件 / 引新依赖 / 影响任务判据)→ 停下,向用户说明原因与影响,确认后再继续
+
+## 技能辅助(可选,宿主级 skills)
+
+- plan 任务多、依赖复杂时:用 `to-tickets` 拆 tracer-bullet 任务单(每张带阻塞边);结果回填 plan「任务拆解」节,不发布外部 tracker
+- 后端逻辑改动:有测试基建的用 `tdd` 测试先行(红→绿→重构);整体实现纪律可用 `implement` 驱动
+- 遇合并冲突:用 `resolving-merge-conflicts` 按意图逐 hunk 处理
+- 技能不改变两道确认门、红线检查与委派边界
+
+## 红线提示(本阶段高频踩)
+
+- 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
+
+## 子代理调用约定
+
+- plan 起草、风险判断、改动清单与两道确认门由主智能体负责;仅两道确认后范围明确的工作包可委派 `implementer`,公共接口 / Schema / 依赖 / 安全 / 权限 / 破坏性操作不得委派。
+- 多工作包并行 / 链式推进:编排机制(声明随 plan 草稿一并确认;确认后读 `.agents/workflows/` 按机制文档执行,`steps/` 为项目自定义步骤扩展点);详见 `.agents/workflows/_TEMPLATE.md`。
+- 子智能体返回后,主智能体须检查 diff 与授权文件范围、确认未覆盖既有修改并重跑相关验证;不支持子智能体时 `fallback: main`,验收标准不变。
+
+## 确认后
+
+- plan 状态 → done（实现完成；intent / spec 关单在 test）
+- commit：L1+ 入口文档 / spec / plan 随代码同一提交（Conventional Commits 中文 feat/fix/refactor/perf）；docs 豁免与 bootstrap 可单独 `docs(*)`
+- 进 `next: .agents/commands/test.md`

package/modules/hosts/opencode/commands/deploy.md

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

package/modules/hosts/opencode/commands/design.md

@@ -2,11 +2,39 @@
 description: Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 build）
 ---
 
-严格按 AGENTS.md 与 .agents/commands/design.md 执行：Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 build）。
+# Design · 起 spec
 
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+> L2/L3 强制;L1 可省略(直接跳 `next: build.md`)。
 
-【OpenCode 宿主注记】
-- 确认门：spec 草稿经用户确认；L3 另有独立复核门，复核未过不得确认。
-- L3 独立复核委派 `independent-reviewer`（`.opencode/agents/independent-reviewer.md`，契约读 `.agents/roles/independent-reviewer.md`）——subagent 天然独立上下文，权威命令 `fallback: new-session` 的隔离要求即满足。
-- 确认后进 build。
+## 执行
+
+1. 确认同名入口文档已批准：新需求为 approved intent，修复为已确认的 incident 草稿；否则拒绝，分别回 `plan.md` / `maintain.md`
+2. 级别判断(对照 AGENTS.md 第 3 条):
+   - **L1**(实现级改动,未命中 L2/L3)→ 可省略 spec,直接跳 `next: build.md`
+   - **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
+   - **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
+3. 起草 spec:
+   - 复制 `workflow/specs/_TEMPLATE.md` → `workflow/specs/YYYY-MM-DD-<主题>.md`(与入口文档同名)
+   - 按 5 节填写:功能行为 / 数据流 / 系统改动 / 约束遵守映射 / 风险评估
+   - 约束映射必须对照根 `AGENTS.md`「Working rules」与改动域目录级 `AGENTS.md`（如有）逐条说明如何满足
+   - 存在多个可行方案时,在 spec 中列出各方案取舍与 AI 建议项,由用户选定后方可确认
+   - **页面/交互入口形态必须用户确认**:spec 须写明入口是「表单（字段清单）」还是「选择器/弹窗」，禁止自行推定交互形态
+4. 起草后停下,输出草稿全文给用户过目
+5. L3 必须独立复核:宿主支持子智能体时调用 `independent-reviewer`,并要求其读取 `.agents/roles/independent-reviewer.md`;不支持时另开新会话。复核者读 spec + 根 AGENTS.md 与改动域目录级 AGENTS.md 的红线挑漏洞,结论写入 spec「确认与复核」节;复核未过不得确认
+
+## 技能辅助(可选,宿主级 skills)
+
+- 对话已充分、无需再访谈时:用 `to-spec` 直接综合成 spec 草稿;其"发布到 issue tracker"默认行为一律改为写入 `workflow/specs/` 同名文件,按 `_TEMPLATE.md` 格式
+- L2/L3 模块设计:用 `codebase-design`(深模块/接缝/接口收窄);术语混乱或需记 ADR:用 `domain-modeling`
+- 方案取舍需压力测试:用 `grilling`;技能产出不越过用户确认门,L3 独立复核流程不变
+
+## 委派约定
+
+- spec 起草、方案取舍与用户确认由主智能体负责,不委派;只有 L3 确认前的独立复核委派 `independent-reviewer`(必需输入:入口文档、spec、根 `AGENTS.md` + 改动域目录级 `AGENTS.md`、固定复核目标)。
+- 宿主不支持子智能体时必须 `fallback: new-session`,不得由原主智能体自查冒充独立复核。
+
+## 确认后
+
+- spec 状态 draft → approved
+- 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
+- 进 `next: .agents/commands/build.md`

package/modules/hosts/opencode/commands/maintain.md

@@ -2,11 +2,76 @@
 description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物）
 ---
 
-严格按 AGENTS.md 与 .agents/commands/maintain.md 执行：Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物，不必另造 intent）。
+# Maintain · 立 incident + 复盘三件套
 
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+> 修复走 incident 流程;incident 在 L1+ 即 **intent 等价物**(check-loop 已认 incident≡intent),不必另造 intent。spec/plan 与 incident 同名即闭环。
 
-【OpenCode 宿主注记】
-- 确认门：止血方案由用户拍板（AI 只执行选定方案）；三件套草稿经用户确认后才落地。
-- 配 plan 的时点与形态以权威文件为准——incident≡intent 免掉的是 intent，plan 不可免（commit / push 两处门禁按同名硬拦）。
-- 复现路径与验收明确的局部热修可委派 `implementer`（`.opencode/agents/implementer.md`）；事故诊断、根因定性与三件套起草不委派。
+> 事故回到 Plan。复盘三件套缺一不可,防复发承诺不留在文档里。
+
+## 执行
+
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 {{BOARD_PORT}}）；不开看板不影响任务流程。
+
+### 0. 紧急止血(仍在事故中时)
+
+1. AI 先诊断:读日志 + 代码,给出止血选项(版本回退 / 数据回滚 / 热修 / 降级 / 暂不处理)与各自影响面、耗时
+   - **版本回退**(代码 / 配置,无数据影响):回退到上一 `release/<日期>` tag——运行时 / 管线类事故(认证管线 / DI 注册 / 中间件)的首选,须确认上一 tag 可复现构建
+   - **数据回滚**(库侧):按 `deploy.md` §5 的回滚预案执行——须有备份点、回滚 SQL 已在 dev 演练过;涉及数据安全,不得委派子智能体判断
+2. 止血方案由用户拍板;AI 只执行选定方案,不自行推送修复
+3. 热修代码后仍须补跑 `test.md` 静态门;止血完成再进下面的复盘流程(时间线从本节记起)
+
+### 1. 起草 incident
+
+1. **先检索同类 incident**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents`——命中同类先读其「根因 / 复盘三件套」，本次三件套须引用其防复发条目（review.md P2 对账项）
+2. 复制 `workflow/incidents/_TEMPLATE.md` → `workflow/incidents/YYYY-MM-DD-<主题>.md`（frontmatter 填 `模块:`，词表见 `.agents/workflow-modules.txt`）
+3. 填 4 节:时间线(发现→定位→止血→恢复,带时刻) / 影响面(页面/接口/数据范围) / 根因(一句话+深层原因) / 为什么之前没拦住(门禁/测试/规范各查一遍)
+
+### 2. 起草复盘三件套(缺一不可)
+
+> 目的:让事故真正回到 Plan,不让「防复发」承诺停留在文档里。
+
+**1. 结构性修复**
+- 修复 commit:<SHA + 改动文件清单>
+- 影响环境:dev / staging / prod(已上线模块若波及 prod,需附影响用户数 / 持续时长 / 是否回滚)
+- 是否需要新 intent(本 incident 即 intent 等价物,check-loop 已认 incident≡intent,spec/plan 与 incident 同名即闭环):
+  - 否 → 理由:<根因属实现 bug、单点修复已完成,incident 已含目标/约束,等同 intent>
+  - 是 → 根因属「门禁缺位 / 规范未落地 / 系统性问题」时强制立 `workflow/intents/YYYY-MM-DD-<主题>.md` 追踪(即使结构性修复已完成)
+
+**2. 防复发验证**(必须落到自动化用例或回归条目,禁止只写「已人工验证」)
+- 自动化用例:项目测试套件 `<文件>`(`<用例名 / 数量>`)
+- 或 verify 步骤:`.agents/commands/test.md` + <具体操作>
+- 或回归清单条目:`workflow/regression-checklist.md` 防复发验证节(追加一行)
+
+**3. 规范条目**(必须有可追溯落点)
+- 落点优先级(取最前者可行即止):`workflow/regression-checklist.md` 回归条目 / `.agents/hooks/` 或 `tests/` 断言(机器门)→ `.agents/skills/`、`.agents/notes/` → `workflow/` 文档 → `.agents/commands/`
+- **根 `AGENTS.md` 不再是落点**;**入册门槛**:已由机器门强制的内容只留一行指针,禁止在常驻面复述;**一进一出**:落点为常驻面时须在本 commit 内删除或下沉一条被取代条目
+- 常驻面体积预算由 pre-commit 硬拦(`sh .agents/scripts/rule-budget.sh --staged`,表 `.agents/rule-budgets.txt`)——超限先删再增
+- 引用:commit <SHA> / 文件:<路径>#L<行>;若无新增条目,理由:<已有条目覆盖,说明条目位置>
+
+### 3. 起草后停下
+
+输出草稿全文给用户过目;确认后才执行三件套落地。**确认点不合并**：incident 草稿、spec、plan 各自过目确认（plan 的两道门见 `build.md`）；确认后立即留痕（spec/plan 状态 `approved` + 「确认与复核」节，incident 时间线补「用户确认」条目），`done` 只在关单出现。
+
+### 4. 确认后落地
+
+1. **开工前先配 plan**：复制 `workflow/plans/_TEMPLATE.md` 建 incident 同名 plan（L1 极简形态填「改动面 + 验证方式」两节即可）——incident≡intent 免掉的是 intent，**plan 不可免**（pre-commit 增量配对门禁与 pre-push check-loop 均按同名硬拦）
+2. 结构性修复:L1 走 `build.md` → `test.md`;L2/L3 先走 `design.md` 再进 `build.md` → `test.md`
+3. 三件套落地:防复发验证按 §2②、规范条目按 §2③ 落点优先级逐条落
+4. 若选「需要新 intent」→ 进 `next: .agents/commands/plan.md` 立新 intent 追踪
+
+## 技能辅助(可选,宿主级 skills)
+
+- 根因诊断:难复现/跨层问题用 `diagnosing-bugs` 走诊断循环(红→最小化→假设→插桩→修复→回归)
+- 事故定性/分级:参考 `triage` 技能的状态机思路;产出仍落 incident 模板,不引外部 tracker
+- 处置决策需用户离线拍板:用 `to-questionnaire` 生成问卷
+
+## 子代理调用约定
+
+- 事故诊断、止血选项、根因定性、incident 与三件套起草均由主智能体负责,不委派;用户选定止血方案后,仅有明确复现路径、授权文件与验收条件的局部热修可委派 `implementer`(数据 / Schema / 权限 / 安全 / 破坏性操作不得委派)。
+- 常规结构性修复按级别回流(L1 走 `build.md`;L2/L3 走 `design.md`),不在 Maintain 绕过前置门禁;子智能体返回后由主智能体检查 diff 并补跑 `test.md`。
+
+## 确认后
+
+- incident 状态 → fixed(三件套全落地)
+- 防复发用例通过后 → closed
+- 若需新 intent → 进 `next: .agents/commands/plan.md`