repomatic 7.17.0__tar.gz → 7.18.0__tar.gz

{repomatic-7.17.0 → repomatic-7.18.0}/.claude/.claude-plugin/plugin.json

@@ -20,5 +20,5 @@
 	"license": "GPL-2.0-or-later",
 	"name": "repomatic",
 	"repository": "https://github.com/kdeldycke/repomatic",
-	"version": "7.17.0"
+	"version": "7.18.0"
 }

{repomatic-7.17.0 → repomatic-7.18.0}/.claude/agents/grunt-qa.md

@@ -17,8 +17,8 @@ Work beyond the local repository: check issues, PRs, and CI runs on GitHub. Fix
 
 ## Tools of the trade
 
-- `gh issue list`, `gh pr list`, `gh pr view`, `gh run list`, `gh run view`
-- `repomatic lint-repo`, `repomatic show-metadata`, and every other subcommand. Inside `kdeldycke/repomatic` itself (a `repomatic/__init__.py` exists) reach it as `uv run repomatic`; anywhere else it is not a project dependency, so use `uvx --exclude-newer '1 week' --exclude-newer-package repomatic=P0D -- repomatic`, which holds the dependency tree to the supply-chain cooldown while keeping a fresh repomatic release installable. A bare `uv run repomatic` downstream dies on `Failed to spawn: repomatic`.
+- `gh issue list`, `gh pr list`, `gh pr view`, `gh run view`
+- `repomatic ci-status`, `repomatic lint-repo`, `repomatic show-metadata`, and every other subcommand. Inside `kdeldycke/repomatic` itself (a `repomatic/__init__.py` exists) reach it as `uv run repomatic`; anywhere else it is not a project dependency, so use `uvx --exclude-newer '1 week' --exclude-newer-package repomatic=P0D -- repomatic`, which holds the dependency tree to the supply-chain cooldown while keeping a fresh repomatic release installable. A bare `uv run repomatic` downstream dies on `Failed to spawn: repomatic`.
 - Tests, type checking, linting
 
 ## Checks
@@ -37,7 +37,7 @@ These issues recur across sessions — check them every pass:
 
 - CLI help output in `readme.md` stale after new subcommands or option changes
 - Version references (`@vX.Y.Z`, `--version` examples) not bumped after releases
-- `GitHub Actions` miscapitalized as "GitHub actions" or "Github Actions"
+- `GitHub Actions` miscapitalized, with a lowercase `h` or `a`
 - Workflow job descriptions missing or outdated after job renames/additions
 - Grammar errors in CLI help strings (`"does not exists"`, missing periods)
 - Verbose "why" explanations in YAML workflow comments that belong in Python docstrings

{repomatic-7.17.0 → repomatic-7.18.0}/.claude/agents/sphinx-docs.md

@@ -187,7 +187,7 @@ The reader's eye lands on line 7 of the Python and line 2 of the captured table
 
 ### Emitting raw HTML from `{python:render}`
 
-`{python:render}` parses captured stdout as MyST, and MyST passes block-level raw HTML straight through to the rendered page. So a generator that produces HTML can just `print(html)` — no `{raw} html` wrap, no extra plumbing:
+`{python:render}` parses captured stdout as MyST, and MyST passes block-level raw HTML straight through to the rendered page. So a generator that produces HTML can just `print(html)` — no `{raw} html` wrap:
 
 ````markdown
 ```{python:render}
@@ -221,7 +221,7 @@ Conversion lifecycle:
 
 - Authors write **MyST** in `*.py` docstrings (`` {role}`target` ``, `[text](url)`, single-backtick inline code, ```` ```{directive} ```` admonitions).
 - The `click_extra.sphinx.myst_docstrings` Sphinx extension hooks `autodoc-process-docstring` at priority 400 and converts MyST to reST at build time, before `sphinx_autodoc_typehints` runs. So the rendered HTML is the same as if the docstrings were always reST, while the source files stay editable in MyST.
-- Run `uvx click-extra convert-to-myst` (or `click-extra convert-to-myst path/to/pkg/`) to migrate an existing reST codebase. The converter is idempotent — already-MyST docstrings are a no-op.
+- Run `uvx --exclude-newer '1 week' click-extra convert-to-myst` (or `click-extra convert-to-myst path/to/pkg/`) to migrate an existing reST codebase. The converter is idempotent — already-MyST docstrings are a no-op.
 
 Extension load order (the rule, with the rationale):
 
@@ -428,10 +428,10 @@ def _link(kind, target):
 for path in Path(".").rglob("*"):
     if path.suffix not in {".md", ".rst", ".py"} or not path.is_file():
         continue
-    text = path.read_text(encoding="utf-8")
+    text = path.read_text(encoding="UTF-8")
     for pattern, replacement in PATTERNS:
         text = pattern.sub(replacement, text)
