@rtorcato/repo-tooling 3.13.0 → 3.13.2

package/README.md

@@ -175,7 +175,7 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
 get three skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (the family's release rules) and `ai-issue-loop` (the label-driven
+`npm-publish` (never hand-cut a release) and `ai-issue-loop` (the label-driven
 issue → PR pipeline) — in any session:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.13.0",
+	"version": "3.13.2",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/ai-issue-loop/SKILL.md

@@ -60,6 +60,8 @@ header names the agent *and* says why it is wearing a human's face:
 | `ai-wip` | issue | Claimed; a worktree exists. |
 | `ai-blocked` | issue | Agent gave up; needs a human. |
 | `ai-review` | PR | Awaiting agent review. |
+| `ai-reviewing-code` | PR | `code-reviewer` claimed and running. Cleared with its verdict. |
+| `ai-reviewing-sec` | PR | `security-expert` claimed and running. Cleared with its verdict. |
 | `ai-ok-code` | PR | `code-reviewer` passed. |
 | `ai-ok-sec` | PR | `security-expert` passed. |
 | `ai-changes` | PR | A reviewer requested changes. |
@@ -86,6 +88,8 @@ gh label create ai-ready    -c '#0e8a16' -d 'Eligible for an AI agent to impleme
 gh label create ai-wip     -c '#fbca04' -d 'Claimed by an agent; worktree exists'
 gh label create ai-blocked -c '#b60205' -d 'Agent gave up; needs a human'
 gh label create ai-review  -c '#1d76db' -d 'PR awaiting agent review'
+gh label create ai-reviewing-code -c '#c5def5' -d 'code-reviewer claimed and running'
+gh label create ai-reviewing-sec  -c '#c5def5' -d 'security-expert claimed and running'
 gh label create ai-ok-code -c '#0e8a16' -d 'code-reviewer passed'
 gh label create ai-ok-sec  -c '#0e8a16' -d 'security-expert passed'
 gh label create ai-changes -c '#d93f0b' -d 'Reviewer requested changes'
@@ -100,14 +104,19 @@ grep -qxF '.claude/ai-loop-status' .gitignore || echo '.claude/ai-loop-status' >
 
 ```
 issue: ai-ready ─pickup─> ai-wip ─> PR opened, labelled ai-review
-PR: ai-review ─> reviewers ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> assigned to you, ai-review dropped
-                            │        (± ai-notes)       │              ─> YOU merge ─> worktree removed
-                            │                           └─ dependabot ─┬─ no ai-notes ─> auto-merge ─> worktree removed
-                            │                                          └─ ai-notes ───> assigned to you
-                            └─> ai-changes ─> fix round (max 2) ─> ai-review
-                                                        └─ round 3 ─> ai-blocked
+PR: ai-review ─> ai-reviewing-* ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> assigned to you, ai-review dropped
+                                 │        (± ai-notes)       │              ─> YOU merge ─> worktree removed
+                                 │                           └─ dependabot ─┬─ no ai-notes ─> auto-merge ─> worktree removed
+                                 │                                          └─ ai-notes ───> assigned to you
+                                 └─> ai-changes ─> fix round (max 2) ─> ai-review
+                                                             └─ round 3 ─> ai-blocked
 ```
 
+`ai-reviewing-code` / `ai-reviewing-sec` are the *claim* step: Pass 3 applies one
+immediately before spawning that reviewer, and the reviewer clears its own
+alongside its verdict label. They are transient — a claim outliving its reviewer
+means the agent died, which is Pass 2's stall reaping, not a state of the PR.
+
 Only the Dependabot arm merges itself, and only when no reviewer left `ai-notes`.
 An issue PR ends at *assigned to you* and waits there — `ai-ok-code, ai-ok-sec`
 with no `ai-review` is the loop's way of saying done. Add `ai-notes` and it means
@@ -374,7 +383,7 @@ work must never be reaped out from under itself.
 | Stalled | Condition | Do |
 |---|---|---|
 | Implementer died | issue `ai-wip` ≥45min, **and no PR exists** for `ai-<N>-<slug>` | `gh issue edit <N> --add-label ai-blocked --remove-label ai-wip --add-assignee @me`, comment, remove the worktree |
-| Reviewer died | PR `ai-review` ≥45min with no `ai-ok-*` and no `ai-changes` | re-spawn the missing reviewer — they're cheap and diff-scoped. If `ai-review` has been applied ≥3 times, `ai-blocked` instead |
+| Reviewer died | PR `ai-reviewing-code` (or `ai-reviewing-sec`) ≥45min with no matching `ai-ok-*` and no `ai-changes` | `gh pr edit <N> --remove-label <the claim that stalled>` — drop **that** label, not a fixed one; a stalled `ai-reviewing-sec` cleared as `ai-reviewing-code` leaves the dead claim in place and the reviewer never re-spawns. Dropping the claim is what lets Pass 3 re-spawn it, and they're cheap and diff-scoped. If that claim has been applied ≥3 times, `ai-blocked` instead |
 | Orphan worktree | `"$WT_ROOT"/ai-<N>-*` whose issue is not `ai-wip` and has no open PR | remove the worktree and branch |
 
 The **no PR exists** condition on the first row is what makes reaping safe. An
@@ -404,8 +413,34 @@ means *a human must look*; do not spend it on a claim you already understand.
 
 **PRs labelled `ai-review`.** For each, spawn *in background* only the reviewers
 whose pass-label is missing — `code-reviewer` if no `ai-ok-code`,
-`security-expert` if no `ai-ok-sec`. Both can run concurrently; launch them in a
-single message.
+`security-expert` if no `ai-ok-sec` — and **only those not already claimed**: skip
+`code-reviewer` if the PR carries `ai-reviewing-code`, `security-expert` if it
+carries `ai-reviewing-sec`. Both can run concurrently; launch them in a single
+message.
+
+**Claim first, then spawn** — the same shape Pass 4 uses before picking up an
+issue. Apply the label immediately before the spawn, not after:
+
+```bash
+gh pr edit <N> --add-label ai-reviewing-code   # then spawn code-reviewer
+gh pr edit <N> --add-label ai-reviewing-sec    # then spawn security-expert
+```
+
+Without the claim there is no window in which "a reviewer is running" is visible.
+A reviewer applies its verdict label only at the *end*, after reading the diff and
+posting its comment, so from spawn until then the labels are indistinguishable
+from "nobody has started" — and a 15-minute tick is comfortably shorter than a
+review. A tick landing in that gap spawns a duplicate of every reviewer in flight:
+two agents read the same diff and post two review comments under the owner's
+avatar, and the verdicts race, one applying `ai-ok-code` while the other applies
+`ai-changes` and leaves the PR contradictory for Pass 1 to interpret. On a 4-PR
+queue that is 8 duplicated reviewers against the monthly cap the limits section
+exists to protect.
+
+Two labels rather than one, because the reviewers are spawned independently and a
+single flag could not say *which* was already running. The reviewer clears its own
+claim alongside its verdict, so a claim never outlives its run; if one does, the
+agent died and Pass 2's stall reaping drops it.
 
 Reviewer prompt template:
 
@@ -452,9 +487,14 @@ Reviewer prompt template:
 > restating the diff. Writing `Nothing.` is a real verdict and the common one —
 > say it plainly rather than padding the section to look thorough.
 >
-> Then apply exactly one verdict label:
-> - Clean, or only nit-level suggestions → `gh pr edit <N> --add-label <ai-ok-code|ai-ok-sec>`
-> - A real defect a maintainer would block on → `gh pr edit <N> --add-label ai-changes --remove-label ai-review`
+> Then apply exactly one verdict label, **clearing your claim label in the same
+> command**:
+> - Clean, or only nit-level suggestions → `gh pr edit <N> --add-label <ai-ok-code|ai-ok-sec> --remove-label <ai-reviewing-code|ai-reviewing-sec>`
+> - A real defect a maintainer would block on → `gh pr edit <N> --add-label ai-changes --remove-label ai-review --remove-label <ai-reviewing-code|ai-reviewing-sec>`
+>
+> Pass 3 applied that claim label immediately before spawning you, and skips
+> spawning a second of you for as long as it is set. Leaving it behind wedges your
+> half of the review until Pass 2 reaps it as a dead reviewer.
 >
 > And **additionally**, if and only if your `### Before merging` section is not
 > `Nothing.`:
@@ -537,7 +577,10 @@ package/from/to table survives because it sits at the top; classify from that.
 > State in your comment which rule fired, name the packages that tripped it, and say
 > whether the body was truncated so the reader knows what you could and couldn't see.
 > Same `🤖 *Automated review — …*` header line, same closing `### Before merging`
-> section, and same one-verdict-label rule as above.
+> section, and same one-verdict-label rule as above — **including clearing your
+> `<ai-reviewing-code|ai-reviewing-sec>` claim label in the same `gh pr edit`**.
+> Pass 3 claimed you with it before spawning you, and a claim left behind wedges
+> your half of the review until Pass 2 reaps it.
 >
 > Be sparing with `ai-notes` here specifically: it suppresses auto-merge, so a
 > reflexive note on every dependency bump wedges the one path that runs
@@ -694,6 +737,16 @@ Then spawn a background implementer agent:
 > 3. Read the repo's `CLAUDE.md` and obey it — especially any pre-commit build
 >    step or committed build output.
 > 4. Do the work. Conventional Commits within the branch.
+>
+>    **Do not run `pnpm install`.** This worktree's `node_modules` is a symlink to
+>    the main checkout, so pnpm sees a foreign directory it must purge first and
+>    aborts with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`. Dependencies are
+>    already present — run tests, lint and build directly. If the work *is* a
+>    dependency change, `pnpm install --lockfile-only` updates `pnpm-lock.yaml`
+>    without touching `node_modules`. When that leaves a verification step you
+>    cannot run, say so in the PR body — name the command you could not run and
+>    why — so the reviewer knows CI is the only check on it rather than assuming
+>    you ran it.
 > 5. Push and open the PR. The title must be a Conventional Commit — it becomes
 >    the squash subject on `main` and, in repos using semantic-release, decides
 >    whether a release goes out at all. Body must contain `Closes #<N>`.

package/skills/npm-publish/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: npm-publish
-description: Use before releasing or publishing any @rtorcato/* package (repo-tooling and the whole family publish the same way). Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by semantic-release on merge to main; an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
+description: Use before releasing or publishing any package in a repo set up by @rtorcato/repo-tooling. Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by the repo's release tool (semantic-release, Changesets, or Release Please); an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
 ---
 
 # npm-publish
 
-Every `@rtorcato/*` package releases through **semantic-release on push to `main`**.
-Versioning, the git tag, the GitHub release, the CHANGELOG, and the npm publish are
-all derived from the commit history. There is no manual release step.
+A repo set up by `@rtorcato/repo-tooling` releases through **automation on merge to
+`main`** — one of semantic-release, Changesets, or Release Please. Versioning, the
+git tag, the GitHub release, the CHANGELOG, and the npm publish all come from that
+pipeline. There is no manual release step under any of them.
 
 ## The rule
 
@@ -17,31 +18,78 @@ all derived from the commit history. There is no manual release step.
 - `npm version` (or editing `"version"` in `package.json`)
 - `git tag` / pushing tags
 - hand-editing `CHANGELOG.md`
+- merging the "Version Packages" PR (Changesets) or the release PR (Release Please) —
+  that merge *is* the publish, so it is the human's release decision, not yours
 
-If asked to "release" or "bump the version", the correct action is to land a
-**conventional commit** on `main` (via PR) and let the pipeline do the rest.
+This holds for all three tools. Only the "what to do instead" differs, so first
+work out which tool the repo uses.
 
-## How a release actually happens
+## Which release tool is this repo on?
 
-1. Work on a branch; commit with Conventional Commits (header ≤ 100 chars).
-2. Open a PR; merge to `main` after review + green CI.
-3. semantic-release runs on `main` and decides the bump from the commits:
-   - `fix:` → patch
-   - `feat:` → minor
-   - `feat!:` / `BREAKING CHANGE:` → major
-   - `chore:` / `docs:` / `refactor:` / `test:` → **no release**
-4. It writes the version, tag, GitHub release, CHANGELOG, and publishes to npm.
+Check the repo root, in this order — these are the same signals the CLI's
+`doctor` check uses (`usesChangesets` / `checkSemanticRelease` in
+`src/languages/js/checks.ts`):
+
+| Signal | Tool |
+|---|---|
+| `.changeset/config.json` exists | **Changesets** |
+| `release-please-config.json` exists | **Release Please** |
+| `.releaserc*` / `release.config.*` exists, or a `"release"` key in `package.json` | **semantic-release** |
+
+Or just ask the tooling: `npx @rtorcato/repo-tooling doctor --json` reports the
+`semantic-release` check as ok with a detail naming the tool actually in use.
+
+If more than one is configured that's drift, not a choice — stop and flag it.
+
+## What to do instead, per tool
+
+### semantic-release
+
+The bump is derived from the commit history, so the commit type *is* the release
+decision:
+
+- `fix:` → patch
+- `feat:` → minor
+- `feat!:` / `BREAKING CHANGE:` → major
+- `chore:` / `docs:` / `refactor:` / `test:` → **no release**
+
+To ship a change: give it the right commit type and merge to `main`.
+
+### Changesets
+
+The bump is declared in a changeset file, **not** inferred from commits. A PR with
+no changeset publishes nothing, silently — so this is a required step, not an
+optional one:
+
+```bash
+pnpm changeset        # pick the packages + bump level, write the summary
+```
+
+That writes `.changeset/<name>.md`. Commit it with the change. On merge to `main`
+the release action opens (or updates) a "Version Packages" PR; merging *that* is
+what publishes — so never merge it yourself, leave it for a human. Hand-authoring
+`.changeset/*.md` is fine — it is the one file in this flow you are meant to
+write. `CHANGELOG.md` is still generated; don't touch it.
+
+### Release Please
+
+Also commit-driven, same Conventional Commit → bump mapping as semantic-release.
+On merge to `main` it opens a release PR that carries the version bump and the
+CHANGELOG entry; merging that PR tags and publishes, so leave that merge to a
+human — never do it yourself. Don't edit `.release-please-manifest.json` by hand.
 
 ## What an agent should do
 
-- To ship a change: make sure it carries the right commit type, then merge to `main`.
+- To ship a change: right commit type, plus a changeset if the repo is on Changesets.
 - To check the last release: `git tag --sort=-creatordate | head -1`, or the GitHub
-  Releases page — don't infer it from `package.json` (that's `0.0.0-development` /
-  the placeholder until CI stamps it).
-- If a release seems stuck, inspect the release workflow run — do **not** publish by hand.
+  Releases page — don't infer it from `package.json` (under semantic-release that's
+  `0.0.0-development` / a placeholder until CI stamps it).
+- If a release seems stuck, inspect the release workflow run, and check for an open
+  release / "Version Packages" PR waiting to be merged — report it, do **not** merge
+  it yourself and do **not** publish by hand.
 
 ## Why
 
 Manual publishes skip provenance, the CHANGELOG, and the tag/version invariant the
-whole family relies on, and a stray `npm version` commit derails the next automated
-bump. One automated path keeps every sibling repo publishing identically.
+pipeline maintains, and a stray `npm version` commit derails the next automated bump.
+One automated path per repo keeps releases reproducible and reviewable.