Understanding the Supply-Chain Pin Gate in verify-routing-coherence.ps1

The supply-chain pin gate is a verification mechanism in verify-routing-coherence.ps1 that enforces exact version pinning for all bootstrap dependencies and auto-install capabilities, failing the build when tools lack reproducible source identifiers.

The reverse-skill repository uses this PowerShell script to validate manifest files and ensure every external dependency is tamper-resistant and reproducible. Located at skills/scripts/verify-routing-coherence.ps1, the gate scans bootstrap-manifest.json files to detect unpinned packages that could introduce supply-chain drift or security vulnerabilities.

What Is the Supply-Chain Pin Gate?

The supply-chain pin gate is a defensive validation step that iterates over manifest entries in skillsManifest and kaliManifest (referencing skills/scripts/bootstrap-manifest.json and kali/scripts/bootstrap-manifest.json). It performs strict checks to confirm that every auto-install capability and bootstrap dependency specifies an immutable source version. If any entry lacks proper pinning, the script invokes the Bad function, aggregates all failures, and exits with a non-zero status code, halting the verification pipeline.

How the Pin Gate Validates Dependencies

The verification logic handles two distinct categories of dependencies, each with specific pinning requirements.

Bootstrap Dependency Verification

For bootstrap dependencies, the gate ensures each entry contains both a package name and a version string formatted as an exact match. The script constructs a regex pattern requiring either == or @ suffixes followed by the escaped version string.

# From verify-routing-coherence.ps1

foreach ($dependencyProperty in @($mc.bootstrapDependencies.PSObject.Properties)) {
    $dependency = $dependencyProperty.Value
    $expectedSuffix = '(?:==|@)' + [regex]::Escape([string]$dependency.version) + '$'
    if ([string]::IsNullOrWhiteSpace([string]$dependency.package) -or
        [string]::IsNullOrWhiteSpace([string]$dependency.version) -or
        [string]$dependency.package -notmatch $expectedSuffix) {
        Bad "unpinned bootstrap dependency: $($dependencyProperty.Name) in $mn"
    } else {
        Ok "pinned bootstrap dependency $($dependencyProperty.Name) in $mn"
    }
}

If the package name omits the version suffix or uses loose version specifiers, the script emits the error: unpinned bootstrap dependency: <name> in <manifest>.

Auto-Install Capability Verification

Capabilities marked with canAutoInstall must provide at least one pinning artifact: pinnedVersion, pinnedCommit, or pinPolicy. The script applies additional rules based on the bootstrapKind:

• GitHub releases (github-release-zip): May use assetSha256 or preferApiDigest as alternative pins
• Local HTTP MCP (local-http-mcp): Exempt only if it does not fetch external sources (no repoUrl or repo fields)

foreach ($cap in $mc.capabilities) {
    if (-not $cap.canAutoInstall) { continue }
    $hasPin = ($cap.pinnedVersion -or $cap.pinnedCommit -or $cap.pinPolicy)
    switch ($cap.bootstrapKind) {
        'github-release-zip' { $hasPin = $hasPin -or $cap.assetSha256 -or $cap.preferApiDigest }
        'local-http-mcp' {
            $fetchesExternalSource = $cap.repoUrl -or $cap.repo
            $hasPin = (-not $fetchesExternalSource) -or $cap.pinnedCommit -or $cap.pinnedVersion
        }
    }
    if (-not $hasPin) {
        Bad "unpinned auto-install capability: $($cap.name) in $mn ($($cap.bootstrapKind))"
    } else {
        Ok "pinned $($cap.name) in $mn"
    }
}

When validation fails, the script reports: unpinned auto-install capability: <name> in <manifest> (<bootstrapKind>).

Why Unpinned Tools Cause Verification Failures

The supply-chain pin gate fails deliberately when encountering unpinned tools to prevent reproducibility breaches and supply-chain attacks. Without exact version pins or commit hashes, subsequent installations might retrieve different binary artifacts if upstream sources change. This non-deterministic behavior breaks build reproducibility and creates attack vectors where malicious actors could substitute compromised packages.

When the script detects unpinned entries, it records the failures, prints a summary of all Bad messages, and terminates with a non-zero exit code. This hard stop forces maintainers to explicitly declare trusted versions, ensuring the reverse-skill framework operates only with cryptographically verifiable or version-locked dependencies.

How to Fix Unpinned Tool Errors

Resolving pin gate failures requires adding explicit version constraints to the manifest files.

For bootstrap dependencies, ensure the package string includes an exact version matcher:

{
    "bootstrapDependencies": {
        "python": { 
            "package": "pip-package==3.10.2", 
            "version": "3.10.2" 
        }
    }
}

For auto-install capabilities, add a pinnedVersion, pinnedCommit, or SHA256 checksum:

{
    "name": "example-tool",
    "bootstrapKind": "github-release-zip",
    "canAutoInstall": true,
    "pinnedVersion": "v2.4.1",
    "assetSha256": "d41d8cd98f00b204e9800998ecf8427e"
}

For capabilities using Git repositories, specify a pinnedCommit:

{
    "name": "git-tool",
    "bootstrapKind": "git-clone",
    "canAutoInstall": true,
    "pinnedCommit": "abc123def456"
}

Summary

• The supply-chain pin gate in verify-routing-coherence.ps1 validates that all external dependencies in bootstrap-manifest.json files use immutable version pins.
• Bootstrap dependencies must use exact match syntax (== or @) tying the package name to the version string.
• Auto-install capabilities require pinnedVersion, pinnedCommit, pinPolicy, or kind-specific alternatives like assetSha256.
• Unpinned tools trigger a non-zero exit status, forcing resolution before the verification pipeline completes.
• Fixes involve adding explicit version constraints to the JSON manifest entries in skills/scripts/bootstrap-manifest.json or kali/scripts/bootstrap-manifest.json.

Frequently Asked Questions

What is a supply-chain pin gate?

A supply-chain pin gate is an automated verification step that checks whether software dependencies specify exact, immutable versions rather than loose or floating references. In the reverse-skill repository, this gate operates within verify-routing-coherence.ps1 to ensure every tool and library consumed by the framework is reproducibly sourced and resistant to tampering.

Why does verify-routing-coherence.ps1 check for exact version matches?

The script enforces exact version matches (using == or @ syntax) to guarantee that package managers retrieve bit-for-bit identical artifacts on every installation. This prevents "dependency confusion" attacks and ensures that the specific version tested in development is the version deployed in production, eliminating drift from silent updates.

How do I resolve an "unpinned auto-install capability" error?

Add a pinning artifact to the capability's entry in the appropriate bootstrap-manifest.json file. You can specify pinnedVersion for release tags, pinnedCommit for Git repositories, or assetSha256 for downloadable binaries. If the capability uses a local-http-mcp bootstrap kind that doesn't fetch external sources, ensure it lacks repoUrl and repo fields to qualify for the exemption.

Where are the manifest files located in reverse-skill?

The primary manifest files validated by the pin gate are located at skills/scripts/bootstrap-manifest.json (for the main repository toolset) and kali/scripts/bootstrap-manifest.json (for the Kali-specific toolset). These JSON files define capabilities, bootstrap dependencies, and pinning policies that the verify-routing-coherence.ps1 script analyzes.

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