# 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 130 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).
