verify-gate

验证门禁

实现与质量评审之间的机器验证门禁。运行项目的编译、测试和 lint 命令。如果任何一项失败，则进入修复循环。如果全部通过，则解除对简化与加固的阻塞。

这是内部循环中的验证步骤。没有这一步，Agent 交付代码时就完全没有机器信号能表明代码是否实际可用。

使用时机

• 完成任何实现工作后、报告“完成”之前
• 运行简化与加固之前
• 修复独立的简化、加固、规格或代码评审所发现的问题之后
• 任何需要机器验证通过信号的时候

流程位置

[implementation] → verify-gate → simplify-and-harden → self-improvement
                   ↻ fix loop — on failure, hands diagnostics to self-healing
                   ↳ self-healing (diagnose → patch → verify → file HEAL); verify-gate re-checks

步骤 1：发现项目命令

阅读项目配置，查找验证命令。按以下顺序检查这些来源：

1. 项目指令文件（CLAUDE.md、AGENTS.md、.github/copilot-instructions.md）——查找 ## Verification 或 ## Test Commands 小节
2. package.json——检查 scripts.test、scripts.lint、scripts.typecheck、scripts.build。同时检查同目录是否有 bun.lock / bun.lockb → 如果存在，优先使用 bun run <script>，而不是 npm run <script>。检查是否有 pnpm-lock.yaml → 如果有，优先使用 pnpm run。检查是否有 yarn.lock → 如果有，优先使用 yarn。
3. Makefile / Justfile——检查 test、lint、check、build 目标
4. Cargo.toml——检查 cargo build、cargo test、cargo clippy
5. pyproject.toml / setup.cfg——检查 pytest、mypy、ruff
6. go.mod——检查 go build ./...、go test ./...、go vet ./...
7. deno.json / deno.jsonc——对已定义的任务使用 deno task <name>

如果找不到任何命令，只询问用户一次，并建议他们在项目指令文件（CLAUDE.md、AGENTS.md 或同类文件）中添加 ## Verification 小节，供之后的会话使用：

## Verification

- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Type check: `npx tsc --noEmit`

定义验收证据

运行命令之前，将每项用户验收标准转化为可观察的证据。对于与宿主集成或面向用户的工作，记录完整的身份链：

• 宿主/界面——指定的应用、浏览器、桌面宿主、嵌入式界面或目标对话
• 工作区——实际执行操作的仓库、分支、环境或文档
• 已加载产物——宿主实际加载的程序包、修订版本或构建产物，而不只是用于构建它的源代码
• 结果——通过真实交互和普通用户操作路径观察到的指定行为

不要用中间状态的证明替代所要求的结果：iframe 的 src 不是已渲染的应用，构建成功不能证明宿主已加载该应用，仅在展开状态下显示的视图不能证明普通视图也可见，瞬时的合成点击不能证明按压达到人类操作所需的时长，已排队或已送达的确认也不是目标对话中可见的一轮消息。

如果环境无法观察所需结果，记录确切的验收缺口。对于该项标准，门禁不得报告 PASSED。

步骤 2：运行验证

按以下顺序运行发现的命令。遇到第一个失败类别时停止。

阶段 1：编译 / 类型检查

运行构建或类型检查命令。这些检查能在浪费时间运行测试之前发现结构性错误。

Exit 0 → proceed to Phase 2
Exit non-zero → enter fix loop with compiler output

阶段 2：测试

运行测试命令。如果测试运行器支持，限定为已更改的文件。

Exit 0 → proceed to Phase 3
Exit non-zero → enter fix loop with test output

阶段 3：Lint（可选，可使用 --skip-lint 跳过）

运行 lint 命令。Lint 失败的严重程度较低，但仍值得发现。

Exit 0 → proceed to Phase 4
Exit non-zero → enter fix loop with lint output

阶段 4：项目专用检查

在标准阶段之后运行已配置的自定义验证工具。每条自定义命令都必须证明其声明的不变量，而不能仅仅因为输入与该不变量无关就成功退出。

阶段 5：结果验收

通过指定宿主和普通用户操作路径，执行步骤 1 中定义的每项验收检查。收集足够的证据，以确认宿主、工作区、已加载产物、交互和观察到的结果。即使编译、测试和 lint 均通过，代理或中间状态也无法通过此阶段。

第 3 步：修复循环

当某个阶段失败时：

1. 阅读输出。 解析错误输出，提取可采取行动的诊断信息——文件路径、行号、错误消息。
2. 限定修复范围。 只修复验证发现的问题。不要重构、改进或改动无关代码。
3. 应用修复。 做出解决失败所需的最小改动。
4. 重新运行失败的阶段。 不要运行所有阶段，只运行失败的阶段。
5. 如果通过， 继续下一个阶段。
6. 如果再次失败， 增加尝试计数。

修复循环限制

