@rtorcato/repo-tooling 3.25.0 → 3.27.0

package/AGENTS.md

@@ -18,7 +18,7 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `setup --config <path>` | ✅ | `--dry-run` only | Scaffold with a full `ProjectConfig` JSON file. See `setup --config-schema`. |
 | `setup --config-schema` | ✅ | ✅ (JSON Schema) | Print the JSON Schema for `ProjectConfig`. Use to validate configs before scaffolding. |
 | `setup --dry-run` | ✅ | ✅ | Print resolved config + file list without writing. Pair with `--preset` or `--config`. |
-| `doctor --json` | ✅ | ✅ | Audit a project. Returns `{ directory, results: [{ check, status, detail, hint? }] }`. Status: `ok` / `drift` / `missing` / `optional-missing`. |
+| `doctor --json` | ✅ | ✅ | Audit a project. Returns `{ directory, results: [{ check, status, detail, hint? }] }`. Status: `ok` / `drift` / `missing` / `optional-missing` / `declared`. |
 | `fix --json --yes` | ✅ | ✅ | Walk every doctor finding, apply fixers. Returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`. |
 | `fix <target> --json --yes` | ✅ | ✅ | Apply one fixer. Targets from `list --json`. |
 | `fix --dry-run` | ✅ | ✅ | Print what each fixer would write without writing. Combine with `--json`. |

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

@@ -51,15 +51,38 @@ const GIT_TIMEOUT_MS = 5_000;
  * `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.
  */
-const AMBIENT_REPO_VARS = [
+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_COMMON_DIR',
-    'GIT_OBJECT_DIRECTORY',
-    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+    '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() {

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';
@@ -156,6 +156,40 @@ function demoteDeclined(results, lock) {
         };
     });
 }
+// Declared exceptions (#558): a failing check the lock names is reported as
+// `declared` with its reason — shown, never hidden, but no longer failing the
+// run. An exception naming a check this run doesn't know is itself drift:
+// otherwise a typo silently does nothing and a check rename silently
+// un-suppresses a finding, and both are invisible.
+function applyExceptions(results, lock) {
+    const exceptions = lock?.exceptions;
+    if (!exceptions)
+        return results;
+    const known = new Set(results.map((r) => r.check));
+    const overlaid = results.map((r) => {
+        const reason = exceptions[r.check];
+        if (!reason || r.status === 'ok')
+            return r;
+        // Hint deliberately dropped: the deviation is declared, so "how to fix it"
+        // is exactly the noise the exception exists to retire.
+        return {
+            check: r.check,
+            status: 'declared',
+            detail: `${r.detail} — declared exception: ${reason}`,
+        };
+    });
+    for (const name of Object.keys(exceptions)) {
+        if (known.has(name))
+            continue;
+        overlaid.push({
+            check: 'Declared exceptions',
+            status: 'drift',
+            detail: `.repo-tooling.json declares an exception for "${name}", which is not a check this run knows`,
+            hint: 'A typo, or a check that was renamed or removed — fix or delete the entry in `exceptions`',
+        });
+    }
+    return overlaid;
+}
 // The language-agnostic checks (src/base): repo hygiene, git hooks, CI,
 // security, and GitHub repo-settings that apply to any repo regardless of
 // language. Declared once and run for every project — a language module layers
@@ -193,6 +227,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;
@@ -228,7 +272,7 @@ export async function runDoctor(dir, skillsDir) {
                 skillsDir,
             })),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // Swift suite (#286): base checks plus the module's own. Swift repos have no
     // package.json, so nothing JS-shaped runs.
@@ -252,7 +296,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runSwiftChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // Python suite (#290): same shape as Swift — base checks plus the module's
     // own, and nothing JS-shaped, because a Python repo has no package.json.
@@ -276,7 +320,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runPythonChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // Perl suite (#289): same shape as Swift and Python — base checks plus the
     // module's own, and nothing JS-shaped, because a distribution has no
@@ -302,7 +346,7 @@ export async function runDoctor(dir, skillsDir) {
             })),
             ...(await runPerlChecks(targetDir)),
         ];
-        return demoteDeclined(results, lock);
+        return applyExceptions(demoteDeclined(results, lock), lock);
     }
     // JS suite: the module's own checks, then the shared base ones. Only the
     // JS-shaped checks are listed here — re-listing the base suite is what made
