What Does the verify-routing-coherence Script Do in reverse-skill? A Complete Technical Breakdown

The verify-routing-coherence.ps1 script is a comprehensive pre-flight health check that validates 20+ structural, contractual, and supply-chain integrity conditions before any skill can execute in the reverse-skill repository.

The reverse-skill repository depends on a complex web of JSON routing tables, operational contracts, and auto-generated artifacts to route user intents to security skills. The verify-routing-coherence script acts as the gatekeeper that ensures this entire system remains internally consistent and CI-ready. Located at skills/scripts/verify-routing-coherence.ps1, it enforces everything from routing JSON schema compliance to mandatory supply-chain pinning policies.

---

Core Architecture: Three Validation Layers

The script organizes its 20 validation checks into three conceptual layers. Each layer targets a specific failure mode that could break skill routing or operational security.

1. Routing Table Integrity

The foundation of reverse-skill is config/routing.json, the single source of truth for all skill-to-route mappings. The verify-routing-coherence script performs four critical checks on this file.

Routing JSON sanity — The script confirms the file exists, contains at least 30 routes, and that every route includes the mandatory fields label, skill, and keywords (lines 24-30). Empty or malformed routes are rejected immediately.

Skill file existence — Every skill path referenced in the JSON must resolve to an actual file on disk (lines 31-34). This prevents "dead routes" that would crash the router at runtime.

Git tracking verification — Using git ls-files, the script ensures every referenced skill file is version-controlled (lines 35-41). Untracked skills break reproducibility and audit trails.

Priority array 1:1 mapping — The priority array in the JSON must cover every route exactly once with no extraneous IDs (lines 44-47). This guarantees deterministic routing order when multiple routes match.

2. Benchmark and Artifact Consistency

Beyond static configuration, the script validates dynamic artifacts and test expectations.

Benchmark consistency — The script loads tests/routing-benchmark.json, asserts at least 100 test cases exist, validates that each case's expect identifier matches the R… pattern, and confirms every expectation exists in the routing JSON (lines 52-63). Stale benchmarks that reference removed routes are flagged.

Generated index presence — The auto-generated INDEX.md must exist (line 68). This searchable overview is consumed by users and downstream tooling.

Hard-coded routing protection — The script scans master-route.ps1 for literal routing tables like $map = [ordered] or 'R1' = 'apk-reverse' and fails if found (lines 70-76). This architectural rule forces all routes to be driven exclusively by routing.json, preventing shadow routing logic.

Master-route case validation — For every canonical case (e.g., "apk-reverse", "malware-analysis"), the script executes master-route.ps1 and verifies that:

• The generated route-scope.md contains the expected primary ID (e.g., R1)
• The underlying SKILL.md file exists

This end-to-end check spans lines 94-29.

Output directory behavior — The script confirms that master-route.ps1 creates a work/ subfolder when invoked without -OutDir, and that -ProjectRoot correctly places artifacts inside the caller's project tree (lines 31-47). This guarantees clean artifact isolation for concurrent analyses.

3. Operational Contract and Supply-Chain Security

The most extensive validation layer ensures operational documents are complete and dependencies are tamper-resistant.

Ops artifact verification — A curated list of required operational documents is asserted to exist (lines 78-12): ops/IDENTITY.md, ops/role-map.md, MASTER-ROUTING.md, and others. These contractual "gates" define scope, evidence requirements, and timeline conventions.

Hub ↔ Ops bidirectional linking — The three hub files (MASTER-ROUTING.md, SKILL.md, routing.md) must contain references to ops contracts for scope, identity, and related concepts (lines 15-22). This enforces navigability between skill definitions and their operational contracts.

RULES gate enforcement — Both RULES.md and RULES_zh.md are validated for:

• Mandatory "case-init / scope" language
• Hard-gate authentication checks
• Explicit ordering of case-init before any ACT command

This implements the security-first "must not ACT before scope" policy (lines 34-57).

Template field checks — A helper function Assert-Fields inspects core operational markdown files for required headings like auth, Evidence, and timeline.md, flagging any schema violations (lines 60-84).

Role-map completeness — The script scans ops/role-map.md to confirm each primary skill domain (attack-chain, pentest-tools, etc.) is documented (lines 87-91).

Case-init artifact validation — Running case-init.ps1 with both default and explicit ProjectRoot, the script validates that generated scope.md, timeline.md, and workitems.md contain required keys including auth and network_profile (lines 68-81).

