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

The verify-routing-coherence.ps1 script detects configuration drift by cross-referencing routing.json against 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 against the ordered route IDs extracted from the markdown table in 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.

# 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 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, 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
2. Parse the markdown table from 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 -NoProfile -ExecutionPolicy Bypass -File .\skills\scripts\verify-routing-coherence.ps1

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

- 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 priorities match the 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 diverges from the human-readable documentation in 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 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.

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