-    path.write_text(text, encoding="utf-8")
+    path.write_text(text, encoding="UTF-8")
 ```
 
 For Python source files (where the role appeared inside docstrings or comments), the replacement keeps the same `[#N](url)` form since `click_extra.sphinx.myst_docstrings` recognizes Markdown links inside docstrings; `:issue:` in a `# comment` was never rendered anyway and becomes a plain link.
@@ -765,9 +765,10 @@ Default-pruning rule:
 - **Match the deployed builder, which is not always `html`.** `[tool.repomatic] sphinx.builder` is what the Docs workflow passes to `sphinx-build -b`, and a project serving extension-less URLs sets it to `dirhtml` (`page/index.html` instead of `page.html`). Read it before assuming a local `-b html` reproduces CI. The builder is chosen on the command line, so it is the one Sphinx setting `conf.py` cannot carry: never "fix" its absence there.
 - **A warning count only covers the pages that build re-read.** Sphinx reuses cached doctrees, so an incremental rebuild reports the warnings of the changed pages alone, and reading that number against a cold build's count shows a drop nothing caused. A `conf.py` edit invalidates the whole cache, which is why the build right after one reports many more. Build into a clean `_build/` before comparing two counts.
 - **Compare two builds only when both hold the same dependency groups.** autodoc imports each module it documents. A build that lacks one group fails those imports, like the test group for a `tests` API page, and each reference into such a module then reports as unresolved. Build the baseline from an export of `HEAD` and the candidate from the working tree, both with `uv run --isolated --frozen --all-extras --all-groups`: neither touches the shared virtual environment.
+- **Run `sphinx-build` with the command sandbox off.** Inside the Claude Code sandbox (`2.1.284`, macOS, 2026-10-02), `sphinx_sitemap` aborts the build at `builder-inited` with `PermissionError: [Errno 1] Operation not permitted`. Intersphinx also fails to fetch its inventories there. Neither failure says anything about the docs.
 - Periodically diff against a fresh `sphinx-quickstart` output in a tmpdir to spot defaults that have shifted under you.
 - Drop conditional import shims once the project's minimum Python no longer needs them. The `try: import tomllib / except: import tomli` pattern is dead code on `requires-python = ">=3.11"`. Same for any `if sys.version_info < (3, X):` branch where `X` is now below the floor. The deps group should lose the corresponding fallback dependency in the same PR.
-- Always pass `encoding="utf-8"` to `Path.read_text()` calls in `conf.py`. Bare `read_text()` picks up the locale, which on minimal CI runners has bitten many projects.
+- Always pass `encoding="UTF-8"` to `Path.read_text()` calls in `conf.py`. Bare `read_text()` picks up the locale, which on minimal CI runners has bitten many projects.
 - `exclude_patterns = ["_build", "_linkcheck", "html", "Thumbs.db", ".DS_Store"]` is the canonical set: `_build` and `_linkcheck` are the build and linkcheck output directories (both also gitignored), and `html` catches stray in-tree builds left by ad-hoc `sphinx-build` invocations.
 - Publish content, not build scaffolding. `html_copy_source = False` and `html_show_sourcelink = False` together drop the `_sources/` copy of every document, which no page in this lineage links to and only a hand-typed URL could reach. Name both: they gate different halves of the feature, and a theme reading only the second offers a link to files that are no longer there. Sphinx still creates the (now empty) directory and writes `.buildinfo` from an unconditional finish task, so a `build-finished` hook removing `.buildinfo`, `.buildinfo.bak` and the empty `_sources/` is what actually keeps them out of the deployed tree.
 - `sphinx_sitemap` earns its place on any site big enough that a crawler would have to walk the whole link graph to find the API pages. It needs `html_baseurl`, and **that value must end in a slash**: sphinx-sitemap concatenates it with each page link (its own normalization line computes the slash-terminated form and discards the result), so a slash-less base emits `https://example.netinstall.html`. Derive it once from `project.urls.Documentation` with `.rstrip("/") + "/"`, feed both `html_baseurl` and `ogp_site_url` from it, and set `sitemap_url_scheme = "{link}"`: the default `{lang}{version}{link}` layout is for sites publishing translations or versions side by side, and yields 404s anywhere else. Pair it with a self-contained `404.html` in `html_extra_path`: when none is present, Cloudflare Pages answers an unmatched route with the home page and a `200`, which tells a crawler every misspelled URL is real. A site on its own host also gets a `robots.txt` there that names the sitemap. A GitHub Pages project site under `{user}.github.io/{project}/` gets none, because crawlers read `robots.txt` only at the host root. The links in its `404.html` start from `/{project}/`, because the page can answer at any depth.
@@ -806,8 +807,9 @@ Linkcheck and intersphinx:
 
 Strictness flags:
 
-- `nitpicky = True` is the default in this lineage. Missing references fail the build instead of producing a half-rendered page. Don't disable it; fix the missing target.
-- `autosectionlabel_prefix_document = True` avoids duplicate-label warnings when two pages have the same heading. Pair with `autosectionlabel = True` in extensions.
+- `nitpicky = True` is the default in this lineage. Each missing reference then logs a warning, which fails a build run with `-W`. Don't disable it; fix the missing target.
+- `click_extra_fail_on_warnings = ["myst.xref_missing"]` fails the build on a `[text](#anchor)` or `[text](page.md#anchor)` link that lands nowhere. myst-parser only logs that warning, and ships the link as written. Set it on a build that logs too many warnings to run with `-W`. The setting needs click-extra `9.4.0`: an older release ignores it, and the build passes. A `page.md#anchor` link to an ID that autodoc generates reports the same warning, though the ID exists: write it as a `{role}` cross-reference.
+- `autosectionlabel_prefix_document = True` avoids duplicate-label warnings when two pages have the same heading. Pair with `"sphinx.ext.autosectionlabel"` in `extensions`.
 
 `suppress_warnings` governance:
 
@@ -816,11 +818,11 @@ Strictness flags:
 - Canonical entries observed across sibling repos:
   - `sphinx_autodoc_typehints.forward_reference` — pytest decorators dynamically generated at import time; pytest's `Mark` type is unavailable during the docs build. Cosmetic.
   - `myst.directive` — empty mermaid directives produced by automated diagram generators with sparse data.
-  - `myst.xref_missing` — MyST validates anchors before autodoc generates them; false positives only.
   - `myst.domains` — upstream limitation in `click_extra.sphinx` (no `resolve_any_xref` method on the click domain).
   - `myst.strikethrough` — `~~text~~` marks deprecated/incorrect spellings in docstrings; the project ships HTML only.
   - `myst.header` — `readme.md` starts at `## ` because GitHub supplies the H1 from the repo name; intentional.
   - `docutils` — code examples in docstrings whose indentation trips reST parsing; usually in test fixtures.
+- Never list `myst.xref_missing` here: it reports a fragment link that lands nowhere, and `click_extra_fail_on_warnings` skips a suppressed type. See § Strictness flags.
 - On every Sphinx or extension upgrade, sweep `suppress_warnings` and re-run a clean build with the entry removed. If the warning no longer fires, drop the entry in the same PR.
 
 `nitpick_ignore` governance:
@@ -885,7 +887,7 @@ Watch for these every pass:
 - An `automodule` block on a narrative page, repeating what the module's own API page already documents. Every such pair costs a duplicate object description per member and buries the guide's message; see § Guide pages carry the prose, API pages carry the API.
 - Stale `.rst` files in `docs/` left over from package renames or earlier `sphinx-apidoc` runs that reference modules or packages no longer in the source tree. They build silently (autodoc skips missing modules with a warning, not an error) but pollute search results and the modindex. Sweep with `git status` after `update-docs`; delete orphans in the same PR.
 - Developer setup held in `readme.md` (a `## Development` section) or in `claude.md`. Setup, dev loop and test commands belong on the `contributing` page of the roster, where a contributor looks for them. `claude.md` loads into every agent session, so it keeps conventions and links to that page. A second copy creates two places to update.
-- A `dependencies.md` page whose embedded Mermaid graph hasn't been regenerated since the last `uv lock` change. The graph stays in sync only if `repomatic update-dep-graph` is wired into a workflow job; manual regeneration drifts. Upstream that job lives in `_release-engine.yaml` and fires on release commits only, so a graph lagging `pyproject.toml` mid-cycle is expected rather than drift.
+- A `packaging.md` page whose embedded Mermaid graph hasn't been regenerated since the last `uv lock` change. The graph stays in sync only if `repomatic update-dep-graph` is wired into a workflow job; manual regeneration drifts. Upstream that job lives in `autofix.yaml` and runs on every push, so a graph lagging `pyproject.toml` means its pull request is still open, not drift. With `[tool.repomatic] dependency-graph.update = false`, the command writes no graph and the job opens no pull request.
 - `pyproject.toml` declaring a docs dependency that's no longer imported by `conf.py` (or vice-versa: importing one not declared). The mismatch passes Sphinx but trips a fresh `uv sync --group docs` run on a CI runner.
 - `click_extra.sphinx.myst_docstrings` listed in `extensions` without `click-extra[sphinx]` declared in `[dependency-groups] docs`. Builds work on the maintainer's machine if the package is installed globally, then break in CI.
 - `click_extra.sphinx` listed in `extensions` without `click_extra_enable_exec_directives = True` in `conf.py`. Since click-extra `v7.15.0` the directives are off by default; without the flag, every `{click:run}` / `{click:source}` / `{python:*}` reference logs an "Unknown directive" warning and the page renders without the live block.

{repomatic-7.17.0 → repomatic-7.18.0}/.claude/skills/babysit-ci/SKILL.md

@@ -80,12 +80,12 @@ After fixing (step 5-7), the loop restarts from the top: push, run all three cha
 
    One call returns every workflow triggered by that commit. Do not reach for `gh run list`: both its branch-wide form and its per-workflow form have put runs weeks old at the top of the list, on a repository whose workflows had in fact run on every recent commit, which reads as "this workflow has not run in a month". Give `head_sha` the **full** 40-character SHA, because an abbreviated one matches nothing and returns an empty list that looks identical to "nothing ran". Quote the whole path: zsh expands the `?` as a glob and kills the call with `no matches found` before `gh` runs. To list a single workflow across a branch instead, use `gh api 'repos/<OWNER>/<REPO>/actions/workflows/<file>/runs?branch=<BRANCH>&created=>=<DATE>'`, and keep the date filter: without it, that endpoint has returned a page twelve days stale while the branch ran every hour.
 
-   Track all five run IDs (`docs.yaml` may have none: its `paths:` filter skips pushes touching nothing docs-relevant). An empty run list for the *other* workflows is not paths-filtering: GitHub can sit on a push event for hours before materializing any run (a 4-hour lag has been observed), so when a freshly pushed SHA shows no runs, keep re-polling instead of concluding the push was filtered, and measure the wait from run creation, not from the push. The `tests.yaml` run exercises the full test matrix; `lint.yaml` runs mypy on every tracked Python file and lints YAML; `autofix.yaml` runs the mechanical fix jobs (`format-*`, `sync-*`, `fix-typos`, `fix-vulnerable-deps`) and turns red when one *crashes* instead of committing a fix; `docs.yaml` builds and deploys the Sphinx site and runs the broken-links check (an externally cancelled or link-flaky run re-runs cleanly via `gh workflow run docs.yaml --ref <BRANCH>`, no commit needed); `release.yaml` runs the Nuitka binary matrix (dev binaries: an ordinary push rebuilds only the `[tool.repomatic] nuitka.dev-targets` canary subset, while release commits, the weekly `schedule` and `workflow_dispatch` build the full target fleet) — but only on projects with `[tool.repomatic] nuitka.enabled` and a CLI entry point; with Nuitka disabled the per-platform jobs skip on every push, release commits included, and a green `release.yaml` means package build plus dev pre-release sync only. Even with Nuitka enabled, a single push can still skip the matrix: `Metadata.skip_binary_build` (`repomatic/metadata/git.py`) is the authoritative signal, true when the head commit is on a non-code branch, is a user-initiated version-bump commit, or (the common case) its changed files fall entirely outside `Metadata.binary_affecting_paths` — a docs-only or workflow-only commit, say. Don't infer the reason from the commit message or assume an unrendered/skipped matrix job name means `nuitka_matrix` itself was empty: the matrix data can be fully populated for that exact commit (verify via the `release / 🧬 Project metadata` job's logged `metadata=` JSON output) while the workflow still elects not to build it. Check `skip_binary_build`'s three conditions before asserting why a matrix skipped, since any one of them is enough on its own. All five workflows must pass — see § Autofix job failures and § Nuitka binary build failures in `references/failure-patterns.md` for how to triage them without stalling the loop.
+   Track all five run IDs (`docs.yaml` may have none: its `paths:` filter skips pushes touching nothing docs-relevant). An empty run list for the *other* workflows is not paths-filtering: GitHub can sit on a push event for hours before materializing any run (a 4-hour lag has been observed), so when a freshly pushed SHA shows no runs, keep re-polling instead of concluding the push was filtered, and measure the wait from run creation, not from the push. The `tests.yaml` run exercises the full test matrix; `lint.yaml` runs mypy on every tracked Python file and lints YAML; `autofix.yaml` runs the mechanical fix jobs (`format-*`, `sync-*`, `update-*`, `fix-typos`, `fix-vulnerable-deps`) and turns red when one *crashes* instead of committing a fix; `docs.yaml` builds and deploys the Sphinx site and runs the broken-links check (an externally cancelled or link-flaky run re-runs cleanly via `gh workflow run docs.yaml --ref <BRANCH>`, no commit needed); `release.yaml` runs the Nuitka binary matrix (dev binaries: an ordinary push rebuilds only the `[tool.repomatic] nuitka.dev-targets` canary subset, while release commits, the weekly `schedule` and `workflow_dispatch` build the full target fleet) — but only on projects with `[tool.repomatic] nuitka.enabled` and a CLI entry point; with Nuitka disabled the per-platform jobs skip on every push, release commits included, and a green `release.yaml` means package build plus dev pre-release sync only. Even with Nuitka enabled, a single push can still skip the matrix: `Metadata.skip_binary_build` (`repomatic/metadata/git.py`) is the authoritative signal, true when the head commit is on a non-code branch, is a user-initiated version-bump commit, or (the common case) its changed files fall entirely outside `Metadata.binary_affecting_paths` — a docs-only or workflow-only commit, say. Don't infer the reason from the commit message or assume an unrendered/skipped matrix job name means `nuitka_matrix` itself was empty: the matrix data can be fully populated for that exact commit (verify via the `release / 🧬 Project metadata` job's logged `metadata=` JSON output) while the workflow still elects not to build it. Check `skip_binary_build`'s three conditions before asserting why a matrix skipped, since any one of them is enough on its own. All five workflows must pass — see § Autofix job failures and § Nuitka binary build failures in `references/failure-patterns.md` for how to triage them without stalling the loop.
 
 3. **Run local tests while waiting for CI.** Don't idle while polling. Start the full test suite and linters locally in the background immediately:
 
    ```shell-session
-   $ uv run pytest --no-header -q &
+   $ uv run --frozen --all-extras --group test pytest --no-header -q &
    $ uv run --group typing repomatic run mypy &
    $ uv run repomatic run ruff -- check repomatic tests docs &
    ```
