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

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, MASTER-ROUTING.md, and 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 – The authoritative routing definition containing all route mappings, labels, and metadata.
• skills/MASTER-ROUTING.md – A human-readable routing table generated from the JSON file for documentation purposes.
• 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 exists at 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 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 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 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 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, 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 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 (lines 86-92).
• Operations artifacts: Verifies essential operation documents exist, including ops/IDENTITY.md and scope-contract.md (lines 94-100).

Running the Verification Locally

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

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:

& $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, MASTER-ROUTING.md, and 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—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, 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 and MASTER-ROUTING.md?

routing.json is the machine-readable single source of truth containing route definitions, while 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.

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