git:20260922.e4ae97c to git:20260922.28cefc1

31 added, 9 removed. Audit A to A.

---

name: arch-upgrade-deps

description: "Upgrade every dependency of the repository to its latest stable or LTS release (runtimes, tools, images, CI, Terraform, libraries), then run the gates and hold back what breaks."

- allowed-tools: Read, Grep, Glob, Edit, WebFetch, Bash(make check), Bash(make infra-reset), Bash(make infra-up), Bash(make migrate), Bash(make migrate-check), Bash(make test-integration), Bash(uv lock:*), Bash(uv sync:*), Bash(uv tree:*), Bash(pnpm update:*), Bash(pnpm install:*), Bash(pnpm view:*), Bash(pnpm outdated:*), Bash(git status:*)

+ allowed-tools: Read, Grep, Glob, Edit, WebFetch, Bash(make check), Bash(make infra-reset), Bash(make infra-up), Bash(make migrate), Bash(make migrate-check), Bash(make test-integration), Bash(uv lock:*), Bash(uv sync:*), Bash(uv tree:*), Bash(pnpm update:*), Bash(pnpm install:*), Bash(pnpm view:*), Bash(pnpm outdated:*), Bash(terraform init:*), Bash(git status:*), Bash(git restore:*)

---

# arch-upgrade-deps

The guideline keeps every dependency on its latest stable release, the

current active LTS line where the technology publishes one (Technology

Choices and How to Override Them, Versions, in

`${CLAUDE_SKILL_DIR}/../../architecture.md`; lens `DEL-26` in

`${CLAUDE_SKILL_DIR}/../../lenses/delivery.md`). Releases keep coming,

so a project drifts unless something moves it. This skill moves it in

one change, proves the change with the repository's own gates, and

leaves the working tree for a person to review.

## Input

`[<dependency> ...] [--plan] [--reset-local-data]`

Examples: empty (every dependency), `python node postgres`, `--plan`,

- `postgres --reset-local-data`. Names limit the upgrade to those

+ `valkey --reset-local-data`. Names limit the upgrade to those

dependencies. `--plan` stops after the plan table and edits nothing.

`--reset-local-data` lets the validation remove the local dependency

volumes when a backing service moves a major; without it the skill

never removes them. Nothing else is asked for.

## Procedure

1. Read the Versions subsection and `DEL-26` in full. Run

`git status`; refuse when the working tree has uncommitted changes,

so the diff this skill leaves holds only the upgrade.

