@rmyndharis/aimhooman 0.1.2 → 0.1.3

package/.agents/rules/aimhooman.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

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.2",
+            "version": "0.1.3",
             "license": "MIT",
             "keywords": [
                 "git",

package/.claude-plugin/plugin.json

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

package/.clinerules/aimhooman.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/.codex-plugin/plugin.json

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

package/.cursor/rules/aimhooman.mdc

@@ -11,7 +11,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -21,8 +21,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/.github/copilot-instructions.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/.kiro/steering/aimhooman.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/.windsurf/rules/aimhooman.md

@@ -9,7 +9,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -19,8 +19,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/AGENTS.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.3] - 2026-07-18
+
+### Fixed
+
+- Repair that empties the index no longer mints an empty commit. Stage only a `.env`,
+  run `git commit -m "add config"`, and the pre-commit repair unstages it and prints
+  "the commit will be empty" — then Git made that empty commit anyway. Git refuses a
+  commit with nothing staged, but repair runs after Git has already decided to proceed,
+  so carrying on created a commit Git would never have made and left a junk commit to
+  `git reset --hard`. Pre-commit now exits 10 when the repair empties the index, so Git
+  stops. Nothing else staged means nothing to commit.
+- `build && git add . && git commit` is no longer denied. Each half already passed on its
+  own; only the pair was refused. The commit-time-staging deny asked the wide bypass
+  predicate — the one that decides whether the staged-content backstop reads the blobs —
+  instead of the narrow question of whether anything will scan the commit. An unmodelled
+  prefix is not a bypass, and pre-commit still scans the real index at commit time. The
+  deny now asks that narrow question. A prefix that reaches the hooks, `--no-verify`, and
+  a real `core.hooksPath` override all keep the deny, where the staged files really would
+  go unscanned. The refusal message no longer names "--no-verify or shell indirection"
+  when neither is present.
+- The `PreToolUse` guard stops refusing more everyday read-only pipelines. Building on the
+  0.1.1 filter allowance, a read-only Git subcommand is now an allowed pipe source, so
+  `git log | head`, `git status | grep modified`, `git diff | cat`, and
+  `cd repo && git log | head` run. Build and test toolchains (`npm`, `cargo`, `make`,
+  `jest`, `eslint`, `tsc`, `pytest`) are allowed as a source. The listing forms of
+  branch/tag/remote/stash/notes run (`git branch | grep`, `git remote -v | grep origin`),
+  while their mutating forms (`git branch -D`, `git tag v1`) stay denied. Git as a pipe
+  sink, `git commit --no-verify`, and `git push` still deny; the reference-transaction and
+  pre-commit hooks remain the boundary.
+
 ## [0.1.2] - 2026-07-17
 
 ### Removed

package/GEMINI.md

@@ -5,7 +5,7 @@ This repository uses aimhooman to keep AI tooling artifacts out of Git history.
 Its policy:
 
 - Never stage or commit local AI session/state files. Examples include