Ghost DSL detection — Hub files are scanned for stale DSL paths like dsl-vm-reverse/ that no longer match canonical locations (lines 13-21). Broken cross-references are treated as errors.

PowerShell parsing sanity — The script parses refresh-tool-index.ps1 with the PowerShell parser to detect syntax errors (lines 24-28), ensuring the tool index can be rebuilt.

Bootstrap-manifest parity — Capability lists in skills/bootstrap-manifest.json and kali/scripts/bootstrap-manifest.json are compared, with mismatches reported (lines 29-48).

Supply-chain pinning — For every auto-install capability in both manifests, the script confirms a version/commit hash or explicit pin-policy exists. Special handling covers GitHub releases, local HTTP, apt, Docker, and other sources (lines 53-80). This enforces reproducible, tamper-resistant installation of third-party tools.

Identity contract check — The script inspects ops/IDENTITY.md for language that explicitly excludes platform-specific runtimes (FastAPI, React) and includes reverse-skill DNA keywords (lines 83-87). This guarantees repository portability.

---

Running the verify-routing-coherence Script

Basic Execution

From the repository root, invoke the script with PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

Successful output appears as:

[OK] routing.json routes=162
[OK] routing.json: all routes have label/skill/keywords
[OK] routing.json: all route skills exist
...
ALL ROUTING COHERENCE CHECKS PASSED

Failures produce [FAIL] … lines, write details to Scratch\…\failures.txt, and exit with code 1.

Custom Scratch Directory

For debugging or CI artifact retention, specify a custom working directory:

$env:TEMP = "$HOME/tmp"
powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1 -ScratchDir "$HOME/tmp/rs-verify"

The script creates the directory, runs all checks, and leaves detailed logs including artifacts-index.txt, template-fields.txt, and verify.txt.

GitHub Actions Integration

- name: Verify routing coherence
  run: |
    pwsh -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

The exit code contract (0 = success, 1 = failure) enables native CI failure propagation.

---

Related Source Files

File	Purpose	Location
verify-routing-coherence.ps1	Main validation script	skills/scripts/
routing.json	Canonical routing table	skills/config/
master-route.ps1	Intent-to-skill routing engine	skills/scripts/
routing-benchmark.json	Routing test expectations	skills/tests/
case-init.ps1	Case scope document generator	skills/scripts/
RULES.md / RULES_zh.md	Security policy gate documents	Repository root
IDENTITY.md	Platform-agnostic identity contract	ops/
refresh-tool-index.ps1	Tool index generator	skills/scripts/
bootstrap-manifest.json	Auto-install capability registry	skills/scripts/

---

Summary

The verify-routing-coherence script in reverse-skill provides 20+ automated checks across three architectural layers:

• Structural correctness — Routing JSON schema, file existence, Git tracking, and priority 1:1 mappings
• Contractual completeness — Operational document presence, RULES gate enforcement, hub-ops linking, and template field validation
• Supply-chain integrity — Bootstrap manifest parity, mandatory version/commit pinning, and identity contract compliance

The script exits with code 0 and emits "ALL ROUTING COHERENCE CHECKS PASSED" on success, or code 1 with detailed failures.txt output on any violation. It is a prerequisite for the repository's CI test suite and should be run manually before any commit touching routing or ops contracts.

---

Frequently Asked Questions

What happens if verify-routing-coherence fails?

The script writes all failure details to a failures.txt file in the scratch directory and exits with status code 1. CI pipelines treat this as a blocking error, and developers must address the reported issues before merging.

Can I run verify-routing-coherence on Windows and Linux?

Yes. The script is written in PowerShell Core (pwsh) and executes identically on Windows, macOS, and Linux provided PowerShell 7+ is installed.

How does verify-routing-coherence prevent hard-coded routing?

The script scans master-route.ps1 for literal routing table definitions like $map = [ordered] or direct route ID assignments. If found, the check fails immediately, enforcing the architectural rule that all routing must flow through routing.json.

Why does verify-routing-coherence check for FastAPI and React exclusions?

The ops/IDENTITY.md check verifies that platform-specific runtimes are explicitly excluded while reverse-skill DNA keywords are present. This ensures the repository remains portable and not inadvertently coupled to specific web frameworks or deployment targets.

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