@rmyndharis/aimhooman 0.1.8 → 0.3.0

package/docs/design/frictionless-enforcement.md

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

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

@@ -1,7 +1,7 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.1.8",
-    "description": "AI works. Hoomans ship. Keep AI session files, secrets, and attribution out of your commits.",
+    "version": "0.3.0",
+    "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,8 @@
         "hooks/",
         "schemas/",
         "docs/hosts.json",
+        "docs/ai-artifacts.gitignore",
+        "docs/catalog.md",
         "docs/design/",
         "docs/logo/",
         ".claude-plugin/",
@@ -47,6 +49,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",

package/rules/paths.json

@@ -216,120 +216,6 @@
             "git restore --staged <path>"
         ]
     },
-    {
-        "id": "secret.dotenv",
-        "version": 4,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".env",
-                "**/.env",
-                ".env.*",
-                "**/.env.*"
-            ],
-            "except": [
-                "**/*.example",
-                "**/*.sample",
-                "**/*.template",
-                "**/*.dist",
-                "**/*.defaults",
-                "**/*.minimal"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "Environment files often carry secrets and should not be committed.",
-        "remediation": [
-            "git restore --staged <path>",
-            "commit a .env.example with placeholders instead"
-        ]
-    },
-    {
-        "id": "secret.private-key",
-        "version": 3,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                "**/id_rsa",
-                "**/id_dsa",
-                "**/id_ecdsa",
-                "**/id_ed25519",
-                "**/*.p12",
-                "**/*.pfx"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "A path matching a private-key filename (id_rsa, id_ed25519, *.p12, *.pfx, ...) is blocked by name — content is not inspected. If this is a real key, it must never be committed; if the name is coincidental, rename the file.",
-        "remediation": [
-            "git restore --staged <path>",
-            "if this is a real key, rotate it if it was ever exposed",
-            "if the name is coincidental (a fixture, a doc), rename the file so it no longer matches a private-key pattern"
-        ]
-    },
-    {
-        "id": "secret.aws-credentials",
-        "version": 2,
-        "provider": "generic",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".aws/credentials",
-                "**/.aws/credentials"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "AWS credentials must never be committed.",
-        "remediation": [
-            "git restore --staged <path>"
-        ]
-    },
-    {
-        "id": "secret.claude-credentials",
-        "version": 1,
-        "provider": "claude-code",
-        "category": "secret",
-        "confidence": "high",
-        "kind": "path",
-        "match": {
-            "path_case": "insensitive",
-            "paths": [
-                ".claude/.credentials.json",
-                "**/.claude/.credentials.json"
-            ]
-        },
-        "actions": {
-            "clean": "block",
-            "strict": "block",
-            "compliance": "block"
-        },
-        "reason": "This file holds an OAuth access token and must never be committed.",
-        "remediation": [
-            "git restore --staged <path>",
-            "Revoke the token if it already reached a commit."
-        ]
-    },
     {
         "id": "generic.agent-instructions",
         "version": 2,

package/schemas/overrides.schema.json

@@ -14,7 +14,10 @@
             "required": ["target"],
             "properties": {
                 "target": { "type": "string", "minLength": 1 },
-                "scope": { "enum": ["path", "rule", "secret-path"] },
+                "scope": {
+                    "enum": ["path", "rule"],
+                    "$comment": "v0.3.0 retired the secret-path scope with built-in secret scanning; the loader drops legacy entries with a warning instead of failing the file."
+                },
                 "reason": { "type": "string" },
                 "actor": { "type": "string" },
                 "at": { "type": "string", "format": "date-time" }

package/skills/aimhooman/SKILL.md

@@ -3,8 +3,8 @@ name: aimhooman
 description: >
   Keep AI tooling artifacts out of Git. Use whenever staging, committing, or
   pushing changes: block AI session/state files (.claude/session.json,
-  .codex/history, .copilot, .cursor/session, .aider.*, .specstory, .agent),
-  secrets (.env, private keys, .aws/credentials), and unwanted AI attribution in
+  .codex/history, .copilot, .cursor/session, .aider.*, .specstory, .agent)
+  and unwanted AI attribution in
   commit messages (Co-authored-by an AI, "Generated with AI"). Also use when the user says
   "aimhooman", "ship it like a hooman", or asks to clean AI residue before a commit.
 license: MIT
@@ -24,13 +24,16 @@ Its policy:
   `.copilot/*`, `.cursor/session*`, `.cursor/chats/*`, `.cursor/logs/*`,
   `.aider.*`, `.specstory/*`, `.continue/sessions/*`, `.playwright-mcp/*`,
   `.remember/*`, `.superpowers/*`, and `.agent/*`. The examples are not
-  exhaustive; the packaged `rules/paths.json` is the detection source of truth.
-  If one is staged, unstage it and keep it out of Git instead.
+  exhaustive; the packaged `rules/paths.json` is the detection source of truth
+  for these artifacts. If one is staged, unstage it and keep it out of Git
+  instead.
 - Never commit secrets: a real `.env` (not `.env.example`), private keys
   (`id_rsa` and files containing a private-key header), `.aws/credentials`,
   `.claude/.credentials.json`, service-account keys, or a provider API key
   (GitHub, GitLab, npm, Slack, Anthropic, OpenAI, Google, Stripe, Hugging Face,
-  SendGrid). Public certificates are allowed.
+  SendGrid). Public certificates are allowed. aimhooman does not scan for
+  secrets — this rule is on you, and a dedicated scanner such as gitleaks is
+  the right backstop for it.
 - Never add AI attribution to commit messages: no `Co-authored-by` trailer naming
   an AI (Claude, Copilot, Codex), no "Generated with/by <AI>" lines, no AI-service
   noreply emails. A commit message reads as if a human wrote it.
