AGENTS.md — Headron Software, contract v3.62.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.

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 123 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:

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.