@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-intel/skills/workflow-update-navigation/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: workflow-update-navigation
+description: "Use when code changes require incremental updates to .planning/navigation files before audit, archive, or future workflow steps."
+---
+
+## Legacy Command Metadata
+
+Original slash-command metadata retained only as workflow invocation guidance.
+
+```yaml
+user-invocable: true
+pattern: generator+reviewer
+inputs:
+- .planning/features/{功能名}/变更清单.md
+- .planning/navigation/
+output: .planning/navigation/{name}.md (updated)
+phase-gate:
+  step1: 加载变更清单和当前 navigation
+  step2: 识别受影响的代码库和模块
+  step3: 增量更新 Directory Map
+  step4: 增量更新 Call Chain Map
+  step5: 增量更新 Conventions
+  step6: 更新 Scan Status 和审查
+allowed-tools:
+- Read
+- Write
+- Bash
+- Grep
+```
+
+# Navigation Update
+
+Incrementally update navigation files after code changes. Do not re-scan the entire project — only update sections affected by the change list.
+
+## Outputs
+
+Always update:
+
+- `.planning/navigation/{name}.md` — affected codebase navigation files
+- `.planning/navigation/INDEX.md` — Codebase Registry scan status timestamps
+
+When `.planning/code-index/` exists or code-index support is part of the project workflow, also refresh and audit the machine index before editing Markdown navigation:
+
+- `.planning/code-index/files.jsonl`
+- `.planning/code-index/symbols.jsonl`
+- `.planning/code-index/relations.jsonl`
+- `.planning/code-index/diagnostics.jsonl`
+- `.planning/code-index/index.sqlite`
+- `.planning/code-index/AUDIT.md`
+
+Do not create by default:
+
+- New navigation files (only update existing ones)
+- New `.planning/` directories
+
+## Resource Loading
+
+- Read `references/incremental-update-guide.md` before updating any navigation file.
+
+## Phase 1 — Load Change List And Current Navigation
+
+1. Read `.planning/features/{功能名}/变更清单.md` — extract all code-level changes (new/modified/deleted/renamed files).
+2. Read `.planning/navigation/INDEX.md` — identify which codebases are affected by the changes.
+3. For each affected codebase, read its `.planning/navigation/{name}.md`.
+4. If `.planning/code-index/` exists, collect changed file paths and run an incremental code-index refresh before updating Markdown navigation:
+
+```text
+devflow_code_index(action="scan", changedFiles=["<changed-file>", "..."])
+devflow_code_index(action="audit")
+```
+
+If change list is missing, tell the user to run `workflow-change-plan` first.
+
+If code-index refresh fails, report the failure. Continue with navigation updates only when the changed files can still be safely traced from navigation and source; otherwise stop and fix the index first.
+
+## Phase 2 — Identify Affected Sections
+
+Cross-reference each change in the change list with the navigation file to determine which sections need updating:
+
+| Change Type | Affected Navigation Section | Update Action |
+|-------------|----------------------------|---------------|
+| New directory | `### Directory Map` | Add directory to tree and table |
+| Deleted directory | `### Directory Map` | Remove from tree and table, or mark deprecated |
+| New handler / controller | `#### API Modules` | Add row with route group, call chain |
+| Modified handler (new/changed routes) | `#### API Modules` | Update routes and call chain for that row |
+| Deleted handler | `#### API Modules` | Remove row or mark deprecated |
+| New page component | `#### Route-Component Map` | Add row with child components, composables, API calls |
+| Modified page component | `#### Route-Component Map` | Update child components / composables for that row |
+| New shared component | `#### Route-Component Map` | Update affected page rows that now use it |
+| New composable / API client | `#### Data Flow` | Add row with API client, state shape, consumers |
+| New job / scheduler | `#### Scheduled Jobs` | Add row with cron, trigger, call chain |
+| Modified job | `#### Scheduled Jobs` | Update cron or call chain for that row |
+| New external integration | `#### External Integrations` | Add row with path, direction |
+| Changed coding convention | `### Conventions` | Add or update convention row |
+| Unchanged modules | None | Skip — do not re-scan |
+
+Rules:
+- Changes that don't affect directory structure, call chains, or conventions are skipped (e.g., internal logic changes within a service method).
+- If a change affects a module that doesn't exist in the current navigation, add it as new.
+
+## Phase 3 — Update Directory Map
+
+For new or deleted directories identified in Phase 2:
+
+1. Read the changed directory from the actual codebase.
+2. Update the ASCII tree in `### Directory Map` — add new branches, remove deleted ones.
+3. Update the Directory | Purpose | Notes table.
+
+Scan depth: top-level and second-level only. Do not deeply read source files — infer purpose from directory names and file names.
+
+Gate: all changed directories from the change list are reflected in the Directory Map.
+
+## Phase 4 — Update Call Chain Map
+
+For affected handlers, routes, components, jobs, or integrations identified in Phase 2:
+
+**Backend-type codebases:**
+1. Read the changed handler files. Extract route registrations.
+2. Trace the call chain: handler method → service → repository → dao.
+3. Update `#### API Modules` table: add new rows, update modified rows, remove deleted rows.
+4. Read changed job files. Extract cron expression and call chain.
+5. Update `#### Scheduled Jobs` table.
+6. If new external integrations were added, update `#### External Integrations`.
+
+**Frontend-type codebases:**
+1. Read the changed page component files. Extract child component imports and composable usage.
+2. Read changed composable files. Extract API client calls and state shape.
+3. Update `#### Route-Component Map` table.
+4. Update `#### Data Flow` table.
+
+Use the same call chain tracing method as `workflow-project-context` Step 3b, but limited to changed modules only.
+
+If code-index is available, use `.planning/code-index/relations.jsonl` or `index.sqlite` as the first source for fine-grained call relationships, then read the changed source files to confirm evidence before updating navigation. Navigation remains a human-readable summary; do not copy unverified low-confidence relations into navigation as facts.
+
+Gate: every changed handler/route/component/job from the change list has its corresponding row updated in the navigation file.
+
+## Phase 5 — Update Conventions
+
+Only if the change list indicates convention changes:
+- `.cursorrules` or `AGENTS.md` / `CLAUDE.md` was modified
+- New coding patterns were introduced that differ from existing conventions
+- User explicitly requested convention update
+
+Extract conventions using the same method as `workflow-project-context` Step 3c, limited to changed areas.
+
+If conventions haven't changed, skip this phase.
+
+## Phase 6 — Update Scan Status And Review
+
+1. For each updated codebase navigation file:
+   - Update `Identity → Scan Status` to the current date
+   - Add a note: "Updated after 变更清单 execution, {日期}"
+2. Update `.planning/navigation/INDEX.md`:
+   - Sync the `Scan Status` column in the Codebase Registry for affected codebases
+3. Run the review checklist:
+
+- [ ] 变更清单中每个涉及代码结构的变更项都在 navigation 中有对应更新
+- [ ] 新增的 handler/route/component/job 调用链已追溯
+- [ ] 删除/重命名的模块在 navigation 中已更新或标记
+- [ ] Directory Map 反映当前代码库顶层目录
+- [ ] Scan Status 已更新为当前时间
+- [ ] INDEX.md Codebase Registry 已同步
+- [ ] 未变更模块未被重新扫描（没有不必要的写入）
+
+Fix gaps before reporting completion.
+
+## Executable Self-Check
+
+Run these commands after all navigation edits. Replace `<affected-navigation-file>` with every navigation file selected in Phase 1.
+
+```bash
+test -s .planning/navigation/INDEX.md
+test -s .planning/navigation/<affected-navigation-file>
+test -s .planning/code-index/AUDIT.md  # when the code index exists
+```
+
+When `.planning/code-index/` exists, call `devflow_code_index(action="validate")` and
+`devflow_code_index(action="audit")` before the shell artifact checks.
+
+The code-index commands are required only when `.planning/code-index/` exists or this workflow refreshed it. Pass only when every selected navigation file and `INDEX.md` is non-empty, `validate` and `audit` exit with code 0, and `AUDIT.md` contains no blocking finding. Also complete every Phase 6 checklist item; commands validate artifact integrity, while the checklist validates change-list coverage. If any check fails, do not advance to audit or archive: correct the navigation/index discrepancy and rerun the failed checks.
+
+## Downstream Read Contract
+
+- `workflow-complete-milestone` should verify that navigation `Scan Status` is not older than the last commit before archiving.
+- Future `workflow-requirement-baseline` invocations will read the updated navigation for conflict and reuse detection.
+- Future source-tracing tasks should use `.planning/code-index/` for fine-grained relation facts when available, with source readback before answering.

