tvproductions/gzkit / .agents/skills/gz-deps-upgrade
gz-deps-upgrade
VerifiedUse when the operator asks to upgrade deps, Python, uv, pyproject or the lockfile; moves them all to upstream at once.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
SKILL.md
View on GitHub---
name: gz-deps-upgrade
persona: main-session
description: Use when the operator asks to upgrade deps, Python, uv, pyproject or the lockfile; moves them all to upstream at once.
category: code-quality
lifecycle_state: active
owner: gzkit-governance
last_reviewed: 2026-11-19
model: haiku
metadata:
skill-version: "1.7.0"
---
# gz deps-upgrade
## Overview
A disciplined upgrade pass for the project's Python toolchain and dependency
surface: the `uv` binary itself, global uv tools, the Python runtime at the `requires-python` floor's minor,
`pyproject.toml` pins (`==`), `>=` floors, and `uv.lock`. Verifies with
`gz check --full` and emits a canonical ARB unittest receipt as evidence.
The procedure is mechanical — its value is doing the *full* sequence in
order, not skipping the floor-bump or the verification step.
## Workflow
1. **Refresh the `uv` binary itself first.** uv is the foundation of every
later step — its resolver and lockfile behavior can change between
releases, so upgrade it before resolving anything. When uv was installed
via the standalone installer (`~/.local/bin/uv`), `uv self update` works
directly. When uv is managed by an external package manager (Homebrew,
pipx, system), `uv self update` is disabled — upgrade through that manager
instead (`brew upgrade uv`, `pipx upgrade uv`, etc.) and note which path
was used.
```bash
uv --version # before
uv self update # standalone-installer path
# OR, if self-update is disabled: brew upgrade uv / pipx upgrade uv
uv --version # after — confirm it moved (or already latest)
```
**The uv floor stays a floor.** `pyproject.toml` `[tool.uv]
required-version` is a lower bound (`>=`), never an exact pin: uv exits 2
on a version it refuses, and the Claude hooks and the ledger merge driver run
through `uv run`, so an exact pin locks the session out whenever the local
binary drifts (GHI #1283). `astral-sh/setup-uv` installs the highest uv the
floor admits in every workflow, and Read the Docs installs the latest; no
workflow carries a uv version of its own. Raise the floor only when the
repository starts using a uv feature older releases lack, and say which.
Skipping uv itself is a half-upgrade: the rest of the pass runs on a stale
resolver. Never skip this step.
2. **Refresh global uv tools** (`mkdocs`, `ruff`, `ty`, `py-gzkit`).
```bash
uv tool upgrade --all
```
3. **Refresh the Python runtime and move the pin with it.** The version is
declared once (drydock RO-9): the floor in `requires-python`, the
interpreter in `.python-version`, written by `uv python pin`. Nothing else
states it: CI, Read the Docs and the release take Python from uv, and Ruff
and ty infer their target from the floor.
```bash
cat .python-version
uv python list --only-downloads
```
When a newer patch of the pinned minor is available, run
`uv python pin <newest patch>`; that one line moves every consumer.
Confirm with `uv run gz validate --astral-discipline`, which fails on any
restatement of the version.
4. **Bump pinned (`==`) deps in `pyproject.toml` to current PyPI latest.**
Inspect the pinned entries under `[project.optional-dependencies]`,
`[dependency-groups]` and `[tool.uv] build-constraint-dependencies` (the
build backend a source-built dependency takes). For each pinned package,
query PyPI:
```bash
curl -s "https://pypi.org/pypi/<pkg>/json" \
| python3 -c 'import sys,json;print(json.load(sys.stdin)["info"]["version"])'
```
Edit `pyproject.toml` to replace each `<pkg>==X.Y.Z` with the latest
version. Skip if the pin already matches latest.
5. **Refresh the lock to latest within `>=` constraints.**
```bash
uv lock --upgrade
```
6. **Sync the environment to the new lock, with uv's malware check on.**
This is where a new version is first installed, so uv refuses any package
OSV names as malware before installing it (RO-9 tranche 5).
```bash
UV_MALWARE_CHECK=1 uv sync --locked --preview-features malware-check
```
7. **Raise `>=` floors in `pyproject.toml` to match what got locked.**
Read each locked version with:
```bash
grep -E '^name = "(<pkg1>|<pkg2>|...)"$' -A 1 uv.lock
```
Edit each `>=` entry to match the locked version. Skip patch-only bumps
that are trivial (e.g., 7.13.4 → 7.13.5 within the same minor); bump
on minor/major changes (e.g., 13.0 → 15.0, 24.0 → 25.5).
8. **Re-run lock + sync** to confirm the new floors don't force
re-resolution.
```bash
uv lock
UV_MALWARE_CHECK=1 uv sync --locked --preview-features malware-check
```
9. **Verify with full quality gate.**
```bash
uv run gz check --full
```
Must end with `✓ All checks passed (full sweep).` Anything else is a failure — stop
and diagnose, then repair the code to the new version's posture. Never
lower a floor or pin a package back to pass the gate (operator ruling
2026-11-19, below).
9a. **Adopt the new strictness.** A dependency that ships new rules or a
stricter posture is adopted strict (operator, 2026-11-19, verbatim:
*"when ty introduces new rules and a stricter posture, we go strict. this
is generally true of any updates (like with Pydantic). we want to move
forward with our depencies."*). For ty, list the rules it ships off with
`uv run ty explain rule` (`Default level: ignore`) and set each one the
tree passes to `"error"` under `[tool.ty.rules]` in `pyproject.toml`; a
rule with findings is repaired by root cause, rule by rule, never
suppressed in bulk. The same holds for a Pydantic or Ruff change of
behavior: move the code, not the version.
10. **Emit canonical ARB unittest receipt** (per AGENTS.md § Attestation).
```bash
uv run gz arb step --name unittest -- uv run unittest-parallel -t . -s tests --buffer
```
Capture the receipt path (`artifacts/receipts/arb-step-unittest-*.json`)
for the commit message.
11. **Mirror skill changes** if you also touched skills/rules in the same
pass:
```bash
uv run gz agent sync control-surfaces
```
12. **Summarize the diff** for the operator: uv binary + tool versions
before/after, pyproject pin/floor deltas, count of locked-package
upgrades, and the ARB receipt ID.
## Suggested commit message
```
chore(deps): upgrade pyproject + uv.lock to latest
<Notable upgrades — major bumps, pin moves, floor lifts.>
Verified via uv run gz check --full (✓ All checks passed (full sweep)) and ARB-receipted
unittest run: <N> tests, OK, exit_status=0
(receipt arb-step-unittest-<id>).
```
Pass the user's verbatim phrasing through the attestation per
AGENTS.md § Attestation. Do not include the operator's personal email.
## Risk notes
Major-version bumps that have historically required manual review (track
release notes if `gz check --full` fails after the upgrade):
- `rich` major bumps (Console / Table API surface)
- `pydantic` minor bumps (model serialization edge cases)
- `structlog` major bumps
- `behave` minor bumps after long quiet periods
- `pyinstaller` minor bumps (binary build path)
Recovery posture: move forward (step 9a). Repair the code to the new
version; when the repair outgrows the pass, track it with a GHI and land the
upgrade anyway, never holding a package at last-known-good.
## Validation
- `uv run gz check --full` exits 0
- `uv.lock` resolves cleanly with no churn on the second `uv lock` run
- `.python-version` names the newest patch of the floor's minor, and
`uv run gz validate --astral-discipline` exits 0
- `uv --version` satisfies the `[tool.uv] required-version` floor in `pyproject.toml`
- ARB unittest receipt at `exit_status=0` exists in
`artifacts/receipts/`
## Common Rationalizations
These thoughts mean STOP — you are about to ship a half-upgrade:
| Thought | Reality |
|---------|---------|
| "Lock-only bump is enough; floors don't matter" | Floors document tested baseline. Operators on fresh installs can resolve to versions you never tested if the floor lags. Bump them. |
| "I'll skip the ARB receipt — `gz check --full` already passed" | `gz check --full` runs the whole unit tier but does not emit the canonical receipt AGENTS.md § Attestation requires for the commit message. Run the ARB step. |
| "The pin bump is just a patch — leave it" | If the pin is `==` the operator has stated intent to pin. Move the pin to current latest; do not let pinned packages silently lag. |
| "I'll bump the floor to whatever — `>=4.0` covers 4.26 anyway" | The floor is a tested baseline, not a wish. Set it to what `uv lock` actually resolved, so future installs match the tested resolution. |
| "Python is fine, no need to refresh the patch" | Patch releases ship CPython security fixes. `uv python pin <newest patch>` is one line and moves every consumer. |
| "The skill is about deps, not uv itself" | uv IS the toolchain that resolves every dep. A pass that upgrades tools/lock on a stale uv is a half-upgrade running on an old resolver. `uv self update` is Step 1; skipping it is the bug this row exists to prevent. |
| "If `gz check --full` fails, I'll just lower the floor" | Lowering a floor or pinning back holds the project behind its dependencies. Repair the code to the new version (step 9a). |
## Red Flags
- `uv` binary left un-upgraded (Step 1 skipped) — the rest of the pass ran on a stale resolver
- `required-version` written as an exact `==` pin — the next local uv drift exits 2 in every hook and locks the session out (GHI #1283)
- `uv.lock` and `pyproject.toml` floors disagree by more than a patch level after the upgrade
- Pinned (`==`) deps left at versions older than current PyPI latest
- `gz check --full` skipped, downgraded, or run only on a subset
- ARB unittest receipt not emitted (commit message has no receipt ID)
- Committing the upgrade without the attestation enrichment
- Touching `[project] version` as part of a deps upgrade (deps changes are not a release; AGENTS.md local rules)
## References
- AGENTS.md § Attestation — canonical ARB receipt requirement
- AGENTS.md § STDLIB-FIRST DOCTRINE — dependency-add discipline
- `pyproject.toml` — single source of truth for pins/floors
- `uv.lock` — resolution snapshot
- `.gzkit/skills/gz-check/SKILL.md` — quality gate invocation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |