yannikzz/ui-contract/ui-contract-audit

Health check

Produces a runnable script in the user's repo (starting point: assets/audit.sh.template) plus a difference report. This is the only unit here whose artifact is executable rather than markdown.

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.

The script reads that table itself, at run time. It does not carry a second copy of the paths, and adapting it does not mean filling paths in. Five knobs remain, and each is a fact the table cannot hold:

It used to be eleven, six of them paths. Measured, twice in one afternoon: SRC set to the production tree reported all 24 allowlist names as "declared but never rendered"; set to the wireframe, it reported the wireframe's own NEUTRAL map as hardcoded-colour drift. Neither was a bug in a check — both were a caller getting a wide interface wrong, and both produced a confident wrong report.

The script encodes that first split as two different exit codes, and they must not be merged back into one:

A fourth tier sits beside the exit code rather than inside it. Clauses marked 🌡 in design.md are hypotheses, so they print a warning and leave the exit code alone: failing a build on a provisional clause hands whatever the clause borrowed a veto over the project's CI.

The cost of that is real and is not hidden: "warnings present, exit 0" is green in CI. The count printed at the end is the only thing that keeps such a report from being read as clean. Never silence it, and never promote a warning to drift without first moving the clause to 🔒 in design.md — the marker is what decides the tier, not the script.

2 and 3 read almost the same in a terminal and are opposite conclusions: 2 says this project has no contract, 3 says it has one and this run is pointed at nothing. Sharing an exit code makes a broken setup look like a clean project, which is the one failure this whole unit exists to prevent. Report exit 3 as a finding, never as "nothing to check".

Exit 3's meaning did not change when the paths moved into the table; only its detection did. It used to compare a path written into the script against the table's — a comparison that no longer exists, because there is no second copy to disagree. The failure it caught changed shape rather than going away.

Two more states are deliberately not exit 3, and telling them apart is the whole point:

It reports; it does not fix

Fixing means changing structure, which means walking the placement decision tree — a decision that belongs to a human, not to a drift detector. Auto-fixing also inverts the sync order the whole method rests on: documents change first, code follows.

So the output is differences plus suggestions, and the suggestion always names the clause that was violated.

Cheap enough to run often

The value of a health check is inversely proportional to what it costs to run. It has to be cheap enough for every release, ideally cheap enough for CI. So the body is automated checks; agent judgement is the supplement, never the substance.

Twelve of fifteen run automatically and fit in CI. If that ratio drops much below eight tenths, this unit has degenerated into subjective re-reading and its value claim fails — that is its stated revisit condition, not a slogan. It currently sits at twelve fifteenths — four fifths, and the three agent-judgement rows are recorded rather than rounded away:

Sizes cannot be checked by regex. A visual spec legitimately discusses numbers — in prose ("no writing off-table px sizes in feature code"), and in anti-pattern rows ("six months in you'll have 13px / 13.5px / 15px at once"). Measured against a real spec, a px regex produced four hits and all four were false positives. A check that cries wolf on correct documents is worse than no check, because people stop reading the output. Colours stay automated: a hex code in a visual spec is unambiguous.

The contrast check reads hex only. A project on a modern token convention writes its colours in oklch(), and the script cannot resolve those — so on such a project it finds no pairs at all. It reports that as skipped, not passed. A green tick there would be the precise failure this whole unit exists to catch, and the tuning instrument (ui-contract-design) is where those projects get contrast validated instead.

The declaration table is found by its three origin keywords, not by its header row — a spec written in the user's language has a translated header. Those keywords (borrowed / this project / not used) are therefore required to stay ASCII, which ui-contract-design states beside the table. If somebody translates them anyway this check finds nothing and says so as a skip; it never reports a wrong answer, but it does go quiet, so a green run here is not proof that the naming is sound.

The threshold is read from `design.md`, never hardcoded. It is found by its shape (4.5:1) rather than by the words around it, because the deliverable is written in the user's language. Rewrite the shape and the check goes quiet — it degrades to no check, never to a wrong one. Same property as the paths-table lookup, and for the same reason.

Do not grep for `data-region="..."` to find region names. The runtime marker is written once, inside the container, as an expression. The only literal occurrence in a healthy tree is the annotation layer's own display text — grepping for it finds the label, not a region. Read the ids off the container's call sites instead; keep a separate grep for literal markers, because those mean somebody wrote a raw element and skipped the type check entirely.

What this version can and cannot see

The asset layer in this version ships only the allowlist type and the structural container. So:

• The token-file checks run only if the project already has a token source
• The declaration-table check needs both design.md and the token file; with either missing it skips and says which one
• The "asset layer matches the region tree" check compares against the container, not against a shell
• Check 10 reports all three states of a structural number: settled, waiting (⏳), refuted (⛔) — refuted rows are lifted verbatim and counted separately from pending ones
• The report ends with a machine-readable tail, AUDIT-JSON {"checks":{...},"warnings":N}: one entry per check, pass/skip/fail, worst grade wins. The prose and the exit codes are unchanged; automation reads the tail instead of parsing prose
• The two agent-judgement checks are available but must be requested; they are not part of the cheap path

Say which checks ran and which were skipped. A green report that silently skipped half its checks is worse than a red one.

Before you call this done

• [ ] The script actually ran, with real output pasted — not just written
• [ ] Every skipped check is named, with the reason
• [ ] If any warnings printed, they are reported as warnings — not folded into "no drift found" because the exit code was 0
• [ ] Every finding names the clause it violates
• [ ] Nothing was auto-fixed
• [ ] The script is committed to the user's repo and works without an agent