package/plugins/devflow-intel/skills/workflow-update-navigation/references/incremental-update-guide.md

@@ -0,0 +1,47 @@
+# 增量更新指引
+
+## 更新范围控制
+
+只重新扫描变更清单中涉及的模块。变更清单外的代码库和模块不做任何扫描或写入。
+
+如果项目存在 `.planning/code-index/`，先按变更文件刷新机器索引，再更新 Markdown navigation：
+
+```text
+devflow_code_index(action="scan", changedFiles=["<changed-file>", "..."])
+devflow_code_index(action="audit")
+```
+
+机器索引用于细粒度事实追踪，navigation 只记录人读摘要。低置信度或无源码证据的 relation 不应写成 navigation 事实。
+
+## 变更类型到更新章节的映射
+
+| 变更类型 | 文件路径特征 | 更新章节 |
+|---------|-------------|---------|
+| 新增目录 | 新增的目录路径 | Directory Map |
+| 删除目录 | 已删除的目录路径 | Directory Map |
+| 新增 handler/controller | `*_handler.go`, `*_controller.*` | API Modules |
+| 修改 handler 路由 | 同 handler 文件被修改 | API Modules（更新对应行） |
+| 新增页面组件 | `src/pages/**/*.vue`, `src/views/**/*.tsx` | Route-Component Map |
+| 新增公共组件 | `src/components/**` | Route-Component Map（更新引用者） |
+| 新增 composable | `src/hooks/**`, `src/composables/**` | Data Flow |
+| 新增 job | `*_job.go`, `*Job.java` | Scheduled Jobs |
+| 新增外部集成 | `pkg/**` 新增外部调用 | External Integrations |
+| 修改 .cursorrules | `.cursorrules` | Conventions |
+
+## 调用链追溯方法
+
+复用 `workflow-project-context` Step 3b 的追溯逻辑，但仅限于变更涉及的 handler/route/component/job。不变更的模块跳过。
+
+当 code-index 可用时：
+
+1. 先从 `.planning/code-index/index.sqlite` 或 `relations.jsonl` 查 changed files 对应 symbols/relations。
+2. 按 `routes_to`、`calls`、`imports`、`reads`、`writes` 扩展相关边。
+3. 回读 `evidence_path` 源码。
+4. 只把已确认且适合人读摘要的链路写入 navigation。
+
+## 标记已废弃
+
+如果变更清单删除了某个模块：
+- 不直接从 navigation 删除行
+- 在 Notes 列标记 `已废弃于 {日期}`
+- 下次全量初始化时由 project-context 清理

