agentleFS
verivus-ossverivus-oss/llm-cli-gateway/.claude/skills/supply-chain-guard/SKILL.md

supply-chain-guard

Skill16 starsChanged 2 months agoMITView on GitHub

Resolve prod-closure dependency drift safely and catch tag-along dependencies. Reproduces the release-gate scan (supply-chain:scan:check), classifies each path-keyed prod INSTANCE as clean / roll-forward / tag-along / source-anomaly / integrity-mismatch / dropped against a committed ledger + baseline, researches advisories with exa, gets independent cross-LLM validation, and writes per-dependency contracts before any ledger change. Use when release-security-audit.sh fails with a supply-chain verdict (exit 2 or 3), to sweep drift before cutting a release, or to audit whether a new package slipped into the prod tree.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Not every drift is equal. A roll-forward (a ledgered name at a new accepted version) is low-risk but still blocks the exit-0 gate until the …

    line 26
  2. Very specific:

    Read report.md under .supply-chain/scan-<ts>/.

    line 48
  3. Distinctive:

    Use exa as a search/research aid, not as the authority.

    line 57
  4. Very specific:

    Before any ledger change, call provider_tool_capabilities for each selected reviewer and confirm that its configured native tools can reach …

    line 80
  5. Very specific:

    Use Codex's read-only sandbox for inspection.

    line 88
  6. Very specific:

    Do not impose a review-round, turn, token, price, budget, or wallclock cap.

    line 94
  7. Very specific:

    When the user explicitly grants full provider permissions and native MCP access for this validation, follow the canonical multi-llm-review …

    line 106

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/supply-chain-guard

Canonical process: docs/development/supply-chain-guard/RUNBOOK.md. Read it once at the start of any session that uses this skill; everything below is a condensed walkthrough and the runbook is the source of truth. Spec: docs/plans/supply-chain-guard.draft.md.

The problem this solves

The release gate is blocklist + invariants (npm audit, osv-scanner, the version blocklist, socket.yml) with no name/instance allowlist, so a new transitive package with no CVE enters the prod closure silently. This guard adds the allowlist layer: a committed ledger (supply-chain/prod-closure.ledger.json, per-name exact acceptedVersions) + instance baseline (prod-closure.baseline.json), and a scanner that fails the release when the shipped closure diverges from the reviewed baseline.

Not every drift is equal. A roll-forward (a ledgered name at a new accepted version) is low-risk but still blocks the exit-0 gate until the baseline is refreshed. A tag-along (a name not in the ledger, an unaccepted version, or a name absent from the baseline) needs a real review. Never rubber-stamp a tag-along.

When to invoke

  • npm run security:audit / CI failed with [supply-chain-guard] verdict exit 2|3.
  • You want to sweep drift before cutting a release.
  • You want to confirm no new package slipped into the prod tree.

Stages, and your responsibilities

1. Scan

npm run supply-chain:scan          # local/advisory (temp-copy fresh resolve; tolerates exit 2)
# or reproduce the gate exactly:
npm run supply-chain:scan:check    # --frozen, requires exit 0 (what CI runs)

Read report.md under .supply-chain/scan-<ts>/. Exit 0 clean, 2 roll-forward/dropped, 3 tag-along / source anomaly / integrity mismatch / reused-invariant failure (forbidden native-tar chain, blocked version, fetch-in-dist) / P2 license-violation (non-allowlisted or missing SPDX license) / P2 socket-policy-drift (a socket.yml issueRule changed from its reviewed value), 1 tool error. If clean, stop; otherwise triage every flagged row.

2. Research each actionable package

Use exa as a search/research aid, not as the authority. Verify current package facts against the npm registry/package publisher, GHSA/OSV advisory records, and the relevant vendor changelog or repository. osv-scanner pre-screens known advisories but does not replace that research. For each drifted package, record the latest npm version and advisories; for a roll-forward, compare the changelog baseline to resolved version; for a tag-along, run npm ls <pkg>, inspect the license, and perform a first-time trust review.

3. Decide + fill the contract

Fill each generated contracts/<pkg>.md: safe-to-upgrade: YES/NO + rationale; run npm run build && npm test && npm run security:audit and record each command result separately from the reviewer verdict.

4. Cross-LLM validation (mandatory, independent)

