# How Routing Coherence Is Verified in reverse-skill: A Complete Technical Guide

> Learn how reverse-skill verifies routing coherence using a PowerShell script and 13 deterministic checks to keep routing files synchronized. A complete technical guide.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-26

---

**The reverse-skill repository maintains routing coherence through the PowerShell script `verify-routing-coherence.ps1`, which performs 13 deterministic checks to ensure that [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), and [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) remain perfectly synchronized.**

Maintaining **routing coherence** ensures that skill dispatching remains reliable and documentation stays accurate across the reverse-skill platform. Instead of relying on manual audits, the repository automates verification through a single script invoked by smoke tests and CI pipelines. This approach guarantees that the routing configuration never drifts between its JSON source, human-readable tables, and regression benchmarks.

## The Three Sources of Truth

The verification process centers on three artifacts that must remain in lockstep:

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The authoritative routing definition containing all route mappings, labels, and metadata.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)** – A human-readable routing table generated from the JSON file for documentation purposes.
- **[`skills/tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tests/routing-benchmark.json)** – A comprehensive test suite containing at least 100 cases that validate routing behavior.

When any of these files drift out of sync—such as a route existing in the JSON but not in the benchmark—the coherence check fails and blocks the pipeline.

## Inside the Verification Script

The **`verify-routing-coherence.ps1`** script executes 13 distinct validation steps, each logging `[OK]` on success or `[FAIL]` on error. According to the source code in `skills/scripts/verify-routing-coherence.ps1`, these checks span file integrity, data consistency, and code quality.

### File Integrity and Structure Checks

The script first validates the existence and basic structure of the routing configuration:

- **Existence verification**: Confirms [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) exists at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) (lines 27-30).
- **Minimum route count**: Ensures the JSON contains at least 30 routes, preventing accidental deletion of large skill sets (line 32).
- **Required field validation**: Verifies every route defines `label`, `skill`, and `keywords` fields to prevent malformed entries (lines 33-35).

### Route Validity and Git Tracking

After confirming structure, the script validates that referenced resources actually exist:

- **Skill file existence**: Checks that each `skill` path in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) points to an existing file in the repository (lines 36-38).
- **Git tracking verification**: Ensures all skill files referenced by routes are tracked by Git, detecting accidental omissions of new skill files from version control (lines 39-45).

### Priority Array Consistency

The script enforces deterministic routing order through priority validation:

- **1-to-1 priority mapping**: Verifies that the `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) contains every route ID exactly once, ensuring no routes are orphaned or duplicated (lines 47-50).
- **Documentation synchronization**: Compares the ordered list of route IDs in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) against the `priority` array in the JSON file, detecting drift between the human-readable table and its source (lines 51-62).

### Benchmark Validation

The regression suite must accurately reflect the current routing configuration:

- **Minimum benchmark size**: Requires [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) to contain at least 100 test cases (lines 67-72).
- **Expectation format**: Validates that every `expect` field matches the pattern `R\d+`, ensuring benchmark expectations reference valid route IDs (lines 73-74).
- **Stale entry detection**: Confirms all benchmark `expect` IDs exist in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), preventing obsolete test cases from accumulating (lines 75-79).

### Code Quality and Operations Checks

Finally, the script validates auxiliary artifacts and coding practices:

- **Generated index presence**: Confirms [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) exists (generated by `extract-summaries.ps1`), ensuring the public skill catalogue is current (line 84).
- **No hard-coded routing**: Scans `skills/scripts/master-route.ps1` for hard-coded routing tables, enforcing that the router always reads dynamically from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) (lines 86-92).
- **Operations artifacts**: Verifies essential operation documents exist, including [`ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/IDENTITY.md) and [`scope-contract.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope-contract.md) (lines 94-100).

## Running the Verification Locally

You can execute the coherence check manually using PowerShell Core on any platform:

```bash
cd skills/scripts
pwsh -NoProfile -File verify-routing-coherence.ps1

```

Successful execution produces output confirming each check:

```

[OK] routing.json routes=78
[OK] routing.json: all routes have label/skill/keywords
[OK] routing.json: all route skills exist
[OK] routing.json: all route skills are tracked
[OK] routing.json priority covers all routes (1:1)
[OK] MASTER-ROUTING.md priority table matches routing.json
[OK] benchmark cases=124
[OK] benchmark expect ids well-formed
[OK] benchmark expects all exist in routing.json
[OK] INDEX.md present (generated)
[OK] master-route.ps1 has no hardcoded routing table
[OK] ops/IDENTITY.md present

```

If any check fails, the script exits with a non-zero code and logs `[FAIL]`, requiring immediate correction before the routing configuration can be considered coherent.

## Integrating with CI/CD

The repository integrates this verification into its testing pipeline via `skills/scripts/test-routing.ps1`. The CI snippet invokes the script with execution policies bypassed and monitors the exit code:

```powershell
& $HostExe -NoProfile -ExecutionPolicy Bypass -File (Join-Path $scriptDir 'verify-routing-coherence.ps1') 2>&1 |
    ForEach-Object { Write-Host $_ }
if ($LASTEXITCODE -ne 0) { exit 1 }

```

This integration ensures that **routing coherence** is validated on every commit, preventing broken routing configurations from reaching production.

## Summary

- The **`verify-routing-coherence.ps1`** script serves as the single entry point for validating routing integrity across the reverse-skill repository.
- Verification spans three critical files: [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), and [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json).
- Thirteen specific checks validate everything from file existence to Git tracking to benchmark accuracy.
- The script exits non-zero on any failure, making it suitable for CI/CD gates.
- Hard-coded routing tables in `master-route.ps1` are explicitly prohibited to enforce dynamic configuration.

## Frequently Asked Questions

### What happens if the routing coherence verification fails?

The script logs a `[FAIL]` message for the specific check that did not pass and exits with a non-zero status code. When running in CI/CD, this immediately aborts the pipeline, preventing deployment of an inconsistent routing configuration. Developers must fix the underlying issue—such as adding a missing skill file to Git or regenerating [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)—before the check will pass.

### How often should `verify-routing-coherence.ps1` be executed?

The script runs automatically during smoke tests and CI pipelines, ensuring verification occurs on every pull request and deployment. For local development, run it whenever you modify [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), add new skills, or update routing benchmarks to catch synchronization errors before committing.

### Can I run the verification script on Linux or macOS?

Yes. The script requires **PowerShell Core** (`pwsh`), which is cross-platform. Install PowerShell Core on Linux or macOS, navigate to `skills/scripts/`, and execute the script using `pwsh -NoProfile -File verify-routing-coherence.ps1`. All path validations and Git checks function identically across operating systems.

### What is the relationship between [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)?

[`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) is the machine-readable single source of truth containing route definitions, while [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) is a human-readable markdown table generated from that JSON. The verification script ensures the priority order in the markdown file exactly matches the `priority` array in the JSON (lines 51-62 of the script), preventing documentation drift when routes are reordered or renamed.