@rtorcato/repo-tooling 4.1.0 → 4.3.0

package/AGENTS.md

@@ -8,7 +8,7 @@ A one-package JavaScript / TypeScript tooling distribution. Ships every preset (
 
 **Swift** repos (detected via `Package.swift`) are covered end to end: `setup --preset swift-library` scaffolds a SwiftPM package, and `doctor`/`fix` run the language-agnostic checks plus SwiftLint / Periphery / `.gitignore` / `Package.swift`. **Python** repos (detected via `pyproject.toml` / `setup.py`) get `doctor`/`fix` — Ruff / mypy / pytest / `.gitignore` / CI / git hooks — but no `setup` preset yet. **Perl** distributions (detected via `cpanfile` / `Makefile.PL` / `dist.ini`) get the same deal: Perl::Critic / perltidy / `.gitignore` / CI / git hooks, no `setup` preset. See `src/languages/` — one directory per language module, `src/base/` for what's shared.
 
-The **ai-issue-loop** pipeline (the `loop` commands, its skills, and the label / agent-user / skills checks) lives in [`@rtorcato/repo-ai`](https://github.com/rtorcato/repo-ai) since #658. `repo-tooling loop` now only prints a pointer there. Its settings still sit in this package's `.repo-tooling.json` under `rules.aiLoop` and `rules.requiredSkills`, which repo-tooling carries forward without reading.
+repo-tooling stands alone. The **ai-issue-loop** pipeline (the `loop` commands, its skills, and the label / agent-user / skills checks) is an optional companion package, [`@rtorcato/repo-ai`](https://rtorcato.github.io/repo-ai/), since #658. Nothing here requires it or checks for it; `repo-tooling loop` only prints a pointer there. Its settings sit in this package's `.repo-tooling.json` under `rules.aiLoop` and `rules.requiredSkills`, which repo-tooling carries forward without reading. See `apps/docs/docs/guides/ai-issue-loop.md` for how the two fit together.
 
 ## CLI surface (agent-friendly)
 

package/README.md

@@ -137,6 +137,7 @@ full field reference. The keys `doctor` acts on:
 - `securityAutomation` — boolean (Dependabot + CodeQL)
 - `bundler` — `tsup` \| `esbuild` \| `vite` \| `none`
 - `aiSetup` — boolean (AGENTS.md, CLAUDE.md, Cursor/Copilot rules)
+- `brand` — boolean (`brand/` banner + social-card SVG sources and `render.sh`)
 
 **How opt-outs actually work.** When the lockfile records that you declined an
 *optional* tool (e.g. `securityAutomation: false`), `doctor` demotes that check
@@ -190,19 +191,22 @@ throwaway fixtures) — in any session:
 /plugin install repo-tooling@repo-tooling
 ```
 
-### The AI issue loop
+### Optional: agents on your issue queue (repo-ai)
 
-The label-driven `ai-ready` issue → PR pipeline (the `ai-workflow`,
-`ai-issue-loop`, `ai-issue` and `ai-loop-status` skills, and the `loop`
-commands they call) moved to its own package,
-[`@rtorcato/repo-ai`](https://github.com/rtorcato/repo-ai), so this one can be
-used without it:
+repo-tooling works entirely on its own. If you also want agents working your
+GitHub issues, the optional companion
+[`@rtorcato/repo-ai`](https://rtorcato.github.io/repo-ai/) runs a label-driven
+loop: an `ai-ready` issue becomes a worktree, a PR and two agent reviews, then
+waits for you to merge. It builds on the repo standard repo-tooling sets up
+(branch protection, the release gate, worktree config) and keeps its settings in
+the same `.repo-tooling.json`:
 
 ```bash
-npx @rtorcato/repo-ai fix claude-skills   # → ~/.claude/skills/{ai-issue-loop,ai-workflow,ai-issue,ai-loop-status}/SKILL.md
+npx @rtorcato/repo-ai setup
 ```
 
-Its settings stay in `.repo-tooling.json` (`rules.aiLoop`, `rules.requiredSkills`).
+See [Using with repo-ai](https://rtorcato.github.io/repo-tooling/guides/ai-issue-loop/)
+for how the two fit together. The loop shipped inside repo-tooling until 4.0.0.
 
 ### Use with other AI tools (Cursor / Copilot / Codex)
 

package/dist/base/checks.js

@@ -266,6 +266,11 @@ export async function checkDependabot(dir) {
                 if (!automerge.includes("package-ecosystem == 'github-actions'")) {
                     deltas.push('auto-merge workflow leaves CI action bumps to a human (#452)');
                 }
+                // #694: a declined PR used to get only a log notice — no assignee, no
+                // comment — and could sit green and ownerless indefinitely.
+                if (!automerge.includes("steps.merge.outcome == 'skipped'")) {
+                    deltas.push('auto-merge workflow leaves declined PRs with no owner (#694)');
+                }
             }
             else {
                 deltas.push('missing dependabot-automerge workflow');

package/dist/base/fixers.js

@@ -75,6 +75,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'editorconfig',
+        selfSafe: true,
         description: 'Scaffold .editorconfig (UTF-8, LF, tab indent)',
         appliesTo: ['EditorConfig'],
         outputs: ['.editorconfig'],
@@ -145,6 +146,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'codeql',
+        selfSafe: true,
         description: 'Scaffold .github/workflows/codeql.yml (security scanning)',
         appliesTo: ['CodeQL'],
         outputs: ['.github/workflows/codeql.yml'],
@@ -214,6 +216,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'codeowners',
+        selfSafe: true,
         description: 'Scaffold .github/CODEOWNERS with commented examples',
         appliesTo: ['CODEOWNERS'],
         outputs: ['.github/CODEOWNERS'],
@@ -226,6 +229,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'community-health',
+        selfSafe: true,
         description: 'Scaffold CONTRIBUTING.md, SECURITY.md, PR + issue templates',
         appliesTo: ['Community health'],
         outputs: [
@@ -244,6 +248,7 @@ export const BASE_FIXERS = [
     },
     {
         target: 'brand',
+        selfSafe: true,
         description: 'Scaffold brand/ — banner, mobile-banner and social-card SVG sources + render.sh, and repoint a README still on root-level banner paths',
         appliesTo: ['Brand assets'],
         outputs: [

package/dist/base/github-settings.js

@@ -217,7 +217,7 @@ async function checkBranchProtection(exec, nwo, branch) {
  * enabled only makes them available on the merge button, and one mis-click puts
  * every intermediate branch commit on the default branch: semantic-release then
  * reads subjects nobody reviewed (a stray `fix:` inside a docs PR cuts a
- * release), and `ai-issue-loop`'s Pass 2 stops finding the `(#N)` squash subject
+ * release), and repo-ai's `ai-loop` cleanup stops finding the `(#N)` squash subject
  * it uses to confirm work landed, so worktrees leak. Observed on `js-common`
  * #204, whose CONTRIBUTING already said squash-only — the rule existed, nothing
  * enforced it.
@@ -706,8 +706,8 @@ const PROTECTION_BODY = JSON.stringify({
     // any required_pull_request_reviews as drift, so `fix github-settings` PUTs it
     // back to null. A repo that deliberately requires approvals will have that
     // silently reverted by the next unrelated fix run, with nothing in the output
-    // naming the rule that was removed. Known downstream case: the ai-issue-loop
-    // pipeline works around it with approval labels precisely because of this.
+    // naming the rule that was removed. Known downstream case: @rtorcato/repo-ai's
+    // ai-loop pipeline works around it with approval labels precisely because of this.
     // Loosen the standard here first if a repo ever genuinely needs review gating.
     required_pull_request_reviews: null,
     restrictions: null,

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

@@ -173,6 +173,8 @@ export function declinedInLock(lock, checkName) {
             return c.turborepo === false;
         case 'Tailwind':
             return c.tailwind === false;
+        case 'Brand assets':
+            return c.brand === false;
         default:
             return false;
     }
@@ -246,6 +248,8 @@ export function lockfilePatchForTarget(target, lock) {
             return c.docsSite ? null : { docsSite: true };
         case 'bun':
             return c.bun ? null : { bun: true };
+        case 'brand':
+            return c.brand ? null : { brand: true };
         default:
             return null;
     }

package/dist/cli/commands/setup-presets.js

@@ -59,6 +59,7 @@ export function buildPresetConfig(name, projectName) {
                 semanticRelease: true,
                 bundler: 'tsup',
                 publint: true,
+                brand: true,
             };
         case 'web-app':
             return {
@@ -210,6 +211,7 @@ export const CONFIG_SCHEMA = {
         nx: { type: 'boolean' },
         tailwind: { type: 'boolean' },
         docsSite: { type: 'boolean' },
+        brand: { type: 'boolean' },
         bun: { type: 'boolean' },
     },
 };
@@ -315,6 +317,8 @@ export function computeFileList(config) {
         files.push('postcss.config.mjs', 'src/styles/globals.css');
     if (config.bun)
         files.push('bunfig.toml');
+    if (config.brand)
+        files.push('brand/banner.svg', 'brand/banner-mobile.svg', 'brand/social-card.svg', 'brand/render.sh');
     files.push('README.md');
     return files;
 }

package/dist/cli/commands/setup.js

@@ -22,6 +22,7 @@ const REVIEWABLE_FEATURES = [
     { key: 'securityAutomation', label: 'Security automation (Dependabot + CodeQL)' },
     { key: 'badges', label: 'README status badges' },
     { key: 'aiSetup', label: 'AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot)' },
+    { key: 'brand', label: 'Brand assets (brand/ banner + social-card SVGs, render.sh)' },
 ];
 /**
  * A preset run may only ask questions when a human is on both ends of the pipe.
@@ -457,6 +458,13 @@ async function promptForConfig(targetDir, seed) {
             message: '🤖 Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)?',
             default: seed?.aiSetup ?? true,
         },
+        {
+            type: 'confirm',
+            name: 'brand',
+            message: '🎨 Add brand assets (brand/ banner + social-card SVG sources, render.sh)?',
+            // On by default for libraries — the ones that publish a README to npm.
+            default: (answers) => seed?.brand ?? answers.projectType === 'library',
+        },
         {
             type: 'select',
             name: 'orchestrator',
@@ -546,6 +554,7 @@ async function promptForConfig(targetDir, seed) {
         publint: answers.publint ?? false,
         badges: answers.badges ?? false,
         aiSetup: answers.aiSetup ?? false,
+        brand: answers.brand ?? false,
         turborepo: answers.orchestrator === 'turbo',
         nx: answers.orchestrator === 'nx',
         tailwind: answers.tailwind ?? false,

package/dist/cli/generators/docs-site.js

@@ -86,9 +86,16 @@ async function ensureWorkspace(targetDir) {
     await fs.writeFile(file, next);
     return rel;
 }
-/** The GitHub Pages base path Docusaurus serves under, e.g. `/repo-tooling/`. */
-function siteBaseUrl(meta) {
-    return `/${meta.repo ?? meta.title}/`;
+/**
+ * A JS string literal in the Biome preset's quote style: single quotes, unless
+ * the value holds more single than double quotes — the same pick Biome makes.
+ */
+function jsString(value) {
+    const singles = value.split("'").length - 1;
+    const doubles = value.split('"').length - 1;
+    if (singles > doubles)
+        return JSON.stringify(value);
+    return `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
 }
 function docusaurusConfig(meta, typedocModules) {
     const owner = meta.owner ?? 'your-org';
@@ -100,111 +107,111 @@ function docusaurusConfig(meta, typedocModules) {
         ? "import { getTypedocPlugins } from '@rtorcato/repo-tooling/docusaurus'\n"
         : '';
     const typedocPlugins = typedocModules.length
-        ? `    ...getTypedocPlugins(${JSON.stringify(typedocModules)}),\n`
+        ? `\t\t...getTypedocPlugins([${typedocModules.map(jsString).join(', ')}]),\n`
         : '';
     return `import type * as Preset from '@docusaurus/preset-classic'
 import type { Config } from '@docusaurus/types'
 import { themes as prismThemes } from 'prism-react-renderer'
 ${typedocImport}
 const config: Config = {
-  title: '${meta.title}',
-  tagline: ${JSON.stringify(meta.tagline)},
-  favicon: 'img/favicon.ico',
+\ttitle: '${meta.title}',
+\ttagline: ${jsString(meta.tagline)},
+\tfavicon: 'img/favicon.ico',
 
-  url: 'https://${owner}.github.io',
-  baseUrl: '/${repo}/',
+\turl: 'https://${owner}.github.io',
+\tbaseUrl: '/${repo}/',
 
-  organizationName: '${owner}',
-  projectName: '${repo}',
+\torganizationName: '${owner}',
+\tprojectName: '${repo}',
 
-  onBrokenLinks: 'warn',
+\tonBrokenLinks: 'warn',
 
-  markdown: {
-    format: 'detect',
-    hooks: {
-      onBrokenMarkdownLinks: 'warn',
-    },
-  },
+\tmarkdown: {
+\t\tformat: 'detect',
+\t\thooks: {
+\t\t\tonBrokenMarkdownLinks: 'warn',
+\t\t},
+\t},
 
-  i18n: {
-    defaultLocale: 'en',
-    locales: ['en'],
-  },
+\ti18n: {
+\t\tdefaultLocale: 'en',
+\t\tlocales: ['en'],
+\t},
 
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          sidebarPath: './sidebars.ts',
-          routeBasePath: '/docs',
-          editUrl: '${ghUrl}/edit/main/apps/docs/',
-        },
-        blog: false,
-        theme: {
-          customCss: './src/css/custom.css',
-        },
-      } satisfies Preset.Options,
-    ],
-  ],
+\tpresets: [
+\t\t[
+\t\t\t'classic',
+\t\t\t{
+\t\t\t\tdocs: {
+\t\t\t\t\tsidebarPath: './sidebars.ts',
+\t\t\t\t\trouteBasePath: '/docs',
+\t\t\t\t\teditUrl: '${ghUrl}/edit/main/apps/docs/',
+\t\t\t\t},
+\t\t\t\tblog: false,
+\t\t\t\ttheme: {
+\t\t\t\t\tcustomCss: './src/css/custom.css',
+\t\t\t\t},
+\t\t\t} satisfies Preset.Options,
+\t\t],
+\t],
 
-  plugins: [
-${typedocPlugins}    [
-      '@easyops-cn/docusaurus-search-local',
-      {
-        hashed: true,
-        indexDocs: true,
-        indexBlog: false,
-        docsRouteBasePath: '/docs',
-        highlightSearchTermsOnTargetPage: true,
-        searchBarShortcutHint: false,
-      },
-    ],
-  ],
+\tplugins: [
+${typedocPlugins}\t\t[
+\t\t\t'@easyops-cn/docusaurus-search-local',
+\t\t\t{
+\t\t\t\thashed: true,
+\t\t\t\tindexDocs: true,
+\t\t\t\tindexBlog: false,
+\t\t\t\tdocsRouteBasePath: '/docs',
+\t\t\t\thighlightSearchTermsOnTargetPage: true,
+\t\t\t\tsearchBarShortcutHint: false,
+\t\t\t},
+\t\t],
+\t],
 
-  themeConfig: {
-    colorMode: {
-      defaultMode: 'dark',
-      respectPrefersColorScheme: true,
-    },
-    navbar: {
-      title: '${meta.title}',
-      items: [
-        { to: '/docs', position: 'left', label: 'Docs' },
-        {
-          href: '${ghUrl}',
-          label: 'GitHub',
-          position: 'right',
-        },
-      ],
-    },
-    footer: {
-      style: 'dark',
-      links: [
-        {
-          title: 'Docs',
-          items: [{ label: 'Getting Started', to: '/docs' }],
-        },
-        {
-          title: 'More',
-          items: [
-            { label: 'GitHub', href: '${ghUrl}' },
-            { label: 'Issues', href: '${ghUrl}/issues' },
-          ],
-        },
-      ],
-      copyright: \`Copyright © \${new Date().getFullYear()} ${meta.title}. Built with Docusaurus.\`,
-    },
-    // \`theme\` is the LIGHT-mode Prism theme and \`darkTheme\` the dark one. Both
-    // were vsDark here, which is why the shared stylesheet had to pin fenced
-    // blocks dark in light mode too (#324). Keep this pairing and the CSS in
-    // step — vsDark tokens on a light surface are unreadable.
-    prism: {
-      theme: prismThemes.vsLight,
-      darkTheme: prismThemes.vsDark,
-      additionalLanguages: ['bash', 'json', 'typescript'],
-    },
-  } satisfies Preset.ThemeConfig,
+\tthemeConfig: {
+\t\tcolorMode: {
+\t\t\tdefaultMode: 'dark',
+\t\t\trespectPrefersColorScheme: true,
+\t\t},
+\t\tnavbar: {
+\t\t\ttitle: '${meta.title}',
+\t\t\titems: [
+\t\t\t\t{ to: '/docs', position: 'left', label: 'Docs' },
+\t\t\t\t{
+\t\t\t\t\thref: '${ghUrl}',
+\t\t\t\t\tlabel: 'GitHub',
+\t\t\t\t\tposition: 'right',
+\t\t\t\t},
+\t\t\t],
+\t\t},
+\t\tfooter: {
+\t\t\tstyle: 'dark',
+\t\t\tlinks: [
+\t\t\t\t{
+\t\t\t\t\ttitle: 'Docs',
+\t\t\t\t\titems: [{ label: 'Getting Started', to: '/docs' }],
+\t\t\t\t},
+\t\t\t\t{
+\t\t\t\t\ttitle: 'More',
+\t\t\t\t\titems: [
+\t\t\t\t\t\t{ label: 'GitHub', href: '${ghUrl}' },
+\t\t\t\t\t\t{ label: 'Issues', href: '${ghUrl}/issues' },
+\t\t\t\t\t],
+\t\t\t\t},
+\t\t\t],
+\t\t\tcopyright: \`Copyright © \${new Date().getFullYear()} ${meta.title}. Built with Docusaurus.\`,
+\t\t},
+\t\t// \`theme\` is the LIGHT-mode Prism theme and \`darkTheme\` the dark one. Both
+\t\t// were vsDark here, which is why the shared stylesheet had to pin fenced
+\t\t// blocks dark in light mode too (#324). Keep this pairing and the CSS in
+\t\t// step — vsDark tokens on a light surface are unreadable.
+\t\tprism: {
+\t\t\ttheme: prismThemes.vsLight,
+\t\t\tdarkTheme: prismThemes.vsDark,
+\t\t\tadditionalLanguages: ['bash', 'json', 'typescript'],
+\t\t},
+\t} satisfies Preset.ThemeConfig,
 }
 
 export default config
@@ -215,7 +222,7 @@ const SIDEBARS = `import type { SidebarsConfig } from '@docusaurus/plugin-conten
 // Autogenerated from the docs/ folder structure — add markdown files and they
 // appear here. Swap for an explicit list when you want to control ordering.
 const sidebars: SidebarsConfig = {
-  docs: [{ type: 'autogenerated', dirName: '.' }],
+\tdocs: [{ type: 'autogenerated', dirName: '.' }],
 }
 
 export default sidebars
@@ -246,13 +253,13 @@ function customCss(accent) {
 @import "./_jt-tokens.css";
 
 :root {
-  --ifm-color-primary: ${accent.light};
-  --jt-accent: ${accent.light};
+\t--ifm-color-primary: ${accent.light};
+\t--jt-accent: ${accent.light};
 }
 
 [data-theme="dark"] {
-  --ifm-color-primary: ${accent.dark};
-  --jt-accent: ${accent.dark};
+\t--ifm-color-primary: ${accent.dark};
+\t--jt-accent: ${accent.dark};
 }
 `;
 }
@@ -279,9 +286,6 @@ function docsPackageJson(meta, typedoc) {
             serve: 'docusaurus serve',
             clear: 'docusaurus clear',
             typecheck: 'tsc --noEmit',
-            // Opt-in smoke test — builds, serves, and checks the site renders. Heavy
-            // browser install, so it's a manual/CI-gated run, not part of `build`.
-            'test:e2e': 'playwright test',
         },
         dependencies: {
             '@docusaurus/core': '^3.10.2',
@@ -297,7 +301,6 @@ function docsPackageJson(meta, typedoc) {
             '@docusaurus/module-type-aliases': '^3.10.2',
             '@docusaurus/tsconfig': '^3.8.1',
             '@docusaurus/types': '^3.10.2',
-            '@playwright/test': '^1.49.0',
             '@rtorcato/repo-tooling': SELF_RANGE,
             '@types/react': '^19.0.0',
             typescript: '~5.6.3',
@@ -354,34 +357,6 @@ jobs:
       build-filter: '${meta.docsPkgName}'
 `;
 }
-/**
- * Playwright config for the docs smoke test. Reuses the shipped preset, then
- * builds + serves the site on :3000 and points the base URL at the site's
- * GitHub Pages base path so routes resolve exactly as in production. One
- * browser keeps the CI browser install light.
- */
-function playwrightConfig(meta) {
-    const url = `http://localhost:3000${siteBaseUrl(meta)}`;
-    return `import { defineConfig, devices } from '@playwright/test'
-import base from '@rtorcato/repo-tooling/playwright'
-
-export default defineConfig({
-  ...base,
-  testDir: './tests',
-  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
-  use: {
-    ...base.use,
-    baseURL: process.env.PLAYWRIGHT_BASE_URL ?? '${url}',
-  },
-  webServer: {
-    command: 'pnpm run build && pnpm exec docusaurus serve --port 3000',
-    url: process.env.PLAYWRIGHT_BASE_URL ?? '${url}',
-    reuseExistingServer: !process.env.CI,
-    timeout: 180_000,
-  },
-})
-`;
-}
 // routeBasePath is '/docs', so the site root has no page of its own and the
 // navbar logo links to a 404 on every page (#664). Redirect it to the docs.
 // Tabs/no semicolons to match the Biome preset the consuming repo is linted with.
@@ -392,21 +367,6 @@ export default function Home() {
 \treturn <Redirect to={useBaseUrl('/docs')} />
 }
 `;
-const SMOKE_SPEC = `import { expect, test } from '@playwright/test'
-
-// Smoke test: assert the built site serves and its core UI renders. Deliberately
-// content-agnostic — it validates "the site builds and boots", not copy.
-test('homepage responds and renders the shell', async ({ page }) => {
-  const res = await page.goto('./')
-  expect(res?.ok()).toBeTruthy()
-  await expect(page.locator('.navbar')).toBeVisible()
-})
-
-test('the starter doc renders a heading', async ({ page }) => {
-  await page.goto('./')
-  await expect(page.locator('h1')).toBeVisible()
-})
-`;
 /**
  * Scaffold the Docusaurus docs site. Writes each file only when missing and
  * returns the relative paths actually written, so `fix docs-site` is safe to
@@ -440,8 +400,6 @@ export async function generateDocsSite(pkg, targetDir, options = {}) {
         [`${DOCS_APP}/src/css/custom.css`, customCss(accent)],
         [`${DOCS_APP}/src/pages/index.tsx`, HOME_PAGE],
         [`${DOCS_APP}/docs/intro.md`, introDoc(meta, badges)],
-        [`${DOCS_APP}/playwright.config.ts`, playwrightConfig(meta)],
-        [`${DOCS_APP}/tests/smoke.spec.ts`, SMOKE_SPEC],
         ['.github/workflows/docs.yml', docsWorkflow(meta)],
     ];
     // TypeDoc emits docs/api/<id> on build — keep the generated tree out of git.

package/dist/cli/generators/index.js

@@ -19,6 +19,7 @@ import { generateTailwind } from './tailwind.js';
 import { generateTurborepo } from './turborepo.js';
 import { generateNx } from './nx.js';
 import { generateBun } from './bun.js';
+import { generateBrand } from './brand.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export async function generateConfigs(config, targetDir) {
@@ -122,6 +123,11 @@ export async function generateConfigs(config, targetDir) {
     }
     // Generate README
     await generateReadme(config, targetDir);
+    // brand/ (#677) — the same generator as `fix brand`. After the README so the
+    // banner-path repoint sees it; no tagline yet, as the lockfile isn't written.
+    if (config.brand) {
+        await generateBrand(await fs.readJson(path.join(targetDir, 'package.json')), targetDir);
+    }
     // Copy ts-reset if TypeScript is enabled
     if (config.typescript.enabled) {
         await copyTSReset(targetDir);

package/dist/cli/generators/security.js

@@ -163,6 +163,8 @@ export function dependabotIgnoreRules(content) {
  * Everything else falls through to a human: production bumps ship to consumers
  * of a published package (#423), majors are breaking by definition, and an
  * ungrouped npm PR reports an empty \`dependency-group\`, so the gate fails closed.
+ * A PR that falls through is assigned to the repo owner with one upserted comment
+ * saying why (#694), so it never sits green and ownerless.
  *
  * CI action bumps are the one ungrouped case that is allowed through, matched on
  * \`package-ecosystem\` (#452): they reach no consumer of the published package
@@ -226,11 +228,13 @@ jobs:
           # No names reported means we cannot verify anything — fail closed.
           if [ -z "\${NAMES//[, ]/}" ]; then
             echo "::notice::no dependency names reported — leaving this PR for a human"
+            echo "reason=Dependabot reported no dependency names, so nothing could be verified" >> "$GITHUB_OUTPUT"
             safe=false
           fi
           for name in \${NAMES//,/ }; do
             if printf '%s\\n' "$ships" | grep -qxF -- "$name"; then
               echo "::notice::$name ships to consumers — leaving this PR for a human"
+              echo "reason=$name ships to consumers of this package" >> "$GITHUB_OUTPUT"
               safe=false
               break
             fi
@@ -247,6 +251,7 @@ jobs:
       # "ci(deps): …", which cuts no release. Majors still fall through to a
       # human — the update-type clause below applies to them too.
       - name: Auto-merge dev-dependency and CI action patch and minor updates
+        id: merge
         if: |
           steps.gate.outputs.safe == 'true' &&
           (steps.metadata.outputs.dependency-group == 'dev-minor' ||
@@ -257,6 +262,46 @@ jobs:
         env:
           PR_URL: \${{ github.event.pull_request.html_url }}
           GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+
+      # Everything the step above declines needs a human, and a notice in the
+      # Actions log is not one (#694). Assign the repo owner and say why in a
+      # single comment, edited in place on every later run rather than repeated.
+      - name: Hand the PR to a human
+        if: steps.merge.outcome == 'skipped'
+        env:
+          PR_URL: \${{ github.event.pull_request.html_url }}
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          REPO: \${{ github.repository }}
+          PR_NUMBER: \${{ github.event.pull_request.number }}
+          OWNER: \${{ github.repository_owner }}
+          REASON: \${{ steps.gate.outputs.reason }}
+          UPDATE_TYPE: \${{ steps.metadata.outputs.update-type }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "$REASON" ]; then
+            case "$UPDATE_TYPE" in
+              version-update:semver-major) REASON="this is a major version bump" ;;
+              version-update:semver-minor | version-update:semver-patch)
+                REASON="this is neither a dev-minor group bump nor a CI action bump, so it may ship to consumers" ;;
+              *) REASON="Dependabot reported no update type, so nothing could be verified" ;;
+            esac
+          fi
+
+          marker='<!-- dependabot-automerge:manual-review -->'
+          body="$marker
+          Not auto-merged: $REASON. Leaving this for @$OWNER to review and merge by hand."
+
+          ids=$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" \\
+            --jq ".[] | select(.body | startswith(\\"$marker\\")) | .id")
+          if [ -n "$ids" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/\${ids%%$'\\n'*}" -f body="$body" > /dev/null
+          else
+            gh pr comment "$PR_URL" --body "$body"
+          fi
+
+          # An organisation login cannot be assigned; the comment still stands.
+          gh pr edit "$PR_URL" --add-assignee "$OWNER" || echo "::warning::could not assign $OWNER"
 `;
 /** Relative paths this generator owns, in a stable order for \`filesWritten\`. */
 export const DEPENDABOT_FILES = [

package/dist/cli/index.js

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
-import path from 'node:path';
 import chalk from 'chalk';
 import { Command } from 'commander';
-import fs from 'fs-extra';
 import { doctorCommand } from './commands/doctor.js';
 import { fixCommand } from './commands/fix.js';
 import { setupProject } from './commands/setup.js';
+import { selfRepoRefusal } from './self-repo.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
 import { getToolVersion } from './utils/version.js';
-async function isSelfRepo(dir) {
-    try {
-        const pkg = await fs.readJson(path.join(dir, 'package.json'));
-        return pkg.name === '@rtorcato/repo-tooling';
-    }
-    catch {
-        return false;
-    }
-}
 const program = new Command();
 program
     .name('@rtorcato/repo-tooling')
@@ -351,29 +341,11 @@ program
     process.exitCode = 1;
 });
 program.hook('preAction', async (_, actionCommand) => {
-    const name = actionCommand.name();
-    if (name === 'setup' || name === 'doctor' || name === 'fix') {
-        // `fix --list` is read-only and safe to run anywhere, including this repo.
-        if (name === 'fix' && actionCommand.opts().list)
-            return;
-        // Dogfood escape hatch (#273): allow read-only `doctor` against this repo
-        // so CI can audit our own config the same way it does consumers'. Scoped
-        // to doctor — the mutating setup/fix stay blocked even with the flag set.
-        if (name === 'doctor' && process.env.REPO_TOOLING_ALLOW_SELF === '1')
-            return;
-        // One mutating exception (#531): `fix lockfile` writes only
-        // .repo-tooling.json — no scaffolding — so our own lockfile can be
-        // migrated by the fixer we ship instead of by hand.
-        if (name === 'fix' &&
-            actionCommand.args[0] === 'lockfile' &&
-            process.env.REPO_TOOLING_ALLOW_SELF === '1')
-            return;
-        const dir = actionCommand.opts().directory ?? process.cwd();
-        if (await isSelfRepo(dir)) {
-            console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));
-            console.log(chalk.gray('   setup and doctor are for consumer projects, not for the tooling repo.\n'));
-            process.exit(0);
-        }
+    const refusal = await selfRepoRefusal(actionCommand.name(), actionCommand.args[0], actionCommand.opts());
+    if (refusal) {
+        console.log(chalk.yellow('\n⚠️  This command cannot be run inside the @rtorcato/repo-tooling repo itself.\n'));
+        console.log(chalk.gray(`   ${refusal}\n`));
+        process.exit(0);
     }
 });
 // Handle unknown commands

package/dist/cli/self-repo.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { getFixers } from './commands/fix.js';
+export async function isSelfRepo(dir) {
+    try {
+        const pkg = await fs.readJson(path.join(dir, 'package.json'));
+        return pkg.name === '@rtorcato/repo-tooling';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Why `setup` / `doctor` / `fix` must not run in `dir`, or null when it may.
+ * Most fixers write configs that import `@rtorcato/repo-tooling/...`, which
+ * this repo can't depend on, so inside it everything is refused unless
+ * `REPO_TOOLING_ALLOW_SELF=1` is set. With the flag, read-only `doctor` (#273)
+ * and `fix <target>` for a `selfSafe` target (#673) get through. A bare `fix`
+ * stays refused even then: it walks every fixer, self-safe or not.
+ */
+export async function selfRepoRefusal(command, target, opts, env = process.env) {
+    if (command !== 'setup' && command !== 'doctor' && command !== 'fix')
+        return null;
+    // `fix --list` is read-only and safe to run anywhere, including this repo.
+    if (command === 'fix' && opts.list)
+        return null;
+    if (!(await isSelfRepo(opts.directory ?? process.cwd())))
+        return null;
+    const allowSelf = env.REPO_TOOLING_ALLOW_SELF === '1';
+    if (allowSelf && command === 'doctor')
+        return null;
+    if (allowSelf && command === 'fix') {
+        if (!target) {
+            const safe = getFixers()
+                .filter((f) => f.selfSafe)
+                .map((f) => f.target);
+            return `a bare \`fix\` runs every fixer, including ones whose output imports @rtorcato/repo-tooling — name a self-safe target instead: ${safe.join(', ')}.`;
+        }
+        const fixer = getFixers().find((f) => f.target.toLowerCase() === target.toLowerCase());
+        if (fixer?.selfSafe)
+            return null;
+        return fixer
+            ? `\`fix ${target}\` is not self-safe: its output imports or depends on @rtorcato/repo-tooling, which this repo cannot depend on.`
+            : `\`fix ${target}\` is not a known self-safe target.`;
+    }
+    return 'setup and doctor are for consumer projects, not for the tooling repo.';
+}

package/dist/cli/utils/lockfile.js

@@ -36,8 +36,6 @@ export const MCP_IMPORTANCE = ['nice-to-have', 'important', 'critical'];
  * be this tool asserting a rule on a repo whose humans have not stated any.
  */
 export const DEFAULT_RULES = {
-    aiLoop: {},
-    requiredSkills: [],
     mcp: { recommended: [] },
     exceptions: {},
 };
@@ -111,7 +109,8 @@ export function lockfileSchema() {
                     aiLoop: {
                         type: 'object',
                         additionalProperties: false,
-                        description: 'Settings for the ai-issue-loop skills from @rtorcato/repo-ai. Repo-scoped on purpose: committed here they travel with the repo and survive a new laptop.',
+                        deprecated: true,
+                        description: 'Deprecated: moved to `.repo-ai.json`, owned by @rtorcato/repo-ai. Still accepted so existing files validate; removed in the next major. `npx @rtorcato/repo-ai fix config` moves it across.',
                         properties: {
                             agentUser: {
                                 type: 'string',
@@ -122,7 +121,8 @@ export function lockfileSchema() {
                     requiredSkills: {
                         type: 'array',
                         items: { type: 'string' },
-                        description: "Agent skills this repo's workflows depend on. Audited by `npx @rtorcato/repo-ai doctor`, which reports a missing or stale installed copy; it never installs one for you.",
+                        deprecated: true,
+                        description: 'Deprecated: moved to `.repo-ai.json`, owned by @rtorcato/repo-ai. Still accepted so existing files validate; removed in the next major. `npx @rtorcato/repo-ai fix config` moves it across.',
                     },
                     mcp: {
                         type: 'object',

package/dist/languages/js/checks.js

@@ -1188,8 +1188,8 @@ export async function checkTreeshakeSetup(dir, pkg) {
  * 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
+ * worktrees it creates itself (`EnterWorktree`); @rtorcato/repo-ai's `ai-loop`
+ * 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.
  */

package/dist/languages/js/fixers.js

@@ -546,6 +546,7 @@ export const FIXERS = [
     },
     {
         target: 'vscode-extensions',
+        selfSafe: true,
         description: 'Recommend the VS Code extensions matching the enabled tools (.vscode/extensions.json)',
         appliesTo: ['VS Code extensions'],
         outputs: ['.vscode/extensions.json'],
@@ -559,6 +560,7 @@ export const FIXERS = [
     },
     {
         target: 'nvmrc',
+        selfSafe: true,
         description: 'Scaffold .nvmrc pinned to Node 22',
         appliesTo: ['Node version pin'],
         outputs: ['.nvmrc'],
@@ -892,6 +894,7 @@ export const FIXERS = [
     },
     {
         target: 'lockfile',
+        selfSafe: true,
         description: `Scaffold ${LOCKFILE_NAME} recording current tool choices`,
         appliesTo: ['lockfile'],
         outputs: [LOCKFILE_NAME],

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "4.1.0",
+	"version": "4.3.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [
@@ -248,6 +248,7 @@
 		"@next/eslint-plugin-next": "^16.3.2",
 		"@playwright/test": "^1.62.1",
 		"@rollup/plugin-typescript": "^12.3.0",
+		"@rtorcato/repo-ai": "^3.1.1",
 		"@semantic-release/commit-analyzer": "^13.0.1",
 		"@semantic-release/exec": "^7.1.0",
 		"@semantic-release/github": "^12.0.9",