[PierreMardon]

ARCHITECTURE.md had grown two and a half times in nine days by sentences added to its paragraphs, until one held 5,080 bytes, and told history as reasons (#118). The developer decided on 2026-10-12 how to close it: a rule that sorts, the page written again against it, two bounds in the gates, and the page read by the developer at every change.

Closes #118

What changes

• A rule that sorts, in AGENTS.md. The page says what the chain is now, in the present tense. A reason says what the alternative would cost, never what happened when it was tried: that goes in the pull request, or in an ADR. What a prompt, a template or a guide says stays there, and the page names the file. A change to the wording of a prompt leaves the page alone. The line that sent to the page everything that is not an ADR is gone.
• The page written again. Same frame, same section titles. The long paragraphs are cut by subject: the commands and the agents one item each, "Critical zones" into the steps a zone goes through, from its declaration to the developer's reading.
• ADR 0038, a critical zone is touched by file. That reading was chosen among the three ways of A blueprint says the plan touches no critical zone, and the hand back at conformity sends the developer to read a file of one #107 and is likely to be "fixed": the record keeps the context the page no longer tells.
• Two bounds, in tests/prompts/test_document_form.py. 600 bytes for a paragraph, a list item or a table row, and 28,700 for the page, its size plus a tenth. A paragraph wrapped over several lines is read as one. The message of a failure gives the way out: cut by subject, or move out what the page does not hold.
• ARCHITECTURE.md declared a critical zone of this repository, in AGENTS.md: a blueprint announces a plan that changes it, and the pull request lists it for the developer to read.
• No prompt changes, so the chain behaves as before and no campaign of the evaluations is owed.

Measured

	Before	After
Bytes	30,925	26,089
Longest paragraph, in bytes	5,080	517
Paragraphs, items or rows over 600 bytes	12	none

The page is 16 % shorter, not the 35 to 40 % first estimated: most of its sections were statements of the state already and stay as they were. What left is the detail of the form of the blueprint, the operating detail of the two billed suites and the stories.

What left the page, and where it is

What	Where
The form of the blueprint: a fact said once, the cut, the titles in bold, no numbered heading, the five aspects, the diagrams	agents/surface-extractor.md, skills/surface-plan/templates/blueprint.md
The two repairs of a returned plan, and how a commit is written	skills/surface-plan/SKILL.md, the template of the plan, agents/surface-extractor.md
The exact words of the definition of a file of a zone, and what a branch may change in a zone named as touched	the three agents, ADR 0038
How the corrections of a refused list are counted	skills/surface-execute/SKILL.md
The replies of the end to end scenarios, the three reasons of the git directory of the stand-in gh	tests/e2e/README.md
The case that states a wrong rule on purpose, the runs stopped at the hand over, the detail of the count	evals/README.md
Why the prompts ban neither cd nor git -C, why no check is prescribed at a moment	ADR 0032, ADR 0037
The two readings of a zone that were tried, the wider definition	ADR 0038

Two reasons are in no file any more, each for a rule its prompt still states: "a page that tells a rule three times is a page the developer skims", and "a number would shift and send a report to another section".

Checked

• scripts/gate.sh, green on 3.11 and on 3.14 before the corrections below; the prompt tests, the formatter and the linter after them.
• An independent reading, by a fresh agent given the old page, the new one and the rule, and asked where the new one fails. It compared 179 sentences: 114 stand word for word, and of the facts of the 65 others none is lost, each found on the page or in the file named above.
• It found seven places where the new page said more or less than the old one: an exception or a condition dropped, a count that was not exact. All seven are corrected in the last commit, with the five paragraphs it found to hold several subjects.

To weigh

• Under the bound of the page, an agent may squeeze sentences instead of sorting. Nothing mechanical prevents it: the reading of the critical zone does.
• The bounds are the developer's: an agent that raises one to pass is changing a file of this pull request's test, which a review sees.
• The other pages a person reads show the same pattern, evals/README.md and tests/e2e/README.md first. They are a second piece of work.