agentic-flow-kit 0.8.0 → 0.9.1

package/modules/hosts/codex/commands/wf-plan.md

@@ -0,0 +1,41 @@
+---
+description: Plan 阶段:立 intent(需求来源 / 目标 / 约束 / 触达红线)
+---
+
+# Plan · 立 intent
+
+> AI 起草,用户确认。确认前不进下一阶段。
+
+## 执行
+
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
+
+1. 若 `workflow/intents/` 已有目标 intent 且状态为 approved → 按级别跳 next（L1 → `build.md`，L2/L3 → `design.md`）
+2. 否则起草新 intent:
+   - **先检索同类**：`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type intents,specs`——命中同类先读其结论与验收，新 intent 引用（防重复立项 / 重复踩坑）
+   - **填空工具先跑**：`node .agents/scripts/fill-intent.mjs --module <模块> --level <L0|L1|L2|L3> --topic <主题> --output workflow/intents/<date>-<主题>.md --notes "<备注>"`——输出含 frontmatter 6 字段（含 risk_level）+ 7 节正文（背景与问题/目标/非目标/约束/影响面/触达红线/验收标准）的草稿；AI 据此填实，模板与节标题机器保证不出错
+   - 复制 `workflow/intents/_TEMPLATE.md` → `workflow/intents/YYYY-MM-DD-<主题>.md`
+   - frontmatter 填 `模块:`（词表见 `.agents/workflow-modules.txt`，新建文档必填，check-loop 会警告）
+   - 按 6 节填写:背景与问题 / 目标(可验证) / 非目标 / 约束 / 影响面 / 触达红线（L1 微改动可省非目标/约束两节，不硬填）
+   - 红线勾选对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
+3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
+4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
+
+   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
+
+## 技能辅助(可选,宿主级 skills)
+
+- 需求模糊、判据写不出时:用 `grilling`/`grill-me` 拷问需求,答完回填 6 节
+- 需要用户离线拍板的决策:用 `to-questionnaire` 生成问卷,问题清单随 intent 草稿一并列出
+- 讨论中需同时沉淀术语表/ADR:用 `grill-with-docs`,文档落 `workflow/` 下与主题同名
+- 技能只辅助澄清,产出仍按 `_TEMPLATE.md` 落 `workflow/intents/`,确认门不变
+
+## 执行主体
+
+- 需求澄清、级别判断与 intent 起草由主智能体负责,本阶段不委派子智能体。
+
+## 确认后
+
+- intent 状态 draft → approved
+- 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)——**提交最早可行点**：入口文档受 pre-commit 闭环配对（增量）门约束，同名 spec / plan 须已在工作区（先例 61ec130）
+- L1 → `.agents/commands/build.md`；L2/L3 → `.agents/commands/design.md`

package/modules/hosts/codex/commands/wf-review.md

