# How the Supply-Chain Pin Gate in verify-routing-coherence Prevents Unpinned Auto-Installs

> Learn how the supply-chain pin gate in verify-routing-coherence blocks unpinned auto-installs. It enforces version constraints, securing your CI pipeline.

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

---

**The supply-chain pin gate in `verify-routing-coherence.ps1` blocks unpinned auto-installs by parsing bootstrap manifests and enforcing deterministic version constraints, aborting the CI pipeline with exit code 1 when any capability lacks a pinned reference.**

The `zhaoxuya520/reverse-skill` repository implements a rigorous supply-chain security model through its `verify-routing-coherence.ps1` script. This PowerShell validation gate inspects every auto-install capability to ensure deterministic provenance, preventing the execution environment from fetching uncontrolled external packages at runtime.

## How the Supply-Chain Pin Gate Works

The pin gate operates as a three-stage validation pipeline defined in `skills/scripts/verify-routing-coherence.ps1`. Each stage incrementally builds a compliance report, and any failure accumulates in a `$fail` counter that forces a non-zero exit status.

### Loading Bootstrap Manifests

The script first locates and parses two critical JSON manifests: the generic **skills manifest** and the **Kali-specific manifest**. These files define the bootstrap dependencies and capabilities requiring validation.

```powershell
$skillsManifest = Join-Path $scriptDir 'bootstrap-manifest.json'
$kaliManifest   = Join-Path $packageRoot 'kali/scripts/bootstrap-manifest.json'

```

These paths resolve to [`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) respectively (see lines 84‑86 of the script). By loading both manifests, the gate ensures no environment-specific dependency evades scrutiny.

### Validating Bootstrap Dependencies

Next, the gate inspects every entry under the `bootstrapDependencies` property. Each dependency must declare both a package name and a version enforced with an exact match operator (`==` or `@`). The script constructs a regex pattern that requires the version suffix to appear at the end of the package string.

```powershell
$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"
}

```

This check (lines 18‑23) rejects any dependency that uses loose versioning or omits the version constraint entirely, ensuring that `pip install requests` never executes as `pip install requests>=2.0`.

### Enforcing Pins on Auto-Install Capabilities

The final stage targets capabilities flagged with `canAutoInstall: true`. Each such capability must provide at least one deterministic reference: `pinnedVersion`, `pinnedCommit`, or `pinPolicy`. The gate applies additional bootstrap-kind-specific logic for specialized installation methods.

```powershell
$hasPin = ($capMap['pinnedVersion'] -or $capMap['pinnedCommit'] -or $capMap['pinPolicy'])
switch ($capMap['bootstrapKind']) {
    'github-release-zip'        { $hasPin = $hasPin -or $capMap['assetSha256'] -or $capMap['preferApiDigest'] }
    'local-http-mcp'           { $hasPin = (-not $fetchesExternalSource) -or $capMap['pinnedCommit'] -or $capMap['pinnedVersion'] }
    'remote-http-mcp'          { $hasPin = (-not $capMap['repoUrl']) -and (-not $capMap['repo']) -and $capMap['pinPolicy'] }
    'apt-package'              { $hasPin = $true }   # distro repos are considered pinned

    'docker-image'             { $hasPin = $true }
    default                    { $hasPin = $hasPin }
}
if (-not $hasPin) {
    Bad "unpinned auto‑install capability: $($capMap['name']) in $mn ($($capMap['bootstrapKind']))"
} else {
    Ok "pinned $($capMap['name']) in $mn"
}

```

This block (lines 31‑50) permits alternative pinning mechanisms—such as `assetSha256` for GitHub release ZIPs—while exempting distro-managed packages like `apt-package` and `docker-image` under the assumption that repository mirrors provide deterministic layers. If `$hasPin` remains false, the script logs a failure and ultimately terminates with `exit 1`, halting any downstream routing or execution.

## Practical Examples of Pin Validation

The following configurations illustrate compliant and non-compliant dependency declarations.

### Correctly Pinned Bootstrap Dependency

```json
{
  "bootstrapDependencies": {
    "pip-requests": {
      "package": "requests==2.31.0",
      "version": "2.31.0"
    }
  }
}

```

Because the `package` field ends with `==2.31.0`, the regex validation succeeds and the gate outputs:

```

[OK] pinned bootstrap dependency pip-requests in bootstrap-manifest.json

```

### Rejected Unpinned Capability

```json
{
  "capabilities": [
    {
      "name": "some-tool",
      "canAutoInstall": true,
      "bootstrapKind": "github-release-zip"
    }
  ]
}

```

Missing `pinnedVersion`, `assetSha256`, or `preferApiDigest`, this entry triggers:

```

[FAIL] unpinned auto-install capability: some-tool in bootstrap-manifest.json (github-release-zip)

```

The script exits with a non-zero status, blocking the CI run.

### Acceptable Pin for GitHub Releases

```json
{
  "capabilities": [
    {
      "name": "tool‑v1",
      "canAutoInstall": true,
      "bootstrapKind": "github-release-zip",
      "assetSha256": "a3f5e2…"
    }
  ]
}

```

The presence of `assetSha256` satisfies the `$hasPin` condition for the `github-release-zip` kind, allowing the gate to approve the capability.

## Summary

- **The supply-chain pin gate** in `verify-routing-coherence.ps1` enforces deterministic provenance by inspecting [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) files across the repository.
- **Dependency validation** requires exact version pinning using `==` or `@` operators, rejecting ambiguous version ranges.
- **Auto-install capability checks** mandate at least one pin field (`pinnedVersion`, `pinnedCommit`, `pinPolicy`, or bootstrap-kind-specific alternatives) for every component flagged with `canAutoInstall`.
- **Execution halt** occurs via `exit 1` when any validation fails, preventing unpinned packages from entering the runtime environment during CI/CD pipelines.

## Frequently Asked Questions

### What constitutes a valid pin for bootstrap dependencies?

A valid pin requires the `package` string to terminate with either `==` or `@` followed immediately by the version number, and the `version` field must be explicitly declared. For example, `"package": "requests==2.31.0"` satisfies the regex check, while `"package": "requests"` or `"package": "requests>=2.0"` causes the gate to flag an unpinned dependency.

### Why are apt-package and docker-image bootstrap kinds exempt from explicit pinning?

The script treats `apt-package` and `docker-image` as inherently pinned because they rely on distribution-managed repositories or immutable image digests managed by the container registry. According to the source code comments in lines 48‑49, these sources are considered deterministic within the context of the underlying infrastructure, though external auditing of those repositories remains the responsibility of the operator.

### How does the pin gate integrate with the repository's CI pipeline?

`verify-routing-coherence.ps1` executes as both a standalone test suite component and a pre-flight gate before routing actions. Because the script aggregates failures in a `$fail` variable and terminates with `exit 1` when violations exist, any pull request introducing unpinned auto-install capabilities triggers a CI failure, preventing merge until deterministic references are added.

### Can a capability pass validation without pinnedVersion or pinnedCommit?

Yes, depending on the `bootstrapKind`. For `github-release-zip`, providing `assetSha256` or `preferApiDigest` satisfies the requirement. For `remote-http-mcp`, a `pinPolicy` field suffices under specific repository conditions. However, generic capabilities without a special bootstrap kind must provide at least one of `pinnedVersion`, `pinnedCommit`, or `pinPolicy` to pass the gate.