CLAUDE.md · git:20260926.38c6dad · 2026-09-26 · sha256 4756bbdad24a5f10
CLAUDE.md git:20260926.38c6dadA
Immutable. This exact content never changes and is served at /api/v1/blob/4756bbdad24a5f10.
# 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).