@rtorcato/repo-tooling 3.21.1 → 3.22.1

package/dist/base/fixers.js

@@ -366,7 +366,11 @@ export const BASE_FIXERS = [
             for (const name of SHIPPED_SKILLS) {
                 const result = await installClaudeSkill(dir, name, { force: forceSkills });
                 if (result.status === 'declined-downgrade') {
-                    console.error(chalk.yellow(`   skipped — ${result.file} is at ${result.installedVersion}, newer than the ${result.shippedVersion} this package ships`));
+                    // Say what was compared, not what is newer: the version is a label,
+                    // and on a git checkout it can understate the content behind it
+                    // (#522). Naming the escape hatch matters for exactly that case.
+                    console.error(chalk.yellow(`   skipped — ${result.file} is stamped ${result.installedVersion}, above the ${result.shippedVersion} this package reports; not overwritten`));
+                    console.error(chalk.yellow('   overwrite anyway:  fix claude-skills --force-skills'));
                     continue;
                 }
                 if (result.status === 'declined-fork') {

package/dist/cli/generators/claude-skills.js

@@ -8,6 +8,7 @@ import { createHash } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
+import { realGitExec } from '../../base/git-identity.js';
 import { getPackageRoot } from '../utils/copy-preset.js';
 import { shellQuote } from '../utils/shell.js';
 /**
@@ -127,13 +128,41 @@ export function isNewerVersion(a, b) {
     }
     return false;
 }
+/**
+ * The version to stamp, given what `package.json` claims.
+ *
+ * In a published tarball that field is authoritative — `@semantic-release/npm`
+ * rewrites it before packing. In a *git checkout* it is not: this repo runs
+ * semantic-release without `@semantic-release/git` (#417), so nothing ever
+ * writes the released version back and the field sits at whatever it was last
+ * hand-set to. Observed 2026-08-22: `package.json` 3.11.0 against npm 3.21.1,
+ * ten minor versions of drift.
+ *
+ * That mattered because the stamp feeds the downgrade guard below: a skill
+ * installed from npm could not be updated from a local checkout, and the
+ * refusal claimed the installed copy was "newer" when only its *label* was.
+ *
+ * So when the package root is a git checkout, take the nearest tag as well and
+ * keep whichever is higher. Monotonic on purpose — this can only ever raise the
+ * answer, so a tagless, shallow, or git-less environment keeps today's
+ * behaviour rather than silently stamping something lower.
+ */
+export async function resolveShippedVersion(root, pkgVersion, git = realGitExec) {
+    if (!(await fs.pathExists(path.join(root, '.git'))))
+        return pkgVersion;
+    const described = await git(['describe', '--tags', '--abbrev=0'], root);
+    const tag = described?.trim().replace(/^v/, '');
+    if (!tag || !/^\d+\.\d+/.test(tag))
+        return pkgVersion;
+    return isNewerVersion(tag, pkgVersion) ? tag : pkgVersion;
+}
 /** The skill source and the package version that will be stamped into it. */
-export async function readShippedSkill(name = SHIPPED_SKILL) {
+export async function readShippedSkill(name = SHIPPED_SKILL, git = realGitExec) {
     const root = getPackageRoot();
     const file = path.join(root, 'skills', name, 'SKILL.md');
     const content = await fs.readFile(file, 'utf8');
     const pkg = await fs.readJson(path.join(root, 'package.json'));
-    return { content, version: String(pkg.version), file };
+    return { content, version: await resolveShippedVersion(root, String(pkg.version), git), file };
 }
 /**
  * The command a human runs to see what their fork changed, before deciding
@@ -187,7 +216,12 @@ export async function installClaudeSkill(skillsDir, name = SHIPPED_SKILL, { forc
         installedVersion,
         shippedVersion: shipped.version,
     };
-    if (installedVersion && isNewerVersion(installedVersion, shipped.version)) {
+    // `force` overrides this too, not just the fork check below. It already
+    // overrides the *stronger* protection — overwriting content someone
+    // deliberately edited — so refusing on a version comparison while allowing
+    // that was backwards, and left no escape hatch at all when the comparison
+    // was wrong (#522).
+    if (!force && installedVersion && isNewerVersion(installedVersion, shipped.version)) {
         return { ...base, status: 'declined-downgrade' };
     }
     // Only `pristine` content is provably ours to replace. Anything else is a

package/dist/cli/utils/lockfile.js

@@ -66,13 +66,18 @@ export async function writeLockfile(dir, config, assets) {
     if (!valid) {
         throw new Error(`Refusing to write invalid lockfile:\n  - ${errors.join('\n  - ')}`);
     }
-    const carried = assets ?? (await readLockfile(dir))?.assets;
+    // One read, because everything not rebuilt from `config` has to be carried
+    // forward explicitly — this object is constructed from scratch, so any key
+    // not named here is dropped by the next `fix lockfile`.
+    const existing = await readLockfile(dir);
+    const carried = assets ?? existing?.assets;
     const filepath = path.join(dir, LOCKFILE_NAME);
     const lockfile = {
         $schema: LOCKFILE_SCHEMA_URL,
         version: LOCKFILE_VERSION,
         config,
         ...(carried && Object.keys(carried).length > 0 ? { assets: carried } : {}),
+        ...(existing?.aiLoop ? { aiLoop: existing.aiLoop } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };

package/package.json

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

@@ -207,6 +207,54 @@ pass.** A session can be pinned to a worktree, so the orchestrator can find itse
 inside one it did not choose. `--git-common-dir` resolves to the main checkout's
 `.git` from anywhere, including a worktree, so `ROOT` is correct either way.
 
+**Resolve `AGENT_USER` — the account in-flight work is assigned to.** Optional:
+unset, every step below that would assign it simply does nothing, and assignment
+behaves exactly as it did before this existed.
+
+```bash
+# Repo config first — committed, so it travels with the repo and survives a new
+# machine. `AI_LOOP_AGENT` overrides it for a repo with no lockfile.
+AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
+# A typo would fail every `gh` edit for the whole tick, so prove it is assignable
+# once, here. 204 = yes, 404 = no; push access is what qualifies an account.
+[ -n "$AGENT_USER" ] && { gh api "repos/$OWNER_REPO/assignees/$AGENT_USER" --silent 2>/dev/null || {
+  echo "⚠ agentUser '$AGENT_USER' is not an assignable collaborator — assigning nothing"
+  AGENT_USER=""; }; }
+```
+
+**It lives in the repo, not a shell profile.** The agent account is a
+collaborator on *this* repo, so a machine-wide env var is both the wrong
+granularity and invisible — forgotten on a new laptop, with the only symptom
+being that assignment quietly stops. In `.repo-tooling.json` it is committed,
+reviewable, and carried forward by `fix lockfile`:
+
+```json
+{ "aiLoop": { "agentUser": "your-bot-account" } }
+```
+
+Every later use is `${AGENT_USER:+--add-assignee "$AGENT_USER"}`, which expands
+to nothing when it is empty — so there is one code path, not two.
+
+**The point is that assignee answers "whose turn is it", which no label does
+well.** Today an issue an agent is mid-way through and an issue nobody has
+touched are both assigned to no one, so the *Assigned to you* view is only ever
+half the story:
+
+| State | Assignee |
+|---|---|
+| issue `ai-ready`, unclaimed | nobody |
+| issue `ai-wip` — an agent is implementing it | `AGENT_USER` |
+| PR `ai-review` / `ai-changes` — an agent is reviewing or fixing | `AGENT_USER` |
+| PR passed both reviews, waiting to merge | the human |
+| `ai-blocked`, declined, or held | the human |
+
+`@me` cannot express this: it resolves to whichever token is running, and the
+agents authenticate as the owner, so `@me` is *always* the human. That is why
+this is a separate name rather than a reuse.
+
+Note the web UI's assignee picker can show a stale list that omits a
+freshly-added collaborator; `repos/{repo}/assignees` is the authority.
+
 **Check the main checkout is not bare before anything else uses `ROOT`.** It has gone
 `core.bare = true` on its own, repeatedly — four times in one session, some occurrences
 immediately after a `worktree remove` and some with nothing removed at all. The trigger
@@ -361,8 +409,11 @@ it behind a hidden marker and upsert:
 
 ```bash
 MARKER='<!-- ai-issue-loop:decision -->'
+ME=$(gh api user --jq .login)   # the identity every loop agent posts as
 ID=$(gh api "repos/$OWNER_REPO/issues/<N>/comments" \
-      --jq "[.[] | select((.body // \"\") | startswith(\"$MARKER\"))] | .[0].id // empty")
+  | jq -r --arg me "$ME" --arg marker "$MARKER" \
+      '[.[] | select(.user.login == $me and ((.body // "") | startswith($marker)))]
+       | .[0].id // empty')
 if [ -n "$ID" ]; then
   gh api -X PATCH "repos/$OWNER_REPO/issues/comments/$ID" -f body="$MARKER
 $TEXT"
@@ -372,10 +423,24 @@ $TEXT"
 fi
 ```
 
+**The author gate is the same one Pass 3's verdict read uses, and for the same
+reason.** Anyone can comment on a public PR, so selecting by marker prefix alone
+lets a stranger who posts `<!-- ai-issue-loop:decision -->` first own the slot
+forever: `.[0]` takes the *oldest* match, the token has repo-write so the `PATCH`
+succeeds, and every decision this loop ever reaches lands inside a
+stranger-authored comment while the loop never posts one of its own. `.user.login`
+against `gh api user`, not `author_association`, for the reason spelled out in
+Pass 3.
+
 `// empty` is load-bearing: `.[0].id` on an empty array is `null`, which `jq -r`
 prints as the four characters `null` — a non-empty string that passes `[ -n ]` and
 sends the `PATCH` to comment id `null`. The upsert would then never post anything,
-silently, which is the one failure mode worse than duplicates.
+silently, which is the one failure mode worse than duplicates. `(.body // "")` is
+load-bearing for the mirror-image reason: a null body throws, aborting the filter
+and emptying `ID`, which re-enters the duplicate-comment branch this whole section
+exists to prevent. Both values come in through `--arg` rather than shell
+interpolation, so the marker and login are jq *data* and cannot be parsed as
+filter syntax.
 
 One comment per PR, edited in place, so the timeline shows the *current* reason
 rather than a log of every tick that ever ran. What it says — and whether to say
@@ -389,9 +454,13 @@ worked. So for every non-Dependabot PR carrying both `ai-ok-code` and `ai-ok-sec
 not `ai-changes`, assign it and clear the stale review flag:
 
 ```bash
-gh pr edit <N> --add-assignee @me --remove-label ai-review
+gh pr edit <N> --add-assignee @me --remove-label ai-review \
+  ${AGENT_USER:+--remove-assignee "$AGENT_USER"}
 ```
 
+Dropping `AGENT_USER` is half the signal: leaving the agent assigned alongside
+you says you both owe it something, which is the one thing never true here.
+
 It lands in the user's *Assigned to you* view, and the labels then read as state rather
 than noise — `ai-ok-code, ai-ok-sec` with no `ai-review` means **waiting on you**. Both
 halves matter: Pass 3 only ever *adds* the `ai-ok-*` labels, so without the removal a
@@ -451,7 +520,7 @@ no other branch of this pass assigns it, which leaves it in no *Assigned to you*
 view at all:
 
 ```bash
-gh pr edit <N> --add-assignee @me
+gh pr edit <N> --add-assignee @me ${AGENT_USER:+--remove-assignee "$AGENT_USER"}
 ```
 
 Count it as `rev`. Idempotent, so it also picks up ones an earlier tick stranded.
@@ -536,7 +605,7 @@ Only then:
 REMOVED=1                                          # every removal in this pass sets this
 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
+gh issue edit <N> --remove-label ai-wip ${AGENT_USER:+--remove-assignee "$AGENT_USER"} 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
@@ -570,7 +639,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 (and set `REMOVED=1`) |
+| 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 ${AGENT_USER:+--remove-assignee "$AGENT_USER"}`, comment, remove the worktree (and set `REMOVED=1`) |
 | 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 (and set `REMOVED=1`) |
 
@@ -755,10 +824,13 @@ intended; one that died after posting is now recovered instead of duplicated.
 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
+gh pr edit <N> --add-label ai-reviewing-code ${AGENT_USER:+--add-assignee "$AGENT_USER"}   # then spawn code-reviewer
+gh pr edit <N> --add-label ai-reviewing-sec  ${AGENT_USER:+--add-assignee "$AGENT_USER"}   # then spawn security-expert
 ```
 
+Assigning `AGENT_USER` on the claim is idempotent — both arms adding the same
+account is one assignee, and Pass 1 removes it at the handoff.
+
 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
@@ -1016,8 +1088,10 @@ and a blank line — naming what each round changed and why the reviewer kept ob
 then:
 
 ```bash
-gh issue edit <M> --add-label ai-blocked --remove-label ai-wip --add-assignee @me
-gh pr edit <N> --add-assignee @me --remove-label ai-review
+gh issue edit <M> --add-label ai-blocked --remove-label ai-wip --add-assignee @me \
+  ${AGENT_USER:+--remove-assignee "$AGENT_USER"}
+gh pr edit <N> --add-assignee @me --remove-label ai-review \
+  ${AGENT_USER:+--remove-assignee "$AGENT_USER"}
 ```
 
 Leave the worktree and PR in place for the human; a ping-pong stall is the case where
@@ -1128,16 +1202,30 @@ does not stack duplicates:
 
 ```bash
 gh issue view <N> --json comments \
-  --jq '[.comments[] | select(.body | startswith("🤖 *Automated — triage"))] | length'
+  | jq -r --arg me "$(gh api user --jq .login)" \
+      '[.comments[]
+        | select(.author.login == $me and ((.body // "") | startswith("🤖 *Automated — triage")))]
+       | length'
 ```
 
+Gated on the loop's own login for the same reason as the decision upsert above,
+inverted: anyone can comment on a public issue, so ungated a stranger who opens
+with that header *suppresses* the decline comment and the issue is left labelled
+with nothing on the timeline saying why. `.author.login` here, not `.user.login`
+— `gh issue view --json` is GraphQL and names the field differently from the REST
+payload the upsert reads.
+
 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 --remove-label ai-ready
+gh issue edit <N> --add-label ai-wip --remove-label ai-ready \
+  ${AGENT_USER:+--add-assignee "$AGENT_USER"}
 ```
 
+Assigning here is what makes the issue list honest: from this moment an agent
+owns the work, and an unassigned `ai-ready` issue is genuinely untouched.
+
 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
@@ -1274,9 +1362,13 @@ Then spawn a background implementer agent:
 > If you cannot finish, hand it back so a human can see it:
 >
 > ```bash
-> gh issue edit <N> --add-label ai-blocked --remove-label ai-wip --add-assignee @me
+> gh issue edit <N> --add-label ai-blocked --remove-label ai-wip --add-assignee @me \
+>   <the orchestrator substitutes `--remove-assignee <AGENT_USER>` here, or nothing>
 > ```
 >
+> Handing back means the issue stops being the agent's: the human must end up the
+> only assignee, or the list still reads as though something is working on it.
+>
 > Then comment why. **Leave your worktree in place — never run
 > `git worktree remove`.** Pass 2 of the next tick reaps it (the issue is no
 > longer `ai-wip` and has no open PR, so it matches the orphan rule) and rebuilds

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

@@ -42,6 +42,12 @@ argument.
    Filter the PR list to those carrying an `ai-*` label — a PR without one is
    not in the pipeline and the loop will never touch it.
 
+   **Read the assignee as "whose turn"**, when the loop is configured with an
+   agent account (`AI_LOOP_AGENT`): that account assigned means an agent is
+   working or reviewing, the human assigned means it is waiting on them, and
+   nobody assigned means queued. Say which in the report rather than listing raw
+   logins — "waiting on you" beats "assignee: someone".
+
 3. **Work out each PR's next move** from its labels, so the report says what
    happens rather than just listing state:
 

package/skills/ai-workflow/SKILL.md

@@ -47,6 +47,12 @@ ROOT=$(git rev-parse --path-format=absolute --git-common-dir)/..; ROOT=$(cd "$RO
 WT_ROOT="$(dirname "$ROOT")/$(basename "$ROOT")-worktrees"
 R=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
 git -C "$ROOT" fetch --prune
+
+# Optional: the account in-flight work is assigned to, so `assignee` says whose
+# turn it is. Unset → nothing below assigns, exactly as before. See the
+# ai-issue-loop skill's Pass 0 for why this is repo config rather than an env var.
+AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
+[ -n "$AGENT_USER" ] && { gh api "repos/$R/assignees/$AGENT_USER" --silent 2>/dev/null || AGENT_USER=""; }
 ```
 
 `R` comes from the working directory's remote and is the only repo touched —
@@ -112,7 +118,8 @@ carrying both re-enters the queue the instant `ai-wip` clears):
 
 ```bash
 for n in <numbers>; do
-  gh issue edit -R "$R" $n --add-label ai-wip --remove-label ai-ready
+  gh issue edit -R "$R" $n --add-label ai-wip --remove-label ai-ready \
+    ${AGENT_USER:+--add-assignee "$AGENT_USER"}
   SLUG="ai-$n-<3-4 kebab words from the title>"
   mkdir -p "$WT_ROOT"
   git -C "$ROOT" worktree add "$WT_ROOT/$SLUG" -b "$SLUG" origin/main
@@ -133,9 +140,12 @@ and why.
 Call `Workflow` with the script below, passing the selected issues as `args`:
 
 ```
-Workflow({args: {repo: R, issues: [{number, title, slug, worktree}, …]}, script: …})
+Workflow({args: {repo: R, agentUser: AGENT_USER, issues: [{number, title, slug, worktree}, …]}, script: …})
 ```
 
+Pass `agentUser` as the empty string when `AGENT_USER` is unset — the script
+tests it, so an empty value simply drops every assign.
+
 ```js
 export const meta = {
 	name: 'ai-workflow',
@@ -205,8 +215,9 @@ leave the worktree in place, and return pr: null.`,
 
 	(r, i) => !r?.pr ? [] : parallel(REVIEWERS.map((v) => () => agent(
 		`Review GitHub PR #${r.pr} in ${args.repo}. First claim your arm:
-\`gh pr edit ${r.pr} --add-label ${v.claim}\` — it stops a concurrent
-ai-issue-loop tick spawning a duplicate of you.
+\`gh pr edit ${r.pr} --add-label ${v.claim}${args.agentUser ? ` --add-assignee ${args.agentUser}` : ''}\` — the label
+stops a concurrent ai-issue-loop tick spawning a duplicate of you, and the
+assignee says the PR is the machine's turn until Pass 1 hands it back.
 
 Read exactly three things and nothing else: \`gh pr view ${r.pr}\`,
 \`gh pr diff ${r.pr}\`, and \`gh issue view ${i.number}\`. Do not explore the