agentic-flow-kit 0.8.0 → 0.9.1

package/modules/hosts/claude/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`

package/modules/hosts/claude/commands/wf-design.md

@@ -0,0 +1,42 @@
+---
+description: Design 阶段:起 spec(L2/L3 强制,L1 可省略)
+---
+
+# Design · 起 spec
+
+> L2/L3 强制;L1 可省略(直接跳 `next: build.md`)。
+
+## 执行
+
+1. 确认同名入口文档已批准：新需求为 approved intent，修复为已确认的 incident 草稿；否则拒绝，分别回 `plan.md` / `maintain.md`（2026-09-30 起机器强制：fill-spec / confirm-doc 对前置未过直接拒绝 exit 2、不落盘不记账）
+2. 级别判断(对照 AGENTS.md 第 3 条):
+   - **L1**(实现级改动,未命中 L2/L3)→ 可省略 spec,直接跳 `next: build.md`
+   - **L2**(改规则 / 契约:编码权威 / 共享契约 / 既有接口语义 / 全局横切口径,闭集见 `new-task.md` §级别判断)→ 必须有 spec
+   - **L3**(数据与运行时结构:schema / 迁移 SQL / DI 链 / 认证与中间件管线)→ 必须有 spec + **新会话独立复核**
+3. 起草 spec:
+   - **填空工具先跑**：`node .agents/scripts/fill-spec.mjs --level <L1|L2|L3> --topic <主题> --output workflow/specs/<date>-<主题>.md`——输出含 frontmatter 5 字段 + 5 节正文（功能行为/数据流/系统改动/约束遵守映射/风险评估）的草稿；AI 据此填实
+   - 复制 `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
+**确认落态唯一入口**（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。
+- 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
+- 进 `next: .agents/commands/build.md`

package/modules/hosts/claude/commands/wf-gate-checklist.md

@@ -0,0 +1,77 @@
+---
+description: 三处口径一致性检查（doctor §检查项 ↔ check-loop §检查项，显式配对登记表 + 断档/未登记告警）
+---
+
+# Gate-Checklist · 三处口径一致性（显式配对登记表）
+
+> `src/doctor.mjs` § 检查项 ↔ `.agents/scripts/check-loop.sh` § 检查项，按脚本内 **PAIRS 登记表**对照。
+> 任何一处加新检查项，另一处不会自动同步——本工具报「未登记」；检查项被删/改号而登记未跟报「断档」。
+> 只报告不修复（B-b 决策）：缺点暴露给用户拍板，本工具不自动同步；exit 恒 0。
+
+## 何时跑
+
+- 改 `src/doctor.mjs` 加新 § 检查项后（同时须登记 PAIRS）
+- 改 `.agents/scripts/check-loop.sh` 加新 § 检查项后（同时须登记 PAIRS）
+- 怀疑两处口径不一致时
+- 不跑：仅改既有检查项的提示文案（不动 § 项与登记表）
+
+## 登记表纪律（契约）
+
+`templates/_agents/scripts/gate-checklist.mjs` 内 **PAIRS** 是配对单源，三选一登记：
+
+| 形态 | 写法 | 含义 |
+|------|------|------|
+| 直接配对 | `{ doctor: 'N', cl: 'M' }` | 同一检查两处实现 |
+| 声明独有 | `{ doctor: 'N', cl: null }` | doctor 装户体检面，无 check-loop 对应（原 intent 拍板只报告不修复） |
+| 经 §7 覆盖 | `{ doctor: '7', cl: 'M' }` | doctor §7 整体运行 check-loop，#M 自动流入 doctor |
+
+- 加新 § 检查项不登记 → 工具报「未登记」（新检查项没对账——核心信号）
+- 删/改检查项不动登记表 → 工具报「断档」
+- 关键词匹配已退役（2026-09-25 registry 重写：实测 18×14 项只匹配 2、28 条噪声缺点，真漏点不可见）
+
+## 怎么跑
+
+```bash
+node .agents/scripts/gate-checklist.mjs --diff   # 人类可读（默认）
+node .agents/scripts/gate-checklist.mjs --json   # 机器可读
+```
+
+输出四段：总览计数 → 对照表（登记表展开）→ 断档（如有）→ 未登记（如有）；全绿时输出「登记完整」。
+
+### 输出示例
+
+```
+▶ flow-kit gate-checklist --diff（显式配对登记表）
+  doctor §检查项: 12  |  check-loop §检查项: 14  |  直接配对 2 + 经 §7 覆盖 12 + 声明独有 9
+  对照表（登记表展开）:
+    ✓ §5 占位符残留 ↔ #2 模板字段占位符残留(YYYY-MM-DD / <主题> 等…)（占位符残留）
+    ● §1 Node 版本（声明独有：Node 版本——装户体检独有）
+    ✓ §7 check-loop ↔ #1 入口文档/spec/plan 同名配对(…（经 §7 整体运行覆盖）
+  ✅ 登记完整（0 断档 / 0 未登记）
+```
+
+### 自验
+
+```bash
+node .agents/scripts/gate-checklist.test.mjs   # 13 场景全过
+npm test                                       # 含 gate-checklist 套件
+```
+
+## 边界（不要做）
+
+- 不要把「登记完整」当作强制门 —— B-b 决策「只报告不修复」：断档/未登记暴露给 follow-up，exit 恒 0
+- 不要改 doctor / check-loop 检查项来消音 —— 登记表才是该改的地方（配对 / 独有 / 经 §7 三选一）
+- 不要扩展到看板告警 —— 看板当前无告警规则（gen-wiki-board.mjs 不做判定），扩展超出范围
+- 不要绕过登记直接改解析正则 —— 解析面只认 doctor `// N.` 节注释与 check-loop `// N.` 项注释（.mjs 头部清单，fallback 旧装户 .sh `# N.`）
+
+## 不在本次同步范围
+
+- `.agents/board/` 看板告警（无告警规则）
+- `wiki/知识沉淀总览.html` 渲染（数据来源是 workflow/INDEX.md 与 wiki 目录，非本工具对照）
+- `flow-kit sync` managed 台账追踪（gate-checklist 不在 managed 范围）
+
+## 相关留痕
+
+- intent（登记表重写）：`workflow/intents/2026-09-25-gate-checklist-registry.md`
+- intent（工具首建）：`workflow/intents/2026-09-25-gate-checklist.md`
+- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（owned 漂移未对账，催生本工具）

