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

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 aligns with benchmark expectations, operational documentation, security constraints, and executable entry points. If any check fails, the script aggregates failures into 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 and exits with status 0.

Validating the Routing Configuration (routing.json)

The script treats 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 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.
• Documentation freshness: Verifies that 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.

Security Contract and Governance Enforcement

Security policies are enforced through static analysis of governance documents:

• RULES gating: Confirms that RULES.md and 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, timeline.md, and 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, SKILL.md, and 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, role-map.md) exists in the repository.
• Hub-to-ops linking: Checks that hub documentation (MASTER-ROUTING.md, SKILL.md, routing.md) contains valid hyperlinks to scope, identity, and other critical ops files.
• Platform agnosticism: Confirms that 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, 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 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 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 -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 -File skills/scripts/verify-routing-coherence.ps1 -ScratchDir C:\temp\rs-verify

Integrate into GitHub Actions or Azure DevOps pipelines:

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

After a failure, inspect the detailed error log:

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 remains the single source of truth by verifying route count, field completeness, and Git tracking.
• The script enforces security contracts by validating 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, 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. It returns a non-zero exit code (specifically 1) when any validation fails, aggregating error details into 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 (such as APK, malware, and pentest), then inspects the generated 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 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 references an expect ID matching the pattern R\d+ that exists in 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.

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