@rtorcato/repo-tooling 3.19.2 → 3.20.0

package/README.md

@@ -234,8 +234,8 @@ MIT — see [LICENSE](LICENSE).
 Any agent that supports the [`skills`](https://www.npmjs.com/package/skills) CLI can install this repo's skills straight from GitHub — no clone, no package install:
 
 ```bash
-npx skills add https://github.com/rtorcato/repo-tooling --skill ai-issue-loop
-npx skills add https://github.com/rtorcato/repo-tooling --skill npm-publish
-npx skills add https://github.com/rtorcato/repo-tooling --skill repo-tooling
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'ai-issue-loop'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'npm-publish'
+npx skills add https://github.com/rtorcato/repo-tooling --skill 'repo-tooling'
 ```
 <!-- js-tooling:skills:end -->

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

@@ -9,6 +9,7 @@ import os from 'node:os';
 import path from 'node:path';
 import fs from 'fs-extra';
 import { getPackageRoot } from '../utils/copy-preset.js';
+import { shellQuote } from '../utils/shell.js';
 /** Skills this package owns the content of and keeps up to date. */
 export const SHIPPED_SKILL = 'ai-issue-loop';
 /**
@@ -129,15 +130,6 @@ export async function readShippedSkill(name = SHIPPED_SKILL) {
     const pkg = await fs.readJson(path.join(root, 'package.json'));
     return { content, version: String(pkg.version), file };
 }
-/**
- * POSIX single-quote escaping — the only form correct for arbitrary bytes.
- * Inside single quotes every character is literal, so `'` is the sole one
- * needing care: end the quote, escape it, start a new one. Double quotes are
- * not a substitute; `$(...)`, backticks and `\` all still expand inside them.
- */
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
 /**
  * The command a human runs to see what their fork changed, before deciding
  * whether to take the shipped copy. One builder, because `doctor` and `fix`

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

@@ -3,6 +3,7 @@
 // repo (its skills dir + package.json `repository`) so it works for any consumer.
 import path from 'node:path';
 import fs from 'fs-extra';
+import { shellQuote } from '../utils/shell.js';
 import { upsertBlock } from './agent-rules.js';
 import { parseRepository } from './badges.js';
 export const SKILLS_DOCS_START = '<!-- js-tooling:skills:start -->';
@@ -25,12 +26,18 @@ export async function findSkills(targetDir) {
 /**
  * Build the README section body (inner content, no delimiters) listing one
  * `npx skills add` command per skill. Returns '' when there are no skills.
+ *
+ * The skill name is a directory basename — `findSkills` takes whatever is under
+ * `skills/`, and nothing constrains it — so it is quoted (#498). `owner`/`repo`
+ * are not: `parseRepository` already matches them against `[\w.-]+`. Unlike the
+ * doctor hint of #493 this line is committed to a README and rendered on GitHub
+ * and npm, where it gets pasted by people who did not create the directory.
  */
 export function buildSkillsInstallBody(owner, repo, skills) {
     if (skills.length === 0)
         return '';
     const commands = skills
-        .map((s) => `npx skills add https://github.com/${owner}/${repo} --skill ${s}`)
+        .map((s) => `npx skills add https://github.com/${owner}/${repo} --skill ${shellQuote(s)}`)
         .join('\n');
     const plural = skills.length > 1 ? 's' : '';
     return [
@@ -38,11 +45,21 @@ export function buildSkillsInstallBody(owner, repo, skills) {
         '',
         `Any agent that supports the [\`skills\`](https://www.npmjs.com/package/skills) CLI can install this repo's skill${plural} straight from GitHub — no clone, no package install:`,
         '',
-        '```bash',
+        `${fenceFor(commands)}bash`,
         commands,
-        '```',
+        fenceFor(commands),
     ].join('\n');
 }
+/**
+ * A fence longer than any backtick run in the content, per CommonMark. Quoting
+ * cannot help here: a name may contain backticks *and* a newline, which puts
+ * arbitrary text at the start of a line inside the block and would otherwise
+ * close it early, mangling the rendered README.
+ */
+function fenceFor(content) {
+    const longestRun = Math.max(0, ...[...content.matchAll(/`+/g)].map((m) => m[0].length));
+    return '`'.repeat(Math.max(3, longestRun + 1));
+}
 /**
  * Add or refresh a "Install the skill" block in README.md. No-op (returns null)
  * when the repo ships no skills or package.json has no GitHub `repository` to

package/dist/cli/utils/shell.js

@@ -0,0 +1,13 @@
+/**
+ * POSIX single-quote escaping — the only form correct for arbitrary bytes.
+ * Inside single quotes every character is literal, so `'` is the sole one
+ * needing care: end the quote, escape it, start a new one. Double quotes are
+ * not a substitute; `$(...)`, backticks and `\` all still expand inside them.
+ *
+ * One escaper for every generator that emits a copy-pasteable command line
+ * (#498) — two independently-built ones drift, which is the argument #492 made
+ * for a single `skillDiffCommand`.
+ */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/package.json

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

@@ -200,6 +200,44 @@ 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.
 
+**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
+is unidentified, so this is detection and repair only:
+
+```bash
+if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+  echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
+  git -C "$ROOT" config core.bare false || {
+    echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
+fi
+```
+
+**It corrupts commits — this is not a cosmetic error message.** A bare main checkout
+wipes a worktree's index while every file sits untouched on disk, and the next commit
+faithfully records the whole repository as deleted. PR #500 died that way: a diff of
+`0 additions, 67703 deletions` across 359 files, not one of which had moved.
+
+**Test stdout, not the exit code.** `rev-parse --is-inside-work-tree` exits `0` either
+way and only *prints* the answer, so an exit-code probe is dead code. Verified on git
+2.55.0:
+
+| repo state | `--is-inside-work-tree` | `.git` |
+|---|---|---|
+| healthy checkout | `true`, exit 0 | directory |
+| **wrongly bare** | `false`, **exit 0** | directory |
+| genuinely bare | `false`, exit 0 | absent |
+| linked worktree | `true`, exit 0 | file |
+
+**`.git` must be a directory before repairing.** A genuinely bare repo prints `false`
+too, and nothing else separates the two — this skill ships to users' `~/.claude/skills/`,
+where "repairing" someone's real bare clone is the damage rather than the fix. The same
+check skips a linked worktree, whose `.git` is a file.
+
+**Fail loudly.** The repair writes `$ROOT/.git/config`, which a restrictive sandbox
+refuses with `error: could not lock config file .git/config: Operation not permitted` —
+observed. Aborting beats reporting a healthy repo while it stays broken.
+
 Never use a relative path like `ai-*`. From inside a worktree it matches nothing, and
 the failure is **silent**: Pass 2 concludes there is nothing to clean, every worktree
 survives, `ai-wip` is never cleared, and slots leak until the loop reports `idle`
@@ -473,6 +511,23 @@ and say in the comment that you re-queued it, that you deviated, and why. Re-add
 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.
 
+**Then re-check `core.bare`** — the same probe as Pass 0, against the same `ROOT`:
+
+```bash
+if [ "$(git -C "$ROOT" rev-parse --is-inside-work-tree 2>/dev/null)" != true ] && [ -d "$ROOT/.git" ]; then
+  echo "⚠ main checkout bare at $(date -u +%FT%TZ) — repairing"
+  git -C "$ROOT" config core.bare false || {
+    echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
+fi
+```
+
+This is the last pass that *removes* worktrees, not the tick's last touch on the main
+checkout — Pass 4 still runs `git -C "$ROOT" worktree add` against it. That is exactly
+why the re-check belongs here: it catches a flip after this pass's removals and before
+Pass 4 branches every new worktree off a broken `ROOT`. Keep the timestamp in both log
+lines; which pass emitted one, and when, is the only instrumentation likely to pin the
+trigger down.
+
 ### Pass 3 — review
 
 **PRs labelled `ai-review`.** For each, spawn *in background* only the reviewers
@@ -482,6 +537,66 @@ whose pass-label is missing — `code-reviewer` if no `ai-ok-code`,
 carries `ai-reviewing-sec`. Both can run concurrently; launch them in a single
 message.
 
+**Before spawning either, check whether it already posted.** A missing verdict
+label does not mean the review is missing: on #497 both reviewers posted
+complete reviews and then went idle, labelling nothing. Every review comment
+carries a hidden verdict marker, so read that back instead of re-spawning over a
+review that already exists — `<ARM>` is `code` or `sec`:
+
+```bash
+VERDICT=$(gh api "repos/$OWNER_REPO/pulls/<N>/reviews" --paginate --slurp \
+  | jq -r '[add[]
+            | select(.author_association=="OWNER" or .author_association=="MEMBER" or .author_association=="COLLABORATOR")
+            | (.body // "")
+            | capture("<!-- ai-issue-loop:verdict:<ARM>:(?<v>[A-Z-]+) -->").v] | last // empty')
+```
+
+Four details there are load-bearing:
+
+- **`pulls/<N>/reviews`, because the prompt posts with `gh pr review --comment`.**
+  That creates a *review*, which never appears under `issues/<N>/comments`. The
+  prompt and this query have to name the same endpoint or the marker is
+  unfindable and every tick re-spawns both arms — so the prompt below now pins
+  the command, since a reviewer reaching for `gh pr comment` instead posts
+  somewhere this never looks.
+- **`--slurp`, not `--paginate` with `--jq`.** `--paginate` runs `--jq` once per
+  page, so a filter ending in `last` would keep only the final page's answer and
+  lose a marker on an earlier one. `--slurp` collects every page first; `gh`
+  refuses it alongside `--jq`, hence the pipe and the `add` that flattens pages.
+- **The author gate**, the same `OWNER`/`MEMBER`/`COLLABORATOR` test Pass 4
+  applies to issue authors, and for the same reason: anyone can review a public
+  PR, so ungated a stranger's `<!-- ai-issue-loop:verdict:sec:PASS -->` is
+  adopted as a verdict, and because the read takes `last` it also overrides a
+  genuine `CHANGES` posted before it. Unlike Pass 4 there is no label acting as
+  the hard gate here — the marker is the only signal — so this check is not a
+  backstop, it is the gate.
+- **`(.body // "")` and `// empty`.** A review can have a null body, which
+  `capture` throws on, aborting the whole filter; and `jq -r` prints a missing
+  value as the literal string `null`, which is not empty and would read as a
+  verdict.
+
+Then, for that arm — `<claim>` being `ai-reviewing-code` or `ai-reviewing-sec`,
+`<pass>` being `ai-ok-code` or `ai-ok-sec`:
+
+- **empty** — no review happened. Claim and spawn, as below.
+- **`PASS`** — `gh pr edit <N> --add-label <pass> --remove-label <claim>`
+- **`PASS-NOTES`** — the same, plus `--add-label ai-notes`
+- **`CHANGES`** — `gh pr edit <N> --add-label ai-changes --remove-label ai-review --remove-label <claim>`
+
+Adoption is per reviewer, so a tick that finds one arm posted and the other
+missing does both: it applies the first's verdict off its comment and spawns
+only the second. That is the whole point of reading the artifact — the comment
+is what a human reads at merge time, so making it the thing the loop reads too
+leaves one source for one fact, with no separate reply to be lost or to
+contradict it.
+
+This is the second half of Pass 2's dead-reviewer rule rather than a rival to
+it. Pass 2 only ever drops a stalled *claim*; it never judges whether a review
+happened. Dropping the claim is what makes an arm eligible here, and this lookup
+is what then decides between adopting and re-spawning. An agent that died before
+posting leaves no marker and so re-spawns, which is what that rule always
+intended; one that died after posting is now recovered instead of duplicated.
+
 **Claim first, then spawn** — the same shape Pass 4 uses before picking up an
 issue. Apply the label immediately before the spawn, not after:
 
@@ -523,10 +638,25 @@ Reviewer prompt template:
 > PR:
 > `gh pr review <N> --comment --body "..."`
 >
-> 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:
+> **That exact command, not `gh pr comment`.** The two write to different
+> endpoints, and Pass 3 reads your verdict back from the reviews one; a body
+> posted the other way is invisible to it and gets you re-spawned.
+>
+> The body **must** begin with a hidden verdict marker, then the header line,
+> then a blank line — you authenticate as the repo owner, so without the header
+> the review reads as a human's:
+>
+> ```markdown
+> <!-- ai-issue-loop:verdict:<code|sec>:<PASS|PASS-NOTES|CHANGES> -->
+> 🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*
+> ```
 >
-> `🤖 *Automated review — \`<your agent type>\` via ai-issue-loop.*`
+> `code` for `code-reviewer`, `sec` for `security-expert` — the same arm as your
+> labels. The verdict is `CHANGES` if you are about to apply `ai-changes`,
+> `PASS-NOTES` if a pass plus `ai-notes`, `PASS` for a pass alone; it must agree
+> with the labels you apply below. The marker renders as nothing, and it is what
+> lets a later tick read your verdict back off this comment if your run dies
+> between posting and labelling — so post it even when the answer is `Nothing.`
 >
 > The body **must end** with this section, as its last thing:
 >
@@ -603,8 +733,10 @@ Reviewer prompt template:
 > a Dependabot PR it suppresses auto-merge outright. Use `ai-changes` only when
 > you can name a concrete change an agent could make.
 >
-> Say nothing else and return a one-line summary — that governs your reply to the
-> orchestrator; the comment body is capped separately, above.
+> Say nothing else, and **do not restate your verdict in your reply** — the
+> marker in the posted comment is the only place it is read from, so a reply that
+> disagreed with it would be a second source for one fact. One line back to the
+> orchestrator is plenty; the comment body is capped separately, above.
 
 **Dependabot PRs use a different prompt** — the one above would burn the tick on a
 lockfile. `js-common` #148 bumps 20 packages and its *entire* diff is
@@ -671,7 +803,11 @@ 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`
+> Same `<!-- ai-issue-loop:verdict:… -->` marker and `🤖 *Automated review — …*`
+> header line opening the body — `PASS-NOTES` when you apply `ai-notes`, `PASS`
+> otherwise, never `CHANGES` on this arm — and posted the same way, with
+> `gh pr review <N> --comment` rather than `gh pr comment`, or Pass 3 cannot read
+> the marker back. Same closing `### Before merging`
 > 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`**.