docs: the language closes its own gaps instead of offering an escape hatch

[FBumann]

Prompt: "We decided to NOT add an escape island!!"

Note

The following content was generated by AI.

The README and the home page sold an escape: island. No key for it exists in src/, and #38 was closed not_planned on 2026-08-27. Both now say what is true: math the language cannot express is a gap in the language.

What this changes

Where	Was	Is
README.md, docs/index.md	"A finite language with a priced way out" — unsayable math "goes in an escape: island, visible in the file and billed before it runs"	"A finite language, with no escape hatch" — a gap closes as a macro, a primitive or a formulation
AGENTS.md	triage is "macro, primitive, or escape"; the ceiling is "relational ∩ local"	"macro, primitive, formulation, or refused"; the ceiling is relational, and locality prices a primitive rather than barring it
docs/examples/index.md	the port ledger's verdicts are "macro, primitive, or escape"	the same four
docs/about/roadmap.md	partition-wise execution is safe because of "the locality closure"	safe because every operator in the language today reads a bounded number of rows per output row

Why

An escape: island is the one thing a reader of that bullet would plan around, and it does not exist. The ceiling wording changes with it. energy-models/mathspec#468 stops treating locality as a gate and makes it the price a new operator pays, which retires "relational ∩ local" as the way to say what the ceiling is. The roadmap's partitioning claim rested on the same closure, so it now rests on the operators the language actually has.

What was verified, and what was not

pixi.sh is blocked from this session's network, so pixi run check was not run. In its place:

• ruff format --check . — 239 files already formatted.
• python -m tools.constructs --check — docs/examples/index.md matches the models. The edited line sits outside all three generated blocks, as do the docs/index.md edits relative to home-math:begin/end.
• pytest tests/test_docs_site.py tests/test_doc_examples.py — 127 passed, 4 skipped. The skips need the [linopy] extra and are unrelated.

A real pixi run check is still owed before merge.

Prose measured with the docs-writing skill's script: README.md avg 19.1 → 18.6, median 18 → 17, over-25 16 → 15; roadmap.md avg 18.6 → 18.5, median 15, over-25 9 before and after. No sentence this change adds exceeds 25 words.

Deliberately not done: the docs are corrected, but nothing is proposed in place of the hatch. With no escape, every gap has to close as a macro, a primitive or a formulation, and which gaps exist is a measurement this PR does not make — a coverage ledger against an external corpus is the follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T18AdG3hoawcwuqXxr4dnM

[codspeed]

Merging this PR will not alter performance

✅ 24 untouched benchmarks
⏩ 58 skipped benchmarks¹

---

_{Comparing claude/amazing-mayer-v5bhvt (cf92844) with main (6dd80ce)}

Footnotes

1. 58 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[read-the-docs-community]

Documentation build overview

📚 lpspec | 🛠️ Build #34566210 | 📁 Comparing cf92844 against latest (6dd80ce)

  🔍 Preview build  

3 files changed

± index.html
± examples/index.html
± about/roadmap/index.html