@rmyndharis/aimhooman 0.1.0

package/schemas/overrides.schema.json

@@ -0,0 +1,134 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/rmyndharis/aimhooman/schemas/overrides.schema.json",
+    "title": "aimhooman local overrides",
+    "type": "object",
+    "properties": {
+        "schema_version": { "const": 1 },
+        "allow": { "$ref": "#/$defs/allowEntries" },
+        "deny": { "$ref": "#/$defs/denyEntries" }
+    },
+    "$defs": {
+        "ordinaryAllow": {
+            "type": "object",
+            "required": ["target"],
+            "properties": {
+                "target": { "type": "string", "minLength": 1 },
+                "scope": { "enum": ["path", "rule", "secret-path"] },
+                "reason": { "type": "string" },
+                "actor": { "type": "string" },
+                "at": { "type": "string", "format": "date-time" }
+            },
+            "additionalProperties": false
+        },
+        "reviewedAllow": {
+            "type": "object",
+            "required": ["target", "scope", "head", "transition", "newObjectId", "newMode"],
+            "properties": {
+                "target": { "type": "string", "minLength": 1 },
+                "scope": { "enum": ["reviewed-instruction", "reviewed-policy-file"] },
+                "reason": { "type": "string" },
+                "actor": { "type": "string" },
+                "at": { "type": "string", "format": "date-time" },
+                "head": { "$ref": "#/$defs/objectId" },
+                "transition": {
+                    "oneOf": [
+                        { "const": "staged" },
+                        { "$ref": "#/$defs/objectId" }
+                    ]
+                },
+                "newObjectId": { "$ref": "#/$defs/nullableObjectId" },
+                "newMode": { "$ref": "#/$defs/nullableBlobMode" }
+            },
+            "allOf": [
+                {
+                    "if": { "properties": { "newObjectId": { "type": "null" } } },
+                    "then": { "properties": { "newMode": { "type": "null" } } },
+                    "else": { "properties": { "newMode": { "$ref": "#/$defs/blobMode" } } }
+                }
+            ],
+            "additionalProperties": false
+        },
+        "migrationAllow": {
+            "type": "object",
+            "required": ["target", "scope", "head", "transition", "oldObjectId", "newObjectId", "newMode"],
+            "properties": {
+                "target": { "const": ".aimhooman.json" },
+                "scope": { "const": "policy-migration" },
+                "reason": { "type": "string" },
+                "actor": { "type": "string" },
+                "at": { "type": "string", "format": "date-time" },
+                "head": { "$ref": "#/$defs/objectId" },
+                "transition": {
+                    "anyOf": [
+                        { "const": "staged" },
+                        { "$ref": "#/$defs/objectId" }
+                    ]
+                },
+                "oldObjectId": { "$ref": "#/$defs/objectId" },
+                "newObjectId": {
+                    "anyOf": [
+                        { "$ref": "#/$defs/objectId" },
+                        { "type": "null" }
+                    ]
+                },
+                "newMode": { "$ref": "#/$defs/nullableBlobMode" }
+            },
+            "allOf": [
+                {
+                    "if": { "properties": { "newObjectId": { "type": "null" } } },
+                    "then": { "properties": { "newMode": { "type": "null" } } },
+                    "else": { "properties": { "newMode": { "$ref": "#/$defs/blobMode" } } }
+                }
+            ],
+            "additionalProperties": false
+        },
+        "allowEntries": {
+            "type": "array",
+            "items": {
+                "oneOf": [
+                    { "$ref": "#/$defs/ordinaryAllow" },
+                    { "$ref": "#/$defs/reviewedAllow" },
+                    { "$ref": "#/$defs/migrationAllow" }
+                ]
+            }
+        },
+        "denyEntries": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["target"],
+                "properties": {
+                    "target": { "type": "string", "minLength": 1 },
+                    "scope": { "enum": ["path", "rule"] },
+                    "reason": { "type": "string" },
+                    "actor": { "type": "string" },
+                    "at": { "type": "string", "format": "date-time" }
+                },
+                "additionalProperties": false
+            }
+        },
+        "objectId": {
+            "type": "string",
+            "$comment": "Accepts mixed case because overrides.json is user-authored; the loader lowercases head/transition/oldObjectId/newObjectId on read. scan-report.schema.json uses lowercase-only because it validates Git's normalized output.",
+            "pattern": "^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$"
+        },
+        "nullableObjectId": {
+            "anyOf": [
+                { "$ref": "#/$defs/objectId" },
+                { "type": "null" }
+            ]
+        },
+        "blobMode": {
+            "type": "string",
+            "enum": ["100644", "100755"]
+        },
+        "nullableBlobMode": {
+            "anyOf": [
+                { "$ref": "#/$defs/blobMode" },
+                { "type": "null" }
+            ]
+        }
+    },
+    "additionalProperties": false
+}