2. Run `make check` (or the repository's equivalent fast gate) before

editing anything. When it fails, report the failure as pre-existing

and stop.

3. Inventory every declaration, in the places the Versions subsection

names: `.python-version` and `requires-python` in every

`pyproject.toml`; `.nvmrc`; `packageManager` and `engines` in every

`package.json`; the `FROM` lines of every Dockerfile; the image tags

of every compose file; runtime versions and action references in

- every CI workflow; engine and runtime versions in Terraform. One

+ every CI workflow; engine and runtime versions in Terraform;

+ `required_version` and the provider constraints of every Terraform

+ root, and the Terraform version the CI steps install. One

dependency declared in several places is one row with every place

listed. The `arch-check` tag in the `Makefile` is not a row: it

moves with the guideline pin in `specs/architecture.md`, when the

project adopts a newer guideline, never here.

4. Resolve the target of each row from the maintainers' own release

data, fetched now, never from memory: the Node release index

(`https://nodejs.org/dist/index.json`, the newest entry whose `lts`

is set), `https://endoflife.date/api/<product>.json` for runtimes,

databases, and caches, `pnpm view <package> version` for npm

packages, and the project's release page for an action or a tool.

The target is the current active LTS release where the technology

publishes an LTS line, and the newest stable release otherwise;

never a pre-release, a release candidate, or a line past its end of

life. A release is adopted once a patch release sits behind it,

never the day it ships, as the Versions subsection states: when the

newest release has no patch release behind it (a `.0`, or a patch

published today), the target is the release before it, and the

plan table says so in its Line column. A target that cannot be

confirmed from a source is marked unconfirmed and left unchanged.

5. Print the plan table (see Output). A backing service in the local

- compose stack that moves a major (Postgres 17 to 18, say) keeps its

+ compose stack that moves a major (the cache's engine, say, from one

+ major to the next) keeps its

data files in a volume the new engine cannot open, and validating

the move means removing that volume. The local data may be worth

keeping: `make seed` rebuilds the seeded org, not what a developer

made by hand. So with `--reset-local-data` the row says

`make infra-reset` in the Line column, and the plan prints, under

the table, that the validation removes the local volumes. Without

it, the row is held back whole, in every place it is declared: it

stays in the plan table with `held back` in its Line column, the

report lists it under Held back with "moves a major; rerun with

--reset-local-data" in place of a failing check, and step 6 leaves

it alone. With `--plan`, stop

here.

6. Edit every declaration of each row to its target, keeping the

declaration's precision: a file that names a minor line

(`3.14`) gets the new minor line, one that names an exact release

(`24.21.0`) gets the exact release, an image tag keeps its variant

suffix (`-alpine`, `-slim`). A managed-service engine in Terraform

moves only to a version the provider offers; when that is not

confirmable, the row is unconfirmed.

+ The deployed database engine keeps its major version. A new minor

+ within that major moves; a new major is held back, in Terraform

+ and in the local compose image alike, so the local stack keeps

+ running the engine the environments run. A major upgrade of a

+ deployed database is a planned change with its own snapshot and

+ its own rehearsal, never a line in a dependency bump. The row

+ stays in the plan table with `held back: deployed major` in its

+ Line column, and the report names it under Held back.

+ After the provider constraints and `required_version` move, run

+ `terraform init -upgrade -backend=false` in every Terraform root,

+ each bootstrap root and each environment root, so each root's

+ `.terraform.lock.hcl` resolves the new providers. The lock files

+ are part of the change; a constraint moved without its lock file

+ plans one thing in CI and another on a laptop.

7. Upgrade the libraries in two passes, when the repository has those

workspaces.

First, within the ranges: `uv lock --upgrade` and `uv sync`, and

`pnpm update --recursive` and `pnpm install`. Both keep to the range

each manifest declares, so this pass moves no library across a

major. Never run `pnpm update --latest` over the workspace: it

ignores the ranges and moves every package past its major at once,

which is the move the second pass makes one library at a time.

Then the majors. List the libraries whose range holds them below a

newer major: `pnpm outdated --recursive` for npm, and

`uv tree --outdated --depth 1` for Python. Raise them one library

at a time, never every range at once, in the order the listing

prints them. For npm,

`pnpm update --recursive --latest <name>` rewrites that one range.

For Python, edit the range in each `pyproject.toml` that declares

it, then run `uv lock --upgrade-package <name>` and `uv sync`. Run

step 8 after each raise and before the next, so a failing gate

names the major that broke it.

Then hold each library to the same rule as a runtime: a resolved

release with no patch release behind it is pinned back to the

release before it in the lock

(`uv lock --upgrade-package <name>==<release>`,

`pnpm update --recursive <name>@<release>`), and the report names

it under Held back with "no patch behind it" in place of a failing

check.

8. Validate: `make check`; then, when Docker is available,

- `make infra-up` (`make infra-reset` in its place when a database

- moved a major in this run, which only `--reset-local-data` allows;

+ `make infra-up` (`make infra-reset` in its place when a backing

+ service moved a major in this run, which only `--reset-local-data` allows;

it recreates the dependency volumes and starts nothing else; `make reset` runs `make up`, which also seeds

and starts the application on the host), `make migrate`,

`make migrate-check`, and

`make test-integration`, only against the local compose stack:

refuse when the effective database URL (the environment, `.env`, or

the settings default) is not a local address.

9. On a failure, find the row that causes it. Fix it in place when the

fix is mechanical and named in that release's upgrade notes (a

renamed setting, a moved import, a new required field in a config

file). When the fix would change what the application does, revert

- that row's edits and its lock changes, mark it held back with the

+ that row's edits and its lock changes with `git restore` on the

+ files the row touched (`git restore <file> ...`), mark it held

+ back with the

failing output, and run step 8 again. Stop after every remaining row

passes.

Never commit. Never edit application behavior to fit an upgrade. A

substitute the project's technology-choices ADR records is upgraded

like the technology it replaces.

## Output

A short report, and nothing else:

```markdown

# Dependency upgrade

|------------|-------------|------|----|------|--------|

- | Postgres | `deployment/local/docker-compose.yml` | 16 | 18 | stable, `make infra-reset` | endoflife.date |

+ | Valkey | `deployment/local/docker-compose.yml` | 8 | 9 | stable, `make infra-reset` | endoflife.date |

+ | Postgres | `deployment/local/docker-compose.yml`, `deployment/terraform/modules/database/` | 17.5 | 17.6 | held back: deployed major (18 exists) | endoflife.date |

**Libraries.** <count of Python and npm packages moved, and every major-version move by name, in the order the caps were raised>

**Fixed.** <mechanical fixes made for an upgrade, one per line with the file>, or none

- **Held back.** <dependency, target, and the failing check, "no patch behind it", or "moves a major; rerun with --reset-local-data">, or none

+ **Held back.** <dependency, target, and the failing check, "no patch behind it", "deployed major", or "moves a major; rerun with --reset-local-data">, or none

**Unconfirmed.** <dependency and why no source confirmed a target>, or none

**Gates.** `make check` <passed | failed: what>; integration <passed | failed: what | skipped: no Docker>

```

The tree is uncommitted, and the commit is the user's.