npm - @rmyndharis/aimhooman - Versions diffs - 0.2.0 → 0.3.1 - Mend

@rmyndharis/aimhooman 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

package/.agents/rules/aimhooman.md +9 -6
package/.claude-plugin/marketplace.json +3 -3
package/.claude-plugin/plugin.json +2 -2
package/.clinerules/aimhooman.md +9 -6
package/.codex-plugin/plugin.json +3 -3
package/.cursor/rules/aimhooman.mdc +10 -7
package/.github/copilot-instructions.md +9 -6
package/.kiro/steering/aimhooman.md +9 -6
package/.windsurf/rules/aimhooman.md +9 -6
package/AGENTS.md +9 -6
package/CHANGELOG.md +111 -0
package/CONTRIBUTING.md +2 -3
package/GEMINI.md +9 -6
package/README.md +57 -376
package/SECURITY.md +6 -4
package/bin/aimhooman.mjs +134 -143
package/docs/ai-artifacts.gitignore +63 -0
package/docs/catalog.md +41 -0
package/docs/cli-reference.md +114 -0
package/docs/design/frictionless-enforcement.md +27 -17
package/docs/faq.md +60 -0
package/docs/integrations.md +108 -0
package/docs/policy.md +82 -0
package/docs/secrets.md +83 -0
package/hooks/hooks.json +1 -1
package/package.json +10 -2
package/rules/paths.json +0 -114
package/schemas/overrides.schema.json +4 -1
package/skills/aimhooman/SKILL.md +11 -8
package/src/args.mjs +2 -7
package/src/exclude.mjs +2 -2
package/src/gitx.mjs +1 -13
package/src/hook.mjs +44 -12
package/src/report.mjs +17 -41
package/src/scan-session.mjs +15 -22
package/src/scan-target.mjs +10 -10
package/src/scan.mjs +9 -24
package/src/state.mjs +104 -15
package/rules/secrets.json +0 -96

package/docs/cli-reference.md ADDED Viewed

@@ -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/design/frictionless-enforcement.md CHANGED Viewed

@@ -2,19 +2,23 @@
 This document describes aimhooman's enforcement model. aimhooman is designed to
 prevent known AI-tool residue from leaking into Git history **without editing
-`.gitignore`, and with repair before rejection on the default ordinary commit path.**
-Plugin startup provides best-effort prevention without `init`; complete Git-boundary
-enforcement requires local or global hook setup.
+`.gitignore` by default, and with repair before rejection on the default ordinary
+commit path.** Plugin startup provides best-effort prevention without `init`;
+complete Git-boundary enforcement requires local or global hook setup.
 ## Goals
 - **Zero-activation for Claude Code:** the plugin is active every session
   (SessionStart), no `init`.
