Przejdź do treści
Biblioteka skilli
DevOps i chmura · Automatyzacja

repomatic-ship

/repomatic-ship

Przygotowuje wydanie i prowadzi CI do zielonego main, uzgadniając changelog, kod i dokumentację, a scalenie zostawia człowiekowi.

Repozytorium
dotfiles ↗
Licencja
BSD-2-Clause
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

BSD-2-Clause, otwarta.

Co robi i kiedy

Przygotowuje wydanie i prowadzi CI do zielonego main, uzgadniając changelog, kod i dokumentację, a scalenie zostawia człowiekowi.

Oryginalny opis (EN)

Prepare a release. Reconcile the changelog, code and docs to the net release state. Then commit, push, and babysit CI until the release PR is built and `main` is green. Stop before the merge. Ask for review in normal use; run fully autonomous under `--dangerously-skip-permissions`.

Jak działa

  1. Context
  2. Instructions
Sekcje z nagłówków SKILL.md, w oryginale · 317 linii, 13 071 słów
Podgląd SKILL.md
---
name: repomatic-ship
description: Prepare a release. Reconcile the changelog, code and docs to the net release state. Then commit, push, and babysit CI until the release PR is built and `main` is green. Stop before the merge. Ask for review in normal use; run fully autonomous under `--dangerously-skip-permissions`.
compatibility: 'Designed for Claude Code. Recommended model: Opus.'
allowed-tools: Bash Read Grep Glob Skill Agent
---

## Context

!`grep -m1 'version' pyproject.toml 2>/dev/null`
!`awk '/^## \[/{n++} n==2{exit} {print}' changelog.md 2>/dev/null`
!`git tag --sort=-v:refname | head -3 2>/dev/null`
!`git log --oneline -25 2>/dev/null`
!`git status --short 2>/dev/null`
!`[ -f repomatic/__init__.py ] && echo "CANONICAL_REPO" || echo "DOWNSTREAM"`
!`grep -rhoE 'kdeldycke/repomatic/[^@ ]+@[0-9a-f]{40} # v[0-9.]+' .github/workflows 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+$' | sort -u | sed 's/^/WORKFLOW_PIN=/'`

## Instructions

You drive a release from a working tree to a ready-to-merge release PR: reconcile the tree to its **net state since the last tag**, validate it locally, commit and push, then babysit CI until the auto-generated release PR is green. You stop there: the human marks the draft release PR ready for review and performs the final "Rebase and merge".

The release is push-driven: the `prepare-release` job in `changelog.yaml` runs `repomatic prepare-release` on push to `main` to build the freeze and unfreeze commits and open the release PR. **Do not run `prepare-release` yourself**: a local run previews a freeze that must not be committed (it marks the changelog "released", and on the canonical repo rewrites every workflow action ref). Your job is to make `main` clean enough that the auto-generated release PR is correct, then keep `main` green.

### How this skill runs

- **The review gate is the permission system, not a behavioral stop.** Normal runs prompt on each `git commit`, `git push`, and subagent write; step 4 shows the consolidated changelog diff *before* the first commit prompt, so approving that commit is the review gate and denying it stops the run. `--dangerously-skip-permissions` mutes the prompts so the full sequence runs autonomously; the skill cannot detect the mode.
- **Invocation method.** When the context shows `CANONICAL_REPO`, use `uv run repomatic`. Otherwise use `uvx --exclude-newer '1 week' --exclude-newer-package repomatic=P0D --from 'repomatic==X.Y.Z' -- repomatic`, with `X.Y.Z` the `WORKFLOW_PIN` the context shows. This applies the supply-chain cooldown to repomatic's dependency tree while keeping a fresh release installable. The pin matters because the tool registry ships inside repomatic: a newer release pins newer `ruff`, `typos` or `mypy` than the ones CI runs, and a gate built on it stops reproducing CI. Drop the `--from` clause only when the context shows no `WORKFLOW_PIN`. References to `<cmd>` below resolve to one or the other.
- **Delegate the substance edits, apply the changelog yourself.** The sweep agents own the code, docs and bundled-asset lanes, so leave those files to them even when you do hold `Edit`/`Write`. The changelog is the exception: a skill is instructions rather than an actor, and `/repomatic-changelog` tells whoever loaded it to apply the consolidation directly, so you write `changelog.md` inline.

### Sub-agent rules

The sweep agents (step 1) and the babysitter (step 6) all follow these rules. Restate them in every spawn prompt: a spawned agent only sees what the prompt carries.

- **Commit attribution.** Every commit this skill or any spawned agent makes carries a `Co-Authored-By: Claude <noreply@anthropic.com>` trailer **by default**, so unattended changes stay traceable, and that default holds even where a downstream `CLAUDE.md` says nothing about commit attribution. A maintainer's explicit standing rule against AI attribution outranks it, because the trailer lands in *their* repository's permanent history. Check for such a rule **before the first commit**: stripping a trailer from an already-pushed commit needs a force-push, which is off-limits. When an exemption applies, write it into the spawn prompt of every agent that may commit: a withdrawal issued mid-run can arrive after the agent has committed.
- **Reports are sent, not written.** A background agent's end-of-turn text is not a channel to rely on, so every spawn prompt must require the final report as a `SendMessage` to the **spawning (main) session**, naming that recipient explicitly: the spawning session answers to `main`, while an invented label like "orchestrator" or "main-orchestrator" resolves to nothing. An agent type whose `tools:` line omits `SendMessage` (`qa-engineer`, `sphinx-docs` and `grunt-qa`) can still hold it when spawned with a `name`. When no message arrives, read the idle notification's text before chasing, since it can carry the report of an agent that could not send one. Chase once when it holds none; the tree (`git diff`) stays the authoritative record either way. Do not pair the message with a "write the same report to a file" fallback: the harness refuses a spawned agent that write.
- **Expand `<cmd>` before it reaches a spawn prompt.** `<cmd>` is this document's placeholder, not a shell command, and a prompt that carries it verbatim (or half-expanded) hands the agent something that cannot run. The trap is `run <tool>`: the tool registry supplies most of them, so dropping the `repomatic run` prefix fails outright. A spawn brief that expands `<cmd> run mypy --` into `uv run --frozen -- mypy --` dies on `Failed to spawn: mypy`, since mypy is not a project dependency. Write the invocation out in full (`uv run repomatic run mypy --`) and let the agent report back if it does not resolve.
- **Trust the tree, not the report.** A mid-run message to a busy agent can land after the agent composed its final report and be silently dropped. A named agent reads its inbox when its turn ends (Claude Code `2.1.284`, 2026-10-04): its final report then answers none of the messages sent during that turn, and a second report follows once it has read them. Before you chase, check that it shows as `running` again. After tasking a running agent, confirm the tree reflects the request (`git diff` the target file) before moving on. Read fresh every time: an edit can land in the gap between two checks. Grep for the *absence* of the old text (`grep -c '<old phrase>' <file>` returning `0`) instead of eyeballing a diff.
- **Never let one lane wait on another lane's edit.** Messages cross: an agent can ask a sibling for a change while you reassign that file, then wait on an edit nobody will make. Name one owner per file in the same message to both agents, and when an agent reports it is blocked on another lane, make the edit yourself and tell it the edit landed.
- **Never revert the shared working tree.** The agents share one tree, so no agent may run a working-tree-reverting git command (`checkout`, `restore`, `stash`, `reset`, `clean`), which silently discards the *other* agents' uncommitted edits. The rule binds investigation too: an agent comparing its file against the committed state reaches for `git stash`, which takes the whole tree. Say so in the spawn prompt, and name the read-only alternative beside it, `git show HEAD:<path>`. For full isolation instead, spawn with `isolation: "worktree"` and merge on join: disjoint files won't conflict.
- **Fix commits stage narrowly** (`git commit <path>`, never `-a`). Uncommitted files an agent did not create are the maintainer's in-progress work: never revert them and never sweep them into a commit. So is a hunk the agent did not write inside a file it edits: report it, and never document or build on it.
- **Degrade gracefully.** A cross-referenced skill excluded from this repo is a fallback path, not a blocker: apply its principle via an `Agent` or inline. When an `Agent` spawn itself fails (a terminal API error), do the work in the main thread. An agent that dies mid-run (a machine put to sleep, a lost login, a restarted session) sends no report and can stop halfway through a refactor. A `SendMessage` resumes it only while the session that spawned it is alive. Before you take its lane over, prove the package still imports, then read its diff file by file.