@@ -0,0 +1,47 @@
+---
+description: 代码评审标准（按风险分级：机器兜底 + AI 自查出清单，用户决策定性与合入）
+---
+
+# Review
+
+> 参考 Anthropic REVIEW.md 做法。宗旨是**用户决策 + AI 协作**：AI 跑机器门禁、自查、出分级清单与建议；用户确认问题定性与合入。把"该机器兜底"与"靠 AI 自查"分开列明，避免注意力耗在机械逐行上。
+> 本文件为通用骨架;项目专属红线 / 命名 / 组件约定的具体口径在项目适配区（目录级 `AGENTS.md` 与 `.agents/hooks/`）补充。
+
+## P0 必拦（优先机器兜底，hook 覆盖不到的靠 AI 自查）
+
+- **架构红线**：分层依赖方向约束(如领域 / 应用层禁直接引用基础设施实现;豁免清单见目录级 `AGENTS.md` / 项目适配区)
+  - 机器兜底：项目自有架构门禁(如有,`.agents/hooks/`)
+- **审计字段**：项目约定的公共审计字段必须由统一基础设施自动写入，禁业务代码手工补写
+  - 机器兜底：项目自有门禁(如有,比对新增审计赋值;统一基础设施与初始化写入合法)
+- **删除拦截**：删除前必须查子级 / 业务引用，被引用时按项目统一口径报错拒绝；无数据库外键兜底的引用(值引用 / 跨模块单据引用)必须服务层显式查
+  - 机器兜底：项目自有门禁(如有,删除调用点与 allowlist 比对) + AI 自查守卫正确性(每个调用点核对删前查引用)
+- **入参校验**：必填字符串判空，范围型字段范围校验，非法输入按项目统一错误口径拒绝
+  - 机器兜底：项目验证测试覆盖(如有) + AI 自查
+- **L2 / L3 改动无 spec**：拒收，先回 `workflow/specs/` 立 spec 确认通过
+
+## P1 应拦（自查重点）
+
+- **DB 命名与迁移**：遵循项目表 / 字段 / 外键命名规范与 schema 变更流程(见目录级 `AGENTS.md`);不得擅自引入项目未采用的迁移机制
+- **前端形态**：新增 / 编辑与大数据量选择等交互遵循项目组件约定(弹层 vs 跳页、选择器形态、表格与样式统一等)
+- **表单**：可选字段空值按项目约定归一化后再提交;禁改后端 DTO 规避校验
+- **状态管理**：遵循项目状态管理模式;store 调 API，组件只调 store
+- **API 入参边界**：写操作禁 `[FromBody]` 绑定领域实体（一律 DTO）；入参 DTO 禁含主键与审计字段
+- **导入信任边界**：导入执行端点服务端全量复验，禁信任客户端校验结果；解析失败进错误行汇总，禁静默丢弃
+- **Create/Update 校验同口径**：Create 已有校验 Update 必须同口径；被引用的标识符字段禁改
+- **查询分页与状态语义**：分页参数范围校验 + 服务层钳制；非法状态与不存在分离(按项目统一错误口径,如 400 / 404)
+- **spec 承诺的断言落地**：spec §测试列出的用例 / 断言须真落到测试或验证脚本；「写进 spec」不等于「跑得起来」，且常驻断言禁写成随时间增长的行数常量
+- **跨宿主薄适配正文漂移**：改 `templates/_agents/{commands,roles}/*.md` 后必须跑 `flow-kit sync-hosts --apply` 单向同步注册表内全部宿主薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）；装户视角由 `flow-kit doctor` §6.7 检查（包源环境 §6.7 skipped）
+
+## P2 建议（提醒，不拦合入）
+
+- 样式统一性（深色 / 浅色主题、卡片样式）
+- 注释完整性（复杂逻辑处补注释，AGENTS.md 已说的不重复）
+- Conventional Commits 中文（feat / fix / docs / style / refactor / perf）
+- 历史同类 incident 的复盘三件套是否补齐
+
+## 审查分工（用户决策 + AI 协作）
+
+- **机器兜底**（pre-commit / pre-push / test 自动拦，无需人守）：门禁清单与判据以 `.githooks/`、`.agents/hooks/`、`check-loop.sh` 头部注释为准；`项目测试命令` 跑自动化用例。
+- **AI 复核**：机器门禁完成后优先委派 `independent-reviewer`，聚焦 P0 hook 未覆盖项 + 全部 P1（P2 视精力）——产出分级问题清单 + 修复建议。复核方法参考 `code-review` 技能（Standards×Spec 双轴）；每条 finding 报告前过 `review-verification-protocol` 防误报门（锚定 file:line、给出证据、校准严重级，不确定就降级为提问）。
+- **独立性**：L2 / L3 必须用独立子智能体，宿主不支持时另开新会话，不得由原作者自查冒充；L0 / L1 且宿主不支持子智能体时可由主智能体按同一复核契约执行。
+- **用户决策**：问题定性（误报驳回 / P0 成立必修 / P1、P2 处置裁量）+ 合入时机；git 历史即评审记录，追溯靠 commit 与 tag。

package/modules/hosts/codex/commands/wf-source-sync-check.md

