Cadora · design spec

Verification, by the numbers

Everything needed to rebuild or extend the surfaces that prove agent work — the exact tokens, the badge system, the failure panel's anatomy, and every state each must render. The rendered components are live HTML; edit them here or lift the specs into Figma.

Palette

Dark instrument surface · green proves · amber warns · red blocks

Green--green · #16c784Gate passed · integrity clean

Amber--amber · #ffd08aVacuous · prerequisite · flagged

Red--red · #fb7185Failed · packaging · blocking

Chip · okbg · #0f5132Green badge ground

Chip · warnbg · #5a4a15Amber badge ground

Chip · badbg · #5a1622Red badge ground

Chip · neutralbg · #26324aUntoned badge ground

Ink--bg · #0f172aPage ground · terminal

Canvas--canvas · #111c2fInset · terminal frame

Line--line · #334158Borders

Text--text · #f5f7fbPrimary · gate output

Muted--muted · #9aa8bcSecondary · labels

Type & metrics

System sans for reading · monospace for the instrument voice

Role	Family	Size / weight	Notes
Badge chip	mono	10px / 700	Radius `4px`, padding `3px 5px`; tone = semantic ground + text
Gate / terminal output	mono	12px / 400	Verbatim stdout+stderr; line-height 1.7; wraps, never truncates mid-token
Failure reason	system-ui	13px / 600	Colour `#ffb4b4`; leads with `✗`
Block label	mono	11px	e.g. `gate vacuous output`, `integrity findings`
Exit code · counts	mono	12px	`exit 1` · `2 blocking` — the numbers, never a stack dump

Metric	Value	Metric	Value
Badge radius	4px	Panel radius	10px
Badge padding	3px 5px	Panel border	1px rgba(210,90,90,.35)
Badge gap	3px	Pre ground	rgba(0,0,0,.28)
Terminal frame	radius 8px	Pre max-height	300px · scroll

Badge system

Every verdict a node can carry — gate state, then integrity state

gate passed gate failed gate vacuous gate blocked_prerequisite gate packaging_failed clean flagged

Badge	Tone	Means	Passes?
gate passed	green	Exited `0` and — for a test gate — at least one test actually ran.	Yes
gate failed	red	Non-zero exit for a real, in-workspace reason (a genuine test/lint failure).	No
gate vacuous	amber	Exited `0` but a test runner executed zero tests — verified nothing.	No
gate blocked_prerequisite	amber	Failed on external missing tooling — not the agent's fault, not its to fix.	No
gate packaging_failed	red	A declared installable package that does not `pip install`.	No
clean	green	Integrity: no counterfeit or substituted build/test tooling found.	—
flagged	amber	Integrity: findings present — open the failure panel to read them.	—

Tone is computed, not authored: a status containing passed is green, one containing fail is red, everything else is amber — so vacuous and blocked_prerequisite read as "ran, but proved nothing," while packaging_failed reads as a hard block. Integrity is green when clean, amber otherwise.

Anatomy — the failure panel

Why a node is blocked, shown verbatim — never paraphrased

✗ gate 'build-test' blocked

gate vacuous output

All checks passed!
no tests ran in 0.01s
warning: No Python files found under the given path(s)

integrity findings

stub-implementation 3 function(s) have a stub body (pass / ... / raise NotImplementedError) — the code looks implemented but isn't; tests that pass over stubs verify nothing

1Failure reason — one line, led by ✗: the run's own node.error, e.g. gate 'build-test' blocked or gate 'build-test' blocked by missing prerequisite(s): quotes.

2Gate output block — a mono label naming the status (gate vacuous output) over the command's combined stdout+stderr in a scrollable <pre>. Shown only when the gate itself failed.

3Integrity findings — each finding as <rule> <detail> in a list; the rule (e.g. stub-implementation) bolded. Shown only when findings exist.

The two blocks are independent: a node can fail on the gate, on integrity, or on both. The panel renders whichever applies. The gate output is the last ~2000 chars, verbatim — the reader sees exactly what the process printed, not a summary of it.

States

Every verdict the surface must render

Passed · proven

gate passedclean

Failed · real bug

gate failed

F401 `typing.List` imported but unused

Found 1 error. · exit 1

Vacuous · tested nothing

gate vacuous

no tests ran in 0.01s

exited 0 — verified nothing

Blocked prerequisite · external

gate blocked_prerequisite

No module named 'quotes'

missing: quotes · not remediable

Packaging failed · won't build

gate packaging_failed

Multiple top-level packages discovered in a flat-layout

pip install -e . refused

Integrity flagged · counterfeit tool

flagged

✗ blocking shadowed-toolchain: pytest

Gate & integrity CLI

Every flag that shapes a verdict

Flag	On	Effect
`--gate-cmd`	run · gate-check	Command a gate runs when not overridden in the topology `gates:` map. Default `ruff check . && pytest -q`; non-zero exit blocks.
`--gate-setup {off,auto}`	run · gate-check	Provision an isolated Python gate venv from `requirements-dev.txt` (default `auto`). The venv lives outside the workspace.
`--gate-wheelhouse DIR`	run · gate-check	Offline wheel directory — installs with `--no-index --find-links`, no network.
`--integrity-mode {off,audit,enforce,repair}`	run	Toolchain integrity handling (default `audit`): audit records; enforce blocks; repair drives one fresh repair session.
`--remediate N`	run	On a `failed`/`vacuous`/`packaging_failed` gate (or a blocking integrity finding), run up to N fresh constrained repair sessions (default `0` = off).
`--remediate-max-cost USD`	run	Stop remediation honestly (`honest-blocked`) before its summed cost exceeds this ceiling.

Command	Cost	What it does
`cadora gate-check <topology> --cwd <ws>`	no executor · no LLM	Runs the topology's gates against an existing workspace; a shared gate runs once; exits non-zero if any gate fails.
`cadora integrity [workspace] [--json]`	no executor · no LLM	Scans a workspace for counterfeit/substituted tooling; exits non-zero on a blocking finding.

Reading the verdict — what to do

Each badge maps to one action

Badge	What it means	What to do
gate passed	Proven — real command, real tests, exit 0.	Nothing. Ship it.
gate failed	A real lint or test failure in the workspace.	Read the gate output; fix it — or `--remediate N` to drive a fix.
gate vacuous	The suite ran zero tests.	Write real, substantive tests — a green on nothing is not a fix.
gate blocked_prerequisite	External tooling is missing.	Provide the dependency/compiler yourself; the agent cannot author it (not remediable).
gate packaging_failed	Declared package won't `pip install`.	Declare packages (`[tool.setuptools.packages.find]`) or move code under `src/`.
flagged	Integrity found counterfeit/hollow tooling.	Remove the shim / fill the stubs; run under `enforce` or `repair` to gate on it.

Voice

Words are part of the design

Do	Not
Name the status — "gate vacuous"	Generic "failed"
"Green means proven, not claimed"	"Success!"
Show the gate output verbatim	Paraphrase what the command "probably" said
Say what to do — "suite ran zero tests — write real tests"	"Invalid"
exit 1 · 2 blocking	A raw multi-page stack trace

Tokens and metrics are taken verbatim from cadora/dashboard/static/style.css; the status vocabulary and tone rules from cadora/gates.py and app.js. Edit the rendered components in place, or hand the palette and tables to a Figma library.

Design specification for Cadora's verification surfaces: the color and type tokens, the badge system for gate and integrity states, the anatomy of a failure panel, every state it must render, and the gate and integrity CLI reference.