package/modules/hosts/claude/commands/wf-maintain.md

@@ -0,0 +1,76 @@
+---
+description: Maintain 阶段:立 incident + 复盘三件套(修复 / 防复发 / 规范条目)
+---
+
+# Maintain · 立 incident + 复盘三件套
+
+> 修复走 incident 流程;incident 在 L1+ 即 **intent 等价物**(check-loop 已认 incident≡intent),不必另造 intent。spec/plan 与 incident 同名即闭环。
+
+> 事故回到 Plan。复盘三件套缺一不可,防复发承诺不留在文档里。
+
+## 执行
+
+> **看板（可选，默认不拉起）**：需要实时看板时手动跑 node .agents/scripts/ensure-board.mjs（跨平台；幂等：探活 / 旧代码自动重启 / 全新启动才弹浏览器；多项目并行自动上探首个可用端口），链接以脚本输出为准（基端口 8933）；不开看板不影响任务流程。
+
+### 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` 只在关单出现。**L2/L3 机器前置**：起草 spec 时 fill-spec / confirm-doc 校验「时间线含『用户确认』留痕」，未过即拒（exit 2）——被拒回本流程补留痕。
+
+### 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——两跳均走确认门 `node .agents/scripts/confirm-doc.mjs <path>`（open→fixed / fixed→closed，无单跳；2026-09-28 起 check-loop 15 对账，AI 不得直改状态）
+- 若需新 intent → 进 `next: .agents/commands/plan.md`

package/modules/hosts/claude/commands/wf-new-task.md

