@rmyndharis/aimhooman 0.3.1 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
             "name": "aimhooman",
             "source": "./",
             "description": "Keeps AI session files and unwanted attribution out at the agent and Git boundary.",
-            "version": "0.3.1",
+            "version": "0.4.0",
             "license": "MIT",
             "keywords": [
                 "git",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "description": "AI works. Hoomans ship. Keeps AI session files and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "description": "AI works. Hoomans ship. Keeps AI session files and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman maintainers",

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-07-20
+
+### Added
+
+- New managed `pre-push` hook (`pushcheck`) that scans every commit a push
+  would introduce, messages included. A commit vetoed by the
+  reference-transaction guard stays in the local object store, and pushing that
+  raw object ID (`git push <remote> <sha>:<ref>`) moved no local branch, so it
+  sailed past every guard; the veto message even printed the SHA. Such pushes
+  are now rejected before any objects are sent. Deletions carry nothing and
+  pass without scanning.
+
+### Changed
+
+- A scan whose only gap is a file over the per-file size budget no longer
+  wedges commits on `clean`/`compliance`: the final ref guard warns and
+  continues instead of vetoing, because path rules still covered the file.
+  `strict` stays fail-closed (exit 31) on any incomplete scan, and every other
+  gap (total byte budget, unreadable objects, rule-pack errors) stays
+  fail-closed on all profiles.
+- Commit overhead: the `commit-msg` dispatcher greps the message for the
+  attribution-rule anchors and skips its Node spawn when none is present (a
+  local rule pack or a missing `pre-commit` dispatcher re-enables the spawn,
+  since the "tree already scanned" premise needs both), and `pre-commit` skips
+  its spawn when the index is empty. A typical commit goes from three Node
+  spawns to two; an empty commit to one.
+- The `not very hooman.` banner now appears only when a finding actually stops
+  or reshapes the operation (a block). A pure review advisory, where the
+  commit proceeds untouched, prints without it so the banner keeps its meaning.
+- A blocked strict-policy downgrade or deletion now prints the exact
+  `aimhooman policy-review` invocation — oids included — instead of pointing at
+  "the reviewed migration command"; running the printed command unlocks the
+  commit.
+- A non-blocking "scan incomplete" warning (the oversized-file case) prints
+  once per tree and gap instead of once per hook: pre-commit, commit-msg, the
+  final ref guard, and pre-push share a notice marker, so the same oversized
+  file no longer warns three times in one commit.
+
 ## [0.3.1] - 2026-07-19
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/rmyndharis/aimhooman/test.yml?branch=main&label=CI" alt="CI">
-  <img src="https://img.shields.io/badge/version-v0.3.1-blue" alt="v0.3.1">
+  <img src="https://img.shields.io/badge/version-v0.4.0-blue" alt="v0.4.0">
   <img src="https://img.shields.io/badge/node-%E2%89%A522.8-339933?logo=node.js&logoColor=white" alt="Node 22.8+">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
   <img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT">
@@ -41,7 +41,9 @@ One detection core, many enforcement surfaces. On the default profile the ordina
 path repairs hygiene findings when it can; `commit-msg` checks the pinned would-be tree,
 and the final ref boundary independently scans every commit introduced to `HEAD` or a
 branch. A block that survives repair stops the commit; an incomplete scan warns on
-`clean`/`compliance` and still vetoes at the final ref guard.
+`clean`/`compliance` and still vetoes at the final ref guard, unless the only gap is a
+file over the per-file size budget. `pre-push` scans what a push would send, so a commit
+pushed by raw object ID cannot bypass the local guards.
 
 ```mermaid
 flowchart TD
@@ -57,15 +59,18 @@ flowchart TD
     MSG -->|unsafe or unrepairable| BLOCK
     REF -->|accepted| SHIP([Ref update commits])
     REF -->|violation or incomplete scan| BLOCK
+    PUSH([git push]) --> PREPUSH["pre-push<br/>scans every commit the push would send,<br/>messages included — even a push by raw object ID"]
+    PREPUSH -->|accepted| SENT([Objects leave for the remote])
+    PREPUSH -->|violation| BLOCK
 
     classDef entry fill:#f8fafc,stroke:#94a3b8,color:#0f172a,stroke-width:1.5px
     classDef hook fill:#eef2ff,stroke:#6366f1,color:#312e81,stroke-width:2px
     classDef ok fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1.5px
     classDef stop fill:#fef2f2,stroke:#ef4444,color:#7f1d1d,stroke-width:2px
 
-    class SESS,AGENT,RUN,COMMIT,DIRECT entry
-    class PRE,MSG,REF hook
-    class SHIP ok
+    class SESS,AGENT,RUN,COMMIT,DIRECT,PUSH entry
+    class PRE,MSG,REF,PREPUSH hook
+    class SHIP,SENT ok
     class BLOCK stop
 ```
 

package/bin/aimhooman.mjs

@@ -128,7 +128,7 @@ function main(argv) {
     // switch below.
     const SUBCOMMAND_HELP_FLAGS = new Set(['--help', '-h', 'help']);
     const knownSubcommands = new Set([
-        'check', 'audit', 'scan', 'precommit', 'commitmsg', 'refcheck', 'init',
+        'check', 'audit', 'scan', 'precommit', 'commitmsg', 'refcheck', 'pushcheck', 'init',
         'status', 'explain', 'allow', 'deny', 'override', 'review',
         'policy-review', 'fix', 'doctor', 'uninstall',
     ]);
@@ -148,6 +148,8 @@ function main(argv) {
             return cmdCommitmsg(rest);
         case 'refcheck':
             return cmdRefcheck(rest);
+        case 'pushcheck':
+            return cmdPushcheck(rest);
         case 'init':
             return cmdInit(rest);
         case 'status':
@@ -249,6 +251,31 @@ function incompleteMessage(scan, { blocking = true } = {}) {
     return message + pathLines.join('');
 }
 
+// One oversized file trips the same non-blocking "scan incomplete" warning in
+// up to three hooks of a single commit (pre-commit, commit-msg, the final ref
+// guard) and again in pre-push. Print it once per tree and gap: the first
+// guard to warn records the tree plus the skip signature, later guards stay
+// silent for the identical gap. State failures degrade to printing — a
+// duplicate warning is noise, a swallowed one is a miss.
+const INCOMPLETE_NOTICE_VERSION = 1;
+function warnIncompleteOnce(repo, treeSha, scan) {
+    const signature = createHash('sha256')
+        .update(JSON.stringify([scan.stats?.skipped || {}, scan.stats?.skippedPaths || {}]))
+        .digest('hex');
+    if (treeSha) {
+        try {
+            const statePath = join(repo.stateDir, 'incomplete-notice.json');
+            let previous = null;
+            try { previous = JSON.parse(readFileSync(statePath, 'utf8')); } catch { /* first run or corrupt state */ }
+            if (previous?.version === INCOMPLETE_NOTICE_VERSION
+                && previous.tree === treeSha
+                && previous.signature === signature) return;
+            writeFileSync(statePath, JSON.stringify({ version: INCOMPLETE_NOTICE_VERSION, tree: treeSha, signature }));
+        } catch { /* fall through to printing */ }
+    }
+    process.stderr.write(incompleteMessage(scan, { blocking: false }));
+}
+
 // 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) {
@@ -444,11 +471,15 @@ function cmdPrecommit(args) {
         if (reviews.length) process.stderr.write(human(reviews, tone()));
         if (!scan.complete) {
             // 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;
+            // with a warning — printed once per tree across all of a commit's
+            // hooks (see warnIncompleteOnce). The clean marker stays unwritten
+            // so commit-msg does not skip its own tree scan.
+            if (profile === 'strict') {
+                process.stderr.write(incompleteMessage(scan));
+                return 31;
+            }
+            warnIncompleteOnce(repo, stagedTreeSha(repo), scan);
+            return 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
@@ -616,7 +647,8 @@ function cmdCommitmsg(args) {
         }
         // 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 }));
+        // pre-commit already printed this exact gap for this tree — warn once.
+        if (!treeScan.complete) warnIncompleteOnce(repo, options.tree, treeScan);
     }
     if (dispatchHooksChanged(repo, profile)) return 20;
     // Strict must fail closed on an incomplete scan: a block still wins (10),
@@ -626,7 +658,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, { blocking: false }));
+    if (!scan.complete) warnIncompleteOnce(repo, options.tree, scan);
     if (!findings.length) return 0;
     const blocks = findings.filter((finding) => finding.decision === 'block');
     if (profile === 'strict') {
@@ -659,6 +691,180 @@ function cmdCommitmsg(args) {
     return remaining.some((finding) => finding.decision === 'block') ? 10 : 0;
 }
 
+// resolveIntroduced maps each proposed update to the commits it introduces,
+// with the review contexts and local-authorship flags the scan needs. Shared
+// by refcheck (local ref updates) and pushcheck (about-to-be-pushed refs).
+// includeStagedContexts carries a staged review into the direct tip's scan;
+// pushcheck leaves it off because a pushed commit is judged as an object, not
+// against the live index it may never have passed through.
+function resolveIntroduced(repo, updates, { includeStagedContexts = true } = {}) {
+    const contextsByCommit = new Map();
+    // A commit's message belongs to whoever wrote it. Attribution and marker
+    // rules police the text a local developer can edit, so they are scoped
+    // to commits authored here: an update that introduces exactly one new
+    // commit on top of a non-zero old tip (a plain commit, an --amend, or a
+    // local --no-ff merge of an already-gated branch). Anything else — a new
+    // branch pulled in by `gh pr checkout` or `git fetch`, a merge of fetched
+    // history — imports other people's commit text the developer cannot
+    // change, and scanning it only blocks the review.
+    const localAuthorTips = new Set();
+    for (const update of updates) {
+        const introduced = introducedCommits(repo, [update]);
+        if (!/^0+$/.test(update.oldObjectId)
+            && introduced.length === 1
+            && introduced[0] === update.newObjectId) {
+            localAuthorTips.add(update.newObjectId);
+        }
+        for (const revision of introduced) {
+            const contexts = contextsByCommit.get(revision) || [];
+            contexts.push({
+                head: update.newObjectId,
+                storedTransition: revision,
+                scanTransition: revision,
+            });
+            // A staged review is bound to the exact old tip. It can be
+            // carried into the final full-snapshot scan only for the direct
+            // proposed tip whose parent is that old tip, never for an
+            // intermediate commit or a newly created branch ancestry.
+            if (includeStagedContexts && revision === update.newObjectId && !/^0+$/.test(update.oldObjectId)) {
+                const { parents } = commitParents(repo, revision);
+                if (parents.includes(update.oldObjectId)) {
+                    contexts.push({
+                        head: update.oldObjectId,
+                        storedTransition: 'staged',
+                        scanTransition: revision,
+                    });
+                }
+            }
+            contextsByCommit.set(revision, contexts);
+        }
+    }
+    return [...contextsByCommit].map(([revision, reviewContexts]) => [
+        revision,
+        reviewContexts,
+        localAuthorTips.has(revision),
+    ]);
+}
+
+// scanProposedCommits scans each introduced commit and returns the first
+// non-zero verdict. rejectNote(revision) supplies the caller-specific veto
+// line(s) printed after the findings; callers without a note pass null.
+function scanProposedCommits(repo, commits, { rejectNote }) {
+    const limits = scanLimits();
+    for (const [revision, reviewContexts, authoredLocally] of commits) {
+        let scan;
+        try {
+            scan = scanGitTarget(repo, {
+                kind: 'commit',
+                revision,
+                reviewContexts,
+                policyMigrationContexts: reviewContexts,
+                limits,
+                messageScope: authoredLocally ? 'commit' : 'changes-only',
+            });
+        }
+        catch (error) {
+            console.error(`aimhooman: cannot scan proposed commit ${revision}: ${error.message}`);
+            return expectedErrorCode(error);
+        }
+        emitDiagnostics(scan.diagnostics);
+        // 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. The single carve-out (a size-limit-only gap, see exitCode)
+        // warns here instead of vetoing.
+        const code = exitCode(scan.findings, scan.profile, scan.complete, {
+            failClosedIncomplete: true,
+            incompleteReasons: scan.incomplete_reasons,
+        });
+        if (code !== 0) {
+            process.stderr.write(human(scan.findings, tone()));
+            if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+            if (rejectNote) process.stderr.write(rejectNote(revision));
+            return code;
+        }
+        if (!scan.complete) {
+            // The commit's tree is the staged tree pre-commit already warned
+            // about, so this is usually the duplicate the once-guard swallows.
+            // rev-parse runs only on this rare path.
+            let treeSha = null;
+            try {
+                treeSha = execFileSync('git', ['rev-parse', `${revision}^{tree}`], {
+                    cwd: repo.root,
+                    encoding: 'utf8',
+                    timeout: GIT_TIMEOUT_MS,
+                }).trim();
+            } catch { /* warn without dedup */ }
+            warnIncompleteOnce(repo, treeSha, scan);
+        }
+    }
+    return 0;
+}
+
+function cmdPushcheck(args) {
+    parseNoArguments(args);
+    let input;
+    try { input = readFileSync(0, 'utf8'); }
+    catch (error) {
+        console.error(`aimhooman: cannot read pre-push input: ${error.message}`);
+        return 30;
+    }
+    // pre-push lines: <local ref> <local oid> <remote ref> <remote oid>. The
+    // local ref name is irrelevant (it is the raw oid for a dangling push);
+    // what matters is which objects are about to be published. Deletions
+    // (zero local oid) carry nothing and were already filtered by the
+    // dispatcher, but belt-and-braces here since pushcheck can be driven
+    // directly.
+    const updates = [];
+    for (const line of input.split('\n').filter(Boolean)) {
+        const match = /^(\S+) (\S+) (\S+) (\S+)$/.exec(line);
+        if (!match) {
+            console.error('aimhooman: malformed pre-push input; push stopped');
+            return 30;
+        }
+        const [, , localOid, remoteRef, remoteOid] = match;
+        if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(localOid)
+            || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(remoteOid)) {
+            console.error('aimhooman: malformed object ID in pre-push input; push stopped');
+            return 30;
+        }
+        if (/^0+$/.test(localOid)) continue;
+        updates.push({ oldObjectId: remoteOid, newObjectId: localOid, ref: remoteRef });
+    }
+    if (!updates.length) return 0;
+    const repo = tryRepo();
+    if (!repo) {
+        // Same bare carve-out as refcheck: a global dispatcher must stay
+        // transparent where no worktree/index policy boundary exists.
+        if (currentRepositoryIsBare()) return 0;
+        console.error('aimhooman: not a git repository');
+        return 30;
+    }
+    let commits;
+    try {
+        // Every pushed commit gets its message scanned (final `true`):
+        // publishing is the act being gated, and a rejected commit pushed by
+        // raw oid has no local branch to vouch for its message. Reachability
+        // trust stays with refs/heads/*, exactly as in refcheck — remote
+        // tracking refs arrive ungated via fetch.
+        commits = resolveIntroduced(repo, updates, { includeStagedContexts: false })
+            .map(([revision, reviewContexts]) => [revision, reviewContexts, true]);
+    }
+    catch (error) {
+        console.error(`aimhooman: cannot resolve pushed commits: ${error.message}`);
+        return 30;
+    }
+    const code = scanProposedCommits(repo, commits, {
+        rejectNote: (revision) =>
+            `aimhooman: push of commit ${revision} was rejected before any objects were sent\n`,
+    });
+    if (code !== 0) return code;
+    // Same last-veto-point integrity check as refcheck: if a chained
+    // predecessor removed any required dispatcher, every profile stops.
+    if (dispatchHooksChanged(repo, 'clean')) return 20;
+    return 0;
+}
+
 function cmdRefcheck(args) {
     const { positionals } = parseArguments(args, {
         minPositionals: 1,
@@ -734,96 +940,24 @@ function cmdRefcheck(args) {
 
     let commits;
     try {
-        const contextsByCommit = new Map();
-        // A commit's message belongs to whoever wrote it. Attribution and marker
-        // rules police the text a local developer can edit, so they are scoped
-        // to commits authored here: an update that introduces exactly one new
-        // commit on top of a non-zero old tip (a plain commit, an --amend, or a
-        // local --no-ff merge of an already-gated branch). Anything else — a new
-        // branch pulled in by `gh pr checkout` or `git fetch`, a merge of fetched
-        // history — imports other people's commit text the developer cannot
-        // change, and scanning it only blocks the review.
-        const localAuthorTips = new Set();
-        for (const update of updates) {
-            const introduced = introducedCommits(repo, [update]);
-            if (!/^0+$/.test(update.oldObjectId)
-                && introduced.length === 1
-                && introduced[0] === update.newObjectId) {
-                localAuthorTips.add(update.newObjectId);
-            }
-            for (const revision of introduced) {
-                const contexts = contextsByCommit.get(revision) || [];
-                contexts.push({
-                    head: update.newObjectId,
-                    storedTransition: revision,
-                    scanTransition: revision,
-                });
-                // A staged review is bound to the exact old tip. It can be
-                // carried into the final full-snapshot scan only for the direct
-                // proposed tip whose parent is that old tip, never for an
-                // intermediate commit or a newly created branch ancestry.
-                if (revision === update.newObjectId && !/^0+$/.test(update.oldObjectId)) {
-                    const { parents } = commitParents(repo, revision);
-                    if (parents.includes(update.oldObjectId)) {
-                        contexts.push({
-                            head: update.oldObjectId,
-                            storedTransition: 'staged',
-                            scanTransition: revision,
-                        });
-                    }
-                }
-                contextsByCommit.set(revision, contexts);
-            }
-        }
-        commits = [...contextsByCommit].map(([revision, reviewContexts]) => [
-            revision,
-            reviewContexts,
-            localAuthorTips.has(revision),
-        ]);
+        commits = resolveIntroduced(repo, updates);
     }
     catch (error) {
         console.error(`aimhooman: cannot resolve proposed commits: ${error.message}`);
         return 30;
     }
-    const limits = scanLimits();
-    for (const [revision, reviewContexts, authoredLocally] of commits) {
-        let scan;
-        try {
-            scan = scanGitTarget(repo, {
-                kind: 'commit',
-                revision,
-                reviewContexts,
-                policyMigrationContexts: reviewContexts,
-                limits,
-                messageScope: authoredLocally ? 'commit' : 'changes-only',
-            });
-        }
-        catch (error) {
-            console.error(`aimhooman: cannot scan proposed commit ${revision}: ${error.message}`);
-            return expectedErrorCode(error);
-        }
-        emitDiagnostics(scan.diagnostics);
-        // 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`);
+    const code = scanProposedCommits(repo, commits, {
+        rejectNote: (revision) =>
+            `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;
-        }
-    }
+            + '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",
+    });
+    if (code !== 0) return code;
     // The reference-transaction hook is the last veto point. If its chained
     // predecessor removed any required dispatcher, every profile stops: there
     // is no downstream guard that can repair the lost boundary safely.

package/docs/cli-reference.md

@@ -62,12 +62,16 @@ manager runs the check but registers no managed guard, so the agent hook still
 refuses the commit. Remove the override before retrying, or accept that the
 repository is unguarded and do not run `init` there.
 
-Repository `init` installs `pre-commit`, `pre-merge-commit`, `commit-msg`, and
-`reference-transaction`, and preserves an existing hook as a predecessor. For
+Repository `init` installs `pre-commit`, `pre-merge-commit`, `commit-msg`,
+`reference-transaction`, and `pre-push`, and preserves an existing hook as a
+predecessor. For
 `commit-msg`, aimhooman pins the would-be tree before the predecessor runs, so a later
 index change cannot select a weaker policy. The prepared reference transaction is the
 last local check for cherry-pick, revert, rebase, `git am`, fetch/worktree branch
-creation, and direct branch-ref updates. Every profile stops if a predecessor removes
+creation, and direct branch-ref updates. The `pre-push` hook scans every commit a push
+would introduce — including one pushed by raw object ID, which moves no local branch
+and therefore never passes the reference-transaction guard. Every profile stops if a
+predecessor removes
 a required guard; the first running dispatcher that detects the loss aborts the
 operation.
 
@@ -89,9 +93,11 @@ change, and strict previews unless `--apply` is supplied.
 `rule` (see [docs/policy.md](policy.md#overrides)).
 
 On `clean` and `compliance`, `check`, `fix`, and the commit hooks warn and continue
-when a scan is incomplete; `strict` exits 31 instead. The final ref guard
-(`reference-transaction`) stays fail-closed on every profile and still vetoes what
-it cannot fully scan.
+when a scan is incomplete; `strict` exits 31 instead. The final ref guards
+(`reference-transaction`, `pre-push`) stay fail-closed on every profile and still
+veto what they cannot fully scan — with one carve-out: a scan whose only gap is a
+file over the per-file size budget warns and continues on `clean`/`compliance`,
+because path rules still covered that file.
 
 Machine reports use `schema_version: 1` and include target policy identity, completeness,
 scan statistics, commit and object metadata. Schemas are published in [`schemas/`](../schemas/).
@@ -111,4 +117,4 @@ History cleanup is deliberately outside aimhooman's scope.
 | 11 | review-required on a non-clean profile |
 | 20 | usage, configuration, or rule-pack error |
 | 30 | Git or I/O error |
-| 31 | scan incomplete on `strict` or at the final ref guard (`clean`/`compliance` warn and continue) |
+| 31 | scan incomplete on `strict`, or at the final ref guard for any gap other than a per-file size-limit on `clean`/`compliance` (those warn and continue) |

package/docs/faq.md

@@ -16,9 +16,11 @@ and treats an incomplete scan as a stop.
 Git objects in batches. Text-oriented rules skip binary files. Size and total budgets
 are visible in reports. Files over 2 MiB or a scan over 64 MiB make the scan
 incomplete (binary files skip complete; oversized text is what trips it): direct
-checks and the Git pre-commit guards warn on `clean`/`compliance` and stop on
-`strict`, and the final ref guard stops on every profile rather than
-claiming that content was checked.
+checks and the Git guards warn on `clean`/`compliance` and stop on
+`strict`. At the final ref guard the carve-out narrows: a scan whose only gap is
+an oversized file (path rules still ran on it) warns and continues there too, while
+any other gap — a blown total budget, an unreadable object — stops on every profile
+rather than claiming that content was checked.
 
 **Can the agent bypass it?** Any local tool can ultimately be bypassed by a user with
 commit access. The agent guard fails closed on what it cannot prove: empty, invalid,

package/docs/secrets.md

@@ -60,7 +60,7 @@ three commits back still gets caught.
 ### Running it alongside aimhooman
 
 The two tools do not overlap and do not fight. aimhooman owns Git's
-`pre-commit`, `commit-msg`, and `reference-transaction` hooks; gitleaks runs
+`pre-commit`, `commit-msg`, `reference-transaction`, and `pre-push` hooks; gitleaks runs
 as a pre-commit.com hook or in CI, so both fire on the same commit without
 sharing state. A commit carrying an AI session file and an API key gets
 stopped for both reasons, each reported by the tool that owns it. Keep

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "description": "AI works. Hoomans ship. Keep AI session files and attribution out of your commits.",
     "homepage": "https://github.com/rmyndharis/aimhooman#readme",
     "repository": {

package/src/githooks.mjs

@@ -26,7 +26,15 @@ const MANAGED = {
     'pre-merge-commit': 'precommit',
     'commit-msg': 'commitmsg "$1"',
     'reference-transaction': 'refcheck "$1"',
+    'pre-push': 'pushcheck',
 };
+// Literal anchors shared by every built-in message-kind rule. The commit-msg
+// dispatcher greps the message for this ERE before paying a Node spawn: a
+// message with no anchor cannot match any attribution rule, so skipping the
+// spawn cannot let attribution through. Pinned by a test that walks
+// rules/attribution.json — a new message rule must carry one of these anchors
+// or the fast path would silently bypass it.
+export const MESSAGE_ANCHOR_ERE = 'anthropic|openai|copilot|claude|chatgpt|gpt|codex|cursor|\\[bot\\]|bot@users';
 const LEGACY_MANAGED = {
     'pre-commit': 'precommit',
     'commit-msg': 'commitmsg "$1"',
@@ -664,7 +672,57 @@ function hookScript(name, cmd, cliPath, chainedPath) {
 }
 `
         : '';
-    const captureTransaction = name === 'reference-transaction'
+    // Fast paths that skip the Node spawn for work the guard can prove is a
+    // no-op. Both sit after the chained-hook call, so a chained predecessor
+    // always runs, and both fall through to the full guard on any doubt (grep
+    // or git erroring included).
+    // - commit-msg: every built-in message rule carries one of the
+    //   MESSAGE_ANCHOR_ERE literals, so a message with no anchor match has
+    //   nothing to strip and no finding to raise. Local packs can declare
+    //   their own message rules, so their presence disables the fast path.
+    //   The tree snapshot stays at the top of the script on purpose: it must
+    //   capture the would-be tree BEFORE a chained predecessor can stage a
+    //   policy change into the live index. The fast path also yields when the
+    //   pre-commit dispatcher itself is gone: its "the tree was already
+    //   scanned" premise no longer holds, so commit-msg pays the spawn and
+    //   scans the captured tree itself.
+    // - pre-commit: an empty index holds nothing to scan (`--allow-empty`,
+    //   `commit -m` with no staged change). git diff exits 1 on staged changes
+    //   and >1 on read errors; only a proven-empty index skips.
+    // - pre-push: deletion lines (zero local oid) carry nothing to scan, so
+    //   they are dropped before the spawn; a push of only deletions never
+    //   starts Node. The chained predecessor still saw the full unfiltered
+    //   input above. The filter is grep, not a shell `case` loop: case
+    //   patterns break inside $( ) on older POSIX shells (bash 3.2 /bin/sh).
+    //   grep exit 1 means "only deletions" — not an error; anything worse
+    //   aborts the push rather than skipping the guard.
+    const preAimFilter = name === 'commit-msg'
+        ? `AIMHOOMAN_COMMON=$(PATH="$AIMHOOMAN_PATH" git rev-parse --git-common-dir 2>/dev/null) || AIMHOOMAN_COMMON=
+if [ ! -x "$(PATH="$AIMHOOMAN_PATH" dirname "$0")/pre-commit" ]; then
+  :
+elif [ -n "$AIMHOOMAN_COMMON" ] && PATH="$AIMHOOMAN_PATH" ls "$AIMHOOMAN_COMMON/aimhooman/rules/"*.json >/dev/null 2>&1; then
+  :
+else
+  PATH="$AIMHOOMAN_PATH" grep -Eiq -- ${shq(MESSAGE_ANCHOR_ERE)} "$1" 2>/dev/null
+  case $? in
+    1) exit 0 ;;
+  esac
+fi
+`
+        : name === 'pre-commit'
+            ? `PATH="$AIMHOOMAN_PATH" git diff --cached --quiet
+case $? in
+  0) exit 0 ;;
+esac
+`
+            : name === 'pre-push'
+                ? `AIMHOOMAN_PUSH_UPDATES=$(
+  printf '%s\\n' "$AIMHOOMAN_REF_UPDATES" | PATH="$AIMHOOMAN_PATH" grep -v '^[^ ]* 0* ' || [ $? -eq 1 ]
+) || exit $?
+[ -n "$AIMHOOMAN_PUSH_UPDATES" ] || exit 0
+`
+                : '';
+    const captureTransaction = name === 'reference-transaction' || name === 'pre-push'
         ? `AIMHOOMAN_REF_UPDATES=$(
   while IFS= read -r AIMHOOMAN_REF_UPDATE || [ -n "$AIMHOOMAN_REF_UPDATE" ]; do
     printf '%s\\n' "$AIMHOOMAN_REF_UPDATE" || exit $?
@@ -682,7 +740,7 @@ function hookScript(name, cmd, cliPath, chainedPath) {
     // shell (/bin/sh -p), so its shebang is honoured only for sh-compatible
     // scripts; bash-only predecessors are out of scope. exit inside the
     // predecessor exits the subshell and propagates via || exit $?.
-    const chainedInvocation = name === 'reference-transaction'
+    const chainedInvocation = name === 'reference-transaction' || name === 'pre-push'
         ? `  printf '%s\\n' "$AIMHOOMAN_REF_UPDATES" | ( . "$CHAINED" ) || exit $?`
         : `  ( . "$CHAINED" ) || exit $?`;
     const aimCommand = name === 'commit-msg'
@@ -692,7 +750,9 @@ function hookScript(name, cmd, cliPath, chainedPath) {
             : cmd;
     const aimInvocation = name === 'reference-transaction'
         ? `printf '%s\\n' "$AIMHOOMAN_REF_UPDATES" | run_aimhooman ${aimCommand} || exit $?`
-        : `run_aimhooman ${aimCommand} || exit $?`;
+        : name === 'pre-push'
+            ? `printf '%s\\n' "$AIMHOOMAN_PUSH_UPDATES" | run_aimhooman ${aimCommand} || exit $?`
+            : `run_aimhooman ${aimCommand} || exit $?`;
     // committed/aborted fire only after refs are locked in, and refcheck can do
     // nothing but return 0 for them (see cmdRefcheck). Short-circuit in the shell
     // so an ordinary commit no longer pays a Node cold start for the committed
@@ -711,7 +771,7 @@ case "$1" in prepared)
   case "$AIMHOOMAN_REF_UPDATES" in
     *refs/heads/*|*" HEAD"*) ;;
     *)
-      for AIMHOOMAN_GUARD in pre-commit pre-merge-commit commit-msg reference-transaction; do
+      for AIMHOOMAN_GUARD in pre-commit pre-merge-commit commit-msg reference-transaction pre-push; do
         [ -x "$(dirname "$0")/$AIMHOOMAN_GUARD" ] || {
           echo "aimhooman: required Git guards changed while reference-transaction was running; $AIMHOOMAN_GUARD is unavailable. The operation was stopped; run 'aimhooman init' and retry." >&2
           exit 20
@@ -779,7 +839,7 @@ fi
 if [ -x "$CHAINED" ]; then
 ${chainedInvocation}
 fi
-${phaseShortCircuit}${aimInvocation}
+${phaseShortCircuit}${preAimFilter}${aimInvocation}
 `;
     const fingerprint = hookFingerprint(template);
     return template.replace(FINGERPRINT_PLACEHOLDER, fingerprint);

package/src/report.mjs

@@ -9,13 +9,17 @@ const HUMAN_FINDING_CAP = 20;
 
 export function human(findings, tone) {
     if (!findings.length) return '';
-    let out = tone === 'professional' ? '\n' : '\nnot very hooman.\n\n';
     let block = 0;
     let review = 0;
     for (const f of findings) {
         if (f.decision === 'block') block += 1;
         else if (f.decision === 'review') review += 1;
     }
+    // The banner means "aimhooman stopped or reshaped your operation". A pure
+    // advisory (review findings only, the commit proceeds untouched) prints
+    // without it — otherwise the banner fires on allowed work and stops
+    // meaning anything when a real block lands.
+    let out = tone === 'professional' || block === 0 ? '\n' : '\nnot very hooman.\n\n';
     // Render findings in order up to the cap, then collapse the rest into one
     // summary line. Keeps the first findings fully visible (the actionable ones)
     // while bounding stderr for repeated-rule scans.
@@ -92,8 +96,13 @@ function isSensitive(finding) {
 // final ref boundary (failClosedIncomplete). Frictionless profiles warn and
 // continue — the reference-transaction guard still scans introduced commits
 // with failClosedIncomplete set, so the skipped content is checked before any
-// ref moves.
-export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false } = {}) {
+// ref moves. One exception at that final boundary: a scan whose only gap is
+// 'size-limit' (a file over maxFileBytes went unscanned for content rules —
+// path rules still ran) warns and continues on frictionless profiles. Blocking
+// the whole commit there cost developers a legit large file for a marker risk
+// that clean/compliance treat as advisory anyway. Strict stays fail-closed on
+// any gap, size-limit included.
+export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false, incompleteReasons = [] } = {}) {
     let block = false;
     let review = false;
     for (const f of findings) {
@@ -101,7 +110,11 @@ export function exitCode(findings, profile, complete = true, { failClosedIncompl
         else if (f.decision === 'review') review = true;
     }
     if (block) return 10;
-    if (!complete && (profile === 'strict' || failClosedIncomplete)) return 31;
+    if (!complete && (profile === 'strict' || failClosedIncomplete)) {
+        const sizeLimitOnly = incompleteReasons.length > 0
+            && incompleteReasons.every((reason) => reason === 'size-limit');
+        if (profile === 'strict' || !sizeLimitOnly) return 31;
+    }
     if (review && findings.some((finding) => (finding.scanProfile || profile) !== 'clean')) return 11;
     return 0;
 }

package/src/scan-session.mjs

@@ -7,6 +7,17 @@ export const DEFAULT_SCAN_LIMITS = Object.freeze({
     maxFindings: 1000,
 });
 
+// Skip reasons that mean a rule never ran on its input, so the scan cannot
+// claim full coverage. What that costs is the caller's call: strict stops on
+// any of them; the final ref guard stops on all but 'size-limit' (see
+// exitCode in report.mjs). 'local-pack-error' never originates here — it is
+// tallied by scan-target — but it belongs to the same contract.
+export const FATAL_SKIP_REASONS = new Set([
+    'metadata-unavailable', 'size-limit', 'total-byte-limit',
+    'missing-object', 'unexpected-object', 'finding-limit',
+    'local-input-limit', 'local-pack-error',
+]);
+
 export function scanEntries(repo, engine, entries, options = {}) {
     const limits = { ...DEFAULT_SCAN_LIMITS, ...options };
     const stats = {
@@ -131,12 +142,9 @@ export function scanEntries(repo, engine, entries, options = {}) {
         stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
     }
 
-    const incompleteReasons = new Set([
-        'metadata-unavailable', 'size-limit', 'total-byte-limit',
-        'missing-object', 'unexpected-object', 'finding-limit', 'local-input-limit',
-    ]);
-    const complete = !Object.keys(stats.skipped).some((reason) => incompleteReasons.has(reason));
-    return { findings, complete, stats };
+    const complete = !Object.keys(stats.skipped).some((reason) => FATAL_SKIP_REASONS.has(reason));
+    const incompleteReasons = Object.keys(stats.skipped).filter((reason) => FATAL_SKIP_REASONS.has(reason));
+    return { findings, complete, incompleteReasons, stats };
 }
 
 function readObjects(repo, objectIds, expectedBytes = 0) {

package/src/scan-target.mjs

@@ -8,7 +8,7 @@ import {
     unmergedPaths,
 } from './gitx.mjs';
 import { commitChanges, commitMessage, commitSnapshot, historyRange } from './history-scan.mjs';
-import { DEFAULT_SCAN_LIMITS, scanEntries } from './scan-session.mjs';
+import { DEFAULT_SCAN_LIMITS, FATAL_SKIP_REASONS, scanEntries } from './scan-session.mjs';
 import { loadRulesWithDiagnostics } from './rules.mjs';
 
 // A tiebreak for the one profile a range report has to name, not a strength
@@ -75,7 +75,7 @@ export function scanMessage(repo, text, options = {}) {
 
 function scanIndex(repo, options) {
     const kind = options.kind || 'staged';
-    const { rawPolicy, floor, policy, head, acknowledged } = resolveStagedPolicy(repo, options.explicitProfile);
+    const { rawPolicy, floor, policy, head, acknowledged, baselineObjectId } = resolveStagedPolicy(repo, options.explicitProfile);
     const loaded = engineForPolicy(repo, policy, options.overrideHead || head);
     const accumulator = createAccumulator(options.limits);
     accumulator.addSkipped(loaded.skipped);
@@ -96,11 +96,14 @@ function scanIndex(repo, options) {
         });
         // A reviewed-path override can suppress a matching path rule, but it
         // cannot turn an unresolved index into a complete commit snapshot.
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('index-unresolved');
     }
 
     if (floor && !isVersionedStrict(rawPolicy)) {
-        accumulator.add([protectedPolicyFinding(rawPolicy, policy, null)]);
+        accumulator.add([protectedPolicyFinding(rawPolicy, policy, null, {
+            oldObjectId: baselineObjectId,
+            transition: 'staged',
+        })]);
     }
     scanEntryGroup(repo, loaded.engine, entries, policy, accumulator, {
         allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
@@ -140,6 +143,7 @@ export function resolveStagedPolicy(repo, explicitProfile) {
         floor,
         head,
         acknowledged,
+        baselineObjectId: baselineStrict ? baseline.policy_object_id : null,
         policy: effectivePolicy(
             rawPolicy,
             explicitProfile,
@@ -209,11 +213,14 @@ function scanCommit(repo, options) {
             throw new GitRevisionError(options.revision, message);
         }
         diagnostics.push({ level: 'warning', message });
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('shallow-repository');
     }
 
     if (floor && !isVersionedStrict(rawPolicy)) {
-        accumulator.add([protectedPolicyFinding(rawPolicy, policy, snapshot)]);
+        accumulator.add([protectedPolicyFinding(rawPolicy, policy, snapshot, {
+            oldObjectId: strictParentPolicies[0]?.policy_object_id ?? null,
+            transition: snapshot.commit,
+        })]);
     }
     // A commit is judged by what it changes, not by the whole tree it inherits.
     // Scanning snapshot.entries (a full `ls-tree`) re-applied path rules to
@@ -284,7 +291,7 @@ function scanRange(repo, options) {
             throw new GitRevisionError(options.range, message);
         }
         diagnostics.push({ level: 'warning', message });
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('shallow-repository');
     }
     const policies = [];
     let usedStrictFloor = false;
@@ -336,7 +343,10 @@ function scanRange(repo, options) {
         diagnostics.push(...loaded.diagnostics);
 
         if (floor && !isVersionedStrict(rawPolicy)) {
-            accumulator.add([protectedPolicyFinding(rawPolicy, policy, commit)]);
+            accumulator.add([protectedPolicyFinding(rawPolicy, policy, commit, {
+                oldObjectId: [...parentStrictObjects][0] ?? null,
+                transition: commit.commit,
+            })]);
         }
         scanEntryGroup(repo, loaded.engine, changes.entries, policy, accumulator, {
             allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
@@ -556,12 +566,27 @@ function isVersionedStrict(policy) {
     ));
 }
 
-function protectedPolicyFinding(rawPolicy, policy, entry) {
+function protectedPolicyFinding(rawPolicy, policy, entry, migration = {}) {
     const removed = !rawPolicy.policy_object_id;
     const reason = removed
         ? 'A versioned strict project policy cannot be deleted or renamed away without a bound review acknowledgment.'
         : 'A versioned strict project policy cannot be downgraded without a bound review acknowledgment.';
-    const remediation = ['Restore the strict policy or use the reviewed migration command bound to this target.'];
+    // Name the exact command, oids included: "use the reviewed migration
+    // command" sent developers to the docs for a three-flag incantation they
+    // could not guess (field-test rerun). The staged form binds to the live
+    // index; the transition form binds to the commit that carries the change.
+    const remediation = ['Restore the strict policy, or unstage the change to keep the current baseline.'];
+    if (migration.oldObjectId && migration.transition) {
+        const newOid = rawPolicy.policy_object_id ?? 'missing';
+        const form = migration.transition === 'staged'
+            ? '--staged'
+            : `--transition ${migration.transition}`;
+        remediation.push(
+            `or acknowledge the migration: aimhooman policy-review --head HEAD ${form} --old ${migration.oldObjectId} --new ${newOid} --reason "reviewed policy migration"`
+        );
+    } else {
+        remediation.push('or acknowledge the migration with a reviewed aimhooman policy-review invocation.');
+    }
     return decorate({
         ruleId: 'generic.project-policy',
         ruleVersion: 1,
@@ -637,10 +662,10 @@ function rangeReportPolicy(basePolicy, policies, usedStrictFloor, explicitProfil
     };
 }
 
-// Skip reasons that mean a rule never ran, as opposed to a rule running and
-// matching nothing. Either way the scan cannot claim to have covered its input.
-const INCOMPLETE_SKIP_REASONS = new Set(['local-input-limit', 'local-pack-error']);
-
+// The canonical set of fatal skip reasons lives in scan-session.mjs
+// (FATAL_SKIP_REASONS); the accumulator records which of them fired so callers
+// can tell "only an oversized file went unscanned" apart from gaps that must
+// stay fail-closed.
 function createAccumulator(limits = {}) {
     const effectiveLimits = { ...DEFAULT_SCAN_LIMITS, ...limits };
     const findings = [];
@@ -657,6 +682,12 @@ function createAccumulator(limits = {}) {
         skippedPaths: {},
     };
     let complete = true;
+    const incompleteReasons = new Set();
+
+    function flagIncomplete(reason) {
+        complete = false;
+        incompleteReasons.add(reason);
+    }
 
     function add(values, total = values.length) {
         stats.findings_total += total;
@@ -667,7 +698,7 @@ function createAccumulator(limits = {}) {
                 continue;
             }
             if (findings.length >= effectiveLimits.maxFindings) {
-                complete = false;
+                flagIncomplete('finding-limit');
                 increment(stats.skipped, 'finding-limit');
                 continue;
             }
@@ -675,7 +706,7 @@ function createAccumulator(limits = {}) {
             findings.push(finding);
         }
         stats.findings_returned = findings.length;
-        if (total > values.length) complete = false;
+        if (total > values.length) flagIncomplete('finding-limit');
     }
 
     return {
@@ -698,16 +729,17 @@ function createAccumulator(limits = {}) {
                     if (stats.skippedPaths[reason].length < 10) stats.skippedPaths[reason].push(entry);
                 }
             }
+            for (const reason of scanned.incompleteReasons || []) incompleteReasons.add(reason);
             if (!scanned.complete) complete = false;
         },
         addSkipped(skipped = {}) {
             for (const [reason, count] of Object.entries(skipped)) {
                 stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
-                if (INCOMPLETE_SKIP_REASONS.has(reason)) complete = false;
+                if (FATAL_SKIP_REASONS.has(reason)) flagIncomplete(reason);
             }
         },
-        markIncomplete() {
-            complete = false;
+        markIncomplete(reason = 'target-unverifiable') {
+            flagIncomplete(reason);
         },
         remaining() {
             return Math.max(0, effectiveLimits.maxFindings - findings.length);
@@ -718,6 +750,9 @@ function createAccumulator(limits = {}) {
         isComplete() {
             return complete;
         },
+        get incompleteReasons() {
+            return [...incompleteReasons];
+        },
     };
 }
 
@@ -731,6 +766,7 @@ function result({ target, policy, accumulator, diagnostics, messageScanned, comm
             policy_enforced_object_ids: policy.enforced_policy_object_ids,
         } : {}),
         complete: accumulator.isComplete(),
+        incomplete_reasons: accumulator.incompleteReasons,
         stats: accumulator.stats,
         findings: accumulator.findings,
         diagnostics,