-  `.claude.json`, `.claude/.credentials.json`, `.claude/session*.json`,
+  `.claude.json`, `.claude/session*.json`,
   `.claude/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
   `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
   `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
@@ -15,8 +15,10 @@ Its policy:
   exhaustive; the packaged `rules/paths.json` is the detection source of truth.
   If one is staged, unstage it and keep it out of Git instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
-  (`id_rsa` and files containing a private-key header), `.aws/credentials`, or
-  service-account keys. Public certificates are allowed.
+  (`id_rsa` and files containing a private-key header), `.aws/credentials`,
+  `.claude/.credentials.json`, service-account keys, or a provider API key
+  (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
+  SendGrid). Public certificates are allowed.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.

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.2-blue" alt="v0.1.2">
+  <img src="https://img.shields.io/badge/version-v0.1.3-blue" alt="v0.1.3">
   <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">
@@ -154,8 +154,11 @@ ignores `.git/hooks`. Repository `init` installs and chains predecessors only wh
 that directory is absent or is proven to be owned by the repository: inside it and
 not tracked by Git. It refuses to modify a global, shared, external, or tracked
 hook directory, because a dispatcher committed from one machine names paths that
-exist only on that machine. In that case, integrate
-aimhooman into the existing hook manager or remove the override before retrying.
+exist only on that machine. Those repositories are not guarded, and there is no
+way to guard them today. Calling `aimhooman precommit` from an existing hook
+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
@@ -238,7 +241,8 @@ files automatically.
   `.agent/`. [`rules/paths.json`](rules/paths.json) is the complete catalog.
 - **Secrets**: a real `.env` (not `.env.example`), private-key content,
   `.aws/credentials`, service-account private keys, recognized AWS secret/session
-  assignments, and provider token prefixes for GitHub, GitLab, npm, and Slack.
+  assignments, and provider token prefixes for GitHub, GitLab, npm, Slack,
+  Anthropic, OpenAI, Google, Stripe, Hugging Face, and SendGrid.
   Public certificates are allowed.
 - **AI attribution** in commit messages: known AI `Co-authored-by:` identities,
   exact "Generated with/by ..." lines, and AI-service noreply attribution trailers.
@@ -410,9 +414,13 @@ that would open an editor, and commits with an active foreign `prepare-commit-ms
 It still cannot prove that every program already selected by local Git config is safe.
 Commands assembled from files, encoded data, or network input may also be invisible to
 its non-executing shell parser (POSIX shells — bash, sh, zsh, dash, ksh — and
-`git.exe`; command nesting, pipelines, background jobs, and non-POSIX executors
-such as PowerShell or fish are classified uncertain and, on `strict`, denied
-with a retry instruction). Repository selection written in non-POSIX shell syntax
+`git.exe`). Everyday read-only pipelines run, because a read-only source cannot hide or
+feed a commit: `git log | head`, `git status | grep modified`, `git diff | cat`,
+`git branch | grep`, `npm test | tail`, `cargo build 2>&1 | grep error`, and
+`cd repo && git log | head` all pass. What stays uncertain and, on `strict`, is denied
+with a retry instruction: a git command as a pipe *sink* (`cat patch | git apply`),
+pipe-to-shell (`curl x | bash`), command nesting, background jobs, and non-POSIX
+executors such as PowerShell or fish. Repository selection written in non-POSIX shell syntax
 is denied before policy lookup on every profile. Guarded Git changes, including
 `add`, commit, and ref updates, also reject shell-expanded targets, any leading-tilde
 target, POSIX targets beginning with exactly `//`, and an explicit split

package/bin/aimhooman.mjs

@@ -59,6 +59,42 @@ function tone() {
     return process.env.AIMHOOMAN_TONE === 'professional' || process.env.CI ? 'professional' : 'playful';
 }
 
