🐛 fix(cooled-prek): admit pinned hook versions

.github/workflows/cooled-hooks.yaml

@@ -7,7 +7,7 @@ on:
         type: string
         default: 7 days
       exclude-newer-package:
-        description: Newline-separated name=date cutoffs that override exclude-newer for single packages
+        description: Newline-separated name=date cutoffs for single locked tools; hook environments ignore them
         type: string
         default: ""
 permissions: {}

changelog.d/+cooled-prek-pins.bugfix.md

@@ -0,0 +1,2 @@
+`cooled-prek` admits a hook's exact pinned release up to its upload time while that release is younger than the
+seven-day cutoff, so a hook bumped to a release younger than that installs instead of failing `cooled-hooks.yaml`.

docs/locked-tools.md

@@ -93,10 +93,15 @@ configurations, which no guard checks.
 
 Input `args` **(required)**: whitespace-separated prek arguments, such as `install-hooks`. prek must be on `PATH`.
 
-A package with a `packages.<name>.uploaded-prior-to` exception in `pyproject.toml`'s `[tool.nab]` is admitted up to that
-date in hook environments too. So a hook dependency pinned to a release newer than the cutoff, such as `sphinx` for
-`docstrfmt`, needs the same temporary exception the release lock uses; delete it once the release is a week old.
-Pitfall: hook environments read exceptions only from `pyproject.toml`, not from a standalone `nab.toml`.
+A Python hook's exact pin, `name==version`, admits that release up to its upload time while it is younger than the
+cutoff, so a hook bumped to a release younger than seven days installs. The pin comes from the hook's
+`additional_dependencies` or from its repository's install requirements at the hook's `rev`: `install_requires` in
+`setup.py` or `setup.cfg`, or `[project].dependencies` in `pyproject.toml`. Dev, test, and extra requirements are not
+read. Once the release is a week old, nothing is written and the normal cutoff applies. A newer release of the pinned
+package, uploaded after the pinned one, stays blocked in every hook environment. The pinned release's dependencies and
+any ranges stay cooled. A pin and a `packages.<name>.uploaded-prior-to` exception for the same package: the later date
+wins. `cooled-prek` fetches the hook repository and looks the pinned release up on PyPI; a failed fetch or lookup fails
+the run. Pitfall: hook environments read exceptions only from `pyproject.toml`, not from a standalone `nab.toml`.
 
 ## Install locked tools: `install-locked-tools`
 

docs/pr-checks.md

@@ -96,14 +96,16 @@ fails instead.
     needs: [test, hooks]
 ```
 
-| Input                   | Default  | Meaning                                                                                |
-| ----------------------- | -------- | -------------------------------------------------------------------------------------- |
-| `exclude-newer`         | `7 days` | Upload cutoff for the lock reader that installs the caller's locked `release-prepare`. |
-| `exclude-newer-package` | empty    | Newline-separated `name=date` cutoffs that override `exclude-newer` for one package.   |
+| Input                   | Default  | Meaning                                                                                   |
+| ----------------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `exclude-newer`         | `7 days` | Upload cutoff for the lock reader that installs the caller's locked `release-prepare`.    |
+| `exclude-newer-package` | empty    | Newline-separated `name=date` cutoffs for one locked tool; hook environments ignore them. |
 
 prek comes from the caller's `release-prepare` lock group. Hook environments read cutoff exceptions from `[tool.nab]` in
-`pyproject.toml`, as [`cooled-prek`](locked-tools.md#run-prek-under-the-cutoff-cooled-prek) describes. The prek cache is
-keyed on `.pre-commit-config.yaml` and `pyproject.toml`, so a changed hook or exception rebuilds its environment.
+`pyproject.toml`, and an exact hook pin admits its release while younger than the cutoff, as
+[`cooled-prek`](locked-tools.md#run-prek-under-the-cutoff-cooled-prek) describes. The `exclude-newer-package` input only
+reaches the locked release tools, never the hook environments. The prek cache is keyed on `.pre-commit-config.yaml` and
+`pyproject.toml`, so a changed hook or exception rebuilds its environment.
 
 ## Release dry run
 

docs/troubleshooting.md

@@ -60,10 +60,13 @@ Run `nab lock --all-groups --all-extras` with the Nab version the lock records,
 The lock's `[tool.nab] created-at` is missing, has no time zone, or lies ahead of the runner's clock. Regenerate the
 lock.
 
-**A hook fails to install during a release or maintenance run, with uv finding no matching version.** The hook pins a
-release younger than seven days, and [`cooled-prek`](locked-tools.md#run-prek-under-the-cutoff-cooled-prek) builds hook
-environments under that cutoff. Wait for the release to age, or add a dated `[tool.nab.packages.<name>]` exception in
-`pyproject.toml`; hook environments ignore exceptions in `nab.toml`.
+**A hook fails to install during a release or maintenance run, with uv finding no matching version.** A package the hook
+resolves to a release younger than seven days is not exactly pinned, and
+[`cooled-prek`](locked-tools.md#run-prek-under-the-cutoff-cooled-prek) builds hook environments under that cutoff. An
+exact pin (`name==version` in `additional_dependencies` or the hook repository's install requirements) admits its
+release while that release is younger than the cutoff, so this is a range, a transitive dependency, or a release newer
+than the pin. Wait for the release to age, or add a dated `[tool.nab.packages.<name>]` exception in `pyproject.toml`;
+hook environments ignore exceptions in `nab.toml`.
 
 ## Release preparation