Local pass, CI fail triage route

Lockfile drift happens when the installed dependency tree no longer matches the version state the team thinks it is testing. This checklist helps developers diagnose npm and Python CI failures caused by changed locks, ignored locks, cache reuse, or mixed install commands.

## What lockfile drift looks like
The code did not change, but CI starts failing after an install. A teammate can reproduce only after deleting node_modules or the virtual environment. The lockfile changed in a branch that was not expected to touch dependencies. A package version differs between local and CI even though package.json or pyproject.toml looks unchanged. These are signs that the dependency graph, not the application code, deserves inspection.

## Check the install command
For npm projects, compare npm install, npm ci, pnpm install, and yarn install behavior. CI should usually use the command that respects the lockfile strictly. For Python, compare pip install -r requirements.txt, pip-tools output, poetry lock, uv lock, or any generated constraints file. The point is not the tool name; the point is whether CI installs the same graph the repository recorded.

## Inspect the diff
A lockfile diff can be large, but the important question is simple: which top-level dependency or resolver setting caused it? Look for package manager version changes, registry changes, optional dependencies, platform-specific packages, and transitive packages related to the failing stack trace. Do not review the entire file line by line unless the diff is small.

## Clear cache only as a test
Clearing CI cache can prove cache involvement, but it is not a root-cause fix by itself. If clearing cache fixes the failure, document what was cached and why it became stale. Then adjust cache keys or install commands so the same drift does not return.

## Keep the report actionable
A good lockfile drift note includes the failing command, install command, lockfile diff summary, package manager version, and the dependency most likely connected to the error. Avoid vague reports like "dependency issue" because they do not tell the next developer where to look.

## Practical rule
If code and tests pass locally but fail after CI install, inspect the dependency graph before rewriting application logic. The lockfile is part of the build input, not just generated noise.

Dependency lockfile drift checklist for npm and Python projects

// COMMENTS

ON THIS PAGE