verify-gate

Verify Gate

実装と品質レビューの間で機械的な検証を行うゲートです。プロジェクトのコンパイル、テスト、Lint コマンドを実行します。いずれかが失敗した場合は、修正ループに入ります。すべて成功した場合は、簡素化と堅牢化に進めるようになります。

これは内部ループの検証ステップです。このステップがなければ、エージェントはコードが実際に動作するかどうかを示す機械的なシグナルをまったく得られないまま、コードを引き渡すことになります。

使用するタイミング

• 実装作業が完了した後、「完了」と伝える前
• 簡素化と堅牢化を実行する前
• 独立した簡素化、堅牢化、仕様、またはコードレビューで指摘された問題を修正した後
• 機械的に検証された成功のシグナルが必要なとき

パイプライン内の位置

[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 がある場合は、npm run <script> より bun 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：テスト

テストコマンドを実行します。テストランナーが対応している場合は、変更したファイルに範囲を絞ります。

選択したプロジェクトのテストで agent-qa を使用する場合は、agent-qa の検証証拠を読んでください。検証とドライランの選択だけでは、テストフェーズを満たしません。完了した実行の証拠をステップ 1 の受け入れ確認の識別情報に紐付け、結果に不足があればフェーズ 5 まで保持します。

選択したテストまたは結果確認で Playwright を使用する場合は、Playwright の検証証拠を読んでください。Playwright Test の結果とブラウザーのみでの観察結果を分け、結果に不足があればフェーズ 5 まで保持します。

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：成果の受け入れ

Step 1 で定義したすべての受け入れチェックを、指定されたホストと通常のユーザーパスを通じて実行します。ホスト、ワークスペース、読み込まれたアーティファクト、操作、観測された結果を特定できるだけの証拠を収集します。コンパイル、テスト、lint がすべて成功していても、プロキシや中間状態ではこのフェーズに合格しません。

Step 3：修正ループ

フェーズが失敗した場合：

1. 出力を読みます。 エラー出力から、ファイルパス、行番号、エラーメッセージなど、対処可能な診断情報を解析します。
2. 修正範囲を限定します。 検証で検出されたものだけを修正します。リファクタリング、改善、無関係なコードへの変更は行いません。
3. 修正を適用します。 失敗を解決するために最小限の変更を行います。
4. 失敗したフェーズを再実行します。 すべてのフェーズではなく、失敗したフェーズだけを実行します。
5. 合格した場合は、次のフェーズに進みます。
6. 再び失敗した場合は、試行回数を増やします。

修正ループの上限

• デフォルトの最大試行回数： フェーズごとに 3 回（--fix-limit N で設定可能）
• 試行のたびにカウンターを増やします。 エラーが変わった場合も同様です。エラー A を修正してエラー B が見つかった場合は、試行 1 ではなく試行 2 として数えます。カウンターは固有のエラー数ではなく、修正の試行回数を記録します。
• 上限に達した場合： 停止します。何が失敗したか、何を試したか、残っているエラー出力を報告します。それ以上推測せず、ユーザーに手動での対応が必要であることを伝えます。
• 合計予算： 修正ループは、元の実装作業量の 20％を超えてはなりません。修正が次々と膨らむ場合は停止して報告します。

Step 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

verify-gate は、Trivial 以外のすべてのパイプライン段階で実行する必要があります。

タスクの規模	パイプライン
Trivial	なし
Small	verify-gate → simplify-and-harden
Medium	intent-framed-agent + verify-gate → simplify-and-harden
Large	品質チェックの前に verify-gate を実行する完全なパイプライン

独立監査エージェント

simplify、harden、spec、または code-review エージェントの指摘による修正後は、verify-gate を再実行します。監査担当者の報告はレビューの証拠であり、変更されたコードが引き続きコンパイルできる、またはテストに合格することの証明ではありません。

self-healing

verify の実行中に失敗した場合は、同じコマンドを再試行するのではなく、診断情報を self-healing に渡します。self-healing は診断 → パッチ適用 → 検証のループを実行し、.learnings/HEALS.md に HEAL- のエントリーを記録して制御を戻します。その後、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 が担当します）
• セキュリティのチェックは行いません（これは simplify-and-harden と独立レビューが担当します）
• 仕様への準拠は検証しません（これは計画／仕様に照らした独立レビューが担当します）
• テストファイルの変更や、新しいテストの追加は行いません
• 変更していないコードのテストは実行しません（テストランナーが対象を絞り込めない場合を除きます）

設定

プロジェクトに .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

設定がない場合は、コマンドを自動検出し（Step 1）、その設定を永続化するよう提案します。

カスタム検証ツール（mcp-scripts）

独自の不変条件を持つプロジェクトでは、gh-aw の mcp-scripts を使用してインライン検証ツールを定義できます。これらは、標準のコンパイル／テスト／リントチェックの後に追加フェーズとして実行されます。

例 — 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 はリントの後に Phase 4 としてこれらを実行します。各スクリプトの終了コードによって合否が決まります。失敗したスクリプトは、標準フェーズと同じ修正ループに入ります。ホストとユーザーが確認できる受け入れテストは Phase 5 のままであり、中間状態だけを証明するカスタムコマンドで置き換えることはできません。

これにより、プロジェクト固有の不変条件を「頭の中にある知識」から「ハーネスにある知識」へと移せます。つまり、エージェントがアクセスできる場所に置けます。