@@ -0,0 +1,65 @@
+---
+description: AI-Native 闭环总入口:6 阶段指令索引(Plan→Design→Build→Test→Deploy→Maintain)
+---
+
+# New Task · 闭环总入口
+
+> 6 阶段指令索引。AI 读 AGENTS.md 后按阶段路由,不并阶段、不跳阶段。
+
+## 6 阶段指令索引
+
+| 阶段 | 指令 | 触发短语 | 可委派子智能体 | 确认点 |
+|------|------|---------|----------------|--------|
+| **Plan** | [.agents/commands/plan.md](.agents/commands/plan.md) | "起个 intent" / "要做个 <功能>" | 无 | intent 要点确认 |
+| **Design** | [.agents/commands/design.md](.agents/commands/design.md) | "起个 spec" / "intent 看过了" | `independent-reviewer`(L3) | spec 草稿确认(L3 加独立复核) |
+| **Build** | [.agents/commands/build.md](.agents/commands/build.md) | "起个 plan" → "动手吧" | `implementer`(确认后、范围明确时) | plan 确认 + 动手前确认 |
+| **Test** | [.agents/commands/test.md](.agents/commands/test.md) | "改完了" / "跑下 verify" | `ui-verifier`、`independent-reviewer` | 测试全过(L2/L3 独立复核)+ 关单；L1 结束 |
+| **Deploy** | [.agents/commands/deploy.md](.agents/commands/deploy.md) | "可以上了" / "过 release 清单" | 无 | 仅 prod：用户确认 + release tag |
+| **Maintain** | [.agents/commands/maintain.md](.agents/commands/maintain.md) | "线上出事了" / "记一笔 incident" | `implementer`(方案确认后) | 三件套要点确认 |
+| **Review**(横切,不占 6 阶段) | [.agents/commands/review.md](.agents/commands/review.md) | "评审一下" / "过 review 标准" | `independent-reviewer`(L2/L3 必须独立复核) | 问题定性与合入时机确认 |
+
+## 路由判断
+
+- **新需求 / 功能**:从 `plan.md` 进,立 **intent**(`workflow/intents/`)
+- **修复类任务 / 事故**:从 `maintain.md` 进,立 **incident**(`workflow/incidents/`);incident 在 L1+ 即 **intent 等价物**(check-loop 认 incident≡intent),不必另立 intent。先检索同类历史(`node .agents/scripts/kb-search.mjs "<关键词>" --scope workflow --type incidents,plans`),有同类先读其历史三件套;再按级别走:
+ - L0 → 直接修复;L1 → 立 incident 后进 `build.md` 起草并确认同名 plan → `test.md`
+ - L2/L3 → 立 incident 后进 `design.md` 起草并确认同名 spec,再进 `build.md` 起草并确认同名 plan → `test.md`
+ - 仅当根因属系统性 / 门禁缺位(maintain.md 三件套「是否需要新 intent」选"是")才另立 `workflow/intents/` 同名 intent
+- **改完代码要验证**:直接进 `test.md`（验证通过即关单；L1 到此结束）
+- **合入前评审**:直接进 `review.md`(横切,P0/P1/P2 分级清单 + L2/L3 独立复核)
+- **准备上线**:直接进 `deploy.md`（仅 prod；文档应已在 test 关单）
+
+## 级别判断(AGENTS.md 第 3 条)
+
+| 级别 | 改什么 | 流程 |
+|------|--------|------|
+| L0 | 文档/样式微调(无行为影响) | 直接 commit,豁免 intent |
+| L1 | **实现级改动**(未命中 L2/L3) | 轻量入口文档(intent / incident) + plan |
+| L2 | **规则 / 契约**(一处改、多处依赖) | 入口文档(intent / incident) + spec + plan 三件套 |
+| L3 | **数据与运行时结构**(schema / 迁移 SQL / DI 链 / 认证与中间件管线) | 同 L2 + spec 新会话独立复核 |
+
+> 级别判定同上表"改什么"列;混合改动按最高档定级。
+
+**L2 触达面**(闭集,命中任一即 L2;本体不改但改其输入域 / 调用点校验同样命中):
+
+1. **编码权威**:项目内「一处生成、多处消费」的编码 / 命名 / 取号规则(编码模板、序列发生器、命名空间与去重约束——具体清单按项目 AGENTS.md)
+2. **共享契约**:跨模块共享的基类 / DTO 形状、跨模块公共接口签名
+3. **既有接口语义**:既有参数或端点的行为变化(由失效变生效、默认值或钳制口径改变)
+4. **全局横切口径**:错误响应出口、分页与校验口径、聚合投影键
+
+> **负例(落 L1)**:纯页面表现 / 文案 / 布局 / 交互实现;纯新增端点或参数且既有行为不变;单模块内部重构且无对外契约变化。
+> **自查句**:能否列出 ≥2 个受影响的消费方(模块 / 端点 / 页面)?能 → L2。
+> 先例:本仓 `workflow/specs/`、`workflow/intents/` 下同类历史(kb 检索主题词)。
+
+> **L1 是默认档**:红线全不勾即 L1,无需正列举——判级只回答「是否命中 L2 四类或 L3 结构面」。
+> **L3 的「DI 链」按组合根与运行时管线理解**:DI 注册、中间件/认证管线、服务构造器依赖变更(先例:本仓 workflow/ 留痕中无 schema 变更仍定 L3 的同类历史)。
+
+## intent 豁免(避免小改动也走完整闭环)
+
+- **L0 新需求**:可直接处理；**L1 新需求**:立轻量 intent + plan(不必 spec)
+- **docs 级改动**(AGENTS.md / workflow/ 模板 / .agents/ 脚本与 commands / yaml):豁免 intent,走 Conventional Commits 直接 commit;若同时触及代码,按代码部分级别立 intent
+- **bootstrap 类改动**(引入规则本身):豁免 intent,commit message 显式声明 `bootstrap`
+
+## 闭环兜底
+
+- 门禁清单与判据以 `.githooks/` / `.agents/hooks/` / `check-loop.sh` 头部注释为准(本文件不复述、不写项数);hard-block = 配对断裂 / 回路断档 / 新建 done 未勾验。本地机器门只有本地钩子,禁 `--no-verify`(见根 `AGENTS.md`)。

package/modules/hosts/claude/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/claude/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/claude/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/claude/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 包源环境跳过）