@rtorcato/repo-tooling 3.24.0 → 3.26.0

package/AGENTS.md

@@ -24,6 +24,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `fix --dry-run` | ✅ | ✅ | Print what each fixer would write without writing. Combine with `--json`. |
 | `list --json` | ✅ | ✅ | Enumerate the library's surface area. Each entry has `{ name, description, exports, fixTarget }`. |
 | `copy <name>` | ✅ | text only | Copy a single preset (`biome`, `tsconfig`) into the current directory. |
+| `loop guard --root <path>` | ✅ | ✅ | Guard an `ai-issue-loop` tick: repair a wrongly-bare main checkout, gate the `node_modules` rebuild (`--removed`). Exit `0` continue, `1` repair failed, `2` root is not a repairable checkout — both non-zero halt the tick. |
 
 ## Recommended workflows
 
@@ -104,6 +105,7 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `src/cli/commands/doctor.ts` — all checks and the public `runDoctor(dir)` / `evaluateNodeVersion(version)` / `nextStepSuggestions(results)`
 - `src/cli/commands/fix.ts` — `Fixer` interface, fixer registry, `fixCommand`
 - `src/cli/commands/fix-targets.ts` — shared check → fix target map (used by both doctor's footer and fix's lookup)
+- `src/cli/commands/loop-guard.ts` — `loop guard`: the `--is-inside-work-tree` / `.git` invariant table and the `node_modules` rebuild gate, drained out of the ai-issue-loop skill's prose (#519)
 - `src/cli/generators/` — one file per concern (linting, testing, build, git, github-actions, security, misc)
 - `tooling/` — every shipped preset, mirrored 1:1 with `package.json` `exports`
 

package/README.md