@@ -61,7 +64,7 @@ npm test
 npm run test:coverage
 ```
 
-aimhooman also enforces this at commit time, so a blocked commit means a real
-violation to fix, not a check to bypass. The rule is simple: AI works, hoomans
-ship.
+aimhooman also enforces the artifact and attribution rules at commit time, so
+a blocked commit means a real violation to fix, not a check to bypass. The rule
+is simple: AI works, hoomans ship.
 <!-- aimhooman:ruleset-end -->

package/src/exclude.mjs

@@ -8,8 +8,8 @@ const END = '# <<< aimhooman managed excludes';
 
 // Local AI residue kept out of `git status`. Deriving this list from the rule
 // catalog prevents the prevention layer from drifting behind enforcement. We
-// intentionally exclude only unambiguous tooling state/settings: secret and
-// review-required rules must remain visible to users.
+// intentionally exclude only unambiguous tooling state/settings: review-
+// required and policy rules must remain visible to users.
 const AUTO_EXCLUDE_CATEGORIES = new Set(['ephemeral-state', 'local-settings']);
 
 export function patternsForRules(rules) {
@@ -74,6 +74,20 @@ export function inspectExclude(file, patterns) {
     return { installed: true, current: missing.length === 0 && actual.size === patterns.length, missing };
 }
 
+// managedPatterns returns the pattern lines currently inside the managed
+// block, or [] when the file or block is absent. Read-only.
+export function managedPatterns(file) {
+    const existing = readExclude(file, null);
+    if (existing === null) return [];
+    const range = managedRange(existing);
+    if (!range) return [];
+    return existing
+        .slice(range.start + BEGIN.length, range.end)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('#') && !line.startsWith('!'));
+}
+
 function stripBlock(s) {
     const range = managedRange(s);
     if (!range) return s;

package/src/githooks.mjs

@@ -651,6 +651,12 @@ function hookScript(name, cmd, cliPath, chainedPath) {
     const shellPathValue = hookPathForShell(pathValue);
     const nodeMetadata = Buffer.from(nodePath, 'utf8').toString('base64url');
     const pathMetadata = Buffer.from(pathValue, 'utf8').toString('base64url');
+    // chainedPath is <stateDir>/chained/<name> for a repository install and
+    // <globalHooksDir>/chained/<name> for a global one, so its grandparent is
+    // always per-install state. The compile cache lives there rather than in a
+    // shared or temp location: no other repository can pollute it, and
+    // `uninstall --purge-state` removes it along with the rest of the state.
+    const compileCacheDir = join(dirname(dirname(String(chainedPath))), 'compile-cache');
     const captureTree = name === 'commit-msg'
         ? `AIMHOOMAN_COMMIT_TREE=$(PATH="$AIMHOOMAN_PATH" git write-tree) || {
   echo "aimhooman: cannot snapshot the would-be commit tree" >&2
@@ -690,10 +696,31 @@ function hookScript(name, cmd, cliPath, chainedPath) {
     // 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
-    // phase. Placed after the chained-hook call, so a chained hook still sees
-    // every phase.
+    // phase. The prepared filter goes further: a transaction that moves neither
+    // a branch nor HEAD (ORIG_HEAD, tags, remote-tracking refs) carries nothing
+    // refcheck scans, so it never spawns at all — but only after proving the
+    // guard is still there to skip. A hook manager that wipes the dispatchers
+    // during a branch-free operation (tag, fetch, stash) would otherwise go
+    // unnoticed, because after a full wipe no later hook exists to raise the
+    // alarm. Presence is exactly what a deletion removes; content integrity
+    // keeps running on every branch transaction via refcheck. Both sit after
+    // the chained-hook call, so a chained hook still sees every phase.
     const phaseShortCircuit = name === 'reference-transaction'
-        ? 'case "$1" in committed|aborted) exit 0 ;; esac\n'
+        ? `case "$1" in committed|aborted) exit 0 ;; esac
+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
+        [ -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
+        }
+      done
+      exit 0 ;;
+  esac ;;
+esac
+`
         : '';
     const template = `#!/bin/sh -p
 ${MARKER} (${name})
@@ -706,6 +733,7 @@ ${MARKER} (${name})
 AIMHOOMAN_CLI=${shq(resolvedCliPath)}
 AIMHOOMAN_NODE=${shq(nodePath)}
 AIMHOOMAN_PATH=${shq(shellPathValue)}
+AIMHOOMAN_COMPILE_CACHE=${shq(compileCacheDir)}
 ${captureTree}${captureTransaction}run_aimhooman() {
   if [ ! -f "$AIMHOOMAN_CLI" ]; then
     echo "aimhooman: guard unavailable (aimhooman CLI is missing); allowing this operation without protection. Reinstall aimhooman or remove the managed hooks." >&2
@@ -731,8 +759,15 @@ ${captureTree}${captureTransaction}run_aimhooman() {
     unset BASH_ENV ENV CDPATH
     PATH=$AIMHOOMAN_PATH
     AIMHOOMAN_ACTIVE_HOOK=${shq(name)}
+    # A V8 compile cache shared by every hook spawn of this installation shaves
+    # the module parse/compile cost off each Node start. Node creates the
+    # directory when it can and silently disables the cache when it cannot, so
+    # an unwritable state directory degrades to the old cold start, never to a
+    # hook failure.
+    NODE_COMPILE_CACHE=$AIMHOOMAN_COMPILE_CACHE
     export PATH
     export AIMHOOMAN_ACTIVE_HOOK
+    export NODE_COMPILE_CACHE
     "$AIMHOOMAN_NODE" "$AIMHOOMAN_CLI" "$@"
   )
 }

package/src/gitx.mjs

@@ -12,7 +12,7 @@ import {
     rmSync,
     symlinkSync,
 } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { gitEnvironment, GIT_TIMEOUT_MS } from './git-environment.mjs';
 
 export class GitRevisionError extends Error {
@@ -99,7 +99,23 @@ function objectMetadata(repo, oids) {
 }
 
 function enrichEntries(repo, entries) {
-    const metadata = objectMetadata(repo, entries.map((entry) => entry.oid));
+    const metadata = objectMetadata(
+        repo,
+        entries.filter((entry) => entry.mode !== '160000').map((entry) => entry.oid),
+    );
+    // Gitlinks (mode 160000) pin a commit of another repository. Enrich them
+    // from the local object store when the pin happens to be there, but never
+    // let the read fail the scan: in a partial clone asking cat-file about a
+    // pin that is not local triggers a promisor fetch that aborts the whole
+    // batch ("not our ref"), surfacing as an EPIPE. A failed read leaves the
+    // mode-derived type in place with no size.
+    try {
+        const gitlinks = objectMetadata(
+            repo,
+            entries.filter((entry) => entry.mode === '160000').map((entry) => entry.oid),
+        );
+        for (const [oid, object] of gitlinks) metadata.set(oid, object);
+    } catch { /* best effort — see above */ }
     return entries.map((entry) => {
         const object = metadata.get(entry.oid) || { type: null, size: null };
         return {
@@ -146,10 +162,45 @@ function diffEntries(repo, args, renameThreshold = null) {
 
 // openRepo resolves the repository containing cwd. Throws if not a repo.
 export function openRepo(cwd = process.cwd()) {
-    const root = gitStr(['rev-parse', '--show-toplevel'], cwd);
-    const gitDir = gitStr(['rev-parse', '--absolute-git-dir'], root);
-    let commonDir = gitStr(['rev-parse', '--git-common-dir'], root);
-    if (!isAbsolute(commonDir)) commonDir = join(root, commonDir);
+    // One rev-parse invocation, not three: this runs inside every Git hook
+    // spawn, and each git subprocess costs ~13ms of the commit-time budget.
+    // The flags print in request order, one value per line.
+    const lines = gitStr(
+        ['rev-parse', '--show-toplevel', '--absolute-git-dir', '--git-common-dir'],
+        cwd,
+    ).split('\n');
+    if (lines.length !== 3) {
+        // A newline inside the repository path breaks the multi-flag output
+        // into extra lines; one flag per call is immune to that.
+        const root = gitStr(['rev-parse', '--show-toplevel'], cwd);
+        const gitDir = gitStr(['rev-parse', '--absolute-git-dir'], root);
+        let commonDir = gitStr(['rev-parse', '--git-common-dir'], root);
+        if (!isAbsolute(commonDir)) commonDir = join(root, commonDir);
+        return {
+            root,
+            gitDir,
+            commonDir,
+            stateDir: join(commonDir, 'aimhooman'),
+            excludeFile: join(commonDir, 'info', 'exclude'),
+        };
+    }
+    const [root, gitDir, commonRaw] = lines;
+    // Only --git-common-dir comes back relative, and it is relative to the cwd
+    // the command ran in, never to the toplevel. Anchor the plain-'.git' case
+    // (a main worktree from any cwd spelling) on git's own canonical root —
+    // the same spelling the three-call version produced — instead of
+    // realpath'ing through the cwd: git lengthens 8.3 names on Windows and
+    // resolves symlinked cwds on macOS, and matching it keeps one spelling
+    // per repository. Anything else (a subdir's ../.git, an uncommon layout)
+    // resolves against the invoking cwd, which is the same directory.
+    let commonDir;
+    if (isAbsolute(commonRaw)) {
+        commonDir = commonRaw;
+    } else if (commonRaw === '.git') {
+        commonDir = join(root, commonRaw);
+    } else {
+        commonDir = resolve(cwd, commonRaw);
+    }
     return {
         root,
         gitDir,
@@ -177,6 +228,17 @@ export function stagedPaths(repo) {
     ], repo.root));
 }
 
+// ignoredByPatterns lists untracked, ignored paths under the given pathspecs.
+// Passing pathspecs keeps git's directory pruning effective: a bare
+// `ls-files --others --ignored` walks the whole worktree and costs ~150ms on
+// a large one, while anchored pathspecs answer in ~15ms.
+export function ignoredByPatterns(repo, pathspecs) {
+    if (!pathspecs.length) return [];
+    return nulStrings(gitBuf([
+        'ls-files', '--others', '--ignored', '--exclude-standard', '-z', '--', ...pathspecs,
+    ], repo.root));
+}
+
 // stagedTreeSha writes the index to a tree object and returns its SHA, the same
 // value `git write-tree` produces in the commit-msg dispatcher. Used by the
 // pre-commit/commit-msg marker dedup (W5): pre-commit records this sha when it

package/src/hook.mjs

@@ -8,6 +8,7 @@ import { newEngineWithDiagnostics } from './scan.mjs';
 import { openRepo, stagedEntries } from './gitx.mjs';
 import { applyExclude, patternsForRules } from './exclude.mjs';
 import { activeGitHook, installedHooks } from './githooks.mjs';
+import { loadConfig } from './state.mjs';
 import { visible } from './report.mjs';
 import { extractRuleset } from './ruleset-text.mjs';
 import { resolvePolicy } from './policy-resolver.mjs';
@@ -84,7 +85,14 @@ export function hookSessionStart() {
         const repo = openRepo();
         const policy = resolvePolicy(repo, { target: 'worktree' });
         const { engine: eng } = newEngineWithDiagnostics(policy.profile, repo.stateDir);
-        applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+        const patterns = patternsForRules(eng.rules);
+        applyExclude(repo.excludeFile, patterns);
+        // 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);
+        }
     } catch {
         /* not a repo; nothing to exclude */
     }
@@ -383,11 +391,23 @@ function hookPreToolUse(input) {
     // above so a read-only .git/info (CI checkout, read-only volume, a
     // repository owned by another user) cannot decide what is allowed.
     if (repo) {
+        const patterns = patternsForRules(eng.rules);
         try {
-            applyExclude(repo.excludeFile, patternsForRules(eng.rules));
+            applyExclude(repo.excludeFile, patterns);
         } catch (e) {
             hygieneWarning = `could not refresh ${repo.excludeFile}: ${e.message}`;
         }
+        // The committed variant of the block gets the same best-effort refresh
+        // when this clone opted into it; a failure there is housekeeping too,
+        // never part of the verdict.
+        try {
+            if (loadConfig(repo.stateDir).gitignore?.enabled) {
+                applyExclude(join(repo.root, '.gitignore'), patterns);
+            }
+        } catch (e) {
+            const gitignoreWarning = `could not refresh ${join(repo.root, '.gitignore')}: ${e.message}`;
+            hygieneWarning = hygieneWarning ? `${hygieneWarning}; ${gitignoreWarning}` : gitignoreWarning;
+        }
     }
     // A strict policy cannot make a meaningful guarantee if Git's own guards
     // are explicitly bypassed. Deny before the shell can stage-and-commit in a
@@ -402,7 +422,7 @@ function hookPreToolUse(input) {
     // A preceding command that may have changed the repository or its hooks is
     // also a potential pre-commit bypass. Strict rejects it above; clean and
     // compliance still need the staged-content backstop so a hook mutation
-    // cannot expose a secret that was already in the index.
+    // cannot sneak a blocked staged file past the guard.
     const commitPrefixRisk = parsed.commands.some((candidate) => (
         (candidate.verb === 'commit' || candidate.verb === 'unknown')
         && candidate.prefixRisk
@@ -426,8 +446,8 @@ function hookPreToolUse(input) {
     // them. A build, a test run, ls — those leave pre-commit to answer, and
     // refusing them taught agents to drop the `&&` gate rather than to run the
     // command separately. hiddenBypass stays wider on purpose; it is what keeps
-    // the staged-content backstop reading the blobs, so a secret already in the
-    // index still stops the commit here.
+    // the staged-content backstop reading the blobs, so a blocked file already
+    // in the index still stops the commit here.
     const prefixHookBypass = opaqueCommitRisk
         || (commitPrefixRisk && (noVerify || bypassHooks || parsed.prefixHooksRisk));
     // The same distinction, for the deny paths that ask "will anything scan this
@@ -460,7 +480,7 @@ function hookPreToolUse(input) {
     const blocks = [];
     // potentialCommit treats a command as leading to a commit. uncertainShell
     // was too broad: it flagged any pipe, so a benign read-only pipeline
-    // (gh ... | tail) was scanned and denied as if it staged a secret.
+    // (gh ... | tail) was scanned and denied as if it staged a blocked file.
     // opaqueCommitHiding keeps every commit-hiding shape (subshells,
     // substitution, script-feeds, code-executing/unlisted pipe segments) while
     // excluding pipelines of known read-only commands.
@@ -503,8 +523,8 @@ function hookPreToolUse(input) {
     // disables the real pre-commit guard, leaving this hook the only check.
     // When the commit also stages files at commit time (-a/--all/-u/--patch, or
     // a preceding `git add`), those files are neither in stagedPaths(repo) now
-    // nor in addPaths, so they were never scanned. Rather than let an unscanned
-    // secret through, deny. (Strict already denied the bypass above.) The rare
+    // nor in addPaths, so they were never scanned. Rather than let unscanned
+    // content through, deny. (Strict already denied the bypass above.) The rare
     // false-positive on an explicit `git add <path> && git commit --no-verify`
     // is safe-side; drop --no-verify to proceed.
     //
@@ -512,7 +532,8 @@ function hookPreToolUse(input) {
     // a --no-verify inside the inner command, where parsed.noVerify cannot see
     // it (the parser only inspects literal argv). Such an uncertain commit is
     // therefore treated as a potential hook bypass for the clean/compliance
-    // secret backstop, so a secret cannot slip past the guard wrapped in eval.
+    // staged-content backstop, so a blocked file cannot slip past the guard
+    // wrapped in eval.
     const indexReplacement = parsed.commands.some((candidate) => (
         candidate.verb === 'commit' && candidate.indexMutationRisk
     ));
@@ -553,9 +574,9 @@ function hookPreToolUse(input) {
     }
     // clean / compliance: advisory only (the git pre-commit unstage is the real
     // enforcement) — except when --no-verify/core.hooksPath bypasses that hook.
-    // A bypassed guard is the one case clean cannot delegate to git, so a blocked
-    // secret is denied here, matching the documented "secret stops the commit when
-    // automatic unstaging fails"; hygiene findings stay advisory.
+    // A bypassed guard is the one case clean cannot delegate to git, so a
+    // secret-category finding (a local rule pack can still declare one) is
+    // denied here; hygiene findings stay advisory.
     const bypassed = Boolean(potentialCommit && hiddenBypass);
     if (bypassed && blocks.some((f) => f.category === 'secret')) {
         return emitDecision(