thea-software

# Headron Software by HLIntel LLC (contract v3.62.0)

> Rules and build checks for AI coding agents.

<!-- GENERATED from atlas.yaml by `atlas.py index --write`; do not edit. -->

- **Is:** a CLI and rule contract for AI coding agents. Each changed file maps to the checks it owes; the commit hook refuses one that fails to parse or type-check, `headron verify` runs the rest.
- **Is not:** a coding agent, model, test framework, or proof code is correct. A check that cannot run reports SKIP or NOT RUN, never a pass; the hook lets that commit through.
- **Needs:** Python >=3.11, pyyaml, defusedxml. No account or key. A package install fetches its matching release from GitHub on first run.
- **`headron init` writes:** AGENTS.md, CLAUDE.md, .mcp.json, .codex/config.toml, .git/hooks/pre-commit. An existing hook moves to `pre-commit.legacy` and still runs; `headron enforce uninstall` restores it.
- **Mind API:** hosted, paid, needs a key; plans a declared change. The command line works without it.

**First reply**: act; ask for a task only if none was given. With `headron`, skip this reply; `["port", "<file>"]` before edits; `["verify"]` before done. No shell: [CHAT.md](CHAT.md), skill first.

## Verbs

`headron <verb>`, in a clone `python scripts/atlas.py <verb>` (`atlas.py port <file>`), or MCP (read-only). Exit code is the verdict; JSON: `tools/atlas-output.schema.json`.

- `intake [<prompt>]`: a prompt as a task: file, role, change class, gates, next; or the questions it lacks
- `resume`: where interrupted work stands, and the one next action
- `port [<target>]`: route, tier, gates, lessons, next commands for a file or tree
- `find <query>`: search: embeddings, prefixes, pointers
- `route <path>`: pack, card, manifest, lane and the rule that resolved a path
- `gate <path> [<gate>]`: the one command a gate runs for a file
- `plan <path>`: the gates a task and change class need for a path
- `steps <path>`: ordered plan for one runtime, entry to return
- `pipeline <path>`: one file end to end: ingest, classify, verify, exit
- `shell [<cmd>]`: refuse shell whose verdict or effect differs from what its writer reads
- `failures [<id>]`: mistakes agents made here, each with its guard
- `landed <branch>`: is every branch change in the base? Ask before deleting
- `check`: the whole contract
- `verify`: every done gate once: PASS, FAIL or NOT RUN, by exit code
- `doctor`: local prerequisites; packprobe checks language tools
- `commands`: every command and instrument, as text or JSON

## Records

- `.agent/bootstrap.json`: this entry as JSON · `.agent/facts.json`: every published figure
- `AGENTS.md`/`CLAUDE.md`: agent runtimes; rules for changing Headron itself · `CHAT.md`: a chat with no shell
- `route <file>`: which of the 40 packs governs it; then read its `tools.yaml`

## When asked to use, install, open, run, pull, report

- **use**: run `headron gate <file>` and the commands it prints; `headron enforce install` makes every commit prove itself.
- **install**: README's quickstart; in a clone, `python -m pip install --require-hashes -r scripts/requirements.lock.txt`.
- **open**: load only your runtime's entry file, then `headron port <path>`; never read the tree breadth-first.
- **run**: `headron verify` for your change; `headron check` for the whole contract.
- **pull**: pin a release tag, never main; to update a clone, `git pull --ff-only` then `headron check`.
- **report**: run `failures <id> --draft '<text>'`, then `skills/headron/SKILL.md`.

## Files

- [MODEL.md](MODEL.md): operating model; read when routed
- [atlas.yaml](atlas.yaml): single source of truth: routes, invariants, gates, profiles, policy
- [docs/INDEX.md](docs/INDEX.md): every document
- [SECURITY.md](SECURITY.md): security policy and measured platform controls