@nurix/etna 0.19.10 → 0.19.12

package/data/harnesses/code/skills/design/references/hard-rules.md

@@ -1,177 +0,0 @@
-# Hard rules — the boot-loaded floor
-
-The hard-prose channel: every machine ban, deterministic threshold, and mandatory procedure the skill enforces, one imperative line each. This file loads into context before any design output.
-
-The backticked anchor id is the shared key: the same id names the `rules.csv` row, the check-engine rule key, the fixture pair, and a finding's provenance. Machine rules are absolute — a violation is fixed now, or classified as inapplicable in `docs/memory/design-decay.md`; never ignored silently. No waivers, no inline suppressions. Lines tagged `· render` are decided on the rendered surface at the render rung (pixels or DOM), not from source at edit time. Judged dimensions are diagnosed, not gated — the index at the foot points at where their judgment lives.
-
-## Doctrine floor
-
-The twelve fixed principles the rule families below serve — the canonical in-skill enumeration. Nothing overrides them: expressiveness is granted by the per-surface delight budget *inside* the floor, never as an exception to it. Cite a principle by its id.
-
-- Throughput vs delight is weighed per surface (`f01`).
-- Empty states are text-first (`f02`).
-- Side panels over modals (`f03`).
-- Numbers are tabular (`f04`).
-- One accent is the default (`f05`).
-- Keyboard-first (`f06`).
-- Semantic token classes only (`f07`).
-- State persists in emitted code (`f08`).
-- Wrong-fit briefs are refused cleanly (`f09`).
-- The substrate is Tailwind + shadcn-flavor only (`f10`).
-- A modular SKILL.md router with lazy references (`f11`).
-- Vocabulary is a business call (`f12`).
-
-## Typography
-
-- `typ-01` Body text contrast ≥ 4.5:1; large text ≥ 3:1. · render
-- `typ-02` Body ≥ 14px on operator surfaces; never below 11px anywhere.
-- `typ-03` Form inputs ≥ 16px on touch/mobile surfaces; desktop operator inputs exempt.
-- `typ-05` Prose measure 45–75ch; tables exempt.
-- `typ-06` ≤ 3 font families per app, each with a distinct job (display / body / numeric-mono); a fourth family is banned. Type scale holds the declared ramp's steps (≤ 7).
-- `typ-07` Tabular lining numerals (`font-variant-numeric`) on every numeric column, KPI, timer, ID.
-- `typ-08` All-caps micro-labels: letter-spacing ≥ 0.02em (caps band 0.05–0.12em); tracking never below −0.04em.
-- `typ-09` Font sizes from a fixed rem scale (step ratio 1.125–1.2) — the fixed scale is the declared ramp's emitted utilities (`text-h1` … `text-display`), not merely *a* scale; ban `vw`/`vh`/`clamp` on font-size; operator surfaces.
-- `typ-10` Adjacent type-scale steps ≥ 25% apart.
-- `typ-11` No UI font weight below 400.
-- `typ-12` Never size type in `em`; px or rem only.
-- `typ-14` Typographic characters: curly quotes/apostrophes, en-dash for ranges, real ellipsis/×/© glyphs, one space after punctuation; never underline non-links; bold XOR italic, never both.
-- `typ-15` Zero em-dashes in UI copy.
-- `typ-16` Ban serif faces in dashboards and software UIs.
-- `typ-18` Uppercase-tracking (eyebrow/micro-label) instances ≤ ceil(sectionCount/3).
-- `typ-19` Code/mono type fixed at 16px; long lines scroll horizontally, never wrap.
-- `typ-20` The `display` ramp step appears only on surfaces stamped `brand-forward`; ≤ 1 display-step element per surface.
-
-## Color
-
-- `col-01` Non-text UI contrast ≥ 3:1 (input borders, icons, focus rings). · render
-- `col-02` One accent, reserved for primary action / selection / state; accent saturation < 80%. Status palettes are additional, not accent violations.
-- `col-03` Color never the only signal; status pairs with an icon or text. · render
-- `col-04` Status colors only via semantic tokens: `--success`, `--warning`, `--destructive`.
-- `col-05` Ban literal palette classes, hex/rgb/oklch literals, and `dark:` prefixes in JSX.
-- `col-06` No pure `#000000` text or canvas, no pure `#ffffff` surfaces; start near `#111827`/`#1F2937`. Fires only when no brand token declares pure black.
-- `col-07` No opacity- or `rgba()`-fabricated shades; every shade is an explicit hex or token.
-- `col-08` Greys 8–10 shades; each accent family 5–10.
-- `col-09` Disabled-state opacity 0.38–0.5.
-- `col-10` Modal scrim 40–60% black.
-- `col-13` Semantic price/status colors are text-only, never fills; never repurposed for generic success or error.
-- `col-14` Data-viz: lines/bars ≥ 3:1 vs background; data labels ≥ 4.5:1. · render
-- `col-16` A wash token (`--wash-*`) is consumed only on `brand-forward`-stamped surfaces; wash stops obey the slop ban (`col-12` vocabulary).
-
-## Spatial
-
-- `spc-01` Every spacing value on the declared 4/8 scale (standard 4/8/12/16/24/32/48/64/96px; dense 2/4/8/12/16/24/32px). The monotony sub-check (≥ 10 identical) excludes operator surfaces.
-- `spc-02` Adjacent spacing values ≥ 25% apart.
-- `spc-03` Tap/click targets ≥ 24×24px (SC 2.5.8); ≥ 44px touch-primary; dense data rows 28px; undersized only via the ≥ 8px spacing exception (`int-11`). · render
-- `spc-04` Numeric columns right-align, text left-aligns; ban center-aligned data columns.
-- `spc-06` Corners on a fixed radius scale (0/2/4/6/8/12/16/24/9999 — 0 = flat archetypes, 9999 = full/pill; a project's token artifact may declare a narrower scale, enforced by the drift check), one scale per page.
-- `spc-07` Dense table rows: 12px vertical cell padding + hairline dividers; buttons compact to 28px; mono numbers on every figure.
-- `spc-08` Full-viewport height uses `min-h-[100dvh]`; never `h-screen` or `100vh`.
-- `spc-09` Ban calc-percentage layout arithmetic (`calc(33% - 1rem)`); CSS Grid instead.
-- `spc-10` No horizontal scroll at any viewport (375/768/1024/1440); any overflow means broken. · render
-- `spc-15` Grid/bento integrity: N items fill exactly N cells; no orphan corners; spans interlock. · render
-- `spc-16` In fixed-width table/grid cells, rendered text fits the cell — no overlap or clip without a `truncate`/scroll affordance. · render
-
-## Depth & hierarchy
-
-- `dep-01` z-index only from the declared scale (0/10/20/40/100/1000); ban 999 and 9999.
-- `dep-02` One h1 per view; heading levels never skip.
-- `dep-04` Ban border and shadow doing the same separation job on one element.
-
-## Interaction
-
-- `int-01` Every interactive element ships a `:focus-visible` ring: ≥ 3:1 contrast, ≥ 2px (2–4px), with offset. · render (contrast)
-- `int-02` Ban `outline: none` without a replacement focus style.
-- `int-03` No pointer-only affordances; every hover-revealed control has a keyboard/focus path.
-- `int-04` Modals use native `<dialog>` + `inert` focus containment; ban nested modals; side panel before modal.
-- `int-08` Labels visible above the input; errors inline below the field (gap 4–8px); ban placeholder-as-label. Form fields only; a bare search input is exempt.
-- `int-09` `aria-sort` on sortable headers; sticky header/first column beyond one viewport; 5–7 default visible columns with a picker; bounded pagination ("1–25 of 150"), never infinite scroll on work queues.
-- `int-10` An `aria-live` region present wherever async status renders.
-- `int-11` Target-to-target spacing ≥ 8px.
-- `int-12` `cursor: pointer` on every clickable element (web).
-- `int-14` All five button states present: default, hover, active, focus, disabled.
-- `int-17` Discernible accessible name on every interactive element and image (`button-name`/`select-name`/`image-alt` Critical, `link-name` Serious). · render
-- `int-18` ARIA spec-valid: `aria-allowed-attr`, `aria-required-attr`, `aria-required-children`, `aria-valid-attr-value`. · render
-
-## Motion
-
-- `mot-01` UI transitions 150–250ms default (micro 100–150, state 200–300, larger 300–500); hard ceiling 500ms.
-- `mot-03` Every animation gated on `prefers-reduced-motion` (0.01ms reset).
-- `mot-04` Ban spring/bounce easing on operator surfaces; ban linear everywhere; easing strings from the token set (ease-out `cubic-bezier(0,0,0.2,1)`); no orchestrated page-load sequences.
-- `mot-05` Animate only `transform` and `opacity`; never top, left, width, height, or margin.
-- `mot-06` `will-change` only on an in-progress `transform`/`opacity` animation; never blanket, never left dangling.
-- `mot-07` Loading indicators skeleton the content shape; delay 150–300ms; nothing < 500ms, spinner/skeleton 500ms–2s, progress bar > 2s.
-- `mot-08` Stagger rides the `stagger-unit` token: 0–60ms per item, ≤ 8 children, total sequence < 1s (child count and total confirmed on the DOM at the render rung). Baseline-stamped surfaces skip arrival cascades; brand-forward surfaces may run `motion-stagger`.
-- `mot-09` Ban scroll-event listeners for animation (`window.addEventListener('scroll')`); observers or scrubbing only.
-- `mot-10` Ban `useState` for continuous scroll/pointer values; motion values instead. React-scoped.
-
-## States
-
-- `sta-01` Every data surface ships loading, empty, error, and partial/degraded states; plus post-action, cancel, disconnection/timeout, and concurrent-edit where they exist.
-- `sta-02` Empty states text-first, at most one action; never a dead-end on actionable surfaces, never a literal no-data message; copy 1–2 sentences.
-- `sta-03` Error states never dead-end: what happened / why / how to recover; an error render must carry a recovery affordance (the machine shell), the three-part copy quality is judged.
-- `sta-05` Toasts auto-dismiss 3–5s, `aria-live="polite"`, never steal focus.
-
-## Code & tokens
-
-- `cod-01` Emitted CSS defines every token the substrate consumes.
-- `cod-02` On improve runs, every value stays inside the lever manifest's vocabulary.
-- `cod-03` Every color, spacing, radius, and duration in a diff resolves to an emitted token.
-- `cod-04` Ban elision comments (`// rest of code`, `// ...`, `// TODO`, "for brevity"); files compile before done.
-- `cod-05` Anti-fabrication: no invented metrics, no fake round numbers (99.99%, 50%), no "BY THE NUMBERS" sections, no John Doe/Acme/Nexus names; fake-precise mock numbers carry a mock marker; unknowable values use a `[bracket]` placeholder.
-- `cod-06` No emoji anywhere, no emoji-as-icons; inline SVG only, one icon family per app, strokeWidth 1.5 or 2; never hand-rolled icon paths.
-- `cod-07` Check dependencies before importing; fonts self-hosted or `next/font` with `font-display: swap`; never a Google Fonts `<link>` in prod.
-- `cod-08` Image placeholders deterministic (`picsum.photos/seed/{seed}/{w}/{h}`); images declare dimensions; `loading="lazy"` below the fold.
-- `cod-09` Component line ceilings: < 120 ln table, < 80 ln section; never modify files outside scope.
-- `cod-11` Every emitted component exports a typed Props interface; no HTML tags in React Native output.
-- `cod-12` Runtime budgets: LCP < 2.5s, INP < 200ms, CLS < 0.1, 16ms frame. · render
-- `cod-15` Per-theme rendered token drift: under each theme context the resolver declares, rendered `--background`/`--foreground`/`--primary` equal that context's authored values. · render
-- `cod-16` Every family name in an emitted font stack binds to an installed package's registered family or a system generic (fail-closed at `--emit`).
-
-## Mandatory procedures (never skip)
-
-- `proc-01` Extract levers into a design-tokens artifact before any improve run on a foreign UI.
-- `proc-02` Ask the reader question before any introspect run — one question, every run, never a stored default.
-- `proc-03` Run the object pass (six-archetype catalog) before screens; a small brief earns a small pass, never a skipped one.
-- `proc-04` Declare the density tier per surface archetype before emission (global tier + per-archetype modifiers).
-- `proc-05` Name the taste anchor before look decisions: project artifact > library entry > Nurix default.
-- `proc-06` Run the self-critique pass against the brief and the ban list before declaring a create run done.
-- `proc-07` Resolve the design system and persist it (`personality.css`) before any UI code.
-- `proc-08` Token-lock at emission: after resolution, no value lands outside the emitted token file.
-- `proc-09` Run the mechanical pre-flight self-count: count rule instances against thresholds; the output fails if over.
-- `proc-10` Run the numeric-anchored self-audit passes, each with an exact-value criterion (canvas, corners-on-scale, shadows, link hover).
-- `proc-11` Follow the fixed audit ordering — hierarchy → typography → palette → spacing → buttons → clutter → empty states → shadows → contrast → grouping — then consolidate, dedupe, severity-rank, report before → after.
-- `proc-12` Run the copy self-audit: re-read every visible string, rewrite every flagged one.
-- `proc-13` Sweep viewports (375/768/1024/1440) before done; any horizontal scroll means broken — fix, don't ship.
-- `proc-14` Cross-check scope: compare deliverable count against scope count; add anything missing before responding.
-
-## Judged dimensions
-
-Not gated — diagnosed. Each names what the judgment covers; the mechanics live in [diagnosis.md](diagnosis.md).
-
-- `typ-04` Line-height inverse to size (body 1.4–1.6, headings 1.1–1.3); prose only, dense tables run tighter.
-- `typ-13` Dense-app type ladder is advisory; the declared scale wins.
-- `typ-17` AI-default fonts (Inter-as-reflex, Roboto/Arial/system, Space Grotesk) are house-taste flags.
-- `col-11` Hover darkens the base shade 10–15%; nearest token-ramp step wins.
-- `col-12` AI-slop palette: purple/blue neon glows and gradients, purple-on-white, reflex `#3B82F6`.
-- `col-15` One grey family per app; a deliberate warm/cool split is a brand decision.
-- `spc-05` Group spacing > within-group spacing (within 4–16px, between 24–64px); what reads as a group is judged.
-- `spc-11` Container max-width ~1400px / `max-w-7xl`; operator surfaces may be full-bleed.
-- `spc-12` Section rhythm 80px dense vs 96px marketing; advisory.
-- `spc-13` Cockpit rule above density 7: no card boxes, hairline dividers, tight padding, mono numbers.
-- `spc-14` Content-overload ceilings (> 7 action areas, 15+ elements, 12+ required fields, nav 5–9); dense surfaces may exceed.
-- `dep-03` Dashboard ≤ ~4 primary metrics above the fold; command centers may exceed.
-- `int-05` Undo over confirm for reversible actions; irreversible without confirm + undo is auto-critical.
-- `int-06` Optimistic updates only for low-stakes actions, always with rollback.
-- `int-07` Validate on blur, not per keystroke; strength meters and counters are exempt.
-- `int-13` One primary CTA per screen/region; one per pane on multi-pane surfaces.
-- `int-15` Virtualize lists ≥ 50 items; bounded/paginated lists exempt.
-- `int-16` Tactile press feedback (−1px translateY / scale 0.98, < 100–150ms); suppressed under reduced-motion.
-- `mot-02` Per-interaction reference durations (button 100 / hover 150 / tooltip 200 / tab 250 / modal 300 / page 400ms) — reference, not a ban.
-- `mot-11` Exit 60–70% of enter; press scale 0.95–1.05; ≤ 1–2 animated elements per view.
-- `sta-04` Errors render inline near the field, not banner-only; system-wide failures may banner.
-- `sta-06` Empty-state taxonomy: first-time / user-cleared / no-results / no-access / error, distinct copy each.
-- `cod-10` No div-built fake product screenshots.
-- `cod-13` Audit output carries a numeric before → after per finding; no vague "feels".
-- `cod-14` One name per concept, one concept per name across UI copy, help text, and API names.
-- `inst-01`–`inst-11` Render instruments (edge density, feature congestion, subband entropy, grid quality, white-space ratio, symmetry, figure-ground contrast, contour congestion, colorfulness, distinct-RGB count, KLM operator-cost) — evidence inside judged findings, never gates; see [diagnosis.md](diagnosis.md).
-- `trust-01`–`trust-04` AI-surface trust rubric (disclosure, human override, consent-gated irreversible actions, auditability); the first three grade auto-critical when absent; see [../data/operator-pack/trust-rubric.md](../data/operator-pack/trust-rubric.md).

package/data/harnesses/code/skills/design/references/improve.md

@@ -1,116 +0,0 @@
-# Improve — the engine
-
-> Loaded when the front gate routes to improve. Pairs with [diagnosis.md](diagnosis.md) (the finding source and format) and closes at the same machine-check wall create's gates enforce. Improve is every change to a UI that **already exists**; [create.md](create.md) owns the case where nothing does.
-
-Improve is one engine, not a set of commands. Every improvement — a review, a polish, a full redesign, a typography-only pass, a rendered judgment — is the same engine run at a different point on three axes. The familiar verbs are parameter bindings, not sibling workflows: there is no `review.md`, no `redesign.md`, no `judge.md`.
-
-## The three axes
-
-- **Scope** — what the run touches: one taxonomy dimension (e.g. `P1 Typography`), one surface, or the whole app. Scope is the diagnosis pass filter and the diff boundary at once.
-- **Depth** — `diagnose-only ↔ apply`. Diagnose-only emits ranked findings and stops. Apply edits the files the findings name.
-- **Authority** — `lever-jailed ↔ lever-consent`. Jailed (the default): emit only values inside the lever manifest's vocabulary. Lever-consent: the manifest itself may change — but only the changes the user has consented to.
-
-Any point in the cube is reachable directly. The presets below are the common ones.
-
-## Preset verbs
-
-Bindings over the engine, in one table. Never restated as separate files.
-
-| Verb | Scope | Depth | Authority | Run |
-| --- | --- | --- | --- | --- |
-| `review` | whole app | diagnose-only | jailed | Rank findings across the app; change nothing. |
-| `polish` | whole app | apply | jailed | Fix everything reachable inside the current levers. |
-| `redesign` | whole app | apply | lever-consent | Apply the consented lever changes, then polish within the new manifest. |
-| `typeset` | `P1 Typography` | apply | jailed | Apply, scoped to the Typography dimension only. |
-| `judge` | whole app (narrowable to a surface) | diagnose-only | jailed | Rank findings from **rendered evidence** — screenshots captured, read back, critiqued (the protocol below); change nothing. |
-
-A narrower or wider pass — one surface, one other dimension — is the same table with the scope cell moved. Bind the parameters; do not author a verb. `judge --fix` is sugar, not a fifth row: a `judge` run followed by an apply-depth run over its findings — still jailed to the lever manifest, closing at the same verify sweep as any apply run.
-
-## The golden rule: jailed to the lever manifest
-
-A design skill improves a UI **using the levers already in it**. Emitting design disjoint from the surrounding UI is a failure, not a style choice.
-
-The project's design-tokens artifact carries the **lever manifest** — the `lever-manifest` in its `$extensions["com.nurix.design"]` payload (spacing scale, radius scale, shadow levels, motion durations/easings, icon family, accent count) plus the token-carried allowlists (the 36 color roles, the font stacks). Read it **first**, before any diagnosis or edit.
-
-### When the UI wasn't built by this skill: extract first
-
-No token artifact (`design.tokens.json`) at project root ⇒ recover one from the code before touching anything.
-
-1. **Scan the source for what IS** — the fonts actually in use, the literal color values that recur, the spacing steps, the radii, the durations, the icon family and stroke.
-2. **Write them into a design-tokens artifact** at project root — `design.tokens.json` + `design.resolver.json` per [SCHEMA.md](../data/design-tokens/SCHEMA.md), payload `provenance: extracted`, `sourced: <date>`, populated lever manifest and primitives.
-3. **Extraction records what IS, never what should be.** A UI running five fonts extracts five fonts. The reduction to two is a tier-two finding (below) — not an extraction edit.
-4. Run the coverage gate over it (`derive-personality.mjs <project-dir> --check`) exactly as over any other artifact.
-
-### The jail is mechanical
-
-An improve run may emit only values inside the manifest's vocabulary — on-scale spacings, manifest fonts, manifest colors, manifest radii and durations. This is not advice. The verify sweep's drift check reads the manifest (`preship-sweep.mjs --files <touched...> --manifest design.tokens.json`) and fails any run that emitted a value outside it, with the same fix-or-classify wall create's gates run into. There is no waiver.
-
-## Tier-two escalation: when the levers themselves are wrong
-
-Diagnosis may find the fundamentals wrong — five fonts where two would do, three competing accents, an off-scale spacing habit. Those are `tier: lever-change` findings (the diagnosis format's tier field). Fixing them means changing the manifest, which the jail forbids. The protocol:
-
-1. **Finish the within-levers work first.** Polish everything reachable inside the current jail.
-2. **Report the fundamentals as tier-two findings** — same canonical format, `tier: lever-change` — phrased as the change and its whole-UI payoff: *"these three changes would make the whole UI consistent."*
-3. **Offer** a follow-up run with lever authority. Never change fundamentals unbidden.
-
-Authority defaults to jailed; lever changes are consent-gated. The skill does not escalate itself — the user triggers the follow-up.
-
-A lever-consent run (redesign-shaped) does **not** unjail emission. It rewrites the manifest first — the consented changes only — then proceeds jailed to the **new** vocabulary. The drift check reads the updated manifest, so there is never an unjailed emit; the jail moves, it never opens.
-
-[introspect.md](introspect.md) runs this handshake in reverse: an introspect report's tier-two findings can seed a consented improve run.
-
-## Findings come from the diagnosis engine
-
-Improve does not diagnose on its own. It runs the shared diagnosis engine ([diagnosis.md](diagnosis.md)) scoped to the run's scope axis, causes-first (Structure → Behavior → Perception).
-
-Findings use the canonical format verbatim — dimension · cause layer · evidence (file:line / token / value) · before→after (numeric where machine-backed) · consequence · tier · severity · provenance. The list is severity-ranked (auto-critical → critical → major → minor). No numeric scores, ever.
-
-Diagnose-only depth stops here: the ranked list is the deliverable. Rendering it per reader register is [introspect.md](introspect.md)'s job, not improve's.
-
-## Apply depth: the same wall as create
-
-Every apply-depth run closes at the **same machine-check wall create's gates enforce**: after the last edit, run the scoped verify sweep over every file the run touched (`preship-sweep.mjs --files <touched...> --manifest design.tokens.json`), resolve every fix-or-classify finding it reports, and don't present results until it comes back clean. The wall is script-shaped — no hook fires it for you, and no run is exempt. An apply run is create's emission discipline pointed at files that already exist.
-
-When a finding names a chart, load `data/combinations/charts.csv` before fixing it; when a finding names an icon, `icons.csv` — the table is the floor for the replacement pick, and an off-table pick states its reason in the finding body. Contract: [combinations/Readme.md](../data/combinations/Readme.md). (The look tables never load here — emission is jailed to the lever manifest.)
-
-## Diff-scope discipline
-
-An improve run edits **only the files its findings name**. A run that writes a file outside its findings fails the pre-ship scope cross-check (`preship-sweep.mjs`).
-
-The universal preservation list holds regardless of scope or depth — never silently changed: route slugs, navigation labels, form-field names and order, analytics/event identifiers, API and data-contract shapes, and generated files. Per-project additions to this list, if ever needed, are entries in the project's token artifact payload — data, not run configuration.
-
-## Run shape
-
-1. **Read the lever manifest.** Extract one from the code first if absent.
-2. **Diagnose** scoped to the run's scope, causes-first; rank; split `within-levers` from `lever-change`.
-3. **Diagnose-only** → deliver the ranked findings and stop.
-4. **Apply** → edit only the files the findings name, then close at the verify sweep over the touched files, jailed to the manifest.
-5. **Escalate** → report the tier-two findings and offer the consented lever-authority follow-up.
-
-## `judge` — the rendered-evidence preset
-
-The invocable eye. `judge` is the preset row above run over **rendered pixels**: same engine, same jail, same finding format — plus screenshots captured, read back, and critiqued. It ships behind an explicit verb, never as a mandatory create phase; create's pipeline keeps zero model-judged rungs.
-
-The protocol, five steps, in order:
-
-1. **Render.** Reuse the render rung's browser plumbing: `render-rung.mjs --screenshot <outdir>` captures the app's key surfaces at **375 / 768 / 1440** (the rung's sweep also lands 1024 — a captured screenshot is read like any other) — the boot theme, *and* the second theme when the resolver declares a dark context (flip `data-theme`, as the rung's per-theme drift check does). Deterministic waits are the rung's existing settle logic; the PNGs land in a run-scoped temp dir.
-2. **Read back.** Read every captured image into context. **A screenshot you didn't read doesn't count** — describe each surface before critiquing it.
-3. **Critique against the four fixed referents** — never free-floating taste:
-   - **the brief** — does the rendered app serve the stated intent;
-   - **the artifact's `anchors`** — does the gestalt read in the named products' class: would this screenshot sit plausibly in Linear's or Stripe's product family;
-   - **the resolved style row's `checklist`** ([`styles.csv`](../data/combinations/styles.csv)) — the did-the-look-land walk, item by item, always including the standing harmony item: palette, type, and treatment read as one hand;
-   - **the project taste profile** (`docs/design/taste.yml`) — does the rendered app respect the recorded taste items; missing or malformed degrades to no-profile behavior with a one-line notice, as at intake.
-
-   Plus the standing judged dimensions — [diagnosis.md](diagnosis.md)'s taxonomy pass, Perception especially — with the screenshots as the evidence.
-4. **Findings** in the canonical format, verbatim — dimension · cause layer · evidence (now admitting screenshot path + region) · before→after · consequence · tier · severity · provenance — severity-ranked, unscored; fix-or-classify applies. Structure findings still precede Perception: causes-first holds even when the evidence is a pixel.
-5. **File the report.** A judge run always writes a dated findings report — `docs/design/judge-YYYY-MM-DD.md` in the consumer project — so the eye leaves a record even when nothing is applied.
-
-### Boundaries — what judge is not
-
-- **Not a rung.** The verification ladder is unchanged; no machine verdict rests on the model's read of a screenshot; a create run completes without judge ever running. Pixel instruments stay evidence-inside-findings — judge is a *workflow*, subject to the same rule.
-- **Not autonomous escalation.** judge recommends; the user triggers any follow-up — `judge --fix`, a lever-consent run. No regenerate-until-passing.
-- **Not a score.** No numeric grades in findings, ever — run-time scores are false precision; severity ranks plus the mandatory measurable before→after per finding give comparability without pretending decimals. Scores exist only outside the skill: the eval harness computes them from its own panel; the skill never self-scores.
-- **Instruments are evidence, never verdicts — on recorded empirical grounds.** "Lower visual complexity ⇒ higher quality" is refuted for this domain: surfaces that are dense on purpose invert the sign of "good". Computational clutter/aesthetics metrics validate correlationally and modestly — ≤ 49% of human ratings on webpages, ≤ 32% on apps, zero validation on dashboards and CRMs — and a subset are pretrained neural nets, excluded outright as model judgment. So a pixel instrument may be *cited inside* a judged finding and is structurally barred from gating. The two vetted instruments a judge finding reaches for first: **Edge Density** (`inst-01` — Canny edge pixels ÷ total pixels; r≈0.83 with visual-search times, the cheapest proxy for how fast an operator finds a target) and the **Keystroke-Level Model** (`inst-11` — P 1.10s · H 0.40s · M 1.35s · K 0.20–0.28s, summed over the core loop; countable operator-cost evidence for the throughput-vs-delight floor principle, `f01`). The interaction *path* is judgment, so KLM is evidence too, never ground truth.
-- **Degradation.** No headless browser → judge **refuses**, printing the rung's install command (`npm install -D playwright && npx playwright install chromium`) — an eye that cannot see does not judge from memory. It never falls back to source-only critique; source-only is `review`.
-
-Prior art for a future live-variant mode (consent-gated, human present — never a rung): impeccable's identity lock — extract the surface's existing identity into one non-aspirational sentence, then a mandatory squint test that every variant reads as the same brand — with 0–4 tunable `--p-*` parameter knobs per variant; the corpus's only closed taste loop with real eyes on it.

package/data/harnesses/code/skills/design/references/interaction.md

@@ -1,77 +0,0 @@
-# Interaction — keyboard-first control
-
-The operator keeps both hands on the keyboard and all attention on the task. This file is the interaction floor that preserves both: the state contract, focus discipline, overlay policy, consequence design, and the keyboard-first operator patterns.
-
-**Seams.** Element-level states (a button, a field, a row) live here. Surface-level lifecycle states — a data surface's loading / empty / error / degraded — and the error and empty-state copy formulas live in [lifecycle.md](lifecycle.md). Do not conflate a button's inline spinner with a surface's skeleton. Thresholds (ring contrast and width, target geometry, dialog mechanics) live in the catalog; this file names the contracts and cites the rule family by anchor prefix (`int-*` interaction, `sta-*` states, `mot-*` motion, `trust-*` AI trust) — it never restates the numbers. The boot-loaded imperative lines are in [hard-rules.md](hard-rules.md); the render-only checks run at the render rung (D32, [diagnosis.md](diagnosis.md)).
-
-## The state contract
-
-Every interactive element ships all its states, designed, never left to the substrate's defaults. Each state communicates one fact to the operator:
-
-| State | Must communicate |
-| --- | --- |
-| default | the element is here and actionable |
-| hover | the pointer is over an actionable target |
-| focus | the keyboard is on this element right now |
-| active | the press registered (tactile feedback) |
-| disabled | present but not actionable, and legibly why-context |
-| loading | the action is in flight; the element is busy, not broken |
-| error | this element's input or action failed, stated inline |
-| success | the action landed |
-
-Hover and focus are **different states for different users** — a pointer user reads hover, a keyboard user reads focus. Designing hover without a focus state strands every keyboard operator; it is the characteristic failure this contract exists to stop. Button-tier states (default / hover / active / focus / disabled) are presence-checked machine rules (`int-*`); distinct button tiers hold, one primary per region.
-
-The **error** state surfaces on blur, never per keystroke (`int-*`), and renders inline below the offending field — never banner-only for a field error. The error *copy* follows lifecycle.md's error formula. The **active** state's tactile press feedback rides the motion rules (`mot-*`, suppressed under reduced-motion); its timing tokens live in [personality.md](personality.md).
-
-## Focus discipline
-
-- **Visible focus, always.** Every focusable element carries a `:focus-visible` ring driven by the `--ring` token so it follows the look. `outline: none` without a replacement is banned (`int-*`). The ring meets the catalog's contrast and width floor — do not restate it, satisfy it.
-- **Focus order follows task order.** Tab order is the sequence the operator works, not a DOM accident. Composite widgets — tables, listboxes, menus, toolbars — use roving tabindex: the widget is one tab-stop, arrow keys traverse inside it.
-- **Focus is returned on overlay close.** Opening an overlay moves focus into it; closing returns focus to the element that opened it. Focus never drops to the top of the document.
-- **Keyboard path parity.** Every pointer affordance has a keyboard equivalent — nothing is reachable by hover or click alone (floor f06). Hover-revealed row actions carry a focus path (`int-*`). `cursor: pointer` marks every clickable element on the web (`int-*`).
-- **Skip links** jump to the primary work region on any surface with substantial navigation.
-
-## Overlay policy
-
-Escalate only as far as the interaction demands, cheapest rung first (floor f03):
-
-1. **Inline expansion** — reveal detail in place; no overlay at all.
-2. **Side panel** — detail and edit open *beside* the work, not on top of it (`--side-panel-width` / `--side-panel-width-rich`). This is the default for viewing and editing an entity.
-3. **Modal** — last, and only when earned.
-
-A modal is earned by exactly two cases: a **destructive or irreversible confirmation**, or a **self-contained one-to-two-field action** that must block the surface until answered. Anything larger — a full form, a multi-field edit, a record's detail — is a side panel or its own route, never a modal.
-
-Modal mechanics are structural: a native `<dialog>` with the background marked `inert`, so focus containment comes from the platform, not a scripted trap (`int-*`). One modal at a time — **nested modals are banned** (`int-*`); a second decision is either a step inside the first or a side panel. `--modal-width-max` caps width; a modal that needs its own scroll is really a side panel or a page.
-
-## Consequence design
-
-Match the affordance to the action's reversibility:
-
-- **Reversible action → undo, not confirm.** Perform it immediately; offer an undo affordance (`int-*`). A confirmation dialog on a reversible action is friction the operator pays on every repetition.
-- **Destructive irreversible action → confirm, with the consequence stated**, plus undo wherever the substrate allows a window. An irreversible action with neither confirmation nor undo is graded **auto-critical** in diagnosis (`int-*`; severity per D22).
-- **Consequence visible before commit.** Irreversible actions preview-then-commit: the operator sees what will happen — rows affected, records deleted, the exact scope — before the commit control.
-- **Optimistic updates only for low-stakes actions, always with rollback** and a visible reconcile on failure (`int-*`). High-stakes writes await server confirmation; they do not fake success.
-
-## Keyboard-first operator patterns
-
-- **Command palette** (`cmdk`) is the power-user's front door — global verbs, entity jump, reachable by a single chord. Expected on any multi-surface operator tool.
-- **Row-level keyboard actions in queues.** A queue row is focusable; the frequent verbs (open, assign, resolve, advance) bind to keys; the kebab overflow is keyboard-reachable, not pointer-only. Roving tabindex moves between rows, and the row's keyboard action set mirrors its pointer menu exactly — no verb is pointer-only.
-- **Tab-stop economics on the core loop.** The operator's core loop ([structure.md](structure.md)) must complete in few keystrokes and homings. Every tab-stop on the hot path is a cost paid per item, per shift — prune stops that do not earn their place, and keep the primary verb one key away.
-- **KLM is the diagnosis lens, not a gate.** Counting the keystrokes, pointer homings, and mental operators of a fixed core-loop path (the Keystroke-Level Model) turns "this feels slow" into a number. It rides [diagnosis.md](diagnosis.md) as a judged instrument against floor f01's throughput metric — evidence inside a finding, never a machine verdict.
-
-## Assistive floors beyond keyboard
-
-Presence-shaped, machine-checked wherever the rule holds universally (D26b; catalog plus render rung):
-
-- `aria-live` region wherever async status renders (`int-*`); toasts announce politely and never steal focus.
-- `aria-sort` on sortable headers (`int-*`).
-- `<dialog>` / `inert` containment on every modal (`int-*`).
-- The visible `:focus-visible` ring meeting the contrast and width floor (`int-*`).
-- Labels visible and above the input; placeholder-as-label is banned on form fields (`int-*`).
-- Accessible-name on every interactive element and image (axe `button-name` / `select-name` / `image-alt` / `link-name`); ARIA validity (`aria-allowed-attr` and family); minimum target geometry — all resolved at the render rung (`int-*`, D32).
-
-**Judged, not machine:** reading order beyond raw DOM sequence, screen-reader narration quality, whether a live region's politeness matches the update's urgency, and cognitive load. These are diagnosis dimensions ([diagnosis.md](diagnosis.md)), not presence flags.
-
-## AI surfaces
-
-Interaction governance for embedded AI and copilot surfaces — presence disclosed, a human override path always visible, irreversible AI-initiated actions consent-gated with preview, actions auditable — defers wholesale to the trust rubric ([trust-rubric.md](../data/operator-pack/trust-rubric.md)); it is not restated here.

package/data/harnesses/code/skills/design/references/introspect.md

@@ -1,100 +0,0 @@
-# Introspect
-
-The workflow that explains **why** a UI isn't working. Loaded when the front gate routes to introspect. Diagnoses with the shared engine (`diagnosis.md`); hands findings to `improve.md` on consent. Reads code — never edits it.
-
-## The deliverable is understanding
-
-Introspect produces a causal explanation, not a fix. The badness a user reports is always felt in **Perception** — the table looks noisy, the page feels heavy, nothing tells you where to look. Its cause almost always lives one layer down, in **Structure** (how it's built) or **Behavior** (how it responds). The run's job is to walk that chain and name every link, so the reader finishes understanding not just *what* is wrong but *why the thing they felt is produced by the thing they didn't see*.
-
-## The run
-
-1. **Ask the reader.** One question, before anything else (below).
-2. **Diagnose** with `diagnosis.md`: passes run causes-first — Structure → Behavior → Perception — producing severity-ranked canonical findings. Introspect invents no diagnosis of its own. When the audited UI renders charts, `data/combinations/charts.csv` loads into the pass — chart findings read against it, and an off-table judgment states its reason in the finding body.
-3. **Explain** each finding as a causal chain narrated the other way: from where the badness is felt (Perception) down to where its cause lives (Structure or Behavior).
-4. **Render** every finding in the reader's register.
-5. **File** the dated report; **offer** the improve handoff.
-
-## The reader question
-
-Asked at invocation, every run, verbatim:
-
-> Who is reading this — a designer, a developer, or a PM/general reader?
-
-Never inferred from the brief. Never a stored default carried from a prior run — ask again every time. Asking costs a beat and is never wrong; a silent guess about the reader is how one diagnosis turns into the wrong three sentences.
-
-The register is presentation only. It changes how a finding is *said*, never what the finding *is* — it is not an axis on the UI or on the diagnosis.
-
-## The three registers
-
-One diagnosis, three renderings. Same evidence, same fix, same severity — never three different opinions.
-
-- **Designer** — the untranslated finding, in design language: dimensions, hierarchy, the causal chain as-is. No translation; the finding is already in their tongue.
-- **Developer** — the finding compiled to code-speak: the token, the file, the line site, the exact edit, and whether it stays within existing levers.
-- **PM / general reader** — the finding translated to outcomes: what the operator loses today, what changes after the fix, and roughly what it costs.
-
-### Worked example — one finding, three ways
-
-Canonical finding (fields owned by `diagnosis.md`):
-
-- **dimension** · B1 Interactive States  **cause layer** · Behavior  **tier** · within-levers  **severity** · major  **provenance** · B1 Interactive States (states-presence)
-- **felt symptom (Perception)** · on first load the queue renders as an empty, misaligned frame, then snaps into place when rows arrive
-- **evidence** · `src/routes/queue/QueueRoute.tsx:28` — `<QueueTable rows={data}>` renders unconditionally while `data` is `[]` during the fetch
-- **before → after** · no loading state → the lifecycle pattern's skeleton, column-geometry-matched, shown while `isLoading`
-- **consequence** · every visit shows a flash of broken-looking UI and a layout shift; the queue reads as *failing* before it reads as *loading*
-
-Rendered per register:
-
-- **Designer** · "The queue has no loading state: it paints its empty frame before data arrives, so the first thing an operator sees is a broken, misaligned table that then jumps. Give it a skeleton matched to the column geometry, held until rows load. A surface that reads as broken before it reads as loading erodes trust on every visit. (Interactive states; cause in Behavior; major.)"
-- **Developer** · "`src/routes/queue/QueueRoute.tsx:28` — `<QueueTable rows={data}>` renders while `data` is `[]` during the fetch. Branch on `isLoading` and render the lifecycle skeleton (column-width-matched rows) until the query resolves. Within existing levers; no token or manifest change. (B1, Behavior; major.)"
-- **PM** · "The queue looks broken for a moment every time it opens, then jumps into place — it needs a real loading state so it reads as loading, not failing. Low effort; removes a daily 'is this thing working?' flinch for every agent. (Major.)"
-
-The designer hears design, the developer gets the branch and the file, the PM gets the cost and the outcome — one diagnosis underneath all three.
-
-## The findings report
-
-Every run files a dated report — introspection doubles as documentation, so a run that produced understanding doesn't evaporate with the conversation. The path is shared with review reports:
-
-```
-docs/design/findings/YYYY-MM-DD-<slug>.md
-```
-
-`<slug>` names the target (the surface, or the app). The report carries the canonical findings so a consented improve run consumes it directly, topped with a two-line executive summary in the chosen register. It is a deliverable, not runtime state — never read back as design state (code is the cache, floor f08).
-
-### Template
-
-```
-# Introspection — <target> · <YYYY-MM-DD>
-
-Reader: <designer | developer | pm>
-Scope: <surface / dimension / whole app examined>
-
-## Summary
-<two lines, in the chosen register — the shape of what's wrong and what it costs>
-
-## Findings
-<severity-ranked: auto-critical → critical → major → minor; canonical format per diagnosis.md>
-
-### <n>. <one-line title> — <severity>
-- dimension · cause layer · tier · provenance
-- evidence: <file:line / token / value>
-- before → after: <token-cited; numeric where machine-backed>
-- consequence: <what it costs the operator>
-- <the finding rendered in the chosen register>
-
-## Handoff
-Findings share the canonical format. To apply, run improve over this report:
-within-levers findings apply jailed; lever-change findings need lever consent.
-```
-
-Severity is a ranked scale, never a number — no scores, ever.
-
-## The improve handshake
-
-Introspect diagnoses; it never touches app code. When the user wants the findings applied, the same canonical findings feed an improve run (D10's escalation, run in reverse): the report *is* the input — improve reads it directly because both share the finding format. Scope covers what the findings name; depth is apply; authority follows each finding's tier — **within-levers** findings apply jailed to the lever manifest, **lever-change** findings are offered and need lever consent, never changed unbidden. The handoff is offered, never automatic.
-
-## Never
-
-- Never edit code — introspect reads, diagnoses, explains, and files the report; fixes happen only through a consented improve run.
-- Never infer or store the reader — ask, every run.
-- Never let a register become three opinions — it is presentation of one diagnosis.
-- Never emit a numeric score — severity rank only.

package/data/harnesses/code/skills/design/references/lifecycle.md

@@ -1,73 +0,0 @@
-# Lifecycle & microcopy
-
-The states a surface actually lives in, and the microcopy mechanisms that fill them. The brief describes the happy path; production is mostly everything else — loading at 9am, empty for a new tenant, degraded and half-stale at 3am. A surface designed only for the state the brief names is a broken surface.
-
-**Loads** at the create **surfaces** phase (state-shells get filled here) and whenever improve/introspect diagnoses state or copy coverage. Reads the `temporal` facts from `docs/design/structure.md`; the state-presence and copy-shape rules (`sta-*`) are already in boot context via `hard-rules.md` — this file is the design content behind them, not a restatement. Dial defaults come from `personality.md`.
-
-## The seam: mechanisms, not words
-
-Everything here is a **mechanism** — a formula, a required shape, a consistency discipline. The actual words are the business's call (floor f12). The skill enforces that an error names what happened / why / how to fix; it never writes the error text. It enforces one term per concept; it never picks the term. Emit shells and shapes; leave the vocabulary to the domain.
-
-## Required states per surface
-
-Four states are **always** required on every data surface: **loading**, **empty**, **error**, **partial/degraded**. They are not afterthoughts — they are the surface. Beyond the four, these are required **only where the model says they exist**, and the model is `docs/design/structure.md`'s `temporal` block, not a guess:
-
-- **post-action** — an action passes through pending/saving/processing before it resolves.
-- **cancel path** — a long or reversible action can be abandoned mid-flight.
-- **disconnection / timeout** — the surface can lose the backend.
-- **concurrent edit** — two operators can touch one record at once.
-
-The temporal probe (run inside the object pass — see `structure.md`) is what decides which conditional states a surface carries; read its facts, don't invent them.
-
-**States are built into the shell, never bolted on.** The scaffold phase already stubbed every declared state per surface (the state-shell stubs). The surfaces phase composes real content into those stubs. A shell whose `error` or `empty` slot ships as a placeholder is an unfinished surface and fails the phase gate. You are never adding states to a finished surface — you are filling shells that already exist.
-
-## Empty states
-
-An empty state is not one state. Five are distinct, and each earns distinct copy — collapsing them into one generic "No data found" is the defect:
-
-| Kind | It means | The copy teaches |
-| --- | --- | --- |
-| first-time | nothing created yet | what this surface is for, how to make the first thing |
-| user-cleared | they emptied it | that the clear worked, how to undo or add again |
-| no-results | filter/search matched nothing | that data exists, that the filter is the cause |
-| no-access | forbidden, not empty | that it exists but is gated, who to ask |
-| error | the fetch failed | routes to the error formula below, never to "empty" |
-
-**The empty formula: acknowledge → state the value → at most one action.** Text-first (floor f02) — copy plus at most one action, never an illustration showcase. *At most* one, not exactly one: a read-only surface (an audit log) legitimately offers zero. Never a dead-end on an actionable surface. Copy runs one to two sentences.
-
-## Errors
-
-**The error formula: what happened / why / how to fix.** All three parts. "Something went wrong" fails all three — it diagnoses nothing, explains nothing, offers no recovery, and is a named defect.
-
-**Dead ends and silent failures are banned.** Every error is visible and every error has an exit. A failure the operator can't see and a failure they can see but can't act on are the same bug.
-
-**Errors render inline, next to the offending field** — not in a banner divorced from the cause. The exception is genuinely system-wide failure (the backend is down, not one field is invalid), which legitimately banners; that scope is why the inline rule grades warning-tier, not absolute.
-
-## Temporal honesty
-
-Render the read model's lag honestly. When a write isn't yet visible in the read model, show a **pending state** — never paint the optimistic result as settled truth. Pending is not a lie; a premature success is.
-
-- **Skeletons mirror the content's shape**, not a centered spinner — the same columns, rows, and blocks the loaded surface will show. **Delay showing ~150–300ms** so a fast response never flashes a skeleton. The full loading-indicator bands (nothing under the short threshold, skeleton in the mid band, progress bar past the long one) are pinned by `mot-*`.
-- **Optimistic updates only for low-stakes actions, always with a visible rollback surface** — the row reverts and says why when the write loses. High-stakes or irreversible actions wait for the server (pessimistic) and preview before commit.
-- **Distinguish "no data" from "can't get data."** Empty means the query succeeded and found nothing; degraded means the query failed or the data is stale. **Mark staleness honestly** — a panel showing a cached value while its source is unreachable says so.
-
-## Toasts
-
-Toasts acknowledge transient, low-stakes success — nothing that needs action. **Auto-dismiss 3–5s, `aria-live="polite"`, never steal focus** (pinned in `sta-*`). An actionable error never lives only in a toast that vanishes; it goes inline where the operator can act on it. A toast is never the only signal for something the operator must do.
-
-## Copy disciplines
-
-Two disciplines govern every visible string, and they apply to UI copy, help text, and API names alike:
-
-- **One term per concept, one concept per term.** If the thing is a "ticket," it is a ticket in the label, the tooltip, the empty state, the toast, and the endpoint. Two words for one concept, or one word for two, is the defect. Divergence is allowed only when deliberate — a legacy-locked internal name may lag a renamed label — never accidental.
-- **Verb+object action labels.** "Create ticket," "Assign agent," "Archive job" — never bare "Submit," "OK," "Done." The label states the object it acts on.
-
-Both ride **sentence case** (not Title Case, not ALL CAPS outside tracked micro-labels) and **front-loading** — put the information-bearing word first so a scanning eye catches meaning at the left edge. "Payment failed — card declined," not "There was a problem processing your payment." Front-load labels, headings, menu items, and column headers.
-
-## The copy self-audit
-
-A pre-ship mandatory procedure (`proc-*`, fires in the whole-app sweep): **re-read every visible string on every surface and rewrite every flagged one.** This is the pass that kills lorem-slop, fabricated metrics, generic "No data found" empties, and dead-end errors in one sweep — and the pass that verifies one-term-per-concept held across the whole app, not just per file. No surface ships un-audited.
-
-## Dials modulate presentation
-
-Lifecycle presentation is dial-controlled, never per-surface improvisation. `data-verbosity` scales how much status copy renders — `full` spells out pending and progress narration, `expert` compresses it. `data-feedback` scales feedback intensity — how often toasts fire, how much motion a state transition carries. The dials compose *with* density, never instead of it. Their levels, defaults, and wiring live in `personality.md`; this file governs the states, not the knobs.