@rmyndharis/aimhooman 0.1.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**yudhi@rmyndharis.com**. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary ban
+
+**Community impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the ban, is allowed during this period. Violating these
+terms may lead to a permanent ban.
+
+### 4. Permanent ban
+
+**Community impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

package/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing to aimhooman
+
+Thanks for considering a contribution. aimhooman is a small,
+zero-runtime-dependency Node ESM tool, so most changes are approachable.
+
+## Prerequisites
+
+- **Node.js 22.8 or newer**
+- **Git 2.28 or newer**
+- **Go 1.25.x** for the pinned `actionlint` release gate
+
+The published runtime has no dependencies. Development tools are locked in
+`package-lock.json`.
+
+## Getting started
+
+```sh
+git clone https://github.com/rmyndharis/aimhooman.git
+cd aimhooman
+node --version    # needs >= 22.8
+npm ci --ignore-scripts
+npm run verify    # schemas, workflows, dead code, coverage, package, installed hooks
+```
+
+## Ways to contribute
+
+- **New detection rules** for an AI tool aimhooman doesn't cover yet.
+- **New host adapters** for an AI coding tool not in the support matrix.
+- **Bug fixes** and **documentation** improvements.
+
+## Adding a rule
+
+Rules live in `rules/` as JSON arrays: `paths.json` (staged paths),
+`attribution.json` (commit-message lines), `markers.json` (staged content),
+`secrets.json` (high-confidence secret patterns). Each
+rule has the shape:
+
+```json
+{
+  "id": "provider.state",
+  "version": 1,
+  "provider": "provider",
+  "category": "ephemeral-state",
+  "confidence": "high",
+  "kind": "path",
+  "match": { "paths": ["**/.provider/**"] },
+  "actions": { "clean": "block", "strict": "block", "compliance": "block" },
+  "reason": "Provider artifacts are local, not repository content.",
+  "remediation": ["git restore --staged <path>"]
+}
+```
+
+Notes:
+
+- `kind`: `"path"`, `"message"`, or `"code"`.
+- `match.paths` use glob syntax (`*`, `**`, `?`, `[class]`). In a pattern such as
+  `**/.x/**`, the leading globstar matches zero or more directories, so one pattern
+  covers both `.x/file` and `nested/.x/file`. An explicit `.x/**` companion is
+  allowed for readability but is not required.
+- `match.content` are regular expressions; prefix `(?i)` for case-insensitive.
+  Local packs use the safe flat subset documented in the README; built-in packs are
+  package-reviewed and may use the wider JavaScript syntax.
+- Path matching is case-sensitive unless `match.path_case` is `"insensitive"`.
+  Use that per rule only when the security name itself is case-insensitive; Git path
+  and override identities remain unchanged.
+- `actions` per profile (`clean` / `strict` / `compliance`). Residue should
+  `block` on all three. Exact high-confidence AI attribution may `block` on
+  clean/strict and `allow` on compliance; ambiguous identities should remain review-only.
+- Add positive and near-miss fixtures in `tests/rule-contracts.test.mjs`. The
+  contract test fails when a catalog rule has no fixture.
+
+## Adding a host adapter
+
+- **Plugin-tier** (live `PreToolUse` guard): see `.claude-plugin/`,
+  `.codex-plugin/`, `.github/hooks/`. Claude and Codex load the packaged hook
+  manifest. The Copilot repository hook calls `aimhooman` from `PATH`.
+- **Instruction-tier** (ruleset text): copy `AGENTS.md` verbatim into the host's
+  rule file, register it in `docs/hosts.json`, then run
+  `npm run sync:ruleset` and `npm run sync:hosts`. The copy
+  and package gates derive required adapter paths from that registry, check exact
+  ordered ruleset regions, and reject unregistered copies.
+
+See `docs/design/agent-portability.md` for the full host matrix.
+
+### Local rules (don't commit these)
+
+Personal, per-clone detection belongs in `<git-common-dir>/aimhooman/rules/*.json`
+(local, never committed). Linked worktrees share it. Contribute general-purpose
+rules to `rules/` instead.
+
+## Commit policy (important)
+
+This project keeps AI tooling residue out of history — **including its own**.
+Commits must read as if a human wrote them:
+
+- **No AI attribution** in commit messages: no `Co-authored-by:` naming an AI,
+  no "Generated with/by …", no AI-service noreply emails. (Yes, aimhooman
+  enforces this on itself.)
+- Keep commits focused — one logical change per commit.
+
+## Pull requests
+
+1. Open a PR against `main`.
+2. Include tests for any new behavior and run `npm run verify`.
+3. Update `CHANGELOG.md` and `docs/` where relevant.
+4. Make sure the PR follows the commit policy above.
+
+By participating, you agree to abide by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+This is a personal, owner-only repository. GitHub branch rules require the `tests`
+workflow but no pull-request approval, code-owner review, last-push approval, or
+other reviewer. The repository has no `CODEOWNERS` fallback.
+
+Changes to agent instructions or `.aimhooman.json` are protected-path changes. CI
+verifies the pinned repository and owner login plus numeric IDs through the GitHub
+API, then fetches the exact workflow-run attempt. GitHub must attribute the
+attempt's `actor` and `triggering_actor` to that owner's login and numeric ID. CI
+binds that authorization to the exact
+head, transition commit, path, resulting blob and regular-file mode, or deletion
+tombstone. Policy migrations additionally bind the old and new policy objects.
+Another commit, attempt, path result, mode, or migration needs fresh authorization.
+A protected-path change by any non-owner fails closed.
+
+The owner account and its credentials are the repository trust root. These checks
+verify GitHub's actor attribution and bind the resulting objects; they do not prove
+an interactive human action, provide independent review, or protect against a
+compromised owner credential.
+
+Releases publish to npm automatically when a `v*` tag is pushed. The workflow
+installs dependencies, runs the test suite, and publishes with npm build provenance,
+authenticated by the `NPM_TOKEN` secret. To cut a release: bump the version (keep
+`package.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, and
+`.claude-plugin/marketplace.json` in sync), add the `## [version]` CHANGELOG entry
+and the matching README version badge, then tag and push:
+
+```sh
+git tag -a v0.1.0 -m v0.1.0
+git push origin v0.1.0
+```
+
+Protect `v*` tags so only the owner can create them and tag update or deletion is
+blocked. Use a granular, publish-only, package-scoped npm token with 2FA enabled
+and rotate it regularly. Do not run `npm publish` or move dist-tags manually while
+a release job is pending or running.

package/GEMINI.md

@@ -0,0 +1,53 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yudhi Armyndharis & aimhooman contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.