package/schemas/project-policy.schema.json

@@ -0,0 +1,12 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/rmyndharis/aimhooman/schemas/project-policy.schema.json",
+    "title": "aimhooman project policy",
+    "type": "object",
+    "required": ["schema_version", "profile"],
+    "properties": {
+        "schema_version": { "const": 1 },
+        "profile": { "enum": ["clean", "strict", "compliance"] }
+    },
+    "additionalProperties": false
+}

package/schemas/rule-pack.schema.json

@@ -0,0 +1,126 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/rmyndharis/aimhooman/schemas/rule-pack.schema.json",
+    "title": "aimhooman local rule pack",
+    "description": "Structural schema for local packs. The loader also applies the documented content-expression and path-glob work limits.",
+    "type": "array",
+    "items": {
+        "type": "object",
+        "required": ["id", "provider", "category", "kind", "match", "actions", "reason"],
+        "properties": {
+            "id": { "type": "string", "minLength": 1 },
+            "version": { "type": "integer", "minimum": 1 },
+            "provider": { "type": "string", "minLength": 1 },
+            "category": { "type": "string", "minLength": 1 },
+            "confidence": { "type": "string", "minLength": 1 },
+            "kind": { "enum": ["path", "message", "code"] },
+            "match": {
+                "type": "object",
+                "properties": {
+                    "paths": { "$ref": "#/$defs/nonEmptyStrings" },
+                    "except": { "$ref": "#/$defs/strings" },
+                    "content": { "$ref": "#/$defs/nonEmptyStrings" },
+                    "path_case": { "enum": ["sensitive", "insensitive"] }
+                },
+                "additionalProperties": false
+            },
+            "actions": {
+                "type": "object",
+                "properties": {
+                    "clean": { "$ref": "#/$defs/action" },
+                    "strict": { "$ref": "#/$defs/action" },
+                    "compliance": { "$ref": "#/$defs/action" }
+                },
+                "minProperties": 1,
+                "additionalProperties": false
+            },
+            "reason": { "type": "string", "minLength": 1 },
+            "remediation": { "$ref": "#/$defs/strings" },
+            "references": { "$ref": "#/$defs/strings" }
+        },
+        "allOf": [
+            {
+                "if": { "properties": { "kind": { "const": "path" } }, "required": ["kind"] },
+                "then": {
+                    "properties": {
+                        "match": {
+                            "type": "object",
+                            "properties": {
+                                "paths": true,
+                                "content": true,
+                                "path_case": true
+                            },
+                            "required": ["paths"],
+                            "not": {
+                                "type": "object",
+                                "properties": { "content": true },
+                                "required": ["content"]
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                "if": { "properties": { "kind": { "const": "message" } }, "required": ["kind"] },
+                "then": {
+                    "properties": {
+                        "match": {
+                            "type": "object",
+                            "properties": {
+                                "content": true,
+                                "paths": true,
+                                "except": true,
+                                "path_case": true
+                            },
+                            "required": ["content"],
+                            "not": {
+                                "anyOf": [
+                                    {
+                                        "type": "object",
+                                        "properties": { "paths": true },
+                                        "required": ["paths"]
+                                    },
+                                    {
+                                        "type": "object",
+                                        "properties": { "except": true },
+                                        "required": ["except"]
+                                    },
+                                    {
+                                        "type": "object",
+                                        "properties": { "path_case": true },
+                                        "required": ["path_case"]
+                                    }
+                                ]
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                "if": { "properties": { "kind": { "const": "code" } }, "required": ["kind"] },
+                "then": {
+                    "properties": {
+                        "match": {
+                            "type": "object",
+                            "properties": { "content": true },
+                            "required": ["content"]
+                        }
+                    }
+                }
+            }
+        ],
+        "additionalProperties": false
+    },
+    "$defs": {
+        "action": { "enum": ["allow", "review", "block"] },
+        "strings": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+        },
+        "nonEmptyStrings": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string", "minLength": 1 }
+        }
+    }
+}

package/schemas/scan-report.schema.json

@@ -0,0 +1,165 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/rmyndharis/aimhooman/schemas/scan-report.schema.json",
+    "title": "aimhooman scan report",
+    "type": "object",
+    "required": [
+        "schema_version",
+        "tool_version",
+        "target",
+        "profile",
+        "policy_source",
+        "policy_object_id",
+        "complete",
+        "stats",
+        "message_scanned",
+        "findings"
+    ],
+    "properties": {
+        "schema_version": { "const": 1 },
+        "tool_version": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 },
+        "profile": { "enum": ["clean", "strict", "compliance"] },
+        "policy_source": { "type": "string", "minLength": 1 },
+        "policy_object_id": { "$ref": "#/$defs/nullableObjectId" },
+        "policy_enforced_object_ids": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/objectId" },
+            "uniqueItems": true
+        },
+        "complete": { "type": "boolean" },
+        "stats": { "$ref": "#/$defs/stats" },
+        "message_scanned": { "type": "boolean" },
+        "commit": { "$ref": "#/$defs/objectId" },
+        "range": {
+            "type": "object",
+            "required": ["base", "scan_base", "head", "commits_scanned"],
+            "properties": {
+                "base": { "$ref": "#/$defs/objectId" },
+                "scan_base": { "$ref": "#/$defs/objectId" },
+                "head": { "$ref": "#/$defs/objectId" },
+                "commits_scanned": { "type": "integer", "minimum": 0 }
+            },
+            "additionalProperties": false
+        },
+        "findings": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/finding" }
+        }
+    },
+    "additionalProperties": false,
+    "$defs": {
+        "objectId": {
+            "type": "string",
+            "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+        },
+        "nullableObjectId": {
+            "anyOf": [
+                { "$ref": "#/$defs/objectId" },
+                { "type": "null" }
+            ]
+        },
+        "stats": {
+            "type": "object",
+            "required": [
+                "entries",
+                "blob_files",
+                "objects_read",
+                "files_scanned",
+                "bytes_scanned",
+                "findings_total",
+                "findings_returned",
+                "skipped"
+            ],
+            "properties": {
+                "entries": { "type": "integer", "minimum": 0 },
+                "blob_files": { "type": "integer", "minimum": 0 },
+                "objects_read": { "type": "integer", "minimum": 0 },
+                "files_scanned": { "type": "integer", "minimum": 0 },
+                "bytes_scanned": { "type": "integer", "minimum": 0 },
+                "findings_total": { "type": "integer", "minimum": 0 },
+                "findings_returned": { "type": "integer", "minimum": 0 },
+                "skipped": {
+                    "type": "object",
+                    "additionalProperties": { "type": "integer", "minimum": 1 }
+                }
+            },
+            "additionalProperties": false
+        },
+        "matchedRule": {
+            "type": "object",
+            "required": [
+                "ruleId", "ruleVersion", "kind", "category", "provider", "confidence",
+                "decision", "reason", "remediation", "source"
+            ],
+            "properties": {
+                "ruleId": { "type": "string", "minLength": 1 },
+                "ruleVersion": { "type": ["integer", "null"], "minimum": 1 },
+                "kind": { "enum": ["path", "message", "code"] },
+                "category": { "type": "string", "minLength": 1 },
+                "provider": { "type": "string", "minLength": 1 },
+                "confidence": { "type": ["string", "null"] },
+                "decision": { "enum": ["allow", "review", "block"] },
+                "reason": { "type": "string", "minLength": 1 },
+                "remediation": { "type": "array", "items": { "type": "string" } },
+                "source": { "enum": ["builtin", "local"] }
+            },
+            "additionalProperties": false
+        },
+        "finding": {
+            "type": "object",
+            "required": [
+                "ruleId", "ruleVersion", "matchedRuleIds", "matchedRules", "kind", "category",
+                "provider", "confidence", "decision", "reason", "remediation", "source",
+                "scanProfile", "policySource", "policyObjectId"
+            ],
+            "properties": {
+                "ruleId": { "type": "string", "minLength": 1 },
+                "ruleVersion": { "type": ["integer", "null"], "minimum": 1 },
+                "matchedRuleIds": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "type": "string", "minLength": 1 },
+                    "uniqueItems": true
+                },
+                "matchedRules": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "$ref": "#/$defs/matchedRule" }
+                },
+                "kind": { "enum": ["path", "message", "code"] },
+                "category": { "type": "string", "minLength": 1 },
+                "provider": { "type": "string", "minLength": 1 },
+                "confidence": { "type": ["string", "null"] },
+                "decision": { "enum": ["block", "review"] },
+                "reason": { "type": "string", "minLength": 1 },
+                "remediation": { "type": "array", "items": { "type": "string" } },
+                "source": { "enum": ["builtin", "local"] },
+                "path": { "type": "string" },
+                "line": { "type": "integer", "minimum": 1 },
+                "text": { "type": "string" },
+                "autofix": { "const": "remove-whole-line" },
+                "commit": { "$ref": "#/$defs/objectId" },
+                "objectId": { "$ref": "#/$defs/objectId" },
+                "parents": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/objectId" },
+                    "uniqueItems": true
+                },
+                "status": { "type": "string" },
+                "statuses": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+                "sourcePath": { "type": "string" },
+                "sourcePaths": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+                "scanProfile": { "enum": ["clean", "strict", "compliance"] },
+                "policySource": { "type": "string", "minLength": 1 },
+                "policyObjectId": { "$ref": "#/$defs/nullableObjectId" },
+                "policyEnforcedObjectIds": {
+                    "type": "array",
+                    "items": { "$ref": "#/$defs/objectId" },
+                    "uniqueItems": true
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+}

package/skills/aimhooman/SKILL.md

@@ -0,0 +1,65 @@
+---
+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
+  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
+---
+
+# aimhooman
+
+<!-- aimhooman:ruleset-start -->
+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/history*`, `.claude/todos/*`, `.claude/shell-snapshots/*`,
+  `.claude/statsig/*`, `.claude/projects/*`, `.claude/logs/*`,
+  `.codex/sessions/*`, `.codex/history*`, `.codex/log/*`, `.codex/logs/*`,
+  `.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.
+- 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.
+- 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.
+- Write in a human voice, not an AI voice. No `delve`, `leverage`, `utilize`,
+  `seamless`, `robust`, `comprehensive`, `underscore`, `foster`, `pivotal`, `myriad`,
+  `tapestry`, `landscape`; no "This PR addresses…", "adversarial self-review",
+  "live-verified", "thoroughly tested with comprehensive examples", "in today's",
+  "let's dive in", "in conclusion"; no bold lead-in on every bullet and no paired
+  em-dash asides. Say what broke or what changed, pick the plain short verb, name the
+  number, and vary sentence length. If the first line could open any PR on any repo,
+  delete it.
+- Treat `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md`
+  as review-required: they may be intentional team config, so confirm before
+  committing them.
+
+Project map:
+
+- `src/scan.mjs` and `src/rules.mjs` load rules and make policy decisions.
+- `src/hook.mjs` and `src/githooks.mjs` enforce them in agent and Git hooks.
+- `src/state.mjs` owns local policy state. `bin/aimhooman.mjs` is the CLI.
+- `tests/` mirrors the production paths and includes real temporary Git repos.
+
+Use Node.js 22.8 or newer. Before finishing a change, run:
+
+```sh
+npm run check
+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:ruleset-end -->

package/src/args.mjs

@@ -0,0 +1,72 @@
+export class ArgumentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArgumentError';
+    }
+}
+
+export function parseArguments(args, definition = {}) {
+    const options = {};
+    const positionals = [];
+    const seen = new Set();
+    const byName = new Map();
+    for (const [key, option] of Object.entries(definition.options || {})) {
+        for (const name of option.names || []) byName.set(name, { ...option, key });
+    }
+
+    let positionalOnly = false;
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (!positionalOnly && argument === '--') {
+            positionalOnly = true;
+            continue;
+        }
+        if (!positionalOnly && argument.startsWith('-')) {
+            const equal = argument.indexOf('=');
+            const name = equal > 0 ? argument.slice(0, equal) : argument;
+            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) {
+                throw new ArgumentError(`option "${name}" may only be used once`);
+            }
+            seen.add(option.key);
+            if (option.type === 'boolean') {
+                if (inlineValue !== undefined) throw new ArgumentError(`option "${name}" does not take a value`);
+                options[option.key] = true;
+                continue;
+            }
+            let value = inlineValue;
+            if (value === undefined) {
+                value = args[++index];
+                // Only treat the next token as a missing value when it is itself a
+                // registered flag; otherwise accept it (e.g. --reason "- rotated key").
+                if (value === undefined || (value.startsWith('-') && byName.has(value))) {
+                    throw new ArgumentError(`missing value for ${name}`);
+                }
+            }
+            if (!value && option.nonEmpty !== false) throw new ArgumentError(`missing value for ${name}`);
+            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;
+            }
+            continue;
+        }
+        positionals.push(argument);
+    }
+
+    for (const group of definition.conflicts || []) {
+        const active = group.filter((key) => options[key] !== undefined && options[key] !== false);
+        if (active.length > 1) throw new ArgumentError(`options conflict: ${active.join(', ')}`);
+    }
+    const minimum = definition.minPositionals ?? 0;
+    const maximum = definition.maxPositionals ?? Infinity;
+    if (positionals.length < minimum) throw new ArgumentError('missing required argument');
+    if (positionals.length > maximum) throw new ArgumentError(`unexpected argument "${positionals[maximum]}"`);
+    return { options, positionals };
+}