@rmyndharis/aimhooman 0.1.5 → 0.1.7

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
             "name": "aimhooman",
             "source": "./",
             "description": "Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
-            "version": "0.1.5",
+            "version": "0.1.7",
             "license": "MIT",
             "keywords": [
                 "git",
@@ -20,4 +20,4 @@
             ]
         }
     ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
     "name": "aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.7",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman"
     },
     "hooks": "./hooks/hooks.json"
-}
+}

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.7",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman maintainers",
@@ -34,4 +34,4 @@
         ],
         "brandColor": "#111827"
     }
-}
+}

package/CHANGELOG.md

@@ -5,6 +5,81 @@ 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.1.7] - 2026-07-18
+
+### Fixed
+
+- The final reference guard no longer holds a branch hostage to a file already
+  in its history. A commit was scanned against the full tree it inherited, so a
+  path allowed in once and then un-allowed blocked every later commit on the
+  branch, even one-line edits to an unrelated file — and the only way out was to
+  rewrite history. The guard now judges a commit by what it changes: a newly
+  staged `.env` still stops the commit, while a file the commit merely carries
+  forward from its parent stays silent. A secret already in history is not
+  forgotten — `aimhooman check --tracked` still names it — but it no longer
+  bricks the branch.
+- Imported history no longer trips the attribution guard. `gh pr checkout` and
+  `git fetch` bring in other people's commits, whose messages a local developer
+  cannot edit; scanning them for AI co-author trailers blocked the checkout
+  whenever a PR commit carried one. The guard now scopes attribution and marker
+  rules to commits written in the repository (a plain commit, an `--amend`, a
+  local merge), and leaves imported commits' messages alone. A locally authored
+  `git commit --no-verify` that smuggles the same trailer is still stopped at the
+  final guard.
+- `aimhooman status` no longer advertises a profile the hooks are not applying.
+  The enforcing guards resolve the project policy from the index, so a worktree
+  `.aimhooman.json` that has not been `git add`ed was invisible to them — yet
+  `status` reported its profile as active. `status` now shows the staged profile
+  the hooks actually enforce, prints the worktree value alongside when the two
+  differ, and names the remedy (`git add .aimhooman.json`).
+- A pipeline into a shell with no commit in it is still refused, but the reason
+  no longer tells the developer to retry a commit they never wrote. The deny
+  text for `echo x | bash` and similar now names the real shape — a pipeline
+  whose sink can run arbitrary commands — instead of reusing the commit-themed
+  message.
+- A timing or scheduling prefix no longer reads as a hook bypass. `time`,
+  `timeout`, `nice`, and `ionice` run the inner command with the same argv in the
+  same place, so `time git commit` is judged like `git commit` instead of being
+  refused as opaque shell indirection. The carve-out only applies when nothing
+  else injects risk; a `--no-verify` or a hooks-path override wrapped in the
+  prefix is still caught.
+
+## [0.1.6] - 2026-07-18
+
+### Fixed
+
+- A tracked file over the per-file scan budget no longer blocks every commit in
+  the repository. 0.1.5 content-scanned the whole tree on every commit, so a 3 MiB
+  vendored bundle that crossed the 2 MiB default budget wedged every later commit
+  with `scan incomplete (size-limit=1)` — even one-line edits to an unrelated file
+  — and the only way out was to raise the budget above the largest tracked file.
+  Path rules still run on the full tree, so a staged `.env` stays blocked, but the
+  content scan now reads only the files a commit actually changes. Editing the
+  oversized file itself still fails the commit until the budget is raised.
+- An oversized file that is binary now skips as `binary` (complete) instead of
+  `size-limit` (incomplete). A PSD, WOFF, or PNG cannot hide the text-pattern
+  secrets the content scan looks for, so it was never really an incomplete scan.
+  The first 8 KB of each oversized file is probed for a NUL byte to tell binary
+  from text; files above 16 MiB stay `size-limit` without probing, because
+  `cat-file --batch` reads the whole blob into memory and probing a 500 MB file
+  just to check for NULs is not worth it. A text file over budget stays a real
+  `size-limit` skip, and the owner must raise `AIMHOOMAN_MAX_FILE_BYTES` to cover
+  it.
+- `secret.dotenv` now excepts `*.minimal`. A `.env.minimal` shipped as a template
+  was blocked by the same rule that catches a real `.env`, because `*.sample`,
+  `*.template`, `*.dist`, and `*.defaults` were excepted but `*.minimal` was not.
+  The rule's version bumps to 4.
+
+### Added
+
+- Incomplete-scan messages name the files that were dropped and why. A budget
+  miss used to print a count (`size-limit=3`) with no path, so the owner had to
+  hunt for the offender. The CLI now lists up to five skipped paths with their
+  sizes and reason, and the JSON scan report carries a `skippedPaths` object so a
+  caller can see every dropped file the same way. The schema documents the field.
+- `aimhooman explain` prints a rule's `except` clause when it has one, so an
+  `allow`/`deny` override can be reasoned about without opening the rule pack.
+
 ## [0.1.5] - 2026-07-18
 
 ### 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.1.5-blue" alt="v0.1.5">
