@nurix/etna 0.19.10 → 0.19.12

package/data/harnesses/code/skills/design/data/operator-pack/surface-catalog.md

@@ -1,132 +0,0 @@
-# Surface catalog
-
-The closed set of six operator surface archetypes. Structure derivation (D28) runs the object pass, then assigns every surface in the entity/surface map an archetype from this catalog — mechanically, by applying the choosing rules below to the map's facts: entities, attributes, cardinalities, relationships, lifecycle states, the operator's unit of work, and the core loop. The pass is never skipped; a small brief earns a small pass, never a guessed archetype. Navigation derives from the object model, never decorated onto it.
-
-Each entry carries five things: **choosing rules** (the object shapes, cardinalities, and lifecycle signals that select it), a **density modifier** (one relative step on the global tier), **composition** (the parts the surface holds and their arrangement, plus the lifecycle states that matter most here), a **navigation slot**, and an **exemplar pointer**.
-
-**Density.** The global tier — spacious · standard · dense — resolves at look time from the token artifact's payload / product-type traits (D31) and rewrites the spacing scale through the density primitive and the D6 `--spacing` remap. Each archetype then applies a single relative step on that tier: one step looser, at tier, or one step denser. Steps clamp at the scale ends (spacious … standard … dense) and never name an absolute value — an absolute override is banned (D31). Structure derivation records the relative step in each surface's `density-modifier` as a signed integer (positive = denser, `+1` / `0` / `-1`); the scaffold emits it as `data-density-step="tighter"` (+1) or `data-density-step="looser"` (-1), no attribute at 0. Modifiers compose with the behavioral dials (D4), never replace them.
-
-**Exemplars load just-in-time.** Every entry points at one token-pure compiling exemplar under `data/operator-pack/exemplars/<slug>.tsx`. The exemplar is read at that archetype's emission phase gate during the surfaces phase (D23) — emitting a surface of archetype X without exemplar X in context is a gate violation (D20). Exemplars are never boot-loaded.
-
----
-
-## list-detail
-
-**Choosing rules.** Selects when all hold:
-- The surface's primary object is one homogeneous collection — many instances of a single entity type (cardinality: N rows of one entity).
-- Each row carries a workable per-row action or lifecycle transition (assign, resolve, approve, retry) — the operator acts row by row.
-- The unit of work is one row (one ticket, one case, one device); the core loop is scan → select → act.
-- Detail is a projection of one selected row, not a standalone destination.
-
-This is the default archetype for the operator's primary entity — the queue shape. Distinguish from entity-detail: if a row's attribute count and relationship fan-out overflow a side panel and the entity is inspected/configured over time, that entity earns its own entity-detail route instead.
-
-**Density modifier.** At tier — the reference archetype. The global tier is calibrated on the operator's primary table, so list-detail runs at it unmodified.
-
-**Composition.** Toolbar (search, filters, bulk actions, column/view picker) + a virtualized table + a side-panel detail. Detail opens **beside** the table, never in a modal (floor f03). Bounded visible columns (rest behind the picker), right-aligned numerics in tabular figures (floor f04), sticky header, bounded pagination ("1–25 of 150") over infinite scroll, virtualization at ≥50 rows. Keyboard-first (floor f06): roving tabindex, arrow/j-k row travel, Enter opens the panel, shortcuts for the frequent verbs. Lifecycle states that matter most: **empty** (first-run vs filtered-to-nothing kept distinct), **loading** (skeleton rows mirroring the table, not a centered spinner), **partial/degraded** (stale rows marked honestly), and the per-row action's post-action state with optimistic-update-then-rollback.
-
-**Navigation.** A top-level nav item per primary entity collection — the queues and tables the operator lives in; the default landing for that entity. Detail is not a nav item; it is a panel state on the list route.
-
-**Exemplar.** `data/operator-pack/exemplars/list-detail.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## dashboard
-
-**Choosing rules.** Selects when all hold:
-- A read-mostly aggregate view over many entities or many metrics — the surface answers "how are things," not "act on this row."
-- Its content is derived (counts, rates, trends, distributions), presented as instances of one Metric object — never minted as N first-class entities (the instances-mistaken-for-objects trap; guard it in the object pass).
-- No per-row lifecycle action is the primary job; drill-down links out to a list-detail or entity-detail.
-- The core loop is glance → notice → drill.
-
-Selects on an overview / home / summary brief. Distinguish from command-center: a dashboard is read-mostly and glanceable; a command-center adds live streams and cross-entity intervention under time pressure.
-
-**Density modifier.** One step looser — a dashboard is a glanceable aggregate; KPI cards and charts need whitespace to separate and read at a glance, not row-scan density.
-
-**Composition.** A KPI / StatCard row at the top (≤4 primary metrics visible without scrolling — answer a few questions well, not many badly) + a small number of self-contained chart/panel tiles below, each a single question with a drill link. Hierarchy from spacing, not borders. Tabular figures on every KPI number (floor f04); charts read `--chart-1..5`; color is never the only signal. Lifecycle states that matter most: **loading** (per-card skeletons, never one page spinner), **partial/degraded** (a downed source names *which* panel is stale — "can't get data" is distinct from "no data"), **empty** (new-tenant zero-state that teaches the surface's value).
-
-**Navigation.** The home/overview landing — typically the app root or the first nav item. It is a hub that links out; never a leaf. Its panels' drill targets are the list-detail and entity-detail routes.
-
-**Exemplar.** `data/operator-pack/exemplars/dashboard.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## entity-detail
-
-**Choosing rules.** Selects when all hold:
-- The subject is a single rich entity with many attributes and outgoing relationships (1 entity : M related collections) that the operator inspects and configures over its life.
-- The entity's data and actions belong together on one surface — splitting them across screens is the broken-object failure; keep the object whole.
-- The temporal probe flagged the entity as long-lived, edited in place, with history that matters.
-- Its attribute count and relationship fan-out exceed what a list-detail side panel holds.
-
-Distinguish from list-detail: list-detail's detail is a lightweight row projection; entity-detail is a destination the operator returns to.
-
-**Density modifier.** At tier — it mixes dense read views (related lists, activity) with edit forms, so it sits at the global tier: neither a scan surface nor a pure form.
-
-**Composition.** Header (entity identity, status, primary actions) + a tab bar (overview / related collections / activity-history) + tabbed content. Related lists render as compact list-details inline; editing happens in place or opens the create-edit stepper beside the work (floor f03). Lifecycle states that matter most: **loading** (skeleton mirroring the header + tab shell), **error** (entity-not-found / load-failure with a recovery path, never a dead end), the edit **save states** (saving / saved / conflict — the concurrent-edit path from the temporal probe), and per-tab **empty** states.
-
-**Navigation.** Not a top-level nav item — reached by drilling from its list-detail (row → entity route), a dashboard, or a command-center link. Route nests under the entity's collection (`/entities/:id`); its tabs are in-surface sub-nav, never top-level entries.
-
-**Exemplar.** `data/operator-pack/exemplars/entity-detail.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## create-edit
-
-**Choosing rules.** Selects when all hold:
-- The surface's job is to mint a new instance or transition one through a multi-field or multi-step change.
-- The lifecycle signal is a **create** (the entity's birth) or a **staged edit** (a governed mutation), not scanning or reading.
-- The change is too large or field-heavy to complete inline in a list-detail panel.
-
-Create mirrors edit — the same field set and order; templates prefill. Distinguish from entity-detail: entity-detail is where an entity *lives*; create-edit is a focused, dismissible task that returns the operator to where it began.
-
-**Density modifier.** One step looser — forms need field breathing room and comfortable target sizes; loosening cuts entry error on a surface where mistakes are costly.
-
-**Composition.** A side-stepper opened **beside** the originating surface (floor f03), or a full form route for long creates. Labels above inputs; errors inline below the field, validated on blur; never placeholder-as-label. Logical field order preserved; one primary CTA bottom-right; primary targets ≥44px. Preview-then-commit for irreversible creates. Lifecycle states that matter most: **validation** (inline, on blur — diagnose → explain → recover), **submitting** (button loading, double-submit disabled), **server-error** (non-dead-end, entered values preserved), **success** (confirmation plus the next step).
-
-**Navigation.** Never a top-level nav item — invoked from a list-detail toolbar ("New") or an entity-detail action, and it returns to that surface on complete. A create route may exist (`/entities/new`) but is entered from the collection, not from the nav.
-
-**Exemplar.** `data/operator-pack/exemplars/create-edit.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## log-stream
-
-**Choosing rules.** Selects when all hold:
-- The primary object is an append-only, time-ordered event or record stream (monotonic; newest-first or tail-following).
-- Cardinality is unbounded and growing; rows are read, filtered, and searched — not acted on individually (no per-row lifecycle action).
-- Events are immutable once written; the temporal axis is the spine.
-
-Selects on a log / event / audit / activity-feed entity — high volume, time-keyed, read + filter. Distinguish from list-detail: list-detail rows carry a workable action and a lifecycle; log-stream lines are frozen history.
-
-**Density modifier.** One step denser — the value of the surface is lines-on-screen; tighten to maximize visible history under one glance.
-
-**Composition.** Filter/search bar + a follow/tail toggle (live vs paused) + a virtualized monospace line list, with inline expansion of a selected line (expand in place, not a modal). Tabular timestamps and IDs (floor f04), level-coded severity via status tokens with a second non-color cue, hairline dividers, minimal chrome. Lifecycle states that matter most: **streaming/live** (new lines announced via `aria-live` without stealing focus), **empty** (no events yet vs filtered-to-nothing, kept distinct), **error** (stream disconnected shows reconnecting, never a dead spinner), **partial/degraded** (dropped or truncated buffer marked honestly).
-
-**Navigation.** A top-level nav item when logs/audit/activity is a primary operator surface; otherwise a tab inside the owning entity-detail (that entity's activity/history). Time-keyed, so deep-links carry a timestamp or anchor.
-
-**Exemplar.** `data/operator-pack/exemplars/log-stream.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## command-center
-
-**Choosing rules.** Selects when all hold:
-- A real-time, multi-pane monitoring surface composes several live entities or streams under one view.
-- The operator acts under time pressure; the core loop is monitor → detect → intervene, across multiple entities at once.
-- The unit of work spans entities, not one row — it fuses aggregate signals (dashboard-like) with live streams (log-stream-like) and quick cross-entity actions.
-
-Reserved for genuine live-ops briefs (NOC, incident console, dispatch, ops bridge). Distinguish from dashboard: a dashboard is read-mostly and drills out; a command-center is live and acts in place. Never assign it to decorate an ordinary dashboard.
-
-**Density modifier.** One step denser — the most information-rich archetype; the operator needs maximum live signal simultaneously visible.
-
-**Composition.** A fixed multi-pane grid: a status/health header + several independently refreshing panels (aggregate tiles, a live stream pane, an alert/queue pane, quick-action controls), composed under one non-scrolling view where the viewport allows. Each pane refreshes on its own; keyboard reach spans panes; irreversible interventions are consent-gated with preview. Lifecycle states that matter most: **per-panel loading and partial/degraded** (each pane fails independently and says so — a command-center that hides a dead feed is dangerous), **live update**, **error**, and the alert/action **post-action** with undo.
-
-**Navigation.** The app root or first nav item for a live-ops tool where monitoring is the job — the operator's home, aggregating routes that also exist standalone. Rare; only for genuine live-ops briefs.
-
-**Exemplar.** `data/operator-pack/exemplars/command-center.tsx` — JIT at the emission gate, never boot (D20).
-
----
-
-## Extension
-
-The catalog is closed at six. A seventh archetype is never added by prose, by a reference edit, or by improvisation at run time. Membership extends **only as operator-pack data**, and only by a ledger-recorded decision (D28) — the new entry carrying its own choosing rules, density modifier, composition, navigation slot, and exemplar, and the exemplar passing the full machine catalog and personality-invariance validation before it ships (D20). Structure derivation assigns from these six; a brief that fits none is surfaced to the operator, never force-fit into the nearest archetype.

package/data/harnesses/code/skills/design/data/operator-pack/trust-rubric.md

@@ -1,76 +0,0 @@
-# AI-surface trust rubric
-
-Judged diagnosis dimensions for any operator surface that shows AI-originated content or takes AI-initiated actions. Four dimensions, anchors `trust-01`..`trust-04`. The rubric grades what a surface already does with AI. Absence of `trust-01`, `trust-02`, or `trust-03` grades **auto-critical** — no exception, no waiver.
-
-## When it fires
-
-Runs inside improve and introspect sweeps, on every surface whose composition holds AI-originated content (drafts, summaries, enrichments, scores, suggestions) or AI-initiated actions (auto-triage, auto-close, agent send / delete / charge). A surface with no AI content skips it. A copilot panel, an agent console, an enrichment column, an auto-triage queue all trip it.
-
-## Scope: audit only
-
-This rubric grades AI surfaces; it does not carry the generative patterns for building them. Streaming / generating states, confidence display, preview-then-apply, undo semantics for agent actions, the copilot-panel archetype — none are authored here. That pattern set enters the operator pack as a recorded addition when its trigger fires (the first embedded-copilot brief, or Nurix's own agent-console needs); `docs/history/backlog.md` holds the trigger. Until then the rubric audits, from day one, whatever other means produced the AI surface.
-
-## The four dimensions
-
-### trust-01 — AI presence is disclosed
-
-**Demands.** Every AI-originated element carries a marker at its point of consumption — a badge, a label, a distinct visual treatment — legible before an operator acts on it. Disclosure also signals *how far to trust*: where the model emits a confidence, a source, or a known-unreliable class, the surface shows it. This folds the accuracy / confidence axis into disclosure — an AI badge sitting over a low-confidence guess presented as fact still fails, because the operator cannot tell the value is soft.
-
-**Passes.** An AI-drafted reply in a support queue sits under an "AI draft" chip with a muted card treatment, distinct from a teammate's message. An enrichment-filled CRM field shows an "auto-filled" marker and its source. A model summary is captioned "AI-generated" and carries a confidence band when the model is unsure.
-
-**Fails.** An AI-drafted reply rendered visually indistinguishable from a human draft. A model-derived "priority" score in a column with no sign it is generated. A low-confidence extraction shown as a plain, authoritative value.
-
-**Judge.** For each AI element on the surface: could a first-time operator, glancing, tell it apart from human or authoritative content — and does the surface tell them how much to trust it?
-
-**Grade.** Absence auto-critical.
-
-### trust-02 — A human override path is visible
-
-**Demands.** Wherever the AI decides or acts, the operator can override, correct, or reject it — per item, on the surface where the decision shows, and keyboard-reachable. A global off-switch is not an override path.
-
-**Passes.** An auto-triage queue gives every item a visible "reassign" and "revert". An AI-suggested value offers inline "accept / edit / dismiss". An auto-close agent exposes per-ticket "reopen" and "stop auto-closing this".
-
-**Fails.** An auto-triage rule with no per-item revert. An AI-set status field that is read-only in the UI. A settings-only "disable AI" toggle with no per-decision correction on the surface itself.
-
-**Judge.** At each point the AI acted, is there a countermand affordance, reachable where the decision appears (not buried in settings) and by keyboard?
-
-**Grade.** Absence auto-critical.
-
-### trust-03 — AI-initiated irreversible actions are consent-gated with preview
-
-**Demands.** Any AI-initiated action that is destructive or irreversible — send, delete, charge, publish, external side-effect — stops before executing, shows a preview of exactly what it will do, and waits for explicit human consent. It is never auto-fired. A reversible AI action needs trust-02's override, not necessarily a preview gate.
-
-**Passes.** An outreach agent stops at a preview of the exact recipients and body, gated on a send click. A bulk-remediation agent shows the diff of the 40 records it will touch and waits for confirm. A refund-capable AI presents amount, account, and reason behind an explicit confirm.
-
-**Fails.** An agent that sends the drafted reply the instant it is generated. An auto-remediation that deletes flagged rows on a timer with no preview step. A "resolve all" action that fires irreversible external calls without showing what it will touch.
-
-**Judge.** Enumerate the AI-initiated actions on the surface; for each irreversible one, is there a concrete preview of the effect and an explicit consent step before execution?
-
-**Grade.** Absence auto-critical.
-
-### trust-04 — AI actions are auditable
-
-**Demands.** AI-taken actions leave a durable, operator-inspectable trail — what acted, when, on what, and on what basis — visible in the UI, not only in backend logs. Attribution distinguishes AI from human.
-
-**Passes.** Each AI-modified record carries an activity entry: "auto-triaged by <agent> at <time>, rule <x>". A command center runs an AI-actions feed with timestamps and revert links. An entity's audit tab lists model actions beside human ones with provenance.
-
-**Fails.** An AI that mutates records with no history entry. Actions attributed generically to "system", indistinguishable from a human edit. An auto-close leaving no timestamped, attributable trace.
-
-**Judge.** For the AI actions on this surface, can an operator reconstruct after the fact what the AI did, when, and on what basis, from the UI itself?
-
-**Grade.** Absence is a finding, severity by judgment — critical or major by the blast radius and reversibility of the actions. It never auto-grades; only trust-01..03 do.
-
-## Writing the finding
-
-Trust findings are judged findings on the canonical schema — peers of machine findings, consumed directly by improve, rendered per reader register by introspect, and carried unchanged into the dated findings report and the decay ledger.
-
-- **provenance** — the trust anchor (`trust-01`..`trust-04`), marked judged. This is the load-bearing tag; anchor parity between this rubric and the finding's provenance is enforced.
-- **dimension** — the AI-surface trust dimension the rubric adds. Where the canonical dimension slot wants a taxonomy code, disclosure copy reads under B5 Content & Copy and the override / consent / audit affordances under B1 Interactive States; the provenance stays the trust anchor either way.
-- **cause layer** — a trust failure is felt in Perception (the operator cannot tell, cannot control, cannot audit) but its cause is almost always Structure (a missing marker or affordance) or Behavior (an ungated action, an absent trail). Name the causal layer, per the causes-first walk.
-- **evidence** — the `file:line` of the AI element and what it renders or does.
-- **before → after** — descriptive, not numeric, because the rubric is judged: the failing state → the affordance that fixes it. E.g. `AI draft renders identically to human messages → AI draft carries a disclosure chip and a muted treatment`.
-- **consequence** — the trust harm: automation bias, a silent irreversible action, an uncorrectable error, an unauditable mutation.
-- **tier** — within-levers when the fix is an affordance the surface can already express (a chip, a confirm dialog, an activity entry); lever-change when the fix needs a generative pattern the pack does not yet carry (route it to the backlogged pattern set, and report it, never freehand it).
-- **severity** — trust-01..03 absence is auto-critical; trust-04 absence is critical or major by judgment; a present-but-weak dimension grades major or minor.
-
-**Presence-shaped machine facets.** Where a facet holds with zero legitimate exceptions — an AI-marked element must carry its disclosure attribute, a consent dialog must trap focus — it is registered as a machine rule in the catalog and fires at its own point. This rubric is the judged layer the machine cannot reach: whether the marker is *legible*, whether the preview shows the *right* effect, whether the trail is *reconstructable* are judgments, and they stay here.

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

@@ -1,173 +0,0 @@
-# Create — the gated phase spine
-
-Create is the only workflow where taste is *made*: personality synthesis, structure derivation, emission. It runs **six gated phases** — intake, structure, scaffold, tokens, fixtures, surfaces — and closes on a **verification ladder**. Each of the six is closed by a phase gate: `phase-gate.mjs <phase>` validates that phase's exit preconditions, exits non-zero printing the exact fix, and **the next phase does not open until the gate is green**. Improve and introspect operate on UIs that already exist — see [improve.md](./improve.md) and [introspect.md](./introspect.md).
-
-| Phase | Gate (must pass to open the next) | Produces |
-| --- | --- | --- |
-| intake | `phase-gate.mjs intake` | confirmed intent digest; resolved design-tokens artifact at project root |
-| structure | `phase-gate.mjs structure` | `docs/design/structure.md` — the entity/surface map |
-| scaffold | `phase-gate.mjs scaffold` | project shell: routes, nav, state-shells, fixture wiring |
-| tokens | `phase-gate.mjs tokens` | `personality.css` + `globals.css`, full token surface |
-| fixtures | `phase-gate.mjs fixtures` | seeded fixture modules in `src/fixtures/` |
-| surfaces | `phase-gate.mjs surfaces` | composed surfaces, every lifecycle state filled |
-| verification | the ladder (below) | a compiled, swept, rendered app |
-
-The gate closing each phase runs the D21 rule classes decidable at that boundary — per-surface structural rules (states presence, token coverage, exemplar-in-context). A gate never waives: it prints the exact fix and the run resolves it before proceeding.
-
-## intake
-
-**Purpose.** Recognize the brief, decide pack coverage, extract intent, resolve the look — its direction, its source, and its delight ceiling.
-**In → out.** the brief · the design.md library · `data/combinations/product-router.csv` (+ `typography.csv` · `palettes.csv` · `styles.csv` when the look is authored fresh) · `docs/design/taste.yml` → a confirmed intent digest carrying the look block · a design-tokens artifact at project root (`design.tokens.json` + `design.resolver.json` — the look + lever manifest).
-**Work.** Front gate: a project-declared identity (product-type traits) wins; otherwise the signal checklist (audience is employees / agents / analysts; the metric is task throughput, not conversion; the surfaces are queues / tables / forms / monitors), with `data/combinations/product-router.csv` — loaded at every intake — as the recognition assist and the digest's density/archetype priors. Build a structured intent digest — entity list, archetype guesses, density tier, substrate, **and the mandatory look block** (below) — every inference marked as inferred, present it once for confirmation, and ask only strategic unknowns whose answers change the design. Fold look-relevant brief language into the taste profile (below) as you read it. Resolve the look through the precedence spine — **project > library (on match) > seed composition > default**, never applied unrecorded (Resolution, below): the project's own artifact wins; a library entry or a fresh seed composition is proposed-and-confirmed (interactive) or resolved-and-recorded (autonomous); `default` — the Nurix look — resolves only when the brief explicitly asks for it. When the look resolves to authoring a fresh artifact — not a library copy, not the default — load `typography.csv`, `palettes.csv`, and `styles.csv` before composing it; the consumption contract is [combinations/Readme.md](../data/combinations/Readme.md). Materialize the resolved artifact at project root against [SCHEMA.md](../data/design-tokens/SCHEMA.md) — the look block in its payload, and for a recorded resolution the resolution record in the artifact root `$description`.
-**Gate — `phase-gate.mjs intake`.** The digest is confirmed and a schema-valid token artifact exists at project root, carrying a well-formed **look block** — presence, the theme / delight / resolution-mode enums, 2–3 named anchors, the resolution shape, and (for a recorded resolution) the resolution record in the artifact root `$description`. A brief no pack covers is refused here — cleanly, with a redirect — never derived.
-**Avoid.**
-- Deriving on silently inferred facts instead of presenting the digest for one confirmation.
-- Blanket-interviewing when the brief already declares its identity — ask only strategic unknowns.
-- Attempting a marketing / storefront / mobile-native brief instead of refusing on pack coverage.
-- Authoring a fresh look without `typography.csv` / `palettes.csv` / `styles.csv` in context — a gate violation.
-- Filling `anchors` with adjectives instead of 2–3 named products — the gate rejects it; convert them first.
-- Applying a resolution unrecorded — an autonomous pick writes its record into the artifact root `$description`, or the gate fails.
-
-### The look block
-
-The intent digest carries a mandatory **look block**, filled at intake beside the entity / archetype / density fields:
-
-```yaml
-look:
-  theme: light | dark | both          # binding when the brief states it; default light
-  anchors: ["Linear", "Stripe Dashboard"]   # 2–3 NAMED real products; adjectives are not anchors
-  delight: baseline | expressive      # the global delight ceiling; per-surface budgets refine it
-  resolution: project | library:<slug> | seed:<style-row>+<palette-row> | default
-  resolution-mode: confirmed | recorded    # how the resolution was authorized (below)
-```
-
-- **`theme` is binding.** A brief-stated theme writes the payload's `theme-default`, the resolver's default context, and scaffold's `<html data-theme>`; `both` ships light-boot with a working toggle, `dark` ships dark-boot. Default light when the brief is silent.
-- **`anchors` are named products, required.** Two or three real products pin the gestalt at the direction moment — unnamed ambition drifts to beige, and ~10 tokens of product names carry what a thousand adjective-words cannot. Adjectives are not anchors: convert an adjective to its nearest named products by **asking** (interactive) or **inferring-and-recording** (autonomous) through the [design.md library](../data/design-md/library/)'s resemblance lookup, then record the named products. Anchors land in the payload so improve and `judge` critique against the same targets the run aimed at.
-- **Anchors work twice.** At resolution they drive the resemblance lookup; at the surfaces phase the anchor products' design.md entries JIT-load so composition leans toward the anchor's gestalt — composition is anchor-*steered*, not exemplar-cloned.
-
-### Resolution — propose-and-record
-
-The precedence spine serves both session modes and is **never applied unrecorded**.
-
-- **Interactive** (a confirmer is present): propose-confirm — the resolved source is proposed from resemblance and applied only on confirmation, never silently.
-- **Autonomous** (the digest's one confirmation round goes unanswered, or the brief forbids questions): resolve the best match, set `resolution-mode: recorded`, and write the **resolution record** into the artifact root `$description` — the winner, the runner-up, and the deciding evidence. For example: `resolution: library:stripe (recorded; runner-up palettes.csv#3; brief phrase "Stripe-dashboard territory" matched product + fintech traits)`. The record is auditable and reversible — an improve run can be pointed at the runner-up by consent. Nothing is silent; nothing dead-ends.
-
-**Selection is brief-keyed, never mood-keyed.** Route before judging: extract the brief's traits (domain, product type, tone words) → filter `product-router.csv` by product type and theme → a 2–3-row shortlist enters context with its `mood` prose → pick, the record naming the runner-up. Same brief → same shortlist; different domains → different pools — divergence by construction, not by model mood. `default` resolves only when the brief explicitly asks for the Nurix look; a look-less brief always composes from seeds through this routing. The taste profile biases the pick once it has content.
-
-**Seed composition partitions, never contests.** A fresh artifact composes from the routed rows by domain: the **palette** row contributes color, the **typography** row type, the **style** row treatment (`css-recipe` + `tokens-hint` + the non-token `voice`). Out-of-domain content in a row — a style row's color suggestion — is advisory prose for the composer, never a value source, so no two seeds can contest the same value. The composer closes with a deliberate **best-fit harmony pass**: do the palette, type, and treatment read as one hand, for *this* user — the taste profile is in context? Harmony is judged, not mechanical; no link exists between the dimension tables.
-
-## structure
-
-**Purpose.** Derive the app's structure from its domain objects — never guess it.
-**In → out.** the confirmed intent digest → `docs/design/structure.md` with its fenced `yaml structure` block.
-**Work.** The object pass: entities, attributes, relationships, cardinalities, lifecycle states; the operator's unit of work and core loop. The **temporal probe runs inside the pass** — intermediate states, read-model lag, deletion semantics, history, failure paths — because they are model facts, not later polish. Then assign each surface an archetype from the closed six-catalog (`list-detail`, `dashboard`, `entity-detail`, `create-edit`, `log-stream`, `command-center`) with its density modifier — see [surface-catalog.md](../data/operator-pack/surface-catalog.md). The pass also classifies **every surface with a mandatory delight `budget`** (`baseline` / `brand-forward`) — permission is structural, decided here; defaults by archetype, overridable against a recorded reason — see [structure.md](./structure.md) (the delight budget). `scaffold.mjs` stamps the budget into each route file and `phase-gate.mjs surfaces` reads it back. Navigation derives from the object model; it is never decorated onto it. The OOUX failure vocabulary (Shapeshifter / Masked / Broken / Isolated) is the judged diagnostic — see [structure.md](./structure.md).
-**Gate — `phase-gate.mjs structure`.** The map parses; every surface carries an archetype from the catalog; the `temporal` block is present. `scaffold.mjs` consumes this block, so its shape is validated here.
-**Avoid.**
-- Skipping the object pass on a small brief — a small brief earns a proportionally small pass, never a skipped one; the skip is the characteristic failure.
-- Decorating navigation onto the UI instead of deriving it from the object model.
-- Omitting the temporal probe — intermediate states and failure paths are model facts, not afterthoughts.
-- Inventing an archetype outside the closed six.
-- Leaving a surface's delight budget to chance — classify every surface, and record the reason whenever a stamp overrides its archetype's default (caught at the surfaces gate).
-
-## scaffold
-
-**Purpose.** Generate the non-creative substrate from the map — the model never freehands it.
-**In → out.** `docs/design/structure.md` → the wired project shell.
-**Work.** `scaffold.mjs docs/design/structure.md --out <project>` emits `index.html` (carrying the `<html>` data attributes), `src/main.tsx`, `src/App.tsx` (react-router-dom), route and navigation wiring per surface, per-surface state-shell stubs (loading / empty / error / degraded shells wired but unfilled), and fixture wiring — under `src/routes/<surface>/`, `src/components/<feature>/`, `src/types/`. These files are **generated**; the preservation contract forbids hand-editing them.
-**Gate — `phase-gate.mjs scaffold`.** The shell exists, routes and nav match the map, every surface has its state-shells, and the `globals.css` import order is correct.
-**Avoid.**
-- Freehanding the route or navigation wiring the generator owns.
-- Hand-editing a generated file after `scaffold.mjs` writes it — generated files are never written into.
-- Getting the `globals.css` import order wrong — the cascade contract is in [personality.md](./personality.md).
-
-## tokens
-
-**Purpose.** Emit the complete token surface from the resolved artifact.
-**In → out.** the design-tokens artifact → `src/styles/personality.css` + `src/styles/globals.css`.
-**Work.** Derivation is hybrid: deterministic where the artifact states a value, judgment-with-recorded-rationale for gaps (a resolved hint records its rationale in the token's `$description`). Before any typography hint is resolved, `data/combinations/typography.csv` is in context; before any color hint, `palettes.csv` **and `accent-presets.md`** — the routed-consult contract. The look's theme filters the consult: a `dark` look narrows the palette pool to dark-capable rows (`theme` column `dark` / `both`), and composing a dark look from a light-only row is off-table and needs a recorded reason. The taste profile sits in context beside the rows, biasing the pick. The table is the floor for the resolution, and an off-table pairing or palette is allowed only with its stated reason recorded in the token's `$description`. The **coverage gate** `derive-personality.mjs <project-dir> --check` fails — exit non-zero, naming the missing paths — if any of the 26 visual primitives, the 2 behavioral dials, or the emission tokens is unassigned and un-hinted. Only once it is green does `derive-personality.mjs <project-dir> --emit <project-dir>` write both files (into `<project-dir>/src/styles/`), defining the full surface — 27 primitives, 17 semantic tokens, and the 17 substrate tokens no consumable value is left to fall back to gray on — and hardening both cascade contracts (selector specificity, import order) with explanatory comments. See [personality.md](./personality.md).
-**Gate — `phase-gate.mjs tokens`.** The coverage gate passed and both files carry the full token surface with the cascade-contract comments intact.
-**Avoid.**
-- Emitting before the coverage gate passes.
-- Leaving any of the 17 substrate tokens to fall back to shadcn-gray defaults.
-- Hardcoding a literal color, spacing, or radius instead of routing through a token.
-- Dropping the cascade-contract comments from the emitted CSS.
-- Resolving a typography or color hint without its combination table in context, or going off-table without the reason in the token's `$description`.
-
-## fixtures
-
-**Purpose.** Produce the taste-bearing data every surface renders — before any surface exists.
-**In → out.** `docs/design/structure.md` → `src/fixtures/*.ts`.
-**Work.** `generate-fixtures.mjs docs/design/structure.md --seed <n> --out src/fixtures/` writes seeded, domain-shaped fixture modules: realistic volumes (queues in the hundreds), long strings, unhappy values, degraded payloads, and empty / error cases — see [fixtures.md](../data/operator-pack/fixtures.md). A fixed seed makes every run reproducible.
-
-> **Fixture-before-surface.** Fixtures are generated before any surface is composed because realistic seeded data is taste-bearing design material — the density, overflow, and state thresholds are only bindable against real volumes, long strings, and unhappy values.
-
-**Gate — `phase-gate.mjs fixtures`.** Seeded modules exist for every entity, cover the unhappy and empty / error cases, and no surface file has yet been written.
-**Avoid.**
-- Lorem-ipsum data or unseeded randomness.
-- Composing a surface before its data exists.
-- Happy-path-only rows — no volumes, long strings, degraded payloads, or empty / error cases.
-
-## surfaces
-
-**Purpose.** Compose each surface per its archetype, filling the pre-created shells.
-**In → out.** the state-shells · the fixtures · the emitted tokens · the archetype exemplar → composed `src/routes/<surface>/` surfaces, every state present.
-**Work.** For each surface, compose in the `@nurix/components` idiom (imported by subpath) against the resolved tokens — the look comes entirely from the cascade, never from literals. Fill every lifecycle state into its pre-created shell; states are composed with the surface, not bolted on after. AI-bearing surfaces clear the [trust rubric](../data/operator-pack/trust-rubric.md); microcopy follows the error and empty-state formulas in [lifecycle.md](./lifecycle.md); keyboard and focus discipline follow [interaction.md](./interaction.md).
-
-> **The budget is a grant, not only a ban.** Read each surface's stamped delight budget ([structure.md](./structure.md), the delight budget) as permission, not just a ceiling: a brand-forward dashboard *uses* the display step on its focal metric, an elevation lift on its hero card, an arrival stagger on its rows — a page of uniform 14px text ignores its budget. A baseline surface withholds ornament, never signal. The budget grants which vocabulary a surface may consume; the floor holds identically at every budget.
-
-> **Just-in-time exemplar.** Each archetype's token-pure exemplar ([exemplars/](../data/operator-pack/exemplars/)) loads just-in-time at that archetype's emission gate — never at boot — because imitation proximity is highest when the exemplar sits in context at the moment of composition. Composing a surface of archetype X without exemplar X in context is a **gate violation**. Imitate the composition; the look comes from the project's personality.
-
-> **Just-in-time combination tables.** `data/combinations/charts.csv` loads at the emission gate of any surface that composes a chart; `icons.csv` loads once, at the first surface-composition gate — icon picks happen throughout. Each table is the floor for its picks: an off-table chart type or icon is allowed only with its stated reason in a code comment adjacent to the deviating pick. An unrecorded off-table pick is a **gate violation**. Contract: [combinations/Readme.md](../data/combinations/Readme.md).
-
-**Gate — `phase-gate.mjs surfaces`.** For each surface the archetype exemplar was in context, all lifecycle states are filled, and the per-surface structural rules pass (states presence, token coverage).
-**Avoid.**
-- Composing archetype X without exemplar X in context — a gate violation.
-- Composing a chart or picking an icon without its combination table in context — a gate violation.
-- Writing states as an afterthought instead of into the pre-created shells.
-- Emitting a look disjoint from the resolved personality — literals or off-scale values instead of the cascade.
-- Modals where side panels belong; a workflow a pointer alone can complete (floor f03 / f06).
-
-## verification
-
-**Purpose.** Prove the app compiles and clears the ladder.
-**In → out.** the composed app → a verified app; any findings routed through the same fix-or-classify loop.
-**Gate.** The verification ladder below — rung 0 is never skipped. Findings surface as the [canonical finding](./diagnosis.md) and resolve before ship.
-
----
-
-## The taste profile — the standing input
-
-A **project taste profile** rides with the consumer project at `docs/design/taste.yml` (beside the judge reports) — per-dimension summaries of the user's expressed taste (`overall`, `typography`, `color`, `density`, `motion`, `dark`), each a short `feel` line plus an `avoid` line. It is **intent, never values**: the token artifact stays the only value transport; the profile biases picks, it never sets them. It is YAML because the file is human-facing intent — prose summaries plus an explanatory header comment.
-
-- **Captured** at intake (look-relevant brief language folds in) and whenever the user reacts to shipped output — an accepted or rejected finding, an improve consent round, a "too showy". The relevant item updates or a new one lands; provenance folds into the prose ("asked twice for tighter headings"), never into machine fields.
-- **Consumed** at resolution (it biases the shortlist pick; the resolution record cites the taste items that drove it) and at the color / type moment (in context beside the seed rows). `judge` critiques against it as a fixed referent.
-- **Reset** serves a deliberate style switch: an explicit flow re-asks the taste questions dimension by dimension and rewrites the items in place. The file is never deleted — switching styles is a re-interview, never a silent fall back to no-profile behavior.
-- **Fail-open.** A missing or malformed `taste.yml` degrades to no-profile behavior with a one-line notice — never a crash, never a block. The profile is a bias; a bias that cannot be read cleanly is simply not applied.
-
-## The preservation contract
-
-Two disciplines protect what must never silently change.
-
-**The fixed never-silently-changed list** — identical across every project, never negotiated:
-
-- route slugs
-- navigation labels
-- form-field names and order
-- analytics / event identifiers
-- API / data-contract shapes
-- generated files (never written into — the is-generated guard)
-
-Changing any of these requires it to be the *named subject* of a finding; they are never collateral edits. Per-project preservation extensions, if ever needed, are entries in the project's token artifact payload — data, not config machinery.
-
-**Diff-scope discipline.** An improve run edits only the files its findings name; a run that touches a file outside its findings fails. Create writes the whole app — the discipline governs improve. See [improve.md](./improve.md).
-
-## The verification ladder
-
-| Rung | What | When |
-| --- | --- | --- |
-| 0 | Compile. | Always — never skipped. |
-| 1 | Static whole-app checks — `preship-sweep.mjs`: the full catalog over all files, plus the mandatory procedures (viewport sweep at 375 / 768 / 1024 / 1440, copy self-audit, scope cross-check against the brief). | Every run. |
-| 2 | Deterministic render rung — `render-rung.mjs`: key surfaces rendered headlessly, re-running the catalog's render-only rules (real overflow at the four viewports, effective and pixel-measured contrast, rendered token drift, actual target geometry, and the `cod-12` runtime perf budgets LCP < 2.5s and CLS < 0.1 collected via `PerformanceObserver`; INP and frame time need the interactive rung); findings through the same fix-or-classify loop. | By default when a headless browser is importable; degrades to a one-line notice otherwise. |
-| 3 | Interactive dev-server / browser audit of the user's own environment. | Consent-gated — asked for, never assumed. |
-
-Model-judged screenshot self-critique is **not a rung** — no machine verdict rests on the model's own read of a screenshot. Pixel instruments (`inst-*`) supply evidence *inside* judged findings, never verdicts.

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

@@ -1,108 +0,0 @@
-# Diagnosis — the shared engine
-
-> The one engine that turns a UI into findings. [improve.md](improve.md) runs it to decide what to change; [introspect.md](introspect.md) runs it to explain why a UI isn't working. Both get the same findings — improve applies them, introspect renders them per reader register. Diagnosis owns the finding format; the consumers own what they do with it.
-
-Reads the rule catalog ([../data/catalog/rules.csv](../data/catalog/rules.csv)) and the AI-surface trust rubric ([../data/operator-pack/trust-rubric.md](../data/operator-pack/trust-rubric.md)). Emits a severity-ranked list of canonical findings, consumed by improve, introspect, the dated findings report, and the decay ledger — one schema across all four.
-
-## The dimension taxonomy
-
-Every finding names a dimension. The set is the sixteen dimensions across three meta-layers — **Perception** (what the operator sees), **Structure** (how it's built), **Behavior** (how it responds).
-
-Perception — P1 Typography (font, scale, weight, rhythm, loading) · P2 Color (palette, contrast, neutrals, saturation) · P3 Spatial (spacing scale, grid, whitespace, rhythm) · P4 Depth & Elevation (shadow scale, z-index, layering) · P5 Visual Hierarchy (emphasis, de-emphasis, the squint test) · P6 Iconography & Imagery (icon sets, stroke, image treatment) · P7 Aesthetic Identity (personality, tone, anti-slop, consistency).
-
-Structure — S1 Semantic Markup (elements, heading hierarchy, ARIA, landmarks) · S2 Component Architecture (composition, reuse, isolation, typed props) · S3 Design Tokens (semantic vs literal, two-layer naming, theming) · S4 Performance (GPU-safe animation, bundle, lazy load, CLS).
-
-Behavior — B1 Interactive States (default/hover/focus/active/disabled/loading/empty/error) · B2 Motion & Animation (timing, easing, stagger, reduced-motion) · B3 Responsive Adaptation (breakpoints, targets, viewport units, input method) · B4 Navigation & Wayfinding (nav patterns, back behavior, deep links, modals) · B5 Content & Copy (microcopy, errors, empty states, labels, terminology).
-
-## Causes-first: the walk order
-
-Diagnosis walks the meta-layers **Structure → Behavior → Perception** — causes before symptoms. Badness is felt in Perception (the table looks noisy, the page feels heavy), but its cause almost always lives one layer down, in Structure or Behavior. Walking causes-first means a Perception symptom is diagnosed to its root and reported once, at the cause — never patched as a cluster of surface edits that leave the root standing.
-
-Two orderings, do not confuse them. The **walk** is causes-first (analysis order). The **delivered list** is severity-ranked (below). [introspect.md](introspect.md) narrates each finding the other way — from the felt symptom down to the cause — because that is how a reader understands it; the diagnosis underneath is the same.
-
-## The canonical finding
-
-Eight fields, fixed. Every finding carries all eight, machine or judged.
-
-- **dimension** — which of the sixteen. Names *what* is wrong.
-- **cause layer** — Structure, Behavior, or Perception. Names *where the fix lives* — the meta-layer of the root, which often differs from the dimension's own layer (a felt Perception problem rooted in a Structure fact).
-- **evidence** — the anchor in the code: `file:line`, a token name, or a measured value; for a rendered-evidence finding (a `judge` run — [improve.md](improve.md)), a screenshot path + the region within it (`shots/1440.png · header row, right cluster`). Never a vibe.
-- **before → after** — the current state → the corrected state. Numeric where machine-backed (a value → its threshold); a concrete, measurable state change where judged. Never "make it cleaner."
-- **consequence** — what it costs the operator: lost throughput, eroded trust, an unreadable figure, an irreversible mistake.
-- **tier** — `within-levers` (fixable inside the current lever manifest) or `lever-change` (needs a manifest change). The [improve.md](improve.md) jail reads this.
-- **severity** — auto-critical → critical → major → minor. A rank, never a number.
-- **provenance** — a catalog anchor id for a machine finding (e.g. `spc-01`), or the judged dimension / trust anchor for a judged one. This is the only field that says how the finding was established.
-
-### Worked example
-
-- **dimension** · P3 Spatial  **cause layer** · Structure (the value bypasses the declared spacing scale — a token-discipline failure, not a raw sizing choice)
-- **evidence** · `src/routes/queue/QueueToolbar.tsx:34` — `className="px-[15px]"`
-- **before → after** · `15px` (off-scale) → `16px` (the nearest step on the manifest's 4/8 scale)
-- **consequence** · a one-off gutter that breaks the toolbar's rhythm against the 16px-gridded rows beside it; proximity stops encoding structure
-- **tier** · within-levers (16px is already in the manifest's spacing scale)
-- **severity** · minor
-- **provenance** · `spc-01` (machine, source-detected)
-
-That is a machine finding with a numeric before→after. For a judged finding worked three ways see [introspect.md](introspect.md); for judged trust findings see [trust-rubric.md](../data/operator-pack/trust-rubric.md).
-
-## Machine and judged findings are peers
-
-There is no primary source and no secondary source. Machine and judged findings share the schema, sort into one severity-ranked list, and feed every consumer identically. Only **provenance** distinguishes them:
-
-- A **machine** finding's provenance is its catalog anchor id. The id resolves in [rules.csv](../data/catalog/rules.csv) to the rule statement, its numbers, and its source tags (WCAG, HIG, `imp`, `stitch`, `axe`, `volt/<product>`, …). Its before→after is the offending value against the rule's threshold.
-- A **judged** finding's provenance is the judged dimension — a taxonomy code, or a trust anchor (`trust-01`..`trust-04`) — with `detector=none` in the catalog. Its before→after is a concrete state change, measurable in kind though not numeric.
-
-Neither kind outranks the other by *kind*. Severity ranks them; provenance only records the route. A judged P5 hierarchy finding can sort above a machine `typ-15` finding, and does when its severity is higher.
-
-## Severity: a ranked scale, never a score
-
-`auto-critical → critical → major → minor`. Ordering, comparability, and priority all come from the rank — never from a number.
-
-- **auto-critical** — assigned *mechanically, by rule, never by judgment*. Two triggers: absence of `trust-01`, `trust-02`, or `trust-03` (AI presence undisclosed, no human override path, an irreversible AI action ungated by consent-and-preview); and any irreversible action lacking **both** a confirm step **and** an undo path (`int-05`). No waiver, and no judgment call can down-rank it — it sorts to the top of every list.
-- **critical** — the surface fails at its purpose: data unreadable or wrong, a required state missing so the surface reads as broken, an accessibility block, a contract about to break.
-- **major** — real loss of throughput or trust; the surface still works but taxes the operator on every use.
-- **minor** — polish: an off-scale value, a tracking miss, a redundant separator. Correct, not costly.
-
-## No numeric scores — a measurable before→after instead
-
-The engine never emits a score. No 0–4, no 0–100, no percentage grade — runtime scores are false precision the best practitioners avoid; the catalog's own machine-check output is defect *evidence*, not a number to average. Comparability comes from two things that do not pretend to a decimal: the severity rank orders the list, and the **mandatory measurable before→after** on every finding says exactly what changes.
-
-Machine-backed → numeric (`620ms → ≤500ms`; `12px → 14px`). Judged → a concrete before/after state (`AI draft renders identically to human messages → AI draft carries a disclosure chip and a muted treatment`). Banned always: "feels off," "make it cleaner," any adjective standing in for a change. `cod-13` is this contract; `self-integrity.mjs` checks that every finding carries a before→after.
-
-## Instruments: numbers as evidence, never verdicts
-
-The render rung computes deterministic numbers (`inst-*`) over the rendered surface. They enter findings **only as evidence inside a judged finding** — never as a gate, never as a verdict.
-
-**Pixel-level instruments** (`inst-01`..`inst-10`): edge density, feature congestion, subband entropy, grid quality, white-space ratio, symmetry, figure-ground contrast, contour congestion, colorfulness, distinct-RGB count. A finding may cite one — *"edge density 0.31 vs the 0.18–0.24 typical of shipped operator surfaces"* — as evidence for a judged P5 or P2 finding. The verdict stays judged.
-
-The load-bearing caution: **dense operator surfaces are dense on purpose.** "Lower visual complexity ⇒ better" was refuted 0–3 in adversarial verification; on an information-dense surface the sign of "good" can invert. A high instrument number is a prompt to *look*, never proof of a problem, and a threshold is never derived from an exemplar (circular). Start with edge density — cheapest, best-documented — and treat every reading as a signal.
-
-**KLM operator-cost** (`inst-11`): a comparative throughput diagnosis, not ground truth. Sum the typed operators over a fixed core-loop path with the published constants — **P (point) 1.10s · H (home hand between keyboard and mouse) 0.40s · M (mental prep) 1.35s · K (keystroke) 0.20–0.28s** — counting clicks, keystrokes, tab-stops, and hand-homings. It compares two paths (before a redesign vs after, path A vs path B), pairing with the entity/surface map's core loop ([structure.md](structure.md)) and floor f01's throughput-first metric. It is a cost *model*: path selection is judgment, so the number is evidence for a judged B1/B4 finding, never a verdict.
-
-## The AI-surface trust rubric
-
-Any surface that shows AI-originated content or takes AI-initiated actions is diagnosed against the trust rubric ([../data/operator-pack/trust-rubric.md](../data/operator-pack/trust-rubric.md)) — four judged dimensions (`trust-01`..`trust-04`), fired inside every improve and introspect sweep, skipped on surfaces with no AI content. Its findings are judged findings on this schema, peers of every other. The rubric owns the four dimensions and their auto-critical gradings; diagnosis consumes them.
-
-## The decay ledger
-
-Quality is the skill's burden, never the user's — so decay is *observed*, not silently absorbed. A run appends to `docs/memory/design-decay.md` (a project memory file, per the CLAUDE.md memory convention) whenever its guidance failed to land. Three event classes:
-
-1. **Machine violations surviving fix-or-classify** — a rule fired and the run resolved it by classifying the rule as inapplicable rather than fixing it (the classification is logged as the fix-or-classify directive requires), or a violation reached ship neither fixed nor classified.
-2. **Judged findings recurring across runs** — the same judged finding reappears on a later run, evidence the guidance is not being absorbed.
-3. **Guidance fought or produced wrong output** — the agent resisted a rule, or following the guidance yielded a worse result or collided with the user's workload.
-
-The ledger is **maintainer-facing telemetry, not runtime state** — the emitted UI stays the only design record (floor f08). The skill never reads it back and **never self-modifies**. The maintainer reads it, diagnoses whether the failure is the skill's design or the project's circumstances, and closes it by hand — updating the skill, or going back to the user.
-
-Entries are **dated, factual, and human-closed** — append-only, oldest at bottom:
-
-```
-## YYYY-MM-DD — <topic>
-
-- event: <machine-violation-classified | judged-finding-recurring | guidance-fought>
-- anchor: <rule id or judged dimension>
-- where: <surface / file:line>
-- what happened: <one factual line — what fired, how it resolved, no editorializing>
-- run: <create | improve:<verb> | introspect>
-```
-
-No verdict, no severity, no remediation in the entry — it records what happened, not what to do about it. The closing is the maintainer's.