/verification-gate

name: verification-gate
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.3.0"
license: MIT
description: 代码改完后的分层验证执行与证据记录。完成 feature / 重大变更 / 创建 PR / 重构 / 声称「修完」前使用——按项目运行 build、unit、e2e、真机等代表性阶段并记录真实结果（编译过 ≠ 功能可用）。覆盖 Tauri 桌面 / Web / 服务 / Skill 四类分支，可把已执行事实转换为 production-engineering-audit staged receipt；完成等级与发布结论由 production-engineering-audit 裁决。不要用于：业务领域验证、Skill 质量审查（用 skill-lint）、纯文档变更、一次性脚本。

Verification Gate（代码改完后的验证门禁）

本 skill 是「代码改完 → 声称完成 / 提交 PR」之间的**验证执行与证据记录层**。核心解决一个问题：**编译过 ≠ 功能可用**。

它负责真实运行适用阶段、观察功能终态并保留阶段事实；`production-engineering-audit`（PEA）是完成 层级的唯一裁决者。需要机器可消费的分层证据时，读取 [`references/staged-receipt.md`](references/staged-receipt.md)，用确定性转换器生成 staged receipt， 再交给 PEA。不要在本 Skill 内另造 READY / RELEASED 判决。

> 直接教训：改完 reader worker 加载，`typecheck` / build / lint / 单测全过，就声称「修完」，实机却「文字层未知」（`textLayerStatus` 卡 unknown）崩——编译层根本抓不到运行时功能问题。这类坑的唯一解是 **e2e（功能验证）+ 真机**。

工作原则

• **先编译层（1-4），再功能层（5-6）**：编译层是前置门禁，但**不充分**；功能层（e2e + 真机）才是完成线。
• **e2e/真机失败必须如实记录**：5/6 不过就不能作为对应完成声明的通过证据，无论 1-4 多干净；

是否达到项目要求的完成层级交给 PEA 按项目契约裁决。

• **断言功能结果，非「存在元素」**：教用户写 e2e 时断言「canvas 像素非空 / textLayerStatus ≠ unknown / 点击后面板真的弹出」，而非「存在 canvas / 存在按钮」（防伪渲染 / 假成功）。
• **Bug 修复必须新增复现测试**（回归规范）：修完一个 bug，加一条能复现该 bug 的 e2e/单测，防止回归。
• **套件悬挂 = 未通过**：`npm test` 永不退出（summary 不打印 / 进程不退）按 P0 基础设施缺陷处理，诊断 playbook 见 `references/lessons-from-practice.md` 教训 12；用子集绕开只能是登记过任务的临时态——悬挂会掩盖真实失败（教训 11：修复当日暴露 3 条被藏数周的失败）。
• **不采信生产者（worker/PM 自己）自报 PASS**：跑实际命令，看实际输出。
• **按项目类型选验证命令**：Tauri 桌面 / Web / 服务 / Skill，命令不同（见 §项目类型分支）。

8 阶段验证

| # | 阶段 | 门禁 | 完成线 | CI | |---|---|---|---|---| | 1 | 构建（build / cargo check） | 失败则停，不继续 | 前置 | ✅ 进 CI（PR 阻断项） | | 2 | 类型检查（typecheck） | 关键错误清零 | 前置 | ✅ 进 CI（PR 阻断项） | | 3 | Lint（`--max-warnings=0` + 依赖环） | 零警告 + 无依赖环 | 前置 | ✅ 进 CI（PR 阻断项） | | 4 | 单元测试（vitest 分层） | 通过 + 覆盖率达标 | 前置 | ✅ 进 CI（PR 阻断项） | | **5** | **e2e 功能验证（Playwright）** | **功能结果断言**（非存在元素） | **核心完成线** | ✅ 进 CI（PR 阻断项，关键） | | **6** | **真机验证（etv / build / staging）** | **真实运行时行为** | **核心完成线** | ⚠️ 通常本地 / staging 跑（CI 难模拟真机，按需） | | 7 | 安全扫描（密钥 / debug 日志） | 无泄露 / 无遗留 console.log | 前置 | ✅ 进 CI（PR 阻断项） | | 8 | Diff 审查（范围 / 越界） | 变更合规，无 forbidden 文件 | 前置 | ✅ 进 CI（PR 阻断项） |

> **CI 列说明**：✅ = 建议在 CI 自动跑、失败即阻断 PR 合并；⚠️ = 真机环境 CI 一般难以模拟，放本地或独立 staging 流水线跑。本地手动跑时 8 阶段全跑，CI 跑 1-5 + 7-8（缺真机）。

阶段 1-4：编译层（前置门禁，不充分）

# 1 构建
npm run build 2>&1 | tail -20          # 前端
cd src-tauri && cargo check 2>&1 | tail # Tauri Rust

# 2 类型检查
npm run typecheck 2>&1 | tail

# 3 Lint（严格：零警告 + 依赖环）
npm run lint -- --max-warnings=0 2>&1 | tail
npx depcruise --config .dependency-cruiser.cjs src 2>&1 | tail  # 依赖环（如有）