### 1. Reconciliation sweep

A release materializes the **net state since the last tag**, not the path taken to reach it. Reconcile the changelog, the code and the docs against `git diff v<last>..HEAD`. Order matters: the changelog *describes* the net change, so reconcile the substance first (code and docs in parallel), then summarize it (changelog). A change introduced and then reverted before release is a no-op for users: no changelog entry, no scaffolding, no docs mention.

**Before spawning, capture the unstaged diff** (`git diff` against `HEAD`): those lines are the maintainer's in-progress drafts, not cycle work. Pass both diffs to each agent with the rule: preserve every line present only in the unstaged set (a curated TODO, a scratch note in a docstring) unless the maintainer explicitly asked for cleanup. Without the guard an agent strips unstaged scratch as "cycle scaffolding". When in doubt, leave it.

**Capture the job-level red inventory in the same breath**: the latest *conclusive* run of each monitored workflow on `main` (`gh api 'repos/<owner>/<repo>/actions/workflows/tests.yaml/runs?branch=main&created=>=<date>'`, then `gh run view <id> --json jobs`), listing every job at `conclusion == "failure"`, `⁉️` probes included: `continue-on-error` folds their crashes into a green run-level conclusion. Read `release.yaml`'s canary `✅ <os>, <sha> build` job too: its `Self-test binary` step runs the CLI test plan against the freshly compiled binary, and a toolchain pin bump upstream (a Nuitka release miscompiling a dependency) reddens it with no line of this repository changed. Under step 6's genuinely-green goal those reds are release work, and every one fixed before the first push saves a 40-90-minute babysit round-trip: seed the code agent's brief with the list.

**Read runs through the API, not the `gh run list` wrappers.** Both the branch-wide form and the per-workflow form have put runs weeks old at the top of the list, which invents a red inventory. Two API calls are the authoritative reads: `gh api 'repos/<owner>/<repo>/actions/runs?head_sha=<sha>'` answers "what ran on this commit", and `gh api 'repos/<owner>/<repo>/actions/workflows/<file>/runs?branch=<branch>'` answers "what ran on this branch", but only with a `created=>=<date>` filter appended: without one the page can be days stale. A date range (`created=2026-09-01..2026-09-09`) walks the older weeks. Give the `head_sha` form the **full** 40-character SHA: an abbreviated one returns an empty list, which looks identical to "nothing ran".

**Scan the open autofix PRs in the same breath, and read their diffs rather than their titles.** An unattended `fix-*`/`format-*`/`sync-*` PR is a pending write to `main` that no one reviewed, and merging one mid-release silently reverts committed work: `gh pr list --state open --json number,headRefName,title` then `gh pr diff <n>` on every automated branch. Look for a *false positive*: a "fix" that is wrong in this repository and that the job re-proposes until the rule is taught otherwise. The tell is a diff that undoes something a human deliberately wrote. Fix it at the rule, not the file: add the word to `[tool.typos] default.extend-words`, the path to the linter's ignore list, the pattern to `extend-ignore-re`. Reverting the file alone guarantees the same PR returns on the next run.

**Judge that diff against current `main`, not against the PR's head.** An open PR is pinned to the commit it branched from, so its diff can describe a file the maintainer has since fixed. Rewording is the third option beside allowlisting and reverting: dropping the trigger word also stops the job re-proposing, and a rule landed on top of it then allowlists a word that appears nowhere. So `git grep` the trigger before writing a rule for it, and when the maintainer already solved it their way, leave it alone. Closing or merging the PR is theirs to decide: surface it, land the rule-level fix **only while the trigger is still live in the tree**, and say either way in the step-7 report.

**Always read that run's `head_sha`, and treat a red as live only if nothing since it could have fixed it.** Most monitored workflows carry a `paths:` filter, so a commit that touches nothing in the filter triggers no run. When *that* commit is the one that fixed the red, the latest conclusive run stays pinned to the superseded parent and keeps reporting a failure that no longer exists. Before adding a red to the brief, run `git log --oneline <run head_sha>..HEAD` and check whether an intervening commit touched the failing area; when the answer is unclear, settle it for the cost of one dispatch (`gh workflow run <workflow> --ref main`, no commit, no PR churn) rather than reasoning about it.

**A green conclusive run proves nothing when supersession cancelled every run between it and `HEAD`.** Walking back past `cancelled` runs to reach the newest conclusive one skips exactly the commits a busy cycle pushed most recently, so that `success` can predate every line the cycle added, and a false green ships the break. Before recording an empty red inventory, diff the gap: `git log --oneline <newest success head_sha>..HEAD`. When cycle commits sit inside it, the workflow has never run on them and the green is stale. Settle it with a dispatch (`gh workflow run <workflow> --ref main`, no commit, no PR churn) or by waiting out `HEAD`'s own run, never by recording "no reds".

The three substance passes own disjoint lanes (code owns Python including docstrings, docs owns prose under `docs/` and `readme.md`, bundled assets owns `.claude/`), so spawn every lane that has work as **one `Agent` call each, all in a single tool-call block**: sequential spawns waste the wall-clock of whichever finishes first.