-- **No `.gitignore` burden:** known AI artifacts are auto-excluded via
-  `.git/info/exclude` (local, never committed, never the user's `.gitignore`).
+- **No `.gitignore` burden by default:** known AI artifacts are auto-excluded via
+  `.git/info/exclude` (local, never committed). `init --gitignore` is the opt-in
+  variant that writes the same managed block to the worktree `.gitignore`, so a
+  team can commit it and share the ignore set across clones.
 - **Repair-first for hygiene by default:** AI artifacts are excluded before
-  staging or unstaged at commit. If a block cannot be repaired, remains in the
-  pinned tree, or cannot be scanned completely, the operation stops.
+  staging or unstaged at commit. If a block cannot be repaired or remains in the
+  pinned tree, the operation stops. An incomplete scan warns on
+  `clean`/`compliance` and stops on `strict`; the final ref guard stops on it
+  at every profile.
 - **Broad, community-updatable rule catalog:** covers many AI tools; extendable
   via PR (core) and local rules (personal).
 - **Block remains available as opt-in** (`strict` profile) for teams that want
@@ -41,8 +45,9 @@ enforcement requires local or global hook setup.
 3. **PreToolUse cannot unstage.** It runs before the tool executes; at `git add X`,
    X is not staged yet. So unstage is a git-tier (`pre-commit`) capability; the
    plugin tier does prevention (excludes) plus advisory (warn).
-4. **`.gitignore` stays clean** because aimhooman writes `.git/info/exclude`
-   (local, not committed, not `.gitignore`).
+4. **`.gitignore` stays clean by default** because aimhooman writes
+   `.git/info/exclude` (local, not committed). The opt-in `init --gitignore`
+   writes the same managed block to `.gitignore` for teams that want it committed.
 ## Design
@@ -54,16 +59,18 @@ enforcement requires local or global hook setup.
 | 1. Catch-all | `pre-commit` hook unstages AI artifacts from the index | git hook | proceeds after repair; stops if repair fails |
 | 2. Agent guard | PreToolUse reports paths and rejects unprovable protected Git mutations | plugin | advisory for paths; fail-closed for boundary bypass |
 | 3. Strict policy | `strict` profile blocks instead of repairing (exit 10) | both | block |
-| 4. Pinned tree | `commit-msg` checks the exact would-be tree and message | git hook | blocks a remaining violation or incomplete scan |
+| 4. Pinned tree | `commit-msg` checks the exact would-be tree and message | git hook | blocks a remaining violation; an incomplete scan warns on clean/compliance, stops on strict |
 | 5. Final ref check | prepared `reference-transaction` scans what each commit introduced to `HEAD` or a branch changes (and the message of commits authored locally) | git hook | blocks a violation or incomplete scan |
 Default profile `clean` uses layers 0, 1, 2, 4, and 5. Successful repair keeps the
 ordinary path low-friction. The pinned-tree and final-ref scans deliberately stop if
-a block remains on a path the commit actually changes, or if any scan is incomplete.
+a block remains on a path the commit actually changes. The final-ref scan also stops
+when it is incomplete, on every profile; an incomplete pinned-tree scan warns on
+`clean`/`compliance` and stops on `strict`.
 A file already in history is not re-tried on every later commit: the final ref check
 judges a commit by its change set, so an inherited path no longer blocks unrelated
 work. Use `aimhooman check --tracked` (or scan the PR range in CI) to surface legacy
-secrets without bricking the branch.
+artifacts without bricking the branch.
 Git 2.54 also emits an earlier `preparing` reference-transaction callback. The
 hook checks dispatcher integrity there without scanning unresolved references,
 then keeps the scan veto at `prepared`, after Git has locked them.
@@ -95,14 +102,15 @@ rather than run the command on its own, which is the friction this tier exists t
 ### Components
 1. **Rule catalog** — `rules/paths.json`, `rules/attribution.json`,
-   `rules/markers.json`, `rules/secrets.json`. Covers Claude, Codex, Copilot, Cursor, Aider, SpecStory,
+   `rules/markers.json`. Covers Claude, Codex, Copilot, Cursor, Aider, SpecStory,
    Continue, Playwright MCP, Remember, Superpowers, and a generic agent dir.
    Community extends via PR (core); personal extensions via
    `<common-git-dir>/aimhooman/rules/*.json` (local, shared by linked worktrees,
    loaded after core, and only able to add restrictions).
 2. **Auto-exclude** — `applyExclude` writes patterns derived from unambiguous
    `ephemeral-state` and `local-settings` rules to `.git/info/exclude` from
-   SessionStart, init, and the agent guard. Secrets and review paths remain visible.
+   SessionStart, init, and the agent guard. Review-required and policy paths
+   remain visible.
 3. **Git boundary** — the `pre-commit` hook scans staged paths; for any AI
    artifact it removes it from the index, then lets the commit proceed only when
    that repair succeeds. `commit-msg` removes complete exact high-confidence attribution lines
@@ -133,8 +141,10 @@ means local rules only add restrictions and can never override a core block.
 ## Implementation notes
 - **Category-aware failure.** On `clean`, a malformed local rule pack is skipped
-  with a warning because built-in rules remain active. Corrupt override state,
-  unreadable Git inputs, and incomplete staged-content scans stop every profile.
+  with a warning because built-in rules remain active. Corrupt override state and
+  unreadable Git inputs stop every profile. An incomplete staged-content scan warns
+  on `clean`/`compliance` and stops `strict`; the final ref guard fails closed on it
+  at every profile.
   Any automatic unstage failure stops; allowing it through would only defer the
   same block to the pinned-tree or final-ref scan. `strict` also vetoes policy
   findings and reviews.
@@ -146,7 +156,7 @@ means local rules only add restrictions and can never override a core block.
 - **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
+  staged path (stage only a `.claude.json`, 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

package/docs/faq.md ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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/hooks/hooks.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-    "description": "aimhooman: keep AI session files, secrets, and attribution out of commits",
+    "description": "aimhooman: keep AI session files and attribution out of commits",
     "hooks": {
         "SessionStart": [
             {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.2.0",
-    "description": "AI works. Hoomans ship. Keep AI session files, secrets, and attribution out of your commits.",
+    "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": {
         "type": "git",
@@ -21,6 +21,13 @@
         "hooks/",
         "schemas/",
         "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/",
@@ -47,6 +54,7 @@
         "check": "node scripts/validate.mjs",
         "sync:hosts": "node scripts/sync-hosts.mjs",
         "sync:ruleset": "node scripts/sync-ruleset.mjs",
+        "sync:catalog": "node scripts/sync-catalog.mjs",
         "test": "node --import ./tests/test-env.mjs --test",
         "test:coverage": "node --import ./tests/test-env.mjs --experimental-test-coverage --test-coverage-include=\"src/**\" --test-coverage-include=\"bin/**\" --test-coverage-include=\"scripts/authorize-owner-paths.mjs\" --test-coverage-include=\"scripts/github-owner-authority.mjs\" --test-coverage-include=\"scripts/package-manifest.mjs\" --test-coverage-include=\"scripts/scan-ci-history.mjs\" --test-coverage-exclude=\"tests/**\" --test-coverage-lines=75 --test-coverage-branches=60 --test-coverage-functions=85 --test-reporter=spec --test-reporter=./scripts/coverage-threshold.mjs --test-reporter-destination=stdout --test-reporter-destination=stderr --test",
         "check:static": "node scripts/static-gates.mjs",