@rmyndharis/aimhooman 0.1.8 → 0.3.0

package/bin/aimhooman.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
-import { chmodSync, lstatSync, readdirSync, readFileSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, 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,6 +10,7 @@ import { exitCode, human, jsonReport, visible } from '../src/report.mjs';
 import {
     GitRevisionError,
     gitConfig,
+    ignoredByPatterns,
     introducedCommits,
     openRepo,
     readCommitPath,
@@ -20,7 +22,7 @@ import {
     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';
@@ -110,7 +112,6 @@ function configuredEngine(profile, repo) {
             entry.scope === undefined
             || entry.scope === 'path'
             || entry.scope === 'rule'
-            || entry.scope === 'secret-path'
         ));
         engine.setOverrides(ordinary(ov.allow), ordinary(ov.deny));
     }
@@ -212,24 +213,30 @@ function emitDiagnostics(diagnostics = []) {
     }
 }
 
-function incompleteMessage(scan) {
+function incompleteMessage(scan, { blocking = true } = {}) {
     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
     // the error, so point at that instead of misdirecting to the limits. When a
     // byte budget is what stopped the scan, name the budget: the caller whose own
     // tree outgrew it needs to raise one, and "reduce the limits" sends them the
-    // wrong way down a road they cannot leave.
+    // wrong way down a road they cannot leave. A blocking stop says "and retry";
+    // a warning names what to change so the next run covers what this one
+    // skipped — this run is already through.
+    const tail = blocking ? 'and retry' : 'so the next scan covers it';
     const budgeted = reasons['size-limit'] || reasons['total-byte-limit'];
     const hint = reasons['local-pack-error']
-        ? 'fix the reported rule pack and retry'
+        ? `fix the reported rule pack ${tail}`
         : 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`;
+            ? `reduce the target, or raise AIMHOOMAN_MAX_FILE_BYTES / AIMHOOMAN_MAX_TOTAL_BYTES, ${tail}`
+            : `reduce the target or limits ${tail}`;
+    let message = `aimhooman: ${blocking ? '' : 'warning: '}scan incomplete${skipped ? ` (skipped: ${skipped})` : ''}; ${hint}\n`;
     const skippedPaths = scan.stats?.skippedPaths || {};
     const pathLines = [];
     for (const [reason, entries] of Object.entries(skippedPaths)) {
@@ -242,6 +249,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`;
@@ -371,6 +389,38 @@ function precommitCleanMatches(repo, treeSha, profile) {
         && 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();
@@ -393,8 +443,12 @@ function cmdPrecommit(args) {
     if (!blocks.length) {
         if (reviews.length) process.stderr.write(human(reviews, tone()));
         if (!scan.complete) {
-            process.stderr.write(incompleteMessage(scan));
-            return 31;
+            // Strict stops on an unchecked remainder. Clean/compliance go ahead
+            // with a warning: the reference-transaction guard rescans the
+            // introduced commit before any ref moves. The clean marker stays
+            // unwritten so commit-msg does not skip its own tree scan.
+            process.stderr.write(incompleteMessage(scan, { blocking: profile === 'strict' }));
+            return profile === 'strict' ? 31 : 0;
         }
         // W5 marker dedup: record that this staged tree scanned clean so the
         // upcoming commit-msg hook can skip its duplicate tree scan. The tree
@@ -403,6 +457,7 @@ function cmdPrecommit(args) {
         // 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') {
@@ -465,21 +520,25 @@ function cmdPrecommit(args) {
         );
         return 10;
     }
-    // Seven of the rules that can reach the summary above are secret rules, so it
-    // cannot name a cause without guessing wrong for a private key or an AWS
-    // credential — and it used to be the only thing printed for a block. Let the
-    // findings speak instead: human() already carries the rule id, the path, the
-    // reason and the remediation, and already redacts secret text. It labels each
-    // one BLOCK, which is the decision that unstaged the path, not a stopped
-    // commit; the summary above says what actually happened to them.
+    // The summary above cannot name a cause without guessing which rule fired,
+    // and it used to be the only thing printed for a block. Let the findings
+    // speak instead: human() already carries the rule id, the path, the reason
+    // and the remediation, and redacts secret-category text from local packs.
+    // It labels each one BLOCK, which is the decision that unstaged the path,
+    // not a stopped commit; the summary above says what actually happened to
+    // them.
     process.stderr.write(human([...blocks, ...reviews], tone()));
-    if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+    // Only frictionless profiles reach the repair path (strict returned 10
+    // above), so an incomplete post-repair scan is a warning, not a stop: the
+    // reference-transaction guard rescans the introduced commit.
+    if (!scan.complete) process.stderr.write(incompleteMessage(scan, { blocking: false }));
     // Git refuses a commit with nothing staged; repair runs after git has already
     // decided otherwise, so carrying on here mints the empty commit git would
     // not. The request was to commit the artifact, not to stamp the history with
     // its message and no content.
     if (emptied) return 10;
-    return scan.complete ? 0 : 31;
+    if (scan.complete) noticeIgnoredArtifacts(repo);
+    return 0;
 }
 
 function cmdCommitmsg(args) {
@@ -555,6 +614,9 @@ function cmdCommitmsg(args) {
             if (!treeScan.complete) process.stderr.write(incompleteMessage(treeScan));
             return treeCode;
         }
+        // exitCode passes an incomplete tree scan on frictionless profiles; the
+        // skip still names itself so the commit does not sail through silently.
+        if (!treeScan.complete) process.stderr.write(incompleteMessage(treeScan, { blocking: false }));
     }
     if (dispatchHooksChanged(repo, profile)) return 20;
     // Strict must fail closed on an incomplete scan: a block still wins (10),
@@ -564,7 +626,7 @@ function cmdCommitmsg(args) {
         process.stderr.write(incompleteMessage(scan));
         return findings.some((finding) => finding.decision === 'block') ? 10 : 31;
     }
-    if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+    if (!scan.complete) process.stderr.write(incompleteMessage(scan, { blocking: false }));
     if (!findings.length) return 0;
     const blocks = findings.filter((finding) => finding.decision === 'block');
     if (profile === 'strict') {
@@ -741,11 +803,24 @@ function cmdRefcheck(args) {
             return expectedErrorCode(error);
         }
         emitDiagnostics(scan.diagnostics);
-        const code = exitCode(scan.findings, scan.profile, scan.complete);
+        // The reference transaction is the final boundary --no-verify cannot
+        // skip, so an incomplete scan vetoes the update on every profile, even
+        // though earlier guards let frictionless profiles through with a
+        // warning.
+        const code = exitCode(scan.findings, scan.profile, scan.complete, { failClosedIncomplete: true });
         if (code !== 0) {
             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;
         }
     }
@@ -829,7 +904,7 @@ function cmdCheck(args) {
     }
     else {
         process.stderr.write(human(findings, tone()));
-        if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+        if (!scan.complete) process.stderr.write(incompleteMessage(scan, { blocking: scan.profile === 'strict' }));
     }
     return exitCode(findings, scan.profile, scan.complete);
 }
@@ -840,8 +915,9 @@ function cmdInit(args) {
             profile: { names: ['--profile'], type: 'string', choices: [...PROFILES] },
             global: { names: ['--global'], type: 'boolean' },
             yes: { names: ['--yes'], type: 'boolean' },
+            gitignore: { names: ['--gitignore'], type: 'boolean' },
         },
-        conflicts: [['profile', 'global']],
+        conflicts: [['profile', 'global'], ['gitignore', 'global']],
         maxPositionals: 0,
     });
     if (rejectUnsupportedGit()) return 20;
@@ -926,7 +1002,7 @@ function cmdInit(args) {
         console.error('aimhooman: not a git repository');
         return 30;
     }
-    return withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
+    const code = withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
         let projectPolicy;
         try {
             projectPolicy = loadProjectPolicy(repo.root);
@@ -955,10 +1031,26 @@ function cmdInit(args) {
         const hookFiles = hookState.some((hook) => hook.shared)
             ? []
             : [...new Set(hookState.flatMap((hook) => [hook.path, hook.chainedPath]))];
+        // --gitignore opts the clone into the committed variant of the managed
+        // block. A plain re-init keeps a previously recorded choice instead of
+        // silently dropping a block a teammate may already have committed. The
+        // record lives in the local config: whether this clone created its
+        // .gitignore is per-clone state, never team policy.
+        let previousGitignore;
+        try {
+            previousGitignore = loadConfig(repo.stateDir).gitignore;
+        } catch {
+            // An unreadable local config is rewritten by saveConfig below, the
+            // same recovery a plain init has always had.
+            previousGitignore = undefined;
+        }
+        const gitignoreFile = join(repo.root, '.gitignore');
+        const gitignoreWanted = Boolean(options.gitignore) || Boolean(previousGitignore?.enabled);
         let snapshots = [];
         let rep;
         try {
             snapshots = [join(repo.stateDir, 'config.json'), repo.excludeFile, ...hookFiles]
+                .concat(gitignoreWanted ? [gitignoreFile] : [])
                 .map(snapshotFile);
             rep = installHooks(repo, CLI_PATH);
             const activeHooks = installedHooks(repo);
@@ -979,11 +1071,21 @@ function cmdInit(args) {
                     : '';
                 throw new Error(`hook installation incomplete; ${cause}repository guard is not active.${remedy}`);
             }
-            saveConfig(repo.stateDir, { profile });
-            applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+            const patterns = patternsForRules(eng.rules);
+            // created is sticky: once aimhooman introduced the file it stays
+            // recorded as ours, so uninstall can remove an emptied husk it made.
+            const gitignore = gitignoreWanted
+                ? { enabled: true, created: Boolean(previousGitignore?.created) || !existsSync(gitignoreFile) }
+                : undefined;
+            saveConfig(repo.stateDir, gitignore ? { profile, gitignore } : { profile });
+            // The opt-in worktree file goes first, so every later failure —
+            // including the core exclude write — rolls it back with the rest.
+            if (gitignore) applyExclude(gitignoreFile, patterns);
+            applyExclude(repo.excludeFile, patterns);
             const saved = loadConfig(repo.stateDir);
-            const excludes = inspectExclude(repo.excludeFile, patternsForRules(eng.rules));
-            if (saved.profile !== profile || !excludes.current) {
+            const excludes = inspectExclude(repo.excludeFile, patterns);
+            if (saved.profile !== profile || !excludes.current
+                || (gitignore && !inspectExclude(gitignoreFile, patterns).current)) {
                 throw new Error('post-install state verification failed');
             }
         } catch (error) {
@@ -1014,11 +1116,18 @@ function cmdInit(args) {
         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 (options.gitignore) {
+            console.log('aimhooman: wrote AI-artifact ignores to .gitignore — commit it to share them with every clone');
+            console.log('  note:     gitignore matching is case-sensitive; the commit hooks still catch case variants');
+        }
         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);
+    return code;
 }
 
 function cmdStatus(args) {
@@ -1062,6 +1171,24 @@ function cmdStatus(args) {
         excludeError = e.message;
         excludes = { current: false, installed: false };
     }
+    // The committed variant is reported only when the local config records the
+    // opt-in; anything else in a worktree .gitignore is the user's own file.
+    let gitignoreRecord;
+    try {
+        gitignoreRecord = loadConfig(repo.stateDir).gitignore;
+    } catch {
+        gitignoreRecord = undefined;
+    }
+    let gitignoreExcludes;
+    let gitignoreError = null;
+    if (gitignoreRecord?.enabled) {
+        try {
+            gitignoreExcludes = inspectExclude(join(repo.root, '.gitignore'), patternsForRules(engine.rules));
+        } catch (e) {
+            gitignoreError = e.message;
+            gitignoreExcludes = { current: false, installed: false };
+        }
+    }
     // The pre-commit and reference-transaction guards resolve the policy from
     // the index, so the staged profile is what is actually enforced. Report it
     // first; the worktree file is shown alongside so an edit that has not been
@@ -1088,6 +1215,9 @@ function cmdStatus(args) {
     console.log(`rules:    ${builtin} built-in${local ? ` + ${local} local` : ''}`);
     console.log(`overrides: ${overrides.allow.length} allow, ${overrides.deny.length} deny`);
     console.log(`excludes: ${excludeError ? `unknown (malformed markers: ${excludeError}; run: aimhooman init)` : excludes.current ? 'current' : excludes.installed ? 'out of date (run: aimhooman init)' : 'not installed (run: aimhooman init)'}`);
+    if (gitignoreRecord?.enabled) {
+        console.log(`gitignore: ${gitignoreError ? `unknown (malformed markers: ${gitignoreError}; run: aimhooman init)` : gitignoreExcludes.current ? 'current' : gitignoreExcludes.installed ? 'out of date (run: aimhooman init)' : 'not installed (run: aimhooman init --gitignore)'}`);
+    }
     for (const error of errors) console.log(`warning:  ${error.message}`);
     const localHooks = gitConfigAtScope(repo.root, '--local', 'core.hooksPath');
     const globalHooks = gitConfigAtScope(repo.root, '--global', 'core.hooksPath');
@@ -1136,7 +1266,7 @@ function cmdOverride(args, allow) {
     const { options, positionals } = parseArguments(args, {
         options: {
             reason: { names: ['--reason'], type: 'string', nonEmpty: false },
-            scope: { names: ['--scope'], type: 'string', choices: ['path', 'rule', 'secret-path'] },
+            scope: { names: ['--scope'], type: 'string', choices: ['path', 'rule'] },
         },
         minPositionals: 1,
         maxPositionals: 1,
@@ -1153,27 +1283,6 @@ function cmdOverride(args, allow) {
     if (scope === 'rule' && !engine.lookup(target)) {
         throw new ArgumentError(`unknown rule ID "${target}"; use --scope path for a path with this spelling`);
     }
-    if (allow && scope === 'rule' && engine.lookup(target)?.category === 'secret') {
-        throw new ArgumentError(
-            `secret rules cannot be allowed at --scope rule (that would suppress every matching secret path under every profile); use --scope secret-path <path> to allow a specific secret path`,
-        );
-    }
-    // A path that matches a secret rule cannot be silenced by a path (or rule)
-    // 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.
-    if (allow && scope !== 'secret-path'
-        && engine.checkPaths([target]).some((finding) => finding.category === 'secret')) {
-        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); '
-            + 'use --scope secret-path to explicitly allow this specific path',
-        );
-    }
-    if (scope === 'secret-path' && !allow) {
-        throw new ArgumentError('--scope secret-path is only valid with allow');
-    }
     const entry = {
         target,
         scope,
@@ -1496,7 +1605,7 @@ function cmdFix(args) {
         return expectedErrorCode(e);
     }
     emitDiagnostics(scan.diagnostics);
-    if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+    if (!scan.complete) process.stderr.write(incompleteMessage(scan, { blocking: scan.profile === 'strict' }));
     if (scan.profile === 'compliance') {
         if (options.apply) throw new ArgumentError('--apply is only valid when the active profile is strict');
         if (scan.findings.length) process.stderr.write(human(scan.findings, tone()));
@@ -1778,6 +1887,32 @@ function cmdUninstall(args) {
         } catch (error) {
             excludeFailure = `exclude block left in ${repo.excludeFile}: ${error.message}`;
         }
+        // The committed variant of the block is only touched while the local
+        // config says this clone opted in; without that record the worktree
+        // .gitignore is treated as user-authored and left alone.
+        let gitignoreRecord;
+        try {
+            gitignoreRecord = loadConfig(repo.stateDir).gitignore;
+        } catch {
+            gitignoreRecord = undefined;
+        }
+        if (gitignoreRecord?.enabled) {
+            const gitignoreFile = join(repo.root, '.gitignore');
+            try {
+                removeExclude(gitignoreFile);
+                // We introduced the file: once the block is gone and nothing
+                // else remains, delete it rather than leave an empty husk. A
+                // file with any other content is user-authored and stays.
+                if (gitignoreRecord.created
+                    && existsSync(gitignoreFile)
+                    && readFileSync(gitignoreFile, 'utf8').trim() === '') {
+                    rmSync(gitignoreFile, { force: true });
+                }
+            } catch (error) {
+                const gitignoreFailure = `gitignore block left in ${gitignoreFile}: ${error.message}`;
+                excludeFailure = excludeFailure ? `${excludeFailure}; ${gitignoreFailure}` : gitignoreFailure;
+            }
+        }
         // 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);
@@ -1874,14 +2009,14 @@ function usage() {
     process.stdout.write(`aimhooman ${VERSION} - AI works. Hoomans ship.
 
 Usage:
-  aimhooman init [--profile clean|strict|compliance]
+  aimhooman init [--profile clean|strict|compliance] [--gitignore]
   aimhooman init --global --yes
   aimhooman check [--staged] [-m <file>|--message <file>] [--profile ...] [--json]
   aimhooman check --commit <rev> | --range <base>...<head> | --tracked
   aimhooman audit|scan [--json] [--profile ...]
   aimhooman status
   aimhooman explain <rule-id>
-  aimhooman allow <path|rule-id> [--scope path|rule|secret-path] [--reason "..."]
+  aimhooman allow <path|rule-id> [--scope path|rule] [--reason "..."]
   aimhooman deny <path|rule-id> [--scope path|rule] [--reason "..."]
   aimhooman override list [--json]
   aimhooman override remove <target>

package/docs/ai-artifacts.gitignore

@@ -0,0 +1,63 @@
+# AI tooling artifacts for .gitignore
+#
+# These patterns cover the session and state files that AI coding tools
+# write into a working tree: transcripts, history, caches, logs, and local
+# settings. aimhooman keeps them out of commits. Copy the lines below into
+# your .gitignore as-is. Matching follows normal gitignore rules and is
+# case-sensitive. The machine-enforced version of this list lives in the
+# aimhooman CLI, which blocks these paths at commit time; this file is the
+# standalone copy for anyone who wants the same coverage without the hooks.
+#
+# Generated from rules/*.json by `npm run sync:catalog`; do not edit by hand.
+# `npm run check` fails when this file is stale.
+
+# >>> aimhooman:catalog-start
+**/.agent/**
+**/.aider.*
+**/.claude.json
+**/.claude/history*
+**/.claude/logs/**
+**/.claude/projects/**
+**/.claude/session*.json
+**/.claude/settings.local.json
+**/.claude/shell-snapshots/**
+**/.claude/statsig/**
+**/.claude/todos/**
+**/.codex/history*
+**/.codex/log/**
+**/.codex/logs/**
+**/.codex/sessions/**
+**/.continue/sessions/**
+**/.copilot/**
+**/.cursor/chats/**
+**/.cursor/logs/**
+**/.cursor/session*
+**/.playwright-mcp/**
+**/.remember/**
+**/.specstory/**
+**/.superpowers/**
+.agent/**
+.aider.*
+.claude.json
+.claude/history*
+.claude/logs/**
+.claude/projects/**
+.claude/session*.json
+.claude/settings.local.json
+.claude/shell-snapshots/**
+.claude/statsig/**
+.claude/todos/**
+.codex/history*
+.codex/log/**
+.codex/logs/**
+.codex/sessions/**
+.continue/sessions/**
+.copilot/**
+.cursor/chats/**
+.cursor/logs/**
+.cursor/session*
+.playwright-mcp/**
+.remember/**
+.specstory/**
+.superpowers/**
+# <<< aimhooman:catalog-end

package/docs/catalog.md

@@ -0,0 +1,41 @@
+# AI-artifact catalog
+
+<!-- Generated from rules/*.json by `npm run sync:catalog`; do not edit by hand. -->
+
+aimhooman watches commits for AI residue: tooling artifacts (session files,
+local settings, and agent state that belong on your machine, not in history)
+and AI attribution (co-author trailers, "generated with" lines, leftover
+markers in code). The table lists every built-in rule and what each profile
+does when it matches: `block` stops the commit, `review` asks a human to
+confirm, `allow` lets it through.
+
+Secret scanning is out of scope since v0.3.0. See
+[docs/secrets.md](secrets.md) for the reasoning and the gitleaks setup we
+recommend instead.
+
+<!-- aimhooman:catalog-start -->
+| Rule | Provider | Category | Kind | clean | strict | compliance | Reason |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `attribution.claude-coauthor` | claude-code | ai-attribution | message | block | block | allow | Unwanted AI co-author attribution (Claude). |
+| `attribution.copilot-coauthor` | copilot | ai-attribution | message | block | block | allow | Unwanted AI co-author attribution (Copilot). |
+| `attribution.codex-coauthor` | codex | ai-attribution | message | block | block | allow | Unwanted AI co-author attribution (Codex). |
+| `attribution.bot-coauthor` | generic | ai-attribution | message | review | review | allow | Unwanted bot co-author attribution. |
+| `attribution.generated-with` | generic | ai-attribution | message | block | block | allow | Unwanted AI generation attribution in the message. |
+| `attribution.ai-noreply` | generic | ai-attribution | message | review | review | allow | AI service noreply email in the message. |
+| `marker.corner-cut` | generic | ai-marker | code | review | block | review | AI-tooling corner-cut marker left in committed code. |
+| `marker.ai-authored` | generic | ai-marker | code | review | block | review | AI-authored code marker left in committed code. |
+| `claude.local-settings` | claude-code | local-settings | path | block | block | block | Personal Claude Code settings are not intended for source control. |
+| `claude.session-state` | claude-code | ephemeral-state | path | block | block | block | Claude Code session and state artifacts are local, not repository content. |
+| `codex.session-state` | codex | ephemeral-state | path | block | block | block | Codex session, history, and log artifacts are local, not repository content. |
+| `copilot.session-state` | copilot | ephemeral-state | path | block | block | block | Copilot local state is not repository content. |
+| `cursor.session-state` | cursor | ephemeral-state | path | block | block | block | Cursor session artifacts are local, not repository content. |
+| `aider.history` | aider | ephemeral-state | path | block | block | block | Aider dotfiles are local, not repository content. |
+| `specstory.history` | specstory | ephemeral-state | path | block | block | block | SpecStory session history is local, not repository content. |
+| `continue.sessions` | continue | ephemeral-state | path | block | block | block | Continue session artifacts are local, not repository content. |
+| `generic.agent-instructions` | generic | ambiguous-instructions | path | review | block | review | Agent instruction files may be intentional team config. Review before committing. |
+| `generic.project-policy` | aimhooman | policy-config | path | review | block | review | Versioned enforcement policy changes require explicit human review. |
+| `playwright-mcp.state` | playwright-mcp | ephemeral-state | path | block | block | block | Playwright MCP session artifacts are local, not repository content. |
+| `remember.state` | remember | ephemeral-state | path | block | block | block | Remember second-brain data is local, not repository content. |
+| `superpowers.state` | superpowers | ephemeral-state | path | block | block | block | Superpowers plugin state is local, not repository content. |
+| `agent.state` | generic | ephemeral-state | path | block | block | block | Generic agent state is local, not repository content. |
+<!-- aimhooman:catalog-end -->