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

> Integrate verify-routing-coherence checks into your CI pipelines for Reverse-Skill. Run the PowerShell script, set a ScratchDir, and ensure success by failing on non-zero exit codes.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The single source of truth for all route definitions.
- **[`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)** – Sanity-checks ensuring benchmark cases reference existing routes.
- **Generated artifacts** – Validates [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md), [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```yaml
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt) report for debugging.

## Local Debugging and Manual Execution

Before pushing to CI, run the checks locally to validate changes to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) or [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md).

### Windows PowerShell 5.1

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

```

### PowerShell Core on Linux/macOS

```bash
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The canonical routing definition cross-validated against [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md).
- **[`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) files.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)** – Human-readable matrix cross-validated against [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json).
- **[`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) (route definitions), [`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json) (benchmark validity), generated artifacts ([`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md), [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt) file created in that directory, which contains the detailed error report. Compare the output against [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.