@@ -361,13 +405,14 @@ export async function runDoctor(dir, skillsDir) {
         codeqlLanguages: languageModule.codeqlLanguages,
         skillsDir,
     })));
-    return demoteDeclined(results, lock);
+    return applyExceptions(demoteDeclined(results, lock), lock);
 }
 const STATUS_ICONS = {
     ok: chalk.green('✅'),
     drift: chalk.yellow('⚠️ '),
     missing: chalk.red('❌'),
     'optional-missing': chalk.gray('➖'),
+    declared: chalk.blue('📝'),
 };
 function statusLabel(status) {
     switch (status) {
@@ -379,6 +424,8 @@ function statusLabel(status) {
             return chalk.red('missing');
         case 'optional-missing':
             return chalk.gray('not configured');
+        case 'declared':
+            return chalk.blue('declared');
     }
 }
 const MAX_NEXT_STEP_SUGGESTIONS = 8;
@@ -411,6 +458,7 @@ export function summarize(results) {
         drift: results.filter((r) => r.status === 'drift').length,
         missing: results.filter((r) => r.status === 'missing').length,
         optionalMissing: results.filter((r) => r.status === 'optional-missing').length,
+        declared: results.filter((r) => r.status === 'declared').length,
     };
 }
 export async function doctorCommand(options = {}) {
@@ -430,7 +478,7 @@ export async function doctorCommand(options = {}) {
         }
         const summary = summarize(results);
         console.log();
-        console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}\n`);
+        console.log(`  Summary: ${chalk.green(`${summary.ok} ok`)}, ${chalk.yellow(`${summary.drift} drift`)}, ${chalk.red(`${summary.missing} missing`)}, ${chalk.gray(`${summary.optionalMissing} not configured`)}, ${chalk.blue(`${summary.declared} declared`)}\n`);
         const suggestions = nextStepSuggestions(results, await detectLanguage(dir));
         if (suggestions.length > 0) {
             console.log(chalk.bold('  Next steps:'));

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/fix.js

@@ -436,7 +436,10 @@ export async function fixCommand(target, options = {}) {
         console.log();
         return;
     }
-    const fixable = results.filter((r) => r.status !== 'ok');
+    // `declared` is a deviation the lockfile records on purpose (#558) — a bulk
+    // fix must not "repair" it. A targeted `fix <target>` still can: naming the
+    // fixer is the same explicit override the declined-in-lock path gets.
+    const fixable = results.filter((r) => r.status !== 'ok' && r.status !== 'declared');
     if (fixable.length === 0) {
         if (json)
             return emitJson(null);

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,47 @@ 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.',
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            exceptions: {
+                type: 'object',
+                additionalProperties: { type: 'string', minLength: 1 },
+                description: 'Declared exceptions: doctor check name → the reason this repo deliberately deviates. The reason is mandatory and non-empty — doctor shows the check as `declared` with it (never hidden) and stops failing the run for it. An entry naming a check doctor does not run is itself reported as drift.',
+            },
             writtenBy: {
                 type: 'string',
                 description: 'Package name and version that last wrote this file.',
@@ -147,6 +196,9 @@ 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 } : {}),
+        ...(existing?.exceptions ? { exceptions: existing.exceptions } : {}),
         writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
         writtenAt: new Date().toISOString(),
     };

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.25.0",
+	"version": "3.27.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

@@ -80,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. |
 
@@ -150,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
@@ -428,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.
 
@@ -508,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
@@ -595,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
@@ -612,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 \
@@ -1347,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"
@@ -1403,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

@@ -129,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.
@@ -280,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`

package/skills/repo-tooling/SKILL.md

@@ -30,6 +30,8 @@ npx @rtorcato/repo-tooling doctor --json                 # confirm clean
   prompt to **No**; `--yes` is required to overwrite. Show `fix <target> --diff` first.
 - `missing` — required and absent → fix it.
 - `optional-missing` — opt-in tool not configured. Only fix if the user wants that tool.
+- `declared` — a real deviation the repo's `.repo-tooling.json` `exceptions` records on
+  purpose, with its reason. Leave it alone; it doesn't fail the run.
 
 `fix` returns `FixActionRecord[]` with `status: applied | dry-run | skipped | already-ok | unsupported`.