AGENTS.md · git:20261117.644c481 · 2026-11-17 · sha256 36726b932d1b173d
AGENTS.md git:20261117.644c481A
Immutable. This exact content never changes and is served at /api/v1/blob/36726b932d1b173d.
# AGENTS.md — Headron Software, contract v3.63.0 **GENERATED by `python scripts/atlas.py index --write`; `atlas.py check` fails on any hand edit.** It comes from `atlas.yaml`, `VERSION` and the tree: change the declaration, not this file. ## Ask, do not read **Never read this repository breadth-first.** Ask where to go, then load only what the answer names. **Plug in:** `python scripts/atlas.py port <file|dir|.> --frame agent`: route, tier, gates, lessons, next steps. Hooks: shell `headron shell --json "<cmd>"` · edit `headron port <file> --line` · done `headron verify`. ```bash python scripts/atlas.py gate <path> <gate> # ONE command: cheapest answer, most accurate python scripts/atlas.py plan <path> --task <task> --change <class> [--modifier <m>] --json python scripts/atlas.py check # exit code IS the verdict; doctor: can it run here ``` Asked to *use, install, open, run, pull, report* this repository? `llms.txt` → *When asked to*. Directed into a role? `headron role`. Picking up interrupted work? `headron resume`. `--json` records are frozen in `tools/atlas-output.schema.json`: depend on those ids. ## Rules that fail the build 1. **No count typed into prose.** Generate it, or name the instrument that prints it. 2. **No calendar date.** Stamp a claim with its contract version; only an external project's own date-shaped version (`atlas.yaml/external_versions`) is exempt. 3. **No tool name in prose.** Tools live in `languages/<route>/tools.yaml`; documents name *gates*. 4. **Refuse rather than invent.** `none` is a real answer; a parser that picks a winner on ambiguous input is worse than one that errors. 5. **Every limit names its closer.** All 95 instruments carry `proves`, `does_not_prove` and `closed_by`; an empty closer fails. 6. **Never raise a cap to fit your code.** `code_shape` and `context_policy` ratchets only fall: split the function or shrink the entry path. 7. **A change ends when the artifact parses.** Every tracked source and JSON file must parse; that check runs first. 8. **A control with no enforcer is refused.** Controls, sandbox rows and gates each name their deciding function (`atlas.yaml/agent_policy`). ## Mistakes made here before, by an agent Each RECURRED here: once is a bug, twice a rule. Learn the shapes; they return in other files. - `a_check_proven_on_one_shape_of_input` — a verified command, and a hook that suddenly rejects good code; a passing MCP probe, and a client that cannot connect - …and 129 more: `headron failures` ## Before you claim a change is done Pick the change class (`source_change`, `api_change`, `dependency_change`, `security_sensitive`, `concurrency_change`, `performance_change`, `retrieval_change`) and satisfy its gates, then verify **on the exit code**, never on output: ```bash python scripts/verify.py # PASS / FAIL / NOT RUN per gate; exit 0 only if every gate passed ``` It runs `verification_policy/done_set` and prints each gate. Both suites plant a real defect per rule and assert their own case counts: new rule, new planted defect. Land with `python scripts/branchstate.py --land`; a bare push of a lane is refused. ## Where to put what Repeated fact: `atlas.yaml` plus a generated block. Language tool: its pack's `tools.yaml`. New rule: its own `*_errors()` and planted defect. Example: `examples/`, and it must run. ## Runtime notes - One body for every runtime, pointed at and never copied: CLAUDE.md routes here, Hermes reads `.agent/bootstrap.json`, a bare model `llms.txt`. Adapter: `models/<runtime>/README.md`; [MODEL.md](MODEL.md).