@@ -0,0 +1,89 @@
+---
+description: 装户面同步一致性检查（包源 templates/_agents/ vs 装副本 .agents/ 三类差异：缺失 / 孤儿 / 漂移）
+---
+
+# Source-Sync-Check · 装户面同步一致性
+
+> `templates/_agents/` 包源 vs `.agents/` 装副本——三类差异报告：缺失 / 孤儿 / 漂移。
+> managed 文件由 `flow-kit sync` 跟踪；owned 文件由 `flow-kit doctor` §6.6 校验——本工具补"两者都没扫"的真空地带（结构级差异）。
+
+## 何时跑
+
+- 改 `templates/_agents/*` 包源后
+- 怀疑装副本未跟包源更新
+- 体检装副本完整性（清理前 / 发版前）
+- 不跑：仅改装副本 `.agents/*`（B-b 决策「只报告」+ 不反向同步）
+
+## 怎么跑
+
+### 默认 `--diff`（仅报告）
+
+```
+node .agents/scripts/source-sync-check.mjs --diff
+node .agents/scripts/source-sync-check.mjs --json                       # 机器可读
+node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>   # 自定义路径
+```
+
+输出三类：
+- **缺失**（missing）——包源有 / 装副本无（如新增文件 init 未执行）
+- **孤儿**（orphan）——包源无 / 装副本有（如历史残留 / 用户本地添加）
+- **漂移**（drift）——两者都有但 sha 不一致（如包源改了装副本未跟）
+
+**排除**：
+- `templates/_agents/cache/`（运行时缓存，与 `flow-kit sync` 既有约定一致）
+- `.agents/kit.json` / `.agents/settings.json`（init 渲染产物，不属双源）
+
+### 输出示例
+
+```
+▶ flow-kit source-sync-check --diff
+  包源 (templates/_agents/) 49 份  |  装副本 (.agents/) 49 份
+  缺失（包源有 / 装副本 无）1：
+    - scripts/source-sync-check.mjs
+  孤儿（包源无 / 装副本 有）1：
+    - hooks/commit-check.config.json
+  漂移（包源装副本都有但 sha 不一致）3：
+    - commands/maintain.md  pkg=3782b695…  tgt=26203f7b…
+    - notes/runtime-env.md  pkg=aedde1ba…  tgt=ad08441e…
+    - scripts/ensure-board.mjs  pkg=e66653b0…  tgt=b6f3cc9b…
+```
+
+### 自验
+
+```
+node .agents/scripts/source-sync-check.test.mjs   # 11 场景全过
+npm test                                            # 含 source-sync-check 套件
+flow-kit doctor                                     # 10/0/0
+```
+
+## 边界（不要做）
+
+- 不要自动化同步（B-b 决策「只报告不修复」——与 `gate-checklist` 同源）
+- 不改 managed 台账跟踪逻辑（`sync.mjs` 不动）
+- 不改 owned 漂移校验（`doctor.mjs` §6.6 不动）
+- 不反向同步——装副本独自有文件（如 hooks/commit-check.config.json）可能是装户配置，不应被删
+- 不检查注册表内宿主 `modules/hosts/` 薄适配漂移（那是 `flow-kit sync-hosts` 范围）
+
+## 当前已识别的真实漂点（首次实测，2026-09-25）
+
+- **缺失**：本工具写完后未同步装副本（预期内——随本次 commit 解决）
+- **孤儿**：`.agents/hooks/commit-check.config.json`（装副本独有，疑似装户配置）
+- **漂移**：`commands/maintain.md` / `notes/runtime-env.md` / `scripts/ensure-board.mjs`
+
+修复留后续 incident / intent 跟踪（不在本次范围）。
+
+## 与既有工具的关系
+
+| 工具 | 作用域 | 算法 |
+|---|---|---|
+| `flow-kit sync` | managed 文件（kit.json 台账跟踪）| 三态覆盖 + 加新 + 报错缺 |
+| `flow-kit doctor` §6.6 | owned 文件（kit.owned 哈希比对）| 盘面 sha vs 台账哈希 |
+| **`flow-kit source-sync-check`** | **所有文件结构（包源 ↔ 装副本全集）** | **sha 全量比对 + 缺失/孤儿分类** |
+
+三者互补，不重叠。
+
+## 相关留痕
+
+- intent：`workflow/intents/2026-09-25-source-sync-check.md`
+- plan：`workflow/plans/2026-09-25-source-sync-check.md`
+- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（包源改了装副本未同步——本工具预防性体检）

