# How `verify-routing-coherence.ps1` Detects Configuration Drift in PowerShell Routing Systems

> Learn how verify-routing-coherence.ps1 detects configuration drift by comparing routing.json to MASTER-ROUTING.md, scanning master-route.ps1, and checking skill file existence. Ensure routing integrity.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-28

---

**The `verify-routing-coherence.ps1` script detects configuration drift by cross-referencing [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) against [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), scanning `master-route.ps1` for hard-coded mappings, and verifying that every referenced skill file exists and is Git-tracked.**

In the `zhaoxuya520/reverse-skill` repository, routing logic depends on a single source of truth defined in JSON configuration files. As the system evolves, maintaining synchronization between code, documentation, and the filesystem becomes critical. The `verify-routing-coherence.ps1` script implements a three-layer validation strategy to catch discrepancies before they reach production environments.

## The Three-Layer Configuration Drift Detection Strategy

The script operates as a gatekeeper by validating three distinct vectors where drift commonly occurs: documentation sync, code hygiene, and filesystem integrity.

### Priority Table Consistency Between JSON and Markdown

At lines 55–60 of `skills/scripts/verify-routing-coherence.ps1`, the script performs a side-by-side comparison of the `priority` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) against the ordered route IDs extracted from the markdown table in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md). 

The validator walks both lists simultaneously, comparing entries at each index. When the script encounters a mismatch—such as finding route `R15` in the JSON where `R12` appears in the documentation—it records a specific drift entry. This prevents accidental reordering or silent omission of routes that would otherwise cause the routing engine to process requests in an unintended sequence.

```powershell

# Example drift output when priorities diverge

[FAIL] MASTER-ROUTING priority drift: 3:R15->R12, 7:R22->R23

```

### Hard-Coded Routing Table Detection

The script enforces architectural discipline by scanning `skills/scripts/master-route.ps1` for legacy patterns that bypass the dynamic configuration system. At lines 86–92, it searches for literal strings matching `$map = [ordered]` or explicit route assignments like `R1 = 'apk-reverse'`.

If the detector finds any hard-coded routing mappings, it immediately flags a failure. This ensures that `master-route.ps1` always reads route definitions from [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) rather than maintaining a static, potentially stale routing table within the script itself.

### Skill File Existence and Git Tracking Validation

For every route defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), the script verifies that the referenced skill file actually exists on disk and that Git is tracking it (lines 35–45). This catches two common failure modes:

- **Missing files**: Routes pointing to skills that have been deleted or renamed without updating the configuration
- **Untracked changes**: New skill files added to the working directory but not yet committed, which would break the routing engine in a fresh clone

## Source Code Implementation Details

The `verify-routing-coherence.ps1` script aggregates all detected issues into a `$fail` collection. When any validation layer discovers drift, the script populates this list with descriptive error messages and exits with a non-zero status code. This design makes the script natively compatible with CI/CD pipelines where non-zero exits trigger build failures.

The validation sequence proceeds as follows:

1. Load the JSON configuration from [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
2. Parse the markdown table from [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) to extract the expected priority order
3. Iterate through both collections to detect index-based mismatches
4. Scan `master-route.ps1` content for forbidden hard-coding patterns
5. Check filesystem existence and Git status for each skill reference

## Running the Verification

You can execute the drift detection locally from the repository root to validate your changes before committing:

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

```

For automated enforcement, integrate the script into your GitHub Actions workflow:

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

```

When drift is detected, the workflow step fails with output similar to:

```

[FAIL] MASTER-ROUTING priority drift: 3:R15->R12, 7:R22->R23
[FAIL] master-route.ps1 contains hardcoded routing table (must read routing.json)
[FAIL] routing.json missing skill files: apk-reverse, unknown-skill

```

## Summary

- The `verify-routing-coherence.ps1` script in `zhaoxuya520/reverse-skill` prevents configuration drift through triple validation
- It ensures [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) priorities match the [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) documentation (lines 55–60)
- It blocks hard-coded routing tables in `master-route.ps1` (lines 86–92)
- It verifies every referenced skill file exists and is Git-tracked (lines 35–45)
- The script exits with non-zero status when drift is detected, making it ideal for CI gates

## Frequently Asked Questions

### What constitutes configuration drift in the reverse-skill routing system?

Configuration drift occurs when the routing definition in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) diverges from the human-readable documentation in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md), when `master-route.ps1` contains static routing logic instead of dynamic JSON lookups, or when skill files referenced in the configuration are missing or untracked by Git. Any of these conditions can cause the routing engine to behave differently than documented or expected.

### How does the script detect hard-coded routing tables?

The script scans the content of `skills/scripts/master-route.ps1` for specific PowerShell patterns associated with static mappings, including `$map = [ordered]` declarations and explicit route assignments like `R1 = 'skill-name'`. Detection of these patterns triggers an immediate failure because they indicate the script is not reading from the centralized [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) configuration.

### Can this script run on non-Windows systems?

Yes, the script is compatible with PowerShell Core (pwsh) on Linux and macOS. The GitHub Actions example uses `pwsh` rather than Windows PowerShell, enabling cross-platform CI/CD validation. Ensure PowerShell is installed on your runner or local machine before executing the verification.

### What happens when configuration drift is detected?

When the script identifies any drift across its three validation layers, it aggregates the specific failures into a `$fail` list, prints detailed error messages to the console, and exits with a non-zero status code. This behavior causes CI pipelines to halt immediately, preventing merges that would introduce inconsistent routing state into the main branch.