@rmyndharis/aimhooman 0.1.2 → 0.1.4

package/docs/design/frictionless-enforcement.md

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

package/package.json

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

package/rules/attribution.json

@@ -95,15 +95,15 @@
     },
     {
         "id": "attribution.generated-with",
-        "version": 2,
+        "version": 3,
         "provider": "generic",
         "category": "ai-attribution",
         "confidence": "high",
         "kind": "message",
         "match": {
             "content": [
-                "(?i)^\\s*generated\\s+(?:with|by)\\s+(?:claude(?:\\s+code)?|(?:github\\s+)?copilot|chatgpt|gpt(?:-[0-9]+(?:\\.[0-9]+)?)?|(?:openai\\s+)?codex|cursor)[.!]?\\s*$",
-                "(?i)^\\s*(?:🤖\\s*)?generated\\s+with\\s+\\[(?:claude(?:\\s+code)?|(?:github\\s+)?copilot|chatgpt|gpt(?:-[0-9]+(?:\\.[0-9]+)?)?|(?:openai\\s+)?codex|cursor)\\]\\([^)]*\\)\\s*$"
+                "(?i)^\\s*(?:🤖\\s*)?generated\\s+(?:with|by)\\s+(?:claude|(?:github\\s+)?copilot|chatgpt|gpt(?:-[0-9]+(?:\\.[0-9]+)?)?|(?:openai\\s+)?codex|cursor)(?:\\s+[A-Za-z0-9.]+){0,3}[.!]?\\s*(?:🤖\\s*)?$",
+                "(?i)^\\s*(?:🤖\\s*)?generated\\s+with\\s+\\[(?:claude|(?:github\\s+)?copilot|chatgpt|gpt(?:-[0-9]+(?:\\.[0-9]+)?)?|(?:openai\\s+)?codex|cursor)(?:\\s+[A-Za-z0-9.]+){0,3}\\]\\([^)]*\\)\\s*(?:🤖\\s*)?$"
             ]
         },
         "actions": {

package/rules/markers.json

@@ -1,7 +1,7 @@
 [
     {
         "id": "marker.corner-cut",
-        "version": 2,
+        "version": 3,
         "provider": "generic",
         "category": "ai-marker",
         "confidence": "medium",
@@ -14,19 +14,32 @@
                 "**/docs/**",
                 "**/test/**",
                 "**/tests/**",
+                "**/__tests__/**",
+                "**/testdata/**",
                 "**/fixtures/**",
                 "**/__fixtures__/**",
                 "**/vendor/**",
+                "**/vendored/**",
                 "**/third_party/**",
                 "**/node_modules/**",
                 "**/dist/**",
                 "**/build/**",
+                "out/**",
+                "target/**",
+                "**/.next/**",
                 "**/coverage/**",
                 "**/generated/**",
                 "**/*.generated.*",
                 "**/*.min.js",
                 "**/*.map",
-                "**/*.md"
+                "**/*.md",
+                "**/*.mdx",
+                "**/*.markdown",
+                "**/*.rst",
+                "**/*.test.*",
+                "**/*.spec.*",
+                "**/*_test.*",
+                "**/*_spec.*"
             ],
             "content": [
                 "(?i)\\b(ponytail|caveman|yagni-oneliner):"
@@ -44,7 +57,7 @@
     },
     {
         "id": "marker.ai-authored",
-        "version": 1,
+        "version": 2,
         "provider": "generic",
         "category": "ai-marker",
         "confidence": "low",
@@ -57,22 +70,35 @@
                 "**/docs/**",
                 "**/test/**",
                 "**/tests/**",
+                "**/__tests__/**",
+                "**/testdata/**",
                 "**/fixtures/**",
                 "**/__fixtures__/**",
                 "**/vendor/**",
+                "**/vendored/**",
                 "**/third_party/**",
                 "**/node_modules/**",
                 "**/dist/**",
                 "**/build/**",
+                "out/**",
+                "target/**",
+                "**/.next/**",
                 "**/coverage/**",
                 "**/generated/**",
                 "**/*.generated.*",
                 "**/*.min.js",
                 "**/*.map",
-                "**/*.md"
+                "**/*.md",
+                "**/*.mdx",
+                "**/*.markdown",
+                "**/*.rst",
+                "**/*.test.*",
+                "**/*.spec.*",
+                "**/*_test.*",
+                "**/*_spec.*"
             ],
             "content": [
-                "(?i)\\b(ai[- ]?generated|generated by (ai|copilot|claude|chatgpt|codex))\\b"
+                "(?i)\\b(generated by (ai|copilot|claude|chatgpt|codex))\\b"
             ]
         },
         "actions": {

package/rules/paths.json

@@ -1,12 +1,13 @@
 [
     {
         "id": "claude.local-settings",
-        "version": 1,
+        "version": 2,
         "provider": "claude-code",
         "category": "local-settings",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".claude/settings.local.json",
                 "**/.claude/settings.local.json"
@@ -24,17 +25,16 @@
     },
     {
         "id": "claude.session-state",
-        "version": 1,
+        "version": 2,
         "provider": "claude-code",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".claude.json",
                 "**/.claude.json",
-                ".claude/.credentials.json",
-                "**/.claude/.credentials.json",
                 ".claude/session*.json",
                 "**/.claude/session*.json",
                 ".claude/history*",
@@ -64,12 +64,13 @@
     },
     {
         "id": "codex.session-state",
-        "version": 1,
+        "version": 2,
         "provider": "codex",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".codex/sessions/**",
                 "**/.codex/sessions/**",
@@ -93,12 +94,13 @@
     },
     {
         "id": "copilot.session-state",
-        "version": 2,
+        "version": 3,
         "provider": "copilot",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".copilot/**",
                 "**/.copilot/**"
@@ -116,12 +118,13 @@
     },
     {
         "id": "cursor.session-state",
-        "version": 1,
+        "version": 2,
         "provider": "cursor",
         "category": "ephemeral-state",
         "confidence": "medium",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".cursor/session*",
                 "**/.cursor/session*",
@@ -143,12 +146,13 @@
     },
     {
         "id": "aider.history",
-        "version": 2,
+        "version": 3,
         "provider": "aider",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".aider.*",
                 "**/.aider.*"
@@ -166,12 +170,13 @@
     },
     {
         "id": "specstory.history",
-        "version": 1,
+        "version": 2,
         "provider": "specstory",
         "category": "ephemeral-state",
         "confidence": "medium",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".specstory/**",
                 "**/.specstory/**"
@@ -189,12 +194,13 @@
     },
     {
         "id": "continue.sessions",
-        "version": 1,
+        "version": 2,
         "provider": "continue",
         "category": "ephemeral-state",
         "confidence": "medium",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".continue/sessions/**",
                 "**/.continue/sessions/**"
@@ -212,7 +218,7 @@
     },
     {
         "id": "secret.dotenv",
-        "version": 2,
+        "version": 3,
         "provider": "generic",
         "category": "secret",
         "confidence": "high",
@@ -226,16 +232,11 @@
                 "**/.env.*"
             ],
             "except": [
-                ".env.example",
-                "**/.env.example",
-                ".env.sample",
-                "**/.env.sample",
-                ".env.template",
-                "**/.env.template",
-                ".env.dist",
-                "**/.env.dist",
-                ".env.defaults",
-                "**/.env.defaults"
+                "**/*.example",
+                "**/*.sample",
+                "**/*.template",
+                "**/*.dist",
+                "**/*.defaults"
             ]
         },
         "actions": {
@@ -303,8 +304,33 @@
         ]
     },
     {
-        "id": "generic.agent-instructions",
+        "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,
         "provider": "generic",
         "category": "ambiguous-instructions",
         "confidence": "medium",
@@ -328,18 +354,19 @@
         },
         "reason": "Agent instruction files may be intentional team config. Review before committing.",
         "remediation": [
-            "aimhooman allow <path> --reason \"shared team config\"",
+            "aimhooman review <path> --head <commit> --reason \"shared team config\"",
             "or unstage if it is personal"
         ]
     },
     {
         "id": "generic.project-policy",
-        "version": 1,
+        "version": 2,
         "provider": "aimhooman",
         "category": "policy-config",
         "confidence": "high",
         "kind": "path",
         "match": {
+            "path_case": "insensitive",
             "paths": [
                 ".aimhooman.json",
                 "**/.aimhooman.json"
@@ -352,54 +379,54 @@
         },
         "reason": "Versioned enforcement policy changes require explicit human review.",
         "remediation": [
-            "aimhooman allow .aimhooman.json --reason \"reviewed team policy change\"",
+            "aimhooman review .aimhooman.json --head <commit> --reason \"reviewed team policy change\"",
             "or unstage the policy change"
         ]
     },
     {
         "id": "playwright-mcp.state",
-        "version": 1,
+        "version": 2,
         "provider": "playwright-mcp",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "paths": [".playwright-mcp/**", "**/.playwright-mcp/**"] },
+        "match": { "path_case": "insensitive", "paths": [".playwright-mcp/**", "**/.playwright-mcp/**"] },
         "actions": { "clean": "block", "strict": "block", "compliance": "block" },
         "reason": "Playwright MCP session artifacts are local, not repository content.",
         "remediation": ["git restore --staged <path>"]
     },
     {
         "id": "remember.state",
-        "version": 1,
+        "version": 2,
         "provider": "remember",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "paths": [".remember/**", "**/.remember/**"] },
+        "match": { "path_case": "insensitive", "paths": [".remember/**", "**/.remember/**"] },
         "actions": { "clean": "block", "strict": "block", "compliance": "block" },
         "reason": "Remember second-brain data is local, not repository content.",
         "remediation": ["git restore --staged <path>"]
     },
     {
         "id": "superpowers.state",
-        "version": 1,
+        "version": 2,
         "provider": "superpowers",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "paths": [".superpowers/**", "**/.superpowers/**"] },