+// The per-scan budget sizes the `cat-file --batch` read buffer, so a value that
+// travelled with a clone would let a hostile repository drive the verifier out
+// of memory instead of being rejected by it. These stay in the environment for
+// that reason, never in .aimhooman.json, and a raise is capped for the same one.
+// Lowering needs no ceiling: a smaller budget only skips more, and a skip is
+// already an incomplete scan, which fails closed at 31.
+const MAX_SCAN_LIMIT_BYTES = 1 << 30;
+
+// Crossing a scan budget marks the scan incomplete on every profile, and an
+// incomplete scan is a ref update the reference-transaction hook refuses — the
+// one boundary --no-verify does not skip. A repository tracking a lockfile, an
+// image or a vendored bundle over the default therefore could not commit at all,
+// and "reduce the target or limits and retry" named something no flag, schema
+// field or config key could do. This is that knob.
+function scanLimits() {
+    const limits = {};
+    for (const [key, name] of [
+        ['maxFileBytes', 'AIMHOOMAN_MAX_FILE_BYTES'],
+        ['maxTotalBytes', 'AIMHOOMAN_MAX_TOTAL_BYTES'],
+    ]) {
+        const raw = process.env[name];
+        if (raw === undefined || raw === '') continue;
+        if (!/^\d+$/.test(raw)) {
+            throw new ArgumentError(`${name} must be a whole number of bytes; got "${visible(raw)}"`);
+        }
+        const value = Number(raw);
+        if (value < 1 || value > MAX_SCAN_LIMIT_BYTES) {
+            throw new ArgumentError(
+                `${name} must be between 1 and ${MAX_SCAN_LIMIT_BYTES} bytes; got ${raw}`
+            );
+        }
+        limits[key] = value;
+    }
+    return limits;
+}
+
 function configuredEngine(profile, repo) {
     const { engine, errors } = newEngineWithDiagnostics(profile, repo?.stateDir);
     if (errors.length && profile === 'strict') {
@@ -166,10 +202,16 @@ function incompleteMessage(scan) {
         .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.
+    // 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.
+    const budgeted = reasons['size-limit'] || reasons['total-byte-limit'];
     const hint = reasons['local-pack-error']
         ? 'fix the reported rule pack and retry'
-        : 'reduce the target or limits and retry';
+        : 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`;
 }
 
@@ -256,9 +298,10 @@ function cmdPrecommit(args) {
     parseNoArguments(args);
     const repo = tryRepo();
     if (!repo) { console.error('aimhooman: not a git repository'); return 30; }
+    const limits = scanLimits();
     let scan;
     try {
-        scan = scanGitTarget(repo, { kind: 'staged' });
+        scan = scanGitTarget(repo, { kind: 'staged', limits });
     } catch (e) {
         console.error(`aimhooman: cannot scan staged content: ${e.message}`);
         return expectedErrorCode(e);
@@ -284,6 +327,7 @@ function cmdPrecommit(args) {
         return 10;
     }
     const paths = [...new Set(blocks.map((f) => f.path).filter(Boolean))];
+    let emptied = false;
     try {
         const unstageTargets = new Set(paths);
         for (const finding of blocks) {
@@ -292,15 +336,15 @@ function cmdPrecommit(args) {
             }
         }
         for (const source of stagedRenameSources(repo, paths)) unstageTargets.add(source);
-        // The empty-commit hint is derived from the staged paths captured before
-        // repair, not from a second git read after `git restore --staged`. That
-        // post-repair read followed an index write and could transiently report
-        // the wrong state under heavy CI load, flaking the repair tests.
-        // unstagePaths is atomic (it throws on failure), so when every staged
-        // path is a repair target the index matches HEAD afterward. The capture
-        // is best-effort and runs before the repair: if this read fails the
-        // unstage still runs and the hint is omitted (empty stays false) rather
-        // than skipping the repair or blocking the commit.
+        // Whether the repair empties the index is derived from the staged paths
+        // captured before repair, not from a second git read after
+        // `git restore --staged`. That post-repair read followed an index write
+        // and could transiently report the wrong state under heavy CI load,
+        // flaking the repair tests. unstagePaths is atomic (it throws on
+        // failure), so when every staged path is a repair target the index
+        // matches HEAD afterward. The capture is best-effort and runs before the
+        // repair: if this read fails the unstage still runs and the commit is
+        // left to proceed rather than blocked on a state we could not read.
         let stagedBefore;
         try {
             stagedBefore = stagedPaths(repo);
@@ -325,10 +369,10 @@ function cmdPrecommit(args) {
             if (!pending.length) break;
             unstagePaths(repo, pending);
         }
-        const empty = stagedBefore !== null
+        emptied = stagedBefore !== null
             && stagedBefore.every((path) => unstageTargets.has(path));
         process.stderr.write(
-            `aimhooman: unstaged ${paths.length} AI artifact(s) from this commit: ${paths.map(visible).join(', ')}${empty ? ' (nothing else staged — the commit will be empty)' : ''}\n`
+            `aimhooman: unstaged ${paths.length} file(s) from this commit: ${paths.map(visible).join(', ')}${emptied ? ' — nothing else was staged, so the commit is stopped rather than left empty' : ''}\n`
         );
     } catch (e) {
         process.stderr.write(
@@ -337,8 +381,20 @@ function cmdPrecommit(args) {
         );
         return 10;
     }
-    if (reviews.length) process.stderr.write(human(reviews, tone()));
+    // 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.
+    process.stderr.write(human([...blocks, ...reviews], tone()));
     if (!scan.complete) process.stderr.write(incompleteMessage(scan));
+    // 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;
 }
 
@@ -380,12 +436,13 @@ function cmdCommitmsg(args) {
     }
     const text = messageBytes.toString('utf8');
     const validUtf8 = Buffer.from(text, 'utf8').equals(messageBytes);
+    const limits = scanLimits();
     let scan;
     let treeScan = null;
     try {
         const checked = againstWouldBeTree(() => ({
             message: scanMessage(repo, text, { target: 'staged' }),
-            tree: options.tree ? scanGitTarget(repo, { kind: 'staged' }) : null,
+            tree: options.tree ? scanGitTarget(repo, { kind: 'staged', limits }) : null,
         }));
         scan = checked.message;
         treeScan = checked.tree;
@@ -461,18 +518,12 @@ function cmdRefcheck(args) {
     if (phase === 'committed' || phase === 'aborted') return 0;
 
     const repo = tryRepo();
-    if (!repo) {
-        // Global hooks also run in bare repositories. Bare repositories have no
-        // worktree/index policy boundary and are intentionally unsupported, so
-        // a global dispatcher must remain transparent there instead of making
-        // every receive-pack or update-ref fail merely because --show-toplevel
-        // is unavailable.
-        if (currentRepositoryIsBare()) return 0;
-        console.error('aimhooman: not a git repository');
-        return 30;
-    }
     if (phase === 'preparing') {
-        return dispatchHooksChanged(repo, 'clean') ? 20 : 0;
+        // This phase never scans, and without a repository there is no
+        // dispatcher directory to inspect either. Git fires it while `git init`
+        // is still building the repository, so refusing here would only stop
+        // repository creation on behalf of a phase with nothing to say.
+        return repo && dispatchHooksChanged(repo, 'clean') ? 20 : 0;
     }
     let input;
     try { input = readFileSync(0, 'utf8'); }
@@ -499,6 +550,31 @@ function cmdRefcheck(args) {
         updates.push({ oldObjectId, newObjectId, ref });
     }
 
+    if (!repo) {
+        // Git writes the initial HEAD inside a reference transaction and fires
+        // this hook while the repository is still being built: GIT_DIR is
+        // exported but nothing can be queried yet, so every rev-parse fails,
+        // --is-bare-repository included. The bare carve-out below therefore
+        // cannot speak for `git init` or `git init --bare`, and reading the
+        // silence as "not a git repository" aborted the transaction and left a
+        // half-built .git behind that a second `git init` could not repair.
+        // That payload is `0000..0000 ref:refs/heads/<name> HEAD`, which the
+        // symref filter above already dropped, so no policy-relevant update
+        // survives and there is nothing to scan. The scope is "the payload
+        // carries nothing", never "git failed to answer": a transaction holding
+        // a real object still demands a repository, so no one can disable the
+        // last veto by arranging for openRepo to fail.
+        if (!updates.length) return 0;
+        // Global hooks also run in bare repositories. Bare repositories have no
+        // worktree/index policy boundary and are intentionally unsupported, so
+        // a global dispatcher must remain transparent there instead of making
+        // every receive-pack or update-ref fail merely because --show-toplevel
+        // is unavailable.
+        if (currentRepositoryIsBare()) return 0;
+        console.error('aimhooman: not a git repository');
+        return 30;
+    }
+
     let commits;
     try {
         const contextsByCommit = new Map();
@@ -533,6 +609,7 @@ function cmdRefcheck(args) {
         console.error(`aimhooman: cannot resolve proposed commits: ${error.message}`);
         return 30;
     }
+    const limits = scanLimits();
     for (const [revision, reviewContexts] of commits) {
         let scan;
         try {
@@ -541,6 +618,7 @@ function cmdRefcheck(args) {
                 revision,
                 reviewContexts,
                 policyMigrationContexts: reviewContexts,
+                limits,
             });
         }
         catch (error) {
@@ -593,6 +671,7 @@ function cmdCheck(args) {
             return 30;
         }
     }
+    const limits = scanLimits();
     let scan;
     try {
         if (o.message && !o.staged && !o.tracked) {
@@ -606,6 +685,7 @@ function cmdCheck(args) {
                 revision: o.commit,
                 range: o.range,
                 explicitProfile: o.profile,
+                limits,
                 ...(o.message ? { messageText } : {}),
             });
         }
@@ -1537,7 +1617,18 @@ function cmdUninstall(args) {
     }
     return withLock(join(repo.commonDir, 'aimhooman-lifecycle.lock'), () => {
     const rep = uninstallHooks(repo);
-    removeExclude(repo.excludeFile);
+    // The irreversible work is already done above, and the report is still
+    // below. A throw from here unwound past all of it, so a damaged marker was
+    // the only thing the user heard while four dispatchers kept guarding every
+    // commit. Report the failure beside the removal report instead of in place
+    // of it. Nothing is swallowed: this is also where the symlink and permission
+    // guards surface, and their messages still reach the user and still exit 30.
+    let excludeFailure = '';
+    try {
+        removeExclude(repo.excludeFile);
+    } catch (error) {
+        excludeFailure = `exclude block left in ${repo.excludeFile}: ${error.message}`;
+    }
     // Trust the directory, not the report. Every refusal below leaves a working
     // dispatcher behind, and one printed under "uninstalled" reads as done.
     const remaining = remainingDispatchers(repo);
@@ -1552,6 +1643,7 @@ function cmdUninstall(args) {
     if (rep.restored.length) console.log(`  hooks restored: ${rep.restored.join(', ')}`);
     for (const w of rep.warnings || []) console.log(`  warning: ${w}`);
     for (const f of rep.failures || []) console.error(`  failure: ${f}`);
+    if (excludeFailure) console.error(`  failure: ${excludeFailure}`);
     const unrestored = purge ? unrestoredChainedBackups(repo) : [];
     if (purge) {
         // Never wipe stateDir while a predecessor hook backup is still on disk:
@@ -1587,7 +1679,9 @@ function cmdUninstall(args) {
         console.log('  eligible non-bare repositories that inherit core.hooksPath are still guarded.');
         console.log('  run `aimhooman uninstall --global` to remove it.');
     }
-    return remaining.length || rep.failures?.length || unrestored.length ? 30 : 0;
+    // The managed block is still in the exclude file and still ignoring paths, so
+    // the uninstall is genuinely incomplete and 30 is the honest answer.
+    return remaining.length || rep.failures?.length || unrestored.length || excludeFailure ? 30 : 0;
     }, LIFECYCLE_LOCK_OPTIONS);
 }
 

package/docs/design/frictionless-enforcement.md

@@ -65,6 +65,30 @@ 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.
 
+### Frictionless agent guard (the everyday commands run)
+
+The layer-2 PreToolUse guard reports paths and refuses unprovable protected Git
+mutations. It does not stand between a developer and the commands they run to read a
+repository. A read-only Git subcommand piped to a filter is a source: `git log | head`,
+`git status | grep modified`, `git diff | cat`, and the `cd repo && git log | head`
+prefix produce stdout for the downstream filter and cannot hide or feed a commit, so
+they run with no refusal. Build and test toolchains (`npm`, `cargo`, `make`, `jest`,
+`eslint`, `tsc`, `pytest`, ...) are allowed as a source for the same reason. The listing
+forms of branch/tag/remote/stash/notes move no ref and run; their mutating forms
+(`git branch -D`, `git tag v1`) still reach the reference-transaction guard. A commit
+made of already-safe halves runs as a whole: `build && git add . && git commit` is
+allowed, because an unmodelled prefix is not a bypass and pre-commit still scans the real
+index at commit time.
+
+What stays refused is what can actually get past the scan. Git as a pipe sink
+(`cat patch | git apply`) reads stdin, which can drive `apply`/`am`/`hash-object`.
+Pipe-to-shell, subshells, `eval`, command substitution, and readers that execute their
+own input stay opaque. `git commit --no-verify`, an explicit `core.hooksPath` override,
+and `git push` refuse on the tiers that own them. The boundary that decides whether a
+commit is scanned is the pre-commit and reference-transaction hook, never a denial of the
+shell line that reads the repo. Refusing the read taught agents to drop the `&&` gate
+rather than run the command on its own, which is the friction this tier exists to avoid.
+
 ### Components
 
 1. **Rule catalog** — `rules/paths.json`, `rules/attribution.json`,
@@ -118,6 +142,10 @@ means local rules only add restrictions and can never override a core block.
   transparent in unsupported bare repositories.
 - **HEAD-safe unstage.** `git restore --staged` needs HEAD; on a repository's
   initial commit it falls back to `git rm --cached --ignore-unmatch`.
+- **Repair never mints an empty commit.** When the pre-commit repair unstages the last
+  staged path (stage only a `.env`, then `git commit`), it exits 10 so Git stops, the
+  same outcome as committing with nothing staged. Carrying on would create a commit Git
+  itself would have refused and leave the developer a junk commit to `git reset --hard`.
 - **Anchored attribution rules.** The AI-noreply rule is anchored to trailer
   lines (`*-by:`) so it never strips a prose line that merely mentions the email.
 - **`compliance` keeps disclosure.** AI-attribution rules resolve to `allow`

package/package.json

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