+  <img src="https://img.shields.io/badge/version-v0.1.7-blue" alt="v0.1.7">
   <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">
@@ -76,7 +76,7 @@ flowchart TD
     DIRECT([Sequencer or direct ref path<br/>cherry-pick · rebase · fetch · worktree · update-ref]) --> REF
     PRE -->|clean: safe repair| MSG["commit-msg snapshots would-be tree,<br/>runs predecessor, then checks<br/>the message and pinned full tree"]
     PRE -->|strict violation, incomplete scan,<br/>or failed repair| BLOCK([Operation stops])
-    MSG -->|message and tree accepted| REF["reference-transaction prepared<br/>full-scans every introduced commit"]
+    MSG -->|message and tree accepted| REF["reference-transaction prepared<br/>scans what each introduced commit changes<br/>(messages of locally authored commits only)"]
     MSG -->|unsafe or unrepairable| BLOCK
     REF -->|accepted| SHIP([Ref update commits])
     REF -->|violation or incomplete scan| BLOCK

package/bin/aimhooman.mjs

@@ -212,7 +212,24 @@ 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';
-    return `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    let message = `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    const skippedPaths = scan.stats?.skippedPaths || {};
+    const pathLines = [];
+    for (const [reason, entries] of Object.entries(skippedPaths)) {
+        for (const entry of entries.slice(0, 5)) {
+            const sizeStr = formatBytes(entry.size);
+            pathLines.push(`  skipped: ${entry.path} (${reason}, ${sizeStr})\n`);
+        }
+        if (entries.length > 5) pathLines.push(`  ... and ${entries.length - 5} more\n`);
+    }
+    return message + pathLines.join('');
+}
+
+function formatBytes(bytes) {
+    if (bytes == null || bytes < 0) return '?';
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
 function snapshotFile(path) {
@@ -582,8 +599,23 @@ 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) {
-            for (const revision of introducedCommits(repo, [update])) {
+            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,
@@ -607,14 +639,18 @@ function cmdRefcheck(args) {
                 contextsByCommit.set(revision, contexts);
             }
         }
-        commits = [...contextsByCommit];
+        commits = [...contextsByCommit].map(([revision, reviewContexts]) => [
+            revision,
+            reviewContexts,
+            localAuthorTips.has(revision),
+        ]);
     }
     catch (error) {
         console.error(`aimhooman: cannot resolve proposed commits: ${error.message}`);
         return 30;
     }
     const limits = scanLimits();
-    for (const [revision, reviewContexts] of commits) {
+    for (const [revision, reviewContexts, authoredLocally] of commits) {
         let scan;
         try {
             scan = scanGitTarget(repo, {
@@ -623,6 +659,7 @@ function cmdRefcheck(args) {
                 reviewContexts,
                 policyMigrationContexts: reviewContexts,
                 limits,
+                messageScope: authoredLocally ? 'commit' : 'changes-only',
             });
         }
         catch (error) {
@@ -910,9 +947,17 @@ function cmdStatus(args) {
         return 30;
     }
     let policy;
+    let stagedPolicy;
     let overrides;
     try {
+        // `policy` describes the worktree file as written; `stagedPolicy` is the
+        // one the enforcing hooks actually read (they resolve from the index, so
+        // a worktree profile that has not been staged is invisible to them).
+        // Reporting the worktree value alone used to advertise a profile the
+        // guard was not applying, so the two are compared below and the
+        // mismatch is named when they disagree.
         policy = resolvePolicy(repo, { target: 'worktree' });
+        stagedPolicy = resolvePolicy(repo, { target: 'staged' });
         overrides = loadOverrides(repo.stateDir);
     } catch (e) {
         console.error(`aimhooman: cannot load enforcement state: ${e.message}`);
@@ -935,9 +980,25 @@ function cmdStatus(args) {
         excludeError = e.message;
         excludes = { current: false, installed: false };
     }
-    const policyLabel = policy.source === 'worktree-policy' ? 'project' : policy.source;
-    console.log(`profile:  ${policy.profile}`);
-    console.log(`policy:   ${policyLabel} (${policy.source}, object=${policy.policy_object_id || 'none'})`);
+    // 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
+    // staged (or a file that was never `git add`ed) cannot masquerade as active.
+    const policyLabelOf = (resolved) => (
+        resolved.source === 'worktree-policy'
+        || resolved.source === 'staged-policy'
+        || resolved.source === 'commit-policy'
+    ) ? 'project' : resolved.source;
+    const enforced = stagedPolicy.profile;
+    const enforcedLabel = policyLabelOf(stagedPolicy);
+    const worktreeLabel = policyLabelOf(policy);
+    const policyDrift = policy.profile !== stagedPolicy.profile
+        || policy.policy_object_id !== stagedPolicy.policy_object_id;
+    console.log(`profile:  ${enforced}${policyDrift ? ` (worktree: ${policy.profile})` : ''}`);
+    console.log(`policy:   ${enforcedLabel} (${stagedPolicy.source}, object=${stagedPolicy.policy_object_id || 'none'})${policyDrift ? `; worktree ${worktreeLabel} (${policy.source}, object=${policy.policy_object_id || 'none'})` : ''}`);
+    if (policyDrift) {
+        console.log(`warning:  worktree .aimhooman.json is not staged, so the hooks enforce the staged profile (${enforced}); run \`git add .aimhooman.json\` to apply ${policy.profile}`);
+    }
     console.log(`hooks:    ${hooksComplete ? installed.join(', ') : installed.length ? `${installed.join(', ')} (incomplete; run: aimhooman init)` : 'not installed (run: aimhooman init)'}`);
     for (const hook of hooks) {
         console.log(`hook ${hook.name}: ${hook.managed ? 'managed' : 'not managed'}, ${hook.executable ? 'executable' : 'not executable'}, ${hook.reachable ? 'reachable' : hook.reason}`);
@@ -978,6 +1039,7 @@ function cmdExplain(args) {
     console.log(`Actions:     clean=${af('clean')} strict=${af('strict')} compliance=${af('compliance')}`);
     console.log(`Reason:      ${r.reason}`);
     if (r.match?.paths) console.log(`Paths:       ${r.match.paths.join(', ')}`);
+    if (r.match?.except) console.log(`Except:      ${r.match.except.join(', ')}`);
     if (r.match?.content) console.log(`Content:     ${r.match.content.join(', ')}`);
     if (r.remediation?.length) {
         console.log('Remediation:');

package/docs/design/frictionless-enforcement.md

@@ -55,15 +55,18 @@ enforcement requires local or global hook setup.
 | 2. Agent guard | PreToolUse reports paths and rejects unprovable protected Git mutations | plugin | advisory for paths; fail-closed for boundary bypass |
 | 3. Strict policy | `strict` profile blocks instead of repairing (exit 10) | both | block |
 | 4. Pinned tree | `commit-msg` checks the exact would-be tree and message | git hook | blocks a remaining violation or incomplete scan |
-| 5. Final ref check | prepared `reference-transaction` full-scans every commit introduced to `HEAD` or a branch | git hook | blocks a violation or incomplete scan |
+| 5. Final ref check | prepared `reference-transaction` scans what each commit introduced to `HEAD` or a branch changes (and the message of commits authored locally) | git hook | blocks a violation or incomplete scan |
 
 Default profile `clean` uses layers 0, 1, 2, 4, and 5. Successful repair keeps the
 ordinary path low-friction. The pinned-tree and final-ref scans deliberately stop if
-a block remains, including a pre-existing tracked block that was not part of the
-current diff, or if any scan is incomplete.
+a block remains on a path the commit actually changes, or if any scan is incomplete.
+A file already in history is not re-tried on every later commit: the final ref check
+judges a commit by its change set, so an inherited path no longer blocks unrelated
+work. Use `aimhooman check --tracked` (or scan the PR range in CI) to surface legacy
+secrets without bricking the branch.
 Git 2.54 also emits an earlier `preparing` reference-transaction callback. The
 hook checks dispatcher integrity there without scanning unresolved references,
-then keeps the full-scan veto at `prepared`, after Git has locked them.
+then keeps the scan veto at `prepared`, after Git has locked them.
 
 ### Frictionless agent guard (the everyday commands run)
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.7",
     "description": "AI works. Hoomans ship. Keep AI session files, secrets, and attribution out of your commits.",
     "homepage": "https://github.com/rmyndharis/aimhooman#readme",
     "repository": {
@@ -74,4 +74,4 @@
         "developer-tools",
         "pre-commit"
     ]
-}
+}

package/rules/paths.json

@@ -218,7 +218,7 @@
     },
     {
         "id": "secret.dotenv",
-        "version": 3,
+        "version": 4,
         "provider": "generic",
         "category": "secret",
         "confidence": "high",
@@ -236,7 +236,8 @@
                 "**/*.sample",
                 "**/*.template",
                 "**/*.dist",
-                "**/*.defaults"
+                "**/*.defaults",
+                "**/*.minimal"
             ]
         },
         "actions": {

package/schemas/scan-report.schema.json

@@ -82,6 +82,21 @@
                 "skipped": {
                     "type": "object",
                     "additionalProperties": { "type": "integer", "minimum": 1 }
+                },
+                "skippedPaths": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "required": ["path", "size"],
+                            "properties": {
+                                "path": { "type": "string" },
+                                "size": { "type": ["integer", "null"], "minimum": 0 }
+                            },
+                            "additionalProperties": false
+                        }
+                    }
                 }
             },
             "additionalProperties": false

package/src/hook.mjs

@@ -443,6 +443,14 @@ function hookPreToolUse(input) {
             : '--no-verify or shell indirection bypasses the pre-commit guard';
     const unmodelledPrefixReason =
         'aimhooman cannot verify the final staged snapshot or Git hooks after an earlier unmodelled command; run that command separately, then retry the commit.';
+    // A pipeline whose sink can execute code (a shell, an interpreter fed on
+    // stdin) can hide a commit or run arbitrary commands, and there is no argv
+    // to read a --no-verify out of. The earlier message reused the commit text
+    // above, which told a developer to "retry the commit" for a command that
+    // was not a commit at all — this names the real shape instead.
+    const opaquePipelineReason = commit
+        ? unmodelledPrefixReason
+        : 'aimhooman cannot prove this pipeline is read-only: a shell or code-executing segment can hide a commit or run arbitrary commands. Drop that segment (for example the `| bash`) and run the pieces separately.';
     const blocks = [];
     // potentialCommit treats a command as leading to a commit. uncertainShell
     // was too broad: it flagged any pipe, so a benign read-only pipeline
@@ -522,7 +530,7 @@ function hookPreToolUse(input) {
         if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
             return emitDecision(
                 'deny',
-                unmodelledPrefixReason,
+                opaquePipelineReason,
             );
         }
         // Nothing found and nothing to object to, so emit nothing and leave the
@@ -552,7 +560,7 @@ function hookPreToolUse(input) {
     if (profile !== 'strict' && potentialCommit && prefixHookBypass) {
         return emitDecision(
             'deny',
-            unmodelledPrefixReason,
+            opaquePipelineReason,
         );
     }
     const guarded = repo && !bypassed && installedHooks(repo).includes('pre-commit');
@@ -861,6 +869,41 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                     environmentRisk,
                     'git',
                 );
+                // A passthrough prefix (time, timeout, nice, ...) execs the inner
+                // command with the same argv in the same place, so it cannot
+                // inject a flag or hide a --no-verify the way eval/sudo/bash -c
+                // can. Re-parse the inner command from its `git` token so the
+                // commit is judged exactly as if the prefix were not there
+                // (--no-verify still denied, a clean commit still allowed). The
+                // carve-out only applies when nothing else injects risk;
+                // otherwise the wrapper falls back to the closed uncertain path.
+                const passthroughExecutable = PASSTHROUGH_PREFIX_EXECUTORS.has(shellExecutable(g0))
+                    && environmentRisk.length === 0
+                    && !targetEnvironmentRisk
+                    && !indirectTargetEnvironmentRisk
+                    && !commandTargetUncertain
+                    && !indirect.targetUncertain
+                    && !indirect.pathDialectUncertain
+                    && !commandPathDialectUncertain
+                    && !unwrapped.uncertain
+                    ? shellExecutable(g0)
+                    : null;
+                if (passthroughExecutable) {
+                    const gitIndex = toks.findIndex((token, index) => (
+                        index > 0 && isGitExecutable(token.replace(/^\(+/, '').replace(/\)+$/, ''))
+                    ));
+                    if (gitIndex > 0) {
+                        const inner = parseGit(toks.slice(gitIndex).join(' '), unwrapped.cwd);
+                        commit ||= inner.commit;
+                        noVerify ||= inner.noVerify;
+                        bypassHooks ||= inner.bypassHooks;
+                        uncertainShell ||= inner.uncertainShell;
+                        addPaths.push(...inner.addPaths);
+                        commands.push(...inner.commands);
+                        sawAdd ||= inner.addPaths.length > 0;
+                        continue;
+                    }
+                }
                 commit = true;
                 uncertainShell = true;
                 commands.push({
@@ -883,7 +926,8 @@ export function parseGit(cmd, initialCwd = process.cwd()) {
                         || indirect.pathDialectUncertain,
                 });
             }
-            if (!READ_ONLY_SHELL_COMMANDS.has(basename(g0))) {
+            if (!READ_ONLY_SHELL_COMMANDS.has(basename(g0))
+                && !PASSTHROUGH_PREFIX_EXECUTORS.has(shellExecutable(g0))) {
                 prefixIndexMutationRisk ||= commandMayReplaceIndex(toks, unit.text);
                 prefixHooksRisk ||= commandMayTouchHooks(toks, unit.text);
                 prefixRisk = true;
@@ -2687,6 +2731,19 @@ const UNCERTAIN_TARGET_INDIRECT_EXECUTORS = new Set([
     'systemd-run', 'unshare', 'watch', 'wsl', 'xargs',
 ]);
 
+// Passthrough prefixes exec the inner command verbatim: the same argv, the same
+// cwd, the same target. `time`, `timeout`, `nice`, `ionice` and friends only
+// measure or schedule — they cannot inject a flag, rewrite the command line, or
+// hide a --no-verify the way eval/sudo/bash -c can. An indirect commit seen
+// through one of these is therefore treated as direct, so `time git commit` is
+// judged like `git commit` instead of being refused as opaque indirection. The
+// carve-out only applies when nothing else is risky (no environment override,
+// no uncertain target); otherwise the wrapper falls back to the closed path.
+const PASSTHROUGH_PREFIX_EXECUTORS = new Set([
+    'time', 'timeout', 'nice', 'ionice', 'chrt', 'taskset', 'numactl',
+    'stdbuf', 'setsid', 'nohup', 'prlimit', 'faketime',
+]);
+
 function indirectCommitInvocation(words, initialCwd) {
     if (!words.length) return false;
     const executable = shellExecutable(words[0]);

package/src/scan-session.mjs

@@ -18,9 +18,11 @@ export function scanEntries(repo, engine, entries, options = {}) {
         findings_total: 0,
         findings_returned: 0,
         skipped: {},
+        skippedPaths: {},
     };
     const candidates = [];
     let selectedBytes = 0;
+    const oversized = [];
 
     for (const entry of entries) {
         if (entry.type !== 'blob') {
@@ -37,17 +39,48 @@ export function scanEntries(repo, engine, entries, options = {}) {
             continue;
         }
         if (entry.size > limits.maxFileBytes) {
-            increment(stats.skipped, 'size-limit');
+            oversized.push(entry);
             continue;
         }
         if (selectedBytes + entry.size > limits.maxTotalBytes) {
             increment(stats.skipped, 'total-byte-limit');
+            appendPath(stats.skippedPaths, 'total-byte-limit', entry.path, entry.size);
             continue;
         }
         selectedBytes += entry.size;
         candidates.push(entry);
     }
 
+    // Oversized files: probe the first 8 KB to separate binary from text.
+    // A binary file (PSD, WOFF, PNG) can't hide text-pattern secrets that
+    // the full content scan would find, so it skips as 'binary' (complete).
+    // A text file that exceeds the budget is a genuine 'size-limit' skip
+    // (incomplete) and the caller must raise the limit to cover it.
+    // Cap probing at 16 MiB: cat-file --batch reads the full blob into memory,
+    // so probing a 500 MB file just to check for NULs is wasteful. Files above
+    // the cap are classified as size-limit without probing.
+    const PROBE_CAP = 16 * 1024 * 1024;
+    const probeable = oversized.filter((entry) => entry.size <= PROBE_CAP);
+    const tooBig = oversized.filter((entry) => entry.size > PROBE_CAP);
+    for (const entry of tooBig) {
+        increment(stats.skipped, 'size-limit');
+        appendPath(stats.skippedPaths, 'size-limit', entry.path, entry.size);
+    }
+    if (probeable.length) {
+        const probeOids = [...new Set(probeable.map((entry) => entry.oid))];
+        const probes = probeObjects(repo, probeOids, probeable);
+        for (const entry of probeable) {
+            const header = probes.get(entry.oid);
+            if (header && isBinary(header)) {
+                increment(stats.skipped, 'binary');
+                appendPath(stats.skippedPaths, 'binary', entry.path, entry.size);
+            } else {
+                increment(stats.skipped, 'size-limit');
+                appendPath(stats.skippedPaths, 'size-limit', entry.path, entry.size);
+            }
+        }
+    }
+
     const objectIds = [...new Set(candidates.map((entry) => entry.oid))];
     const batch = readObjects(repo, objectIds, selectedBytes);
     stats.objects_read = batch.objects.size;
@@ -65,6 +98,7 @@ export function scanEntries(repo, engine, entries, options = {}) {
         let matched;
         if (isBinary(blob)) {
             increment(stats.skipped, 'binary');
+            appendPath(stats.skippedPaths, 'binary', entry.path, blob.length);
             // Binary classification only skips text-oriented policy rules. Secret
             // signatures are ASCII byte sequences, so latin1 preserves a
             // one-byte-to-one-code-unit view and keeps the existing byte limits.
@@ -148,10 +182,55 @@ function readObjects(repo, objectIds, expectedBytes = 0) {
     return { objects, failures };
 }
 
+// probeObjects reads the first 8000 bytes of each blob to decide whether it is
+// binary (contains a NUL). cat-file --batch outputs full blobs, so the buffer
+// must accommodate total blob sizes, but we only inspect the leading bytes.
+function probeObjects(repo, objectIds, entries) {
+    const unique = [...new Set(objectIds.filter(Boolean))];
+    if (!unique.length) return new Map();
+    const PROBE_BYTES = 8000;
+    // Sum the actual sizes so the buffer can hold the full output.
+    const sizeByOid = new Map();
+    for (const entry of entries) {
+        if (entry.oid && entry.size > 0) sizeByOid.set(entry.oid, Math.max(sizeByOid.get(entry.oid) || 0, entry.size));
+    }
+    const totalExpected = unique.reduce((sum, oid) => sum + (sizeByOid.get(oid) || 0), 0);
+    const output = execFileSync('git', ['cat-file', '--batch'], {
+        cwd: repo.root,
+        env: gitEnvironment(),
+        input: Buffer.from(unique.join('\n') + '\n'),
+        encoding: 'buffer',
+        maxBuffer: Math.max(2 * 1024 * 1024, totalExpected + unique.length * 256 + 1024),
+        timeout: GIT_TIMEOUT_MS,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const probes = new Map();
+    let offset = 0;
+    for (const requested of unique) {
+        const newline = output.indexOf(0x0a, offset);
+        if (newline < 0) break;
+        const header = output.subarray(offset, newline).toString('utf8');
+        offset = newline + 1;
+        const fields = header.split(' ');
+        if (fields[1] === 'missing' || fields.length !== 3 || fields[1] !== 'blob') continue;
+        const size = Number(fields[2]);
+        const end = offset + size;
+        if (end > output.length || output[end] !== 0x0a) break;
+        probes.set(requested, output.subarray(offset, offset + Math.min(size, PROBE_BYTES)));
+        offset = end + 1;
+    }
+    return probes;
+}
+
 function increment(record, key) {
     record[key] = (record[key] || 0) + 1;
 }
 
+function appendPath(record, reason, path, size) {
+    if (!record[reason]) record[reason] = [];
+    if (record[reason].length < 10) record[reason].push({ path, size });
+}
+
 function isBinary(buffer) {
     const length = Math.min(buffer.length, 8000);
     for (let index = 0; index < length; index++) if (buffer[index] === 0) return true;

package/src/scan-target.mjs

@@ -215,20 +215,39 @@ function scanCommit(repo, options) {
     if (floor && !isVersionedStrict(rawPolicy)) {
         accumulator.add([protectedPolicyFinding(rawPolicy, policy, snapshot)]);
     }
-    scanEntryGroup(repo, loaded.engine, snapshot.entries, policy, accumulator, {
+    // 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
+    // every file the commit merely carried forward from its parent, so a path
+    // allowed into history once (under an override that was later removed, or
+    // before the guard existed) blocked every later commit on the branch. The
+    // change set already drives content scanning; routing path rules through it
+    // too means a newly added `.env` still fires while an inherited one stays
+    // silent, matching how scanRange has always judged history.
+    scanEntryGroup(repo, loaded.engine, snapshot.changes, policy, accumulator, {
         reviewPathEntries: snapshot.changes,
+        contentEntries: snapshot.changes,
         allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
         transition: snapshot.commit,
     });
-    accumulator.add(loaded.engine.checkMessage(snapshot.message)
-        .map((finding) => decorate(finding, snapshot, policy)));
-    accumulator.addSkipped(loaded.engine.takeSkipped());
+    // The message is the author's words, so it is scanned for attribution and
+    // markers only when the commit was written here. Fetched history (a PR
+    // checked out for review, a branch pulled from a remote) carries other
+    // people's commit text that a local developer cannot edit, so flagging it
+    // only blocks the review. cmdRefcheck passes messageScope='changes-only'
+    // for commits that were imported rather than authored; a direct `aimhooman
+    // check --commit` still defaults to scanning the message.
+    const scanMessageText = options.messageScope !== 'changes-only';
+    if (scanMessageText) {
+        accumulator.add(loaded.engine.checkMessage(snapshot.message)
+            .map((finding) => decorate(finding, snapshot, policy)));
+        accumulator.addSkipped(loaded.engine.takeSkipped());
+    }
     return result({
         target: `commit:${snapshot.commit}`,
         policy,
         accumulator,
         diagnostics,
-        messageScanned: true,
+        messageScanned: scanMessageText,
         commit: snapshot.commit,
     });
 }
@@ -367,8 +386,15 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
         })
             .map((finding) => decorate(finding, entry, policy)));
     }
+    // Content scanning can target a narrower set than the path check. When
+    // contentEntries is provided (e.g. only changed files in a commit), read
+    // blobs only for those entries instead of the full snapshot. Path-based
+    // rules already ran on the full tree above, so secrets like .env are still
+    // caught even when their blob isn't re-read.
+    const contentScannable = (options.contentEntries ?? entries)
+        .filter((entry) => entry.status !== 'D' && entry.type !== 'deleted');
     const remaining = accumulator.remaining();
-    const scanned = scanEntries(repo, engine, scannable, {
+    const scanned = scanEntries(repo, engine, contentScannable, {
         maxFileBytes: accumulator.limits.maxFileBytes,
         maxTotalBytes: accumulator.remainingBytes(),
         maxFindings: remaining,
@@ -628,6 +654,7 @@ function createAccumulator(limits = {}) {
         findings_total: 0,
         findings_returned: 0,
         skipped: {},
+        skippedPaths: {},
     };
     let complete = true;
 
@@ -665,6 +692,12 @@ function createAccumulator(limits = {}) {
             for (const [reason, count] of Object.entries(scanned.stats.skipped || {})) {
                 stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
             }
+            for (const [reason, paths] of Object.entries(scanned.stats.skippedPaths || {})) {
+                if (!stats.skippedPaths[reason]) stats.skippedPaths[reason] = [];
+                for (const entry of paths) {
+                    if (stats.skippedPaths[reason].length < 10) stats.skippedPaths[reason].push(entry);
+                }
+            }
             if (!scanned.complete) complete = false;
         },
         addSkipped(skipped = {}) {