# 4 单元测试（分层）
npm test 2>&1 | tail -50                # vitest（unit + integration + dom 分层）

**门禁**：任一失败 → 停，修复后再继续。但这 4 层全过 **≠ 功能可用**。

阶段 5：e2e 功能验证（核心完成线）

**这是「编译过 ≠ 功能可用」的唯一解**。用 Playwright（或等价）驱动应用，断言**功能结果**。

npm run test:e2e -- tests/e2e/reader-renders.test.ts   # FaroPDF 实际路径示例
# 或项目既有：npm run verify:reader-e2e（chromium 真 Worker 功能门禁）

**断言深度**——不只「存在元素」，断言功能结果（见 `references/assertion-depth.md`）。

**门禁事实**：e2e 不过就记录 `failed`，不把该阶段当作 behavior-complete 证据；由 PEA 判断当前 声明是否被阻断。

阶段 6：真机验证（核心完成线）

dev server e2e 不够——真实运行时（Tauri WKWebView / Web build 产物 / 服务 staging）行为可能不同。

| 项目类型 | 真机验证 | |---|---| | Tauri 桌面 | `npm run tauri build` 产物实机（或 etv：`WEBKIT_INSPECTOR_SERVER` + tauri dev 真机 DOM + 截图） | | Web | `npm run build` + `vite preview`（build 产物，非 dev server） | | 服务 | staging 环境真实请求 |

**阶段通过条件**：真机行为与 dev e2e 一致；prod-only 问题（worker/协议/路径）必须真机抓到。

阶段 7-8：安全 + Diff（前置）

# 7 安全
grep -rnE "sk-|api_key|password|token" --include="*.ts" --include="*.rs" src/ src-tauri/ 2>/dev/null | grep -viE "test|fixture|env|placeholder" | head
grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head

# 8 Diff 审查
git diff --stat
git diff HEAD~1 --name-only   # 逐文件审：非预期变更 / 缺失错误处理 / forbidden 文件

项目类型分支（按项目选验证命令）

Tauri 桌面

npm run build && cd src-tauri && cargo check   # 1 构建
npm run typecheck                                # 2 类型
npm run lint                                     # 3 lint
npm test                                         # 4 单测
npm run test:e2e                                  # 5 e2e（打开 PDF 渲染 + textLayerStatus 断言；jsdom 层）
npm run verify:reader-e2e                          # 5+ chromium 真 Worker 门禁（dev server 自起自灭）
npm run verify:prod-render                         # 5+ 产物层门禁（vite preview build 产物 + 真实 UI + Retina DPR=2）
# 6 真机：npm run tauri build 产物实机 / etv（npm run etv:dev + etv:run，WKWebView 真机 DOM + 截图）
#    ⚠ 桌面 WebView 四层验证盲区（引擎代差/DPR/产物嵌入/dev≠打包）见教训 13：
#    chromium 全绿 ≠ WKWebView 过；真机 console（构建戳确认版本）是唯一决定性证据

真机验证做法见 `references/e2e-practice.md`（Tauri etv 段）。

Web

npm run build && npm run typecheck && npm run lint && npm test   # 1-4
npm run test:e2e                                                  # 5 Playwright（CI 也跑）
# 6 真机：npm run build + vite preview（build 产物）

服务

npm run build && npm run typecheck && npm run lint   # 1-3
npm test                                              # 4 unit + integration
# 5 integration test（HTTP 请求断言响应）
# 6 真机：staging 环境真实请求

Skill

引用 `skill-lint`（已有 Skill 创建质量审查）。本 skill 不重复 skill-lint 的职责。

触发时机

• 完成 feature 或重大代码变更后
• **创建 PR 之前**（PR 合并的硬门禁）
• 重构之后
• **声称「修完」「behavior-complete」「done」之前**（先产出阶段事实，再由 PEA 对完成层级裁决）
• Bug 修复后（+ 新增复现测试）
• **release / 交付收尾、把 NOT_VERIFIED 清单「移交用户」之前**——先分层收口（见 §NOT_VERIFIED 分层收口）

**持续模式**：长会话中每 15 分钟或重大变更后执行（心智检查点：完成函数后 / 完成组件后 / 切换任务前）。

本地验证 vs CI 门禁（必须搞清楚）

**不需要 GitHub Actions 也能做完整验证。** 本 skill 的 8 阶段本质是「一组要在代码声称完成前跑的命令 + 判定标准」，它在哪跑、谁来跑是独立的：

• **本地验证**：你（或 AI 代理）手动跑 `build → typecheck → lint → test → test:e2e`，看实际输出并记录阶段事实。即时、灵活，但**靠自觉**——容易「编译过了就声称修完」（正是本 skill 要防的坑）。
• **CI 门禁**（GitHub Actions / GitLab CI / Gitea / Jenkins 等）：把**同一组命令**写进流水线，在 push / 开 PR 时自动跑，失败就**阻断 merge**。它不改变「验证什么」，只是把门禁变成**客观强制**——没过门禁的代码合不进去。

**关键认知**：

1. CI 不是「另一种验证」，是**同一套验证的自动化载体**。本地能过、CI 才能过；本地乱