Dependency Discipline

Every dependency is code you now ship, maintained by strangers, on their schedule, with your name on the incident. npm install is the easiest way to adopt a liability while feeling productive. The discipline: adopt deliberately, pin exactly, upgrade continuously, and keep the exits marked.

Gate 1: Before adding — the adoption review

First question: can 30 lines of your own code do this? For anything smaller than a real domain (left-pad-class utilities, one date format, a simple retry), writing it beats importing it — your 30 lines have no transitive tree, no CVE feed, no maintainer burnout. Import for genuine domains: crypto (NEVER hand-roll — threat-model-security), parsers for messy formats, timezone data, database drivers, frameworks.

If importing, spend five deliberate minutes:

• Aliveness: commits/releases in the last year, issues getting answers, more than one maintainer (bus factor). A dead dependency is a fork you haven't admitted to yet.
• Weight: what does it drag in transitively? (npm ls, dependency graph). A 3-line convenience with 40 transitive deps is a bad trade; prefer libraries with shallow trees.
• Blast radius when it breaks: dev-only tool (low bar) vs runtime-critical path vs touches-money-or-auth (high bar: popularity, audit history, and your own reading of its core code).
• License compatible with your use (GPL in a proprietary SaaS backend is usually fine; in distributed code it's a legal meeting).
• Exit cost: how hard to replace later? High-exit-cost deps (frameworks, ORMs) deserve real evaluation; for the rest, keep them behind your own adapter so the exit stays cheap (architecture-design).

Gate 2: Pinning — builds must not drift

• Lockfiles committed, always, and honored in CI/production installs (npm ci, pip install -r requirements.txt with pins, poetry.lock, cargo.lock). An unlocked build means yesterday's green and today's deploy are different software (deployment-safety Gate 1).
• Docker base images by specific tag (ideally digest), never latest. Same for GitHub Actions (@v4 minimum; SHA-pin for anything with secrets access).
• The rule: a rebuild with no code change produces the same artifact. Any violation of that is a drift channel; close it.

Gate 3: Upgrading — small, often, boring

The counterintuitive truth: teams that upgrade more often have fewer upgrade disasters. Staying two majors behind doesn't avoid the migration; it batches it into a death march with security pressure attached.

• Cadence: patch/minor updates in a regular small batch (monthly, or automated via Renovate/Dependabot with CI gating); major versions individually, deliberately, reading the changelog/migration guide first.
• One dependency (or one coherent batch) per PR, tests green, deployed normally — so when something breaks, git bisect has one suspect (root-cause-debugging: "find what changed").
• Read the changelog before upgrading, not after the incident. Breaking changes announce themselves; nobody listens.
• Framework/language runtime upgrades are projects, not chores: branch, upgrade, run the full suite + golden-path verification, then merge — not "bump it and see".

Gate 4: Vulnerability response — triage, don't panic

Scanner alerts (Dependabot/npm audit/pip-audit) are inputs, not verdicts. Triage each:

1. Is the vulnerable path reachable in your usage? A ReDoS in a dev-only build tool ≠ an RCE in your request parser. Severity × reachability = your actual priority.
2. Reachable + serious → patch now via the smallest jump that fixes it, deploy through the normal (fast) pipeline.
3. Not reachable → note the reasoning, schedule with the regular batch. Suppressing alerts silently trains everyone to ignore the channel (observability-readiness's alert-fatigue rule applies).
4. No fix released? Mitigate (disable the feature, input-validate ahead of it, vendor-patch as last resort) and track the upstream issue.

Supply-chain paranoia (the part everyone skips until it's news)

• New-package hygiene: check the exact name (typosquats live on one-letter differences), the publish date vs popularity (a "popular" package published last week is a flag), and whether install scripts run (--ignore-scripts where feasible).
• CI is the crown jewel: it holds your secrets and builds your artifacts. Third-party CI actions/plugins get the same adoption review as runtime deps, pinned by SHA.
• Your registry account (npm/PyPI) with publish rights gets 2FA — you're someone else's supply chain too.
• Periodic pruning: every dependency audit removes something. Unused deps are pure attack surface; depcheck/pip-extra-reqs-class tools find them.

The ledger

Keep the why of non-obvious dependencies findable (ADR line, lockfile comment, or docs): "we use X over the popular Y because Z". Six months later, someone (or some AI) will "simplify" by swapping it back, rediscovering Z in production (docs-and-runbooks).