# Purpose of verify-routing-coherence.ps1 in reverse-skill: Full-Stack Integrity Audit Explained

> Understand the purpose of verify-routing-coherence.ps1 in reverse-skill. This script automates a full-stack integrity audit for routing, docs, benchmarks, and security contracts.

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

---

**The `verify-routing-coherence.ps1` script is a comprehensive sanity-check utility that automates a full-stack integrity audit of the routing configuration, documentation, benchmarks, and security contracts within the *reverse-skill* repository.**

Located at `skills/scripts/verify-routing-coherence.ps1` in the `zhaoxuya520/reverse-skill` repository, this PowerShell validator ensures that every artefact defining how security skills are discovered, invoked, and gated remains internally consistent. It aggregates over twenty distinct validation checks into a single automated gate that prevents configuration drift and enforces governance policies before code reaches production.

## Core Responsibilities of the Routing Validator

The script functions as a **coherence engine** that cross-references multiple subsystems. When executed, it validates that the canonical routing table in [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) aligns with benchmark expectations, operational documentation, security constraints, and executable entry points. If any check fails, the script aggregates failures into [`failures.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt), prints a red-colored summary, and exits with a non-zero status. Upon success, it writes *"ALL ROUTING COHERENCE CHECKS PASSED"* to [`verify.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify.txt) and exits with status `0`.

## Validating the Routing Configuration ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json))

The script treats [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) as the single source of truth and subjects it to rigorous structural validation:

- **Existence and parsability**: Confirms the file exists and contains valid JSON.
- **Route cardinality**: Verifies the presence of **≥ 30 routes** to ensure comprehensive skill coverage.
- **Field completeness**: Ensures every route object contains mandatory fields: `label`, `skill`, and `keywords`.
- **File existence**: Validates that all `skill` paths referenced in routes point to existing files.
- **Version control**: Checks that every route file is tracked by Git, preventing orphaned entries.
- **Priority coverage**: Confirms the priority list encompasses every defined route.

These checks guarantee that `master-route.ps1` can deterministically resolve any valid skill hint without encountering missing or malformed routing entries.

## Benchmark and Documentation Consistency

The validator ensures that regression testing and public documentation remain synchronized with the routing table:

