@rmyndharis/aimhooman 0.3.0 → 0.4.0

package/docs/cli-reference.md

@@ -0,0 +1,120 @@
+# CLI reference
+
+```
+aimhooman init | status | check | audit | scan | explain | allow | deny | override | review | policy-review | fix | doctor | uninstall | version
+```
+
+## Install and init
+
+Node 22.8+ and Git 2.28+, zero runtime dependencies, ships as source. Git 2.28
+is required for the prepared-phase reference transaction guard that checks
+cherry-pick, revert, rebase, `git am`, and other ref-producing flows.
+
+```sh
+npm install -g @rmyndharis/aimhooman
+```
+
+Guard a repository:
+
+```sh
+aimhooman init        # git hooks + local excludes; normally no worktree files
+aimhooman init --gitignore # also write the managed AI-artifact block to the worktree .gitignore
+aimhooman status
+aimhooman uninstall   # restore hooks/excludes; keep local policy state
+aimhooman uninstall --purge-state # also delete common Git-directory state
+```
+
+`init --gitignore` is the opt-in for teams that want the ignore set committed:
+it writes the same managed pattern block into the worktree `.gitignore`,
+records the choice in the local config, and prints a notice to commit the file
+so every clone shares it. `status` shows the recorded choice, and `uninstall`
+removes the block (and the file, if aimhooman created it and nothing else
+remains). The default stays local: `.git/info/exclude` only.
+
+Two honest edges. `uninstall` deletes the `.gitignore` itself only when
+aimhooman created it and the removed block leaves it empty — if you committed
+the file, that deletion is a tracked worktree deletion you then commit or
+restore. And the opt-in record lives in the common Git directory, so linked
+worktrees share the choice while each worktree keeps its own `.gitignore`.
+
+For commits you make at the terminal (outside your AI tool), one global setup guards
+eligible non-bare repositories that do not override `core.hooksPath` locally:
+
+```sh
+aimhooman init --global --yes # advanced: change core.hooksPath after confirmation
+aimhooman uninstall --global # unset it
+```
+
+Global `core.hooksPath` changes Git behavior for repositories that inherit it and can
+replace their default hook directory. A local or worktree-scoped override takes
+precedence. Bare repositories are outside the worktree/index policy boundary and the
+global dispatchers leave them unchanged. `status` shows both local and global values.
+Prefer repository `init` unless the global ordering is understood.
+
+When `core.hooksPath` is set, Git reads hooks only from that effective directory and
+ignores `.git/hooks`. Repository `init` installs and chains predecessors only when
+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. 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`,
+`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. 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.
+
+## Commands
+
+`check` accepts one Git target (`--staged`, `--tracked`, `--commit <rev>`, or
+`--range <base>...<head>`), plus `--message <file>`, `--profile`, and `--json`.
+Commit and range targets read commit messages from Git automatically. A range scans each
+introduced commit, so a bad file added and deleted before the endpoint is still reported.
+Use an all-zero object ID as the base when there is no prior commit; this includes the root
+commit. Deleting an ordinary forbidden path is not itself a finding, while removing or
+lowering a versioned strict project policy still needs a bound policy review.
+`audit` and `scan` are aliases for a full tracked-index scan.
+`init --global --yes` and `uninstall --global` manage the advanced terminal-Git guard;
+`uninstall --global` cannot be combined with the local `--purge-state` option.
+`fix` follows the active profile: clean writes an exact safe repair, compliance makes no
+change, and strict previews unless `--apply` is supplied.
+`allow` resolves a finding by path or rule ID; an allow entry's scope is `path` or
+`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 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/).
+
+For an existing repository, start with `aimhooman audit --json`. If a residue path is
+already tracked, remove it from the index with `git rm --cached <path>` and add an
+appropriate ignore/exclude. aimhooman does not scan for secrets; if one was committed,
+rotate it first — [docs/secrets.md](secrets.md) covers why and what to run instead.
+History cleanup is deliberately outside aimhooman's scope.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | clean, or non-blocking review |
+| 10 | policy violation (block) |
+| 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 for any gap other than a per-file size-limit on `clean`/`compliance` (those warn and continue) |

package/docs/faq.md

@@ -0,0 +1,62 @@
+# FAQ
+
+**Is this a way to hide AI use?** No. aimhooman removes operational residue and
+establishes human ownership. It never changes author, committer, signature, or
+timestamp, and the compliance profile keeps any disclosure your policy requires.
+
+**Will it cancel my commits?** On the default `clean` profile, aimhooman first tries to
+exclude or unstage hygiene artifacts and safely remove exact attribution lines. The
+commit proceeds if no block remains; a scan that runs over budget warns and continues.
+A pre-existing tracked block, failed unstage/repair, or unterminated exact attribution
+still stops the operation, and the final `reference-transaction` guard vetoes a commit
+it cannot fully scan, on every profile. `strict` cancels findings instead of repairing,
+and treats an incomplete scan as a stop.
+
+**Does it slow commits down?** The staged check runs locally with no network and reads
+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 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,
+or non-object hook JSON, missing managed final guards, and hook or receive-pack
+indirection around protected ref mutations are denied on every profile, and `strict`
+additionally rejects `--no-verify`, unknown executor shapes, and uncertain commit
+execution. Read-only commands and pipelines run; the guard stands between the agent
+and protected Git mutations, not between you and reading a repository. Git hooks are
+not a sandbox: an editor or another local program started during a commit has the same
+filesystem access and can change a later hook. Wrappers that can select another cwd or
+filesystem namespace (`sudo`, `chroot`, WSL, sandbox launchers) fail closed on every
+profile; retry as a direct Git command from the target repository. Treat local
+executables and Git config as trusted. For team enforcement, scan the actual PR range
+in CI (a normal CI checkout has no staged changes):
+
+```sh
+git fetch origin main
+aimhooman check --range origin/main...HEAD --profile strict
+```
+
+On GitHub Actions, configure `actions/checkout` with `fetch-depth: 0` so the
+triple-dot merge base is available.
+
+`pre-commit` and `commit-msg` do not cover every sequencer or ref movement. The managed
+`reference-transaction` hook therefore checks introduced commits during Git's prepared
+phase and can abort the local ref update. Git 2.54's earlier `preparing` callback is
+accepted for compatibility and checks guard integrity; scanning remains in `prepared`,
+after references are locked.
+CI still scans the exact pushed or PR history:
+local hooks do not govern another clone, server-side updates, or history created before
+the guard was installed.
+Bare repositories have no worktree/index boundary and are not supported by local commands.
+A submodule is a separate repository with separate state and hooks; run `aimhooman init`
+inside each submodule that needs local enforcement.
+
+**What about secrets?** aimhooman does not scan for secrets since v0.3.0 and never
+did history cleanup. A committed credential is exposed: rotate it, then run a
+dedicated scanner over the repository. [docs/secrets.md](secrets.md) explains the
+reasoning and shows the gitleaks setup we recommend.

package/docs/integrations.md

@@ -0,0 +1,108 @@
+# Integrations
+
+aimhooman runs wherever commits get checked: as a pre-commit.com hook, as a
+GitHub Action, and next to other hook tooling. This page shows each setup and
+what it does and does not cover.
+
+## pre-commit.com
+
+The repository ships a `.pre-commit-hooks.yaml`, so pre-commit installs
+aimhooman straight from Git. Add this to `.pre-commit-config.yaml` and run
+`pre-commit install`:
+
+```yaml
+repos:
+  - repo: https://github.com/rmyndharis/aimhooman
+    rev: v0.3.0
+    hooks:
+      - id: aimhooman
+```
+
+pre-commit npm-installs the package at the pinned revision and runs
+`aimhooman check --staged` on every commit. Pin `rev` to a tag and bump it
+deliberately.
+
+The hook checks the staged tree, so it passes no filenames. Any non-zero
+exit fails it: 10 for a policy violation, 11 for a review-required finding on
+a non-clean profile, 20 for a usage or configuration error, 30 for a Git or
+I/O error, 31 when a scan budget leaves the scan incomplete on `strict` or at
+the final ref guard (`clean`/`compliance` warn and continue). On the default
+`clean` profile a review-only finding exits 0, so reviews alone do not fail
+the hook. Blocks always do.
+
+This hook is the CLI check only. It does not install aimhooman's managed Git
+hooks or the agent guard; `aimhooman init` in the repository adds those.
+
+## GitHub Actions
+
+The repository root has an `action.yml`, so a workflow can scan the exact
+pull request range:
+
+```yaml
+# .github/workflows/aimhooman.yml
+name: aimhooman
+on: [pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: rmyndharis/aimhooman@v0.3.0
+        with:
+          base: ${{ github.event.pull_request.base.sha }}
+          head: ${{ github.event.pull_request.head.sha }}
+```
+
+`fetch-depth: 0` is required. The range is triple-dot, so the scan starts at
+the merge base of the two commits, and a shallow checkout does not have that
+commit. The action installs aimhooman from npm and defaults to the `strict`
+profile; set `profile:` under `with:` to change that.
+
+Pinning the action tag (`@v0.3.0`) pins only the action's steps, not the CLI:
+the action npm-installs aimhooman at run time, and the `version` input
+defaults to `latest`. Set `version:` under `with:` (for example
+`version: 0.3.0`) to pin the CLI itself.
+
+For `push` events, use `base: ${{ github.event.before }}` and
+`head: ${{ github.event.after }}`. On the first push to a branch `before` is
+all zeros; `aimhooman check --range` accepts an all-zero base and includes
+the root commit in the scan.
+
+CI is the enforcement tier that travels with the repository: local hooks do
+not govern another clone, and a laptop can skip its own hooks. The action
+cannot.
+
+## Secrets
+
+aimhooman does not scan for secrets. Pair it with
+[gitleaks](https://github.com/gitleaks/gitleaks), either as a pre-commit.com
+hook or as a second CI job next to the action above.
+[docs/secrets.md](secrets.md) explains why the built-in scanner was removed
+and shows both gitleaks setups.
+
+## husky
+
+husky sets `core.hooksPath` to `.husky`. `aimhooman init` refuses to install
+into or over an external or shared hooks directory by design: `.husky` is
+tracked repository content, and a dispatcher written there would stage this
+machine's absolute CLI and Node paths for everyone who clones
+(`src/githooks.mjs` has the full rule set). Two ways out:
+
+- Keep husky and call `aimhooman check --staged` from `.husky/pre-commit`.
+  You get the CLI check only. The agent-tier guard (PreToolUse) asks for
+  aimhooman's own managed hooks and refuses guarded commits without them, so
+  agent-driven commits stay unguarded in this setup.
+- Drop husky for the guarded hooks and let `aimhooman init` manage them.
+  Existing hooks are not lost: init preserves each one as a chained
+  predecessor, and the dispatcher runs it before its own check.
+
+## lint-staged
+
+lint-staged builds a list of staged files and runs one command per batch.
+aimhooman does not fit that shape: it reads the whole index and commit from
+Git and takes no file list, so a per-batch invocation would check the same
+index several times. Run it at hook level instead, through its own managed
+hooks or the pre-commit.com setup above.

package/docs/policy.md

@@ -0,0 +1,82 @@
+# Team policy and overrides
+
+aimhooman's per-clone defaults serve a solo developer. This page covers the
+team layer: a versioned policy file, owner-authorized changes to protected
+paths in CI, local overrides, and local rule packs.
+
+## Versioned team policy
+
+Commit `.aimhooman.json` when every clone should use the same baseline:
+
+```json
+{
+  "schema_version": 1,
+  "profile": "strict"
+}
+```
+
+The project policy takes precedence over the per-clone profile written by `init`.
+An individual `check` may escalate to `--profile strict`, but cannot weaken or replace
+the team profile. Malformed project policy fails closed with an actionable error;
+personal allow/deny exceptions and local rule packs remain in the common Git directory
+under `aimhooman/`.
+Under `strict`, policy files and agent instructions are blocking findings (exit 10):
+both rules' strict action is `block`, not review. The product's `review` and
+`policy-review` commands record local, object-bound decisions. An ordinary path or
+rule allow does satisfy those engine findings; the one finding an allow cannot
+satisfy is the strict-policy downgrade-or-removal block, which is constructed
+outside the engine and clears only through a bound `policy-review` acknowledgment.
+
+### Owner authorization in CI
+
+For a protected-path change, CI verifies the pinned repository and owner login plus
+numeric IDs through the GitHub API, then inspects the exact workflow-run attempt.
+GitHub must attribute both `actor` and `triggering_actor`, including their numeric IDs,
+to that owner. CI then binds the authorization to the exact head, transition commit,
+path, resulting blob and regular-file mode, or deletion tombstone. A strict-policy
+migration also binds its old and new policy objects. A different attempt, commit, path
+result, mode, or policy transition needs fresh authorization. A change not attributed to
+the owner fails closed. This is owner authorization verified through GitHub attribution,
+not independent review.
+
+## Overrides
+
+Every decision has a rule ID, so you can resolve a finding narrowly:
+
+```sh
+aimhooman allow AGENTS.md --reason "shared team config"   # stop flagging this path
+aimhooman deny  path/or/rule-id                            # always block it
+aimhooman explain claude.session-state                     # why a rule fires
+```
+
+Overrides live in the repository's common Git directory under
+`aimhooman/overrides.json` (local, never committed), so linked worktrees share them.
+An allow entry's scope is `path` or `rule`.
+
+```sh
+aimhooman override list --json
+aimhooman override remove AGENTS.md
+aimhooman override reset --all
+```
+
+Secret scanning left the product in v0.3.0, and the `secret-path` allow scope went
+with it: existing `secret-path` entries are dropped on load with a warning, and the
+rest of the file keeps working. Use a dedicated scanner for credentials instead —
+[docs/secrets.md](secrets.md) explains the reasoning and shows the gitleaks setup.
+
+## Local rule packs
+
+Add your own per-repository detection with local rule packs in the common Git directory
+under `aimhooman/rules/*.json`
+(the structural schema is in [`schemas/rule-pack.schema.json`](../schemas/rule-pack.schema.json);
+local rules only add detection — they can't weaken
+a built-in block). Within one rule, local content patterns are capped at 32 expressions,
+512 characters per expression, and 4,096 characters total. Path and exception scopes
+share the same glob count, per-expression, and total limits. They use a flat subset: literals,
+character classes, anchors, dot, escapes, and fixed `{n}` repeats. Groups, alternation,
+lookaround, backreferences, and variable quantifiers are rejected. A local expression
+does not run on a line longer than 16,384 characters; that skip is reported and makes the
+scan incomplete. Path rules are case-sensitive by default. Set
+`match.path_case` to `"insensitive"` only for a security name whose meaning is
+case-insensitive, such as `.env`; matching folds that rule's candidate and patterns but
+does not change the Git path or override identity.

package/docs/secrets.md

@@ -0,0 +1,83 @@
+# Secrets and aimhooman
+
+aimhooman v0.3.0 removed built-in secret scanning. This page explains why and
+shows the setup we recommend instead.
+
+## Why the built-in scanner went away
+
+aimhooman does one job: it keeps AI tooling residue (session files, local
+state, AI attribution) out of Git history. Secret scanning is a different
+craft. A serious scanner tracks hundreds of credential formats, tunes for
+entropy and false positives, and ships pattern updates on its own cadence.
+aimhooman's eight rules could not keep up with that, and a scanner that only
+sometimes works is worse than none: it reads as coverage it never had. Use a
+tool that does secrets full-time. We recommend [gitleaks](https://github.com/gitleaks/gitleaks).
+
+Two things do stay. The agent-facing policy still tells agents never to commit
+secrets, because an instruction costs nothing. And a local rule pack can still
+declare `category: "secret"`; findings from such a rule keep their matched
+text redacted in every report.
+
+## Recommended setup: gitleaks
+
+### Pre-commit hook (pre-commit.com)
+
+Add this to `.pre-commit-config.yaml` and run `pre-commit install`:
+
+```yaml
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+```
+
+The hook scans staged changes and stops the commit when a credential shows
+up. Pin `rev` and bump it deliberately.
+
+### GitHub Action
+
+Laptops bypass hooks; CI should not. Add a workflow step that scans pull
+requests:
+
+```yaml
+# .github/workflows/gitleaks.yml
+name: gitleaks
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+```
+
+`fetch-depth: 0` gives the action the full history so a secret introduced
+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`, `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
+aimhooman for AI hygiene, keep gitleaks for secrets, and let each report in
+its own words.
+
+## Migrating from the built-in scanner
+
+Two escape hatches left with the scanner:
+
+- `aimhooman allow <path> --scope secret-path` is gone. Existing
+  `secret-path` entries in `overrides.json` are dropped on load with a
+  warning; the rest of the file keeps working.
+- `aimhooman init --grandfather-secrets` is gone.
+
+If secrets already sit in your history, aimhooman was never the fix and
+removing it changes nothing about that: a committed credential is exposed.
+Rotate it, then run `gitleaks git` (or `gitleaks detect`) over the repository
+to find anything else that needs rotation. Scrubbing history is optional and
+secondary; rotation is not.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.3.0",
+    "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": {
@@ -23,6 +23,11 @@
         "docs/hosts.json",
         "docs/ai-artifacts.gitignore",
         "docs/catalog.md",
+        "docs/secrets.md",
+        "docs/policy.md",
+        "docs/cli-reference.md",
+        "docs/faq.md",
+        "docs/integrations.md",
         "docs/design/",
         "docs/logo/",
         ".claude-plugin/",

package/src/args.mjs

@@ -27,7 +27,7 @@ export function parseArguments(args, definition = {}) {
             const inlineValue = equal > 0 ? argument.slice(equal + 1) : undefined;
             const option = byName.get(name);
             if (!option) throw new ArgumentError(`unknown option "${name}"`);
-            if (seen.has(option.key) && !option.repeatable) {
+            if (seen.has(option.key)) {
                 throw new ArgumentError(`option "${name}" may only be used once`);
             }
             seen.add(option.key);
@@ -49,12 +49,7 @@ export function parseArguments(args, definition = {}) {
             if (option.choices && !option.choices.includes(value)) {
                 throw new ArgumentError(`invalid value for ${name}: "${value}"`);
             }
-            if (option.repeatable) {
-                if (!options[option.key]) options[option.key] = [];
-                options[option.key].push(value);
-            } else {
-                options[option.key] = value;
-            }
+            options[option.key] = value;
             continue;
         }
         positionals.push(argument);

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/gitx.mjs

@@ -1,17 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import {
-    cpSync,
-    lstatSync,
-    mkdirSync,
-    mkdtempSync,
-    readFileSync,
-    realpathSync,
-    readdirSync,
-    readlinkSync,
-    renameSync,
-    rmSync,
-    symlinkSync,
-} from 'node:fs';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 

package/src/hook.mjs

@@ -86,12 +86,23 @@ export function hookSessionStart() {
         const policy = resolvePolicy(repo, { target: 'worktree' });
         const { engine: eng } = newEngineWithDiagnostics(policy.profile, repo.stateDir);
         const patterns = patternsForRules(eng.rules);
-        applyExclude(repo.excludeFile, patterns);
+        // Each refresh is housekeeping with its own silent failure, mirroring
+        // the pre-tool-use path: a read-only .git/info must not skip the
+        // worktree .gitignore refresh below, and neither may decide anything.
+        try {
+            applyExclude(repo.excludeFile, patterns);
+        } catch {
+            /* exclude refresh is best effort */
+        }
         // A clone that opted into the committed variant gets the same refresh in
         // its worktree .gitignore; every failure degrades silently, same as the
         // exclude write above.
-        if (loadConfig(repo.stateDir).gitignore?.enabled) {
-            applyExclude(join(repo.root, '.gitignore'), patterns);
+        try {
+            if (loadConfig(repo.stateDir).gitignore?.enabled) {
+                applyExclude(join(repo.root, '.gitignore'), patterns);
+            }
+        } catch {
+            /* gitignore refresh is best effort */
         }
     } catch {
         /* not a repo; nothing to exclude */