A blueprint that says a fact once, and shows behavior, not code

ARCHITECTURE.md

@@ -23,7 +23,7 @@ host CI    --runs----> surface-status check --require conformant
 ```
 
 - **Commands** are three skills the developer types. `/surface-plan` explores, interviews, has the plan drafted and writes it with its gates, has the blueprint drawn and cross-checked, then commits, pushes and opens a draft pull request. It then stays in the conversation and takes amendments there, as it does after a block during planning, since a reply that approves nothing needs no new launch. `/surface-execute` approves the drafted revision by being launched, then dispatches slices, gate runs, reviews and fixes. It puts a plan change proposal and the ceiling to the developer in the conversation: a refusal or a resumption goes on in the session, while an accepted change or an amendment goes to `/surface-plan`, since this command cannot load it and never writes the plan. `/surface-status` reports, runs the conformity check, and abandons a plan on confirmation.
-- **Agents** are four roles of the chain, and one agent built into Claude Code. The `Plan` agent drafts the plan, in the form it chooses: a good plan is what it already does well, so the chain ships no definition for it and holds the plan only to the minimum it reads, the numbered acceptance criteria, the slices behind their markers, each enough for an agent that starts fresh, and the `gates` block ([ADR 0035](docs/adr/0035-plan-drafted-by-the-built-in-plan-agent.md)). It has no write tool: it returns the plan, and `/surface-plan` writes `plan.md` as returned, but for two repairs it makes without a word to the developer, who never reads the plan: a return that arrived escaped, whose markers the script would not read, and a path of the machine. The extractor draws `blueprint.md` from `plan.md`, as long as the feature needs, since the developer reads all of it. A blueprint has a fixed frame and a free body: it opens with the idea, the acceptance criteria and the scope, and closes with the sensitive zones, while the extractor cuts the body by what the developer decides separately, and keeps the cut of the previous revision, so that a revision is read against the one before. No heading carries a number: a section is cited by its title, which an amendment does not move, where a number would shift and send a report to another section. Five aspects are gone through whatever the cut, the data schema, the boundaries, the sequences, the state machines and the algorithms, and one closing line names those the plan leaves alone, since silence must not read as "unchanged". A diagram is drawn where what it shows has a shape that prose flattens, with the existing elements the change attaches to. The checker looks for what the plan does and the blueprint does not show, never for a cut, a short section or a diagram that is not there. The executor carries out a slice or a fix. The reviewer judges the branch against the approved blueprint, writes `conformity.md` when it finds nothing, with the changed files of the critical zones, judges a break an executor suspects, and corrects that list of files when the script refuses it.
+- **Agents** are four roles of the chain, and one agent built into Claude Code. The `Plan` agent drafts the plan, in the form it chooses: a good plan is what it already does well, so the chain ships no definition for it and holds the plan only to the minimum it reads, the numbered acceptance criteria, the slices behind their markers, each enough for an agent that starts fresh, and the `gates` block ([ADR 0035](docs/adr/0035-plan-drafted-by-the-built-in-plan-agent.md)). It has no write tool: it returns the plan, and `/surface-plan` writes `plan.md` as returned, but for two repairs it makes without a word to the developer, who never reads the plan: a return that arrived escaped, whose markers the script would not read, and a path of the machine. The extractor draws `blueprint.md` from `plan.md`, as long as the feature needs, since the developer reads all of it. A fact is said once in prose on the whole page: the criteria state the rules, and the body shows what no criterion states, as behavior and not as code, since a page that tells a rule three times is a page the developer skims. So an aspect the plan changes is shown by a criterion or in the body, and the checker reads both. A blueprint has a fixed frame and a free body: it opens with the idea, the acceptance criteria and the scope, and closes with the sensitive zones, while the extractor cuts the body by what the developer decides separately, and keeps the cut of the previous revision, so that a revision is read against the one before. No heading carries a number: a section is cited by its title, which an amendment does not move, where a number would shift and send a report to another section. Five aspects are gone through whatever the cut, the data schema, the boundaries, the sequences, the state machines and the algorithms, and one closing line names those the plan leaves alone, since silence must not read as "unchanged". A diagram is drawn where what it shows has a shape that prose flattens, with the existing elements the change attaches to. The checker looks for what the plan does and the blueprint does not show, never for a cut, a short section or a diagram that is not there. The executor carries out a slice or a fix. The reviewer judges the branch against the approved blueprint, writes `conformity.md` when it finds nothing, with the changed files of the critical zones, judges a break an executor suspects, and corrects that list of files when the script refuses it.
 - **The state script** derives the state, refuses illegal steps, runs the gates, and answers the skills and the host's CI.
 - **A plan folder**, `docs/plans/<date>-<slug>/` by default, holds the specs, the exploration, the interview, the plan, the blueprint, the reports (`checks/`, `reviews/`, `plan-changes/`, `gates/`), `conformity.md` and `journal.jsonl`. It is the whole state of a plan.
 - **The installer** copies the chain into the host, updates it, and checks it for drift.

agents/surface-checker.md

@@ -22,7 +22,7 @@ Count only what would change the decision of the person who validates the bluepr
 
 The closing section of the blueprint, the sensitive zones, names each critical zone the repository's agent instructions declare that the plan touches, or says that the plan touches none: the developer reads the code of those zones themselves, and learns there which ones. A critical zone the plan touches and the sensitive zones do not name is an omission, even when another section shows the change. So is a closing section that says nothing of the critical zones, or says none while the plan touches one.
 
-The blueprint is as long as the feature needs, and its body is cut for the feature. The cut, the titles and the order of its sections are never an omission, and neither is a short section or the absence of a diagram: only what the blueprint does not show counts. Whatever the cut, five aspects must not be left in the dark: the data schema, the architecture and its boundaries, the sequences, the state machines, the algorithms. The closing line of the blueprint names those the plan leaves alone. An aspect the closing line names while the plan changes it is an omission. So is an aspect neither shown in the body nor named by the closing line: the developer cannot tell that the feature leaves it alone.
+The blueprint is as long as the feature needs, and its body is cut for the feature. The cut, the titles and the order of its sections are never an omission, and neither is a short section or the absence of a diagram: only what the blueprint does not show counts. Whatever the cut, five aspects must not be left in the dark: the data schema, the architecture and its boundaries, the sequences, the state machines, the algorithms. The closing line of the blueprint names those the plan leaves alone. An aspect the closing line names while the plan changes it is an omission. So is an aspect neither shown on the page, by a criterion or in the body, nor named by the closing line: the developer cannot tell that the feature leaves it alone.
 
 If you find nothing, say so: zero omissions is an answer.
 

agents/surface-extractor.md

@@ -32,6 +32,8 @@ And the repository's agent instructions, `AGENTS.md` or `CLAUDE.md` at its root,
 
 Write in the language `exploration.md` names in its repository rules. The blueprint is as long as the feature needs, and no longer: the developer reads all of it, so a small change gets a short page. No section and no diagram is written for its own sake.
 
+A fact is said once in prose on the whole page, the frame included: the idea sums the feature up, and a diagram may draw what the prose says. The acceptance criteria state the rules, carried whole, and nothing tells them again: the body shows what no criterion states, the shape of the data, the boundaries between components, an order between actors, the states, an algorithm, an irreversible effect, an assumption the plan takes, the case that explains a rule, and names a criterion instead of saying it again. The scope says what is left out: what is done stands in the criteria and in the body, never there. The sensitive zones name each zone, point to the criterion or the section that holds its rule, and say in full only what stands nowhere else. The statement of the critical zones and the closing line are always written, even when a criterion says the same.
+
 ### The frame
 
 Every blueprint opens and closes the same way, so the developer always finds what the work is judged against. No heading carries a number: a section is cited by its title, which an amendment does not move.
@@ -50,7 +52,7 @@ Sensitive zones opens with the critical zones because their code is what the dev
 
 ### The body
 
-Between them, the body shows what will be built. You choose how to cut it: by what the developer has to decide separately, never by the slices of the plan nor by the layout of the code. Take the first cut that fits:
+Between them, the body shows what will be built. It shows behavior, which the developer decides, not code. What a user, a file or another program sees stays on the page: a name they type or read, a message, the value of a limit, a dependency the feature adds, which component calls which, each component under the name the repository gives it, with what it answers for. What only the code sees stays in the plan: the names of functions, constants and helpers, the calls to a library, the layout of the code. You choose how to cut it: by what the developer has to decide separately, never by the slices of the plan nor by the layout of the code. Take the first cut that fits:
 
 1. One behavior, a small change: no cut, a single section.
 2. Several flows or visible behaviors, largely independent: one section per flow, each with its own data, order and states.
@@ -64,7 +66,7 @@ When `blueprint.md` already exists, read it before you write: keep its cut and i
 
 ### The aspects
 
-Whatever the cut, five aspects must not be left in the dark: the data schema, the architecture and its boundaries, the sequences, the state machines, the algorithms. Go through each: what the plan changes of it is shown in the body, in the section it belongs to. The blueprint ends with one closing line that names every aspect the plan leaves alone, as the template shows, so the developer sees at a glance what the feature does not touch. There is no closing line when the plan changes all five.
+Whatever the cut, five aspects must not be left in the dark: the data schema, the architecture and its boundaries, the sequences, the state machines, the algorithms. Go through each: what the plan changes of it is shown on the page, by a criterion or in the body, in the section it belongs to. The blueprint ends with one closing line that names every aspect the plan leaves alone, as the template shows, so the developer sees at a glance what the feature does not touch. There is no closing line when the plan changes all five.
 
 ### The diagrams