@rtorcato/repo-tooling 3.28.0 → 3.30.0

package/AGENTS.md

@@ -19,6 +19,8 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `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` / `declared`. |
+| `doctor --rules-from <owner/repo>` | ✅ | ✅ | Report how this repo's `config`/`rules` differ from a reference repo's `.repo-tooling.json` (read over `gh`). Informational only — adds a `rulesReference` key to the JSON, never a check result, never affects the exit code. |
+| `setup --from <owner/repo>` | ❌ (seeds the wizard) | `--dry-run` only | Seed the wizard's defaults from a reference repo's recorded config. Seeded, not skipped — every question is still asked. |
 | `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/agent-user.js

@@ -31,15 +31,15 @@ export async function checkAgentUser(dir, agentUser, exec) {
         return {
             check: CHECK,
             status: 'ok',
-            detail: 'not applicable — no aiLoop.agentUser in .repo-tooling.json',
+            detail: 'not applicable — no rules.aiLoop.agentUser in .repo-tooling.json',
         };
     }
     if (!LOGIN.test(agentUser)) {
         return {
             check: CHECK,
             status: 'drift',
-            detail: `aiLoop.agentUser "${agentUser}" is not a valid GitHub login`,
-            hint: 'Fix or remove aiLoop.agentUser in .repo-tooling.json',
+            detail: `rules.aiLoop.agentUser "${agentUser}" is not a valid GitHub login`,
+            hint: 'Fix or remove rules.aiLoop.agentUser in .repo-tooling.json',
         };
     }
     // Cheap gate first: no .git → never spawn (keeps tmp-dir doctor runs offline).
@@ -52,15 +52,15 @@ export async function checkAgentUser(dir, agentUser, exec) {
         return {
             check: CHECK,
             status: 'ok',
-            detail: `aiLoop.agentUser "${agentUser}" is an assignable collaborator`,
+            detail: `rules.aiLoop.agentUser "${agentUser}" is an assignable collaborator`,
         };
     }
     if (/HTTP 404/.test(r.stderr)) {
         return {
             check: CHECK,
             status: 'drift',
-            detail: `aiLoop.agentUser "${agentUser}" is not an assignable collaborator — the loop skills will silently assign nothing`,
-            hint: `Add the account as a collaborator (\`gh api -X PUT repos/{owner}/{repo}/collaborators/${agentUser}\`) or remove aiLoop.agentUser from .repo-tooling.json`,
+            detail: `rules.aiLoop.agentUser "${agentUser}" is not an assignable collaborator — the loop skills will silently assign nothing`,
+            hint: `Add the account as a collaborator (\`gh api -X PUT repos/{owner}/{repo}/collaborators/${agentUser}\`) or remove rules.aiLoop.agentUser from .repo-tooling.json`,
         };
     }
     // Offline, unauthenticated, or gh missing — not evidence of drift.

package/dist/cli/commands/doctor.js

@@ -19,6 +19,7 @@ import { checkMilestones } from '../../base/milestones.js';
 import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
+import { compareRulesWithReference } from '../utils/reference-rules.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, 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';
@@ -136,7 +137,9 @@ function checkLockfile(lock) {
     return {
         check: 'lockfile',
         status: 'ok',
-        detail: `.repo-tooling.json v${lock.version} (written by ${lock.writtenBy})`,
+        // The stamp only ever describes the tool-written `record` subtree — the
+        // human-written `rules` half is deliberately unstamped (#559).
+        detail: `.repo-tooling.json v${lock.version} (record written by ${lock.record.writtenBy})`,
     };
 }
 // Lockfile-driven demotion: if the lock records an intentional opt-out for a