+        "match": { "path_case": "insensitive", "paths": [".superpowers/**", "**/.superpowers/**"] },
         "actions": { "clean": "block", "strict": "block", "compliance": "block" },
         "reason": "Superpowers plugin state is local, not repository content.",
         "remediation": ["git restore --staged <path>"]
     },
     {
         "id": "agent.state",
-        "version": 2,
+        "version": 3,
         "provider": "generic",
         "category": "ephemeral-state",
         "confidence": "high",
         "kind": "path",
-        "match": { "paths": [".agent/**", "**/.agent/**"] },
+        "match": { "path_case": "insensitive", "paths": [".agent/**", "**/.agent/**"] },
         "actions": { "clean": "block", "strict": "block", "compliance": "block" },
         "reason": "Generic agent state is local, not repository content.",
         "remediation": ["git restore --staged <path>"]

package/rules/secrets.json

@@ -45,14 +45,15 @@
     },
     {
         "id": "secret.aws-key-content",
-        "version": 1,
+        "version": 2,
         "provider": "aws",
         "category": "secret",
         "confidence": "high",
         "kind": "code",
         "match": {
             "content": [
-                "(?i)\\baws_(?:secret_access_key|session_token)\\b\\s*[:=]\\s*[\\\"']?[A-Za-z0-9/+=]{32,}(?![A-Za-z0-9/+=])"
+                "(?i)\\baws_(?:secret_access_key|session_token)\\b\\s*[:=]\\s*[\\\"']?[A-Za-z0-9/+=]{32,}(?![A-Za-z0-9/+=])",
+                "\\b(?:AKIA|ASIA)[A-Z0-9]{16}\\b"
             ]
         },
         "actions": {
@@ -74,7 +75,8 @@
         "kind": "code",
         "match": {
             "content": [
-                "\\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{60,255}|glpat-[A-Za-z0-9_-]{20,255}|npm_[A-Za-z0-9]{36,255}|xox[baprs]-[A-Za-z0-9-]{20,255})\\b"
+                "\\b(?:gh[pousr]_[A-Za-z0-9]{36,255}|github_pat_[A-Za-z0-9_]{60,255}|glpat-[A-Za-z0-9_-]{20,255}|npm_[A-Za-z0-9]{36,255}|xox[baprs]-[A-Za-z0-9-]{20,255})\\b",
+                "\\b(?:sk-ant-api[0-9]{2}-[A-Za-z0-9_-]{80,255}|sk-proj-[A-Za-z0-9_-]{40,255}|AIza[A-Za-z0-9_-]{35}|(?:sk|rk)_live_[A-Za-z0-9]{20,255}|hf_[A-Za-z0-9]{34}|SG\\.[A-Za-z0-9_-]{20,255}\\.[A-Za-z0-9_-]{40,255})\\b"
             ]
         },
         "actions": {

package/skills/aimhooman/SKILL.md

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

package/src/atomic-write.mjs

@@ -290,7 +290,17 @@ export function withLock(lockPath, fn, options = {}) {
             if (attempt + 1 < retries) waitForLock(retryDelayMs);
         }
         if (!held) {
-            throw new Error(`cannot acquire state lock "${lockPath}" after ${retries} attempts`);
+            // Name the queue, not just the lock. This scheme writes no file at lockPath;
+            // only the legacy holder checked above would, so a reader of this error
+            // usually goes looking for a path that is not there. What blocks is a
+            // candidate in the queue directory, retained because its owner cannot be
+            // disproved, and a holder killed outright never reaches the finally below
+            // that would have removed its own.
+            throw new Error(
+                `cannot acquire state lock "${lockPath}" after ${retries} attempts. Contenders `
+                + `queue in "${queueDir}"; if no other aimhooman command is running, a candidate `
+                + 'there outlived the process that published it, and removing that directory clears it',
+            );
         }
         return fn();
     } catch (error) {

package/src/githooks.mjs

@@ -124,7 +124,7 @@ function canonicalPath(path) {
 
 // Ask Git for the path it actually uses. In a linked worktree this resolves to
 // the common repository hooks directory, not <gitDir>/hooks.
-function effectiveHooksDir(repo) {
+export function effectiveHooksDir(repo) {
     try {
         return execFileSync(
             'git',

package/src/gitx.mjs

@@ -200,7 +200,7 @@ export function unmergedPaths(repo) {
 export function stagedRenameSources(repo, destinations) {
     const selected = new Set(destinations);
     if (!selected.size) return [];
-    const entries = diffEntries(repo, ['--cached'], 1);
+    const entries = diffEntries(repo, ['--cached'], '1%');
     const sources = new Set(entries
         .filter((entry) => entry.status === 'R' && selected.has(entry.path) && entry.sourcePath)
         .map((entry) => entry.sourcePath));
@@ -210,7 +210,9 @@ export function stagedRenameSources(repo, destinations) {
     // there is no exact source to recover. When a blocked destination remains an
     // add even at the lowest similarity threshold, conservatively restore every
     // staged deletion. This may unstage an unrelated deletion, but it never lets
-    // automatic repair silently commit half of a possible rename.
+    // automatic repair silently commit half of a possible rename. That threshold
+    // carries a % sign because git reads a bare 1 as the fraction 0.1, so -M1
+    // asks for 10% and leaves a 3%-similar rename here as an add plus a delete.
     if (entries.some((entry) => entry.status === 'A' && selected.has(entry.path))) {
         for (const entry of entries) {
             if (entry.status === 'D') sources.add(entry.path);
@@ -226,8 +228,13 @@ export function readStagedPath(repo, path) {
     const target = 'staged';
     let records;
     try {
+        // The --literal-pathspecs flag rather than :(top,literal) magic: magic
+        // parsing is disabled by GIT_LITERAL_PATHSPECS in the environment, which
+        // would leave the pathspec a literal filename no repository contains, so
+        // git matched nothing and the read reported the policy absent. cwd is
+        // already repo.root, which is what the top magic was for.
         records = nulStrings(gitBuf([
-            'ls-files', '--stage', '-z', '--', `:(top,literal)${path}`,
+            '--literal-pathspecs', 'ls-files', '--stage', '-z', '--', path,
         ], repo.root));
     } catch (error) {
         throw new GitTargetReadError(target, path, gitErrorDetail(error), error);
@@ -274,7 +281,7 @@ export function readCommitPath(repo, revision, path) {
     let records;
     try {
         records = nulStrings(gitBuf([
-            'ls-tree', '--full-tree', '-z', oid, '--', `:(top,literal)${path}`,
+            '--literal-pathspecs', 'ls-tree', '--full-tree', '-z', oid, '--', path,
         ], repo.root));
     } catch (error) {
         throw new GitTargetReadError(target, path, gitErrorDetail(error), error);
@@ -483,8 +490,13 @@ export function unstagePaths(repo, paths) {
             '--pathspec-from-file=-', '--pathspec-file-nul',
         ], opts);
     } else {
+        // -f waives only the check that the staged blob still matches the file
+        // on disk. With no HEAD that check has nothing else to pass against, so
+        // an artifact appended to between `git add` and `git commit` could never
+        // be unstaged. --cached leaves the worktree alone either way, and the
+        // sibling `restore --staged` branch enforces no equivalent check.
         execFileSync('git', [
-            '--literal-pathspecs', 'rm', '--cached', '--quiet', '--ignore-unmatch',
+            '--literal-pathspecs', 'rm', '--cached', '-f', '--quiet', '--ignore-unmatch',
             '--pathspec-from-file=-', '--pathspec-file-nul',
         ], opts);
     }

package/src/history-scan.mjs

@@ -13,6 +13,10 @@ function gitBuffer(repo, args, input) {
         encoding: 'buffer',
         maxBuffer: 128 * 1024 * 1024,
         timeout: GIT_TIMEOUT_MS,
+        // Same reason as gitBuf in gitx.mjs: without an explicit stdio,
+        // execFileSync echoes the child's stderr before it checks the exit
+        // status, so git's raw output reaches the terminal even on success.
+        stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
         ...(input === undefined ? {} : { input }),
     });
 }