package/plugins/devflow-quality/agents/code-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: devflow-code-reviewer
+description: Read-only adversarial code reviewer focused on correctness, security, regressions, and contract violations in changed files.
+tools:
+  - read
+  - grep
+  - find
+  - lsp
+  - bash
+model: "@slow"
+thinkingLevel: high
+autoloadSkills:
+  - code-review
+---
+
+Review the actual diff and its affected call paths. Prefer concrete defects over style commentary. For each finding provide severity, file and location, triggering scenario, impact, and a minimal fix direction. Verify whether tests cover the failure.
+
+Do not edit code, fix findings, or mutate workflow state. If no actionable finding remains, say so and list the validation evidence inspected.

package/plugins/devflow-quality/agents/verification-runner.md

@@ -0,0 +1,21 @@
+---
+name: verification-runner
+description: Independent verification agent that executes tests and acceptance checks without modifying implementation or workflow state.
+tools:
+  - read
+  - grep
+  - find
+  - lsp
+  - bash
+  - browser
+  - devflow_mainflow
+model: "@task"
+thinkingLevel: medium
+autoloadSkills:
+  - workflow-verify-work
+  - workflow-generate-mainflow-cases
+---
+
+Verify the assigned acceptance criteria against the built system. Run the smallest deterministic checks first, then integration or browser flows when required. Capture exact commands, observed results, logs or screenshots, and reproducibility details.
+
+Do not change implementation to make tests pass and do not mark checkpoints. Return pass, fail, or blocked for each criterion, with evidence and the narrowest suspected fault boundary.