@@ -100,13 +100,13 @@ After fixing (step 5-7), the loop restarts from the top: push, run all three cha
    $ uv run repomatic ci-status --branch=<BRANCH> --no-fatal
    ```
 
-   It reads every workflow a push can start (derived from `.github/workflows/`, so its list is wider than the five above), reports each one's latest run, and names the failing jobs that actually gate a merge. Three traps it settles, so no hand-rolled `jq` has to: a run's own `status` lags its jobs (every monitored workflow can read `queued` while a dozen jobs have already finished, which is indistinguishable from the runner-cap saturation a busy account genuinely hits); a `continue-on-error` probe that crashed hides inside a `success` run conclusion; and a run whose `conclusion` is `failure` with *no* failed job is a workflow-level error (an invalid `strategy.matrix` expression, malformed YAML, a missing secret) with no job log to read, which the command flags rather than letting you write off a persistently-red workflow as a known artifact.
+   It reads every workflow a push can start (derived from `.github/workflows/`, so its list is wider than the five above), reports each one's latest run, and names the failing jobs that actually gate a merge. Four traps it settles, so no hand-rolled `jq` has to: a run's own `status` lags its jobs (every monitored workflow can read `queued` while a dozen jobs have already finished, which is indistinguishable from the runner-cap saturation a busy account genuinely hits); a `continue-on-error` probe that crashed hides inside a `success` run conclusion; a run whose `conclusion` is `failure` with *no* failed job is a workflow-level error (an invalid `strategy.matrix` expression, malformed YAML, a missing secret) with no job log to read, which the command flags rather than letting you write off a persistently-red workflow as a known artifact; and a run that was cancelled, or that ran no job, has no failed job and still gives its commit no result, so its verdict reads `cancelled` or `skipped`, never `green`.
 
-   `ci-status` reads the same endpoints as the `gh api` calls above, and it has printed a stale table the same way: re-read a surprising red or green once before acting on it.
+   `ci-status` reads runs through the same `head_sha` endpoint, commit by commit back from the branch tip, and says when the tip has no run yet. A workflow that ran no job on the tip, like `tests.yaml` on a version-bump commit, is read on an earlier commit, and the command names it. A `cancelled` or `skipped` verdict is not a pass: see [§ When supersession never lets a run conclude](#when-supersession-never-lets-a-run-conclude). A workflow with no run on the newest commits falls back to its own run listing, filtered by creation date. Re-read a surprising red or green once before acting on it.
 
    Run state *does* gate the run-scoped log read (step 4): `gh run view --log-failed` refuses to answer until the parent run reaches a terminal state. A completed job's own log is readable at once.
 
-   **A queue is not a hang, and elapsed time alone cannot tell them apart.** A long stall invites the theory that some run is stuck and that cancelling it would free the pool, which is a conclusion worth reaching only on evidence, because acting on it destroys work that was progressing fine. Two readings settle it, and neither is the elapsed clock. Get a **baseline** from that workflow's recent successful runs (`gh run list --workflow <wf> --repo <owner/repo> --status success --json createdAt,updatedAt`): a suite whose normal duration is two hours is not hung at ninety minutes. Then read **per-job `completedAt` timestamps** (`gh run view <id> --json jobs`) rather than an aggregate: a flat count of `in_progress` jobs is not evidence of a stall, since jobs finish and others start into the freed slots, holding the count steady while real progress continues. Watch for the self-contradiction that exposes the mistake, a report that the count "dropped from 11 to 9" *and* that nothing has changed. Two smaller traps live here too: `gh` reports a pending job's `conclusion` as `""`, not `null`, so a `select(.conclusion == null)` filter silently matches nothing and reads as "no pending jobs"; and jobs queue against the runner pool their `runs-on` names, so a stall confined to macOS cells says nothing about Linux capacity. **Never cancel another repository's run to free slots without the maintainer's explicit go-ahead**, and never ask for that go-ahead on a diagnosis you have not backed with a baseline and timestamps.
+   **A queue is not a hang, and elapsed time alone cannot tell them apart.** A long stall invites the theory that some run is stuck and that cancelling it would free the pool, which is a conclusion worth reaching only on evidence, because acting on it destroys work that was progressing fine. Two readings settle it, and neither is the elapsed clock. Get a **baseline** from that workflow's recent successful runs (`gh api 'repos/<OWNER>/<REPO>/actions/workflows/<wf>/runs?status=success&created=>=<DATE>' --jq '.workflow_runs[] | [.created_at, .updated_at] | @tsv'`): a suite whose normal duration is two hours is not hung at ninety minutes. Then read **per-job `completedAt` timestamps** (`gh run view <id> --json jobs`) rather than an aggregate: a flat count of `in_progress` jobs is not evidence of a stall, since jobs finish and others start into the freed slots, holding the count steady while real progress continues. Watch for the self-contradiction that exposes the mistake, a report that the count "dropped from 11 to 9" *and* that nothing has changed. Two smaller traps live here too: `gh` reports a pending job's `conclusion` as `""`, not `null`, so a `select(.conclusion == null)` filter silently matches nothing and reads as "no pending jobs"; and jobs queue against the runner pool their `runs-on` names, so a stall confined to macOS cells says nothing about Linux capacity. **Never cancel another repository's run to free slots without the maintainer's explicit go-ahead**, and never ask for that go-ahead on a diagnosis you have not backed with a baseline and timestamps.
 
    **Gate 2 (lint.yaml, ~4 min):** `lint.yaml` finishes before `tests.yaml`. If "Lint types" (mypy) fails, proceed to step 4 immediately.
 
@@ -134,7 +134,7 @@ After fixing (step 5-7), the loop restarts from the top: push, run all three cha
    $ gh run view <LINT_RUN_ID> --json jobs --jq '[.jobs[] | select(.conclusion == "failure")] | .[].databaseId'
    ```
 