1. **Code**: an `Agent` that reviews every file changed since the last tag for reuse, quality, simplification, and deduplication, and fixes what it finds, simplifying before adding: existing code or a tool often already covers the case. Two layers: first strip scaffolding from reverted or superseded work within the cycle diff (abandoned workarounds, dead branches, WIP notes that never shipped); then harmonize what remains (collapse duplication, lift repeated literals to their canonical source, align new code with module patterns). Its constraints:

   - Every edit stays behavior-preserving: step 2 is the safety net, a failing test vetoes.
   - A defect in code the cycle added is the exception: it is release work. The agent fixes it in the pass, with a test that fails on the pre-fix lines. It never reached a release, so it takes no changelog entry. Write this into the brief: an agent told only to preserve behavior holds the fix back and asks, and the answer reaches it a full round later (sub-agent rules, trust the tree). A defect that predates the cycle is reported instead.
   - Type checks use the CI-equivalent `<cmd> run mypy` (pinned version and `--python-version`), never a bare `mypy` whose newer interpreter raises false positives CI never sees. Pass it **no arguments**, exactly as step 2's Types gate does: the runner then resolves the same tracked-`*.py` list CI's lint job checks, `tests/` and `docs/conf.py` included. A downstream `CLAUDE.md` "type checking" command is often the narrow dev-loop form scoped to the package only: do not inherit that scope, since a package-only run stays green on a `tests/` or `docs/` type error that reddens Lint post-push.
   - Failures the pass believes pre-existing get *reported*, not silently scoped out: that verdict belongs to step 2's CI check.
   - Adopting features from upgraded dependencies stays in `/repomatic-deps modernize`.
   - On the canonical repo, workflow invocations reading `uv --no-progress run --frozen -- repomatic` are the intended unfrozen state (the freeze commit rewrites them to a `uvx 'repomatic=={version}'` PyPI pin at release): never flag the local form as a pin regression or downstream breakage. The invariant to check instead is that every `uv`-invoking job provisions `setup-uv` in its own steps. Do not "restore" an isolated `uvx --from .` here: an index resolution can be made unsatisfiable by the install cooldown while a lockfile cannot.
   - Docstring rendering belongs to this pass: build the docs and fix any broken cross-reference role a docstring introduced (the docs pass can surface but not fix them). Build in a separate environment, with `{scratch}` a directory outside the repository: `UV_PROJECT_ENVIRONMENT={scratch}/docs-venv uv run --frozen --all-extras --group docs -- sphinx-build --fresh-env -b html docs docs/_build/html`. The shared `.venv` then keeps the CI-matching groups, which the `docs` group would perturb (see step 2's `--all-groups` warning). `--fresh-env` re-reads every page: an incremental build reports warnings only from the pages it re-read. A checked-in `:mirror:` block whose cells embed source-line anchors is invalidated by every edit that moves a line in the anchored modules, docstring rewraps included: expect the `update-docs` autofix PR to refresh it after the push, and take that PR's file (`gh api 'repos/<owner>/<repo>/contents/<path>?ref=update-docs' -H 'Accept: application/vnd.github.raw'`) when a local regeneration would differ from CI's, as a terminal-dependent width does, or when `gh pr merge` is permission-walled. Build only into the gitignored `docs/_build`, never an ad-hoc path: a stray build tree pollutes `git status` and trips tool scans like `run typos`.
   - **A docs build that already warns needs a baseline.** Without one, the pass cannot tell the cycle's warnings from older ones, and fixes them all. Build the last tag in a throwaway `git worktree`, then compare the two warning lists with their line numbers removed. A warning the tag build lacks is one the cycle added: fix it. A warning both builds hold predates the cycle: report one count per category, and leave it.
   - Shortening an over-long workflow line to satisfy yamllint's 120-char limit must not lift `hashFiles(...)` (or any `runner.*`) into a workflow-level `env:` var: that context exposes only `github`/`secrets`/`inputs`/`vars`, so the expression resolves to empty at run-init before checkout and silently breaks the value. Shorten the literal itself instead (trim a shared key prefix, say).
   - The red inventory from the pre-spawn capture is part of its brief: root-cause each repo-fixable red (a chronic platform break, a flaky live-registry install, a crashing `⁉️` probe) and fix it at the source per step 6's taxonomy, even when the failing file saw no change this cycle.
   - Pending work the cycle introduced belongs in a ```` ```{todo} ```` admonition where Sphinx renders it, not in a bare `# TODO`/`XXX` comment: a comment never reaches the published todo list. This applies to **committed** cycle-diff lines only: a `# TODO` present only in the unstaged set is the maintainer's draft and stays untouched.
   - Retire a `{todo}` whose trigger fired, deleting the shim it guards in the same edit. Bound the check to what moved: `git diff v<last>..HEAD -- pyproject.toml uv.lock` plus the tool-version registry names the upstream releases this cycle actually adopted, and a todo naming one of them is the only kind worth re-reading. Read the trigger's own wording against that diff: a todo waiting on the dependency *floor* fires only when `pyproject.toml` raises it, never on a `uv.lock` bump that merely installs the release, and a shim the old floor still needs gets its todo re-scoped to that floor rather than deleted. Never poll every linked ticket, and leave a todo whose trigger has not fired alone.

2. **Docs**: an `Agent` that verifies prose docs against current behavior, not the journey (version references, CLI output, removed or renamed features go stale every cycle). Its constraints:

   - Manually-maintained version examples (install commands, binary download URLs, `uses:` refs) track the latest *released* tag, never the version being prepared, because the docs site deploys on every push to `main`. "Manually-maintained" is not a synonym for "under `docs/`": the freeze reaches into that tree in at least one repo (the canonical one rewrites `docs/install.md`), so decide file by file from the freeze's actual scope per the next bullet, never from the path. The tracking runs both ways: advance a sample that *lags* the released tag (still at N-1 after release N published) up to it, applying the bump directly; only bumping a sample forward to the not-yet-released version is off-limits. Grep every version string in `docs/` and `readme.md` rather than trusting a sub-agent's list.
   - **What the freeze rewrites varies by repo.** The canonical repo pins workflow refs and CLI invocations; a downstream freeze may touch only `changelog.md`, `citation.cff`, `__init__.py`, and `pyproject.toml`. Read the last freeze commit's actual diff (`git show <last-freeze-sha>`, never just `--stat`) and treat every version sample it does not rewrite, `readme.md` quick-start output included, as hand-maintained tracking the released tag.
   - **Freeze-management is per line, not per file.** A file the freeze touches can still carry hand-maintained samples it never rewrites, so `--stat` clears the whole file and the stale ones survive.
   - **Settle each sample individually** with `git log -S '<the literal string>' -- <file>`, which shows whether a freeze commit or a human last moved it.
   - **On a cycle that migrated the release tooling itself, the historical freeze under-predicts the new one.** A pre-repomatic freeze touching only `changelog.md` says nothing about the repomatic freeze, which also rewrites `citation.cff`, `__init__.py`, and `pyproject.toml`: treat every version sample as hand-maintained until the regenerated release PR's diff shows the new freeze's actual scope.
   - The mirror of the hand-maintained rule: a freeze-managed field legitimately shows the *dev* version between releases, so never flag one as stale against the released tag or as a dead link. `pyproject.toml`'s `urls.Download` reading `.../releases/tag/vX.Y.Z.devN` (a tag that has no GitHub release yet) is the expected post-bump state that the freeze rewrites to the release tag at cut. Classify a version string by which mechanism owns it before judging it stale.
   - A third owner sits beside hand-maintained and freeze-managed: artifacts regenerated by `autofix.yaml`'s `update-dep-graph` job. It runs on every push, unless `[tool.repomatic] dependency-graph.update` is `false`, and delivers each refresh through its own PR. `docs/assets/dependencies.mmd` therefore lags `pyproject.toml` only while that PR is open: a dependency added since the last refresh is *expected* to be missing until the PR merges. Never hand-forge the file, and never run `<cmd> update-dep-graph` to "fix" it mid-sweep: a local run uses whatever repomatic version the sweep resolved rather than the version the job pins, so it produces churn the next regeneration reverts. Classify a stale-looking generated artifact by the job that owns it before reporting it as drift.
   - **A fourth owner is a version derived from a sibling checked-in file, and it is the only one that breaks something when bumped.** A build recipe in prose stages an artifact and then invokes a spec, manifest or lockfile the repository tracks, so its version must equal what that file declares rather than the released tag. Bumping the prose alone leaves the recipe unrunnable: a walkthrough that downloads `{pkg}-{X.Y.Z}.tar.gz` into `~/rpmbuild/SOURCES`, then builds `{pkg}.spec` with `rpmbuild`, resolves `Source0` through the spec's own `%{version}`. The tell is that the literal sits inside a procedure invoking a file in the repository: read that file's declared version before touching it. `git log -S '<the literal>'` settles the owner, since a derived value is written once by the commit that added the recipe.
   - **A hand-maintained block enumerating a registry population is a drift class the version rules above do not reach.** A readme that pastes a console transcript of a whole collection (a `members` mapping, a `member_ids` set, a name list) or carries a `mirror-src` diagram lags the moment an entry is added, and nothing reports it. Check every such block against the live collection, and derive the file set the change owes from the previous commit of the same kind: `git log -S '<a sibling entry>'` finds the commit that added the last one, and its diff names each file that change had to touch.
   - Executable doc blocks fail open: a `{click:run}` invocation that no longer parses renders the usage error into the published page instead of failing the build (only `click:tree` and `click:config` hard-error). Verify each `{click:run}` invocation against the current CLI, or grep the built HTML for `Error: No such option`-class output.
   - Correcting one description of a convention means correcting *every* description of it in the same pass: a rule restated in more than one place (an overview line and its worked example, two docs pages) drifts as a set, so grep for the sibling statements and align them together.
   - The same "align the siblings" rule governs *quantities*, not just wording. A cycle that measured the same thing twice ships two answers, so cross-check every timing, size, count and ratio a page states against the other statements of it, the changelog's copy included. Surrounding prose that quotes a ratio the tables no longer support is the tell. Report the contradiction with the conflicting values and which one the other statements corroborate, rather than silently re-deriving numbers on hardware that is not the maintainer's.
   - **Commit provenance decides whether a clashing figure is reported or fixed, and the two need opposite handling.** Blame each one (`git log -S`, or read the commit that introduced it). When the older figure entered *earlier in this same cycle* and a later commit measured the thing again, it is superseded intra-cycle scaffolding, which layer 1 of the code pass strips like any other. Replace it, and cite the surviving measurement's source beside it. Only when neither figure obsoletes the other are they independent measurements, and only then does the report-don't-touch rule above apply.
   - The docs build has a single owner, the code agent (which already builds for docstring cross-references): verify prose against that build instead of launching a second `sphinx-build` into the same output dir.
   - A probe of the package runs through the same `uv run` form as the tests, group list included. Another group list re-resolves the shared environment, and a test parametrized over installed plugins then collects a different set.
   - Any docs-pass edit touching a `.py` file (typically `docs/conf.py`) is re-verified with a bare `<cmd> run mypy` before the agent returns: `docs/conf.py` may import from the docs group's higher Python floor while mypy checks the project minimum, and the break otherwise surfaces only in CI's lint job. Give it no arguments, per step 2's Types gate.
   - Changelog *released* sections (`## [X.Y.Z]` blocks) are immutable history: a command, option, or config key named there was correct for that release, so never flag or rewrite a since-renamed name in one. When the changelog seeds the checklist for a rename, reconcile only the unreleased section.
   - A ```` ```{todo} ```` on a docs page follows the same two rules the code pass applies to docstrings: pending work the cycle introduced is written as one rather than as a loose closing sentence, and one whose trigger fired this cycle goes, along with the paragraph it qualified.

3. **Bundled assets**: an `Agent` (use `qa-engineer`, the gatekeeper for agent and skill definitions) that checks `.claude/skills/**` and `.claude/agents/**` against what the cycle actually changed. These files deploy verbatim to every downstream repo through `repomatic init`, and neither substance lane owns them: the code pass sees no Python and the docs pass is scoped to `docs/`. Its constraints:

   - **Scope it to claims the cycle invalidated**, not a general review. Grep the cycle diff for the behaviors these files describe (cadences, gating conditions, job names, default values, config keys) and verify each surviving statement against its source, rather than reading for style.
   - **Verify against the workflow or module, never against the summary in the brief.** A second-hand description is the same failure one level up.
   - Fix the claim, do not rewrite the surrounding strategy: a stale fact inside good advice is a fact bug.
   - A pre-existing error in the same class, found while checking, is in scope — these ship downstream too, and nothing else audits them. Report it separately from the cycle-caused ones so the maintainer can tell which the release introduced.
   - Cross-references must degrade gracefully; skills stay self-contained (no upstream-only `docs/` URLs or paths), since downstream repos have neither.

   **Downstream, the lane covers only what the repository authors.** A skill named in `<cmd> list-skills`, or an agent that `repomatic init subagents` installs, is a synced copy: the next sync overwrites an edit to it, so report a stale claim in one for step 8 instead. When the repository tracks no skill or agent of its own, skip this lane and spawn the code and docs passes alone.

4. **Changelog**: once the substance passes settle, invoke `/repomatic-changelog consolidate` through the `Skill` tool, so the consolidated entries (and the version advisory reading them) reflect the reconciled tree, renames included. It collapses superseded values and drops intra-cycle reverts. Consolidation assumes the entries already exist: when the unreleased section under-represents the net cycle (a maintainer left one stub bullet for a multi-feature cycle), run `add` first, or the bare `/repomatic-changelog` default that runs `add` then `consolidate`. When both `add` and consolidation find nothing user-facing (a purely mechanical cycle), consolidation backfills one generic maintenance bullet rather than leaving the section empty (`/repomatic-changelog` consolidation rule 08). If the skill is excluded here, degrade gracefully (sub-agent rules).

### If the sweep made no edits

A clean cycle, where every change since the last tag is already at its net end-state, is a normal outcome. With **no working-tree edits**, the commit-and-push spine collapses and three steps change shape:

- **Step 2** becomes redundant: CI already ran on this exact commit (it is `HEAD` of `main`), so verify that run's conclusion (`gh api 'repos/<owner>/<repo>/actions/runs?head_sha=<full-sha>'`) instead of paying for a fresh gate. Still quick-run the time-dependent external smoke checks (`<cmd> run typos`, `<cmd> audit --fix`): re-published binaries and new CVEs drift independently of code.
- **Step 5** is a no-op: never force an empty commit.
- **Step 6** reduces to verifying the existing run. When `gh pr list --head prepare-release` shows a PR whose freeze commit sits on the current `HEAD`, confirm every stable job on `HEAD` is green and go to step 7, spawning `/babysit-ci` only on a real failure. When no current PR exists (the last push missed `changelog.yaml`'s `paths:` filter), trigger one with `gh workflow run changelog.yaml --ref main`, still with no commit.

Steps 3, 4, and 7 are unchanged: the version advisory and the (empty) changelog diff still inform the maintainer.

### If the sweep touched only prose

When the sweep's edits are confined to prose and Markdown (`docs/`, `readme.md`, `changelog.md`, `.claude/`; no `.py`, no `pyproject.toml`, no `uv.lock`), the full step-2 gate is disproportionate. Narrow to what step 1's docs and bundled-asset passes do not already own: `<cmd> run mdformat --verify -- <file>` over the changed Markdown, plus `<cmd> lint-changelog` when `changelog.md` changed, plus every test that reads an edited file. Find those with `git grep -l -F '<file name>' -- tests/` for each changed path: a readme roster test or a docs conformance test takes prose as its input, and CI may never run it, since a workflow `paths:` filter can omit the prose file it reads. Run it in the **same position** as the full gate: before the step-5 commit and push, never after.

Step 6 narrows too: watch the run yourself with the takeover watcher it describes, and spawn `/babysit-ci` only on a real failure, as the no-edit branch does.

### 2. Validate locally (pre-push gate)

When the sweep rewrote code, prove it green **before** paying for a CI round-trip (no edits: see above). Launch the slow checks (tests, types, changelog lint) in parallel in the background, act on the fastest failure first (mypy and ruff in seconds, pytest in minutes), fix in the working tree, re-run only what failed, and iterate until every check is green. A check earns a *blocking* seat only while it reports faster than CI would surface the same failure: the push is what starts the 40-90-minute matrices.

**First read CI's conclusions on `HEAD`** (`gh api 'repos/<owner>/<repo>/actions/runs?head_sha=<full-sha>'`): every red job there is cycle work this release must fix, and no "pre-existing failure" claim from the sweep is valid until checked against it.

**Read at the *job* level (`gh run view <run> --json jobs`), never the run level.** `continue-on-error` hides a crashed `⁉️` probe inside a green run conclusion, and this read doubles as the check that the step-1 red-inventory fixes actually landed.

**"The source did not change" never proves "the check still passes".** An in-cycle lockfile bump can invalidate `type: ignore` comments and override signatures with zero source changes.

**When HEAD's own runs are still `queued`/`in_progress`, read an ancestor instead.** Take the latest *conclusive* run of each monitored workflow on an ancestor (`gh api 'repos/<owner>/<repo>/actions/workflows/tests.yaml/runs?branch=main&created=>=<date>'`, skipping the `cancelled`/`skipped` supersession noise a busy cycle piles up). A `failure` there is a pre-existing red carried on `main` for several commits: fix it before the first push. A `success` there is not the mirror verdict: read it against step 1's rule on a stale green. Miss it and a platform-gated failure the single-OS local gate cannot run surfaces only in step 6, at the cost of an extra CI round-trip.

The checks:

- **Tests**: `uv run --frozen --all-extras --group test pytest --no-header -q`. Exception: an integration-heavy suite driving real external tooling can outrun a local background timeout and need tools not installed locally, so it is not a fast gate. Skip it, keep the rest of the gate, and treat the CI matrix on the exact commit as the authoritative test signal (step 6 covers dispatching one). Between the extremes, a suite whose local runtime approaches CI's fast platforms (~5-8 minutes from push) stops blocking: start it with the gate, push once every fast check is green, and fold the still-running suite into step 6 as the first babysit channel.
- **Types**: `<cmd> run mypy`, with no arguments. The runner resolves the same tracked-file list CI's lint job checks, `docs/conf.py` included. Do **not** pass directory names instead (`<cmd> run mypy -- repomatic tests docs`): directories change module resolution enough that mypy follows an installed dependency's own source, so a package pulled in by the `docs` group and written for a newer Python fails the run under `--python-version 3.10` with a syntax error in a file this project does not own.
- **Changelog**: `<cmd> lint-changelog`. It skips the unreleased section, and re-checks live any release the cached lookups miss, unless its section already records the gap. A `⚠ X.Y.Z: not found on PyPI` warning therefore names an earlier release missing from PyPI: report it, though it does not block this release.
- **Shippable deps**: `<cmd> lint-deps`. Offline and instant, and it covers the one release failure nothing else in this gate can see: a `[tool.uv.sources]` override never reaches the published metadata, so tests, types, formatting and the build all pass on a tree whose wheel every user then fails to install. Run it even on a docs-only cycle, where a lockfile bump can still have moved a source. A blocker naming a git source paired with a `.dev` floor is the `sync-dep-sources` idiom mid-flight: wait for that swap PR, and do not edit `pyproject.toml` by hand. The release lane carries the same check as a hard gate, but it fires after the freeze commit is already on `main`, where the only recovery is to burn the version and ship the next one.
- **Formatting**, reproduced with the **pinned** tools, never the dev-env `uv run ruff`:
  - **Run autopep8 over the cycle's changed Python files**: `git diff --name-only HEAD -- '*.py' | xargs <cmd> run autopep8 --`, which wraps long-line comments ruff leaves. Never pass a shell variable holding the space-separated list, which the runner takes as one literal path and rejects with `[Errno 2] No such file or directory: 'a.py b.py c.py '`.
  - **Then `<cmd> run ruff -- check` and `<cmd> run ruff -- format`, and read `git diff`.** Both write in place, but `check` only does so because the resolved ruff config sets `fix = true`: a repo carrying a `[tool.ruff]` section without that key gets a read-only `check` and an empty diff that means nothing. An empty diff past your reconciliation edits is green; fold a legitimate style fix into the reconciliation. Where the config does set it, that write is repo-wide rather than scoped to the cycle: a repo carrying pre-existing findings has them fixed in files this release never touched, and each one must be reversed before staging. Pass `--no-fix` when you only want to read the state. That write also runs *against* your own reconciliation: a compatibility re-export is exactly what `F401` deletes, because the old module's body never names it, and the diff then reads clean because the file is back to its committed state. A cycle that moves public symbols to a new module keeps them importable at the old address, so mark each such name `# noqa: F401` or list it in `__all__`, and confirm it survived by grepping for the name rather than by reading the diff.
  - On a tree that holds uncommitted sweep edits, `git diff` shows them mixed with what the formatters wrote. Copy the changed files aside before the sequence, then compare each one against its copy: an empty comparison is the green. A per-tool `--verify` cannot replace this, since `<cmd> run autopep8 --verify` reports a rewrite that `ruff format` then reverts.
  - **For any Markdown the reconciliation touched (`changelog.md`, `docs/`), ask `<cmd> run mdformat --verify -- <file>`.** It reports what the write path would change without touching the tree. Never a bare `mdformat`/`mdformat --with mdformat-myst`, whose plugin set rewrites MyST directive colon-options (a `{list-table}`'s `:header-rows:`/`:widths:`) to `---` frontmatter form, diverging from CI's autofix.
  - Landmine: autopep8 relocates a trailing `# type: ignore[...]` off a >88-char line onto its own line, voiding the suppression (Lint red under `warn_unused_ignores`); ruff format usually reverts the relocation, so only wraps that survive the full pinned sequence are real formatting debt. Never commit the relocation: fix the line length at the source so the comment rides the opening line.
  - **When the reconciliation touched `pyproject.toml`, run `<cmd> run pyproject-fmt` before any `uv lock`.** Nothing else in this gate formats that file, so skipping it leaves CI's `format-pyproject` job to open a pull request mid-release. Running it after the lock respells a specifier the lock already recorded (`>=9.0` becomes `>=9`), and `uv lock` treats the two spellings as equal, so the lock keeps the stale one until an unrelated change rewrites it.
- **Workflow YAML**, whenever the cycle touched `.github/workflows/`: `<cmd> run actionlint --`, `<cmd> run zizmor -- .`, and `<cmd> run yamllint --` over every workflow. Nothing else in this gate reads workflow YAML, yet step 1's code pass is told to edit it, and on this repo a bundled workflow carries a regression to every downstream repo, which gets the workflow without the conformance tests guarding it here. One class to know: GitHub Actions evaluates an `if:` as an expression only when the value is *entirely* one `${{ … }}`. A folded block scalar (`if: >`) wrapped around one appends a trailing newline, so the value interpolates to a non-empty string and the step is truthy forever. Write a multi-line condition **bare**, with no wrapper (a leading `!` rules out the bare single-line form, since YAML reads it as a tag indicator). A second class: these three tools contradict each other, so a fix clearing the one that complained can redden one that was green. zizmor `1.30.0` added a `self-repository` audit demanding `uses: $/…` over `uses: ./…`, while the pinned actionlint rejects `$/` as a malformed ref in both the reusable-workflow and the step-level position. So re-run all three after adopting any linter's advice, and settle a conflict by measuring: put the proposed form in a scratch workflow outside the repo and run the other linters against it. When they genuinely disagree, keep the working form, silence the complaining tool inline (`# zizmor: ignore[rule]`), and leave an `XXX` beside it naming the blocking tool and its upstream ticket, with the swap recorded as a `{todo}` in whichever docstring owns the concern, since a YAML comment reaches no published todo list.
- **Autofix externals**: smoke-run `<cmd> run typos`, **every formatter that downloads a checksum-pinned binary** (`<cmd> run biome` and peers), and the vulnerable-deps scan `<cmd> audit --fix` (parses live `uv audit` output). An upstream re-publish flips a pinned SHA-256 and kills the step; pytest mocks these, so the drift (or a changed output schema) surfaces only here or in CI's `autofix` run. A pin living upstream in `repomatic` breaks every downstream repo and cannot be patched here: surface it for the step-8 upstream report. Invocation rules:
  - **Run each tool bare.** A bare `<cmd> run <tool>` builds the invocation CI performs, resolving the tool's own file list. Do not pass `.` instead: `biome check --write .` and `shfmt -- .` resemble what `autofix.yaml` runs and are not it, and biome ships no `.gitignore` awareness by default, so `.` walks ignored trees like `docs/_build`.
  - A tool the repo has no files for is skipped by the runner rather than invoked pathless. To check a pin alone without running the tool over anything, `<cmd> run <tool> -- --version` still downloads and checksum-verifies the binary. That skip covers only tools whose registry entry names a default inventory (`default_paths`). `oxipng` names none, since CI drives it through `format-images`, so a bare `run oxipng` exits `2` on missing file arguments even in a repo full of PNGs: smoke its pin with `-- --version` instead.
  - Not every non-zero smoke is drift, and only drift is worth reporting upstream. Three failure shapes are environmental and block nothing: `No binary for <platform> <arch>. Available: …` (an `UnsupportedPlatformError`) means the pinned release ships no build for the *dev machine's* platform, which says nothing about CI's Linux runners — and it is the **interpreter's** arch that decides, so an Apple-silicon host running an x86-64 interpreter under Rosetta resolves to macOS x86-64 and fails on a tool that ships only macOS ARM64, where the native interpreter would have succeeded; `Truncated download for <url>: got N of M bytes` is a short body from a proxy or a sandboxed network, not a bad artifact; and `PermissionError: [Errno 1] Operation not permitted` under the binary cache dir is a sandbox denial. Retry the last two with the sandbox off before concluding anything. Real drift reads `SHA-256 mismatch for <url>: expected …, got …`: that one alone breaks every downstream repo and belongs in the step-8 report.
  - These run in **write mode** (`run typos` defaults to `--write-changes`; `audit --fix` rewrites pins), and a smoke run can still touch files outside CI's `autofix` scope: **revert any mutation that is not part of this release's net diff** before the step-5 commit; a fix that genuinely belongs to the cycle can be kept and folded into the reconciliation. Revert a formatter *move* as a move: it is a paired add-plus-delete, and reverting only the added copy silently deletes the block from the file. A mutated file carrying no reconciliation edit reverts whole with `git checkout -- <file>`: safe at this gate, where the sweep agents have already joined (their no-revert rule protects a *live* shared tree).
  - **An untracked file has no committed copy to revert to.** A bare run still reaches it: `typos` walks the directory, and the `mdformat` inventory lists untracked Markdown. With one in `git status`, pass only the changed files, or check the pin alone with `-- --version`.
  - **Run the smoke checks in a throwaway `git worktree` at `HEAD`, while the sweep agents work.** A write-mode tool then cannot touch the shared tree, so nothing needs a revert. Pins and advisories do not depend on the sweep edits, so the result holds. Spelling does: once the lanes join, run `<cmd> run typos --verify -- <files>` over the changed files, which reads them without writing.
- **Binary self-test plan**, against the source build: `uv run -- click-extra test-suite --command <source-entrypoint> --jobs max`, the same engine `tests.yaml` (`--command`) and `release.yaml` (`--binary`) drive. It catches the two failures otherwise hidden until the ~90-minute matrix: a case assertion drifted from current CLI output (colors stripped by the piped harness, a moved string), and a plan that cannot *load* under the binary runner's stdlib-only base deps.
  - **Keep the plan TOML or JSON.** A YAML or json5 plan raises "format support disabled" and silently falls back to a trivial suite. Confirm a non-TOML plan parses under stdlib `tomllib`, since the full-venv source run has the format extras and hides the gap.
  - **It cannot catch a case whose expected output depends on the target platform's identity.** The source run is single-OS, so an assertion keyed on the release runner's distro (a `manylinux` container correctly detected as its RHEL/AlmaLinux base) or a manager present only there passes locally and still reds the binary matrix. A cycle that bumps a platform-detection dependency (`extra-platforms`) can silently shift such attributions: check the test plan in the binary matrix, not just in the source self-test.
- **Fresh resolution**: `uvx --no-progress --from . <cmd-bare> --version`. A fresh isolated env resolves `[project.dependencies]` from scratch, surfacing transitive conflicts the already-synced venv hides; CI's test matrix installs from `uv.lock` and hides them too, while end users installing via `uvx` hit exactly this resolution, so a failure is **release-blocking**. Fix at the dependency level (drop, swap, or wait on upstream), never with environment-scoped overrides: `uvx --from .` does not read `[tool.uv] override-dependencies`.
  - **A cooldown filter is not a resolution failure — check for it before declaring one.** `uvx` reads the *user-level* `~/.config/uv/uv.toml`, which on a maintainer's machine typically carries a supply-chain `exclude-newer`. A release that raises a dependency floor to a version published inside that window then fails to resolve **on the maintainer's machine only**. The tell is in uv's own output: a `hint: <pkg> was filtered by exclude-newer to only include packages uploaded before <date>. The latest version satisfying the requirement is vX, published at <later date>`. It is self-clearing: the same command passes once the dependency ages past the window.
  - **Re-run with the cutoff lifted wholesale, and judge the gate on that result.** Use `uvx --no-progress --exclude-newer 2100-01-01 --from . <cmd-bare> --version`. Lifting it per-package (`--exclude-newer-package <pkg>=0d`) just surfaces the next floor in the chain, one round-trip at a time.
  - **A cooled run that resolves and then crashes is a floor bug, not the cooldown.** A cooldown artifact fails *during* resolution, and says so with the `hint:` above. A floor bug installs cleanly, then dies at runtime on the older version the cooldown fell back to: typically a `TypeError` naming an argument a newer release introduced. Lifting the cutoff hides it, so judging the lifted run alone passes the gate on a release that every cooled install will break. Downstream repos run the frozen `uvx 'repomatic==X.Y.Z'` under a workflow-level `UV_EXCLUDE_NEWER`, and `uvx` reads neither `uv.lock` nor `[tool.uv]`. Read the traceback before crediting the cutoff. When the older version is at fault, raise the floor to what the code needs, and let `lint-deps` say whether the release waits.
  - **The `uv-build ... missing an upper bound` warning here is expected, never a resolution failure.** repomatic deliberately leaves `uv-build` uncapped across managed repos (rationale in repomatic's own `pyproject.toml` `[build-system]` comment), so never flag it or add a cap.

**The local gate is single-OS**, so platform-specific failures surface only in CI. Shrink that window pre-push:

- The usual culprits: path resolution (`Path.resolve()` canonicalizes Windows 8.3 names and POSIX symlinks), home-directory expansion, env-var casing, filesystem case-sensitivity, text-I/O encoding (Windows defaults to cp1252, so a bare `open()`/`read_text()`/`write_text()` breaks on the first non-ASCII character, and only in Windows CI: pass `encoding="UTF-8"`, and when the cycle touched file I/O, run the suite once with `PYTHONWARNDEFAULTENCODING=1` to surface calls ruff's inference-limited `PLW1514` cannot see), and direct execution of a generated script (Windows honors neither the executable bit nor the shebang, dispatching on file extension, so a `chmod +x`'d shebang script a test runs by bare path fails with `WinError 193`: emit a `.cmd` launcher beside a `.py` sidecar on Windows, or invoke the interpreter explicitly).
- The structural fix is to **mirror the production transformation, not reconstruct it**: a test asserting on a derived value should run the same pipeline the code runs, so the expectation matches by construction on every platform. Where expectations must diverge by platform, the CI matrix is authoritative: read every cell, not just your OS.
- **Name what the gate cannot run**: grep the cycle's changed test files for pytestmarks that exclude the local platform (`unless_*`, `skip_*`, `skipif`) and diff-review those tests' expectations by hand. Extend the review to the *inputs* those tests consume: new docs prose or docstrings can redden a platform-gated conformance test whose skip list never met that reference class (a reworded docstring a Sphinx test asserts on, a first-ever stdlib cross-reference missing from a skip list). The cycle's earlier pushes already ran those tests in CI, which is why the read of CI's conclusions on `HEAD` above is what actually catches them pre-push.
- **Reproducing a platform-specific failure churns the shared venv, and the wrong re-sync then reddens the rest of the gate with artifacts.** Confirming a free-threaded or version-specific break with `uv run --python <other>` (like `3.14t` for a free-threading race) recreates and repoints `.venv` to that interpreter.
  - **Restore it with `uv sync --frozen --all-extras --group test --group typing`.** `test` mirrors `tests.yaml`, and `typing` (stubs-only, so it cannot perturb a test at runtime) keeps the gate's own `<cmd> run mypy` honest: a venv synced without it floods `import-untyped`/`import-not-found` in files the cycle never touched (even `pytest` reads as `import-not-found`).
  - **Never `--all-groups`.** It additionally pulls in the `docs` group whose imports perturb process-global-state-dependent tests (logging config, default theme) into spurious failures, while a default-only `uv sync` strips both needed groups (no `pytest` at all).
  - **Trust CI's `lint.yaml`/`tests.yaml` over a local gate re-run against a churned venv.** These are venv-provisioning artifacts, not code regressions, so re-sync to the CI-matching groups before re-running the gate. `lint.yaml` on the prior `HEAD` reporting exactly the real error set, and none of the stub noise, is the authoritative mypy signal.

### 3. Version advisory (never bumps, never blocks)

Read the consolidated unreleased section and classify the bump the net diff implies:

- A `**Breaking:**` entry, or any removed or renamed public API: **major**.
- A new feature, command, or config key: **minor**.
- Only fixes, dependency bumps, and internal changes: **patch**.

State the classification and the single strongest reason, then keep going on the patch default (the unfreeze commit bumps the patch automatically). **Do not merge a version-increment PR, and do not stop**: for minor or major, surface an advisory ("this release looks like a `minor`: merge the `minor-version-increment` PR if you want that bump") and proceed. The maintainer merges that PR out of band, which re-triggers the release PR on its own.

### 4. Present the sweep

Show `git diff` of `changelog.md` plus a one-line summary of the code and docs changes the agents made. Consolidation drops and merges entries: surfacing this is what lets you catch an over-eager drop at the commit prompt before it ships.

### 5. Commit and push

Commit the reconciled tree with a message describing the net reconciliation (plus the attribution trailer), then push to `main`: the push regenerates the release PR through `prepare-release`.

**Keep that message short**: an imperative subject under 72 characters, and a body only when the sweep bundled orthogonal strands of work. That body is then one short line per strand, never a paragraph per theme. The changelog carries the user-facing story and the diff carries the rest.

**Re-read `git status` immediately before staging, and never reach for `git add -A`.** A sweep agent that has gone quiet can resume editing minutes later, after the step-2 gate has already run and while you are drafting the commit. `git add -A` then sweeps in files you never reviewed and whose changes the gate never covered. Diff every path that was not in the tree when you ran the gate, and re-run the gate before committing if any appeared: an edit landing after the gate is an ungated edit, whoever made it. The narrow-staging rule of the sub-agent rules (`git commit <path>`, never `-a`) binds the orchestrator's own reconciliation commit too.

**A gate command you ran yourself re-creates the mutations you already reverted.** The step-2 revert is not final. Any later step that builds the documentation regenerates the committed artifacts that build owns, and a test selection can build them without announcing it. So re-read `git status` after the *last* command that touched the tree, not after the sweep agents joined, and stage by explicit path so a resurrected artifact cannot enter the commit.

**A parallel session can edit the files your sweep edited.** The maintainer may drive a second session in the same checkout, and its hunks can land beside yours in one file. Staging that file by path then commits its unfinished work under your message. Stage each shared file as a blob without its hunks: `git hash-object -w` on a copy outside the tree, then `git update-index --cacheinfo`. Gate that exact tree in a throwaway `git worktree`, not in the shared tree. The worktree also keeps an untracked file out of the file inventories some tests check. List the other session's hunks in the step-7 report.

**Signed commits may need the sandbox off.** With SSH signing (`gpg.format = ssh`), the harness sandbox blocks the signing agent's socket and any key file under a `denyRead` path (`Operation not permitted`). Signing runs sandboxed once the settings allow the socket in `sandbox.network.allowUnixSockets`, and the public key, allowed-signers file and `gpg.ssh.program` wrapper in `sandbox.filesystem.allowRead`, with `~/.ssh` a real directory rather than a symlink. Otherwise, disable the sandbox for the `git commit` and `git push` calls only. The network proxy can still break an SSH push after a sandboxed signing succeeds, with `ssh_dispatch_run_fatal`: push that remote with the sandbox off.

**A hardware key is not a retry loop.** A hardware-backed key (Secretive, YubiKey, TPM) prompts the maintainer per signature, and one unanswered prompt wears three faces, sometimes in sequence across retries: `agent refused operation?`, `Couldn't sign message (signer): communication with agent failed?` (exit 128, then `failed to write commit object`), or no output until something kills the command. A signing command silent for minutes is a prompt nobody answered, not a slow command: bound it with a timeout and hand off. Stop after one or two retries and ask the maintainer.

**Prefer merging a green autofix PR over authoring your own signed commit.** When the fix already exists as an open, CI-green `sync-*` or `format-*` branch, GitHub signs the merge commit server-side, sidestepping the local key entirely.

**"Ask the maintainer" can mean asking them to act outside this session.** `gh pr merge` may itself be walled by a standing `permissions.deny` rule in the operator's settings, which no in-chat authorization can override. When both the merge and the signed commit are blocked, ask them to run the merge or push themselves, not merely to approve in chat. The same applies to the babysitter in step 6: its skill carries the explicit hand-off contract.

### 6. Babysit CI to green

Step 2 cleared every locally-reproducible failure and step 1's red inventory pre-paid the debt already visible in past runs, so the first run should be close to green: babysit handles what only CI surfaces, platform-specific breaks and, when the project builds binaries, the slow Nuitka matrix.

**The goal of this step is a genuinely green suite, not a catalogue of which reds are "non-blocking."** Fix *every* `tests.yaml` failure surfaced here, including flaky and pre-existing ones carried on `main` for months (a chronic environment-specific break, a "known-flaky" live-registry install, an allowed-failure `⁉️` probe that actually crashes), not only this cycle's regressions. Root-cause each red to its mechanism: the manager argv it builds, the dependency it imports, the assertion that drifted. Then fix it at the source: a real code bug gets the code fix, a genuinely-flaky live-registry install is folded into the test's tolerated-exit set (with the reasoned comment its peers carry), a partial-wheel import crash is converted to a clean skip gated on the library's own availability sentinel, a wall-clock budget that fires on a shared runner is resampled so the assertion reads the fastest of several runs rather than one. Say this in the babysitter's spawn prompt too: its own skill sends it to re-run anything infrastructure-shaped, and a timing flake looks exactly like that. A red's `⁉️`/non-blocking status governs only whether it *gates the merge*, never whether it gets fixed.

**Run a tight fix-loop: act on the first failing job, never the run's conclusion.** The instant any job turns `conclusion=="failure"` (`gh run view <run> --json jobs`, broken on the earliest failure rather than the run's overall conclusion), fetch its log, reproduce and fix locally against the pinned gate on the touched files, commit with the attribution trailer, and push. The fresh push supersedes the obsolete in-progress run: never wait out a 40-90-minute matrix per fix. Batch only fixes alr

[…] pełny plik w paczce .zip
Pliki w paczce (3)
  • SKILL.md 82 KB
  • references/findings-in-repomatic.md 3 KB
  • references/short-ship.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · kdeldycke/dotfiles100BSD-2-Clause
kdeldycke/repomatic100LGPL

Migawka bazy z 13.11.2026 · wersja paczki 0076c3f68772 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100babysit
    Prowadzi zmianę przez commit, push, pull request, niezależne przeglądy, CI i scalenie, gdy CI jest zielone.
  • 86release-prep
    Przygotowuje wydanie JetWhale: szkic wpisu do changeloga i pull request z tą zmianą.
  • 100release
    Wykonuje wydanie po sprawdzeniu czystego main: ustala wersję, pisze dwujęzyczny changelog i pyta o zgodę przed tagiem.
  • 100release
    Przygotowuje wydanie pakietu Spotcraft: podbicie wersji, changelog, pull request do main i opis tego, co publikuje CI.
  • 100ls-release
    Przeprowadza wydanie nowej wersji LlamaStash od zmiany CHANGELOG do publikacji i sprawdzenia każdego kanału.
  • 96release
    Przygotowuje wydanie prismantis: podbicie wersji, changelog, weryfikację, tag i wypchnięcie zmian.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.