- **Benchmark validation**: Inspects [`tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tests/routing-benchmark.json) for existence and a minimum of **≥ 100 benchmark cases**. Each case’s `expect` ID must match the pattern `R\d+` and correspond to a valid entry in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json).
- **Documentation freshness**: Verifies that [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md) (generated by `extract-summaries.ps1`) is present, ensuring the public skill index is current.
- **Hard-coded table prevention**: Scans `master-route.ps1` to confirm it does **not** contain an embedded routing table, forcing dependency on the canonical [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json).

## Security Contract and Governance Enforcement

Security policies are enforced through static analysis of governance documents:

- **RULES gating**: Confirms that [`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) embed the required "case-init / scope" and "auth status = granted" guard language. This enforces the critical policy that analysis must be scoped before any ACT (Action) is permitted.
- **Case initialization scaffolding**: Executes `case-init.ps1` and validates the creation of [`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). It verifies that required fields—including `auth`, `network_profile`, `in_scope`, and `ready_for_act`—are present, ensuring the case-initialization contract is honored.
- **Decision-boundary contracts**: Scans [`ops/timeline-workitem.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/timeline-workitem.md), [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), and [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for the "genuine decision boundary" language introduced in issue #77, ensuring the governance model (decision Δ, carry-forward refs) is consistently applied.

## Operational Integrity Verification

The script validates that operational artefacts required for deployment and role-based access control are present and correctly linked:

- **Ops artefacts existence**: Verifies that every file listed under *ops* (e.g., [`IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/IDENTITY.md), [`role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/role-map.md)) exists in the repository.
- **Hub-to-ops linking**: Checks that hub documentation ([`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)) contains valid hyperlinks to scope, identity, and other critical ops files.
- **Platform agnosticism**: Confirms that [`ops/IDENTITY.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/IDENTITY.md) explicitly avoids platform-specific frameworks (FastAPI, React) and retains core reverse-skill concepts.
- **Role-map coverage**: Ensures that primary skill categories appear in [`ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ops/role-map.md), keeping the role-based permission matrix current.

## End-to-End Routing Tests

Beyond static analysis, the script performs dynamic validation of the routing engine:

- **Master-route matrix**: Executes `master-route.ps1` for every defined skill (APK, malware, pentest, etc.) and validates that the generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) contains the correct route ID and that the source skill file exists. This provides end-to-end validation that the routing engine produces expected artefacts.
- **Default work-directory handling**: Checks that when no explicit `-OutDir` is given, output is placed under a `work/` folder, preventing stray files from littering the repository root.
- **Project-root isolation**: Verifies that using `-ProjectRoot` keeps all generated artefacts inside the caller’s project tree, supporting composability when the skill is invoked from external projects.

## Dependency and Migration Checks

The validator ensures build reproducibility and prevents legacy path regressions:

- **Ghost-DSL detection**: Detects stray references to the deprecated `dsl-vm-reverse/` path that should have been migrated, preventing stale paths from breaking builds.
- **Bootstrap-manifest parity**: Compares [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) with the Kali counterpart and flags missing capabilities.
- **Dependency pinning**: Inspects all bootstrap capabilities for proper version/commit pinning according to their `bootstrapKind`, enforcing reproducible builds and supply-chain security.

## How to Run verify-routing-coherence.ps1

Execute the script from the repository root using PowerShell with bypass execution policy:

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

```

The script creates a temporary scratch directory, prints `[OK] …` or `[FAIL] …` lines for each check, and exits with code `0` on success or `1` on failure.

To specify a custom scratch directory for CI artifact retention:

```powershell
powershell -File skills/scripts/verify-routing-coherence.ps1 -ScratchDir C:\temp\rs-verify

```

Integrate into GitHub Actions or Azure DevOps pipelines:

```yaml
- name: Verify routing coherence
  run: powershell -File skills/scripts/verify-routing-coherence.ps1

```

After a failure, inspect the detailed error log:

```powershell
type $env:TEMP\failures.txt

# or if using -ScratchDir:

type C:\temp\rs-verify\failures.txt

```

## Summary

- **`verify-routing-coherence.ps1`** serves as the **canonical integrity gate** for the *reverse-skill* repository, validating over twenty distinct coherence constraints.
- It ensures **[`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json)** remains the single source of truth by verifying route count, field completeness, and Git tracking.
- The script enforces **security contracts** by validating [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) guards and `case-init.ps1` scaffolding fields.
- It performs **end-to-end dynamic tests** by executing `master-route.ps1` for every skill and verifying output artefacts.
- Exit codes (**`0`** for success, **`1`** for failure) and output files ([`verify.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify.txt), [`failures.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt)) provide machine-readable CI/CD integration points.

## Frequently Asked Questions

### What exit codes does verify-routing-coherence.ps1 return?

The script returns exit code **`0`** when all coherence checks pass, writing *"ALL ROUTING COHERENCE CHECKS PASSED"* to [`verify.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify.txt). It returns a **non-zero exit code** (specifically `1`) when any validation fails, aggregating error details into [`failures.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt) and printing a red-colored failure summary to stderr.

### How does the script validate that routes actually work?

The script executes `master-route.ps1` for every skill defined in [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) (such as APK, malware, and pentest), then inspects the generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) output to confirm it contains the correct route ID and that the referenced source skill file exists. This end-to-end test matrix verifies that the routing engine correctly resolves hints to concrete skill implementations.

### Can I run this script in a CI/CD pipeline without modifying the repository?

Yes. The script supports a `-ScratchDir` parameter that directs all temporary artefacts (including [`failures.txt`](https://github.com/zhaoxuya520/reverse-skill/blob/main/failures.txt) and intermediate test outputs) to a specified directory. This allows CI systems to retain logs without polluting the workspace, and the script’s exit code can directly gate pipeline stages, failing the build if routing coherence is compromised.

### What happens if the routing benchmark does not match the routing table?

The script validates that every entry in [`tests/routing-benchmark.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tests/routing-benchmark.json) references an `expect` ID matching the pattern `R\d+` that exists in [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json). If a benchmark case references a non-existent route ID or if the benchmark contains fewer than **100 test cases**, the script flags a coherence failure and exits with status `1`, preventing regression testing against stale or incomplete routing data.