## TL;DR
composer.json changed without a lockfile refresh. Run composer update --lock to re-resolve just the lockfile hash, or a full composer update if versions should move too, then commit composer.lock. CI keeps running composer install.

## Error

```text
composer 'The lock file is not up to date with the latest changes in composer.json'  -  how to fix
```

## Steps

1. Validate first: composer validate.
   Expected output: You see whether composer.json itself is well-formed.
2. Refresh the lockfile: composer update --lock.
   Expected output: composer.lock is rewritten to match composer.json without moving versions unnecessarily.
3. If versions should move with the change, run composer update [package] instead.
   Expected output: The named package updates and the lockfile records it.
4. Review the diff: git diff composer.lock.
   Expected output: The diff matches the composer.json change.
5. Commit both files; confirm CI's composer install goes green.
   Expected output: Deterministic installs from the committed lockfile.

## When to use

- composer install fails with the lock file is not up to date with the latest changes in composer.json
- Someone edited composer.json and skipped the lock step
- A merge changed composer.json without refreshing the lock

## When not to use

- composer reports the lock file does not contain a compatible set; that is a solver problem, needs a real update
- The install fails downloading; that is network, not staleness
- You are tempted to run composer update in CI; commit the lockfile instead

## Variant phrasings

### composer install warns the lock file is not up to date
The warning shape; --lock refreshes without a full re-resolve.

### Lockfile drift after editing composer.json by hand
The hand-edit shape; update --lock reconciles the pair.

### Agent edited composer.json and CI broke
Add the lock refresh to the agent's bump routine.

## Why it happens

composer.lock records a content hash of composer.json. Any edit to the manifest invalidates the hash, and composer install refuses to proceed on a lockfile that no longer describes the manifest. update --lock re-hashes and re-resolves minimally.

## Edge cases

- composer update --lock still re-resolves metadata; it is not a pure hash rewrite, so review the diff.
- If the composer.json edit was a mistake, revert it instead of re-locking around it.
- Partial updates (composer update [package]) keep the rest of the lock stable; prefer them for single bumps.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kPiNd6Mr8Yna7A5rYEYKIg