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

> Discover what the verify-routing-coherence script does in reverse-skill. This PowerShell script performs a crucial pre-flight health check for skill execution, ensuring integrity. Learn more!

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) contains the expected primary ID (e.g., `R1`)
- The underlying [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/IDENTITY.md), [`ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/role-map.md), [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`RULES_zh.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), flagging any schema violations (lines 60-84).

**Role-map completeness** — The script scans [`ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), [`timeline.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/timeline.md), and [`workitems.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/bootstrap-manifest.json) and [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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
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:

```powershell
$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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/artifacts-index.txt), [`template-fields.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/template-fields.txt), and [`verify.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify.txt).

### GitHub Actions Integration

```yaml
- 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) | Canonical routing table | `skills/config/` |
| `master-route.ps1` | Intent-to-skill routing engine | `skills/scripts/` |
| [`routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing-benchmark.json) | Routing test expectations | `skills/tests/` |
| `case-init.ps1` | Case scope document generator | `skills/scripts/` |
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) / [`RULES_zh.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES_zh.md) | Security policy gate documents | Repository root |
| [`IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/IDENTITY.md) | Platform-agnostic identity contract | `ops/` |
| `refresh-tool-index.ps1` | Tool index generator | `skills/scripts/` |
| [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json).

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

The [`ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.