package/modules/hosts/codex/commands/wf-sync-hosts.md

@@ -0,0 +1,66 @@
+---
+description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 + 单向 apply；frontmatter 不动）
+---
+
+# Sync-Hosts · 跨宿主适配层正文段同步
+
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
+> 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
+
+## 何时跑
+
+- 改 `templates/_agents/commands/*.md` 正文后（8 个 commands 文件）
+- 改 `templates/_agents/roles/*.md` 正文后（3 个 roles 文件）
+- 装户跑 `flow-kit doctor` 报"跨宿主薄适配正文漂移 N 对" WARN 时
+- 不跑：仅改 frontmatter；改 trae 钩子/规则；改包源其他文件
+
+## 怎么跑
+
+### 默认 `--diff`（仅报告）
+
+```
+node bin/flow-kit.mjs sync-hosts --diff
+node bin/flow-kit.mjs sync-hosts --json   # 机器可读
+```
+
+输出三类：
+- **正文对齐 N 对** — sha 一致，无需处理
+- **正文段漂移 N（权威源 vs 薄适配 sha 不一致）** — `--apply` 同步方向；不区分"权威源改了"或"薄适配手改了"，由用户拍板
+- **⚠️ 权威源声明但薄适配缺失** — `add-host <h>` 接管后跑 `--apply` 才会装（apply 不自动创建）
+- **⚠️ 孤儿薄适配（权威源无对应文件）** — 历史残留或宿主特化，apply 不删
+
+### `--apply` 单向同步
+
+```
+node bin/flow-kit.mjs sync-hosts --apply
+```
+
+按权威源正文覆盖薄适配正文段；薄适配原 frontmatter 保留（trae name: wf-X、opencode 描述、zcode/omp 中文风格各自不动）。apply 不反向同步——薄适配手改了正文也会被覆盖（这是设计选择，避免漂移方向歧义）。
+
+### 自验
+
+```
+npm test                                       # 含 sync-hosts.test.mjs 8 场景
+node bin/flow-kit.mjs doctor                   # 装户跑 §7.x PASS；包源跑 §7.x skipped
+sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已探测分流
+```
+
+## 边界（不要做）
+
+- 不要 `--apply` 反向同步（写权威源）：权威源是真相，薄适配手改会被覆盖——这是设计，apply 前先看 `--diff`
+- 不要删除孤儿薄适配：可能是宿主特化或历史残留，apply 不动
+- 不要改 frontmatter 让 sha 凑齐：frontmatter 是宿主特化字段（trae name: wf-X 等），工具不参与
+- 不要把「避免与权威版本漂移」明文加回去——这是旧契约的指针风格，已被 B-b 正文副本取代
+- 装了新宿主后跑 `--apply`：新宿主目录空白，apply 不会自动创建薄适配（薄适配须经 `add-host <h>` 接管）
+
+## 不在本次同步范围
+
+- trae 钩子（`modules/hosts/trae/hooks/*.cjs`）— 独立演进的工程件
+- trae 规则（`modules/hosts/trae/rules/*.md`）— 同上
+- 包源 .agents/scripts/*.cjs（pre-commit 等钩子）— 同步由 `flow-kit sync` 走 managed 台账负责
+
+## 相关留痕
+
+- intent：`workflow/intents/2026-09-25-cross-host-sync.md`
+- plan：`workflow/plans/2026-09-25-cross-host-sync.md`（含 B-b 方案拍板）
+- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）

package/modules/hosts/codex/commands/wf-test.md

@@ -0,0 +1,66 @@
+---
+description: Test 阶段:静态门(架构红线 + build + test)+ UI 实测(headless Chrome)
+---
+
+# Test · 静态门 + UI 实测
+
+> 两道闸:静态门全过 + 涉及 UI 走浏览器实测。失败不放过。
+
+## 1. 静态门(代码改动后必跑)
+
+```bash
+# 项目自有门禁脚本(如有;清单以 .agents/hooks/ 与目录级 AGENTS.md 头部注释为准)
+项目构建命令                                      # 编译
+项目测试命令                                       # 自动化测试
+项目类型检查命令                                  # 前端类型检查/构建(涉及前端时跑)
+node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1 即先修台账再继续:跑 gen-wiki-board.mjs 补索引/看板;pre-commit 已按增量自动拦,此行用于改完即验)
+node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 owned 漂移 + §6.7 跨宿主薄适配正文漂移(装户环境；包源环境 §6.7 skipped)
+```
+
+> **环境注记**：本地服务占用构建产物导致编译失败、多会话并行时「谁跑静态门 / 提交谁先停服务」等约定——如有,见项目注记 `.agents/notes/runtime-env.md` §2,跑静态门前先过一眼。
+
+> **Windows / PowerShell 取码**：`bash` / `sh` 不在 PATH、命令不存在时 `$LASTEXITCODE` 保持旧值（假绿）——调法与取真码姿势见 `.agents/notes/runtime-env.md` §1(如有),断言「通过」前先确认命令真的跑了。
+
+任一失败 → 不进 UI 实测,回 `build.md` 修复;失败难复现(偶发/跨层)时先用 `diagnosing-bugs` 技能走诊断循环(红→最小化→假设→插桩→修复→回归),修复仍回 `build.md`。
+
+> **门禁 / 看板 / wiki 脚本改动**(`.agents/scripts/`、`.agents/hooks/`、`.agents/board/`):按改动对象跑对应 fixture 回归,须全绿——闭环门禁 `node .agents/scripts/check-loop.test.mjs`、wiki 生成器 `node .agents/scripts/gen-wiki-board.test.mjs`、提交前 hook 测试(如有);涉及看板告警规则时,用同批 workflow fixture 双跑 `check-loop`（经 shim 或 .mjs 直跑）与看板 `/api/board`,断言 hard-block 集合被看板告警覆盖(防口径分叉)。
+
+## 2. 切库冒烟(切换 / 新增目标库后必跑)
+
+改了项目数据库连接配置(或新增目标库)时,静态门不足以保证库-代码一致(编译 / 类型检查不连库;自动化测试覆盖受既有用例限制),必须额外两步:
+
+1. **schema 比对**:代码期望的表与列 vs 目标库实际 schema。范围 = 近期 schema 变更脚本涉及对象 + 项目基础 / 平台只读表(如有)
+2. **接口探活**:跑项目自有冒烟脚本(如有,脚本路径登记于根 `AGENTS.md`「项目适配区」;脚本不可用再手工逐个 GET 关键端点),任一非 200 即判库未同步,**停在此步,不部署**
+
+防复发条目的断言增量登记在 `workflow/regression-checklist.md`(如有)。
+
+## 3. UI 实测(涉及前端改动时)
+
+调用项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`(如有)；环境细节(服务起法 / headless Chrome 参数 / CDP 注入 / 进程生命周期)见该技能与项目注记 `.agents/notes/runtime-env.md`(如有)。
+
+## 4. 独立复核(L2/L3 强制)
+
+- L2/L3 改动必须由 `independent-reviewer` 在独立上下文复核;宿主不支持子智能体时另开新会话,避免沿用原修改思路盲区
+- 复核者读入口文档(intent / incident) + spec + plan + diff,判断变更意图与风险
+- 复核意见交用户定性(采纳 / 驳回);采纳项回 `build.md` 修改
+
+## 子代理调用约定
+
+- 静态门不委派;UI 实测委派 `ui-verifier`(静态门通过后)、独立复核委派 `independent-reviewer`,均要求读取对应 `.agents/roles/*.md`;宿主不支持时按 frontmatter `fallback`(reviewer 必须另开新会话,不得主智能体自查冒充)。
+- 子智能体只返回证据与结论——失败项修复仍回 `build.md`,不得在 Test 阶段顺手改代码;修复后重跑本阶段,全过后用户确认再关单。
+
+## 确认后
+
+- 输出测试报告(通过项 / 失败项)
+- 失败项已修复并复测通过
+- **关单**（日常闭环点，不依赖是否上 prod）:
+  - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
+  - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」，intent → done；同名 spec（若有）仍 approved → done
+  - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
+  - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
+  - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）
+  - **委派快照回写**：关单后若 `workflow/delegations.md` §月度聚合快照缺当月行或 doctor §6.5 报陈旧 → 跑 `node .agents/scripts/agg-delegations.cjs` 并回贴当月快照行
+- L1：本阶段结束，不进 deploy
+- L2/L3：仅当用户确认要上 prod 时进 `.agents/commands/deploy.md`

package/modules/hosts/codex/skills/flow-kit/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: flow-kit
+description: 按仓库内的 AI 闭环开工。用户说开工、走闭环、起 intent、起 spec 时使用。
+---
+
+# flow-kit
+
+仓库根 AGENTS.md 是 Codex 自动读取的项目说明。阶段命令的权威正文在 .agents/commands/。
+
+- 总入口：.agents/commands/new-task.md
+- 与 Claude / Cursor 同形的薄转发，供显式引用：.codex/commands/wf-*.md
+- 角色薄转发：.codex/agents/*.md，行为以 .agents/roles/ 为准
+
+Codex 会装入本技能。.codex/commands 不会被注册成斜杠命令。

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

@@ -0,0 +1,52 @@
+---
+name: implementer
+description: 公共契约见 .agents/roles/implementer.md
+---
+# Implementer
+
+> 公共角色契约（本文件）：`.agents/roles/implementer.md`。宿主薄适配（各宿主目录下 `agents/implementer.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
+## 职责
+
+执行已经由主智能体和用户确认、范围明确的实现任务。适用范围仅限：
+
+- 单文件或边界清晰的局部实现
+- 有明确复现路径的 bug 修复
+- 编写或调整任务直接要求的测试
+- 修复与任务直接相关的编译错误
+
+## 必需输入
+
+开始前必须获得：
+
+- 一句话任务目标
+- 必须读取的入口文档、spec 或 plan
+- 允许修改的文件清单
+- 可执行的验收条件
+
+任一输入缺失或相互冲突时，停止并向主智能体报告，不自行扩大范围。
+
+## 行为边界
+
+- 只修改明确授权的文件；若必须触及其他文件，先停止并说明原因。
+- 仓库可能有其他智能体或用户同时工作；保留现有改动，不回退、不覆盖无关修改。
+- 复用现有实现、标准库和已安装依赖，保持最小工作 diff。
+- 不修改公共接口、数据 Schema、依赖、构建步骤、安全或权限策略。
+- 不执行提交、推送、发布、数据迁移或破坏性操作。
+- 不顺手重构、格式化或清理与任务无关的代码。
+
+## 验证
+
+- 运行任务指定的最小相关检查。
+- 检查失败时只修复由本次改动引起且仍在授权范围内的问题。
+- 同一验证连续失败三次，或继续需要猜测需求时，停止并报告阻塞。
+
+## 输出
+
+返回给主智能体：
+
+1. 修改文件清单
+2. 每个文件的改动摘要
+3. 已运行的验证及结果
+4. 未解决的阻塞或剩余风险
+

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

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

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

@@ -0,0 +1,48 @@
+---
+name: ui-verifier
+description: 公共契约见 .agents/roles/ui-verifier.md
+---
+# UI Verifier
+
+> 公共角色契约（本文件）：`.agents/roles/ui-verifier.md`。宿主薄适配（各宿主目录下 `agents/ui-verifier.md`）正文段同源本文件，frontmatter 各自保留宿主特化字段（check-loop 检查项 6 按本引用校验适配层不断线）。
+
+## 职责
+
+对已经实现的 UI 改动执行浏览器实测并收集可复核证据。只验证，不修复。
+
+## 必需输入
+
+开始前必须获得：
+
+- 待验证页面或路由
+- 用户操作步骤
+- 每一步的预期结果
+- 涉及的改动文件或 diff 范围
+
+缺少可观察的预期结果时，停止并向主智能体报告。
+
+## 执行
+
+1. 读取项目根目录 `AGENTS.md`，以及改动域目录级 `AGENTS.md`（如有，前端改动域）。
+2. 读取并遵循项目 UI 实测技能 `.agents/skills/verify-ui/SKILL.md`（如有）。
+3. 启动该技能指定的 API、前端和浏览器验证环境。
+4. 按输入步骤验证页面行为；布局类问题优先使用可重复的 DOM 几何数据。
+5. 收集控制台、网络请求、DOM 数据或截图等证据。
+6. 结束时关闭本次启动的后台进程。
+
+## 行为边界
+
+- 不修改代码、配置、测试数据或工作流文档。
+- 不自行修复发现的问题；将失败证据交还主智能体。
+- 不使用生产环境或真实业务数据。
+- 无法启动环境或完成关键路径时，报告阻塞，不把部分验证标记为通过。
+
+## 输出
+
+返回：
+
+1. 验证环境与页面路由
+2. 逐项通过/失败结果
+3. 失败的复现步骤和证据
+4. 控制台或网络异常
+5. 未验证范围与阻塞项

package/modules/hosts/cursor/commands/wf-build.md

@@ -0,0 +1,79 @@
+---
+description: Build 阶段:起 plan + 实现代码 + 自验(确认后才动代码)
+---
+
+# Build · 起 plan + 写代码
+
+> AI 起草 plan,用户确认;进计划模式列改动,用户确认;最后才动代码。两道确认门。
+
+## 执行
+
+### 起草 plan
+
+1. 确认同名入口文档（approved intent 或已确认的 incident）+ spec（若 L2/L3）均已确认；否则回上一阶段（fill/confirm 未过即拒）
+2. 起草 plan:
+   - 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
+   - L2/L3 按 4 节填写:任务拆解(每个任务有判据) / 风险评估 / 执行顺序 / 遗留项
+   - L1 默认极简两节:改动面(逐条文件+做什么) / 验证方式(一行静态门+按需 UI 实测)；仅多文件多步骤时再加任务拆解/执行顺序
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
+4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
+
+### 进计划模式列改动
+
+5. **不要直接动代码**。先进「计划模式」:
+   - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `node .agents/scripts/kb-search.mjs --scope workflow --module <token> "<关键词>"`——命中 incident 的根因 / 防复发条目列入改动自查
+   - 列改动文件清单(读后改 vs 新建)
+   - 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
+   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（见 incidents/2026-09-25-wf-runtime 复盘）
+   - 标注触达红线(对照根 `AGENTS.md`「Working rules」+ 改动域目录级 `AGENTS.md`（如有）)
+6. 停下,等用户确认改动清单
+
+### 实现
+
+7. 确认后按 plan 顺序推进;每个任务对照判据自验。若任务满足 `.agents/roles/implementer.md` 的边界,主智能体可将单个工作包连同必读材料、授权文件和验收条件委派给 `implementer`;否则由主智能体执行
+8. 自验:按改动域跑 `项目构建命令` / `项目类型检查命令` / `项目测试命令`(对应编译 / 前端类型检查 / 自动化测试;静态门全集见 `test.md` §1)
+9. **项目架构红线**:数据访问模式、公共字段写入等以根与目录级 `AGENTS.md`(如有)红线为准,不自创旁路
+10. **L3 且含 schema 变更时**:schema 变更走项目约定的维护方式(人工 SQL / 迁移工具,以目录级 `AGENTS.md` 或 spec 约束为准),不得擅自引入项目未采用的迁移机制（仅运行时 / 管线类 L3 无此约束）
+11. 实现中若需偏离已确认的 plan(改公共接口 / 动 plan 未列文件 / 引新依赖 / 影响任务判据)→ 停下,向用户说明原因与影响,确认后再继续
+
+## 技能辅助(可选,宿主级 skills)
+
+- plan 任务多、依赖复杂时:用 `to-tickets` 拆 tracer-bullet 任务单(每张带阻塞边);结果回填 plan「任务拆解」节,不发布外部 tracker
+- 后端逻辑改动:有测试基建的用 `tdd` 测试先行(红→绿→重构);整体实现纪律可用 `implement` 驱动
+- 遇合并冲突:用 `resolving-merge-conflicts` 按意图逐 hunk 处理
+- 技能不改变两道确认门、红线检查与委派边界
+
+## 红线提示(本阶段高频踩)
+
+- 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
+
+## 改权威源后必跑（薄适配同步防漏）
+
+- 改 `templates/_agents/{commands,roles}/*.md` 正文后跑 `node bin/flow-kit.mjs sync-hosts --diff` → 拍板 → `--apply` 单向同步（只动正文段，frontmatter 不动）；口径与边界详见 `.agents/commands/sync-hosts.md`
+
+## 改 doctor / check-loop 后必跑（三处口径对账）
+
+- 改 `src/doctor.mjs` 加新 § 检查项 → 跑 `node .agents/scripts/gate-checklist.mjs --diff` 看 doctor ↔ check-loop 对照表
+- 改 `.agents/scripts/check-loop.sh` 加新 § 检查项 → 同上
+- 任一处有而另一边无 → 工具报"缺点"，由用户拍板是否补齐（不自动同步，B-b 决策）；详见 `.agents/commands/gate-checklist.md`
+
+## 改包源后必跑（装户面同步一致性）
+
+- 改 `templates/_agents/*` 包源后 → 跑 `node .agents/scripts/source-sync-check.mjs --diff` 看装副本 `.agents/` 是否同步（缺失 / 孤儿 / 漂移三类差异）
+- 漂移说明包源改了装副本未跟；缺失说明新增文件 init 未执行；孤儿说明装副本独有（可能是装户配置，不删）
+- **新增 managed 类文件须经 init/sync 登记，禁手动双写绕过台账**——手工同时写 `templates/_agents/` 与 `.agents/` 会绕过台账登记，使该文件永远不被 sync 升级（`doctor` 台账覆盖率检查会拦；见 incidents/2026-09-26-managed-ledger-adopt 复盘）
+- 门禁边界（pre-commit 双源一致性）：比较工作树非暂存区——两侧改好、分两笔提交不拦（最终一致即可）；包源删除文件退化为「孤儿」只报告不拦，删包源须手动清理装副本残件（复核 P2-2 声明，2026-09-27 gate-hardening-p2-batch）
+- B-b 决策「只报告不修复」；详见 `.agents/commands/source-sync-check.md`
+
+## 子代理调用约定
+
+- plan 起草、风险判断、改动清单与两道确认门由主智能体负责;仅两道确认后范围明确的工作包可委派 `implementer`,公共接口 / Schema / 依赖 / 安全 / 权限 / 破坏性操作不得委派。
+- 多工作包并行 / 链式推进:编排机制(声明随 plan 草稿一并确认;确认后读 `.agents/workflows/` 按机制文档执行,`steps/` 为项目自定义步骤扩展点);详见 `.agents/workflows/_TEMPLATE.md`。
+- 子智能体返回后,主智能体须检查 diff 与授权文件范围、确认未覆盖既有修改并重跑相关验证;不支持子智能体时 `fallback: main`,验收标准不变。
+
+## 确认后
+
+- plan 状态 → done（实现完成；intent / spec 关单在 test）
+- commit：L1+ 入口文档 / spec / plan 随代码同一提交（Conventional Commits 中文 feat/fix/refactor/perf）；docs 豁免与 bootstrap 可单独 `docs(*)`
+- 进 `next: .agents/commands/test.md`

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

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