@rtorcato/repo-tooling 3.13.2 → 3.15.0

package/AGENTS.md

@@ -95,6 +95,8 @@ npx @rtorcato/repo-tooling fix claude-skills --yes --json
 
 Fixers marked `explicitOnly` are exempt from `fix` all *and* from `fix --yes` — they only run when named as the target. Today that is `claude-skills`, the one fixer whose blast radius is outside the repo.
 
+A fixer may also **refuse** — the target file holds something the generator cannot reproduce, so overwriting would destroy it. Today that is `dependabot` against a config with repo-local `ignore:` rules (#422). A targeted `fix dependabot` then exits 1 with `error: dependabot-ignore-rules`; a bulk `fix --yes` records it `skipped` and carries on with the rest. Neither `--yes` nor `--json` overrides it — resolve the named rules by hand and re-run.
+
 ## Source-of-truth files in the repo
 
 - `src/cli/commands/setup.ts` — `ProjectConfig` interface and the setup orchestrator

package/dist/base/checks.js

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import { BLOCK_START, hasStaleAgentBlock } from '../cli/generators/agent-rules.js';
 import { BADGE_START, hasPublicOnlyBadges } from '../cli/generators/badges.js';
 import { claudeSkillStatus, SHIPPED_SKILL } from '../cli/generators/claude-skills.js';
+import { DEPENDABOT_CONFIG_PATHS, dependabotIgnoreRules } from '../cli/generators/security.js';
 import { detectNestedLanguages } from '../cli/utils/detect-language.js';
 /**
  * Root-only detection is the decision (#317), not an oversight — but it used to
@@ -235,7 +236,7 @@ export async function checkGitHubActions(dir, preset = null) {
     }
 }
 export async function checkDependabot(dir) {
-    for (const candidate of ['.github/dependabot.yml', '.github/dependabot.yaml']) {
+    for (const candidate of DEPENDABOT_CONFIG_PATHS) {
         const candidatePath = path.join(dir, candidate);
         if (await fs.pathExists(candidatePath)) {
             // The canonical standard (apps/docs/docs/guides/dependabot-strategy.md) is
@@ -250,21 +251,39 @@ export async function checkDependabot(dir) {
                 }
             }
             const automergePath = path.join(dir, '.github', 'workflows', 'dependabot-automerge.yml');
-            if (!(await fs.pathExists(automergePath))) {
+            if (await fs.pathExists(automergePath)) {
+                // Pre-#423 workflows gated on the semver type alone, so production
+                // bumps of a published package merged with nobody in the loop. The
+                // canonical gate also requires the dev-minor group.
+                const automerge = await fs.readFile(automergePath, 'utf8');
+                if (!automerge.includes("dependency-group == 'dev-minor'")) {
+                    deltas.push('auto-merge workflow merges production bumps (missing dev-minor group gate)');
+                }
+            }
+            else {
                 deltas.push('missing dependabot-automerge workflow');
             }
+            // Repo-local `ignore:` rules aren't drift — they're deliberate, and the
+            // canonical config has no way to express them. Report them anyway so the
+            // reason `fix dependabot` refuses is visible before anyone runs it (#422).
+            const ignored = dependabotIgnoreRules(content);
+            const ignoreNote = ignored.length === 0
+                ? ''
+                : ` — ${ignored.length} local \`ignore:\` rule(s) the canonical config cannot express (${ignored.join(', ')}); \`fix dependabot\` refuses rather than drop them`;
             if (deltas.length > 0) {
                 return {
                     check: 'Dependabot',
                     status: 'drift',
-                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})`,
-                    hint: 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
+                    detail: `${candidate} drifts from canonical (${deltas.join('; ')})${ignoreNote}`,
+                    hint: ignored.length > 0
+                        ? 'Run `npx @rtorcato/repo-tooling fix dependabot --diff` — it will refuse until the `ignore:` block is dealt with by hand'
+                        : 'Run `npx @rtorcato/repo-tooling fix dependabot` to apply the canonical grouping + auto-merge workflow',
                 };
             }
             return {
                 check: 'Dependabot',
                 status: 'ok',
-                detail: `${candidate} + auto-merge workflow`,
+                detail: `${candidate} + auto-merge workflow${ignoreNote}`,
             };
         }
     }

package/dist/base/fixers.js

@@ -21,11 +21,13 @@ import { generateBrand } from '../cli/generators/brand.js';
 import { generateCommunityHealth } from '../cli/generators/community-health.js';
 import { generateCommitlintConfig } from '../cli/generators/git.js';
 import { generateCodeowners, generateEditorConfig } from '../cli/generators/misc.js';
-import { generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { findDependabotIgnoreRules, generateCodeQLWorkflow, generateDependabotConfig, generateRenovateConfig, } from '../cli/generators/security.js';
+import { classifyCopiedAssets } from '../cli/utils/copied-assets.js';
 import { copyPreset } from '../cli/utils/copy-preset.js';
 import { detectLanguage } from '../cli/utils/detect-language.js';
 import { resolveLanguageModule } from '../languages/registry.js';
 import { applyGithubSettings } from './github-settings.js';
+import { applyLoopLabels } from './labels.js';
 import { closeCompletedMilestones } from './milestones.js';
 /**
  * A fixer giving up on something the user has to resolve — a wrong flag, not a
@@ -75,6 +77,24 @@ async function resolveInstallDir(explicit, assumeYes) {
     return trimmed ? path.resolve(trimmed) : null;
 }
 export const BASE_FIXERS = [
+    {
+        target: 'copied-assets',
+        description: 'Re-copy presets that are unchanged since they were copied but older than the version this package ships',
+        appliesTo: ['Copied assets'],
+        outputs: ['(the stale copied presets, re-copied in place)'],
+        canFixDrift: true,
+        async run({ targetDir }) {
+            // Only the `stale` ones: their content provably still matches what was
+            // copied, so overwriting loses nothing. `modified` assets are somebody's
+            // deliberate fork and stay a human decision (#428).
+            const stale = (await classifyCopiedAssets(targetDir)).filter((a) => a.state === 'stale');
+            const filesWritten = [];
+            for (const asset of stale) {
+                filesWritten.push((await copyPreset(asset.preset, targetDir)).target);
+            }
+            return { filesWritten };
+        },
+    },
     {
         target: 'editorconfig',
         description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
@@ -112,6 +132,16 @@ export const BASE_FIXERS = [
         outputs: ['.github/dependabot.yml', '.github/workflows/dependabot-automerge.yml'],
         canFixDrift: true,
         async run({ targetDir }) {
+            // The template owns the whole file but emits no `ignore:` block, so
+            // regenerating deletes any repo-local ignore rule — silently, and with
+            // nothing in `doctor` to report the loss afterwards, because from the
+            // fixer's point of view the file then matches the standard exactly (#422).
+            // Refuse rather than warn: an unattended `fix --yes` would walk past a
+            // warning, and the rules are unrecoverable once written over.
+            const ignored = await findDependabotIgnoreRules(targetDir);
+            if (ignored) {
+                throw new FixerAbort('dependabot-ignore-rules', `refusing to overwrite ${ignored.file} — it has ${ignored.rules.length} \`ignore:\` rule(s) the canonical config does not reproduce: ${ignored.rules.join(', ')}`, `re-add the \`ignore:\` block after regenerating, or delete it from ${ignored.file} to accept the loss — then re-run \`fix dependabot\``);
+            }
             const { dependabotEcosystem } = await moduleFor(targetDir);
             return { filesWritten: await generateDependabotConfig(targetDir, dependabotEcosystem) };
         },
@@ -176,6 +206,19 @@ export const BASE_FIXERS = [
             return { filesWritten: await closeCompletedMilestones(targetDir) };
         },
     },
+    {
+        target: 'labels',
+        description: 'Repair ai-issue-loop label colours and descriptions on GitHub via `gh label edit` (mutates the remote repo, not files). No-ops on a repo that does not use the loop',
+        appliesTo: ['AI loop labels'],
+        outputs: ['GitHub labels (remote, via gh label edit)'],
+        // safe-add for the same reason github-settings is: it exempts this fixer
+        // from the `--diff` shadow-run, which executes run() for a mere preview.
+        riskLevel: 'safe-add',
+        canFixDrift: true,
+        async run({ targetDir }) {
+            return { filesWritten: await applyLoopLabels(targetDir) };
+        },
+    },
     {
         target: 'codeowners',
         description: 'Scaffold .github/CODEOWNERS with commented examples',

package/dist/base/github-settings.js

@@ -51,11 +51,15 @@ export const GITHUB_STANDARD = {
     requiredContexts: ['lint', 'typecheck', 'build', 'test'],
 };
 const CODE_SCANNING_CHECK = 'Code-scanning gate';
+const RELEASE_GATE_CHECK = 'Release gate';
+const RELEASE_ENV_CHECK = 'Release environment';
 const CHECK_NAMES = [
     'Branch protection',
     'Merge settings',
     'Workflow permissions',
     CODE_SCANNING_CHECK,
+    RELEASE_GATE_CHECK,
+    RELEASE_ENV_CHECK,
 ];
 // Recommended CodeQL alert thresholds — GitHub's UI defaults. This is the
 // override surface: bump them here for a stricter/looser fleet-wide baseline.
@@ -143,6 +147,7 @@ export async function checkGitHubSettings(dir, exec) {
         checkMergeSettings(info),
         await checkWorkflowPermissions(gh, info.nwo),
         await checkCodeScanningRuleset(gh, info.nwo, info.branch, dir),
+        ...(await checkReleaseGate(gh, info.nwo, dir)),
     ];
 }
 function probeFailureReason(probe) {
@@ -425,6 +430,270 @@ async function checkCodeScanningRuleset(gh, nwo, branch, dir) {
             : 'Run `npx @rtorcato/repo-tooling fix github-settings` to add a code_scanning branch ruleset that blocks merge on High+ CodeQL alerts',
     };
 }
+// --- Release environment gate (#429) --------------------------------------
+/** The environment name the standard reserves for the publish gate. */
+const RELEASE_ENVIRONMENT = 'release';
+/**
+ * What a job has to run for a merge to the default branch to reach a registry.
+ * `semantic-release` counts on its own — the shipped preset publishes with it.
+ */
+const PUBLISH_COMMAND = /semantic-release|changesets\/action|(?:npm|pnpm|yarn)\s+publish/;
+const GATE_HINT = 'Create a `release` environment with required reviewers (Settings → Environments) and add `environment: release` to the publishing job — a merge to the default branch then leaves the run `waiting` instead of publishing';
+const ENV_HINT = 'Add `environment: release` to the publishing job, or delete the environment — whichever was meant. An environment nothing references still lists under Settings → Environments as though it gates something';
+const unquote = (s) => s.replace(/^['"]|['"]$/g, '');
+/**
+ * A workflow's `jobs:` blocks, keyed by job id.
+ *
+ * Hand-split rather than parsed: this package ships no YAML dependency, and the
+ * only question asked of the result is whether *one particular job* carries an
+ * `environment:` key. A whole-file grep would answer that wrong on any repo with
+ * a `github-pages` deploy job — which is the exact false negative this check
+ * exists to avoid. Jobs sit one indent level under `jobs:` and their keys one
+ * level below that, which holds for every workflow Actions accepts.
+ */
+export function workflowJobs(yaml) {
+    const jobs = new Map();
+    const lines = yaml.split('\n');
+    const start = lines.findIndex((l) => /^jobs:\s*$/.test(l));
+    if (start === -1)
+        return jobs;
+    const indentOf = (l) => l.length - l.trimStart().length;
+    // The block runs until the next top-level key. A column-0 comment is not one —
+    // it ends nothing, so skipping it keeps a stray comment between `jobs:` and its
+    // first job from truncating the block and hiding every job below it.
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i] ?? '';
+        if (l.trim() !== '' && !l.trimStart().startsWith('#') && indentOf(l) === 0) {
+            end = i;
+            break;
+        }
+    }
+    const body = lines.slice(start + 1, end);
+    const first = body.find((l) => l.trim() !== '' && !l.trimStart().startsWith('#'));
+    if (first === undefined)
+        return jobs;
+    const jobIndent = indentOf(first);
+    let id = null;
+    let buf = [];
+    for (const line of body) {
+        const header = line.trim() !== '' && indentOf(line) === jobIndent
+            ? /^([\w.-]+):/.exec(line.trim())?.[1]
+            : undefined;
+        if (header) {
+            if (id)
+                jobs.set(id, buf.join('\n'));
+            id = header;
+            buf = [];
+        }
+        else if (id) {
+            buf.push(line);
+        }
+    }
+    if (id)
+        jobs.set(id, buf.join('\n'));
+    return jobs;
+}
+/**
+ * The environment a job runs in, in either form Actions accepts: the scalar
+ * `environment: release`, or a block whose `name:` names it. Null when the job
+ * declares none.
+ */
+export function jobEnvironment(body) {
+    const inline = /^[ \t]*environment:[ \t]*(\S+)[ \t]*$/m.exec(body);
+    if (inline?.[1])
+        return unquote(inline[1]);
+    const at = body.search(/^[ \t]*environment:[ \t]*$/m);
+    if (at === -1)
+        return null;
+    // Step names are list items (`- name:`), so the first bare `name:` after the
+    // block opener is the environment's.
+    const name = /^[ \t]*name:[ \t]*(\S+)/m.exec(body.slice(at))?.[1];
+    return name ? unquote(name) : null;
+}
+/**
+ * A job body with whole-line comments dropped. Same reasoning as
+ * `hookHasUncommented` in base/checks.ts: a `#` line runs nothing, so matching
+ * it is a false positive. Observed on this repo's own ci.yml, where a `varcheck`
+ * job carrying `# npm publish uses OIDC trusted publishing` was reported as the
+ * publishing job. Comments are stripped rather than pattern-tested because
+ * `jobEnvironment` needs the same treatment — a commented-out `environment:`
+ * would otherwise read as a live gate, the exact inversion of this check.
+ */
+function withoutComments(body) {
+    return body
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('#'))
+        .join('\n');
+}
+/** `private: true` — nothing reaches a registry, so no gate is owed. */
+async function isPrivatePackage(dir) {
+    try {
+        const pkg = await fs.readJson(path.join(dir, 'package.json'));
+        return pkg?.private === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The first workflow job that runs a publish command, or null if none does.
+ *
+ * `'skip'` when the directory exists but can't be read — a permission error or a
+ * broken symlink must not read as "nothing publishes", which would report the
+ * gate as `ok` on a repo whose workflows were never inspected. Same shape as
+ * `readEnvironments`: absent is an answer, unreadable is not.
+ */
+async function findPublishJob(dir) {
+    const workflowsDir = path.join(dir, '.github', 'workflows');
+    if (!(await fs.pathExists(workflowsDir)))
+        return null;
+    try {
+        for (const f of (await fs.readdir(workflowsDir)).sort()) {
+            if (!/\.ya?ml$/.test(f))
+                continue;
+            const content = await fs.readFile(path.join(workflowsDir, f), 'utf-8');
+            if (!PUBLISH_COMMAND.test(content))
+                continue;
+            for (const [job, raw] of workflowJobs(content)) {
+                const body = withoutComments(raw);
+                if (PUBLISH_COMMAND.test(body)) {
+                    return { file: f, job, environment: jobEnvironment(body) };
+                }
+            }
+        }
+    }
+    catch {
+        return 'skip';
+    }
+    return null;
+}
+async function readEnvironments(gh, nwo) {
+    const r = await gh(['api', `repos/${nwo}/environments`]);
+    // A repo with no environments can answer 404 — that's "none", not unreadable.
+    if (!r.ok)
+        return /404|not found/i.test(r.stderr) ? new Map() : 'skip';
+    try {
+        const parsed = JSON.parse(r.stdout);
+        const envs = new Map();
+        for (const e of parsed.environments ?? []) {
+            if (typeof e.name !== 'string')
+                continue;
+            envs.set(e.name, (e.protection_rules ?? []).some((p) => p.type === 'required_reviewers'));
+        }
+        return envs;
+    }
+    catch {
+        return 'skip';
+    }
+}
+/**
+ * The gap between merging the default branch and publishing to npm (#429). On
+ * the shipped semantic-release preset those are one event: nothing stands
+ * between a squash-merge and a new version on the registry.
+ *
+ * Two checks, because they fail differently and want different answers:
+ *
+ * - **Release gate** — the publishing job runs behind no environment at all, or
+ *   behind one that isn't really a gate (absent, or with no required reviewers).
+ * - **Release environment** — the repo *has* a `release` environment and no job
+ *   references it. That's the failure mode worth catching: an unreferenced
+ *   environment gates nothing while reading as a gate in the GitHub UI.
+ *
+ * The two never both fire on one repo. "No `environment:` and no `release`
+ * environment" is the gate check's; "no `environment:` but a `release`
+ * environment exists" is the environment check's, and the gate check defers.
+ *
+ * A repo that publishes nothing is `ok` — not applicable, not drift. There is
+ * no fixer: creating the environment needs a `required_reviewers` list only a
+ * human can supply, so both hints describe the manual step.
+ */
+async function checkReleaseGate(gh, nwo, dir) {
+    const publish = (await isPrivatePackage(dir)) ? null : await findPublishJob(dir);
+    if (publish === 'skip') {
+        const reason = 'could not read .github/workflows';
+        return [skip(RELEASE_GATE_CHECK, reason), skip(RELEASE_ENV_CHECK, reason)];
+    }
+    if (!publish) {
+        const detail = 'not applicable — no workflow job publishes to a registry';
+        return [
+            { check: RELEASE_GATE_CHECK, status: 'ok', detail },
+            { check: RELEASE_ENV_CHECK, status: 'ok', detail },
+        ];
+    }
+    const envs = await readEnvironments(gh, nwo);
+    if (envs === 'skip') {
+        const reason = 'could not read environments';
+        return [skip(RELEASE_GATE_CHECK, reason), skip(RELEASE_ENV_CHECK, reason)];
+    }
+    const named = publish.environment;
+    const where = `${publish.file} \`${publish.job}\``;
+    const hasRelease = envs.has(RELEASE_ENVIRONMENT);
+    let gate;
+    if (named === null) {
+        gate = hasRelease
+            ? {
+                check: RELEASE_GATE_CHECK,
+                status: 'ok',
+                detail: `${where} declares no environment — reported by the ${RELEASE_ENV_CHECK} check`,
+            }
+            : {
+                check: RELEASE_GATE_CHECK,
+                status: 'drift',
+                detail: `${where} publishes with no \`environment:\` and the repo has no \`${RELEASE_ENVIRONMENT}\` environment — anything that lands on the default branch publishes`,
+                hint: GATE_HINT,
+            };
+    }
+    else if (!envs.has(named)) {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'drift',
+            detail: `${where} names the \`${named}\` environment, which the repo does not have — Actions creates it unprotected on first run, so the publish is never held`,
+            hint: GATE_HINT,
+        };
+    }
+    else if (!envs.get(named)) {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'drift',
+            detail: `the \`${named}\` environment has no required_reviewers — ${where} passes straight through it`,
+            hint: GATE_HINT,
+        };
+    }
+    else {
+        gate = {
+            check: RELEASE_GATE_CHECK,
+            status: 'ok',
+            detail: `${where} runs behind the \`${named}\` environment (required reviewers)`,
+        };
+    }
+    let environment;
+    if (!hasRelease) {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'ok',
+            detail: `no \`${RELEASE_ENVIRONMENT}\` environment — nothing to reference`,
+        };
+    }
+    else if (named === RELEASE_ENVIRONMENT) {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'ok',
+            detail: `${where} references the \`${RELEASE_ENVIRONMENT}\` environment`,
+        };
+    }
+    else {
+        environment = {
+            check: RELEASE_ENV_CHECK,
+            status: 'drift',
+            detail: named
+                ? `the repo has a \`${RELEASE_ENVIRONMENT}\` environment but ${where} runs in \`${named}\` — \`${RELEASE_ENVIRONMENT}\` gates nothing while still reading as a gate in the GitHub UI`
+                : `the repo has a \`${RELEASE_ENVIRONMENT}\` environment but ${where} references no environment — it gates nothing while still reading as a gate in the GitHub UI`,
+            hint: ENV_HINT,
+        };
+    }
+    return [gate, environment];
+}
 /** The branch-protection body PUT to the API — mirrors the doctor standard. */
 const PROTECTION_BODY = JSON.stringify({
     required_status_checks: { strict: false, contexts: GITHUB_STANDARD.requiredContexts },

package/dist/base/labels.js

@@ -0,0 +1,205 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import { realGhExec } from './github-settings.js';
+/**
+ * `ai-issue-loop` label hygiene (#446). Same class of GitHub-side drift as
+ * github-settings.ts and milestones.ts, on the same `gh` seam.
+ *
+ * The bug this exists for: the skill's bootstrap uses `gh label create`, which
+ * *errors as a no-op* when the label already exists. It can add a missing label
+ * but can never repair an existing one, so a hand-created `ai-ready` keeps
+ * whatever colour the web picker gave it forever. Measured across eight repos,
+ * six had `ai-ready` at `B60205` — byte-identical to `ai-blocked`, so "an agent
+ * should pick this up" and "an agent gave up" rendered the same. Repair here
+ * goes through `gh label edit`, which is the whole point of the fixer.
+ *
+ * This table is the single source of truth for the label set. The bootstrap
+ * block in skills/ai-issue-loop/SKILL.md is asserted against it in
+ * tests/base/labels.test.ts, so the two cannot drift apart.
+ */
+const CHECK = 'AI loop labels';
+export const LOOP_LABELS = [
+    {
+        name: 'holding',
+        color: '5319e7',
+        description: 'Gate/holding issue — human judgement, never auto-picked',
+    },
+    { name: 'ai-ready', color: '0e8a16', description: 'Eligible for an AI agent to implement' },
+    { name: 'ai-wip', color: 'fbca04', description: 'Claimed by an agent; worktree exists' },
+    { name: 'ai-blocked', color: 'b60205', description: 'Agent gave up; needs a human' },
+    { name: 'ai-review', color: '1d76db', description: 'PR awaiting agent review' },
+    { name: 'ai-reviewing-code', color: 'c5def5', description: 'code-reviewer claimed and running' },
+    { name: 'ai-reviewing-sec', color: 'c5def5', description: 'security-expert claimed and running' },
+    { name: 'ai-ok-code', color: '0e8a16', description: 'code-reviewer passed' },
+    { name: 'ai-ok-sec', color: '0e8a16', description: 'security-expert passed' },
+    { name: 'ai-changes', color: 'd93f0b', description: 'Reviewer requested changes' },
+    {
+        name: 'ai-notes',
+        color: 'fbca04',
+        description: 'Passed, but a reviewer left something to read before merging',
+    },
+];
+/**
+ * How many of the set have to exist before this repo counts as running the
+ * loop. A repo with none has opted out, not drifted — creating eleven labels it
+ * will never use is the nag this threshold exists to prevent. One alone is the
+ * observed half-state (`cf-common` has only `ai-ready`, applied by hand), which
+ * is likewise not evidence the pipeline runs there.
+ */
+const IN_USE_THRESHOLD = 2;
+const skip = (reason) => ({
+    check: CHECK,
+    status: 'ok',
+    detail: `skipped — ${reason}`,
+});
+/**
+ * Case-insensitive, `#`-insensitive. The drift that started this was uppercase
+ * `B60205` against lowercase `b60205` — GitHub's colour picker writes uppercase,
+ * `gh` writes lowercase, and the two render identically. Comparing raw would
+ * report every hand-created label as drift forever and have the fixer PATCH a
+ * colour that was already correct.
+ */
+const normalizeColor = (c) => c.trim().replace(/^#/, '').toLowerCase();
+async function readLabels(gh) {
+    const r = await gh(['label', 'list', '--json', 'name,color,description', '--limit', '200']);
+    if (!r.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(r.stdout);
+        if (!Array.isArray(parsed))
+            return null;
+        const byName = new Map();
+        for (const l of parsed) {
+            if (typeof l?.name !== 'string')
+                continue;
+            byName.set(l.name, {
+                name: l.name,
+                color: typeof l.color === 'string' ? l.color : '',
+                description: typeof l.description === 'string' ? l.description : '',
+            });
+        }
+        return byName;
+    }
+    catch {
+        return null;
+    }
+}
+export function classifyLabels(existing) {
+    const deltas = { present: [], missing: [], wrongColor: [], wrongDescription: [] };
+    for (const spec of LOOP_LABELS) {
+        const actual = existing.get(spec.name);
+        if (!actual) {
+            deltas.missing.push(spec);
+            continue;
+        }
+        deltas.present.push(spec);
+        if (normalizeColor(actual.color) !== normalizeColor(spec.color))
+            deltas.wrongColor.push({ spec, actual: normalizeColor(actual.color) });
+        if (actual.description.trim() !== spec.description)
+            deltas.wrongDescription.push(spec);
+    }
+    return deltas;
+}
+const names = (specs) => specs.map((s) => `\`${s.name}\``).join(', ');
+export async function checkLoopLabels(dir, exec) {
+    // Cheap gate first: no .git → never spawn (keeps tmp-dir doctor runs offline).
+    if (!(await fs.pathExists(path.join(dir, '.git'))))
+        return skip('not a git repository');
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const existing = await readLabels(gh);
+    if (!existing)
+        return skip('could not read labels');
+    const { present, missing, wrongColor, wrongDescription } = classifyLabels(existing);
+    if (present.length < IN_USE_THRESHOLD)
+        return {
+            check: CHECK,
+            status: 'ok',
+            detail: 'not applicable — repo does not use the ai-issue-loop labels',
+        };
+    const deltas = [];
+    for (const { spec, actual } of wrongColor)
+        deltas.push(`\`${spec.name}\` is #${actual}, should be #${spec.color}`);
+    if (wrongDescription.length)
+        deltas.push(`wrong description: ${names(wrongDescription)}`);
+    if (missing.length)
+        deltas.push(`missing: ${names(missing)}`);
+    if (deltas.length)
+        return {
+            check: CHECK,
+            status: 'drift',
+            detail: deltas.join('; '),
+            hint: 'Run `npx @rtorcato/repo-tooling fix labels` to repair them with `gh label edit` — `gh label create` cannot change an existing label, which is how this drifted',
+        };
+    return {
+        check: CHECK,
+        status: 'ok',
+        detail: `${present.length} ai-issue-loop label(s) match spec`,
+    };
+}
+/**
+ * Repairs colour and description with `gh label edit`, and creates the labels
+ * the set is missing. Only on a repo already running the loop (the same
+ * `IN_USE_THRESHOLD` gate the check uses) — otherwise a plain `fix --yes` would
+ * push eleven labels into every repo it touches.
+ *
+ * Idempotent: an aligned repo is a no-op, and a label whose only difference is
+ * the hex case is not touched at all.
+ *
+ * Advisories go to `console.error`; stdout carries the `--json` payload (#357).
+ */
+export async function applyLoopLabels(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        console.error(chalk.gray('   skipped — not a git repository'));
+        return [];
+    }
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin, dir));
+    const existing = await readLabels(gh);
+    if (!existing) {
+        console.error(chalk.gray('   skipped — could not read labels'));
+        return [];
+    }
+    const { present, missing, wrongColor, wrongDescription } = classifyLabels(existing);
+    if (present.length < IN_USE_THRESHOLD) {
+        console.error(chalk.gray('   skipped — repo does not use the ai-issue-loop labels'));
+        return [];
+    }
+    // One edit per drifted label, whichever field drifted — the API takes both.
+    const toEdit = new Set([...wrongColor.map((w) => w.spec), ...wrongDescription]);
+    const applied = [];
+    for (const spec of toEdit) {
+        // `edit`, not `create`: create errors as a no-op on an existing label, so a
+        // fixer built on it would silently repair nothing (#446).
+        const r = await gh([
+            'label',
+            'edit',
+            spec.name,
+            '--color',
+            spec.color,
+            '--description',
+            spec.description,
+        ]);
+        if (r.ok)
+            applied.push(`repaired label "${spec.name}"`);
+        else
+            console.error(chalk.yellow(`   could not repair "${spec.name}": ${r.stderr.trim() || 'gh error'}`));
+    }
+    for (const spec of missing) {
+        const r = await gh([
+            'label',
+            'create',
+            spec.name,
+            '--color',
+            spec.color,
+            '--description',
+            spec.description,
+        ]);
+        if (r.ok)
+            applied.push(`created label "${spec.name}"`);
+        else
+            console.error(chalk.yellow(`   could not create "${spec.name}": ${r.stderr.trim() || 'gh error'}`));
+    }
+    if (applied.length === 0)
+        console.error(chalk.gray('   labels already match spec'));
+    return applied;
+}

