# CLAUDE.md — Thea Software, contract v3.9.2

**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.

```bash
python scripts/atlas.py gate  <path> <gate>    # ONE command: cheapest answer, most accurate
python scripts/atlas.py route <path> --json    # pack, card, manifest, label, lane, authority
python scripts/atlas.py plan  <path> --task <task> --change <class> [--modifier <m>] --json
python scripts/atlas.py process <id> --json    # a named process: gates, artifacts, stop/escalate
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*.

`route` names **the precedence rule that resolved it, with evidence**, so a match and a lucky
guess differ. `--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 41 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_fixture_that_names_what_it_could_read` — a passing test that planted nothing
- `a_guard_that_crashes_on_another_guards_input` — a broken harness, so the real finding is never reached
- `a_count_typed_into_prose` — an accurate sentence, on the day it is written
- `a_flow_value_split_on_a_comma` — a declaration that reads complete in the file and is half missing once loaded
- `a_generated_block_carrying_a_relative_link` — a working link, in the document it was written in
- …and 37 more in `atlas.yaml/agent_failure_modes`

## 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`, `quantum_change`) and satisfy its
gates, then verify **on the exit code**, never on output:

```bash
python scripts/verify.py            # every gate below, one verdict each; exit 0 only if all PASS
python scripts/atlas.py check
python scripts/atlas_test.py
python scripts/agent_test.py
python scripts/astshape.py
python scripts/exrun.py
python scripts/contextcost.py
ruff check .
```

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.

## Claude Code specifics

- Route first; load only the pack named. A whole-repo read is `context_policy/forbidden_default`.
- Deterministic rules belong in hooks, not instructions: instructions are not a sandbox.
- Adapter: [models/claude/README.md](models/claude/README.md); runtimes: [MODEL.md](MODEL.md).
