How to Run verify-routing-coherence Checks in CI Pipelines for Reverse-Skill

Run the verify-routing-coherence.ps1 script in PowerShell after checkout, passing a -ScratchDir for artifacts, and fail the pipeline on non-zero exit codes.

The verify-routing-coherence check is the canonical validation suite for the reverse-skill repository, ensuring that routing.json, benchmark files, and generated documentation remain internally consistent. This PowerShell-based audit runs seamlessly in continuous integration (CI) environments to catch routing contract violations before they reach production.

What the verify-routing-coherence Script Validates

According to the source code in skills/scripts/verify-routing-coherence.ps1, the script performs a comprehensive audit of the following components:

• skills/config/routing.json – The single source of truth for all route definitions.
• skills/tests/routing-benchmark.json – Sanity-checks ensuring benchmark cases reference existing routes.
• Generated artifacts – Validates INDEX.md, MASTER-ROUTING.md, and various ops/* documents.
• Master route implementation – Verifies integrity of skills/scripts/master-route.ps1.
• Case-initialisation logic – Tests skills/scripts/case-init.ps1 for proper artifact placement.
• Cross-platform behavior – Confirms correct artifact placement when a custom ProjectRoot is supplied.

The script loads helper libraries from skills/scripts/lib/RouteScope.ps1 (providing Get-ReverseRouteScopeFields) and skills/scripts/lib/HostRuntime.ps1 (providing Resolve-ReverseHostExe) to locate the reverse-skill host executable and parse generated route-scope files.

CI Pipeline Configuration

GitHub Actions Example (Multi-Platform)

The following workflow runs the verification across Windows, Linux, and macOS runners. It handles PowerShell Core installation on non-Windows platforms and captures debug artifacts on failure.

name: Verify Routing Coherence

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  verify-routing:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ windows-latest, ubuntu-latest, macos-latest ]

    steps:
      # 1️⃣ Checkout the repo

      - uses: actions/checkout@v4

      # 2️⃣ Install PowerShell Core on non‑Windows platforms

      - name: Install PowerShell Core
        if: matrix.os != 'windows-latest'
        uses: microsoft/setup-powershell@v2
        with:
          version: '7.4.x'

      # 3️⃣ Run the verification script

      - name: Run verify‑routing‑coherence
        shell: pwsh
        run: |
          # Create a temporary directory for script output – helps keep the log readable

          $scratch = Join-Path $env:GITHUB_WORKSPACE 'ci-scratch'
          New-Item -ItemType Directory -Force -Path $scratch | Out-Null

          # Execute the script; it will exit 0 on success, 1 on failure

          & "${{ github.workspace }}/skills/scripts/verify-routing-coherence.ps1" -ScratchDir $scratch

      # 4️⃣ (Optional) Upload artefacts for debugging

      - name: Upload verification artefacts
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: routing‑coherence‑output
          path: ci-scratch

Step-by-Step Breakdown

Each step in the pipeline serves a specific validation purpose:

• Checkout – Provides the full repository tree so the script can resolve all relative paths (e.g., skills/config/routing.json).
• Install PowerShell Core – Guarantees a consistent PowerShell version (7.x) on Linux/macOS, satisfying the script’s #Requires -Version 5.1 constraint.
• Run verification script – Calls verify-routing-coherence.ps1 with the -ScratchDir parameter to isolate temporary files.
• Upload artefacts – When checks fail, the script writes detailed logs under -ScratchDir; uploading them preserves the failures.txt report for debugging.

Local Debugging and Manual Execution

Before pushing to CI, run the checks locally to validate changes to routing.json or MASTER-ROUTING.md.

Windows PowerShell 5.1

$Scratch = Join-Path $PWD 'tmp-scratch'
powershell -NoProfile -ExecutionPolicy Bypass -File .\skills\scripts\verify-routing-coherence.ps1 -ScratchDir $Scratch

PowerShell Core on Linux/macOS

Scratch=$(pwd)/tmp-scratch
pwsh -NoProfile -ExecutionPolicy Bypass -File ./skills/scripts/verify-routing-coherence.ps1 -ScratchDir "$Scratch"

Exit codes:

• 0 – Script prints “ALL ROUTING COHERENCE CHECKS PASSED” and exits successfully.
• 1 – Script prints a failure summary, writes failures.txt into the scratch directory, and exits with error.

Key Source Files and Dependencies

Understanding the dependency graph helps troubleshoot CI failures:

• skills/scripts/verify-routing-coherence.ps1 – The main CI-compatible verification script that orchestrates all checks.
• skills/scripts/master-route.ps1 – Implements the routing engine exercised by the verification suite.
• skills/scripts/case-init.ps1 – Handles case-initialisation artifacts; tested for correct path placement.
• skills/config/routing.json – The canonical routing definition cross-validated against MASTER-ROUTING.md.
• skills/tests/routing-benchmark.json – Benchmark data that must stay synchronized with the main routing configuration.
• skills/scripts/lib/HostRuntime.ps1 – Helper resolving the reverse-skill host executable via Resolve-ReverseHostExe.
• skills/scripts/lib/RouteScope.ps1 – Provides Get-ReverseRouteScopeFields for parsing generated route-scope.md files.
• skills/MASTER-ROUTING.md – Human-readable matrix cross-validated against routing.json.
• skills/INDEX.md – Generated skill summary validated for presence and structure.

Summary

• The verify-routing-coherence.ps1 script is the authoritative test for routing consistency in reverse-skill.
• It validates skills/config/routing.json, benchmark files, and generated documentation against the implementation in master-route.ps1.
• CI pipelines should invoke the script using pwsh (PowerShell Core) on Linux/macOS or powershell on Windows.
• Always provide a -ScratchDir parameter to isolate temporary files and preserve logs on failure.
• The script exits with code 1 on any validation error, naturally failing the CI step.

Frequently Asked Questions

What specific files does verify-routing-coherence check?

The script audits skills/config/routing.json (route definitions), skills/tests/routing-benchmark.json (benchmark validity), generated artifacts (INDEX.md, MASTER-ROUTING.md, ops/* documents), and the PowerShell implementation files master-route.ps1 and case-init.ps1. It also verifies cross-platform artifact placement when custom project roots are used.

Which PowerShell version is required to run the checks?

The script requires Windows PowerShell 5.1 or PowerShell Core 7.x (as specified by the #Requires -Version 5.1 directive). Linux and macOS runners must install PowerShell Core, while Windows runners can use the built-in Windows PowerShell or upgrade to Core for consistency.

How do I debug a failed coherence check locally?

Run the script locally with the -ScratchDir parameter pointing to a new directory. If validation fails, examine the failures.txt file created in that directory, which contains the detailed error report. Compare the output against skills/config/routing.json and skills/MASTER-ROUTING.md to identify discrepancies.

Can I run verify-routing-coherence on Linux or macOS CI runners?

Yes. Install PowerShell Core (pwsh) on the runner, then invoke the script using the pwsh shell. The script is cross-platform and validates file paths and artifact placement correctly on all supported operating systems.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}