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

> Discover the supply-chain pin gate in verify-routing-coherence.ps1. Learn how it enforces version pinning and why unpinned tools cause build failures for reproducible builds.

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

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) and [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.

```powershell

# 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)

```powershell
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:

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

```

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

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

```

For capabilities using Git repositories, specify a `pinnedCommit`:

```json
{
    "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) or [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) (for the main repository toolset) and [`kali/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.