Pin bundled install snippets to zero-install uvx/pipx run

adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json

@@ -10,7 +10,11 @@
       "bd4755e06715c839608c09da302ed844c764fd3e4047d7bdf495d68dc559c2a5"
     ],
     "prompts/add-shipgate-to-repo.md": [
-      "c67aa56813d76ddafd4091b2120d914fab6e0590b46e3598d856b7c4e6443fb1"
+      "c67aa56813d76ddafd4091b2120d914fab6e0590b46e3598d856b7c4e6443fb1",
+      "ea3c37cfbbd42c40d164abfe21d468a3a5550d5384125f94a53c947dea6b4b2a"
+    ],
+    "prompts/decide-shipgate-relevance.md": [
+      "9cf6fdf60f45032635482ff96c64684af5f84ef9c10977e6d36e7d1c856d07e9"
     ],
     "prompts/stabilize-strict-mode.md": [
       "ac9a176738ab2538d725c29ba302637bac6b287588e07d952aae352f85ab98cc"

adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md

@@ -9,22 +9,30 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 ## Your task
 
-1. **Install the tool** — you need `>=0.11.0`, since the `agents-shipgate verify` step this prompt relies on only ships in 0.11.0+:
+1. **Install the tool — pin the version so a stale build can't shadow it.** This flow drives `agents-shipgate verify`, which only ships in **`>=0.11.0`**; an older copy lingering on `PATH` (we have seen `0.8.0`) has no `verify` subcommand and writes no `verifier.json`, so it silently breaks the gate. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary:
    ```bash
-   pipx install agents-shipgate
-   pipx upgrade agents-shipgate
+   SG="uvx agents-shipgate@0.11.0"            # uv: ephemeral, always the pinned build
+   # or: SG="pipx run agents-shipgate==0.11.0"
+   $SG --version                             # confirm the pinned runner resolves
+   ```
+   Every step below calls `$SG …`; e.g. `$SG detect …` runs `agents-shipgate detect` through the pinned runner, never a `PATH` copy.
+
+   If you would rather install onto `PATH`, pin the floor and **fail loudly when it resolves older** — a plain `pipx install agents-shipgate` is a no-op when an older build already exists — then set `SG=agents-shipgate`:
+   ```bash
+   python -m pip install -U "agents-shipgate>=0.11.0"   # or: pipx install "agents-shipgate>=0.11.0"
+   agents-shipgate --version   # STOP if this prints < 0.11.0 — re-run pinned via uvx agents-shipgate@0.11.0
+   SG=agents-shipgate          # only after the line above confirms >=0.11.0
    ```
-   A plain `pipx install` is a no-op when an older build is already installed, so the follow-up `pipx upgrade` brings a stale copy current. If `pipx` is unavailable, use `python -m pip install -U "agents-shipgate>=0.11"` and verify with `agents-shipgate --version`.
 
 2. **Sanity-check the install** before touching the user's code:
    ```bash
-   agents-shipgate self-check --json
+   $SG self-check --json
    ```
    Confirm `"ready": true`. If not, surface the failure to the user.
 
    When available, verify the installed CLI contract locally:
    ```bash
-   agents-shipgate contract --json
+   $SG contract --json
    ```
    Read `report_schema_version`, `packet_schema_version`, `gating_signal`, and
    `manual_review_signals[]`; prefer these local values over stale docs. If the
@@ -34,15 +42,15 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 3. **Detect:**
    ```bash
-   agents-shipgate detect --workspace . --json
+   $SG detect --workspace . --json
    ```
    Read the response: `is_agent_project`, `frameworks[]` (per-framework score + evidence + candidate files), `agent_name_candidates[]`, `suggested_sources[]` (MCP/OpenAPI files matched by glob).
 
    **Stop only when ALL of these hold:** `is_agent_project: false`, `suggested_sources` is empty, `codex_plugin_candidates` is empty, no `shipgate.yaml` already exists in the workspace, AND the user did not explicitly request a scan. Otherwise proceed — MCP/OpenAPI tool-surface repos and Codex plugin package repos register as `is_agent_project: false` because they have no Python framework imports, but they are valid Shipgate targets. MCP/OpenAPI hits surface as `suggested_sources`; Codex plugin hits surface as `codex_plugin_candidates`.
 
 4. **Generate a starter manifest + GitHub Actions workflow:**
    ```bash
-   agents-shipgate init --workspace . --write --ci --json
+   $SG init --workspace . --write --ci --json
    ```
    The `--json` form returns:
    - `manifest_status`: `"written"` | `"skipped_existing"` | `"not_attempted"`
@@ -60,7 +68,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 6. **Run the scan with patch suggestions:**
    ```bash
-   agents-shipgate scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
+   $SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
    ```
    The report lands at `agents-shipgate-reports/report.json`. The Release Evidence Packet lands at `agents-shipgate-reports/packet.{md,json,html}`. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
 
@@ -80,7 +88,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 7. **Apply the safe patches:**
    ```bash
-   agents-shipgate apply-patches --from agents-shipgate-reports/report.json --confidence high --apply --json
+   $SG apply-patches --from agents-shipgate-reports/report.json --confidence high --apply --json
    ```
    Default `--confidence high` only mutates patches whose `confidence` field is `"high"`. Today that's the 3 stale-manifest removals. Scope-coverage appends ship at `medium` and require explicit `--confidence medium` to apply. ManualPatches are never auto-applied.
 
@@ -106,25 +114,25 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
    - The path to the Release Evidence Packet (`agents-shipgate-reports/packet.md`) for reviewer-shaped output
    - The top 3 active critical/high findings (use `report.json`, not stdout)
    - Which patches were applied (count from `apply-patches --json` output's `files`)
-   - Any check IDs the user should investigate first — link to `docs_url` from the finding for full rationale, or use `agents-shipgate explain <CHECK_ID> --json` for the same content via CLI
+   - Any check IDs the user should investigate first — link to `docs_url` from the finding for full rationale, or use `$SG explain <CHECK_ID> --json` for the same content via CLI
 
 ## What to do if the scan errors out
 
-Set `AGENTS_SHIPGATE_AGENT_MODE=1` and re-run. The CLI will append a JSON line to stderr with `{error, message, next_action}`. Follow the `next_action`.
+Re-run the failing `$SG …` command with `AGENTS_SHIPGATE_AGENT_MODE=1` set. The CLI will append a JSON line to stderr with `{error, message, next_action}`. Follow the `next_action`.
 
 Common errors and fixes:
 
 | Error | Fix |
 |---|---|
-| `Config file not found: shipgate.yaml` | Run `agents-shipgate init --workspace . --write` first |
+| `Config file not found: shipgate.yaml` | Run `$SG init --workspace . --write` first |
 | `Input path '...' resolves outside manifest directory` | The declared `tool_sources[].path` is outside the manifest dir. Move the spec inside the tree, symlink it, or copy it |
 | `Invalid shipgate.yaml: ... Did you mean X?` | A field is at the wrong nesting level; move it as suggested |
 | `Containment violation` (apply-patches exit 5) | A patch's `target_file` resolved outside `report.manifest_dir`. Re-run scan to refresh; never patch arbitrary system files |
 
 ## What NOT to do
 
 - Do **not** commit `agents-shipgate-reports/` — it's regenerated each run.
-- Do **not** run `agents-shipgate baseline save` until the user has reviewed the initial findings. Baselining ratchets in noise that strict CI will silently ignore. The right time to baseline is **after** the user has decided which findings they accept.
+- Do **not** run `$SG baseline save` until the user has reviewed the initial findings. Baselining ratchets in noise that strict CI will silently ignore. The right time to baseline is **after** the user has decided which findings they accept.
 - Do **not** suppress findings without a real `reason` — the manifest validator rejects empty reasons, and the `reason` field is the audit trail when someone asks "why is this OK?"
 - Do **not** use `risk_overrides.tools.{tool}.remove_tags` to silence a finding without checking whether the heuristic is actually wrong. Prefer `checks.ignore` with a reason.
 - Do **not** edit a trace recording to flip `approved` or `confirmed` — implement the runtime gate instead.

adoption-kits/claude-code-skill/prompts/decide-shipgate-relevance.md

@@ -69,16 +69,15 @@ the rules to the changed file list.
    ```
 
 5. **Then act.**
-   - If `run_shipgate: true` and Shipgate is installed:
-     ```bash
-     agents-shipgate detect --workspace . --json
-     ```
-     Then follow [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md)
-     for the first-adoption helper flow.
-   - If `run_shipgate: true` and Shipgate is **not** installed: install
-     it (`pipx install agents-shipgate`) and run `detect`. If the user
-     prefers a zero-install first step, point them at the GitHub Action
-     (`ThreeMoonsLab/agents-shipgate@v0.11.0`) instead.
+   - If `run_shipgate: true`: run `detect` through a **version-pinned,
+     zero-install** runner so a stale copy already on `PATH` can't answer —
+     `uvx agents-shipgate@0.11.0 detect --workspace . --json` (or
+     `pipx run agents-shipgate==0.11.0 …`). Only fall back to a bare
+     `agents-shipgate detect` once `agents-shipgate --version` confirms
+     `>=0.11.0`. Then follow
+     [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md)
+     for the first-adoption helper flow, or point the user at the GitHub
+     Action (`ThreeMoonsLab/agents-shipgate@v0.11.0`) if they prefer CI.
    - If `run_shipgate: false` and `dry_run_recommended: true`: propose
      a non-mutating scan only — never propose `init --write` based on a
      dry-run match alone. Phrase it as "X may have shifted the tool

prompts/add-shipgate-to-repo.md

@@ -9,22 +9,30 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 ## Your task
 
-1. **Install the tool** — you need `>=0.11.0`, since the `agents-shipgate verify` step this prompt relies on only ships in 0.11.0+:
+1. **Install the tool — pin the version so a stale build can't shadow it.** This flow drives `agents-shipgate verify`, which only ships in **`>=0.11.0`**; an older copy lingering on `PATH` (we have seen `0.8.0`) has no `verify` subcommand and writes no `verifier.json`, so it silently breaks the gate. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary:
    ```bash
-   pipx install agents-shipgate
-   pipx upgrade agents-shipgate
+   SG="uvx agents-shipgate@0.11.0"            # uv: ephemeral, always the pinned build
+   # or: SG="pipx run agents-shipgate==0.11.0"
+   $SG --version                             # confirm the pinned runner resolves
+   ```
+   Every step below calls `$SG …`; e.g. `$SG detect …` runs `agents-shipgate detect` through the pinned runner, never a `PATH` copy.
+
+   If you would rather install onto `PATH`, pin the floor and **fail loudly when it resolves older** — a plain `pipx install agents-shipgate` is a no-op when an older build already exists — then set `SG=agents-shipgate`:
+   ```bash
+   python -m pip install -U "agents-shipgate>=0.11.0"   # or: pipx install "agents-shipgate>=0.11.0"
+   agents-shipgate --version   # STOP if this prints < 0.11.0 — re-run pinned via uvx agents-shipgate@0.11.0
+   SG=agents-shipgate          # only after the line above confirms >=0.11.0
    ```
-   A plain `pipx install` is a no-op when an older build is already installed, so the follow-up `pipx upgrade` brings a stale copy current. If `pipx` is unavailable, use `python -m pip install -U "agents-shipgate>=0.11"` and verify with `agents-shipgate --version`.
 
 2. **Sanity-check the install** before touching the user's code:
    ```bash
-   agents-shipgate self-check --json
+   $SG self-check --json
    ```
    Confirm `"ready": true`. If not, surface the failure to the user.
 
    When available, verify the installed CLI contract locally:
    ```bash
-   agents-shipgate contract --json
+   $SG contract --json
    ```
    Read `report_schema_version`, `packet_schema_version`, `gating_signal`, and
    `manual_review_signals[]`; prefer these local values over stale docs. If the
@@ -34,15 +42,15 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 3. **Detect:**
    ```bash
-   agents-shipgate detect --workspace . --json
+   $SG detect --workspace . --json
    ```
    Read the response: `is_agent_project`, `frameworks[]` (per-framework score + evidence + candidate files), `agent_name_candidates[]`, `suggested_sources[]` (MCP/OpenAPI files matched by glob).
 
    **Stop only when ALL of these hold:** `is_agent_project: false`, `suggested_sources` is empty, `codex_plugin_candidates` is empty, no `shipgate.yaml` already exists in the workspace, AND the user did not explicitly request a scan. Otherwise proceed — MCP/OpenAPI tool-surface repos and Codex plugin package repos register as `is_agent_project: false` because they have no Python framework imports, but they are valid Shipgate targets. MCP/OpenAPI hits surface as `suggested_sources`; Codex plugin hits surface as `codex_plugin_candidates`.
 
 4. **Generate a starter manifest + GitHub Actions workflow:**
    ```bash
-   agents-shipgate init --workspace . --write --ci --json
+   $SG init --workspace . --write --ci --json
    ```
    The `--json` form returns:
    - `manifest_status`: `"written"` | `"skipped_existing"` | `"not_attempted"`
@@ -60,7 +68,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 6. **Run the scan with patch suggestions:**
    ```bash
-   agents-shipgate scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
+   $SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
    ```
    The report lands at `agents-shipgate-reports/report.json`. The Release Evidence Packet lands at `agents-shipgate-reports/packet.{md,json,html}`. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
 
@@ -80,7 +88,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
 
 7. **Apply the safe patches:**
    ```bash
-   agents-shipgate apply-patches --from agents-shipgate-reports/report.json --confidence high --apply --json
+   $SG apply-patches --from agents-shipgate-reports/report.json --confidence high --apply --json
    ```
    Default `--confidence high` only mutates patches whose `confidence` field is `"high"`. Today that's the 3 stale-manifest removals. Scope-coverage appends ship at `medium` and require explicit `--confidence medium` to apply. ManualPatches are never auto-applied.
 
@@ -106,25 +114,25 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
    - The path to the Release Evidence Packet (`agents-shipgate-reports/packet.md`) for reviewer-shaped output
    - The top 3 active critical/high findings (use `report.json`, not stdout)
    - Which patches were applied (count from `apply-patches --json` output's `files`)
-   - Any check IDs the user should investigate first — link to `docs_url` from the finding for full rationale, or use `agents-shipgate explain <CHECK_ID> --json` for the same content via CLI
+   - Any check IDs the user should investigate first — link to `docs_url` from the finding for full rationale, or use `$SG explain <CHECK_ID> --json` for the same content via CLI
 
 ## What to do if the scan errors out
 
-Set `AGENTS_SHIPGATE_AGENT_MODE=1` and re-run. The CLI will append a JSON line to stderr with `{error, message, next_action}`. Follow the `next_action`.
+Re-run the failing `$SG …` command with `AGENTS_SHIPGATE_AGENT_MODE=1` set. The CLI will append a JSON line to stderr with `{error, message, next_action}`. Follow the `next_action`.
 
 Common errors and fixes:
 
 | Error | Fix |
 |---|---|
-| `Config file not found: shipgate.yaml` | Run `agents-shipgate init --workspace . --write` first |
+| `Config file not found: shipgate.yaml` | Run `$SG init --workspace . --write` first |
 | `Input path '...' resolves outside manifest directory` | The declared `tool_sources[].path` is outside the manifest dir. Move the spec inside the tree, symlink it, or copy it |
 | `Invalid shipgate.yaml: ... Did you mean X?` | A field is at the wrong nesting level; move it as suggested |
 | `Containment violation` (apply-patches exit 5) | A patch's `target_file` resolved outside `report.manifest_dir`. Re-run scan to refresh; never patch arbitrary system files |
 
 ## What NOT to do
 
 - Do **not** commit `agents-shipgate-reports/` — it's regenerated each run.
-- Do **not** run `agents-shipgate baseline save` until the user has reviewed the initial findings. Baselining ratchets in noise that strict CI will silently ignore. The right time to baseline is **after** the user has decided which findings they accept.
+- Do **not** run `$SG baseline save` until the user has reviewed the initial findings. Baselining ratchets in noise that strict CI will silently ignore. The right time to baseline is **after** the user has decided which findings they accept.
 - Do **not** suppress findings without a real `reason` — the manifest validator rejects empty reasons, and the `reason` field is the audit trail when someone asks "why is this OK?"
 - Do **not** use `risk_overrides.tools.{tool}.remove_tags` to silence a finding without checking whether the heuristic is actually wrong. Prefer `checks.ignore` with a reason.
 - Do **not** edit a trace recording to flip `approved` or `confirmed` — implement the runtime gate instead.

prompts/decide-shipgate-relevance.md

@@ -69,16 +69,15 @@ the rules to the changed file list.
    ```
 
 5. **Then act.**
-   - If `run_shipgate: true` and Shipgate is installed:
-     ```bash
-     agents-shipgate detect --workspace . --json
-     ```
-     Then follow [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md)
-     for the first-adoption helper flow.
-   - If `run_shipgate: true` and Shipgate is **not** installed: install
-     it (`pipx install agents-shipgate`) and run `detect`. If the user
-     prefers a zero-install first step, point them at the GitHub Action
-     (`ThreeMoonsLab/agents-shipgate@v0.11.0`) instead.
+   - If `run_shipgate: true`: run `detect` through a **version-pinned,
+     zero-install** runner so a stale copy already on `PATH` can't answer —
+     `uvx agents-shipgate@0.11.0 detect --workspace . --json` (or
+     `pipx run agents-shipgate==0.11.0 …`). Only fall back to a bare
+     `agents-shipgate detect` once `agents-shipgate --version` confirms
+     `>=0.11.0`. Then follow
+     [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md)
+     for the first-adoption helper flow, or point the user at the GitHub
+     Action (`ThreeMoonsLab/agents-shipgate@v0.11.0`) if they prefer CI.
    - If `run_shipgate: false` and `dry_run_recommended: true`: propose
      a non-mutating scan only — never propose `init --write` based on a
      dry-run match alone. Phrase it as "X may have shifted the tool