cooldown-guard 0.1.0

auditable uv cooldown exceptions for emergency dependency upgrades

cooldown-guard

cooldown-guard makes uv cooldown exceptions auditable, narrow, and easy to clean up.

it is built around four ideas:

• keep global exclude-newer on
• allow temporary package-specific exceptions for emergency fixes
• pin the exception with constraint-dependencies
• automatically relax the exception once the normal cooldown window catches up

what it writes

given a project like:

[tool.uv]
exclude-newer = "7 days"

an approval like:

cooldown-guard approve urllib3==2.7.0 \
  --project /path/to/repo \
  --approved-by alice \
  --reason "security fix" \
  --advisory CVE-2026-12345 \
  --introduced-via requests \
  --introduced-via types-tqdm

will update the target pyproject.toml to look like:

[tool.uv]
exclude-newer = "7 days"
exclude-newer-package = { urllib3 = "2026-05-07T16:13:18Z" }
constraint-dependencies = ["urllib3==2.7.0"]

and create a .cooldown-guard.toml ledger beside it.

commands

• cooldown-guard approve <package>==<version>: add a narrow exception and run uv lock
• cooldown-guard validate: verify that the ledger and pyproject.toml agree
• cooldown-guard status: show active and cleaned exceptions
• cooldown-guard cleanup --check: test whether an active exception can now be relaxed from == to >=
• cooldown-guard cleanup --apply: apply that relaxation and run uv lock

ci

the repo includes:

• .github/workflows/ci.yml: tests the tool itself
• examples/github-actions/validate.yml: consumer-side validation on pull requests
• examples/github-actions/reconcile.yml: nightly cleanup that can open a pull request

the example workflows install from a git url placeholder. swap your-org/your-repo for the real repo path, or replace it with a pypi package name once published.

notes

• approved_by is audit metadata, not authorization. real authorization should still come from codeowners, branch protection, and normal review policy.
• the tool shells out to uv lock instead of reimplementing resolution.
• v1 intentionally targets the common case where the repo-level exclude-newer is a duration like "7 days".