-   The first filter negates the unstable glyph rather than matching a `✅` prefix, mirroring `JobStatus.required`. `tests.yaml` runs four required jobs whose names carry no `✅` at all (`🧬 Project metadata`, `1️⃣ Run-once tests`, `📦 Package install`, `🖥️ Validate …`), and the release engine prefixes the workflow ahead of the glyph, so a prefix test silently drops a real failure from the batch.
+   The first filter negates the unstable glyph rather than matching a `✅` prefix, mirroring `JobStatus.required` on every name GitHub expanded. `tests.yaml` runs four required jobs whose names carry no `✅` at all (`🧬 Project metadata`, `1️⃣ Run-once tests`, `📦 Package install`, `🖥️ Validate …`), and the release engine prefixes the workflow ahead of the glyph, so a prefix test silently drops a real failure from the batch.
 
    Fetch each failed job's log (`gh api repos/<OWNER>/<REPO>/actions/jobs/<JOB_ID>/logs --allow-escape-sequences`) and fix them as one batch: different sources surface different issues, and logs survive cancellation. Batch only what has *already failed*, never what might still fail. Once every harvested failure is root-caused and fixed, push immediately rather than waiting for undrained cells to surface more: the fresh run supersedes the stale one, and serially waiting out each full matrix is the slow path. Analyze following the [error triage discipline](#error-triage-discipline): stable-job `FAILED`/`AssertionError` lines only. Then match each failure against `references/failure-patterns.md` before fixing anything.
 
@@ -156,7 +156,7 @@ After fixing (step 5-7), the loop restarts from the top: push, run all three cha
    After applying fixes, re-run the full local validation:
 
    ```shell-session
-   $ uv run pytest --no-header -q
+   $ uv run --frozen --all-extras --group test pytest --no-header -q
    $ uv run --group typing repomatic run mypy
    $ uv run repomatic run ruff -- check repomatic tests docs
    $ uv run repomatic run ruff -- format repomatic tests docs
@@ -195,6 +195,8 @@ After fixing (step 5-7), the loop restarts from the top: push, run all three cha
 
 A busy default branch can cancel the same workflow indefinitely. Every push shares the `${{ github.workflow }}-${{ github.ref }}` concurrency group, so an unrelated commit landing mid-matrix cancels yours, and the next one cancels its replacement. Three consecutive heads leaving `tests.yaml` cancelled is an ordinary afternoon, not a fault. Dispatching a fresh run does not escape it: a `workflow_dispatch` run joins the same group and is cancelled by the next push like any other.
 
+A dispatch does settle one case: a version-bump commit, whose subject starts with `[changelog] Bump`, merged right after your push. It cancels your runs, and `tests.yaml` skips the bump commit itself, so `ci-status` reads `cancelled` on your commit. Run `gh workflow run tests.yaml --ref <BRANCH>` once: the dispatched run tests the head, which holds your change.
+
 **A cancelled run is neither a failure nor a pass, and the run-level conclusion hides which.** Read the jobs:
 
 ```shell-session
@@ -228,7 +230,7 @@ Report the union explicitly: which cells passed in CI, which you closed locally,
 
 The workflow uses `continue-on-error` for unstable jobs, so the run can succeed even when they fail.
 
-`repomatic ci-status` does this classification, and doing it by hand is where it goes wrong: job-name shapes differ across workflows — `tests.yaml` names carry no workflow prefix (`✅ ubuntu-26.04 / py3.10`) while the release engine's arrive through the reusable call (`release / ✅ ubuntu-26.04, abc1234 build`) — so a test anchored at the start of the name misfiles one shape and a split on `" / "` misfiles the other, either way masking a real failure as green. Containment is the one test both shapes satisfy. Only `✅`/`⁉️` carry stability: a job whose name opens on some other emoji (`🛡️ Lint types`, `1️⃣ Run-once tests`) is required, so test for the absence of `⁉️` rather than for the presence of any glyph. If you reformat job names for display, keep the raw string for the test.
+`repomatic ci-status` does this classification, and doing it by hand is where it goes wrong: job-name shapes differ across workflows — `tests.yaml` names carry no workflow prefix (`✅ ubuntu-26.04 / py3.10`) while the release engine's arrive through the reusable call (`release / ✅ ubuntu-26.04, abc1234 build`) — so a test anchored at the start of the name misfiles one shape and a split on `" / "` misfiles the other, either way masking a real failure as green. Containment is the one test both shapes satisfy. Only `✅`/`⁉️` carry stability: a job whose name opens on some other emoji (`🛡️ Lint types`, `1️⃣ Run-once tests`) is required, so test for the absence of `⁉️` rather than for the presence of any glyph. A name that still holds both glyphs is a matrix GitHub never expanded, on a run stopped before the matrix got its cells: `ci-status` reads it as required. If you reformat job names for display, keep the raw string for the test.
 
 ## Error triage discipline
 

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/babysit-ci/references/failure-patterns.md

