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.
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
-
Refresh the
uvbinary 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 updateworks directly. When uv is managed by an external package manager (Homebrew, pipx, system),uv self updateis disabled — upgrade through that manager instead (brew upgrade uv,pipx upgrade uv, etc.) and note which path was used.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-versionis 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 throughuv run, so an exact pin locks the session out whenever the local binary drifts (GHI #1283).astral-sh/setup-uvinstalls 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.
-
Refresh global uv tools (
mkdocs,ruff,ty,py-gzkit).uv tool upgrade --all -
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 byuv 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.cat .python-version uv python list --only-downloadsWhen a newer patch of the pinned minor is available, run
uv python pin <newest patch>; that one line moves every consumer. Confirm withuv run gz validate --astral-discipline, which fails on any restatement of the version. -
Bump pinned (
==) deps inpyproject.tomlto 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:curl -s "https://pypi.org/pypi/<pkg>/json" \ | python3 -c 'import sys,json;print(json.load(sys.stdin)["info"]["version"])'Edit
pyproject.tomlto replace each<pkg>==X.Y.Zwith the latest version. Skip if the pin already matches latest. -
Refresh the lock to latest within
>=constraints.uv lock --upgrade -
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).
UV_MALWARE_CHECK=1 uv sync --locked --preview-features malware-check -
Raise
>=floors inpyproject.tomlto match what got locked. Read each locked version with:grep -E '^name = "(<pkg1>|<pkg2>|...)"$' -A 1 uv.lockEdit 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). -
Re-run lock + sync to confirm the new floors don't force re-resolution.
uv lock UV_MALWARE_CHECK=1 uv sync --locked --preview-features malware-check -
Verify with full quality gate.
uv run gz check --fullMust 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.
-
Emit canonical ARB unittest receipt (per AGENTS.md § Attestation).
uv run gz arb step --name unittest -- uv run unittest-parallel -t . -s tests --bufferCapture the receipt path (
artifacts/receipts/arb-step-unittest-*.json) for the commit message. -
Mirror skill changes if you also touched skills/rules in the same pass:
uv run gz agent sync control-surfaces -
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):
richmajor bumps (Console / Table API surface)pydanticminor bumps (model serialization edge cases)structlogmajor bumpsbehaveminor bumps after long quiet periodspyinstallerminor 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 --fullexits 0uv.lockresolves cleanly with no churn on the seconduv lockrun.python-versionnames the newest patch of the floor's minor, anduv run gz validate --astral-disciplineexits 0uv --versionsatisfies the[tool.uv] required-versionfloor inpyproject.toml- ARB unittest receipt at
exit_status=0exists inartifacts/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
uvbinary left un-upgraded (Step 1 skipped) — the rest of the pass ran on a stale resolverrequired-versionwritten as an exact==pin — the next local uv drift exits 2 in every hook and locks the session out (GHI #1283)uv.lockandpyproject.tomlfloors disagree by more than a patch level after the upgrade- Pinned (
==) deps left at versions older than current PyPI latest gz check --fullskipped, 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] versionas 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/floorsuv.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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |