@rmyndharis/aimhooman 0.3.0 → 0.3.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

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

package/.cursor/rules/aimhooman.mdc

@@ -1,5 +1,5 @@
 ---
-description: aimhooman - keep AI session files, secrets, and unwanted AI attribution out of Git.
+description: aimhooman - keep AI session files and unwanted AI attribution out of Git.
 globs:
 alwaysApply: true
 ---

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.3.1] - 2026-07-19
+
+### Fixed
+
+- `fix` on a strict policy no longer exits 11 (review required) when the
+  message holds a removable attribution line but the recheck of the cleaned
+  message stays incomplete; it exits 31, the same verdict `--apply` reaches
+  for the same content.
+- `commitmsg` printed the blocking "scan incomplete … and retry" framing for
+  a tree scan that stopped at exit 11 on the compliance profile; the framing
+  now follows the profile, matching `check` and `fix`.
+- `loadOverrides` burned the full lock retry budget (~50 × 10 ms) when a
+  caller already held `overrides.json.lock` (every `allow`/`deny`/`override`/
+  `review`/`policy-review` write); the warn-once migration persist now takes
+  one lock attempt and skips quietly when the lock is held.
+- Two-arg `loadConfig(stateDir, root)` dropped the per-clone `gitignore`
+  record whenever a project policy owned the profile; the record is now read
+  best effort from config.json.
+- Session-start hook: a failed `.git/info/exclude` refresh no longer skips
+  the worktree `.gitignore` refresh; each has its own silent failure, like
+  the pre-tool-use path.
+- `uninstall` now also sweeps the worktree `.gitignore` lock queue left by
+  `init --gitignore`; the sweep previously covered only the three `.git`-side
+  queues.
+- `action.yml` gained a `version` input (default `latest`) so the installed
+  CLI can be pinned (pinning the action tag never pinned the CLI), and its
+  `actions/setup-node` step is pinned to the same SHA the test workflow uses.
+- The tarball now ships `docs/secrets.md`, `docs/policy.md`,
+  `docs/cli-reference.md`, `docs/faq.md`, and `docs/integrations.md`; links
+  to them from the README and the catalog dangled inside node_modules.
+- Documentation and comment accuracy: the Cursor manifest description and the
+  usage and integrations exit-code lines no longer mention secret scanning
+  and now name the strict/final-guard scope of exit 31; the README flowchart
+  no longer implies an incomplete scan blocks pre-commit on every profile;
+  `docs/policy.md` states correctly that strict turns policy-file and
+  agent-instruction findings into blocks and that only the policy
+  downgrade/removal block is allow-proof; the 0.3.0 binary bullet, the FAQ
+  budget answer, and two stale comments now describe what the code does.
+
+### Removed
+
+- Dead code: the unreachable `release` branch of
+  `scripts/scan-ci-history.mjs` (no workflow sets that context) along with
+  `selectReleaseBase` and the `RELEASE_ENVIRONMENT_VERIFIED` contract; the
+  never-produced `object-read-failed` incomplete reason; the callerless
+  `repeatable` option in the argument parser; and eight unused `node:fs`
+  imports in `src/gitx.mjs`.
+
 ## [0.3.0] - 2026-07-19
 
 This release narrows aimhooman to the job it does better than anyone else:
@@ -30,8 +78,11 @@ reference-transaction guard keeps its veto on every profile.
   `overrides.json` are dropped on load with a warning naming the file.
   A secret already in history needs rotation and a gitleaks run, not
   aimhooman.
-- With no rule reading binary content, an oversized binary file no longer
-  makes a scan incomplete; oversized text still does.
+- In-budget binary blobs are no longer content-scanned: v0.2.0 read their
+  bytes for secrets, and with the scanner gone they now skip as binary. The
+  oversized-file probe is unchanged — binary up to 16 MiB still skips
+  complete, and binary over it is still a size-limit skip that leaves the
+  scan incomplete.
 
 ### Added
 

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/rmyndharis/aimhooman/test.yml?branch=main&label=CI" alt="CI">
-  <img src="https://img.shields.io/badge/version-v0.3.0-blue" alt="v0.3.0">
+  <img src="https://img.shields.io/badge/version-v0.3.1-blue" alt="v0.3.1">
   <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">
@@ -52,7 +52,7 @@ flowchart TD
     COMMIT([Ordinary git commit or merge]) --> PRE["pre-commit / pre-merge-commit<br/>run predecessor, resolve staged policy,<br/>scan exact index"]
     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])
+    PRE -->|strict violation or failed repair| BLOCK([Operation stops])
     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])

package/bin/aimhooman.mjs