@@ -20,7 +20,7 @@ The classic false green: mypy passes locally over a subset of directories while
 
 ## Platform-specific test skips
 
-Some tests are skipped on certain platforms (`windows-11-arm` has no Python 3.10 ARM64 build). Before investigating missing results, check the matrix `exclude` section in `tests.yaml` and the `skip_platforms` entries in the binary self-test plan (`tests/cli-test-suite.toml`): individual cases can opt out of platforms without affecting the CI matrix.
+Some tests are skipped on certain platforms (`windows-11-arm` has no Python 3.10 ARM64 build). Before investigating missing results, check which cells the matrix excludes. `repomatic show-test-matrix` lists the computed matrix that the bundled `tests.yaml` runs, with the built-in exclusions and the `[tool.repomatic] test-matrix.exclude` entries applied. A `tests.yaml` with a hand-written matrix carries its own `exclude` section. Then check the `skip_platforms` entries in the binary self-test plan (`tests/cli-test-suite.toml`): individual cases can opt out of platforms without affecting the CI matrix.
 
 ## Cross-platform divergence
 
@@ -41,6 +41,7 @@ Not all CI failures are code bugs:
 - **Action version mismatches**: `Unable to resolve action`, deprecated-runtime errors. Fix the workflow YAML, not the Python.
 - **Network/registry flakiness**: `uv`/`pip` timeouts, PyPI 503s, `ConnectionResetError`. Re-run.
 - **A wall-clock budget assertion** (`assert elapsed_ms < N`) failing on a shared runner: infrastructure is the *trigger*, but the defect is the test, which took one sample and so measured that runner's worst moment rather than the code. A re-run only re-rolls the dice, and the tell that it has been re-rolled before is a budget already ratcheted upward in an earlier cycle for the same runner class. Assert on the fastest of several samples instead: a real regression slows every sample, a scheduling stall slows one. Raising the budget again is the fix that stops working.
