A lockfile policy that stops agent churn

Agents love 'fixing' installs by regenerating the lockfile, and every regeneration is a 3,000-line diff nobody reviews. Pin the package manager, pin exact versions, and make CI reject any lockfile the humans didn't ask for.

Expected result

Agents install with the committed lockfile every time, dependency changes only happen when explicitly requested, and CI fails any PR where the lockfile changed without a corresponding package.json change.

Difficulty

Beginner

Estimated time

~20 min

Version notes

Works with npm 10 (npm ci), pnpm 9 (--frozen-lockfile), yarn 4 (--immutable). Bun users: bun install --frozen-lockfile since 1.0.

1. 01Node 18+ with corepack available
2. 02One package manager you're willing to commit to
3. 03CI where you can add a small check step

01

Declare the package manager so agents can't guess

Half of lockfile churn starts with an agent picking the wrong tool (npm in a pnpm repo) because nothing told it otherwise. The packageManager field plus corepack makes the choice mechanical.

corepack enable
npm pkg set packageManager="pnpm@9.15.0"

Copy

02

Pin exact versions on save

Caret ranges are how a lockfile regeneration turns into 40 silent minor bumps. Save-exact means an agent adding one dependency changes one line.

npm config set save-exact true --location=project

Copy

03

Make frozen installs the only install

The install command agents reach for must refuse to mutate the lockfile. pnpm and yarn have frozen modes; npm's is npm ci. Put the right one in your AGENTS.md as THE install command.

# AGENTS.md excerpt
## Installing dependencies
- Install: `pnpm install --frozen-lockfile`
- NEVER run a bare install after changing package.json without being asked.
- NEVER edit pnpm-lock.yaml by hand or regenerate it to 'fix' an error.
- If install fails, STOP and report the error instead of changing the lockfile.

! Common failures

Agent still runs npm install in a pnpm repo

Add a preinstall guard: "preinstall": "npx only-allow pnpm" in package.json scripts. It fails fast with a clear message the agent actually reads and obeys.

Frozen install fails after a legitimate package.json edit and the agent starts thrashing

That's the designed stop-point. The AGENTS.md line 'STOP and report' matters — with it, agents ask; without it, they regenerate. If asked, the human runs the unfrozen install once, reviews the delta, commits.

CI tripwire fires on legitimate transitive security bumps

Those PRs should touch package.json (overrides field) anyway. If you truly want lockfile-only bumps, restrict them to a bot-labeled branch pattern excluded from the check.