Structural spec — layout.md

Produces one artifact: layout.md. Skeleton and per-chapter requirements are in layout-md-outline.md. The question bank is interview-layout.md. Read both.

For the interview discipline, call the Skill tool with "decision-interview". For which document a thing belongs in, call the Skill tool with "ui-contract-glossary". For the deliverable's language and terminology, call the Skill tool with "deliverable-language". For handling change requests once something is running, call the Skill tool with "spec-before-code".

Preconditions

Artifact paths come from docs/ui-contract/config.md's paths table. If that file doesn't exist, the specs are at the repo root. Never assume a path the config contradicts.

Check these before asking anything. All three are hard stops, not warnings.

The first row's third clause matters: once layout.md exists, this gate must not fire again. Without it, every later maintenance edit on an existing project is blocked forever.

The third row is this plugin's upstream boundary, and it is narrow on purpose. It fires on nothing to place, not on vague: a rough list of features is workable input, and sharpening it is what the interview is for. A product that has not decided what it does yet cannot have a region tree, and inventing one produces a spec that constrains nothing — every later feature lands outside it, so the placement tree sends everything to §9 and the contract degrades into a permission queue.

Three things decide whether this document is useful at all

1. The placement decision tree goes first (§1), and it has to be total.

It is the entry point: an agent takes a new requirement, walks the tree, implements directly if it lands — and stops if it doesn't. Total means every input reaches exactly one region name or the explicit stop, never zero and never two.

A tree with a hole is worse than no tree: agents don't halt at a hole, they improvise past it with the document's authority behind them.

The fallback must be the explicit stop → §9, never some real region, and it must not route back into the tree.

2. Every row of the region allowlist (§2) needs a "must not hold" cell.

Listing only what goes in a region is documentation; stating what must not go in is a spec. The forbidden entries come from every "don't make it X" conclusion in the interview. This column is also the only thing the compile-time layer can act on later.

3. Every anti-pattern carries a reason and a replacement.

"Don't do X" gets worked around. "Don't do X, because it causes Y, do Z instead" gets followed.

No visual values

layout.md contains no color values, font sizes, radii, or spacing values — only structural parameters (column widths, minimum sizes, region counts, grid columns). Where a value is needed, write "see design.md §X".

Region descriptions say what goes here / what must not — never "what this is", which is visible from the screen. A wrong description is more dangerous than wrong code, because the next agent extends from it.

Before you call this document done

• No color / font-size / radius / spacing values anywhere
• Every structural number that only a type or spacing scale can validate is marked ⏳, with what would settle it (layout-md-outline.md §3) — writing one plainly claims a certainty nobody has yet
• The ⏳ list was handed over as a copyable note, carrying the marked lines verbatim — paraphrasing invents a requirement, and for a visual owner who is somebody else this note is the only thing that reaches them. ui-contract-audit check 10 reprints it later in the same shape
• Traced the decision tree with the four hostile inputs (layout-md-outline.md §Verify), each landing on exactly one region name or the explicit stop. The traces are written into Appendix C, not just performed in the conversation — one that leaves no trace in the artifact is indistinguishable from one that never happened
• The fallback is stop → §9, not a real region, and it doesn't route back into the tree
• Traced three or four ordinary requirements onto region names, also in Appendix C — stopping on everything passes the hostile traces too, and turns the contract into a permission queue
• Every allowlist row has a "must not hold" cell, none of them empty, and the column's header is copied from layout-md-outline.md §2 — re-read the table you wrote, not the one you meant to write. This is the step that has been skipped: the document still looks complete without the column
• Every anti-pattern has a reason and a replacement
• Every region description says "what goes here / what must not", not "what this is"
• The half was ended where it ends, and handed over — see below

Where this ends

layout.md is the structural half's deliverable. Three things still follow it inside this same half — the asset layer, the entry-layer enforcement, and then a rebuild of the projection — and they are the rest of handing this document over, not the start of the visual half. The projection comes last because a source has just changed and it is rebuilt from the changed source.

docs/ui-contract/config.md records two answers that decide what happens next: how far this session was authorised to go, and who answers for the visual half. Unless it says the visual half is authorised, do not enter it. Not "ask first" — do not enter it. A visual spec produced without somebody answering for the brand is a set of decisions nobody made, written in the shape of a specification, and nothing in the file reveals that.

Hand back, in plain words: what layout.md owns, that the projection is a viewing device rather than a deliverable and does not survive a fresh clone, and what the visual half would settle if and when it runs.