@rtorcato/repo-tooling 3.16.1 → 3.16.3

package/dist/cli/commands/setup.js

@@ -108,7 +108,7 @@ export async function setupProject(options) {
     const interactive = !options.config && !options.preset;
     const dryRun = options.dryRun === true;
     if (interactive && !dryRun) {
-        console.log(chalk.cyan('\n🛠️  Welcome to JS Tooling Setup!\n'));
+        console.log(chalk.cyan('\n🛠️  Welcome to repo-tooling setup!\n'));
         console.log(chalk.gray(`Setting up tooling in: ${targetDir}\n`));
     }
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.16.1",
+	"version": "3.16.3",
 	"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

@@ -43,14 +43,12 @@ real approvals.
 
 The same constraint makes everything an agent posts *look* hand-written by the
 owner. So **every comment any agent leaves — review, blocked, gave-up, declined —
-opens with a `🤖 *Automated …*` italic header line** naming which agent wrote it,
-followed by a blank line. Non-negotiable: a detailed security review under a
-human's avatar misrepresents who reviewed the code.
+opens with a `🤖 *Automated …*` italic header line naming which agent wrote it**,
+then a blank line. Name the agent and stop there: a detailed security review
+under a human's avatar misrepresents who reviewed the code, but *why* it wears
+that avatar is read once and then reread on every comment forever.
 
-Spell the reason out rather than assuming the reader knows the convention — the
-header names the agent *and* says why it is wearing a human's face:
-
-`🤖 *Automated — <which agent> via ai-issue-loop. Posted under the owner's account by an agent; not a human message. There is no separate GitHub account for AI agents, so this appears under @<owner>'s avatar.*`
+`🤖 *Automated — <which agent> via ai-issue-loop.*`
 
 **Comment budget: ≤10 lines, and a clean outcome gets no comment at all.** A
 40-line comment on every PR trains the reader to skip all of them, including the
@@ -63,16 +61,16 @@ drift with a second copy to maintain.
 | Clean and ready | **None.** `ai-ok-code, ai-ok-sec` + assigned + no `ai-review` already says it. |
 | `ai-notes` | ≤10 lines; link the reviewer's `### Before merging`. |
 | `ai-changes`, CI red, `ai-blocked` | ≤10 lines, action first, then the specific cause. |
-| Reviewer verdict | `### Before merging` plus at most 3 short paragraphs above it. |
+| Reviewer verdict | `### Before merging` plus ≤600 characters above it. |
 | Declining an issue | The one exception — a hard handoff needs its reasoning; see Pass 4. |
 
 ## Labels
 
 | Label | On | Meaning |
 |---|---|---|
-| `ai-ready` | issue | Eligible for an agent. The hard gate. |
-| `ai-wip` | issue | Claimed; a worktree exists. |
-| `ai-blocked` | issue | Agent gave up; needs a human. |
+| `ai-ready` | issue | Eligible for an agent. The hard gate; **cleared on pickup**. |
+| `ai-wip` | issue | Claimed; a worktree exists. Never rides alongside `ai-ready`. |
+| `ai-blocked` | issue | Agent gave up; needs a human. Only a human re-adds `ai-ready`. |
 | `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. |
@@ -400,13 +398,21 @@ Only then:
 git -C "$ROOT" worktree remove --force "$WT_DIR"   # the path found above, not a rebuilt one
 git -C "$ROOT" branch -D "$BRANCH" 2>/dev/null
 gh issue edit <N> --remove-label ai-wip 2>/dev/null
+# Still OPEN means the PR said only `Refs #N`; a `Closes #N` issue is already closed.
+if [ "$(gh issue view <N> --json state -q .state)" = OPEN ]; then
+  gh issue edit <N> --add-assignee @me
+fi
 ```
 
 A closed-unmerged PR is the exception: there is no squash to find, so skip the
 confirmation and remove — the work was abandoned deliberately.
 
-The issue itself closes from the PR body's `Closes #N`. This pass is what frees
-concurrency slots, so it must run before Pass 4.
+The issue itself closes from the PR body's `Closes #N`, so both edits are normally
+no-ops on a closed issue. A PR that said only `Refs #N` leaves it **open**, which is
+what the state check catches. The work has landed, so it must not go back in
+the queue; pickup already dropped `ai-ready`, and assigning it is what stops a
+merged issue sitting unowned instead (#429 had to be moved to `holding` by hand).
+This pass is what frees concurrency slots, so it must run before Pass 4.
 
 **Then reap the stalled.** Nothing can time out an agent: the Agent tool takes no
 timeout, and an agent whose session died leaves its labels behind with no process
@@ -432,13 +438,15 @@ work must never be reaped out from under itself.
 The **no PR exists** condition on the first row is what makes reaping safe. An
 agent that got as far as opening a PR has handed off to the label state machine
 and is no longer the thing being waited on; only a run that produced nothing is
-presumed dead. The reaped issue keeps its worktree removed, so a re-labelled
-`ai-ready` starts clean.
+presumed dead. Reaping deliberately does **not** restore `ai-ready` — `ai-blocked`
+means a human decides when the issue re-enters the queue, and the removed worktree
+means their re-label starts clean. The other two `ai-blocked` exits, Pass 3's
+ping-pong stop and an implementer handing back, leave it off for the same reason.
 
 **Every `ai-blocked` must say why, and land in front of a human.** So reaping always
 does three things together — label, assign, comment — and the comment opens with
 
-`🤖 *Automated — \`ai-issue-loop\` Pass 2 (stall reaping). Posted under the owner's account; not a human message.*`
+`🤖 *Automated — \`ai-issue-loop\` Pass 2 (stall reaping).*`
 
 then a blank line. State which stall rule fired, how long the label sat, and whether a
 worktree was removed. A bare `ai-blocked` with no explanation is worse than no label:
@@ -448,9 +456,12 @@ puts it in the statusline and fires a notification with a sound.
 **Reaping is not always the right call — say so when it isn't.** The rule assumes a
 dead agent, but a stale `ai-wip` can also come from a run that was cancelled
 deliberately, in which case the work is fine and only the claim is stale. If you know
-the cause and it is benign, clear `ai-wip` **without** `ai-blocked` so Pass 4 can pick
-it straight back up, and say in the comment that you deviated and why. `ai-blocked`
-means *a human must look*; do not spend it on a claim you already understand.
+the cause and it is benign, **return it to the queue** — `gh issue edit <N> --add-label
+ai-ready --remove-label ai-wip`, no `ai-blocked` — so Pass 4 picks it straight back up,
+and say in the comment that you re-queued it, that you deviated, and why. Re-adding
+`ai-ready` is not optional: pickup cleared it, so clearing `ai-wip` alone drops the
+issue out of the queue silently, which is the worse failure. `ai-blocked` means *a
+human must look*; do not spend it on a claim you already understand.
 
 ### Pass 3 — review
 
@@ -493,20 +504,19 @@ Reviewer prompt template:
 > purpose. Also read the repo's `CLAUDE.md` if the diff plausibly touches a rule
 > it states.
 >
-> `<code-reviewer: Judge correctness, obvious bugs, and adherence to the repo's
-> stated conventions.>` / `<security-expert: Judge injection risk, leaked
-> secrets, unsafe shell/SQL construction, and dependency or supply-chain
-> changes.>`
+> `<code-reviewer: Judge correctness, obvious bugs, and adherence to the repo's stated
+> conventions.>` / `<security-expert: Judge injection risk, leaked secrets, unsafe
+> shell/SQL construction, and dependency or supply-chain changes.>` That is the
+> checklist to run, not an outline to write up.
 >
 > Post your verdict as a comment — **never** `--approve`, it errors on your own
 > PR:
 > `gh pr review <N> --comment --body "..."`
 >
-> The body **must** begin with this exact header line, then a blank line. Every
-> agent authenticates as the repo owner, so without it the timeline reads as if
-> a human wrote the review:
+> The body **must** begin with this exact header line, then a blank line — you
+> authenticate as the repo owner, so without it the review reads as a human's:
 >
-> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop. Posted under the owner's account; not a human review.*`
+> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*`
 >
 > The body **must end** with this section, as its last thing:
 >
@@ -525,13 +535,14 @@ Reviewer prompt template:
 > That section is what a human reads at merge time, so put anything you would
 > want them to know there rather than leaving it in the prose above — a finding
 > buried mid-paragraph does not survive the handoff. For the same reason, **cap
-> the body at that section plus at most 3 short paragraphs above it**: no process
-> narration, no restating the diff, no listing what you checked and found fine.
-> The bar is a finding that
-> **changes what a human would do**: a semver implication, a deliberate
-> omission, a follow-up that must be filed. Not observations, not praise, not
-> restating the diff. Writing `Nothing.` is a real verdict and the common one —
-> say it plainly rather than padding the section to look thorough.
+> the body at that section plus ≤600 characters above it**. Verify everything;
+> narrate only where the PR is **wrong** or **silent**. Never list what you
+> checked and found clean, and never confirm a claim the PR body already makes —
+> agreement is what the pass label is for, so a review that agrees is nearly
+> empty. The bar is a finding that **changes what a human would do**: a semver
+> implication, a deliberate omission, a follow-up that must be filed. Writing
+> `Nothing.` is a real verdict and the common one — say it plainly rather than
+> padding to look thorough.
 >
 > Then apply exactly one verdict label, **clearing your claim label in the same
 > command**:
@@ -633,8 +644,8 @@ 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, same 3-paragraph cap on the body, and same one-verdict-label rule as
-> above — **including clearing your
+> section, same ≤600-character cap and no-negative-findings rule on the body, 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.
@@ -669,7 +680,7 @@ gh api "repos/$OWNER_REPO/issues/<N>/timeline" \
 ```
 
 If that count is **≥ 3**, stop looping. Comment the reason on the PR — opening with
-`🤖 *Automated — \`ai-issue-loop\` Pass 3. Posted under the owner's account; not a human message.*`
+`🤖 *Automated — \`ai-issue-loop\` Pass 3.*`
 and a blank line — naming what each round changed and why the reviewer kept objecting,
 then:
 
@@ -738,10 +749,9 @@ same issue gets re-triaged from scratch every time, and the reasoning that took
 real work to reach is lost.
 
 The comment opens with the standard `🤖 *Automated …*` header — see the top of this
-file; it must state that no GitHub account exists for AI agents, so the comment
-wears the owner's avatar. Then, in the body — **this is the one comment exempt
-from the ≤10-line budget, and only this one.** Declining is a hard handoff whose
-whole value is the reasoning; do not reach for this shape on a PR handoff:
+file. Then, in the body — **this is the one comment exempt from the ≤10-line
+budget, and only this one.** Declining is a hard handoff whose whole value is the
+reasoning; do not reach for this shape on a PR handoff:
 
 - **Why an agent cannot finish it**, concretely. "Not suitable" is useless. Name
   the blocker: binary assets it cannot author, a force-push past branch
@@ -769,9 +779,17 @@ Take the first `slots` issues. For each, **claim it first** so a concurrent tick
 can't double-pick:
 
 ```bash
-gh issue edit <N> --add-label ai-wip
+gh issue edit <N> --add-label ai-wip --remove-label ai-ready
 ```
 
+Dropping `ai-ready` is half the claim, not tidiness — the diagram above is a
+transition, not an accumulation. An issue left carrying both re-enters the queue
+the instant `ai-wip` clears for any reason other than the PR closing it, and the
+next tick spawns an agent to re-implement work already sitting in an open PR
+(#458, #467, #461, #452, all in one session). Every path that legitimately returns
+an issue to the queue therefore re-adds `ai-ready` explicitly; Pass 2's benign-stall
+path is the only one, and a human does the rest.
+
 **Then create the worktree yourself**, before spawning anything. `<slug>` is 3–4
 kebab-case words from the title:
 
@@ -858,7 +876,7 @@ Then spawn a background implementer agent:
 > **must** open with this exact line, then a blank line — you authenticate as the
 > owner, so without it the issue reads as if they wrote it themselves:
 >
-> `🤖 *Automated — implementer via ai-issue-loop. Posted under the owner's account; not a human message.*`
+> `🤖 *Automated — implementer via ai-issue-loop.*`
 >
 > Say what you tried, the exact error, and what a human would need to decide. "Could
 > not finish" with no detail wastes the handoff — the whole point of the label is that