package/plugins/devflow-quality/extensions/devflow-quality.ts

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+export default function devflowQuality(pi: ExtensionAPI) {
+  const { z } = pi.zod;
+  pi.registerTool({
+    name: "devflow_mainflow",
+    label: "Devflow Mainflow Cases",
+    description: "Run an allowlisted main-flow discovery, compile, or validation operation.",
+    parameters: z.object({
+      action: z.enum(["discover", "compile", "validate"]),
+      args: z.array(z.string()).default([]),
+    }),
+    approval: "exec",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+      const roots = [
+        process.env.DEVFLOW_KIT_ROOT,
+        path.join(ctx.cwd, ".skills"),
+        path.resolve(moduleDirectory, "../skills"),
+        path.resolve(moduleDirectory, "../../.."),
+      ].filter(Boolean) as string[];
+      const skillRoot = roots.find(root =>
+        existsSync(path.join(root, "workflow-generate-mainflow-cases/scripts")),
+      );
+      if (!skillRoot) throw new Error("Devflow quality skills not found");
+      const scripts = {
+        discover: "discover_codebases.py",
+        compile: "compile_dsl.py",
+        validate: "validate_case_payloads.py",
+      } as const;
+      const script = path.join(
+        skillRoot,
+        "workflow-generate-mainflow-cases/scripts",
+        scripts[params.action],
+      );
+      const child = Bun.spawn(["python3", script, ...params.args], {
+        cwd: ctx.cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const [exitCode, stdout, stderr] = await Promise.all([
+        child.exited,
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+      ]);
+      const out = stdout.trim();
+      const err = stderr.trim();
+      return {
+        content: [{ type: "text" as const, text: out || err || `Process exited with ${exitCode}` }],
+        details: { action: params.action, exitCode, stderr: err || undefined },
+        isError: exitCode !== 0,
+      };
+    },
+  });
+}

package/plugins/devflow-quality/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@devflow/omp-quality",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": "*"
+  },
+  "omp": {
+    "extensions": [
+      "./extensions/devflow-quality.ts"
+    ]
+  }
+}

