@rmyndharis/aimhooman 0.1.7 → 0.2.0

package/bin/aimhooman.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
-import { chmodSync, lstatSync, readdirSync, readFileSync, rmdirSync, rmSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { chmodSync, lstatSync, readdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { GIT_TIMEOUT_MS } from '../src/git-environment.mjs';
@@ -9,20 +10,23 @@ import { exitCode, human, jsonReport, visible } from '../src/report.mjs';
 import {
     GitRevisionError,
     gitConfig,
+    ignoredByPatterns,
     introducedCommits,
     openRepo,
     readCommitPath,
     readStagedPath,
     stagedPaths,
     stagedRenameSources,
+    stagedTreeSha,
     unstagePaths,
     withIndexFromTree,
 } from '../src/gitx.mjs';
 import { loadConfig, loadOverrides, loadProjectPolicy, normalizeOverrideTarget, saveConfig, saveOverrides } from '../src/state.mjs';
-import { applyExclude, inspectExclude, patternsForRules, removeExclude } from '../src/exclude.mjs';
+import { applyExclude, inspectExclude, managedPatterns, patternsForRules, removeExclude } from '../src/exclude.mjs';
 import { effectiveHooksDir, hookDiagnostics, installHooks, installGlobalHooks, uninstallGlobalHooks, globalHooksDir, installedHooks, remainingDispatchers, uninstallHooks, unrestoredChainedBackups } from '../src/githooks.mjs';
 import { ArgumentError, parseArguments } from '../src/args.mjs';
 import { engineForPolicy, scanGitTarget, scanMessage } from '../src/scan-target.mjs';
+import { DEFAULT_SCAN_LIMITS } from '../src/scan-session.mjs';
 import { resolvePolicy } from '../src/policy-resolver.mjs';
 import { atomicWrite, withLock } from '../src/atomic-write.mjs';
 import { commitParents, resolveCommit } from '../src/history-scan.mjs';
@@ -118,6 +122,22 @@ function configuredEngine(profile, repo) {
 
 function main(argv) {
     const [cmd, ...rest] = argv;
+    // Subcommand-level --help: `aimhooman override --help` (or `init -h`, etc.)
+    // previously fell into the subcommand's strict argument parser, which rejects
+    // --help as an unknown option and exits 20. Recognise a leading help flag on
+    // any real subcommand and route to usage() instead, so help works everywhere.
+    // The top-level help forms (cmd itself is help/--help/-h) are handled in the
+    // switch below.
+    const SUBCOMMAND_HELP_FLAGS = new Set(['--help', '-h', 'help']);
+    const knownSubcommands = new Set([
+        'check', 'audit', 'scan', 'precommit', 'commitmsg', 'refcheck', 'init',
+        'status', 'explain', 'allow', 'deny', 'override', 'review',
+        'policy-review', 'fix', 'doctor', 'uninstall',
+    ]);
+    if (knownSubcommands.has(cmd) && rest.length && SUBCOMMAND_HELP_FLAGS.has(rest[0])) {
+        usage();
+        return 0;
+    }
     switch (cmd) {
         case 'check':
             return cmdCheck(rest);
@@ -197,8 +217,11 @@ function emitDiagnostics(diagnostics = []) {
 
 function incompleteMessage(scan) {
     const reasons = scan.stats?.skipped || {};
+    // Each count is how many items were skipped, not the limit that fired:
+    // "(size-limit=1)" read as a one-byte budget. Name the noun so the number
+    // cannot be mistaken for the budget it tripped.
     const skipped = Object.entries(reasons)
-        .map(([reason, count]) => `${reason}=${count}`)
+        .map(([reason, count]) => `${reason}=${count} ${skipCountNoun(reason, count)}`)
         .join(', ');
     // Every other reason is a size or budget the caller can shrink. A pack that
     // will not compile is not, and the warning above already names the file and
@@ -212,7 +235,7 @@ function incompleteMessage(scan) {
         : budgeted
             ? 'reduce the target, or raise AIMHOOMAN_MAX_FILE_BYTES / AIMHOOMAN_MAX_TOTAL_BYTES, and retry'
             : 'reduce the target or limits and retry';
-    let message = `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    let message = `aimhooman: scan incomplete${skipped ? ` (skipped: ${skipped})` : ''}; ${hint}\n`;
     const skippedPaths = scan.stats?.skippedPaths || {};
     const pathLines = [];
     for (const [reason, entries] of Object.entries(skippedPaths)) {
@@ -225,6 +248,17 @@ function incompleteMessage(scan) {
     return message + pathLines.join('');
 }
 
+// Most skip reasons tally files; the three below tally something else, so the
+// noun travels with the reason instead of reading "local-pack-error=1 file".
+function skipCountNoun(reason, count) {
+    const noun = {
+        'finding-limit': 'finding',
+        'local-input-limit': 'input',
+        'local-pack-error': 'pack',
+    }[reason] || 'file';
+    return `${noun}${count === 1 ? '' : 's'}`;
+}
+
 function formatBytes(bytes) {
     if (bytes == null || bytes < 0) return '?';
     if (bytes < 1024) return `${bytes} B`;
@@ -311,6 +345,81 @@ function dispatchHooksChanged(repo, profile) {
     return true;
 }
 
+// W5 pre-commit/commit-msg marker dedup. pre-commit writes a marker after a
+// clean, complete scan of the staged tree; commit-msg reads it and skips its
+// duplicate ~170ms tree scan when the staged tree sha, profile, and
+// completeness all match. The marker lives in stateDir (gitignored plumbing).
+// It is self-invalidating: any index mutation between the two hooks changes the
+// tree sha, so a stale marker never matches. A missing/corrupt/mismatched
+// marker makes commit-msg fall back to the full scan, so this is purely an
+// optimization and never weakens the guard.
+const PRECOMMIT_CLEAN_VERSION = 1;
+function precommitCleanPath(repo) {
+    return join(repo.stateDir, 'precommit-clean.json');
+}
+function recordPrecommitClean(repo, profile) {
+    let treeSha;
+    try {
+        treeSha = stagedTreeSha(repo);
+    } catch {
+        return; // cannot compute the sha → do not record; commit-msg will scan
+    }
+    try {
+        writeFileSync(precommitCleanPath(repo), JSON.stringify({
+            version: PRECOMMIT_CLEAN_VERSION,
+            tree: treeSha,
+            profile,
+            complete: true,
+        }));
+    } catch {
+        // best effort; a missing marker just means commit-msg scans normally
+    }
+}
+function precommitCleanMatches(repo, treeSha, profile) {
+    let marker;
+    try {
+        marker = JSON.parse(readFileSync(precommitCleanPath(repo), 'utf8'));
+    } catch {
+        return false; // missing/corrupt → fall back to full scan
+    }
+    return marker?.version === PRECOMMIT_CLEAN_VERSION
+        && marker.complete === true
+        && marker.tree === treeSha
+        && marker.profile === profile;
+}
+
+// F-E1: the prevention layer keeps AI artifacts out of `git status`, which
+// also keeps their exclusion silent — a `git add .` never tells the developer
+// the chat log did not make the commit. Name the artifacts once per set
+// change. The worktree walk is pathspec-pruned to the anchored managed
+// patterns (~15ms; a bare ignored-listing costs ~150ms on a large tree), so
+// `**/`-prefixed duplicates are skipped: nested artifacts still get excluded,
+// they just do not get the notice. Informational only — it must never change
+// an exit code, so every failure inside degrades to silence.
+const IGNORED_NOTICE_VERSION = 1;
+function noticeIgnoredArtifacts(repo) {
+    try {
+        const patterns = managedPatterns(repo.excludeFile)
+            .filter((pattern) => !pattern.startsWith('**/'));
+        if (!patterns.length) return;
+        const paths = ignoredByPatterns(repo, patterns).sort();
+        if (!paths.length) return;
+        const hash = createHash('sha256').update(paths.join('\0')).digest('hex');
+        const statePath = join(repo.stateDir, 'ignored-notice.json');
+        let previous = null;
+        try { previous = JSON.parse(readFileSync(statePath, 'utf8')); } catch { /* first run or corrupt state */ }
+        if (previous?.version === IGNORED_NOTICE_VERSION && previous.hash === hash) return;
+        writeFileSync(statePath, JSON.stringify({ version: IGNORED_NOTICE_VERSION, hash }));
+        const shown = paths.slice(0, 5);
+        const more = paths.length - shown.length;
+        process.stderr.write(
+            `aimhooman: ${paths.length} AI artifact(s) present locally are kept out of commits: `
+            + `${shown.map(visible).join(', ')}${more ? `, and ${more} more` : ''} `
+            + "(they stay on disk; 'git status --ignored' lists them; shown once per set change)\n"
+        );
+    } catch { /* informational only */ }
+}
+
 function cmdPrecommit(args) {
     parseNoArguments(args);
     const repo = tryRepo();
@@ -336,6 +445,14 @@ function cmdPrecommit(args) {
             process.stderr.write(incompleteMessage(scan));
             return 31;
         }
+        // W5 marker dedup: record that this staged tree scanned clean so the
+        // upcoming commit-msg hook can skip its duplicate tree scan. The tree
+        // sha is the same value the commit-msg dispatcher computes via
+        // `git write-tree`; the index is unchanged on this no-block path, so the
+        // sha is stable. A missing/stale/mismatched marker makes commit-msg
+        // fall back to the full scan, so this is purely an optimization.
+        recordPrecommitClean(repo, profile);
+        noticeIgnoredArtifacts(repo);
         return profile === 'strict' && reviews.length ? 11 : 0;
     }
     if (profile === 'strict') {
@@ -412,6 +529,7 @@ function cmdPrecommit(args) {
     // not. The request was to commit the artifact, not to stamp the history with
     // its message and no content.
     if (emptied) return 10;
+    if (scan.complete) noticeIgnoredArtifacts(repo);
     return scan.complete ? 0 : 31;
 }
 
@@ -463,7 +581,14 @@ function cmdCommitmsg(args) {
     try {
         const checked = againstWouldBeTree(() => ({
             message: scanMessage(repo, text, { target: 'staged' }),
-            tree: options.tree ? scanGitTarget(repo, { kind: 'staged', limits }) : null,
+            // W5 marker dedup: if pre-commit already scanned this exact tree
+            // clean (matching sha + profile + complete), skip the duplicate
+            // ~170ms tree scan. The marker is self-invalidating (any index
+            // mutation changes the tree sha), and a missing/stale/mismatched
+            // marker falls back to the full scan, so this is safe.
+            tree: options.tree && precommitCleanMatches(repo, options.tree, hookProfile)
+                ? null
+                : (options.tree ? scanGitTarget(repo, { kind: 'staged', limits }) : null),
         }));
         scan = checked.message;
         treeScan = checked.tree;
@@ -672,6 +797,15 @@ function cmdRefcheck(args) {
             process.stderr.write(human(scan.findings, tone()));
             if (!scan.complete) process.stderr.write(incompleteMessage(scan));
             process.stderr.write(`aimhooman: proposed commit ${revision} was rejected before refs changed\n`);
+            // The vetoed commit stays in the object store: the ref never
+            // moved, but the bytes — including whatever triggered the block —
+            // are still on disk. Whether gc collects it depends on other refs,
+            // so phrase the cleanup as conditional; rotating an exposed secret
+            // stays the operator's call either way.
+            process.stderr.write(
+                `aimhooman: note: the rejected commit object remains in the local object store; `
+                + "if nothing else references it, 'git gc --prune=now' removes it when you are done inspecting\n"
+            );
             return code;
         }
     }
@@ -766,8 +900,9 @@ function cmdInit(args) {
             profile: { names: ['--profile'], type: 'string', choices: [...PROFILES] },
             global: { names: ['--global'], type: 'boolean' },
             yes: { names: ['--yes'], type: 'boolean' },
+            grandfatherSecrets: { names: ['--grandfather-secrets'], type: 'boolean' },
         },
-        conflicts: [['profile', 'global']],
+        conflicts: [['profile', 'global'], ['grandfatherSecrets', 'global']],
         maxPositionals: 0,
     });
     if (rejectUnsupportedGit()) return 20;
@@ -777,166 +912,240 @@ function cmdInit(args) {
             return 20;
         }
         return withLock(join(globalHooksDir(), 'lifecycle.lock'), () => {
-        const aimDir = globalHooksDir();
-        let existing = '';
+            const aimDir = globalHooksDir();
+            let existing = '';
+            try {
+                existing = execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+            } catch { /* unset */ }
+            if (existing && existing !== aimDir) {
+                console.error(
+                    `aimhooman: core.hooksPath is already set to '${existing}'; refusing to overwrite. ` +
+                    'Unset it (git config --global --unset core.hooksPath) or choose a different setup.'
+                );
+                return 20;
+            }
+            // A --system hooksPath would be shadowed by the --global write below and
+            // could silently disable a system-wide hook manager, so refuse here too.
+            let systemHooksPath = '';
+            try {
+                systemHooksPath = execFileSync('git', ['config', '--system', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+            } catch { /* unset or no system config */ }
+            if (systemHooksPath) {
+                console.error(
+                    `aimhooman: core.hooksPath is set at --system scope to '${systemHooksPath}'; ` +
+                    'a --global install would shadow it. Unset it or choose a different setup.'
+                );
+                return 20;
+            }
+            const localRepo = tryRepo();
+            const localHooksPath = localRepo ? gitConfigAtScope(localRepo.root, '--local', 'core.hooksPath') : '';
+            if (localHooksPath) {
+                console.error(`aimhooman: warning: this repository has local core.hooksPath="${localHooksPath}", which overrides the global guard here`);
+            }
+            const hookSnapshots = REQUIRED_GIT_HOOKS
+                .map((name) => snapshotFile(join(aimDir, name)));
+            let rep;
+            try {
+                rep = installGlobalHooks(CLI_PATH);
+                if (rep.skipped?.length) {
+                    for (const warning of rep.warnings || []) console.error(`aimhooman: ${warning}`);
+                    console.error('aimhooman: global hook installation aborted; core.hooksPath was not changed');
+                    return 20;
+                }
+                execFileSync('git', ['config', '--global', 'core.hooksPath', rep.dir], { timeout: GIT_TIMEOUT_MS });
+            } catch (error) {
+                const rollbackFailures = [];
+                for (const snapshot of hookSnapshots.reverse()) {
+                    try { restoreSnapshot(snapshot); }
+                    catch (rollbackError) {
+                        rollbackFailures.push(`${snapshot.path}: ${rollbackError.message}`);
+                    }
+                }
+                try {
+                    if (existing) execFileSync('git', ['config', '--global', 'core.hooksPath', existing], { timeout: GIT_TIMEOUT_MS });
+                    else execFileSync('git', ['config', '--global', '--unset', 'core.hooksPath'], { stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+                } catch (rollbackError) {
+                    rollbackFailures.push(`global core.hooksPath: ${rollbackError.message}`);
+                }
+                console.error(`aimhooman: global hook installation failed: ${error.message}`);
+                if (rollbackFailures.length) {
+                    console.error(`aimhooman: rollback incomplete: ${rollbackFailures.join('; ')}`);
+                }
+                return 30;
+            }
+            console.log(`aimhooman: global hooks at ${rep.dir} (core.hooksPath set)`);
+            for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
+            console.log('  note: this replaces the default .git/hooks directory in non-bare repositories that inherit the global setting; local/worktree core.hooksPath overrides it.');
+            return 0;
+        }, LIFECYCLE_LOCK_OPTIONS);
+    }
+    if (options.yes) throw new ArgumentError('--yes is only valid with --global');
+    let profile = options.profile || 'clean';
+    const profileExplicit = Boolean(options.profile);
+    const repo = tryRepo();
+    if (!repo) {
+        console.error('aimhooman: not a git repository');
+        return 30;
+    }
+    const code = withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
+        let projectPolicy;
         try {
-            existing = execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
-        } catch { /* unset */ }
-        if (existing && existing !== aimDir) {
-            console.error(
-                `aimhooman: core.hooksPath is already set to '${existing}'; refusing to overwrite. ` +
-                'Unset it (git config --global --unset core.hooksPath) or choose a different setup.'
-            );
+            projectPolicy = loadProjectPolicy(repo.root);
+        } catch (e) {
+            console.error(`aimhooman: cannot load project policy: ${e.message}`);
             return 20;
         }
-        // A --system hooksPath would be shadowed by the --global write below and
-        // could silently disable a system-wide hook manager, so refuse here too.
-        let systemHooksPath = '';
+        if (projectPolicy) {
+            if (profileExplicit && profile !== projectPolicy.profile) {
+                console.error(
+                    `aimhooman: project policy requires profile "${projectPolicy.profile}"; ` +
+                    'edit .aimhooman.json to change the team baseline'
+                );
+                return 20;
+            }
+            profile = projectPolicy.profile;
+        }
+        let eng;
         try {
-            systemHooksPath = execFileSync('git', ['config', '--system', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
-        } catch { /* unset or no system config */ }
-        if (systemHooksPath) {
-            console.error(
-                `aimhooman: core.hooksPath is set at --system scope to '${systemHooksPath}'; ` +
-                'a --global install would shadow it. Unset it or choose a different setup.'
-            );
+            eng = configuredEngine(profile, repo);
+        } catch (e) {
+            console.error(`aimhooman: cannot initialise policy: ${e.message}`);
             return 20;
         }
-        const localRepo = tryRepo();
-        const localHooksPath = localRepo ? gitConfigAtScope(localRepo.root, '--local', 'core.hooksPath') : '';
-        if (localHooksPath) {
-            console.error(`aimhooman: warning: this repository has local core.hooksPath="${localHooksPath}", which overrides the global guard here`);
-        }
-        const hookSnapshots = REQUIRED_GIT_HOOKS
-            .map((name) => snapshotFile(join(aimDir, name)));
+        const hookState = hookDiagnostics(repo);
+        const hookFiles = hookState.some((hook) => hook.shared)
+            ? []
+            : [...new Set(hookState.flatMap((hook) => [hook.path, hook.chainedPath]))];
+        let snapshots = [];
         let rep;
         try {
-            rep = installGlobalHooks(CLI_PATH);
-            if (rep.skipped?.length) {
-                for (const warning of rep.warnings || []) console.error(`aimhooman: ${warning}`);
-                console.error('aimhooman: global hook installation aborted; core.hooksPath was not changed');
-                return 20;
+            snapshots = [join(repo.stateDir, 'config.json'), repo.excludeFile, ...hookFiles]
+                .map(snapshotFile);
+            rep = installHooks(repo, CLI_PATH);
+            const activeHooks = installedHooks(repo);
+            if (!REQUIRED_GIT_HOOKS.every((name) => activeHooks.includes(name))) {
+                // installHooks declines rather than throws when the hooks directory is
+                // not ours, and its warnings are the only record of why. They are
+                // printed on the success path only, so carry them into the failure or
+                // the user is told nothing but "incomplete". The prefix is load-bearing:
+                // the exit-code branch below matches on it.
+                const cause = rep.shared && rep.warnings.length ? `${rep.warnings.join('; ')}; ` : '';
+                // When the decline is because the hooks path is shared/tracked (or,
+                // after B2, worktree content the next add would commit), name the two
+                // ways out so the user is not stuck: let aimhooman use the default
+                // .git/hooks, or — for a worktree hooks path kept local — exclude it
+                // first. The uninstall hint lets them undo this init attempt.
+                const remedy = rep.shared
+                    ? ' To proceed, either unset core.hooksPath so aimhooman uses the default .git/hooks, or (for a worktree hooks path you keep local) add it to .gitignore or .git/info/exclude and retry. Run "aimhooman uninstall" to undo this init attempt.'
+                    : '';
+                throw new Error(`hook installation incomplete; ${cause}repository guard is not active.${remedy}`);
+            }
+            saveConfig(repo.stateDir, { profile });
+            applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+            const saved = loadConfig(repo.stateDir);
+            const excludes = inspectExclude(repo.excludeFile, patternsForRules(eng.rules));
+            if (saved.profile !== profile || !excludes.current) {
+                throw new Error('post-install state verification failed');
             }
-            execFileSync('git', ['config', '--global', 'core.hooksPath', rep.dir], { timeout: GIT_TIMEOUT_MS });
         } catch (error) {
             const rollbackFailures = [];
-            for (const snapshot of hookSnapshots.reverse()) {
+            try {
+                const uninstalled = uninstallHooks(repo);
+                rollbackFailures.push(...(uninstalled.failures || []));
+            } catch (rollbackError) {
+                rollbackFailures.push(`hook uninstall: ${rollbackError.message}`);
+            }
+            const hookSet = new Set(hookFiles);
+            const restoreHooks = Boolean(rep?.installed?.length || rep?.chained?.length);
+            for (const snapshot of snapshots.reverse()) {
+                if (!restoreHooks && hookSet.has(snapshot.path)) continue;
                 try { restoreSnapshot(snapshot); }
                 catch (rollbackError) {
                     rollbackFailures.push(`${snapshot.path}: ${rollbackError.message}`);
                 }
             }
-            try {
-                if (existing) execFileSync('git', ['config', '--global', 'core.hooksPath', existing], { timeout: GIT_TIMEOUT_MS });
-                else execFileSync('git', ['config', '--global', '--unset', 'core.hooksPath'], { stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
-            } catch (rollbackError) {
-                rollbackFailures.push(`global core.hooksPath: ${rollbackError.message}`);
-            }
-            console.error(`aimhooman: global hook installation failed: ${error.message}`);
             if (rollbackFailures.length) {
+                console.error(`aimhooman: initialisation failed: ${error.message}`);
                 console.error(`aimhooman: rollback incomplete: ${rollbackFailures.join('; ')}`);
+                return 30;
             }
-            return 30;
+            console.error(`aimhooman: initialisation failed and prior files were restored: ${error.message}`);
+            return /hook installation incomplete/.test(error.message) ? 20 : expectedErrorCode(error);
         }
-        console.log(`aimhooman: global hooks at ${rep.dir} (core.hooksPath set)`);
-        for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
-        console.log('  note: this replaces the default .git/hooks directory in non-bare repositories that inherit the global setting; local/worktree core.hooksPath overrides it.');
+        console.log(`aimhooman: initialised (profile: ${profile})`);
+        console.log(`  state:    ${repo.stateDir}`);
+        console.log(`  excludes: ${repo.excludeFile}`);
+        console.log(`  note:     known AI artifacts are now ignored locally; see them with 'git status --ignored'`);
+        if (rep.installed.length) console.log(`  hooks:    ${rep.installed.join(', ')}`);
+        if (rep.chained.length) console.log(`  chained:  ${rep.chained.join(', ')} (existing hooks preserved)`);
+        for (const warning of rep.warnings) console.log(`  warning:  ${warning}`);
+        console.log('  undo:     aimhooman uninstall');
         return 0;
-        }, LIFECYCLE_LOCK_OPTIONS);
-    }
-    if (options.yes) throw new ArgumentError('--yes is only valid with --global');
-    let profile = options.profile || 'clean';
-    const profileExplicit = Boolean(options.profile);
-    const repo = tryRepo();
-    if (!repo) {
-        console.error('aimhooman: not a git repository');
-        return 30;
-    }
-    return withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
-    let projectPolicy;
+    }, LIFECYCLE_LOCK_OPTIONS);
+    if (code === 0 && options.grandfatherSecrets) grandfatherTrackedSecrets(repo);
+    return code;
+}
+
+// --grandfather-secrets: a repository that already tracks secret-looking
+// fixtures (test certs, sample keys) would see every commit touching one
+// blocked, and allowing each path by hand does not scale. After a successful
+// init, scan the tracked tree once and write a --scope secret-path allow for
+// every path with a secret finding. The posture for NEW files is unchanged —
+// only paths found in this scan get an allow, so a secret added after init is
+// still blocked. A failed or incomplete scan never fails the init itself: the
+// guard is already active by then, so the gap is reported as a warning.
+function grandfatherTrackedSecrets(repo) {
+    let scan;
     try {
-        projectPolicy = loadProjectPolicy(repo.root);
-    } catch (e) {
-        console.error(`aimhooman: cannot load project policy: ${e.message}`);
-        return 20;
+        // Commit-time budgets exist for latency, but a grandfather scan that
+        // stops at the default 64 MiB total or 1,000 findings silently misses
+        // fixtures in exactly the large, fixture-heavy repositories it exists
+        // for (OpenSSL tracks ~200 MiB and its 279 key files produce more
+        // than a thousand PEM findings). This is a one-shot, operator-invoked
+        // scan of the operator's own repository, so the defaults here are the
+        // same cap an env raise could reach plus a generous finding budget;
+        // the per-file budget and an explicit env override still apply.
+        scan = scanGitTarget(repo, {
+            kind: 'tracked',
+            limits: { maxTotalBytes: MAX_SCAN_LIMIT_BYTES, maxFindings: 100_000, ...scanLimits() },
+        });
+    } catch (error) {
+        console.error(`aimhooman: warning: grandfather scan failed (${error.message}); no pre-existing secret paths were allowed`);
+        return;
     }
-    if (projectPolicy) {
-        if (profileExplicit && profile !== projectPolicy.profile) {
-            console.error(
-                `aimhooman: project policy requires profile "${projectPolicy.profile}"; ` +
-                'edit .aimhooman.json to change the team baseline'
-            );
-            return 20;
-        }
-        profile = projectPolicy.profile;
+    if (!scan.complete) {
+        console.error('aimhooman: warning: tracked scan was incomplete, so the grandfathered set may be partial; allow the remaining paths with --scope secret-path');
     }
-    let eng;
-    try {
-        eng = configuredEngine(profile, repo);
-    } catch (e) {
-        console.error(`aimhooman: cannot initialise policy: ${e.message}`);
-        return 20;
+    const paths = [...new Set(scan.findings
+        .filter((finding) => finding.category === 'secret' && finding.path)
+        .map((finding) => finding.path))].sort();
+    if (!paths.length) {
+        console.log('aimhooman: no tracked secret findings to grandfather');
+        return;
     }
-    const hookState = hookDiagnostics(repo);
-    const hookFiles = hookState.some((hook) => hook.shared)
-        ? []
-        : [...new Set(hookState.flatMap((hook) => [hook.path, hook.chainedPath]))];
-    let snapshots = [];
-    let rep;
-    try {
-        snapshots = [join(repo.stateDir, 'config.json'), repo.excludeFile, ...hookFiles]
-            .map(snapshotFile);
-        rep = installHooks(repo, CLI_PATH);
-        const activeHooks = installedHooks(repo);
-        if (!REQUIRED_GIT_HOOKS.every((name) => activeHooks.includes(name))) {
-            // installHooks declines rather than throws when the hooks directory is
-            // not ours, and its warnings are the only record of why. They are
-            // printed on the success path only, so carry them into the failure or
-            // the user is told nothing but "incomplete". The prefix is load-bearing:
-            // the exit-code branch below matches on it.
-            const cause = rep.shared && rep.warnings.length ? `${rep.warnings.join('; ')}; ` : '';
-            throw new Error(`hook installation incomplete; ${cause}repository guard is not active`);
-        }
-        saveConfig(repo.stateDir, { profile });
-        applyExclude(repo.excludeFile, patternsForRules(eng.rules));
-        const saved = loadConfig(repo.stateDir);
-        const excludes = inspectExclude(repo.excludeFile, patternsForRules(eng.rules));
-        if (saved.profile !== profile || !excludes.current) {
-            throw new Error('post-install state verification failed');
-        }
-    } catch (error) {
-        const rollbackFailures = [];
-        try {
-            const uninstalled = uninstallHooks(repo);
-            rollbackFailures.push(...(uninstalled.failures || []));
-        } catch (rollbackError) {
-            rollbackFailures.push(`hook uninstall: ${rollbackError.message}`);
-        }
-        const hookSet = new Set(hookFiles);
-        const restoreHooks = Boolean(rep?.installed?.length || rep?.chained?.length);
-        for (const snapshot of snapshots.reverse()) {
-            if (!restoreHooks && hookSet.has(snapshot.path)) continue;
-            try { restoreSnapshot(snapshot); }
-            catch (rollbackError) {
-                rollbackFailures.push(`${snapshot.path}: ${rollbackError.message}`);
-            }
-        }
-        if (rollbackFailures.length) {
-            console.error(`aimhooman: initialisation failed: ${error.message}`);
-            console.error(`aimhooman: rollback incomplete: ${rollbackFailures.join('; ')}`);
-            return 30;
+    const { engine } = newEngineWithDiagnostics('clean', repo.stateDir);
+    const added = withLock(join(repo.stateDir, 'overrides.json.lock'), () => {
+        const ov = loadOverrides(repo.stateDir);
+        let count = 0;
+        for (const path of paths) {
+            const entry = {
+                target: path,
+                scope: 'secret-path',
+                reason: 'pre-existing tracked fixture (grandfathered at init)',
+                actor: gitConfig(repo.root, 'user.email'),
+                at: new Date().toISOString(),
+            };
+            const sameAllow = (candidate) => (
+                candidate.target === path && effectiveOverrideScope(candidate, engine) === 'secret-path'
+            );
+            if (ov.allow.some(sameAllow)) continue;
+            ov.allow = upsert(ov.allow, entry, sameAllow);
+            count += 1;
         }
-        console.error(`aimhooman: initialisation failed and prior files were restored: ${error.message}`);
-        return /hook installation incomplete/.test(error.message) ? 20 : expectedErrorCode(error);
-    }
-    console.log(`aimhooman: initialised (profile: ${profile})`);
-    console.log(`  state:    ${repo.stateDir}`);
-    console.log(`  excludes: ${repo.excludeFile}`);
-    if (rep.installed.length) console.log(`  hooks:    ${rep.installed.join(', ')}`);
-    if (rep.chained.length) console.log(`  chained:  ${rep.chained.join(', ')} (existing hooks preserved)`);
-    for (const warning of rep.warnings) console.log(`  warning:  ${warning}`);
-    return 0;
-    }, LIFECYCLE_LOCK_OPTIONS);
+        saveOverrides(repo.stateDir, ov);
+        return count;
+    });
+    console.log(`aimhooman: grandfathered ${added} tracked secret path(s) with --scope secret-path allows; new files with secrets are still blocked`);
 }
 
 function cmdStatus(args) {
@@ -1049,6 +1258,25 @@ function cmdExplain(args) {
     return 0;
 }
 
+// The content half of the secret-allow guard in cmdOverride: run the engine's
+// own secret-category content rules over the target's bytes. Files over the
+// scanner's per-file budget, unreadable paths, and non-regular files skip it —
+// this guard is a UX safety net against an allow that would report success yet
+// leave the block in place, and the commit-time scanner still fails closed on
+// whatever was not checked here.
+function fileContentMatchesSecret(engine, repo, target) {
+    let content;
+    try {
+        const file = join(repo.root, target);
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.size > DEFAULT_SCAN_LIMITS.maxFileBytes) return false;
+        content = readFileSync(file, 'utf8');
+    } catch {
+        return false;
+    }
+    return engine.checkContent(target, content, { categories: ['secret'] }).length > 0;
+}
+
 function cmdOverride(args, allow) {
     const verb = allow ? 'allow' : 'deny';
     const { options, positionals } = parseArguments(args, {
@@ -1080,9 +1308,13 @@ function cmdOverride(args, allow) {
     // allow: only --scope secret-path suppresses secret findings, deliberately,
     // so a local override cannot hide a possible leaked key. Without this check
     // a bare `allow .env.minimal` would report success but leave the block in
-    // place, which reads as a broken allow.
+    // place, which reads as a broken allow. checkPaths only evaluates path
+    // rules, so a content-shaped secret (a private key inside an
+    // ordinary-looking filename) would slip past it; the content half of the
+    // guard closes that hole.
     if (allow && scope !== 'secret-path'
-        && engine.checkPaths([target]).some((finding) => finding.category === 'secret')) {
+        && (engine.checkPaths([target]).some((finding) => finding.category === 'secret')
+            || fileContentMatchesSecret(engine, repo, target))) {
         throw new ArgumentError(
             `"${target}" matches a secret rule, so a ${scope} allow cannot silence it `
             + '(a local override must not hide a possible leaked key); '
@@ -1638,41 +1870,41 @@ function cmdUninstall(args) {
     });
     if (options.global) {
         return withLock(join(globalHooksDir(), 'lifecycle.lock'), () => {
-        const aimDir = globalHooksDir();
-        const readGlobalHooksPath = () => {
-            try {
-                return execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
-            } catch { return ''; }
-        };
-        const current = readGlobalHooksPath();
-        let unsetAttempted = false;
-        if (current === aimDir) {
-            unsetAttempted = true;
-            try {
-                execFileSync('git', ['config', '--global', '--unset', 'core.hooksPath'], { stdio: ['ignore', 'ignore', 'ignore'], timeout: GIT_TIMEOUT_MS });
-            } catch { /* may have failed; re-verify below */ }
-            // A read-only or locked ~/.gitconfig can make --unset fail silently.
-            // Do not remove the dispatchers while core.hooksPath still resolves to
-            // them, or every repository inheriting this setting would run zero
-            // hooks with no warning. Preserve the working dispatchers until the
-            // config can be cleaned.
-            if (readGlobalHooksPath() === aimDir) {
-                console.error('aimhooman: could not unset global core.hooksPath (read-only or locked ~/.gitconfig); leaving dispatchers in place.');
-                console.error('  Fix the config permissions and run `aimhooman uninstall --global` again.');
-                return 30;
+            const aimDir = globalHooksDir();
+            const readGlobalHooksPath = () => {
+                try {
+                    return execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS }).trim();
+                } catch { return ''; }
+            };
+            const current = readGlobalHooksPath();
+            let unsetAttempted = false;
+            if (current === aimDir) {
+                unsetAttempted = true;
+                try {
+                    execFileSync('git', ['config', '--global', '--unset', 'core.hooksPath'], { stdio: ['ignore', 'ignore', 'ignore'], timeout: GIT_TIMEOUT_MS });
+                } catch { /* may have failed; re-verify below */ }
+                // A read-only or locked ~/.gitconfig can make --unset fail silently.
+                // Do not remove the dispatchers while core.hooksPath still resolves to
+                // them, or every repository inheriting this setting would run zero
+                // hooks with no warning. Preserve the working dispatchers until the
+                // config can be cleaned.
+                if (readGlobalHooksPath() === aimDir) {
+                    console.error('aimhooman: could not unset global core.hooksPath (read-only or locked ~/.gitconfig); leaving dispatchers in place.');
+                    console.error('  Fix the config permissions and run `aimhooman uninstall --global` again.');
+                    return 30;
+                }
             }
-        }
-        const rep = uninstallGlobalHooks();
-        console.log('aimhooman: global hooks uninstalled');
-        if (current && current !== aimDir) {
-            console.log(`  core.hooksPath kept at "${current}" (not owned by aimhooman)`);
-        } else {
-            console.log(`  core.hooksPath ${unsetAttempted ? 'unset' : 'was already unset'}`);
-        }
-        if (rep.removed.length) console.log(`  dispatchers removed: ${rep.removed.join(', ')}`);
-        for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
-        console.log(`  dir kept at ${rep.dir}`);
-        return 0;
+            const rep = uninstallGlobalHooks();
+            console.log('aimhooman: global hooks uninstalled');
+            if (current && current !== aimDir) {
+                console.log(`  core.hooksPath kept at "${current}" (not owned by aimhooman)`);
+            } else {
+                console.log(`  core.hooksPath ${unsetAttempted ? 'unset' : 'was already unset'}`);
+            }
+            if (rep.removed.length) console.log(`  dispatchers removed: ${rep.removed.join(', ')}`);
+            for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
+            console.log(`  dir kept at ${rep.dir}`);
+            return 0;
         }, LIFECYCLE_LOCK_OPTIONS);
     }
     const purge = Boolean(options.purgeState);
@@ -1683,72 +1915,72 @@ function cmdUninstall(args) {
     }
     const lifecycleLock = join(repo.commonDir, 'aimhooman-lifecycle.lock');
     const exitStatus = withLock(lifecycleLock, () => {
-    const rep = uninstallHooks(repo);
-    // The irreversible work is already done above, and the report is still
-    // below. A throw from here unwound past all of it, so a damaged marker was
-    // the only thing the user heard while four dispatchers kept guarding every
-    // commit. Report the failure beside the removal report instead of in place
-    // of it. Nothing is swallowed: this is also where the symlink and permission
-    // guards surface, and their messages still reach the user and still exit 30.
-    let excludeFailure = '';
-    try {
-        removeExclude(repo.excludeFile);
-    } catch (error) {
-        excludeFailure = `exclude block left in ${repo.excludeFile}: ${error.message}`;
-    }
-    // Trust the directory, not the report. Every refusal below leaves a working
-    // dispatcher behind, and one printed under "uninstalled" reads as done.
-    const remaining = remainingDispatchers(repo);
-    if (remaining.length) {
-        console.error('aimhooman: NOT uninstalled; leaving dispatchers in place:');
-        for (const path of remaining) console.error(`  ${path}`);
-        console.error('  These still guard every commit. Remove them by hand to finish uninstalling.');
-    } else {
-        console.log('aimhooman: uninstalled');
-    }
-    if (rep.removed.length) console.log(`  hooks removed:  ${rep.removed.join(', ')}`);
-    if (rep.restored.length) console.log(`  hooks restored: ${rep.restored.join(', ')}`);
-    for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
-    for (const f of rep.failures || []) console.error(`  failure: ${f}`);
-    if (excludeFailure) console.error(`  failure: ${excludeFailure}`);
-    const unrestored = purge ? unrestoredChainedBackups(repo) : [];
-    if (purge) {
-        // Never wipe stateDir while a predecessor hook backup is still on disk:
-        // a per-hook restore failure leaves the user's original hook existing
-        // only in <stateDir>/chained, so purging would destroy it irrecoverably.
-        if (unrestored.length || rep.failures?.length) {
-            console.error(
-                'aimhooman: state NOT purged — '
-                + `${unrestored.length} chained hook backup(s) remain unrestored`
-                + `${rep.failures?.length ? ` (failures: ${rep.failures.join('; ')})` : ''}; `
-                + "re-run 'aimhooman uninstall' to retry restore before purging."
-            );
+        const rep = uninstallHooks(repo);
+        // The irreversible work is already done above, and the report is still
+        // below. A throw from here unwound past all of it, so a damaged marker was
+        // the only thing the user heard while four dispatchers kept guarding every
+        // commit. Report the failure beside the removal report instead of in place
+        // of it. Nothing is swallowed: this is also where the symlink and permission
+        // guards surface, and their messages still reach the user and still exit 30.
+        let excludeFailure = '';
+        try {
+            removeExclude(repo.excludeFile);
+        } catch (error) {
+            excludeFailure = `exclude block left in ${repo.excludeFile}: ${error.message}`;
+        }
+        // Trust the directory, not the report. Every refusal below leaves a working
+        // dispatcher behind, and one printed under "uninstalled" reads as done.
+        const remaining = remainingDispatchers(repo);
+        if (remaining.length) {
+            console.error('aimhooman: NOT uninstalled; leaving dispatchers in place:');
+            for (const path of remaining) console.error(`  ${path}`);
+            console.error('  These still guard every commit. Remove them by hand to finish uninstalling.');
         } else {
-            rmSync(repo.stateDir, { recursive: true, force: true });
-            console.log('  state purged');
+            console.log('aimhooman: uninstalled');
         }
-    } else {
-        console.log(`  state kept at ${repo.stateDir} (use --purge-state to remove)`);
-    }
-    // Surface when a global core.hooksPath still enforces aimhooman, so a local
-    // uninstall cannot be mistaken for full removal. Foreign hooksPath values
-    // are left to the generic "not modified" warning emitted above.
-    const aimDir = globalHooksDir();
-    let globalHooksPath = '';
-    try {
-        globalHooksPath = execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], {
-            encoding: 'utf8',
-            timeout: GIT_TIMEOUT_MS,
-        }).trim();
-    } catch { /* unset */ }
-    if (globalHooksPath === aimDir) {
-        console.log('aimhooman: global Git guard is still active');
-        console.log('  eligible non-bare repositories that inherit core.hooksPath are still guarded.');
-        console.log('  run `aimhooman uninstall --global` to remove it.');
-    }
-    // The managed block is still in the exclude file and still ignoring paths, so
-    // the uninstall is genuinely incomplete and 30 is the honest answer.
-    return remaining.length || rep.failures?.length || unrestored.length || excludeFailure ? 30 : 0;
+        if (rep.removed.length) console.log(`  hooks removed:  ${rep.removed.join(', ')}`);
+        if (rep.restored.length) console.log(`  hooks restored: ${rep.restored.join(', ')}`);
+        for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
+        for (const f of rep.failures || []) console.error(`  failure: ${f}`);
+        if (excludeFailure) console.error(`  failure: ${excludeFailure}`);
+        const unrestored = purge ? unrestoredChainedBackups(repo) : [];
+        if (purge) {
+            // Never wipe stateDir while a predecessor hook backup is still on disk:
+            // a per-hook restore failure leaves the user's original hook existing
+            // only in <stateDir>/chained, so purging would destroy it irrecoverably.
+            if (unrestored.length || rep.failures?.length) {
+                console.error(
+                    'aimhooman: state NOT purged — '
+                    + `${unrestored.length} chained hook backup(s) remain unrestored`
+                    + `${rep.failures?.length ? ` (failures: ${rep.failures.join('; ')})` : ''}; `
+                    + "re-run 'aimhooman uninstall' to retry restore before purging."
+                );
+            } else {
+                rmSync(repo.stateDir, { recursive: true, force: true });
+                console.log('  state purged');
+            }
+        } else {
+            console.log(`  state kept at ${repo.stateDir} (use --purge-state to remove)`);
+        }
+        // Surface when a global core.hooksPath still enforces aimhooman, so a local
+        // uninstall cannot be mistaken for full removal. Foreign hooksPath values
+        // are left to the generic "not modified" warning emitted above.
+        const aimDir = globalHooksDir();
+        let globalHooksPath = '';
+        try {
+            globalHooksPath = execFileSync('git', ['config', '--global', '--get', 'core.hooksPath'], {
+                encoding: 'utf8',
+                timeout: GIT_TIMEOUT_MS,
+            }).trim();
+        } catch { /* unset */ }
+        if (globalHooksPath === aimDir) {
+            console.log('aimhooman: global Git guard is still active');
+            console.log('  eligible non-bare repositories that inherit core.hooksPath are still guarded.');
+            console.log('  run `aimhooman uninstall --global` to remove it.');
+        }
+        // The managed block is still in the exclude file and still ignoring paths, so
+        // the uninstall is genuinely incomplete and 30 is the honest answer.
+        return remaining.length || rep.failures?.length || unrestored.length || excludeFailure ? 30 : 0;
     }, LIFECYCLE_LOCK_OPTIONS);
     // Sweep the operational residue the guard authored in .git, so uninstall leaves
     // no aimhooman fingerprints behind — the same tooling residue this tool exists
@@ -1792,7 +2024,7 @@ function usage() {
     process.stdout.write(`aimhooman ${VERSION} - AI works. Hoomans ship.
 
 Usage:
-  aimhooman init [--profile clean|strict|compliance]
+  aimhooman init [--profile clean|strict|compliance] [--grandfather-secrets]
   aimhooman init --global --yes
   aimhooman check [--staged] [-m <file>|--message <file>] [--profile ...] [--json]
   aimhooman check --commit <rev> | --range <base>...<head> | --tracked