@rtorcato/repo-tooling 3.27.0 → 3.29.0

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/base/git-identity.js

@@ -149,3 +149,72 @@ export async function checkGitIdentity(dir, exec) {
         hint: HINT,
     };
 }
+const HISTORY_CHECK = 'Git author history';
+/**
+ * Bounded so doctor stays cheap on every invocation; the output always names
+ * how many commits were actually examined so "0 found" is never read as "all
+ * history is clean".
+ */
+export const HISTORY_SCAN_LIMIT = 200;
+/** How many offending commits to name; the count carries the rest. */
+const HISTORY_SAMPLE = 3;
+const HISTORY_HINT = 'These commits are already made: the address can never be verified as a secondary email, so they cannot be re-linked to a forge account without a history rewrite (#327). Fix the identity going forward (see the Git identity check) and treat the history as recorded loss.';
+/**
+ * The retrospective half of `checkGitIdentity` (#557): that check reads the
+ * identity the *next* commit will use, this one scans recent history for
+ * commits already made with a bad one. Same classifier — `classifyGitEmail` —
+ * so the two can never drift. Same STATUS reasoning too: history is not
+ * something the repo's author can fix by editing the repo, so a finding is
+ * `optional-missing`, never `drift`/`missing`, and the exit code is untouched.
+ * Detection only — there is deliberately no fixer, because the only "fix" is a
+ * history rewrite no tool should offer unprompted.
+ */
+export async function checkGitIdentityHistory(dir, exec) {
+    if (!(await fs.pathExists(path.join(dir, '.git')))) {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'not a git repository' };
+    }
+    if (process.env.CI) {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'skipped on CI' };
+    }
+    const git = exec ?? ((args) => realGitExec(args, dir));
+    // A shallow clone has almost no history; scanning its stub and reporting
+    // "0 found" would be a false all-clear.
+    if ((await git(['rev-parse', '--is-shallow-repository'])) === 'true') {
+        return {
+            check: HISTORY_CHECK,
+            status: 'ok',
+            detail: 'shallow clone — commit history is not available to scan',
+        };
+    }
+    // %h %ae: abbreviated hash + author email, one commit per line.
+    const log = await git(['log', `-${HISTORY_SCAN_LIMIT}`, '--format=%h %ae']);
+    if (log === null || log === '') {
+        return { check: HISTORY_CHECK, status: 'ok', detail: 'no commits to scan' };
+    }
+    const commits = log.split('\n').map((line) => {
+        const sp = line.indexOf(' ');
+        return { hash: line.slice(0, sp), email: line.slice(sp + 1) };
+    });
+    const bad = commits.filter(({ email }) => {
+        const verdict = classifyGitEmail(email);
+        return verdict === 'placeholder' || verdict === 'generated';
+    });
+    const scanned = `the last ${commits.length} commit${commits.length === 1 ? '' : 's'}`;
+    if (bad.length === 0) {
+        return {
+            check: HISTORY_CHECK,
+            status: 'ok',
+            detail: `no placeholder or machine-derived author emails in ${scanned}`,
+        };
+    }
+    const sample = bad
+        .slice(0, HISTORY_SAMPLE)
+        .map(({ hash, email }) => `${hash} (${email})`)
+        .join(', ');
+    return {
+        check: HISTORY_CHECK,
+        status: 'optional-missing',
+        detail: `${bad.length} of ${scanned} carry a placeholder or machine-derived author email — e.g. ${sample}`,
+        hint: HISTORY_HINT,
+    };
+}

package/dist/cli/commands/doctor.js

@@ -16,7 +16,7 @@ import { checkAgentUser } from '../../base/agent-user.js';
 import { checkGitHubSettings } from '../../base/github-settings.js';
 import { checkLoopLabels } from '../../base/labels.js';
 import { checkMilestones } from '../../base/milestones.js';
-import { checkGitIdentity } from '../../base/git-identity.js';
+import { checkGitIdentity, checkGitIdentityHistory } from '../../base/git-identity.js';
 import { checkCopiedAssets } from '../utils/copied-assets.js';
 import { LOCKFILE_VERSION, readLockfile } from '../utils/lockfile.js';
 import { declinedInLock, getFixTargetForCheck } from './fix-targets.js';
@@ -136,7 +136,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 +164,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));
@@ -202,6 +204,8 @@ async function runBaseChecks(dir, lock, opts) {
     results.push(await checkCopiedAssets(dir));
     results.push(await checkNestedLanguages(dir, opts.language));
     results.push(await checkGitIdentity(dir));
+    // The retrospective half (#557): commits already made with a bad identity.
+    results.push(await checkGitIdentityHistory(dir));
     results.push(await checkEditorConfig(dir));
     results.push(await checkFile(dir, COMMITLINT_FILE_CHECK));
     if (opts.hooks) {
@@ -219,7 +223,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));
@@ -229,13 +233,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));

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

@@ -76,10 +76,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) {

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/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: 'Package name and version that last wrote the record subtree.',
+                    },
+                    writtenAt: {
                         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.',
+                        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,15 +157,31 @@ 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 } : {}),
     };
 }
 export async function readLockfile(dir) {
@@ -166,7 +200,11 @@ export async function readLockfile(dir) {
         const obj = raw;
         if (typeof obj.version !== 'number')
             return null;
-        if (typeof obj.config !== 'object' || obj.config === 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);
     }
@@ -186,21 +224,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 +256,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 +270,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/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.27.0",
+	"version": "3.29.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`.