+- **A stable job that turns red with no change to the tree or to the runner image**: a setup step met a different outside world, like a package manager that started a cleanup or a migration because its upstream metadata moved. The failing test only shows the symptom. Compare the setup output of the last green job with the red one before you read the test output: a step that prints new lines, or runs in one log only, names the cause. Fix that step. A re-run changes nothing, and a tolerated exit code hides the defect.
 - **Permission errors**: `Resource not accessible by integration`, 403s. Check `gh api rate_limit` first ([§ GitHub API rate-limit exhaustion](#github-api-rate-limit-exhaustion)), then token permissions; never code.
 - **A whole workflow red with nothing executed**, every job reporting failure and the `metadata` job unable to resolve its own toolkit pin: the inline `uvx 'repomatic==X.Y.Z'` command is missing `--exclude-newer-package repomatic=P0D`, so the workflow-wide `UV_EXCLUDE_NEWER` refuses a pin naming a release younger than the window, and each `needs: metadata` job dies with it. Splice the flag onto that command line — `uvx` reads no project configuration, so there is nowhere else the bypass can live — or merge the `sync-workflow-pins` PR that backfills it. `lint-repo`'s fatal `self-pin-cooldown-exemption` check names the offending files. Re-running changes nothing.
 - **A Cloudflare deploy that ends red after publishing**: the `docs.yaml` workflow's `deploy-docs-cloudflare` job dropped a file over 25 MiB, so the live site links to a file it does not have. The offload step's error annotation names each file and the reason. Re-run only when the reason is a failed upload. Any other reason, like an undeclared R2 bucket or missing R2 secrets, needs a repository change or maintainer setup: report it instead.

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/benchmark-update/SKILL.md

@@ -177,6 +177,10 @@ Stale or abandoned projects should be moved to the "Excluded projects" section w
 
 For each feature row, spot-check 2-3 projects against their current documentation or changelog. Flag cells that look wrong (features added or removed since the benchmark was written).
 
+A row added since the last pass gets every competitor cell assessed, not a sample: its cells start unassessed, and an empty cell reads as "unsupported".
+
+Re-anchor the version-pinned evidence links of a competitor that shipped a new release. A link pinned to a tag or a commit with a line range (`blob/v17.12.2/src/steps.rs#L120-L140`) keeps pointing at the old release. Find the same snippet in the new release by its content, never by the old line numbers, then repoint the link to the new tag and range. A snippet that is gone means the cell needs a fresh assessment.
+
 #### 3. Gap analysis freshness
 
 For each item in "Gaps and opportunities", check whether the linked upstream issues have changed status:

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/file-bug-report/SKILL.md

@@ -83,6 +83,8 @@ $ gh api repos/<owner/repo>/contents/.github/CODE_OF_CONDUCT.md --jq '.download_
 $ gh api repos/<owner/repo>/community/code_of_conduct --jq '.body'
 ```
 
+Read each file to its end. When the repository file only points to a code of conduct hosted elsewhere, fetch that page and read it too.
+
 #### 1d. Issue templates and forms
 
 List all issue templates. Repos may use classic markdown templates, YAML issue forms, or both:
@@ -155,10 +157,19 @@ $ gh issue list --repo <owner/repo> --state all --json title,url,state
 
 Search with multiple keyword variations (error messages, function names, symptoms). Check both open and closed issues: the bug may have been reported and closed as "won't fix", or fixed in a version the user hasn't upgraded to.
 
-If a matching open issue exists, report it to the user and stop. If a matching closed issue exists, mention it in the report with a link and explain why this is a new occurrence (different version, different context, regression).
+If a matching open issue exists, report it to the user and stop. Do not offer a comment on an issue that a maintainer has already answered as in progress, unless the user asks for one. If a matching closed issue exists, mention it in the report with a link and explain why this is a new occurrence (different version, different context, regression).
 
 A matching issue closed for lack of a reproducer is not a dead end: cite it, because that closure is part of the record, and supply what it lacked.
 
+A keyword search over issues is not enough. Run these four checks too before you report the result to the user:
+
+- **Pull requests.** Run the same keywords through `gh search prs`: a fix under review answers the report before it is filed.
+- **Everything since the behavior appeared.** List the issues and pull requests created since the commit that introduced it, and read every title. A body search is noisy, because pasted logs hold the tool's own vocabulary.
+- **Branches and release notes.** Read the development branches and the release notes for a fix in progress, and for the maintainer's own words on the topic.
+- **Overlap.** Name the threads that share the theme without being duplicates. Cross-reference in the report the ones a reader can confuse with it.
+
+Tell the user which checks ran, and what each one could not reach: a deleted issue, a truncated search, a chat server.
+
 ### 3. Gather evidence
 
 Collect the actual error output, environment details, and reproduction steps from the current conversation context, CI logs, or local files. Always include:
@@ -189,6 +200,7 @@ The maintainer of the code is the authority on it. Hand over observations they c
 - **Date a behavior by the commit that added it, not by the release note that announced it.** Release notes list what is worth reading about now, not what shipped now: `git tag --contains {sha} | sort -V | head -1` names the first release that carried the commit.
 - **Report what varied, where, and the link to it, then stop.** Leave the diagnosis, its implications for CI or users, and the next step to the maintainer, who reaches them faster from the facts than from a summary of them.
 - **Give every failing reproducer a passing control beside it.** Without a near-identical case that passes, red cannot be told apart from a broken harness, a missing dependency or a mistake in the reproducer. Assert the control too, and have the job report the test as void when the control breaks.
+- **Run the reproducer in a second implementation before naming one.** When the target implements a shared standard (a browser engine, an interpreter, a compiler), the same result elsewhere moves the report to the standard, or to the code under test.
 - **Freeze the reproducer's vocabulary once the prose quotes it.** Renaming a log line, an artifact or a path that the report quotes forces a rerun, then a repoint of every link and quoted phrase.
 - **Re-read the draft before handing anyone steps to reproduce.** Give only the steps the draft records as reproducible, and flag a symptom seen only once as a one-off.
 

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/github-housekeeping/SKILL.md

@@ -83,7 +83,7 @@ Hybrid pipeline, cheapest signal first:
 
 1. **Already labeled** items need nothing: record them as settled.
 2. **Keyword heuristics** derived from each label's own description. Score title hits heavily (a title match with no rival label is high confidence) and cap body-match contributions so long bodies cannot fake a signal. This confidently resolves roughly half of a typical backlog for free.
-3. **Agent batches** for the residual: parallel subagents, ~70 items each, given the taxonomy with calibration examples, item titles plus bodies truncated to ~500 chars, and the heuristic's best guess as a hint. Demand strict machine-parseable output (`number|label|confidence|rationale`, one line per item, every item exactly once) and validate on merge: unknown labels, missing items, and unparseable lines get retried or fall through.
+3. **Agent batches** for the residual: parallel subagents, ~70 items each, given the taxonomy with calibration examples, item titles plus bodies truncated to ~500 chars, and the heuristic's best guess as a hint. Demand strict machine-parseable output (`number|label|confidence|rationale`, one line per item, every item exactly once) and validate on merge: unknown labels, missing items, and unparsable lines get retried or fall through.
 4. **Fallback**: anything dropped by an agent gets classified by hand so coverage stays total.
 
 Review gates before applying: all low-confidence calls, plus every proposed `🪫 AI slop`/`🚫 wont do/fix`, go in a "needs review first" section of the plan, open items sorted first. Offer to open candidate batches in the browser (`xargs open < urls.txt`) so the maintainer can eyeball them quickly.

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/repomatic-audit/SKILL.md

@@ -25,8 +25,9 @@ You perform a comprehensive audit of a downstream repository against the upstrea
 Before flagging an issue, verify that the gap isn't **deliberate** or covered by a runtime mechanism. Common false positives:
 
 - **`[tool.repomatic] exclude` is authoritative.** Files listed there (like `workflows/changelog.yaml` or `labels`) are intentionally absent on disk. Do **not** report them as MISSING.
+- **`[tool.repomatic] lint-repo.declined` records a decision.** Each entry names one bundled template entry that a `[tool.X]` section leaves out, with the reason. Do **not** report that entry as DRIFT. Report the record itself when `lint-repo` says it declines nothing.
 - **Bundled defaults applied at runtime.** Some config is materialized from the bundled template at runtime when the file is absent, so no on-disk copy is needed. **Absence of these files is not a problem**: it is the intended state when the user is happy with the bundled policy. Only flag DRIFT if the user wants to deviate from it. Exactly five tools carry such a fallback, the ones whose `ToolSpec` sets `default_config` in `repomatic/tooling/tool_registry.py`: `actionlint`, `mdformat`, `ruff`, `yamllint` and `zizmor`.
-- **A `[tool.X]` section is never a candidate for deletion.** The inverse of the rule above, and the more expensive mistake. Every other tool has no `default_config`, so its resolution chain has no level 3 to fall back on: `lychee`, `typos`, `mypy`, `pytest`, `coverage`, `bumpversion` and `uv` are *deployed* into `pyproject.toml` by `repomatic init`, and that section is the only config the tool will ever see. Deleting it does not restore inheritance from a bundled default, it drops the tool to level 4 and runs it bare, silently discarding every rule the section held. Read the tool's `default_config` before proposing a section be dropped "to inherit upstream updates". Re-running `repomatic init` fixes a stale section only for the components marked `SyncMode.ONGOING` in `repomatic/registry.py` (`lychee`, `typos`, `bumpversion`, `uv`). It never revisits a `mypy`, `pytest` or `coverage` section after the first write: `lint-repo` warns on each bundled template entry such a section lacks, to copy by hand or decline on purpose.
+- **A `[tool.X]` section is never a candidate for deletion.** The inverse of the rule above, and the more expensive mistake. Every other tool has no `default_config`, so its resolution chain has no level 3 to fall back on: `lychee`, `typos`, `mypy`, `pytest`, `coverage`, `bumpversion` and `uv` are *deployed* into `pyproject.toml` by `repomatic init`, and that section is the only config the tool will ever see. Deleting it does not restore inheritance from a bundled default, it drops the tool to level 4 and runs it bare, silently discarding every rule the section held. Read the tool's `default_config` before proposing a section be dropped "to inherit upstream updates". Re-running `repomatic init` fixes a stale section only for the components marked `SyncMode.ONGOING` in `repomatic/registry.py` (`lychee`, `typos`, `bumpversion`, `uv`). It never revisits a `mypy`, `pytest` or `coverage` section after the first write: `lint-repo` warns on each bundled template entry such a section lacks, to copy by hand or to decline with a reason under `[tool.repomatic] lint-repo.declined`.
 - **Generator artifacts vs user error.** When local thin-callers diverge from upstream (e.g., extra `workflow_dispatch:`, missing `paths:`), the cause may be the **upstream generator**, not downstream tampering. Inspect `repomatic/github/workflow_sync.py` (`generate_thin_caller`, `_adapt_trigger_paths`, `generate_workflow_header`) before recommending the user re-run `repomatic init` to "fix" something `init` itself produced.
 - **Project-level `claude.md` may live under a sub-directory.** `[tool.repomatic] subagents.location` and `skills.location` indicate a project where `.claude/` is not at the root (e.g., dotfiles repos with `dotfiles/.claude/CLAUDE.md`). Search the configured location, not just `./CLAUDE.md`.
 
@@ -57,6 +58,21 @@ Keep the two axes apart in the report, because only one of them is actionable:
 
 ### 1. Workflow audit (`workflows`)
 
+#### Ask the generator first
+
+Before you compare a managed file by hand, run the adopted release's generator on a throwaway copy of `HEAD`:
+
+```shell-session
+$ git worktree add --detach {scratch}/audit HEAD
+$ uvx --no-progress --exclude-newer '1 week' --exclude-newer-package repomatic=P0D --directory {scratch}/audit 'repomatic==X.Y.Z' init
+$ git -C {scratch}/audit diff
+$ git worktree remove --force {scratch}/audit
+```
+
+An empty diff means every thin caller, each header-only workflow header and each ongoing-sync `[tool.X]` section equals what that release generates. Any hunk is DRIFT that the sync would rewrite. Keep `--directory`: `--output-dir` alone writes into the copy but reads `[tool.repomatic]` from the directory the command started in.
+
+The generator does not read hand-owned jobs, the comment beside a synced key, or an entry only the local file carries. Compare those yourself, in the sections below.
+
 #### Thin-caller workflows
 
 Compare each local thin-caller workflow against its reference. These should be identical (except for files listed in `exclude`). Flag:
@@ -106,7 +122,7 @@ Compare these files against the upstream reference. **Before flagging absence as
 | `.gitignore`                          | Must be a real file: git skips an in-tree `.gitignore` reached via symlink; otherwise content vs upstream         | Auto-generated by repomatic; drift means the user should re-run sync.                                                                                    |
 | `pyproject.toml` `[tool.lychee]`      | Note differences (usually project-specific, just flag for review); a root `lychee.toml` wins as native config     | Project doesn't run lychee.                                                                                                                              |
 
-**Skip** files that are intentionally excluded via `exclude` in `[tool.repomatic]`. Cross-check `[tool.ruff] extend-exclude` and similar before flagging "missing" entries.
+**Skip** files that are intentionally excluded via `exclude` in `[tool.repomatic]`, and settings declined under `lint-repo.declined`. Cross-check `[tool.ruff] extend-exclude` and similar before flagging "missing" entries.
 
 ### 3. Upstream contribution opportunities (`upstream`)
 

{repomatic-7.17.0/repomatic/data → repomatic-7.18.0/.claude}/skills/repomatic-deps/SKILL.md

@@ -38,7 +38,9 @@ You help users understand and maintain their project's dependencies. This skill
 
 ### Mechanical layer
 
-The `_release-engine.yaml` workflow's `update-dep-graph` job regenerates the dependency graph on release commits only, to avoid noise from transitive dependency changes. This mode is useful for **interactive analysis** — understanding the graph, spotting concerns, or generating it before pushing.
+The `autofix.yaml` workflow's `update-dep-graph` job regenerates the dependency graph on every push, for packages and uv virtual projects alike. This mode is useful for **interactive analysis** — understanding the graph, spotting concerns, or generating it before pushing.
+
+With `[tool.repomatic] dependency-graph.update = false`, the `update-dep-graph` command exits without writing a graph, and the job opens no pull request. Tell the user so, and skip this mode.
 
 ### Argument handling
 
@@ -77,21 +79,27 @@ These conventions are derived from the `pyproject.toml` files across all `kdeldy
 1. **Use `>=` (not `~=` or `==`).** Relaxed lower bounds give packagers freedom to release security hotfixes without waiting for an upstream bump. Upper bounds are forbidden per [https://iscinumpy.dev/post/bound-version-constraints/](https://iscinumpy.dev/post/bound-version-constraints/).
 2. **Every version bound needs a comment tying the floor to a concrete code dependency.** The comment goes on the line above the dependency and states which feature, method, or API from that version the project actually uses. Prefer referencing the call site or module that depends on it:
    ```toml
-   # wcmatch 10.0 changed globbing semantics; our sync_gitignore() relies on
-   # the new symlink-aware matching behavior.
-   "wcmatch>=10",
+   dependencies = [
+     # wcmatch 10.0 changed globbing semantics; our sync_gitignore() relies on
+     # the new symlink-aware matching behavior.
+     "wcmatch>=10",
+   ]
    ```
    A good floor comment answers: "if someone installed an older version, what would break and where?" If you cannot point to a concrete usage, the floor may be unnecessarily high.
    **A floor comment documents the floor as it stands, in one short paragraph.** It is not a record of how the floor got there. Left alone it drifts that way on its own: each bump appends a paragraph about the newly required version, nothing is deleted, and the comment becomes a private changelog of the dependency with the declared version buried under the floors it replaced. When raising a floor, **rewrite the comment rather than extending it**: keep what the new version buys (API, fix, `requires-python` alignment, the call site consuming it, a CVE or upstream issue identifier), delete every superseded floor (`git log -- pyproject.toml` keeps that history), and move out what is not about this floor (usage detail belongs in the module using it, a comparison against an alternative package in an `XXX` pointer to the upstream ticket). `lint-deps` warns past 40 words, which is the ceiling to write to even where it is not run.
    **Security fixes are also a valid floor bump reason.** A CVE or advisory in an older version justifies raising the floor even when the API is unchanged. The comment should cite the CVE or advisory:
    ```toml
-   # requests 2.32.0 fixes CVE-2024-35195 (session credential leak on redirects).
-   "requests>=2.32",
+   dependencies = [
+     # requests 2.32.0 fixes CVE-2024-35195 (session credential leak on redirects).
+     "requests>=2.32",
+   ]
    ```
-3. **Python version support is not a valid reason to bump a floor.** The dependency resolver already picks the right version via `requires-python` metadata. If `boltons>=20` works and boltons 25 merely adds Python 3.13 support, keep `>=20` — the resolver handles it. **Exception:** when a dependency *drops* a Python version your project still supports (or your project drops one, aligning minimum `requires-python`), that alignment is a valid floor bump reason. The comment should state the version range alignment, not the Python support:
+3. **Python version support is not a valid reason to bump a floor.** The dependency resolver already picks the right version via `requires-python` metadata. If `mango>=2` works and mango 5 merely adds Python 3.13 support, keep `>=2` — the resolver handles it. **Exception:** when a dependency *drops* a Python version your project still supports (or your project drops one, aligning minimum `requires-python`), that alignment is a valid floor bump reason. The comment should state the version range alignment, not the Python support:
    ```toml
-   # boltons 25.0.0 dropped Python 3.9, matching our requires-python >= 3.10.
-   "boltons>=25",
+   dependencies = [
+     # coverage 7.11.0 dropped Python 3.9, matching our requires-python >= 3.10.
+     "coverage>=7.11",
+   ]
    ```
 4. **Use conditional markers for Python-version-gated deps.** Example: `"tomli>=2; python_version<'3.11'"`. When a dep has a version marker, the floor rationale must make sense for the Python versions where the dep is actually installed — not for versions excluded by the marker.
 5. **Alphabetical order** within the list.
@@ -120,6 +128,7 @@ Read the full `pyproject.toml`. `lint-deps` already reports the specifier style,
 | Stale comment             | Comment references a reason that no longer applies (the cited method was replaced, or the Python version left the support matrix)                               |
 | Accreted comment          | Comment narrates superseded floors beside the declared one. Rewrite it around the version in force; `lint-deps` catches only the long ones                      |
 | Inflated floor            | Floor higher than the oldest version providing the APIs actually used (see [floor verification](#floor-verification) below)                                     |
+| Understated floor         | Floor lower than the oldest version the code runs on (see [lowest-version check](#lowest-version-check) below)                                                  |
 | Marker/rationale mismatch | Floor rationale contradicts the conditional marker (e.g., "Python 3.14 wheels" on a dep gated by `python_version<'3.11'` — that dep is never installed on 3.14) |
 | Section style             | `[project.optional-dependencies]` used where `[dependency-groups]` would be appropriate                                                                         |
 | Conditional markers       | Missing Python version marker for backport packages                                                                                                             |
@@ -132,7 +141,19 @@ Comments and changelogs can lie; the codebase is the source of truth. For each d
 1. **Grep for imports.** Search the source tree for all imports from the package. List the specific APIs used (functions, classes, constants).
 2. **Determine the oldest version providing those APIs.** Check when the API was introduced — changelogs, release notes, or `pip index versions <pkg>` to see what exists on PyPI. A floor that rests on a behavior (comments kept, output formatting) needs a bisect instead, since a changelog can credit it to a later release than the one that shipped it. Run one probe per release with `uv run --no-project --exclude-newer '1 week' --with '<pkg>==<version>' python probe.py`, and compare each output byte for byte with the locked release.
 3. **Lower the floor** when it exceeds the oldest compatible version. Prefer conservative minimums (the major version that introduced the API) over aggressive ones. Update both the version specifier and the comment.
-4. **Run `uv lock`** after any floor change to verify the lock still resolves.
+4. **Run `uv lock`** after any floor change to verify the lock still resolves. Run it with the uv version the workflows pin on their `setup-uv` steps, like `uvx --exclude-newer '1 week' --from 'uv==X.Y.Z' uv lock`: a newer local uv rewrites the lockfile `revision` and adds tables that CI never writes. After a floor raised in one dependency group only, add `--upgrade-package <pkg>`: a group with its own `requires-python` resolves as a separate fork, and a plain `uv lock` keeps the old pin in the other one.
+
+#### Lowest-version check
+
+A floor can also be too low: the code calls an API that the declared version lacks. The lockfile holds the newest release of each dependency, so no ordinary test run shows it, and the first to see it is a user on an old environment.
+
+1. **Resolve every direct dependency at its floor.** Run `uv pip compile pyproject.toml --resolution lowest-direct --exclude-newer '1 week' --python-version <floor>`, with the lowest Python the project supports. It prints the set and installs nothing.
+2. **Compare the output with the declared floors.** A package resolved above its floor is held there by another requirement, so no install can reach the declared version. Report it as **Info**, with the requirement that holds it.
+3. **Run the suite on the lowest set.** In a throwaway `git worktree`, `uv sync --resolution lowest-direct --all-extras --group test` installs it and `uv run --frozen -- pytest` tests it. The sync rewrites `uv.lock`, so keep it out of the main checkout. When the test matrix carries a `lowest-direct` cell, read its last CI result instead.
+4. **Probe what the suite cannot see.** Two cases pass the suite and still break a user. The test tooling can hold a dependency above its floor, as pytest does for `packaging`. A mocked client hides the library behind it. For each one, write a script that makes the call the code makes, and run it against the floor: `uv run --no-project --exclude-newer '1 week' --with '<pkg>==<floor>' python probe.py`.
+5. **Raise a floor that fails**, to the first release that passes. Name the failing call in the comment.
+
+To test one floor alone, build an environment from the lockfile and swap that package in with `uv pip install --exclude-newer '1 week' --no-deps '<pkg>==<floor>'`. `uv run --with` resolves the package's own dependencies again, so a failure there can come from another package.
 
 #### Special cases
 
@@ -165,12 +186,12 @@ These comment patterns typically signal a floor set at adoption or auto-bump tim
 
 The `[tool.uv]` section may contain `exclude-newer-package` entries that exempt specific packages from the global `exclude-newer` cooldown window. They arrive from two places: written by hand (the package is published by the same maintainer, or is developed in-repo), or written by `audit --fix`, which reaches a CVE fix still inside the window through an entry rather than lifting `exclude-newer` for the whole tree.
 
-**Expiry is mechanical, so do not audit for it.** `sync-uv-lock` owns the lifecycle of every entry and reports each move in its PR body: it rewrites a relative span (`"0 day"`) into a fixed cutoff pinned to the locked version's upload time, which *holds* the package instead of letting it track latest, then prunes the entry outright once that held version ages past the global cooldown and the package rejoins normal resolution. A live fixed cutoff is therefore a freeze doing its job, not a leftover: proposing its deletion un-holds a package the freeze was deliberately pinning. A surviving relative span means the freeze has not run yet, not that a span is the steady state.
+**Expiry is mechanical, so do not audit for it.** `sync-uv-lock` owns the lifecycle of every entry and reports each move in its PR body: it rewrites a relative span (`"0 day"`) into a fixed cutoff pinned to the locked version's upload time, which *holds* the package instead of letting it track latest, then prunes the entry outright once that held version ages past the global cooldown and the package rejoins normal resolution. A live fixed cutoff is therefore a freeze doing its job, not a leftover: proposing its deletion un-holds a package the freeze was deliberately pinning. A surviving relative span means the freeze has not run yet, except on a package with no upload time in the lockfile: one consumed from a git or path source, or one the lockfile does not hold. That span stays as written.
 
 What is left for this audit is the part no schedule settles:
 
-1. **Is the package still a dependency?** If it was removed from `[project].dependencies` and all `[dependency-groups]`, the entry is dead weight that no prune will ever reach, since pruning keys off the locked version's age and the package is no longer in the lock.
-2. **Is a hand-written exemption still justified?** A same-maintainer or in-repo package keeps its span indefinitely and correctly. An external package exempted during a migration that has since finished no longer needs one.
+1. **Is the package still a dependency?** If it was removed from `[project].dependencies` and all `[dependency-groups]`, a relative span on it is dead weight that no prune will ever reach. A fixed cutoff needs no audit there: `sync-uv-lock` prunes it once the cooldown window has passed the cutoff itself.
+2. **Is a hand-written exemption still justified?** A package consumed from a git or path source keeps its span indefinitely and correctly. A same-maintainer package on an index does not: its entry admits one release, and is written again for the next one that must not wait. An external package exempted during a migration that has since finished no longer needs one.
 3. **Does the comment explain the reason?** Like version floors, a hand-written exemption should carry a comment naming why the cooldown does not apply to it.
 
 Flag those as warnings. Never flag an entry merely for existing or for looking old.
@@ -188,10 +209,10 @@ Produce:
 
 1. **Policy compliance summary**: A table with one row per dependency: name, specifier, has comment (yes/no), issues found.
 2. **Grouped findings** by severity:
-   - **Errors**: Wrong specifier style, missing version, upper bounds.
+   - **Errors**: Wrong specifier style, missing version, upper bounds, understated floors.
    - **Warnings**: Missing or stale comments, ordering issues, inflated floors, marker/rationale mismatches.
-   - **Info**: Suggestions for floor adjustments based on API verification or cross-repo data.
-3. **Suggested fixes**: For each error/warning, show the current line and the recommended replacement. For inflated floors, include the verified API minimum and a rewritten comment.
+   - **Info**: Suggestions for floor adjustments based on API verification or cross-repo data, and floors that no install can reach.
+3. **Suggested fixes**: For each error/warning, show the current line and the recommended replacement. For inflated floors, include the verified API minimum and a rewritten comment. For understated floors, include the failing call and the first release that passes.
 
 ---
 
@@ -279,7 +300,7 @@ Common false-positive patterns to reject early:
 
 1. **Find the version deltas.** Determine which dependencies changed, and from and to which version, cheapest source first:
 
-   - The most recent `sync-uv-lock` PR — its body lists every bump with its old and new version and a changelog or compare link per package. Find it with `gh pr list --search 'head:sync-uv-lock' --state all --limit 1`, then `gh pr view <number> --json body`.
+   - The most recent `sync-uv-lock` PR — its body lists every bump with its old and new version and a changelog or compare link per package. Find it with `gh pr list --search 'head:sync-uv-lock' --state all --limit 1`, then `gh pr view <number> --json body`. That body covers one sync only: when several merged since the last release tag, diff the lockfile against the tag to get the whole range.
    - Failing that, find the last release tag (`git tag --sort=-v:refname | head -1`) and diff the lockfile against it (`git diff <tag> -- uv.lock`), reading the version pairs.
    - For a single named package, read its locked version and the `pyproject.toml` floor.
 

{repomatic-7.17.0 → repomatic-7.18.0}/.claude/skills/repomatic-init/SKILL.md

@@ -38,4 +38,3 @@ You help users bootstrap a repository to use the reusable GitHub Actions workflo
 Suggest the user run:
 
 - `/repomatic-audit` to check the generated files against upstream conventions.
-- After pushing, the `autofix.yaml` and `lint.yaml` workflows keep the workflow callers synced and validated automatically.