stocktake

name	stocktake
license	MIT
description	Use when auditing, updating, or migrating project dependencies, runtimes, package managers, lockfiles, or toolchains. Requires reading authoritative release and migration notes, changing one compatibility boundary at a time, and verifying the resolved dependency graph.

stocktake

A stocktake records what the project actually uses before changing what it orders. Dependency work starts from manifests, resolved versions, runtime pins, generated clients, and CI configuration. The requested version is only one line in that inventory.

Modes

• AUDIT reports outdated, unsupported, vulnerable, duplicated, or unused dependencies without changing the repository.
• UPDATE applies a requested version change or an accepted audit finding.
• MIGRATE handles a major version, runtime, package manager, or toolchain boundary with required source and configuration changes.

If the user asks only for an audit, stop after the backlog. Do not turn discovery into a lockfile rewrite.

1. Define the boundary

Pin the scope before running an updater:

• named package, runtime, toolchain, or manifest
• requested target version or allowed version range
• applications and libraries affected
• compatibility floors that must remain supported
• whether security remediation changes the priority

Split unrelated major upgrades. A runtime migration, framework major, and package-manager change are separate compatibility boundaries even when one command can update all three.

2. Inventory resolved state

Read every source that can select or constrain a version:

• package manifests and workspace roots
• lockfiles, checksums, and vendored dependency records
• runtime and toolchain pins
• CI actions, build images, containers, and deployment configuration
• generated clients, code generators, plugins, and peer dependencies
• repository instructions that prescribe supported versions

Record direct and transitive versions using the ecosystem's supported inspection command. Do not infer the resolved graph from a manifest range.

3. Establish the baseline

Run the project's documented checks before editing. Capture:

• install or dependency-resolution result
• focused tests for the affected subsystem
• full test or build result when practical
• relevant warnings and deprecation messages

A red baseline does not automatically block an urgent security update, but it must be reported and separated from new failures.

4. Read authoritative change notes

Use primary sources for the exact versions crossing the boundary:

• release notes and migration guides from the maintainer
• official runtime or package-manager compatibility tables
• security advisory and fixed-version record when relevant
• deprecation and removal notes for APIs used by this repository

Write down required migrations before changing declarations. A version solver reaching green does not prove the source still follows the supported contract.

5. Make the smallest safe batch

1. Change one compatibility boundary.
2. Regenerate the lockfile or resolved graph with the official package-manager command. Never hand-edit generated resolution data.
3. Inspect direct and transitive deltas. Explain unexpected additions, removals, source changes, and large version jumps.
4. Update source and configuration only for documented compatibility changes or errors reproduced locally.
5. Keep unrelated formatting, cleanup, and opportunistic upgrades out of the diff.

Patch and minor updates may travel together when they share the same manifest, compatibility surface, and verification command. Major versions do not.

6. Verify

Run, in order:

1. dependency installation or resolution from a clean-enough state
2. the affected package's focused tests or build
3. static analysis, type checks, or compilation that exercises changed APIs
4. the full project check used for the baseline
5. the ecosystem command that prints the final resolved graph

For security work, confirm the vulnerable resolved version is absent. For runtime or toolchain work, confirm CI and deployment pins match local configuration.

Use check before reporting the update as complete. Include the old and new resolved versions plus the commands that prove them.

Audit report

# stocktake: <scope> (<date>)
Mode: AUDIT | UPDATE | MIGRATE

## Boundary
- Current resolved version:
- Target version:
- Compatibility floor:

## Required migrations
- Source and configuration changes from authoritative notes

## Dependency delta
- Direct changes
- Material transitive changes

## Verification
- Baseline command and result
- Updated command and result
- Final resolved version evidence

## Deferred
- Breaking or unrelated upgrades left for separate work

Stop conditions

Stop and ask when:

• the target version changes a public compatibility floor the user did not approve
• authoritative notes require a data migration, deployment sequence, or destructive regeneration
• two lockfiles or package managers disagree about ownership of the same dependency set
• the upgrade requires credentials, paid registries, or production-only systems unavailable in the session
• the smallest safe batch still crosses multiple major boundaries

Common mistakes

• Updating the manifest and never checking the resolved version.
• Running a broad update command for one requested package and accepting every lockfile change.
• Trusting third-party summaries over the maintainer's migration guide.
• Claiming a vulnerability is fixed while the old transitive version remains in the lockfile.
• Combining runtime, framework, and package-manager majors in one diff.
• Hand-editing a generated lockfile to make the diff look smaller.