diagram-authoring-guard

name	diagram-authoring-guard
description	Guard rails for writing or editing diagram YAML. Use before authoring a new diagram, changing frame structure, adding arrows, or adjusting spacing in diagrams/1.input/**. Routes to the derived-value register and to the corpus checks that will judge the work.
argument-hint	Name the diagram slug or the field you are about to set

Diagram authoring guard

When to use

• Authoring a new frame YAML in diagrams/1.input/.
• Editing structure, arrows, or spacing in an existing one.
• About to write a number into a frame and unsure whether the engine owns it.
• A rendered diagram does not match what the YAML reads.

Skip this for code-only work that does not touch diagrams/1.input/**.

The one rule

If the engine derives a value, do not author it. Hand-setting a derived value does not customise the diagram; it opts that frame out of the design language. It will still render, which is why nobody catches it.

Read docs/authoring-invariants.md before writing any number. It is a register, not an essay — one table of what is derived, by what, and whether you may set it.

Procedure

1. Check the register first. For each value you intend to write, find its row. If the answer is "No", delete the line and let the engine derive it.
2. Do not author padding below the root. The root's padding is the canvas margin; everything else is role-derived.
3. Do not author gap to fix a box's internal rhythm. A wide band between composition columns is legitimate; correcting spacing inside a panel is not. A labelled arrow widens its own container's gap automatically.
4. Do not pin arrow anchor sides. foo.right switches off nearest-side inference, fan-out planning and parallel ports at once, so the arrow breaks the moment the layout direction changes. Write foo and let the router pick. Before adding a reverse, parallel, self-loop, or arrow-reference edge, read the cross-engine topology section in docs/authoring-invariants.md. ELK Layered accepts simple frame-to-frame DAGs and routeable reciprocal frame bundles today; the registry honestly withholds it from residual long cycles, pinned/authored routes, one-way multiplicity, self-loops, and arrow endpoints rather than attempting parameter tuning.
5. Do not hand-tune label_gap. If a label collides, the layout is wrong. Fix the structure.
6. Set level: explicitly on every headed container, per docs/frame-classes.md and the level-assignment skill. This is the one thing you must author.
7. Compare against the reference. diagrams/1.input/approved-visual-language.yaml authors no padding and no gap anywhere. If your file is looser than it, you have overridden something.
8. Run the checks before claiming done. npm --prefix packages/layout-engine test.

What will judge the work

These fail on violation and name the diagram:

• authored-padding-corpus.test.ts — hand-set padding below the root
• arrow-label-clearance-corpus.test.ts — a label over a filled box or a shaft
• annotation-spacing-parity.test.ts — label offset must equal leaf text offset
• level-promotion-corpus.test.ts — siblings must share a structural tier

Both corpus allowlists are shrink-only. Adding an entry is not a fix.

Guardrails

• A green suite is not a rendered diagram. Load it in npm run preview before calling it done.
• Do not copy spacing from a nearby diagram. Nine of the corpus files predate the current rules, and two are on the padding allowlist precisely because they are wrong.
• If you believe a derived value is wrong, change the derivation and its test — do not work around it in one YAML file.