package/dist/cli/commands/doctor.js

@@ -13,8 +13,10 @@ import { SWIFT_GIT_HOOKS, runSwiftChecks } from '../../languages/swift/checks.js
 import { readSwiftPackage, renderSwiftWorkflow } from '../../languages/swift/ci.js';
 import { detectLanguage } from '../utils/detect-language.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
+import { checkLoopLabels } from '../../base/labels.js';
 import { checkMilestones } from '../../base/milestones.js';
 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';
@@ -150,6 +152,9 @@ function demoteDeclined(results, lock) {
 async function runBaseChecks(dir, lock, opts) {
     const results = [];
     results.push(checkLockfile(lock));
+    // Any language can have copied presets (swiftlint, ruff, perlcriticrc), so
+    // this rides with the base suite rather than a module's (#428).
+    results.push(await checkCopiedAssets(dir));
     results.push(await checkNestedLanguages(dir, opts.language));
     results.push(await checkGitIdentity(dir));
     results.push(await checkEditorConfig(dir));
@@ -166,6 +171,8 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(...(await checkGitHubSettings(dir)));
     // Milestone hygiene (#397) — same seam, same self-skip.
     results.push(await checkMilestones(dir));
+    // ai-issue-loop label colours/descriptions (#446) — same seam, same self-skip.
+    results.push(await checkLoopLabels(dir));
     results.push(await checkGitLabCI(dir));
     results.push(await checkCodeowners(dir));
     results.push(await checkCommunityHealth(dir));