CLAUDE.md · diff
git:20260926.38c6dad to git:20260926.0266684
3 added, 75 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
- # 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.
+ <!-- GENERATED by `atlas.py index --write`; edit atlas.yaml, not this file. -->
+ @AGENTS.md
## 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).
+ - Adapter: [models/claude/README.md](models/claude/README.md).