Dispatch only through the installed local stdio gtwy MCP surface (mcp__gtwy__* or the client-rendered equivalent), never a direct provider binary, SDK, connector/shadow gateway, or shell fallback. The supply-chain runbook's explicit selected roster is Codex, Grok, and Mistral. It is a purpose-specific minimum, not a claim that those three are a universal seven-provider review.

Before any ledger change, call provider_tool_capabilities for each selected reviewer and confirm that its configured native tools can reach the required research sources. Then create an independent session for each selected reviewer and require it to verify the classification and safe-to-upgrade call against npm, advisory databases, and changelogs, not merely the summary. If a reviewer cannot access a required source, preserve that research gap, repair the configuration or provide independently verifiable source provenance, and keep the validation incomplete until it can return an evidence-backed verdict. Use Codex's read-only sandbox for inspection; Mistral's programmatic legacy default is permissionMode:"accept-edits", so retain an explicit no-mutation instruction; and use only Grok controls confirmed by provider_tool_capabilities. All three use approvalStrategy:"legacy" and omit approvalPolicy: mcp_managed is Claude-only.

Do not impose a review-round, turn, token, price, budget, or wallclock cap. A tag-along requires APPROVED_UNCONDITIONALLY from every reviewer in the selected roster. Every review prompt must require exactly one terminal JSON verdict: APPROVED_UNCONDITIONALLY, CHANGES_REQUIRED, or BLOCKED_EXTERNAL. A conditional, malformed, timed-out, or unavailable reviewer makes the validation incomplete: repair/retry it or hold the ledger change and report BLOCKED_EXTERNAL with its exact error. Record each verdict and job ID in the contract. CHANGES_REQUIRED must contain independent source evidence and cannot be treated as approval.

Explicit user-authorized full-access review

When the user explicitly grants full provider permissions and native MCP access for this validation, follow the canonical multi-llm-review full-access protocol. Build the target checkout and start a fresh local node dist/index.js --transport=stdio process from it; do not use a globally installed or stale gateway. Reapply provider-native full-access controls on every new job, preserve ambient native MCP configuration, and do not construct a pretend gateway allowlist.

Give each reviewer the verification report as a corrective-program specification, exact base and diff or exhaustive changed-file list, relevant untracked files, and durable raw evidence. Require independent verification of the repository, package metadata, registry data, advisories, changelogs, docs, tests, commands, and available MCP facts. A reviewer must not approve from the report alone. A disagreement needs code, package, advisory, documentation, test, or command evidence, not assertion. Retain the purpose-specific Codex, Grok, and Mistral roster only when the user explicitly scopes this supply-chain gate to it; otherwise the canonical exhaustive protocol requires all seven CLI providers. Do not set caller review caps. On a user-required 90-second cadence, make non-blocking progress checks no more frequently than every 90 seconds.

5. Write the ledger + refresh the baseline

Append the newly accepted EXACT version to that name's acceptedVersions (never a range: exit 1). For a dropped name, state: "revoked" once all instances are gone. Regenerate the baseline so it matches the tree the next release ships; that is what turns exit 2 into exit 0.

6. Ledger audit trail

Copy the filled contracts to docs/development/supply-chain-guard/ledger/<YYYY-MM-DD>/<pkg>.md, commit with the ledger change, land on master via PR (build(supply-chain): / fix(supply-chain):).

Anti-patterns to refuse

  • Rubber-stamping a tag-along (full review plus explicit APPROVED_UNCONDITIONALLY from the required roster, or out).
  • Skipping the advisory sweep "because it's just a patch."
  • Writing a ledger change before cross-LLM validation (steps 2 to 4 first).
  • Accepting a reviewer verdict without cited evidence.
  • Deleting ledger entries to "clean up" (only prune dropped after revoked).
  • Treating a local fresh-resolve sweep as the authoritative gate (the gate is --frozen); accepting a roll-forward without refreshing the baseline.

Quick links

  • Runbook: docs/development/supply-chain-guard/RUNBOOK.md
  • Tool: scripts/supply-chain/dep-drift-scan.mjs (tests: dep-drift-scan.test.mjs)
  • Ledger + baseline: supply-chain/prod-closure.{ledger,baseline}.json
  • Release gate: scripts/release-security-audit.sh
  • Proactive upgrades: Dependabot (.github/dependabot.yml)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.