@@ -91,6 +91,7 @@ See the [Getting Started guide](https://rtorcato.github.io/repo-tooling/guides/g
 | `copy <config>` | Copy a single config file into the current project. | `npx @rtorcato/repo-tooling copy biome` |
 | `doctor` | Diagnose an existing project for missing or drifted tooling. | `npx @rtorcato/repo-tooling doctor` |
 | `fix [target]` | Apply scaffolders for what `doctor` flagged (`--yes`, `--dry-run`, `--diff`). | `npx @rtorcato/repo-tooling fix` |
+| `loop guard` | Repair a main checkout that has gone `core.bare = true`, and gate the `node_modules` rebuild after a worktree removal. Exits `1` if the repair failed and `2` if the root is not a repairable checkout — see `--help`. | `npx @rtorcato/repo-tooling loop guard --root .` |
 
 Prefer to run the audit in CI? `doctor` also ships as a GitHub Action:
 
@@ -181,10 +182,11 @@ 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 six skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (never hand-cut a release), `ai-issue-loop` (the label-driven
-issue → PR pipeline), `ai-workflow` (burst the `ai-ready` queue in parallel
-worktrees), `ai-issue` (file agent-executable issues) and `ai-loop-status`
-(read-only pipeline status) — in any session:
+`npm-publish` (never hand-cut a release), `ai-workflow` (**the entry point** to
+the `ai-ready` issue → PR pipeline: bursts the queue in parallel worktrees, then
+schedules the engine below), `ai-issue-loop` (that engine — one stateless tick;
+it runs on a loop rather than being typed), `ai-issue` (file agent-executable
+issues) and `ai-loop-status` (read-only pipeline status) — in any session:
 
 ```
 /plugin marketplace add rtorcato/repo-tooling

package/dist/base/checks.js

@@ -535,6 +535,100 @@ export async function checkClaudeSkills(skillsDir) {
         detail: `${SHIPPED_SKILLS.length} skills installed at ${[...versions].join(', ')}`,
     };
 }
+/**
+ * The skills *this repo* declares it depends on — `requiredSkills` in
+ * `.repo-tooling.json` (#533). Where `checkClaudeSkills` above reports on the
+ * package's whole skill set as a machine-level nicety, this one is the repo
+ * asserting a dependency, so it names the skills the repo actually runs on and
+ * reports a stale installed copy against them.
+ *
+ * Staleness is the failure mode it exists for. Absence fails loudly the moment
+ * something reaches for the skill; a copy three releases behind runs to
+ * completion without complaint — observed 2026-08-26, an `ai-issue-loop` missing
+ * both its decision-comment security gate and its decay rule.
+ *
+ * Same severity rule as `checkClaudeSkills`, for the same reason: it probes the
+ * machine, not the repo, so it never returns `drift` or `missing`. A contributor
+ * with no Claude installed must not fail this repo's `doctor`.
+ *
+ * **Check and hint only.** The fixer writes into `~/`, and repo config that
+ * triggers writes outside the repo is the shape of a supply-chain attack even
+ * when the content is benign. doctor says stale; the human runs the fixer.
+ */
+export async function checkRequiredSkills(names, skillsDir) {
+    const check = 'Required skills';
+    const hint = 'Run `npx @rtorcato/repo-tooling fix claude-skills` yourself to install or refresh them — add `--force-skills` to overwrite a locally modified copy. It writes to `~/.claude`, outside this repo, so nothing runs it for you.';
+    // A name outside SHIPPED_SKILLS has no shipped asset to hash against, and
+    // reading one would throw rather than report. The published schema rejects it
+    // in an editor; this is the runtime half of the same validation.
+    const unknown = names.filter((name) => !SHIPPED_SKILLS.includes(name));
+    if (unknown.length > 0) {
+        return {
+            check,
+            status: 'optional-missing',
+            detail: `.repo-tooling.json lists ${unknown.join(', ')}, which this package does not ship`,
+            hint: `requiredSkills accepts ${SHIPPED_SKILLS.join(', ')}`,
+        };
+    }
+    const statuses = [];
+    for (const name of names)
+        statuses.push([name, await claudeSkillStatus(name, skillsDir)]);
+    const missing = statuses.filter(([, s]) => !s.installed).map(([name]) => name);
+    // `needsInstall` is `behind && pristine`, so these two partitions are disjoint:
+    // a copy matching no shipped version is a fork, not something to update.
+    const stale = statuses.filter(([, s]) => s.installed && s.needsInstall);
+    const modified = statuses.filter(([, s]) => s.contentState && s.contentState !== 'pristine');
+    const parts = [
+        missing.length > 0 ? `not installed: ${missing.join(', ')}` : null,
+        ...stale.map(([name, s]) => `${name} is stale — installed ${s.installedVersion ?? 'unstamped'}, this package ships ${s.shippedVersion}`),
+        ...modified.map(([name, s]) => `${name} at ${s.file} matches no version this package has shipped`),
+    ].filter((part) => part !== null);
+    if (parts.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `${names.length} required skill(s) installed and current: ${names.join(', ')}`,
+        };
+    }
+    return { check, status: 'optional-missing', detail: parts.join('; '), hint };
+}
+/**
+ * The MCP servers this repo's workflow assumes — `mcp.recommended` in
+ * `.repo-tooling.json` (#534). Informational in the strongest sense: it reports
+ * which recommended names the repo-scoped `.mcp.json` does not declare, and
+ * stops there.
+ *
+ * Never `drift`, never a CI failure, and deliberately no fixer — MCP servers
+ * execute code, so installing one from committed repo config would be an install
+ * directive rather than a recommendation. `.mcp.json` carries Claude Code's own
+ * first-use consent prompt; that is where the decision belongs.
+ *
+ * User-scoped MCP config is not probed at all. It is machine-private, and a
+ * server configured there is none of this repo's business.
+ */
+export async function checkRecommendedMcp(dir, recommended) {
+    const check = 'Recommended MCP';
+    // Absent, malformed or unreadable all mean the same thing here — nothing is
+    // declared — and none of them is worth its own finding on an advisory check.
+    const declared = await fs
+        .readJson(path.join(dir, '.mcp.json'))
+        .then((raw) => Object.keys(raw?.mcpServers ?? {}))
+        .catch(() => []);
+    const absent = recommended.filter((entry) => !declared.includes(entry.name));
+    if (absent.length === 0) {
+        return {
+            check,
+            status: 'ok',
+            detail: `.mcp.json declares all ${recommended.length} recommended server(s): ${recommended.map((e) => e.name).join(', ')}`,
+        };
+    }
+    return {
+        check,
+        status: 'optional-missing',
+        detail: absent.map((e) => `${e.name} (${e.importance}) — ${e.why}`).join('; '),
+        hint: 'Advisory only. Add what you want to `.mcp.json` by hand; nothing here installs or enables an MCP server.',
+    };
+}
 /**
  * Conventional Commits is a repo convention, not a JavaScript one — the config
  * file is the same in any repo that has node available to run commitlint, so

package/dist/base/git-identity.js

@@ -44,6 +44,53 @@ const DETAIL = {
 const HINT = 'Commits made with this identity will not link to your forge account, and the address cannot be added as a verified secondary email to fix them retroactively (#327). Set a real one: `git config --global user.email you@yourdomain.com` — or per-repo, drop `--global`.';
 const CHECK = 'Git identity';
 const GIT_TIMEOUT_MS = 5_000;
+/**
+ * Git exports these to everything a hook runs, and they outrank `cwd`/`-C`: a
+ * child spawned from a `pre-push` answers about the *hook's* repository, not
+ * the directory it was handed. Harmless for a config read; not harmless for
+ * `loop guard`, whose whole job is deciding whether one specific checkout has
+ * gone bare (#519). Every caller here names its repo explicitly, so the
+ * ambient one is never what was meant.
+ *
+ * This is `git rev-parse --local-env-vars` verbatim — git's own answer, and what
+ * githooks(1) says to clear before touching a different repository. Do not
+ * curate it by hand: the first version of this list was assembled from the vars
+ * that looked repository-ish and missed the `GIT_CONFIG*` family, which
+ * redirects where `git config` reads *and writes* — the exact operation this
+ * module's callers perform.
+ *
+ * Kept byte-identical with `AMBIENT_GIT_REPO_VARS` in `scripts/lib/git-env.mjs`;
+ * a test asserts both cover what the installed git reports. Two copies because
+ * this one compiles into `dist/` for consumers and that one is loaded raw by
+ * `.mjs` scripts that run before any build.
+ */
+export const AMBIENT_REPO_VARS = [
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    'GIT_CONFIG',
+    'GIT_CONFIG_PARAMETERS',
+    'GIT_CONFIG_COUNT',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_IMPLICIT_WORK_TREE',
+    'GIT_GRAFT_FILE',
+    'GIT_INDEX_FILE',
+    'GIT_NO_REPLACE_OBJECTS',
+    'GIT_REPLACE_REF_BASE',
+    'GIT_PREFIX',
+    'GIT_SHALLOW_FILE',
+    'GIT_COMMON_DIR',
+    // Not in git's local-env list: it scopes which refs are visible rather than
+    // which repository is used. Cleared anyway — a namespace inherited from a
+    // hook would hide refs from a command that meant to see all of them.
+    'GIT_NAMESPACE',
+];
+function repoScopedEnv() {
+    const env = { ...process.env };
+    for (const key of AMBIENT_REPO_VARS)
+        delete env[key];
+    return env;
+}
 /** Never rejects; a missing or failing git resolves to null. */
 export const realGitExec = (args, cwd) => new Promise((resolve) => {
     let settled = false;
@@ -56,7 +103,11 @@ export const realGitExec = (args, cwd) => new Promise((resolve) => {
     };
     // Args are internal constants, never user free-text — shell:false keeps
     // this injection-safe.
-    const child = spawn('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] });
+    const child = spawn('git', args, {
+        cwd,
+        env: repoScopedEnv(),
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
     let stdout = '';
     const timer = setTimeout(() => {
         child.kill();

package/dist/cli/commands/doctor.js

@@ -20,7 +20,7 @@ import { checkGitIdentity } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
-import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
+import { checkAiSetup, checkBrand, checkCodeowners, checkClaudeSkills, checkCodeQL, checkCommunityHealth, checkCoverageUpload, checkDependabot, checkEditorConfig, checkFile, checkGitHooks, checkGitHubActions, checkGitLabCI, checkNestedLanguages, checkPrePushHook, checkReadmeBadges, checkRecommendedMcp, checkRequiredSkills, COMMITLINT_FILE_CHECK, } from '../../base/checks.js';
 import { allDeps, checkAreTheTypesWrong, checkBiome, checkClaudeWorktreeSettings, checkConfigSchemaVersions, checkDocsSite, checkEnginesNode, checkGitDependencies, checkKnip, checkLintStaged, checkNodeVersionConsistency, checkNodeVersionPin, checkPackageJson, checkPackageManager, checkPublint, checkSemanticRelease, checkSizeLimit, checkTailwind, checkBuildApprovals, checkPnpmWorkspace, checkTreeshakeSetup, checkTurborepo, checkTypedoc, checkVerifyScript, checkVscodeExtensions, evaluateNodeVersion, FILE_CHECKS, findDocsAppDir, jsBadgeAudience, jsGitHooksProfile, readPackageJson, } from '../../languages/js/checks.js';
 export { evaluateNodeVersion };
 const PACKAGE = '@rtorcato/repo-tooling';
@@ -193,6 +193,16 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkAiSetup(dir));
     // User-global, not repo state — see checkClaudeSkills on why it never returns drift.
     results.push(await checkClaudeSkills(opts.skillsDir));
+    // #533: gated on `aiLoop`, which is already the "this repo uses the pipeline"
+    // signal, so a repo that doesn't gets no line at all rather than an empty one.
+    if (lock?.aiLoop && lock.requiredSkills?.length) {
+        results.push(await checkRequiredSkills(lock.requiredSkills, opts.skillsDir));
+    }
+    // #534: advisory. Absent `mcp.recommended` means the repo has nothing to say
+    // about MCP, which is not a finding.
+    if (lock?.mcp?.recommended?.length) {
+        results.push(await checkRecommendedMcp(dir, lock.mcp.recommended));
+    }
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
     return results;

package/dist/cli/commands/fix-targets.js

@@ -49,6 +49,12 @@ export const FIX_TARGETS = {
     'Claude worktree settings': 'ai',
     'Claude skills': 'claude-skills',
     'Copied assets': 'copied-assets',
+    // `Required skills` (#533) and `Recommended MCP` (#534) are deliberately
+    // absent. Both are driven by committed repo config and both would act outside
+    // the repo — installing into `~/.claude`, enabling a code-executing MCP
+    // server. Staying out of this map keeps them out of `fix`'s footer suggestions
+    // and out of every lookup a fixer path makes; their own hints name the command
+    // a human runs by hand.
 };
 /**
  * Where the Swift module's fixers shadow (or extend) the JS-named defaults

package/dist/cli/commands/loop-guard.js

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { realGitExec } from '../../base/git-identity.js';
+/**
+ * The invariant table from the skill, 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 |
+ *
+ * Two things it encodes. **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 (`insideWorkTree` is `null` only when git
+ * itself failed, i.e. there is no repo here). And **`.git` must be a directory
+ * before repairing** — a genuinely bare repo prints `false` too, and nothing
+ * else separates the two. This ships to consumers' machines, where "repairing"
+ * someone's real bare clone is the damage rather than the fix.
+ */
+export function classifyRoot(insideWorkTree, gitEntry) {
+    if (insideWorkTree === null)
+        return 'not-a-repo';
+    if (insideWorkTree.trim() === 'true')
+        return 'work-tree';
+    if (gitEntry === 'directory')
+        return 'wrongly-bare';
+    // A linked worktree's `.git` is a file; its main checkout is where a repair
+    // belongs, and that is not the path we were handed.
+    if (gitEntry === 'file')
+        return 'linked-worktree';
+    return 'genuinely-bare';
+}
+/**
+ * `--frozen-lockfile` forbids re-resolution, so neither `pnpm-lock.yaml` nor a
+ * `pnpm-workspace.yaml` carve-out moves as a side effect of a cleanup.
+ * `--config.confirmModulesPurge=false` gets past
+ * `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY` — which is why a bare `pnpm
+ * install` cannot repair this.
+ */
+export const REBUILD_ARGS = [
+    'install',
+    '--frozen-lockfile',
+    '--config.confirmModulesPurge=false',
+];
+const realInstall = (cwd) => new Promise((resolve) => {
+    // stdout stays clean for the `--json` payload; pnpm's diagnostics are
+    // still visible on stderr.
+    const child = spawn('pnpm', [...REBUILD_ARGS], {
+        cwd,
+        stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    child.on('close', (code) => resolve(code === 0));
+    child.on('error', () => resolve(false));
+});
+async function gitEntryKind(root) {
+    // lstat, not stat: the file/directory distinction is the whole discriminator.
+    try {
+        const stat = await fs.lstat(path.join(root, '.git'));
+        return stat.isDirectory() ? 'directory' : 'file';
+    }
+    catch {
+        return 'absent';
+    }
+}
+/** `ai-*` directories one level down, in either place worktrees are kept. */
+async function findLive(dirs) {
+    const live = [];
+    for (const dir of dirs) {
+        // A missing worktree root is the normal case, not an error.
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.startsWith('ai-'))
+                live.push(path.join(dir, entry.name));
+        }
+    }
+    return live;
+}
+/** The sibling layout the skill uses: `<parent>/<name>-worktrees`. */
+export function defaultWorktreeRoot(root) {
+    return path.join(path.dirname(root), `${path.basename(root)}-worktrees`);
+}
+const stamp = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+const UNUSABLE = {
+    'genuinely-bare': 'main checkout is a genuinely bare repository (.git absent) — refusing to flip core.bare on a real bare clone',
+    'linked-worktree': '--root points at a linked worktree (.git is a file), not the main checkout — repair belongs on the main checkout',
+    'not-a-repo': 'not a git repository',
+};
+/**
+ * One tick's worth of guarding, as data. The command wrapper prints it and
+ * sets the exit code; tests call this directly.
+ */
+export async function runLoopGuard(options = {}) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const worktreeRoot = options.worktreeRoot
+        ? path.resolve(options.worktreeRoot)
+        : defaultWorktreeRoot(root);
+    const git = options.git ?? ((args) => realGitExec(args, root));
+    const install = options.install ?? realInstall;
+    const messages = [];
+    const state = classifyRoot(await git(['rev-parse', '--is-inside-work-tree']), await gitEntryKind(root));
+    let bare = 'healthy';
+    let exitCode = 0;
+    if (state === 'wrongly-bare') {
+        messages.push(`⚠ main checkout bare at ${stamp()} — repairing`);
+        // Writes $ROOT/.git/config, which a restrictive sandbox refuses with
+        // `error: could not lock config file .git/config`. Aborting beats
+        // reporting a healthy repo while it stays broken.
+        if ((await git(['config', 'core.bare', 'false'])) === null) {
+            bare = 'repair-failed';
+            exitCode = 1;
+            messages.push('⚠ repair FAILED — main checkout still bare');
+        }
+        else {
+            bare = 'repaired';
+            messages.push('main checkout repaired — core.bare is false');
+        }
+    }
+    else if (state !== 'work-tree') {
+        bare = 'unrepairable';
+        exitCode = 2;
+        messages.push(`⚠ ${UNUSABLE[state]}`);
+    }
+    else {
+        messages.push('main checkout is a work tree');
+    }
+    const live = await findLive([worktreeRoot, path.join(root, '.claude', 'worktrees')]);
+    const rebuild = await decideRebuild({ root, removed: options.removed === true, exitCode, live });
+    let outcome = rebuild;
+    if (rebuild === 'deferred') {
+        messages.push(`rebuild deferred — ${live.length} worktree(s) still live`);
+    }
+    else if (rebuild === 'rebuilt') {
+        messages.push('rebuilding the main checkout’s node_modules');
+        if (!(await install(root))) {
+            outcome = 'rebuild-failed';
+            // Not fatal: a broken .bin cannot corrupt a commit the way a bare
+            // checkout does. Loud, though — a silent skip is the breakage this
+            // guard exists to end.
+            messages.push('⚠ node_modules rebuild FAILED — main checkout may be unbuildable');
+        }
+        else {
+            messages.push('node_modules rebuilt');
+        }
+    }
+    return { root, worktreeRoot, state, bare, rebuild: outcome, live, exitCode, messages };
+}
+/**
+ * The three load-bearing conditions, kept separate from the run so a test can
+ * assert them without a pnpm install:
+ *
+ * - **`removed`** — set by every removal path, merged-PR cleanup *and* stall
+ *   reaping. A reaped worktree needs this most: its agent died mid-command.
+ * - **`pnpm-lock.yaml`** — non-pnpm repos skip the whole thing.
+ * - **no live worktrees** — the rebuild *purges* the shared modules dir, which
+ *   would be yanked out from under any agent still running in a surviving
+ *   worktree. Deferring costs a broken main checkout until the last worktree
+ *   clears; not deferring costs a live implementer run.
+ */
+export async function decideRebuild(input) {
+    if (!input.removed)
+        return 'not-requested';
+    // Nothing runs against a root we are about to halt the tick over.
+    if (input.exitCode !== 0)
+        return 'skipped-root-unusable';
+    if (!(await fs.pathExists(path.join(input.root, 'pnpm-lock.yaml'))))
+        return 'skipped-no-lockfile';
+    return input.live.length > 0 ? 'deferred' : 'rebuilt';
+}
+export async function loopGuardCommand(options) {
+    const result = await runLoopGuard(options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log();
+        for (const line of result.messages) {
+            console.log(`  ${line.startsWith('⚠') ? chalk.yellow(line) : chalk.gray(line)}`);
+        }
+        console.log();
+    }
+    process.exitCode = result.exitCode;
+}

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import fs from 'fs-extra';
 import packageJson from '../../package.json' with { type: 'json' };
 import { doctorCommand } from './commands/doctor.js';
 import { fixCommand } from './commands/fix.js';
+import { loopGuardCommand } from './commands/loop-guard.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
 async function isSelfRepo(dir) {
@@ -346,6 +347,22 @@ program
     skillsDir: options.skillsDir,
     forceSkills: options.forceSkills,
 }));
+// Mechanics the ai-issue-loop skill used to describe in prose-with-shell (#519).
+// Deliberately outside the isSelfRepo hook below: the loop runs against this
+// repo like any other, and a guard that refuses here would guard nothing.
+const loop = program.command('loop').description('🔁 ai-issue-loop mechanics as tested commands');
+loop
+    .command('guard')
+    .description('🛡️  Repair a wrongly-bare main checkout and gate the node_modules rebuild')
+    .option('--root <path>', 'Main checkout the loop branches worktrees from', process.cwd())
+    .option('--worktree-root <path>', 'Where ai-* worktrees live (default: <root>-worktrees)')
+    .option('--removed', 'A worktree was removed this tick — consider rebuilding node_modules')
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nExit codes:\n' +
+    '  0  root is a usable work tree (healthy, or repaired in place) — continue the tick\n' +
+    '  1  repair was attempted and failed; the root is still bare — halt the tick\n' +
+    '  2  root is not a repairable main checkout (bare clone, linked worktree, or not a repo) — halt the tick\n')
+    .action(loopGuardCommand);
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'setup' || name === 'doctor' || name === 'fix') {

package/dist/cli/utils/lockfile.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import fs from 'fs-extra';
 import packageJson from '../../../package.json' with { type: 'json' };
 import { CONFIG_SCHEMA, validateProjectConfig } from '../commands/setup-presets.js';
+import { SHIPPED_SKILLS } from '../generators/claude-skills.js';
 export const LOCKFILE_NAME = '.repo-tooling.json';
 // Package and bin name used before the js-tooling→repo-tooling rename (#272).
 // The bin no longer exists and the package is 404 on the registry, so any
@@ -17,6 +18,12 @@ export const LEGACY_LOCKFILE_NAME = `.${LEGACY_TOOL_NAME}.json`;
 // files carry no hashes, which reads as "not tracked", never as drift.
 export const LOCKFILE_VERSION = 3;
 const LOCKFILE_SCHEMA_URL = 'https://rtorcato.github.io/repo-tooling/schemas/lockfile.json';
+/**
+ * How much of the repo's workflow assumes a recommended MCP server (#534).
+ * Signals priority to a human reading the file, and nothing more — no code
+ * branches on it beyond printing it.
+ */
+export const MCP_IMPORTANCE = ['nice-to-have', 'important', 'critical'];
 /**
  * JSON Schema for the lockfile, published with the docs site at the exact URL
  * every written lockfile's `$schema` points to (#529). The `satisfies` clauses
@@ -26,8 +33,9 @@ const LOCKFILE_SCHEMA_URL = 'https://rtorcato.github.io/repo-tooling/schemas/loc
  * `pnpm schema:generate` and gated by tests/cli/utils/lockfile-schema.test.ts.
  *
  * A function, not a const: lockfile.ts sits in an import cycle with
- * setup-presets.ts (via the swift scaffolder), so CONFIG_SCHEMA is in its TDZ
- * while this module evaluates.
+ * setup-presets.ts (via the swift scaffolder) and with claude-skills.ts (via
+ * copy-preset.ts), so CONFIG_SCHEMA and SHIPPED_SKILLS are both in their TDZ
+ * while this module evaluates. Reading them here, at call time, is safe.
  */
 // ponytail: key sets are compiler-checked against the type; a changed field
 // *type* (string → number) still needs both lines edited by hand.
@@ -73,6 +81,42 @@ export function lockfileSchema() {
                     },
                 },
             },
+            requiredSkills: {
+                type: 'array',
+                items: { type: 'string', enum: SHIPPED_SKILLS },
+                description: 'Agent skills this repo\'s workflows depend on. doctor compares each installed copy\'s stamped hash against the shipped one and reports a missing or stale skill — always as "not configured", never drift, because it probes the machine rather than the repo. It never runs the fixer for you.',
+            },
+            mcp: {
+                type: 'object',
+                additionalProperties: false,
+                description: "Advisory MCP metadata: names, importance and reasons only, never an install directive. Executable server config belongs in the native .mcp.json, which carries Claude Code's own first-use consent prompt.",
+                properties: {
+                    recommended: {
+                        type: 'array',
+                        description: "MCP servers this repo's workflow assumes. doctor reports which of them .mcp.json does not declare, informationally — it never installs or enables one.",
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['name', 'importance', 'why'],
+                            properties: {
+                                name: {
+                                    type: 'string',
+                                    description: 'The server name as it would appear in .mcp.json.',
+                                },
+                                importance: {
+                                    type: 'string',
+                                    enum: MCP_IMPORTANCE,
+                                    description: "How much of the repo's workflow assumes the server.",
+                                },
+                                why: {
+                                    type: 'string',
+                                    description: 'One line on what the server is for — the thing .mcp.json structurally cannot say.',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
             writtenBy: {
                 type: 'string',
                 description: 'Package name and version that last wrote this file.',
@@ -147,6 +191,8 @@ export async function writeLockfile(dir, config, assets) {
         config,
         ...(carried && Object.keys(carried).length > 0 ? { assets: carried } : {}),
         ...(existing?.aiLoop ? { aiLoop: existing.aiLoop } : {}),
+        ...(existing?.requiredSkills ? { requiredSkills: existing.requiredSkills } : {}),
+        ...(existing?.mcp ? { mcp: existing.mcp } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };

package/dist/cli/utils/shell.js

@@ -1,4 +1,12 @@
 /**
+ * Quote a value as one literal argument **for a POSIX `sh` command line, and
+ * nothing else**. The result is wrong in `cmd.exe`, which does not treat `'` as
+ * a quote at all, and wrong in PowerShell, which does — but escapes an embedded
+ * `'` by doubling it rather than POSIX's `'\''`, so this output still mangles
+ * any value containing one. It is also wrong anywhere the value lands inside
+ * double quotes or an existing quoted string — it is a whole argument, not a
+ * fragment.
+ *
  * 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

package/dist/languages/js/checks.js

@@ -1002,6 +1002,12 @@ export async function checkTreeshakeSetup(dir, pkg) {
  * one pays a full install before it can typecheck, lint or test — unless
  * `.claude/settings.json` tells Claude to symlink the directory from the main
  * checkout (#396). JS-only: the other language modules have nothing to symlink.
+ *
+ * Two consumers, one list (#527). Claude Code honours the setting only for
+ * worktrees it creates itself (`EnterWorktree`); the shipped `ai-issue-loop`
+ * skill creates its own with `git worktree add`, so it reads this same list and
+ * makes the symlinks itself. That is why the check is worth passing on a repo
+ * running the loop, where the setting alone would govern nothing.
  */
 export async function checkClaudeWorktreeSettings(dir) {
     const check = 'Claude worktree settings';

package/package.json

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

@@ -2,11 +2,14 @@
 name: ai-issue-loop
 model: sonnet
 description: |
-  Run one tick of the label-driven GitHub issue pipeline: pick up `ai-ready`
-  issues into per-issue worktrees, review the resulting PRs with other agents,
-  and auto-merge once both reviewers pass. Use when the user says "run the
-  issue loop", "work the ai-ready issues", "babysit the AI PRs", or invokes
-  `/ai-issue-loop`. Designed to be driven by `/loop 15m /ai-issue-loop`.
+  **The engine behind `/ai-workflow` — normally you do not invoke this
+  directly.** One stateless tick over the GitHub label state: answer
+  `ai-changes` with a fix round, merge Dependabot PRs, hand passed issue PRs to
+  the human, clean up merged worktrees, reap stalled agents, and pick up any
+  remaining `ai-ready` issues. `/ai-workflow` is the entry point and schedules
+  this itself via `/loop 15m /ai-issue-loop`; reach for it directly only to
+  force a tick early — "run one tick", "babysit the AI PRs" — or when the user
+  invokes `/ai-issue-loop`. Only Dependabot PRs ever merge unattended.
   GitHub only (`gh`) — not GitLab.
 ---
 
@@ -77,11 +80,11 @@ drift with a second copy to maintain.
 | `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. Reviewers never apply it to a Dependabot PR. |
+| `ai-ok-code` | PR | `code-reviewer` passed. In-flight only — Pass 1 strips it at handoff. |
+| `ai-ok-sec` | PR | `security-expert` passed. In-flight only — Pass 1 strips it at handoff. |
+| `ai-changes` | PR | A reviewer requested changes, **or** Pass 1 sent the PR back over CI. Reviewers never apply it to a Dependabot PR. |
 | `ai-notes` | PR | Passed, but a reviewer left something to read before merging. |
-| `merge-ready` | PR | Both agent reviews passed and the PR is mergeable — waiting on a human. Derived state; Pass 1 applies and strips it. |
+| `merge-ready` | PR | Both agent reviews passed and the PR is mergeable — waiting on a human. Derived state; Pass 1 applies and strips it, and it **supersedes** the `ai-ok-*` pair rather than joining it. |
 | `ai-suggested` | issue | Follow-up a reviewer filed. A triage queue, never auto-picked. Pass 2 closes it after 30 days untouched. |
 | `holding` | issue | A gate — closes on human judgement, never picked up. |
 
@@ -147,12 +150,13 @@ 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 ─> ai-reviewing-* ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> merge-ready, assigned to you, ai-review dropped
+PR: ai-review ─> ai-reviewing-* ─┬─> ai-ok-code + ai-ok-sec ─┬─ issue PR  ─> merge-ready, assigned to you (ai-review + both ai-ok-* dropped)
                                  │        (± ai-notes)       │              ─> YOU merge ─> worktree removed
                                  │                           └─ dependabot ─┬─ no ai-notes ─> auto-merge ─> worktree removed
                                  │                                          └─ ai-notes ───> merge-ready, assigned to you
                                  └─> ai-changes (issue PRs only) ─> fix round (max 2) ─> ai-review
-                                                                               └─ round 3 ─> ai-blocked
+                                     ▲                                         └─ round 3 ─> ai-blocked
+                                     └─ Pass 1 sends back: not CLEAN, or a required check FAILED
 ```
 
 `ai-reviewing-code` / `ai-reviewing-sec` are the *claim* step: Pass 3 applies one
@@ -263,9 +267,9 @@ immediately after a `worktree remove` and some with nothing removed at all. The
 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
+if [ "$(env -u GIT_DIR -u GIT_WORK_TREE 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 || {
+  env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" config core.bare false || {
     echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
 fi
 ```
@@ -291,6 +295,14 @@ too, and nothing else separates the two — this skill ships to users' `~/.claud
 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.
 
+**`GIT_DIR` and `GIT_WORK_TREE` beat `-C`, so unset them.** When either is exported —
+some tooling wrappers do — git ignores `-C "$ROOT"` and operates on whatever they
+point at, so the probe would diagnose a *different* repo and the repair would write
+that repo's `.git/config`. Both failures are silent, and both are worse than the bug
+being guarded against. This skill installs into arbitrary users' `~/.claude/skills/`,
+so the caller's environment is not ours to assume; `env -u` scopes the unset to the
+one command rather than to the tick.
+
 **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.
@@ -348,9 +360,54 @@ and lacks either `ai-ok-*`, disarm it before labelling:
 gh pr merge <N> --disable-auto
 ```
 
-If there are no open PRs carrying any `ai-*` label **and** no eligible `ai-ready`
-issues (Pass 4's query), skip straight to Pass 5 with `SUMMARY=idle`. Skip the
-passes, never the report.
+**Adopt agent-opened PRs the same way.** A PR an agent opens outside Pass 4 — one
+with no `ai-ready` issue behind it — carries no `ai-*` label, so it matches no pass
+and is therefore assigned by nothing: it never reaches *Assigned to you*, which is
+the view where merges actually happen. Observed on #548, which passed all five
+required checks and read *Able to merge* while its assignees read *No one—assign
+yourself*. Label it `ai-review` and Pass 1 hands it over on the existing path once
+both arms pass — no second assignment rule is needed:
+
+```bash
+ME=$(gh api user --jq .login)   # the identity every loop agent opens PRs as
+gh pr list --state open --json number,author,labels,body \
+  | jq -r --arg me "$ME" \
+      '.[] | select(.author.login == $me)
+           | select([.labels[].name] | any(startswith("ai-")) | not)
+           | select((.body // "") | startswith("🤖 "))
+           | .number'
+```
+
+**The `🤖` header is the discriminator, not the login.** Every agent authenticates as
+the owner's own `gh`, so author login alone cannot tell a PR an agent opened from one
+the owner wrote by hand — and a PR the owner wrote themselves must not be swept in,
+which would put two reviewers on work nobody asked to have reviewed. The header is
+wire format, the same as the `<!-- ai-issue-loop:* -->` markers: every PR body this
+pipeline writes opens with `🤖 *Automated …*` or `🤖 *Opened by …*`, so match it and
+do not redefine it. `(.body // "")` is load-bearing for the reason Pass 1's upsert
+spells out — a null body throws and empties the whole filter, here adopting nothing
+rather than everything.
+
+If there are no open PRs carrying any `ai-*` label, no eligible `ai-ready` issues
+(Pass 4's query), **and** no `ai-*` worktree left on disk, skip straight to Pass 5
+with `SUMMARY=idle`. Skip the passes, never the report.
+
+```bash
+find "$WT_ROOT" "$ROOT/.claude/worktrees" -maxdepth 1 -name 'ai-*' -type d 2>/dev/null
+```
+
+**The third condition is not implied by the other two.** Pass 2's cleanup is keyed
+off worktrees *on disk*, never off open PRs, so the moment the last open PR is merged
+by hand both of the other conditions go true while its worktree is still present and
+its issue still carries `ai-wip` — the label only Pass 2 ever clears. Every later tick
+meets the same two conditions, so the worktree and the label survive indefinitely
+while the loop reports `idle`. The two leaks also protect each other: the
+orphan-worktree rule that would otherwise reap it matches only a worktree *whose issue
+is not `ai-wip`*, and the stale label is exactly what stops it. Observed 2026-08-26 —
+#541 and #542 closed and their PRs merged, both worktrees still on disk, both issues
+still `ai-wip`. No concurrency slot leaks (the cap counts *open* `ai-wip` issues); what
+leaks is disk, an issue list that reads as though agents are still working, and Pass
+2's `node_modules` rebuild, which is gated on `REMOVED=1` and so never runs.
 
 ### Pass 1 — merge
 
@@ -372,7 +429,8 @@ gh api repos/$OWNER_REPO/environments \
 ```
 
 Non-zero → a non-Dependabot PR may auto-merge, but only carrying **all** of: both
-`ai-ok-code` and `ai-ok-sec`, no `ai-notes`, no `ai-changes`, and
+`ai-ok-code` and `ai-ok-sec` — or `merge-ready`, which subsumes them once an
+earlier tick handed the PR over — no `ai-notes`, no `ai-changes`, and
 `mergeStateStatus: CLEAN`. Zero, or the call errors, or `gh` lacks access to that
 endpoint → hand the PR over exactly as below.
 
@@ -452,47 +510,68 @@ leads with what to do.
 
 **Hand a ready PR over properly.** "Merge it yourself" is only actionable if the user
 can find it, and a PR sitting in a list of open PRs looks identical to one still being
-worked. So for every non-Dependabot PR carrying both `ai-ok-code` and `ai-ok-sec` and
-not `ai-changes`, assign it, label it, and clear the stale review flag — **but only
+worked. So for every non-Dependabot PR carrying both `ai-ok-code` and `ai-ok-sec` —
+or `merge-ready` already, from an earlier tick — and not `ai-changes`, assign it,
+label it, and clear the labels the handoff supersedes — **but only
 after the `mergeStateStatus` probe below reports `CLEAN`**. That ordering is what
 makes `merge-ready` assert more than the `ai-ok-*` pair ever did: reviews passed
 *and* GitHub will accept the merge.
 
 ```bash
-gh pr edit <N> --add-assignee @me --add-label merge-ready --remove-label ai-review \
+gh pr edit <N> --add-assignee @me --add-label merge-ready \
+  --remove-label ai-review --remove-label ai-ok-code --remove-label ai-ok-sec \
   ${AGENT_USER:+--remove-assignee "$AGENT_USER"}
 ```
 
+**`merge-ready` replaces the pass pair — it does not join it.** A handed-off PR
+wearing `ai-ok-code`, `ai-ok-sec` *and* `merge-ready` says one thing three times,
+and the reader has to know which of the three is the strongest before they can
+act on any of them. `merge-ready` asserts strictly more than the pair (both
+reviews passed **and** `CLEAN`), so the pair carries no information once it is
+applied — a ready PR's whole vocabulary is the two-row table below.
+
+Consequently **`merge-ready` satisfies every later test for the `ai-ok-*` pair** —
+the gated-repo auto-merge arm above, the Dependabot arm below, and this pass's own
+selector on the next tick. The pair stays the in-flight signal Pass 3 writes and
+reads; it is only at the handoff that it stops being the thing anyone looks at.
+
 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 — `merge-ready` means **waiting on you**, filterable at a glance where an
-absence never was. Both
-halves matter: Pass 3 only ever *adds* the `ai-ok-*` labels, so without the removal a
-finished PR keeps wearing `ai-review` forever and looks mid-review. Idempotent, so
-re-running a tick is harmless.
-
-**`merge-ready` is derived state — reconcile it every tick.** The `ai-ok-*` pair
-plus `CLEAN` stays the source the loop computes from; the label only mirrors it.
-A PR carrying `merge-ready` while no longer `CLEAN`, or missing either pass
-label, gets it stripped (`gh pr edit <N> --remove-label merge-ready`). That is
+absence never was. Every removal
+matters: Pass 3 only ever *adds* its labels, so without them a finished PR keeps
+wearing `ai-review` forever and looks mid-review while three green-ish labels
+argue about who passed what. Idempotent, so re-running a tick is harmless.
+
+**`merge-ready` is derived state — reconcile it every tick.** `CLEAN` stays the
+source the loop computes from; the label only mirrors it. A PR carrying
+`merge-ready` while no longer `CLEAN`, or carrying `ai-changes`, gets it stripped
+(`gh pr edit <N> --remove-label merge-ready`) — and the two send-back blocks
+below strip it as part of the same edit. That is
 what keeps a stateless 15-minute loop from letting the label lie after `main`
 moves. Take no other action — do not merge, and **post no
-comment on a clean handoff**: nothing is wrong, so those three labels are the
+comment on a clean handoff**: nothing is wrong, so that one label is the
 whole message. A comment is how the loop records what a label cannot; a clean PR
 has nothing to record. An `ai-notes` handoff is the exception per the budget
 table — ≤10 lines through the marker upsert, linking the reviewer's
 `### Before merging` rather than restating it.
 
+**Reconcile on `CLEAN` only — never on a missing `ai-ok-*`.** The handoff strips
+that pair itself, so a rule that stripped `merge-ready` whenever a pass label was
+absent would undo the tick before it on every handed-off PR, leaving it with no
+labels at all, matching no selector in any pass, and assigned to a human with
+nothing saying why it is theirs.
+
 **Never strip `ai-notes` here.** It is the whole point of the handoff: it has to
 survive to the moment of merging, which is the moment it is for. A ready PR reads
 one of two ways, and the difference must be legible without opening anything:
 
 | Labels | Means |
 |---|---|
-| `merge-ready` | Clean — merge freely. |
-| `merge-ready, ai-notes` | Passed, but open the comments first. |
+| `merge-ready` | Merge freely. |
+| `merge-ready`, `ai-notes` | Passed, but open the comments first. |
 
 **Check it can actually merge before calling it ready.** The `ai-ok-*` labels
 report the *agent review* verdict and nothing more — they say nothing about
@@ -539,8 +618,8 @@ 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.
 
 So: every open PR **authored by `dependabot[bot]`**, labelled both `ai-ok-code`
-and `ai-ok-sec`, **not** `ai-changes`, **not** `ai-notes`, that has no
-`autoMergeRequest` yet:
+and `ai-ok-sec` (or `merge-ready`), **not** `ai-changes`, **not** `ai-notes`, that
+has no `autoMergeRequest` yet:
 
 ```bash
 gh pr merge <N> --auto --squash --delete-branch
@@ -556,10 +635,78 @@ no human picks it up. Merging
 unattended when a reviewer flagged something for a human writes the note into the
 void, which is the one way this label can be worse than useless.
 
-**Also flag CI red here** — it is the one stall the loop cannot resolve itself.
-Any PR that already has `autoMergeRequest != null` and a `FAILURE` in its
-`statusCheckRollup` will sit queued forever. Count these as `ci-red` for Pass 5;
-take no other action (a human decides whether to fix or close).
+**CI red on an issue PR is a send-back, not a wait.** Reviewers are diff-scoped
+and never see CI, so both arms happily pass a PR whose `build` failed two minutes
+after it opened — and nothing else in the pipeline was ever going to dispatch a
+fix. Observed on #543 (2026-08-26): the human found it via the red ✗ on the PR
+page, which is precisely the noticing this loop exists to do. `ai-changes` **is**
+the send-back label; Pass 3 dispatches the fix-round implementer off it, under
+the same 2-round budget.
+
+So for every open **non-Dependabot** PR carrying any `ai-*` label, with a
+completed `FAILURE` on a **required** check:
+
+```bash
+gh pr checks <N> --required --json name,state,link 2>/dev/null \
+  | jq -r '.[] | select(.state == "FAILURE") | "\(.name)\t\(.link)"'
+```
+
+1. `gh pr edit <N> --add-label ai-changes --remove-label ai-review --remove-label ai-ok-code --remove-label ai-ok-sec --remove-label ai-notes --remove-label merge-ready`
+2. **Comment through the marker upsert** — ≤10 lines, naming the failing check
+   and pasting the relevant excerpt from `gh run view <run-id> --log-failed`
+   (the run id is in that check's `link`). This step is not optional: the
+   fix-round prompt reads the PR's comments *as its instructions*, so without it
+   the implementer arrives at a PR marked `ai-changes` with nothing telling it
+   what changed or why.
+
+   **Write that excerpt to a file and pass `--body-file`; never interpolate the
+   log into the command.** A failing job prints whatever the branch told it to,
+   and on a public repo the branch is a stranger's — so the excerpt is untrusted
+   bytes that a contributor chooses. Inline `--body "$(gh run view …)"` puts
+   megabytes of it, control characters and all, through the shell and past
+   GitHub's comment size cap. The same rule already governs reviewer verdicts
+   further down; this is the one other place a body is assembled from output
+   nobody in this pipeline wrote. Trim to the failing lines before writing.
+3. Count it as `ci-red` for Pass 5, which carries the `⚠`.
+
+**Say in the comment that the fix may not be code.** #543's failure was the
+dogfood check finding a *bootstrap* gap — a label present in the canonical table
+and not yet on the repo — where the fix was `gh label create` / `fix labels`, or
+an `ACCEPTED` entry in `scripts/dogfood.mjs`, and never a branch edit. The
+implementer has repo-write, so leave that path open; a comment that assumes the
+branch is at fault steers it into editing code that is not wrong.
+
+Two carve-outs, both so the loop does not fight itself:
+
+- **An `ai-reviewing-code` / `ai-reviewing-sec` claim is active** — leave the PR
+  alone this tick. A reviewer is mid-run, and the fix round relabels `ai-review`
+  and re-spawns both arms anyway, so sending back now only throws away a review
+  in flight.
+- **`ai-changes` is already on the PR** — leave it. Re-applying is not free:
+  Pass 3 counts `ai-changes` applications off the timeline and stops at three, so
+  a stateless 15-minute loop re-adding it while CI stays red would exhaust the
+  round budget within the hour and mark the issue `ai-blocked` before any agent
+  had done anything.
+
+**`--required`, not the whole rollup.** `statusCheckRollup` also carries optional
+and third-party contexts, and an advisory check going red is not a broken PR —
+sending one back spends a fix round to change nothing. The required set is the
+actual merge gate, and `gh` already resolves which checks are in it. Dropping
+`ai-review` in step 1 is the mirror of what a `CHANGES` verdict does: leaving it
+on would have Pass 3 spawn reviewers *and* a fix round against one PR, reviewing
+a diff that is being rewritten underneath them. The implementer re-adds it when
+it pushes.
+
+No new label. `ai-changes` plus that comment already say "sent back, and why";
+if telling a review-rejected PR from a CI-rejected one in the list view ever
+matters, add a `ci-failing` rider on top of `ai-changes` then, not speculatively
+now.
+
+**A Dependabot PR is the exception — flag it, never send it back.** There is no
+fix round for one (Pass 3 treats `ai-changes` on a bot PR as terminal), so a red
+one that already armed auto-merge will sit queued forever and only a human can
+choose between a fix and a close. Count these as `ci-red` too; take no other
+action:
 
 ```bash
 gh pr list --state open --json number,autoMergeRequest,statusCheckRollup \
@@ -719,13 +866,16 @@ where `ai-blocked` would not be — nothing is lost, only the queue is honest.
 **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
+if [ "$(env -u GIT_DIR -u GIT_WORK_TREE 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 || {
+  env -u GIT_DIR -u GIT_WORK_TREE git -C "$ROOT" config core.bare false || {
     echo "⚠ repair FAILED — main checkout still bare"; exit 1; }
 fi
 ```
 
+The `env -u` prefix carries the same weight here as in Pass 0, and for the same
+reason — keep it on both lines.
+
 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
@@ -1288,49 +1438,73 @@ mkdir -p "$WT_ROOT"
 git -C "$ROOT" worktree add "$WT_ROOT/$SLUG" -b "$SLUG" origin/main
 ```
 
-**Then give it dependencies — and the choice matters.** Symlinking is the cheap
-path, but it is only correct for an issue confined to an app:
+**Then give it dependencies — from the repo's own symlink list.** `fix ai` writes
+`worktree.symlinkDirectories` into `.claude/settings.json`: the root
+`node_modules`, plus one entry per workspace package that has one, globbed from
+the repo's *own* `pnpm-workspace.yaml` / `package.json` `workspaces` (#406). That
+list is the single source of truth for what a worktree needs linked. Read it and
+do the linking here:
 
 ```bash
-# Only for app/docs-only issues — nothing under a workspace package.
-# Replaces worktree.symlinkDirectories. Link the workspace packages too, not just
-# the root — with only the root linked, `pnpm verify` ENOENTs at the treeshake step
-# because apps/*/node_modules is missing, and the agent cannot self-verify.
-ln -s "$ROOT/node_modules" "$WT_ROOT/$SLUG/node_modules"
-for app in "$ROOT"/apps/*/; do
-  [ -d "$app/node_modules" ] || continue
-  ln -s "$app/node_modules" "$WT_ROOT/$SLUG/apps/$(basename "$app")/node_modules"
+DIRS=$(jq -r '.worktree.symlinkDirectories[]? // empty' "$ROOT/.claude/settings.json" 2>/dev/null)
+for d in $DIRS; do
+  [ -d "$ROOT/$d" ] || continue          # an entry pointing at nothing links nothing
+  mkdir -p "$(dirname "$WT_ROOT/$SLUG/$d")"
+  ln -s "$ROOT/$d" "$WT_ROOT/$SLUG/$d"
 done
 ```
 
-**For anything touching a workspace package, do not symlink — install for real:**
+**Read the setting, do not rely on it.** `worktree.symlinkDirectories` is a
+**Claude Code** setting, honoured by `EnterWorktree` — which this pipeline
+forbids outright (see below) and replaces with a raw `git worktree add`. So the
+setting is *inert for exactly the worktrees this loop creates*: `doctor` can
+report `Claude worktree settings: ok` while every agent worktree gets its
+dependencies by some other path, which is how #511/PR #526 ended up hand-installed.
+Taking the list as data and doing the `ln -s` here is what makes that check mean
+something for loop worktrees too, without either subsystem owning the other.
+
+**No list, or no `.claude/settings.json` → install for real instead:**
 
 ```bash
-(cd "$WT_ROOT/$SLUG" && pnpm install)
+[ -z "$DIRS" ] && (cd "$WT_ROOT/$SLUG" && pnpm install)
 ```
 
-Those symlinks share the **root** and `apps/*`. pnpm workspaces keep the
-resolution that matters in each `packages/<name>/node_modules`, which is not
-symlinked and does not exist in a fresh worktree. Measured on `api-common`
-2026-08-20: the main checkout had per-package `node_modules` in **37 of 37**
-packages, the worktree had **1**. So `pnpm --filter <pkg> typecheck` there fails
-with `Cannot find module` rather than the real error — the agent cannot reproduce
-the bug, and the environment looks like the issue's fault. Issue #201 was handed
-back `ai-blocked` this way, well-diagnosed and untouched.
+That fallback is safe precisely because nothing was symlinked — the hazard below
+is `pnpm install` against a *symlinked* tree, not a real install in an isolated
+one. It costs a duplicate `node_modules` and about ten seconds, since pnpm
+hardlinks from the store. Run `npx @rtorcato/repo-tooling fix ai` in the repo to
+get the faster path back.
+
+Why the list has to come from that file rather than a hand-rolled glob: pnpm
+workspaces keep the resolution that matters in each
+`packages/<name>/node_modules`, and an earlier version of this pass linked the
+root and `apps/*` only — so it reproduced that gap on every repo that nests its
+packages anywhere else. Measured on `api-common` 2026-08-20: the main checkout
+had per-package `node_modules` in **37 of 37** packages, the worktree had **1**.
+So `pnpm --filter <pkg> typecheck` there fails with `Cannot find module` rather
+than the real error — the agent cannot reproduce the bug, and the environment
+looks like the issue's fault. Issue #201 was handed back `ai-blocked` this way,
+well-diagnosed and untouched. `workspaceSymlinkDirs` already globs the consuming
+repo's own layout, so deriving the list is both shorter here and correct on repos
+this file has never seen.
 
 **Never force `pnpm install` against a symlinked tree.** It wants to purge and
 rebuild the modules dir (`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`), which
 mutates the **main checkout's** `node_modules` — shared by every other worktree
 and yanked out from under any agent mid-typecheck. `CI=true` and
 `--config.confirmModulesPurge=false` both silence that prompt; neither makes it
-safe. A real install in an unsymlinked worktree costs a duplicate `node_modules`
-and is the price of isolation. Pass 2's rebuild is the one sanctioned exception,
-and only because it is gated on no worktree surviving.
-
-**Once per repo, exclude the symlink from git.** Repos ignore `node_modules/`
-*with a trailing slash*, which does not match a symlink — so the link shows as
-untracked in every worktree and a `git add -A` commits it. `.git/info/exclude`
-is shared by all worktrees and never committed:
+safe. Now that the default path symlinks, this rule is **load-bearing rather than
+advisory** — the implementer prompt below states it, and `browser-common` #145 →
+PR #147 is what an implementer doing it anyway costs: the main checkout's `.bin`
+emptied, surfacing arbitrarily later in a human's `git push`. Pass 2's rebuild is
+the one sanctioned exception, and only because it is gated on no worktree
+surviving.
+
+**Once per repo, exclude the symlinks from git.** Repos ignore `node_modules/`
+*with a trailing slash*, which does not match a symlink — so every link shows as
+untracked in every worktree and a `git add -A` commits it. The pattern below has
+no slash, so it matches at any depth and covers the nested workspace links too.
+`.git/info/exclude` is shared by all worktrees and never committed:
 
 ```bash
 grep -qxF 'node_modules' "$ROOT/.git/info/exclude" || echo 'node_modules' >> "$ROOT/.git/info/exclude"
@@ -1344,9 +1518,9 @@ directory — the two rules are incompatible, so the call can only ever be refus
 five-plus times in one tick, each producing *"this session is isolated in the worktree
 …"* refusals on unrelated orchestrator commands. Implementers work via
 `git -C <absolute worktree path>` instead, which is what the prompt below says.
-Creating the worktree here also fixes the `worktree-` branch-prefix drift, and lets the
-`node_modules` symlink be explicit rather than depending on
-`worktree.symlinkDirectories` being configured.
+Creating the worktree here also fixes the `worktree-` branch-prefix drift, and it is
+why the symlinks above are created explicitly *from* `worktree.symlinkDirectories`
+rather than by `EnterWorktree` honouring it.
 
 **Spawn implementers one at a time — never two in the same message.** The worktree pin
 is a property of the session, not of an agent, so concurrent spawns cross-pin: the

package/skills/ai-workflow/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: ai-workflow
 description: |
-  Implement the `ai-ready` GitHub issue queue in parallel — one agent per issue,
-  each in its own git worktree, ending at open PRs reviewed by two agents. Use
-  when the user says "burst the queue", "work all the ai-ready issues in
-  parallel", or invokes `/ai-workflow`. Hands off to the ai-issue-loop skill for
-  fix rounds and merging. GitHub only (`gh`) — not GitLab.
+  **The entry point for the `ai-ready` issue pipeline — start here.** Implements
+  the queue in parallel, one agent per issue, each in its own git worktree,
+  ending at open PRs reviewed by two agents; then registers the ai-issue-loop
+  engine on a 15-minute loop to carry those PRs through fix rounds and cleanup.
+  Use when the user says "burst the queue", "run the AI pipeline", "work the
+  ai-ready issues", or invokes `/ai-workflow`. Never merges. GitHub only
+  (`gh`) — not GitLab.
 ---
 
 # ai-workflow
@@ -127,10 +129,11 @@ done
 ```
 
 **Then give each worktree dependencies** — the loop skill's Pass 4 rules apply
-verbatim: symlink `node_modules` (root *and* `apps/*`) only for an issue confined
-to an app; run a real `pnpm install` in the worktree for anything touching a
-workspace package; never force an install against a symlinked tree; and add
-`node_modules` to `$ROOT/.git/info/exclude` once per repo.
+verbatim: symlink every entry of `worktree.symlinkDirectories` from
+`$ROOT/.claude/settings.json` (the root `node_modules` plus each workspace
+package's, written by `fix ai`); run a real `pnpm install` in the worktree only
+when that list is missing or empty; never force an install against a symlinked
+tree; and add `node_modules` to `$ROOT/.git/info/exclude` once per repo.
 
 Stop here on `--label-only`. Report the picks and — briefly — what you skipped
 and why.
@@ -278,8 +281,8 @@ and still wearing a stale `ai-review`. Close that window here: once per PR
 whose two review arms both completed, apply the `ai-issue-loop` skill's Pass 1
 **by reference — execute what its text currently says, never a copy of it
 here**. A second copy of the handoff logic is drift with two files to keep
-honest; deferring means changes to Pass 1 (e.g. a future `merge-ready` label)
-take effect here without touching this file.
+honest; deferring means changes to Pass 1 (its `merge-ready` handoff, its CI-red
+send-back) take effect here without touching this file.
 
 - **Both arms passed** → run ai-issue-loop's Pass 1 handoff/send-back logic
   on this PR, per its current text — with one carve-out: `mergeStateStatus`