package/plugins/devflow-quality/skills/code-review/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: code-review
+description: "Use when code needs review for project conventions, spec compliance, behavioral risks, missing tests, change-list completion criteria verification, or post-refactor validation."
+---
+
+# 代码规范审查技能
+
+逐层对照 `.context/spec/` 规范文档，检查目标代码的合规性，输出可操作的问题清单。若项目存在 `.context/spec/index.md`，先按索引匹配 stack spec 和 codebase spec，再加载具体层级规范。
+
+## 核心原则
+
+1. **规范是唯一标准** — 只对照 `.context/spec/` 中的规范文档，不参考其他已有代码；代码推断规则必须低于显式规范和 codebase spec
+2. **文件级全量扫描** — 扫描目标文件的每一行，不只看"最近改动的部分"
+3. **逐条不跳过** — 规范文档中的每一条规则都要检查，包括"看起来无关"的细节。**禁止主观过滤**：不能因为"这个 VO 字段很简单"、"只有一个字段"、"直接传字符串"等主观判断而跳过检查项，规范就是规范，简单的代码同样要逐条对照
+4. **加法和减法都查** — 既查"缺了什么该有的"，也查"多了什么不该有的"（未使用方法/字段/import）
+
+## 工作流程
+
+### 第零步：提取变更清单完成标准
+
+**当 code-review 作为 feature-development 工作流的独立 `code-review` step 被调用时必须执行。** 独立调用 code-review（如"帮我 review 一下 XX 模块"）时，若提供 phase number 则尝试关联变更清单，否则跳过此步。
+
+1. **定位变更清单**：
+   - 若传入 phase number：从 phase 目录的 CONTEXT.md 推断功能名，查找 `.planning/features/{功能名}/变更清单.md`
+   - 若直接调用但用户提供了变更清单路径：使用用户指定路径
+   - 若找不到变更清单：跳过此步，在输出 REVIEW.md 中标注 "无变更清单，跳过完成标准验证"
+
+2. **提取每个任务的完成标准**：
+   - 遍历变更清单中所有 `### T-XXX` 或 `#### {编号}` 任务块
+   - 从每个任务的 `**完成标准**` / `**完成标准：**` 字段中提取所有条目
+   - 区分格式：
+     - `- [ ] 具体描述` → checkbox 格式（新格式，可精确验证）
+     - `- 具体描述` → 纯列表格式（旧格式，尽力验证但精度有限）
+
+3. **提取每个任务的文件路径**：
+   - 从 `**文件**：` / `**文件**` 字段获取目标文件路径
+   - 支持多文件（反引号路径或逗号/换行分隔列表）
+
+4. **构建验证清单**：
+   - 对每条 `- [ ]` 条目，组装：`{任务ID, 文件路径, 标准描述, 格式类型}`
+   - 对纯列表条目，标记 `format: legacy`，后续验证尽力而为
+
+### 第一步：确定审查范围
+
+用户可能以多种方式描述需求：
+
+- "帮我 review 一下 activity_rule_config" → 审查该模块全部层级
+- "检查 handler 层是否符合规范" → 审查指定层级
+- "重构完了，检查一下" → 审查当前 git diff 涉及的文件
+
+**确定范围后，识别涉及的层级**：
+
+|| 层级       | 文件位置                           | 对应规范                          |
+| ---------- | ---------------------------------- | --------------------------------- |
+| Handler    | `internal/web/*_handler.go`        | handler.md                        |
+| VO         | `internal/web/vo/*_vo.go`          | vo.md                             |
+
+### 第一步.5 — Seam 越界检查
+
+在加载规范之前，先检查本次要审查的代码是否在预设的 seam 范围内。
+
+**1. 读取 seam 标注**
+
+查找变更清单或 API 调用指南中的 seam 信息：
+
+- 如果有 `api-call-guide.md`：从每个步骤的 `Seam` 字段提取
+- 如果有 `变更清单.md`（旧版）：从每个任务的 seam 标注提取
+- 如果两者都没有：跳过此步骤
+
+**2. 对比 seam 标注与实际修改文件**
+
+```
+seam 标注: "只改 OrderWorkflow.process()" 
+实际修改列表: OrderWorkflow.go (✅ 范围内)
+              OrderService.go (❌ 越界！)
+
+→ 标记为 seam 越界项
+```
+
+**3. 判断越界严重级别**
+
+| 级别 | 定义 | 处理 |
+|------|------|------|
+| 🔴 阻塞 | 改了 seam 外且无文档说明 | 必须修复，审查不通过 |
+| 🟡 警告 | 改了 seam 外但有技术方案支持 | 记录，需确认 |
+| 🟢 信息 | 改了 seam 内但接口新增过多 | 记录观察 |
+
+**4. 接口膨胀检查**
+
+检查被修改的模块，其公开方法是否在本次变更中显著增加：
+
+- 新增 ≤ 2 个公开方法 → 🟢
+- 新增 3-5 个 → 🟡 标记为"接口膨胀观察项"
+- 新增 > 5 个 → 🔴 标记为"模块深度退化——考虑拆分"
+
+**输出**：seam 越界检查结果清单，列入审查问题清单。
+
+### 第二步：加载规范（渐进式）
+| DAO        | `internal/repository/dao/*_dao.go` | dao.md                            |
+| Domain     | `internal/domain/*.go`             | 各层规范中的 domain 相关条目      |
+
+如果涉及分页，额外加载 `pagination.md`。
+
+### 第二步：加载规范（渐进式）
+
+**必读**（每次审查都要读）：
+1. `.planning/rules/INDEX.md`（如存在）— 找到项目规则入口
+2. `.context/spec/index.md`（如存在）— 匹配目标文件所在 codebase 的 stack spec 和 codebase spec
+3. 命中的 `.context/spec/stacks/{stack_key}.md` — 技术栈通用规范
+4. 命中的 `.context/spec/backend|frontend/{codebase}.md` — 项目实例规范
+5. `.planning/code-index/`（如存在）— 用于调用方、被调用方、导入、读写资源、测试覆盖等关系事实定位
+6. 兼容旧规范：`.context/spec/backend/index.md` 和 `.context/spec/backend/go.md`（如存在）
+
+**按层级按需加载**（只读涉及的层级，详见 `references/spec-checklist.md`）：
+- Handler 层 → 读 `handler.md`
+- VO 层 → 读 `vo.md`
+- Service 层 → 读 `service.md` + `errors.md` + `logging.md`
+- Repository 层 → 读 `repository.md`
+- DAO 层 → 读 `dao.md`
+- 有分页 → 读 `pagination.md`
+
+**经验教训**（目录存在时读取）：
+- `.context/lessons/README.md`（如存在）— 项目积累的踩坑经验；不存在时跳过，不阻塞审查
+
+### 第三步：逐层执行审查
+
+**对每一个目标文件**，按以下流程执行：
+
+1. **⛔ Gate 前置：先查 code-index** — 在读取任何业务源码之前，必须先用 `code_index outline` 或 `code_index search` 获取目标文件的符号表。code-index 不可用时用 LSP `documentSymbol` 兜底。
+2. **用 code-index relations 查引用/调用/导入/测试覆盖** — 确认每个导出方法是否有调用方；code-index 缺失、过期或无命中时再用 Grep / LSP findReferences 兜底
+3. **回读源码 evidence** — 对用于审查结论的 relation，必须读取 `evidence_path:evidence_line` 附近源码。**此时可声明"基于 code-index 符号 [X] 读取源码"以通过 gate。**
+4. **逐条对照规范检查清单** — 详见 `references/` 目录下各层级的检查清单：
+   - Handler 层 → `references/handler-checklist.md`
+   - VO 层 → `references/vo-checklist.md`
+   - Service 层 → `references/service-checklist.md`
+   - Repository 层 → `references/repository-checklist.md`
+   - DAO 层 → `references/dao-checklist.md`
+   - 跨层检查 → `references/cross-layer-checklist.md`
+
+**⛔ Gate 合规检查：** 审查输出中，每个涉及源码的结论必须附带 code-index 符号引用（格式：`[符号名 @ path:line]`）。若审查全程未出现 code-index 查询操作，或输出中的源码引用无 code-index 依据，则在问题清单最上方追加：
+
+```
+⛔ SOURCE-READ GATE VIOLATION — 本次审查未走 .planning/code-index/ gate。
+审查结论降级为"未经索引验证"，需重新执行。
+```
+
+### 第四步：输出问题清单
+
+按以下格式输出，按优先级分组：
+
+```markdown
+## 问题清单
+
+### 高优先级
+| #   | 层级 | 文件:行号 | 问题描述 | 规范依据 |
+| --- | ---- | --------- | -------- | -------- |
+
+### 中优先级
+| # | 层级 | 文件:行号 | 问题描述 | 规范依据 |
+
+### 低优先级
+| # | 层级 | 文件:行号 | 问题描述 | 规范依据 |
+```
+
+**优先级判断标准**：
+- **高**：违反核心原则（跨层职责、错误处理模式、缺少必要字段 tag）
+- **中**：不符合规范细节（命名、排序、nil slice、未使用代码）
+- **低**：风格偏好（字段命名惯例、代码组织顺序）
+
+### 第四步附：兼容性影响评估
+
+输出问题清单后，**必须**对每个建议修改项评估兼容性影响。如果存在以下风险，在问题清单之后单独输出 **兼容性风险提示**：
+
+#### 前端兼容性
+
+涉及以下修改时必须提示用户：
+
+- **VO 返回字段变更**：修改已有返回 VO 的 `json` tag 名称、删除字段、变更字段类型 → 会导致前端解析失败
+- **响应结构层级变化**：如分页响应从 `{total, list}` 改为 `{total_count, list, has_next, page}` → 前端可能依赖旧的字段名
+- **错误码/消息变更**：修改已有的错误码数值或消息文案 → 前端可能基于错误码做了逻辑判断
+- **接口路径或参数名变更**：改变 `form`/`json` tag 的 key → 前端请求参数将不匹配
+
+**提示格式**：
+```markdown
+## 兼容性风险提示
+
+### 前端兼容性
+| #   | 修改项                           | 风险描述            | 建议方案                              |
+| --- | -------------------------------- | ------------------- | ------------------------------------- |
+| 1   | 分页响应字段 total → total_count | 前端依赖 total 字段 | 保留 total 字段兼容，新增 total_count |
+```
+
+#### 数据库兼容性
+
+涉及以下修改时必须提示用户：
+
+- **Model 字段变更**：重命名、删除、修改类型 → 需要 DDL 迁移，可能影响线上数据
+- **表名变更**：修改 `TableName()` 返回值 → 需要 DDL 迁移
+- **索引或约束变更**：添加/修改唯一索引、外键 → 可能与现有数据冲突
+- **新增非空字段无默认值**：INSERT 时报错
+
+**提示格式**：
+```markdown
+### 数据库兼容性
+| #   | 修改项                          | 风险描述                      | 建议方案                       |
+| --- | ------------------------------- | ----------------------------- | ------------------------------ |
+| 1   | 删除 model.Xxx 的 OldField 字段 | 线上表仍有该列，需要 DDL 迁移 | 先加新列 → 数据迁移 → 再删旧列 |
+```
+
+**如果不涉及兼容性风险，不需要输出此节。**
+
+### 第四步.五：验证变更清单完成标准
+
+**前置条件：** 已完成第零步（提取了变更清单完成标准）。若第零步未找到变更清单或全部为 legacy 格式，则 `completion_criteria_status = "skipped"`。
+
+对第零步提取的每条完成标准，读取目标文件的完整内容，逐条验证：
+
+#### 验证方法
+
+1. **读取目标文件**：读取任务对应文件（从变更清单 `**文件**` 字段获取）的当前内容
+2. **搜索证据**：扫描代码中是否有与标准描述匹配的实现
+   - 字段/方法/类定义：搜索对应的名称（如 `_evaluate_network_assertions`、`uiAssertionOptions`）
+   - 逻辑行为：搜索关键代码模式（`try/finally`、`if page is None`、`page.on("response")`）
+   - 配置/常量值：搜索枚举值、数组长度、配置项
+   - 导入/调用关系：优先查 code-index 的 `imports`、`calls`、`routes_to`、`tested_by`，再回读源码；缺失时搜索 `import`、调用语句、注册逻辑
+3. **判定状态**：
+   - `✅ PASSED` — 代码中有明确证据满足标准（标注文件:行号作为证据）
+   - `❌ FAILED` — 代码与标准描述矛盾，或应有但缺失
+   - `⚠️ UNVERIFIABLE` — 标准描述过于模糊，无法通过静态分析判定（如"用户体验良好"、"功能正常工作"）
+   - `— SKIPPED` — 旧格式条目（无 `[ ]`），已尽力验证但精度有限
+
+#### 输出格式
+
+```markdown
+## 完成标准验证
+
+> **来源**：`.planning/features/{功能名}/变更清单.md`
+> **格式**：checkbox（N 条）/ legacy（M 条）
+> **总结**：{passed}/{total} 通过，{failed} 未通过，{unverifiable} 待人工，{skipped} 跳过
+
+| Task | 文件 | 完成标准 | 证据 | 状态 |
+|------|------|---------|------|------|
+| T-001 | executor.py | `execute_step` 在 `_run_action` 前注册 `page.on("response")` | executor.py:47 `page.on("response", ...)` | ✅ PASSED |
+| T-001 | executor.py | `try/finally` 中 `removeListener` 确保清理 | executor.py:78-80 `finally: page.removeListener(...)` | ✅ PASSED |
+| T-002 | executor.py | `page=None` 时全部返回 `skipped` | executor.py:210 `if page is None: return [...]` | ✅ PASSED |
+| T-003 | StepConfigModal.tsx | 断言类型下拉包含 10 个选项 | `uiAssertionOptions` 仅含 6 项 | ❌ FAILED |
+```
+
+#### 状态汇总规则
+
+- **全部 PASSED（或仅含 SKIPPED/UNVERIFIABLE）**：`completion_criteria_status = "passed"`
+- **存在 FAILED**：`completion_criteria_status = "failed"`，将导致 `code_review_gate` 阻塞
+- **全部为 SKIPPED**（旧格式或无变更清单）：`completion_criteria_status = "skipped"`，不阻塞
+- **存在 UNVERIFIABLE**：不影响 passed/failed 判定，但需在汇总中标注待人工确认项数量
+
+#### REVIEW.md 输出规范
+
+REVIEW.md 文件顶部必须包含 YAML frontmatter，供 execute-phase 解析：
+
+```yaml
+---
+status: clean|issues_found
+completion_criteria_status: passed|failed|skipped
+phase: {phase_number}
+reviewed_at: {ISO timestamp}
+---
+```
+
+### 第五步：如果处于重构流程中
+
+当此技能作为重构验证环节被调用时：
+
+1. 输出问题清单后，**不等待用户确认**，直接逐个修复
+2. 每修复一个问题后运行 `go build ./...` 确认编译通过
+3. 全部修复后运行 `go test ./目标包/... -v -count=1` 确认测试通过
+4. 重新执行一轮审查，确认问题清零
+5. 如果发现新问题（修复过程中引入的），继续修复循环
+6. 直到问题清单为空，输出 "审查通过，无合规问题"
+
+**重要：** 完成标准验证（第四步.五）中的 `❌ FAILED` 项**不属于自动修复范围**。这些是功能实现缺失，需要开发者判断和补充实现，不能通过风格修正自动处理。仅规范合规问题（第一至四步）可自动修复。
+
+## 关键规则
+
+1. **不修改 VO 字段定义** — 重构场景下不改变已有的 VO 字段名和类型（tag 补全除外）
+2. **不猜测业务意图** — 不确定某段代码是否违反规范时，标注为"待确认"并说明理由
+3. **引用具体规范** — 每个问题必须指向具体的规范文件和条目，不能只说"不规范"
+4. **关注遗漏模式** — 重点检查之前经验教训中记录的常见遗漏（lessons/README.md）
+5. **兼容性优先** — 任何涉及前端响应结构（VO json tag、响应格式、错误码）或数据库 schema（model 字段、表名）的修改建议，必须附带兼容性风险提示和渐进式迁移方案