@@ -162,7 +165,7 @@ function demoteDeclined(results, lock) {
 // 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;
+    const exceptions = lock?.rules?.exceptions;
     if (!exceptions)
         return results;
     const known = new Set(results.map((r) => r.check));
@@ -221,7 +224,7 @@ async function runBaseChecks(dir, lock, opts) {
     // ai-issue-loop label colours/descriptions (#446) — same seam, same self-skip.
     results.push(await checkLoopLabels(dir));
     // aiLoop.agentUser assignability (#530) — same seam, same self-skip.
-    results.push(await checkAgentUser(dir, lock?.aiLoop?.agentUser));
+    results.push(await checkAgentUser(dir, lock?.rules?.aiLoop?.agentUser));
     results.push(await checkGitLabCI(dir));
     results.push(await checkCodeowners(dir));
     results.push(await checkCommunityHealth(dir));
@@ -231,13 +234,13 @@ async function runBaseChecks(dir, lock, opts) {
     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));
+    if (lock?.rules?.aiLoop && lock.rules.requiredSkills?.length) {
+        results.push(await checkRequiredSkills(lock.rules.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));
+    if (lock?.rules?.mcp?.recommended?.length) {
+        results.push(await checkRecommendedMcp(dir, lock.rules.mcp.recommended));
     }
     results.push(await checkReadmeBadges(dir, opts.badges.audience, opts.badges.fixTarget));
     results.push(await checkCoverageUpload(dir));
@@ -463,11 +466,43 @@ export function summarize(results) {
         declared: results.filter((r) => r.status === 'declared').length,
     };
 }
+/**
+ * Print the `--rules-from` comparison (#563). Deliberately not a CheckResult:
+ * two repos legitimately differ, so a difference is never a finding about either
+ * one, and keeping it out of `results` is what makes "never affects the exit
+ * code" structural rather than a promise the next check has to remember.
+ */
+function printRulesComparison(comparison) {
+    console.log(chalk.cyan(`\n📐 Rules vs ${comparison.reference}`), chalk.gray('(informational — differences are not drift and do not affect the exit code)\n'));
+    if (!comparison.compared) {
+        console.log(`  ${chalk.gray('➖')} ${chalk.gray(`not compared — ${comparison.reason}`)}\n`);
+        return;
+    }
+    const differences = comparison.differences ?? [];
+    if (differences.length === 0) {
+        console.log(`  ${chalk.green('✅')} ${chalk.gray('identical — no differences to report')}\n`);
+        return;
+    }
+    const show = (v) => (v === undefined ? chalk.dim('(absent)') : JSON.stringify(v));
+    for (const d of differences) {
+        console.log(`  ${chalk.bold(d.path)}`);
+        console.log(`     ${chalk.gray('here:')} ${show(d.local)}`);
+        console.log(`     ${chalk.gray(`${comparison.reference}:`)} ${show(d.reference)}`);
+    }
+    console.log(chalk.gray(`\n  ${differences.length} difference(s).\n`));
+}
 export async function doctorCommand(options = {}) {
     const dir = options.directory ?? process.cwd();
     const results = await runDoctor(dir, options.skillsDir);
+    const comparison = options.rulesFrom
+        ? await compareRulesWithReference(dir, options.rulesFrom)
+        : null;
     if (options.json) {
-        console.log(JSON.stringify({ directory: path.resolve(dir), results }, null, 2));
+        console.log(JSON.stringify({
+            directory: path.resolve(dir),
+            results,
+            ...(comparison ? { rulesReference: comparison } : {}),
+        }, null, 2));
     }
     else {
         console.log(chalk.cyan(`\n🩺 Diagnosing ${path.resolve(dir)} against ${PACKAGE} presets...\n`));
@@ -489,6 +524,8 @@ export async function doctorCommand(options = {}) {
             }
             console.log();
         }
+        if (comparison)
+            printRulesComparison(comparison);
     }
     const summary = summarize(results);
     const exitCode = summary.drift > 0 || summary.missing > 0 ? 1 : 0;

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

@@ -124,7 +124,7 @@ export function getFixTargetForCheck(checkName, language) {
 export function declinedInLock(lock, checkName) {
     if (!lock)
         return false;
-    const c = lock.config;
+    const c = lock.record.config;
     switch (checkName) {
         case 'TypeScript':
             return c.typescript?.enabled === false;
@@ -186,7 +186,7 @@ export function declinedInLock(lock, checkName) {
  * the lockfile already reflects the change.
  */
 export function lockfilePatchForTarget(target, lock) {
-    const c = lock.config;
+    const c = lock.record.config;
     switch (target) {
         case 'biome':
             if (c.linting.tool === 'biome' || c.linting.tool === 'both')

package/dist/cli/commands/fix.js

@@ -291,7 +291,7 @@ export async function fixCommand(target, options = {}) {
             }
             process.exit(1);
         }
-        const files = computeFileList(resyncLock.config);
+        const files = computeFileList(resyncLock.record.config);
         if (!silent) {
             console.log(chalk.cyan(`\n🔄 Resync from ${LOCKFILE_NAME} (${files.length} files in scope)\n`));
         }
@@ -320,8 +320,8 @@ export async function fixCommand(target, options = {}) {
                 return;
             }
         }
-        await generateConfigs(resyncLock.config, targetDir);
-        await writeLockfile(targetDir, resyncLock.config);
+        await generateConfigs(resyncLock.record.config, targetDir);
+        await writeLockfile(targetDir, resyncLock.record.config);
         if (json) {
             console.log(JSON.stringify({ directory: targetDir, mode: 'resync', dryRun: false, files }, null, 2));
         }

package/dist/cli/commands/setup.js

@@ -8,6 +8,7 @@ import { detectLanguage } from '../utils/detect-language.js';
 import { formatGeneratedFiles } from '../utils/format.js';
 import { installDependencies } from '../utils/install.js';
 import { LOCKFILE_NAME, writeLockfile } from '../utils/lockfile.js';
+import { fetchReferenceLockfile } from '../utils/reference-rules.js';
 import { buildPresetConfig, computeFileList, CONFIG_SCHEMA, PRESET_NAMES, validateProjectConfig, } from './setup-presets.js';
 /**
  * The opinionated extras a preset turns on, in the order they're offered for
@@ -63,11 +64,36 @@ async function reviewPresetConfig(config) {
     }
     return reviewed;
 }
+/**
+ * Read a reference repo's recorded config to seed the wizard (#563). Only
+ * `record.config` — the answers — crosses over: `assets` and the
+ * `writtenBy`/`writtenAt` stamps describe the reference's own history, and this
+ * repo's lockfile gets its own on the first write. `rules` is left behind too,
+ * since an `exceptions` entry excuses a deviation in the repo that wrote it.
+ *
+ * `null` means the reference could not be read — reported plainly and declined,
+ * the way `doctor --rules-from` reports "not compared". Falling through to an
+ * unseeded wizard would be worse: the user asked for that repo's answers, and
+ * generic defaults would be written as though they had confirmed them.
+ */
+async function seedFromReference(reference) {
+    const result = await fetchReferenceLockfile(reference);
+    if (!result.ok) {
+        console.error(chalk.red(`\n❌ Cannot seed from ${reference} — ${result.reason}.`));
+        console.error(chalk.gray('   Re-run without --from to answer the wizard from scratch.\n'));
+        return null;
+    }
+    console.log(chalk.cyan(`\n🌱 Seeding defaults from ${reference} — every answer is still yours to change.\n`));
+    return result.lockfile.record.config;
+}
 /** `null` means the run was declined, not that it failed — see promptForConfig. */
 async function resolveConfig(options) {
     if (options.config && options.preset) {
         console.warn(chalk.yellow('⚠️  Both --config and --preset given; --config wins.\n'));
     }
+    if (options.from && (options.config || options.preset)) {
+        console.warn(chalk.yellow('⚠️  --from seeds the wizard, which --config/--preset skip; ignoring --from.\n'));
+    }
     if (options.config) {
         const configPath = path.resolve(options.config);
         if (!(await fs.pathExists(configPath))) {
@@ -76,10 +102,12 @@ async function resolveConfig(options) {
         const raw = await fs.readJson(configPath);
         // Accept the `.repo-tooling.json` lockfile itself as the config source, so a
         // repo needs only one file: the lockfile already embeds the full
-        // ProjectConfig under `config`. Unwrap it here rather than requiring a
-        // separate hand-authored config file (#271).
-        const candidate = typeof raw === 'object' && raw !== null && 'config' in raw && 'version' in raw
-            ? raw.config
+        // ProjectConfig — under `record.config` since v4, top-level `config` before
+        // (#559). Unwrap it here rather than requiring a separate config file (#271).
+        const candidate = typeof raw === 'object' && raw !== null && 'version' in raw
+            ? (raw.record?.config ??
+                raw.config ??
+                raw)
             : raw;
         const { valid, errors } = validateProjectConfig(candidate);
         if (!valid) {
@@ -97,7 +125,14 @@ async function resolveConfig(options) {
             return config;
         return reviewPresetConfig(config);
     }
-    return promptForConfig(path.resolve(options.directory));
+    let seed;
+    if (options.from) {
+        const seeded = await seedFromReference(options.from);
+        if (seeded === null)
+            return null;
+        seed = seeded;
+    }
+    return promptForConfig(path.resolve(options.directory), seed);
 }
 export async function setupProject(options) {
     if (options.configSchema) {
@@ -163,7 +198,7 @@ const SCAFFOLDABLE = ['js', 'swift'];
  * like. Languages setup can't scaffold yet are still offered — hiding them reads
  * as "repo-tooling is JS-only" when the honest answer is "not yet" (#139).
  */
-async function promptForLanguage(targetDir) {
+async function promptForLanguage(targetDir, seed) {
     const detected = await detectLanguage(targetDir);
     const { language } = await inquirer.prompt([
         {
@@ -176,8 +211,10 @@ async function promptForLanguage(targetDir) {
                     : `${module.label} (${module.supported ? 'doctor/fix only — no setup preset yet' : 'setup lands with its module'})`,
                 value: module.id,
             })),
+            // What this dir already looks like beats the reference's language: the
+            // files on disk are evidence, the reference is only a suggestion.
             // 'unknown' is a bare dir mid-setup — JS is the historical default.
-            default: detected === 'unknown' ? 'js' : detected,
+            default: detected !== 'unknown' ? detected : (seed?.language ?? 'js'),
         },
     ]);
     return LANGUAGES[language];
@@ -194,9 +231,16 @@ function explainNotScaffoldable(module) {
     console.log(chalk.gray(`   ${module.label} setup presets are tracked at\n` +
         '   https://github.com/rtorcato/repo-tooling/issues/139\n'));
 }
-/** `null` when the chosen language has no scaffolding yet; nothing is written. */
-async function promptForConfig(targetDir) {
-    const language = await promptForLanguage(targetDir);
+/**
+ * `null` when the chosen language has no scaffolding yet; nothing is written.
+ *
+ * @param seed A reference repo's recorded config (#563). It moves the *defaults*
+ *   only — every question is still asked, so seeding can never write an answer
+ *   the user did not see. `projectName` is deliberately never seeded: a new repo
+ *   is not the reference repo.
+ */
+async function promptForConfig(targetDir, seed) {
+    const language = await promptForLanguage(targetDir, seed);
     // Gate on SCAFFOLDABLE, not `module.supported` — Swift is supported (#286)
     // but has no preset yet (#288), and falling through here would write a
     // package.json into a Swift repo.
@@ -226,6 +270,18 @@ async function promptForConfig(targetDir) {
     // Turborepo only makes sense in a pnpm-workspace monorepo, so the prompt is
     // only offered when one is already present in the target dir.
     const hasWorkspace = await fs.pathExists(path.join(targetDir, 'pnpm-workspace.yaml'));
+    // Two questions ask for something the config stores as a set of booleans, so
+    // their seeded default has to be derived rather than read.
+    const seededReleaseTool = !seed
+        ? 'semantic-release'
+        : seed.semanticRelease
+            ? 'semantic-release'
+            : seed.changesets
+                ? 'changesets'
+                : seed.releasePlease
+                    ? 'release-please'
+                    : 'none';
+    const seededOrchestrator = !seed ? 'turbo' : seed.turborepo ? 'turbo' : seed.nx ? 'nx' : 'none';
     const answers = await inquirer.prompt([
         {
             type: 'input',
@@ -238,6 +294,7 @@ async function promptForConfig(targetDir) {
             type: 'select',
             name: 'projectType',
             message: '🏗️  What type of project are you building?',
+            default: seed?.projectType,
             choices: [
                 { name: '📚 Library/Package', value: 'library' },
                 { name: '🌐 Web Application', value: 'web-app' },
@@ -250,7 +307,7 @@ async function promptForConfig(targetDir) {
             type: 'confirm',
             name: 'useTypeScript',
             message: '📘 Do you want to use TypeScript?',
-            default: true,
+            default: seed?.typescript.enabled ?? true,
         },
         {
             type: 'select',
@@ -275,6 +332,7 @@ async function promptForConfig(targetDir) {
                 }
                 return baseChoices;
             },
+            default: seed?.typescript.config,
             when: (answers) => answers.useTypeScript,
         },
         {
@@ -287,7 +345,7 @@ async function promptForConfig(targetDir) {
                 { name: '🔥 Both Biome + ESLint', value: 'both' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'biome',
+            default: seed?.linting.tool ?? 'biome',
         },
         {
             type: 'select',
@@ -300,13 +358,14 @@ async function promptForConfig(targetDir) {
                 }
                 return choices;
             },
+            default: seed?.linting.eslintConfig,
             when: (answers) => answers.lintingTool === 'eslint' || answers.lintingTool === 'both',
         },
         {
             type: 'confirm',
             name: 'oxlint',
             message: '🦀 Also run Oxlint alongside (50–100× faster than ESLint)?',
-            default: false,
+            default: seed?.oxlint ?? false,
             when: (answers) => answers.lintingTool !== 'none',
         },
         {
@@ -320,7 +379,7 @@ async function promptForConfig(targetDir) {
                 { name: '🌲 Cypress (E2E)', value: 'cypress' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'vitest',
+            default: seed?.testing.framework ?? 'vitest',
         },
         {
             type: 'select',
@@ -332,19 +391,19 @@ async function promptForConfig(targetDir) {
                 { name: '🔄 Both', value: 'both' },
             ],
             when: (answers) => answers.testingFramework === 'jest',
-            default: 'node',
+            default: seed?.testing.environment ?? 'node',
         },
         {
             type: 'confirm',
             name: 'gitHooks',
             message: '🪝 Set up Git hooks (Husky + lint-staged)?',
-            default: true,
+            default: seed?.gitHooks ?? true,
         },
         {
             type: 'confirm',
             name: 'commitLint',
             message: '📝 Set up conventional commit linting?',
-            default: true,
+            default: seed?.commitLint ?? true,
             when: (answers) => answers.gitHooks,
         },
         {
@@ -357,40 +416,40 @@ async function promptForConfig(targetDir) {
                 { name: '🙏 Release Please (Google, release-PR-driven)', value: 'release-please' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'semantic-release',
+            default: seededReleaseTool,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'treeshakeCheck',
             message: '🌳 Add a tree-shake verification check (apps/treeshake-check)?',
-            default: false,
+            default: seed?.treeshakeCheck ?? false,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'publint',
             message: '📦 Add publint to lint your package before publishing?',
-            default: true,
+            default: seed?.publint ?? true,
             when: (answers) => answers.projectType === 'library',
         },
         {
             type: 'confirm',
             name: 'badges',
             message: '🔖 Add status badges (CI, npm, coverage, license) to the README?',
-            default: true,
+            default: seed?.badges ?? true,
         },
         {
             type: 'confirm',
             name: 'securityAutomation',
             message: '🛡️  Include security automation (Dependabot + CodeQL)?',
-            default: true,
+            default: seed?.securityAutomation ?? true,
         },
         {
             type: 'confirm',
             name: 'aiSetup',
             message: '🤖 Add AI agent rules (AGENTS.md, CLAUDE.md, Cursor, Copilot, Claude skill)?',
-            default: true,
+            default: seed?.aiSetup ?? true,
         },
         {
             type: 'select',
@@ -401,14 +460,14 @@ async function promptForConfig(targetDir) {
                 { name: '🔷 Nx (nx.json)', value: 'nx' },
                 { name: '❌ None', value: 'none' },
             ],
-            default: 'turbo',
+            default: seededOrchestrator,
             when: () => hasWorkspace,
         },
         {
             type: 'confirm',
             name: 'tailwind',
             message: '🎨 Add Tailwind CSS v4 (PostCSS plugin + globals.css)?',
-            default: true,
+            default: seed?.tailwind ?? true,
             // Only meaningful for frontend project types.
             when: (answers) => answers.projectType === 'web-app' ||
                 answers.projectType === 'react-app' ||
@@ -431,13 +490,14 @@ async function promptForConfig(targetDir) {
                 }
                 return choices;
             },
+            default: seed?.bundler,
             when: (answers) => answers.projectType !== 'nextjs-app', // Next.js has its own bundler
         },
         {
             type: 'confirm',
             name: 'bun',
             message: '🥟 Target the Bun runtime (bunfig.toml + Bun-typed tsconfig)?',
-            default: false,
+            default: seed?.bun ?? false,
             // A runtime flag, not a project type — offer it for Node-compatible
             // library/API targets, not the browser-framework types.
             when: (answers) => answers.projectType === 'library' || answers.projectType === 'node-api',

package/dist/cli/index.js

@@ -34,6 +34,8 @@ program
     .option('--config <path>', 'Skip prompts; read a ProjectConfig or .repo-tooling.json lockfile from <path>')
     .option('--dry-run', 'Print the resolved config and file list, write nothing')
     .option('--config-schema', 'Print the JSON Schema for ProjectConfig and exit')
+    // Seeds the wizard, never skips it (#563) — every answer is still yours.
+    .option('--from <owner/repo>', "Seed the wizard's defaults from that repo's .repo-tooling.json instead of the built-in ones (read via `gh`)")
     .action(setupProject);
 program
     .command('copy <config>')
@@ -321,6 +323,9 @@ program
     // The read side of `fix --skills-dir` (#485). No --yes/--json requirement
     // here: doctor never writes, so an unresolved directory is just reported.
     .option('--skills-dir <path>', 'Where `fix claude-skills` installs user-global agent skills (default: ~/.claude/skills). Pass the same path `fix` was given, or the skill reports as not installed')
+    // Rules are per-repo (#563): this compares them against another repo's, and
+    // only reports. Never drift, never a fixer, never part of the exit code.
+    .option('--rules-from <owner/repo>', "Report how this repo's config and rules differ from that repo's .repo-tooling.json (informational; read via `gh`)")
     .action(doctorCommand);
 program
     .command('fix [target]')

package/dist/cli/utils/copied-assets.js

@@ -33,7 +33,7 @@ export async function classifyCopiedAssets(dir) {
         const current = await hashFile(path.join(dir, preset.target));
         if (current === null)
             continue;
-        const recorded = lock?.assets?.[name];
+        const recorded = lock?.record.assets?.[name];
         // Unmodified since the copy, so whether it's stale is purely a question of
         // what this package ships now. A source we can't read (shouldn't happen)
         // falls back to the recorded hash — "no news", not drift.

package/dist/cli/utils/json-schema.js

@@ -0,0 +1,64 @@
+/**
+ * A JSON Schema validator covering exactly the keyword subset `lockfileSchema()`
+ * and `CONFIG_SCHEMA` use: type (object/array/string/integer/boolean), enum,
+ * minLength, required, properties, additionalProperties (`false` or a schema)
+ * and items. Returns one message per problem; an empty array means valid.
+ *
+ * Hand-rolled because the repo has no JSON Schema validator and the schemas lean
+ * on seven keywords — not enough to justify an ajv dependency. It lives in src
+ * rather than in a test because a reference repo's lockfile is untrusted input
+ * that has to be schema-checked before it is read (#563).
+ */
+// ponytail: `format: date-time` is not checked, and neither are composition
+// keywords — none appear in either schema. Reach for ajv the day one does.
+export function validateAgainstSchema(value, schema, path = '$') {
+    const errors = [];
+    if (schema.enum && !schema.enum.includes(value)) {
+        errors.push(`${path}: ${JSON.stringify(value)} is not one of ${schema.enum.join(', ')}`);
+    }
+    if (schema.type === 'array') {
+        if (!Array.isArray(value))
+            return [`${path}: expected array`];
+        if (schema.items) {
+            for (const [i, item] of value.entries()) {
+                errors.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+            }
+        }
+        return errors;
+    }
+    if (schema.type === 'object') {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return [`${path}: expected object`];
+        }
+        const obj = value;
+        for (const key of schema.required ?? []) {
+            if (!(key in obj))
+                errors.push(`${path}: missing required property "${key}"`);
+        }
+        for (const [key, child] of Object.entries(obj)) {
+            const property = schema.properties?.[key];
+            if (property)
+                errors.push(...validateAgainstSchema(child, property, `${path}.${key}`));
+            else if (schema.additionalProperties === false) {
+                errors.push(`${path}: unknown property "${key}"`);
+            }
+            else if (typeof schema.additionalProperties === 'object') {
+                errors.push(...validateAgainstSchema(child, schema.additionalProperties, `${path}.${key}`));
+            }
+        }
+        return errors;
+    }
+    if (schema.type === 'integer') {
+        if (!Number.isInteger(value))
+            errors.push(`${path}: expected integer`);
+    }
+    else if (schema.type && typeof value !== schema.type) {
+        errors.push(`${path}: expected ${schema.type}, got ${typeof value}`);
+    }
+    if (schema.minLength !== undefined &&
+        typeof value === 'string' &&
+        value.length < schema.minLength) {
+        errors.push(`${path}: shorter than minLength ${schema.minLength}`);
+    }
+    return errors;
+}

package/dist/cli/utils/lockfile.js

@@ -16,7 +16,10 @@ export const LEGACY_LOCKFILE_NAME = `.${LEGACY_TOOL_NAME}.json`;
 // migrated to v2 on read, defaulting language to 'js'.
 // v3 added `assets` — the pristine hash of each copied preset (#428). Older
 // files carry no hashes, which reads as "not tracked", never as drift.
-export const LOCKFILE_VERSION = 3;
+// v4 split the file into two subtrees with documented ownership (#559):
+// `record` (tool-written, stamped) and `rules` (human-written, unstamped).
+// Nothing was renamed or dropped — the flat v3 fields just moved into them.
+export const LOCKFILE_VERSION = 4;
 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).
@@ -48,10 +51,10 @@ export function lockfileSchema() {
         $schema: 'https://json-schema.org/draft/2020-12/schema',
         $id: LOCKFILE_SCHEMA_URL,
         title: 'Lockfile',
-        description: `${LOCKFILE_NAME} — the committed record of what @rtorcato/repo-tooling set up in this repo. Written by \`setup\` and \`fix\`, read by \`doctor\`.`,
+        description: `${LOCKFILE_NAME} — two documents sharing one file: \`record\` is written by @rtorcato/repo-tooling (\`setup\` and \`fix\`) and stamped with provenance; \`rules\` is written by humans, reviewed in PRs, and never stamped. Both are read by \`doctor\`.`,
         type: 'object',
         additionalProperties: false,
-        required: ['version', 'config', 'writtenBy', 'writtenAt'],
+        required: ['version', 'record'],
         properties: {
             $schema: {
                 type: 'string',
@@ -59,78 +62,93 @@ export function lockfileSchema() {
             },
             version: {
                 type: 'integer',
-                description: `Lockfile format version (current: ${LOCKFILE_VERSION}). v2 added config.language, v3 added assets; older files are migrated on read.`,
+                description: `Lockfile format version (current: ${LOCKFILE_VERSION}). v2 added config.language, v3 added assets, v4 split the file into record/rules subtrees; older files are migrated on read.`,
             },
-            config: {
-                ...projectConfigSchema,
-                description: 'The resolved setup configuration this repo was scaffolded or audited with.',
-            },
-            assets: {
-                type: 'object',
-                additionalProperties: { type: 'string' },
-                description: "Preset name → sha256 of the asset's pristine content at copy time. Lets doctor tell a deliberate local fork (file differs from this hash) from a copy the package has since moved past (file still matches, shipped asset doesn't). A preset with no entry is untracked, never drifted.",
-            },
-            aiLoop: {
+            record: {
                 type: 'object',
                 additionalProperties: false,
-                description: 'Settings for the ai-issue-loop skills. Repo-scoped on purpose: committed here they travel with the repo and survive a new laptop.',
+                required: ['config', 'writtenBy', 'writtenAt'],
+                description: 'The tool-written record of what setup/fix last did. Only the tool writes here — the writtenBy/writtenAt stamps are provenance claims about exactly this subtree.',
                 properties: {
-                    agentUser: {
+                    config: {
+                        ...projectConfigSchema,
+                        description: 'The resolved setup configuration this repo was scaffolded or audited with.',
+                    },
+                    assets: {
+                        type: 'object',
+                        additionalProperties: { type: 'string' },
+                        description: "Preset name → sha256 of the asset's pristine content at copy time. Lets doctor tell a deliberate local fork (file differs from this hash) from a copy the package has since moved past (file still matches, shipped asset doesn't). A preset with no entry is untracked, never drifted.",
+                    },
+                    writtenBy: {
                         type: 'string',
-                        description: 'Login that in-flight work is assigned to, so `assignee` says whose turn it is. Must be an assignable collaborator; the skills verify that at runtime.',
+                        description: 'Package name and version that last wrote the record subtree.',
+                    },
+                    writtenAt: {
+                        type: 'string',
+                        format: 'date-time',
+                        description: 'ISO 8601 timestamp of the last record write.',
                     },
                 },
             },
-            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: {
+            rules: {
                 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.",
+                description: "The human-written ruleset: the repo's stated intent, edited by hand and reviewed in PRs. The tool carries it forward verbatim on every write and never stamps it.",
                 properties: {
-                    recommended: {
+                    aiLoop: {
+                        type: 'object',
+                        additionalProperties: false,
+                        description: 'Settings for the ai-issue-loop skills. Repo-scoped on purpose: committed here they travel with the repo and survive a new laptop.',
+                        properties: {
+                            agentUser: {
+                                type: 'string',
+                                description: 'Login that in-flight work is assigned to, so `assignee` says whose turn it is. Must be an assignable collaborator; the skills verify that at runtime.',
+                            },
+                        },
+                    },
+                    requiredSkills: {
                         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.',
+                        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.',
+                    },
                 },
             },
-            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.',
-            },
-            writtenAt: {
-                type: 'string',
-                format: 'date-time',
-                description: 'ISO 8601 timestamp of the last write.',
-            },
         },
     };
 }
@@ -139,17 +157,53 @@ export function lockfileSchema() {
  * current version, so a newer-than-supported file is left as-is for
  * checkLockfile to flag. `version` stays at the on-disk value — bumping it here
  * hid every older file from doctor's older-than-current check (#531); the write
- * path stamps LOCKFILE_VERSION anyway, so the file is v3 next time it's saved.
+ * path stamps LOCKFILE_VERSION anyway, so the file is v4 next time it's saved.
+ *
+ * v1–v3 are flat: nest the fields into record/rules (#559), default language
+ * to 'js' (v1, #140) and assets to {} (pre-v3, #428). Nothing is renamed.
  */
-function migrate(lock) {
-    if (lock.version >= LOCKFILE_VERSION)
-        return lock;
+function migrate(raw) {
+    if (raw.version >= LOCKFILE_VERSION)
+        return raw;
+    const flat = raw;
+    const rules = {
+        ...(flat.aiLoop ? { aiLoop: flat.aiLoop } : {}),
+        ...(flat.requiredSkills ? { requiredSkills: flat.requiredSkills } : {}),
+        ...(flat.mcp ? { mcp: flat.mcp } : {}),
+        ...(flat.exceptions ? { exceptions: flat.exceptions } : {}),
+    };
     return {
-        ...lock,
-        config: { language: 'js', ...lock.config },
-        assets: lock.assets ?? {},
+        ...(flat.$schema ? { $schema: flat.$schema } : {}),
+        version: flat.version,
+        record: {
+            config: { language: 'js', ...flat.config },
+            assets: flat.assets ?? {},
+            writtenBy: flat.writtenBy,
+            writtenAt: flat.writtenAt,
+        },
+        ...(Object.keys(rules).length > 0 ? { rules } : {}),
     };
 }
+/**
+ * Normalize already-parsed JSON into a Lockfile, or null when it isn't one.
+ * Split out of readLockfile so a lockfile fetched from somewhere other than the
+ * filesystem — a reference repo, over `gh` — goes through the same migration
+ * before anything reads it (#563).
+ */
+export function parseLockfile(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const obj = raw;
+    if (typeof obj.version !== 'number')
+        return null;
+    // v4+ keeps config under `record`; v1–v3 keep it at the top level (#559).
+    const config = obj.version >= LOCKFILE_VERSION
+        ? obj.record?.config
+        : obj.config;
+    if (typeof config !== 'object' || config === null)
+        return null;
+    return migrate(obj);
+}
 export async function readLockfile(dir) {
     let filepath = path.join(dir, LOCKFILE_NAME);
     if (!(await fs.pathExists(filepath))) {
@@ -160,15 +214,7 @@ export async function readLockfile(dir) {
         filepath = legacy;
     }
     try {
-        const raw = (await fs.readJson(filepath));
-        if (typeof raw !== 'object' || raw === null)
-            return null;
-        const obj = raw;
-        if (typeof obj.version !== 'number')
-            return null;
-        if (typeof obj.config !== 'object' || obj.config === null)
-            return null;
-        return migrate(obj);
+        return parseLockfile((await fs.readJson(filepath)));
     }
     catch {
         return null;
@@ -186,21 +232,21 @@ export async function writeLockfile(dir, config, assets) {
     }
     // One read, because everything not rebuilt from `config` has to be carried
     // forward explicitly — this object is constructed from scratch, so any key
-    // not named here is dropped by the next `fix lockfile`.
+    // not named here is dropped by the next `fix lockfile`. `rules` rides along
+    // verbatim: it is the human's subtree, and the stamp says nothing about it.
     const existing = await readLockfile(dir);
-    const carried = assets ?? existing?.assets;
+    const carried = assets ?? existing?.record.assets;
     const filepath = path.join(dir, LOCKFILE_NAME);
     const lockfile = {
         $schema: LOCKFILE_SCHEMA_URL,
         version: LOCKFILE_VERSION,
-        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(),
+        record: {
+            config,
+            ...(carried && Object.keys(carried).length > 0 ? { assets: carried } : {}),
+            writtenBy: `@rtorcato/repo-tooling@${packageJson.version}`,
+            writtenAt: new Date().toISOString(),
+        },
+        ...(existing?.rules ? { rules: existing.rules } : {}),
     };
     await fs.writeJson(filepath, lockfile, { spaces: 2 });
     // Migrate a pre-rename repo to the new name: now that the canonical file is
@@ -218,7 +264,7 @@ export async function updateLockfileConfig(dir, patch) {
     const existing = await readLockfile(dir);
     if (!existing)
         return false;
-    const merged = { ...existing.config, ...patch };
+    const merged = { ...existing.record.config, ...patch };
     await writeLockfile(dir, merged);
     return true;
 }
@@ -232,6 +278,6 @@ export async function recordAssetHash(dir, preset, hash) {
     const existing = await readLockfile(dir);
     if (!existing)
         return false;
-    await writeLockfile(dir, existing.config, { ...existing.assets, [preset]: hash });
+    await writeLockfile(dir, existing.record.config, { ...existing.record.assets, [preset]: hash });
     return true;
 }

package/dist/cli/utils/reference-rules.js

@@ -0,0 +1,125 @@
+import { realGhExec } from '../../base/github-settings.js';
+import { validateAgainstSchema } from './json-schema.js';
+import { LOCKFILE_NAME, lockfileSchema, parseLockfile, readLockfile, } from './lockfile.js';
+/**
+ * Rules are per-repo (#563): there is no guideline package, so sharing a
+ * guideline means pointing at another repo. This module is the one fetcher both
+ * halves of that share — `doctor --rules-from` reads a reference repo's rules to
+ * report differences, and `setup --from` reads the same file to seed the wizard.
+ *
+ * The reference is untrusted input from end to end: the `owner/repo` string is
+ * shape-checked before it reaches an API path, the response is size-capped, and
+ * the JSON is validated against the published schema before a single field is
+ * read. Nothing here ever writes, and nothing is ever applied.
+ */
+/**
+ * `owner/repo`. The injection boundary — the reference is interpolated into the
+ * gh API path below, so anything with a slash, `..` or a shell metacharacter in
+ * it has to be rejected here rather than defended against later.
+ */
+const REFERENCE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Generous by four orders of magnitude — a real lockfile is ~1 KB. This is not a
+ * tuning knob, it is the "huge file" guard: the response is fully buffered by the
+ * time we see it, so the cap stops us parsing and diffing a repo's 40 MB joke.
+ */
+const MAX_BYTES = 128 * 1024;
+/**
+ * The GitHub arm of the fetch. Another forge is a second function of this shape
+ * dispatched from fetchReferenceLockfile — everything downstream (size cap,
+ * parse, schema validation, diff) is forge-agnostic and already shared.
+ */
+async function fetchFromGitHub(reference, exec) {
+    const gh = exec ?? ((args, stdin) => realGhExec(args, stdin));
+    // `Accept: raw` returns the file itself rather than the base64-in-JSON envelope.
+    const r = await gh([
+        'api',
+        `repos/${reference}/contents/${LOCKFILE_NAME}`,
+        '-H',
+        'Accept: application/vnd.github.raw',
+    ]);
+    if (r.ok)
+        return { ok: true, text: r.stdout };
+    if (/HTTP 404/.test(r.stderr)) {
+        return { ok: false, reason: `${reference} has no ${LOCKFILE_NAME} (or is not visible to you)` };
+    }
+    const detail = r.stderr.trim().split('\n').pop() ?? 'gh failed';
+    return { ok: false, reason: `could not read ${reference}: ${detail}` };
+}
+function parseReference(reference, text) {
+    if (Buffer.byteLength(text) > MAX_BYTES) {
+        return {
+            ok: false,
+            reason: `${reference}'s ${LOCKFILE_NAME} is larger than ${MAX_BYTES} bytes`,
+        };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: `${reference}'s ${LOCKFILE_NAME} is not valid JSON` };
+    }
+    // Migrate first, then validate: an older reference is flat on disk and would
+    // fail the current schema for a reason that says nothing about its rules.
+    const lockfile = parseLockfile(raw);
+    if (!lockfile) {
+        return { ok: false, reason: `${reference}'s ${LOCKFILE_NAME} is not a recognisable lockfile` };
+    }
+    const errors = validateAgainstSchema(lockfile, lockfileSchema());
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: `${reference}'s ${LOCKFILE_NAME} fails the published schema: ${errors.slice(0, 3).join('; ')}`,
+        };
+    }
+    return { ok: true, lockfile };
+}
+export async function fetchReferenceLockfile(reference, exec) {
+    if (!REFERENCE.test(reference)) {
+        return { ok: false, reason: `"${reference}" is not an owner/repo reference` };
+    }
+    const fetched = await fetchFromGitHub(reference, exec);
+    if (!fetched.ok)
+        return fetched;
+    return parseReference(reference, fetched.text);
+}
+/**
+ * The comparable half of a lockfile: the resolved config plus the human-written
+ * rules. `assets` hashes and the `writtenBy`/`writtenAt` stamps are excluded on
+ * purpose — they differ between any two repos by construction, so diffing them
+ * would bury every difference that means something.
+ */
+function rulesView(lock) {
+    return { config: lock.record.config, ...(lock.rules ?? {}) };
+}
+function flatten(value, prefix = '', out = new Map()) {
+    // Arrays are leaves: `requiredSkills` differing by one entry is one difference
+    // about the list, not a per-index report that shifts when the order does.
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            flatten(child, prefix ? `${prefix}.${key}` : key, out);
+        }
+        return out;
+    }
+    out.set(prefix, value);
+    return out;
+}
+export function diffRules(local, reference) {
+    const mine = local ? flatten(rulesView(local)) : new Map();
+    const theirs = flatten(rulesView(reference));
+    return [...new Set([...mine.keys(), ...theirs.keys()])]
+        .sort()
+        .filter((p) => JSON.stringify(mine.get(p)) !== JSON.stringify(theirs.get(p)))
+        .map((p) => ({ path: p, local: mine.get(p), reference: theirs.get(p) }));
+}
+export async function compareRulesWithReference(dir, reference, exec) {
+    const result = await fetchReferenceLockfile(reference, exec);
+    if (!result.ok)
+        return { reference, compared: false, reason: result.reason };
+    return {
+        reference,
+        compared: true,
+        differences: diffRules(await readLockfile(dir), result.lockfile),
+    };
+}

package/dist/languages/js/fixers.js

@@ -864,10 +864,10 @@ export const FIXERS = [
                 console.error(chalk.yellow('   no package.json found — skipping'));
                 return { filesWritten: [] };
             }
-            const config = lock ? lock.config : inferProjectConfig(pkg);
+            const config = lock ? lock.record.config : inferProjectConfig(pkg);
             // Recorded hashes win: they capture the pristine content at copy time,
             // which a byte-match against today's shipped asset can only approximate.
-            const assets = { ...(await identifiablePresetHashes(targetDir)), ...lock?.assets };
+            const assets = { ...(await identifiablePresetHashes(targetDir)), ...lock?.record.assets };
             await writeLockfile(targetDir, config, assets);
             return { filesWritten: [LOCKFILE_NAME] };
         },

package/package.json

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

@@ -219,8 +219,9 @@ behaves exactly as it did before this existed.
 
 ```bash
 # Repo config first — committed, so it travels with the repo and survives a new
-# machine. `AI_LOOP_AGENT` overrides it for a repo with no lockfile.
-AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
+# machine. `AI_LOOP_AGENT` overrides it for a repo with no lockfile. The flat
+# `.aiLoop` fallback reads a pre-v4 lockfile that hasn't migrated yet (#559).
+AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.rules.aiLoop.agentUser // .aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
 # A typo would fail every `gh` edit for the whole tick, so prove it is assignable
 # once, here. 204 = yes, 404 = no; push access is what qualifies an account.
 [ -n "$AGENT_USER" ] && { gh api "repos/$OWNER_REPO/assignees/$AGENT_USER" --silent 2>/dev/null || {
@@ -235,7 +236,7 @@ being that assignment quietly stops. In `.repo-tooling.json` it is committed,
 reviewable, and carried forward by `fix lockfile`:
 
 ```json
-{ "aiLoop": { "agentUser": "your-bot-account" } }
+{ "rules": { "aiLoop": { "agentUser": "your-bot-account" } } }
 ```
 
 Every later use is `${AGENT_USER:+--add-assignee "$AGENT_USER"}`, which expands

package/skills/ai-workflow/SKILL.md

@@ -53,7 +53,7 @@ git -C "$ROOT" fetch --prune
 # Optional: the account in-flight work is assigned to, so `assignee` says whose
 # turn it is. Unset → nothing below assigns, exactly as before. See the
 # ai-issue-loop skill's Pass 0 for why this is repo config rather than an env var.
-AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
+AGENT_USER="${AI_LOOP_AGENT:-$(jq -r '.rules.aiLoop.agentUser // .aiLoop.agentUser // empty' "$ROOT/.repo-tooling.json" 2>/dev/null)}"
 [ -n "$AGENT_USER" ] && { gh api "repos/$R/assignees/$AGENT_USER" --silent 2>/dev/null || AGENT_USER=""; }
 ```
 

package/skills/repo-tooling/SKILL.md

@@ -30,7 +30,7 @@ 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
+- `declared` — a real deviation the repo's `.repo-tooling.json` `rules.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`.