yannikzz/ui-contract/ui-contract-enforce

Enforcement

Produces edits to the repo-root CLAUDE.md and to the type layer. No new document.

For pushing rules into the type system, call the Skill tool with "constraint-by-types". For the interview discipline, call the Skill tool with "decision-interview". For the deliverable's language and terminology, call the Skill tool with "deliverable-language".

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.

There is no wireframe precondition. Enforcement depends on the allowlist, not on anything being drawn — it runs fine in a repo that has never had a wireframe.

The one question this unit asks

How hard should enforcement be?

Two passes, not one

The four layers below do not become installable at the same moment, so this unit runs twice.

Do not install the compile-time layer on a staged asset layer. A union that lives outside the product constrains only what lives beside it. Measured (2026-08-25): in the admin-console example, PageWithInspector, TableColumnKind, InspectorKind and PageKind are all declared in wireframe/src/wire.tsx; every one of them is a layout.md clause, and none of them reaches a line of production code. ui-contract-assets records the same measurement from the other side — kept word-for-word on both sides on purpose, so the two can be compared. It type-checks, it goes green, and it guards a directory that gets deleted.

The layers

Documents alone don't get read — least of all when the task sounds small ("just adding a button"). Miss a layer and things leak through.

The compile-time layer has to sit on code that ships

A union type only fires where something type-checks against it. So "the allowlist is a union type" is half a mechanism; the other half is which typecheck it is part of, and that half has been left implicit.

A wireframe's typecheck does not count. The wireframe is a throwaway reference implementation — constraining it constrains nothing that ships, and if the project keeps its wireframe out of the repository, that typecheck does not run in CI at all. Either way the layer reports nothing and looks no different from one that is working.

Two things have to be true, and both are checkable:

1. The union type lives in the asset layer, inside the product source tree, and the command a contributor or CI actually runs (tsc --noEmit, pnpm typecheck, whatever the project uses) covers that path.
2. Something fails even when no product code happens to use a given region name yet. On a young project most of the allowlist has no call sites, so an empty product tree type-checks clean against any union at all — including one somebody weakened. The assertion file in constraint-by-types §2 is what closes this; without it, the layer's strength is proportional to how much code already exists, which is backwards.

Verify it by breaking it. Put an off-allowlist name into a product file, run the project's typecheck, and paste the error. A layer nobody has seen fail is a layer nobody has seen.

The asset boundary is the newest layer and the least obvious. Layering the specs into production code created a new drift surface: the asset layer is real production code, so business pressure pushes changes into it directly — someone adds a slot to a container to ship a feature, and the spec never hears about it. The boundary clause is what makes that visible at review time.

The three forms of the allowlist

Put a line at the top of layout.md §2 saying that changing the table requires changing both of the others.

Before you call this done

• [ ] Region names are identical across the document, the type definition, and the code — grep every allowlist name and find it in all three
• [ ] The repo-root CLAUDE.md entry clause exists and names the decision tree by section
• [ ] Every "must not hold" entry that can be expressed as a type omission has been, with a comment marking the omission deliberate
• [ ] Each of those omissions also has a line in the assertion file (constraint-by-types §2), so deleting the prohibition breaks the build instead of going silent
• [ ] The union type is in the product source tree, and the project's own typecheck command covers it — name the command. A wireframe's typecheck does not satisfy this
• [ ] The assertion file is inside that same typecheck's `include`. Nothing imports it, so a narrow include drops it silently
• [ ] Enforcement was verified by breaking it: an off-allowlist name was written into a product file, the project's typecheck was run, and the real error is pasted
• [ ] The asset boundary clause is written, and it names both halves (no hardcoded token values; no locally-declared structural containers)