dependency_pinning v1.0.0

name: "dependency_pinning" description: "Lock dependency versions so builds are reproducible and supply-chain safe: lockfile discipline per ecosystem (npm/pip/Go/Rust/Ruby), exact-pin policy for direct vs transitive deps, scheduled audit cadence, upgrade runbooks, and vendoring fallbacks when a registry goes down. Triggers when a project lacks a lockfile, deps drift between environments, upgrades break builds, or a CI pipeline installs at build time."

Dependency Pinning

Purpose

Make every build install the exact same code, in every environment, every time. That means a committed lockfile, installs that refuse to resolve at build time, a policy for how tight each pin is, a cadence for getting off old versions, and a plan for the day the registry is unreachable.

Workflow

1. Inventory. Run bin/dep-pinning-check.py against the repo root. It flags: missing lockfiles, unpinned or ranged requirements in manifests, CI jobs that resolve instead of installing from a lock, and tag-pinned GitHub Actions.
2. Lock. For each ecosystem present, establish the lockfile per references/ecosystem-lockfiles.md and commit it. A lockfile only protects you if CI installs from it, so fix the CI install step in the same change.
3. Set the pin policy. Manifest (package.json, pyproject.toml, go.mod, Cargo.toml) = intent: direct deps with the narrowest range the team can live with. Lockfile = truth: exact versions, every transitive dep, ideally with hashes. Binaries and deployed services lean toward exact pins everywhere; libraries lean toward caret/compatible ranges in the manifest so downstream resolvers keep room to move.
4. Schedule the grind. Weekly automated update PRs (Dependabot or Renovate), a weekly audit run, and a monthly lockfile review. Details and configs in references/audit-and-upgrade-runbook.md.
5. Plan the outage. Stand up at least one registry fallback before you need it: vendored deps, a local mirror, or a proxy cache. Options in references/registry-fallback.md.
6. Verify. Re-run the check script. npm ci-style commands must fail loudly when the lock is stale; that failure is the feature.

Output Contract

When this skill is used to set up or fix a repo's dependency discipline, the result includes:

• A committed lockfile for every ecosystem in the repo.
• CI that installs strictly from the lockfile (frozen/ci/deploy flags), verified to fail when lock and manifest disagree.
• A written pin policy (direct vs transitive, app vs library) the team can point at in review.
• A scheduled audit + update bot config, and a registry-fallback plan for deploys.

Operating Rules

1. Two files, two jobs. The manifest declares intent (ranges allowed). The lockfile records reality (exact, hashes where the ecosystem supports them). Never resolve versions at deploy time.
2. Lockfiles are committed. No lockfile in .gitignore. Review lockfile diffs in PRs the way you review code: a lockfile-only PR with no manifest change is worth a second look.
3. Pin for binaries, range for libraries. Deployed services and binaries get exact pins for predictability. Published libraries use compatible ranges in the manifest so consumers are not boxed in.
4. *latest and never ship. Forbidden in committed manifests. Same for branch names in submodules and moving tags in CI workflows; use commit SHAs.
5. Audit on a cadence, patch on an alert. Weekly scans find rot; known advisories get patched immediately, out of band. CI gates on severity: no merging over unresolved High/Critical in the ecosystems the team ships.
6. Upgrade small, never stale. Patch/minor upgrades ride automated PRs. Major upgrades get one PR each, changelog read first, never bundled. Letting the gap grow until the upgrade is a rewrite is the failure mode this discipline exists to prevent.
7. Own the transitive tree. A vulnerability in a transitive dep gets pinned around it (npm overrides, yarn resolutions, Go version bump) when the direct parent will not move fast enough.
8. The registry will be down someday.** Vendoring, mirrors, or offline caches are a deploy requirement, not a nice-to-have. A build that needs the public registry at 3am during an outage is a build you did not finish.

Tooling

bin/dep-pinning-check.py — read-only repo scanner. Run it from the repo root:

bash
python3 ~/workspace/skills/dependency-pinning/bin/dep-pinning-check.py [path]

Exit 0 means the pinning discipline is healthy; non-zero lists findings with severity (error/warn). It never modifies anything. See the header comment for the full check list.