• 默认最大尝试次数： 每个阶段 3 次（可通过 --fix-limit N 配置）
• 每次尝试都会增加计数器， 即使错误发生变化也一样。修复错误 A 后发现错误 B，算作第 2 次尝试，而不是第 1 次。计数器统计修复尝试次数，而非不同错误的数量。
• 达到限制时： 停止。报告失败内容、已尝试的操作和剩余错误输出。不要继续猜测——告知用户需要人工介入。
• 总预算： 修复循环不应超过原始实现工作量的 20%。如果修复工作不断扩大，就停止并报告。

第 4 步：门禁信号

所有阶段通过后：

## Verify Gate: PASSED

- Build: passed
- Tests: passed (N tests, M suites)
- Lint: passed (or skipped)
- Custom checks: passed (or not applicable)
- Outcome acceptance: passed (or not applicable)

Ready for simplify-and-harden.

修复循环耗尽后：

## Verify Gate: BLOCKED

- Build: passed
- Tests: FAILED (attempt 3/3)
  - [file:line] error description
  - [file:line] error description
- Lint: not reached
- Outcome acceptance: not reached

Fix loop exhausted. Manual intervention needed before quality review.

与其他技能集成

skill-pipeline

除了 Trivial 级别外，verify-gate 应在每个流水线深度运行：

任务规模	流水线
Trivial	无
Small	verify-gate → simplify-and-harden
Medium	intent-framed-agent + verify-gate → simplify-and-harden
Large	完整流水线，在质量检查前运行 verify-gate

独立审计 Agent

在根据 simplify、harden、spec 或 code-review Agent 的建议进行修复后，重新运行 verify-gate。审计者的报告是审查证据，并不能证明修改后的 代码仍能编译或通过测试。

self-healing

verify 运行期间发生任何失败时，将诊断信息交给 self-healing（不要只重试相同命令）。Self-healing 会运行诊断 → 修补 → 验证循环，将 HEAL- 条目写入 .learnings/HEALS.md，然后返回控制权。Verify-gate 随后会重新运行检查。每个阶段最多进行 3 次修复尝试，之后放弃。

self-improvement

如果修复循环发现某种反复出现的模式（HEALS.md 中的 Recurrence-Count >= 3），修复流程的 Handoff 区块会将其标记出来，通过 self-improvement 将其提升到 CLAUDE.md / AGENTS.md / 新技能中。对于非修复类经验（更正、知识缺口、功能请求），请按照 self-improvement 技能的要求，分别记录到 .learnings/LEARNINGS.md、ERRORS.md 或 FEATURE_REQUESTS.md。

此技能不做什么

• 不审查代码质量（由 simplify-and-harden 负责）
• 不检查安全性（由 harden-auditor 负责）
• 不验证规范符合性（由 spec-auditor 负责）
• 不修改测试文件或添加新测试
• 不运行未修改代码的测试（除非测试运行器不支持限定范围）

配置

如果项目有 .verify-gate.yml，或项目指令文件（CLAUDE.md、AGENTS.md 或同等文件）中有 verify-gate 部分：

verify-gate:
  build: npm run build
  test: npm test
  lint: npm run lint
  type_check: npx tsc --noEmit
  fix_limit: 3
  skip_lint: false
  test_scope: changed  # changed | all

如果不存在配置，则自动发现命令（第 1 步），并建议将其保存为持久配置。

自定义验证工具（mcp-scripts）

包含自定义不变量的项目可以使用 gh-aw 的 mcp-scripts 定义内联验证工具。这些工具会作为标准编译／测试／lint 检查之后的附加阶段运行。

示例——需要进行 API 模式验证和旧式导入检查的项目：

# In .github/workflows/verify-gate-ci.md or plugin config
mcp-scripts:
  verify-api-schema:
    lang: shell
    description: "Validate API schema matches implementation"
    run: |
      python scripts/validate_schema.py --strict

  check-no-legacy-imports:
    lang: shell
    description: "Ensure no imports from deprecated legacy/ directory"
    run: |
      ! grep -r "from legacy" src/ --include="*.py"

  verify-rate-limits:
    lang: javascript
    description: "All API routes must have rate limiting middleware"
    run: |
      const routes = require('./src/routes');
      const missing = routes.filter(r => !r.middleware.includes('rateLimit'));
      if (missing.length) { console.error('Missing rate limit:', missing); process.exit(1); }

定义了 mcp-scripts 时，verify-gate 会在 lint 之后将其作为第 4 阶段运行。每个脚本的退出代码决定通过或失败。失败的脚本会进入与标准阶段相同的修复循环。宿主和用户可观察的验收仍是第 5 阶段，不能被只能证明中间状态的自定义命令取代。

这样，项目特定的不变量就从“脑海中的知识”变成了“运行框架中的知识”——这正是 Agent 能够获取知识的地方。