@@ -611,7 +611,7 @@ function cmdCommitmsg(args) {
         const treeCode = exitCode(treeScan.findings, treeScan.profile, treeScan.complete);
         if (treeCode !== 0) {
             if (treeScan.findings.length) process.stderr.write(human(treeScan.findings, tone()));
-            if (!treeScan.complete) process.stderr.write(incompleteMessage(treeScan));
+            if (!treeScan.complete) process.stderr.write(incompleteMessage(treeScan, { blocking: treeScan.profile === 'strict' }));
             return treeCode;
         }
         // exitCode passes an incomplete tree scan on frictionless profiles; the
@@ -1645,9 +1645,13 @@ function cmdFix(args) {
                     ? `aimhooman: strict policy would remove ${repair.removed.length} exact attribution line(s); rerun with --apply to write the repair`
                     : 'aimhooman: strict policy found no automatically repairable attribution lines'
             );
+            // 11 asks a human to review the lines a repair would remove, which is
+            // only honest when the recheck saw the whole message. An incomplete
+            // recheck on strict fails closed (31) — the same verdict --apply
+            // reaches below for the same content.
             return remaining.some((finding) => finding.decision === 'block')
                 ? 10
-                : repair.removed.length ? 11 : exitCode(remaining, scan.profile, remainingComplete);
+                : repair.removed.length && remainingComplete ? 11 : exitCode(remaining, scan.profile, remainingComplete);
         }
     } else if (options.apply) {
         throw new ArgumentError('--apply is only needed when the active profile is strict');
@@ -1975,6 +1979,7 @@ function cmdUninstall(args) {
     for (const queue of [
         `${lifecycleLock}.queue`,
         `${repo.excludeFile}.aimhooman.lock.queue`,
+        `${join(repo.root, '.gitignore')}.aimhooman.lock.queue`,
         join(effectiveHooksDir(repo), '.aimhooman-hooks.lock.queue'),
     ]) {
         try { rmdirSync(queue); } catch { /* held by another aimhooman, or already gone */ }
@@ -2030,7 +2035,8 @@ Usage:
   aimhooman version
 
 Exit codes: 0 clean, 10 blocked, 11 review required, 20 invalid input or policy,
-30 Git or I/O failure, 31 incomplete scan.
+30 Git or I/O failure, 31 incomplete scan on strict or at the final ref guard
+(clean/compliance warn and continue).
 `);
 }
 

package/docs/cli-reference.md

@@ -0,0 +1,114 @@
+# 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`, and
+`reference-transaction`, and preserves an existing hook as a predecessor. For
+`commit-msg`, aimhooman pins the would-be tree before the predecessor runs, so a later
+index change cannot select a weaker policy. The prepared reference transaction is the
+last local check for cherry-pick, revert, rebase, `git am`, fetch/worktree branch
+creation, and direct branch-ref updates. Every profile stops if a predecessor removes
+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 guard
+(`reference-transaction`) stays fail-closed on every profile and still vetoes what
+it cannot fully scan.
+
+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 (`clean`/`compliance` warn and continue) |

package/docs/faq.md

@@ -0,0 +1,60 @@
+# 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 pre-commit guards warn on `clean`/`compliance` and stop on
+`strict`, and the final ref guard stops on every profile rather than
+claiming that content was checked.
+
+**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`, and `reference-transaction` 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.3.1",
     "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/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 */

package/src/report.mjs

@@ -34,10 +34,11 @@ export function human(findings, tone) {
             out += `       > ${isSensitive(f) ? '[redacted]' : visible(f.text.trim())}\n`;
         }
         // Render the whole remediation array, not just the first entry. Several
-        // rules carry a second line (e.g. "rotate the key if it was ever exposed")
-        // that the previous single-index render dropped silently. UT-08: print a
-        // rule's fix once — a repeated rule (20 hits of the same secret rule)
-        // used to reprint the identical fix block for every finding.
+        // rules carry a second line (e.g. "or unstage if it is personal" on
+        // generic.agent-instructions) that the previous single-index render
+        // dropped silently. UT-08: print a rule's fix once — a repeated rule
+        // (20 hits of the same path rule) used to reprint the identical fix
+        // block for every finding.
         const remedies = f.remediation || [];
         if (remedies.length && fixesPrinted.has(f.ruleId)) {
             out += `       fix: as above for ${f.ruleId}\n`;

package/src/scan-session.mjs

@@ -132,7 +132,7 @@ export function scanEntries(repo, engine, entries, options = {}) {
     }
 
     const incompleteReasons = new Set([
-        'metadata-unavailable', 'size-limit', 'total-byte-limit', 'object-read-failed',
+        'metadata-unavailable', 'size-limit', 'total-byte-limit',
         'missing-object', 'unexpected-object', 'finding-limit', 'local-input-limit',
     ]);
     const complete = !Object.keys(stats.skipped).some((reason) => incompleteReasons.has(reason));

package/src/state.mjs

@@ -4,7 +4,7 @@ import {
     readFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { atomicWrite } from './atomic-write.mjs';
+import { atomicWrite, withLock } from './atomic-write.mjs';
 import { normalizeGitPath } from './git-path.mjs';
 
 // Per-repository state, stored in the common Git dir (never the worktree).
@@ -105,8 +105,20 @@ export function parseProjectPolicy(text, file = '.aimhooman.json') {
 
 export function loadConfig(stateDir, root) {
     const project = loadProjectPolicy(root);
-    if (project) return { profile: project.profile, source: 'project', file: project.file };
     const file = join(stateDir, 'config.json');
+    if (project) {
+        // The project policy owns the profile, but the --gitignore opt-in stays
+        // per-clone state in config.json; a two-arg caller still needs it. The
+        // profile no longer depends on that file here, so a missing or corrupt
+        // one just omits the record instead of failing the load.
+        const gitignore = readGitignoreRecord(file);
+        return {
+            profile: project.profile,
+            source: 'project',
+            file: project.file,
+            ...(gitignore ? { gitignore } : {}),
+        };
+    }
     let text;
     try {
         text = readFileSync(file, 'utf8');
@@ -129,6 +141,17 @@ export function loadConfig(stateDir, root) {
     };
 }
 
+// Best-effort read of the per-clone gitignore record for the project-policy
+// branch above: any failure (absent file, invalid JSON, invalid shape) means
+// no record, never a failed load.
+function readGitignoreRecord(file) {
+    try {
+        return normalizeLocalConfig(JSON.parse(stripBom(readFileSync(file, 'utf8'))), file).gitignore;
+    } catch {
+        return undefined;
+    }
+}
+
 export function saveConfig(stateDir, config) {
     const file = join(stateDir, 'config.json');
     const normalized = normalizeLocalConfig(config, file);
@@ -193,7 +216,28 @@ export function loadOverrides(stateDir) {
         if (error?.code === 'ENOENT') return { allow: [], deny: [] };
         throw new LocalOverridesError(file, `cannot read file: ${error.message}`, error);
     }
-    return parseOverrides(text, file);
+    const dropped = { count: 0 };
+    const overrides = parseOverrides(text, file, dropped);
+    if (dropped.count) {
+        process.stderr.write(
+            `aimhooman: warning: ${file}: dropped ${dropped.count} override(s) with retired scope "secret-path"; built-in secret scanning was removed in v0.3.0\n`
+        );
+        // Persist the cleaned file so the migration warns once, not on every
+        // command. Re-read under the lock so a concurrent allow/deny write is
+        // never clobbered; a failed rewrite only means the warning returns
+        // next run, so this stays best effort. One attempt, no queue wait:
+        // allow/deny/override/review/policy-review call loadOverrides while
+        // already holding this same lock, and the bakery queue would park the
+        // inner candidate behind the outer one for the full retry budget
+        // before the catch below swallowed the throw.
+        try {
+            withLock(`${file}.lock`, () => {
+                const fresh = parseOverrides(readFileSync(file, 'utf8'), file);
+                atomicWriteJson(file, { schema_version: 1, ...fresh });
+            }, { retries: 1 });
+        } catch { /* best effort */ }
+    }
+    return overrides;
 }
 
 export function saveOverrides(stateDir, overrides) {
@@ -207,17 +251,17 @@ export function normalizeOverrideTarget(target) {
     return normalizeGitPath(target);
 }
 
-function parseOverrides(text, file) {
+function parseOverrides(text, file, dropped = { count: 0 }) {
     let value;
     try {
         value = JSON.parse(stripBom(text));
     } catch (error) {
         throw new LocalOverridesError(file, `invalid JSON: ${error.message}`, error);
     }
-    return normalizeOverrides(value, file);
+    return normalizeOverrides(value, file, dropped);
 }
 
-function normalizeOverrides(value, file) {
+function normalizeOverrides(value, file, dropped = { count: 0 }) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new LocalOverridesError(file, 'root must be a JSON object');
     }
@@ -230,17 +274,13 @@ function normalizeOverrides(value, file) {
     if (value.schema_version !== undefined && value.schema_version !== 1) {
         throw new LocalOverridesError(file, 'schema_version must be 1');
     }
-    const dropped = { count: 0 };
-    const normalized = {
+    // The caller owns the drop count: loadOverrides warns and persists the
+    // cleaned file, saveOverrides drops retired entries silently on the next
+    // write.
+    return {
         allow: overrideEntries(value.allow, 'allow', file, dropped),
         deny: overrideEntries(value.deny, 'deny', file, dropped),
     };
-    if (dropped.count) {
-        process.stderr.write(
-            `aimhooman: warning: ${file}: dropped ${dropped.count} override(s) with retired scope "secret-path"; built-in secret scanning was removed in v0.3.0\n`
-        );
-    }
-    return normalized;
 }
 
 function overrideEntries(value, key, file, dropped = { count: 0 }) {
@@ -251,8 +291,8 @@ function overrideEntries(value, key, file, dropped = { count: 0 }) {
     return value.map((entry, index) => {
         // Built-in secret scanning and its secret-path override scope were
         // removed in v0.3.0. An overrides file written by an older version may
-        // still carry such entries; drop them (one warning per file, below)
-        // instead of failing the whole load.
+        // still carry such entries; drop them (loadOverrides warns once and
+        // persists the cleaned file) instead of failing the whole load.
         if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.scope === 'secret-path') {
             dropped.count += 1;
             return null;