Concepts
The Risk Model
SAFE, REVIEW, DANGER — and why there's no grey area.
Three tiers, no grey area
Every field change lands in exactly one of three tiers. The boundaries are conservative by design — when layoutd can’t prove a change is safe, it says so rather than guessing.
Proven. Auto-generated.
A provably-correct transformation exists. layoutd emits complete migration logic — no human input, no offset math to verify.
Probably safe. Human eyes needed.
Code is generated with a warning. Correctness depends on context the tool can't see — CI policy decides auto-pass vs. required approval.
No provable path. Fails CI.
No automatically-correct transformation exists. CI fails by default; shipping requires an explicit, recorded acknowledgement.
Zero false-safe verdicts
The north star is a single guarantee: layoutd never calls something safe that isn’t. It may flag a change for review as often as needed — conservative refusal is always acceptable — but optimistic generation never is. A migration the tool can’t prove correct is one the tool will not silently emit.
The acknowledgement mechanism
Failing CI on DANGER forces an explicit, recorded decision instead of a silent one. To ship a known danger, you name that specific change in the CI config (the --ack file). Only the named danger passes — any other danger still fails the build.
This is strictly better than hand-writing the migration, where the dangerous change is invisible in a normal-looking diff. The danger doesn’t disappear; it becomes a permanent, audited line in your version history.
Acknowledgement is a record, not a bypass
--ack file doesn’t make it safe — it makes the decision visible and attributable. Reviewers and auditors see exactly which danger was accepted, by whom, and when.Next, see how each kind of change maps to these tiers in The Five Change Cases.