@nurix/etna 0.19.11 → 0.19.12

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

@@ -1,159 +0,0 @@
-# Structure derivation
-
-The second create phase. Runs after intake, before scaffold. Two steps, in order: the **object pass**, then **archetype assignment**. The output is one small, durable file — `docs/design/structure.md` — that every later phase reads and `scaffold.mjs` consumes.
-
-The pass is never skipped. A small brief earns a proportionally small pass — a two-entity brief gets a two-entity map — but it always runs. Skipping straight to layout is the characteristic structural failure: screens that look plausible and model the domain wrongly. The structure phase gate requires a populated map before scaffold opens; an empty pass fails it.
-
-## The object pass
-
-Extract the domain model from the brief. Record, per the map schema below:
-
-- **Entities** — the nouns the operator works with (Ticket, Customer, Agent, Device). Extract what the brief and its domain support; do not fabricate entities the domain lacks, and do not promote an attribute to an entity.
-- **Attributes** — the fields each entity carries.
-- **Relationships and cardinalities** — how entities connect, recorded as `{to, cardinality}` (`one-to-one`, `one-to-many`, `many-to-one`, `many-to-many`).
-- **Lifecycle states** — the ordered states an entity moves through (new → open → pending → resolved → closed). Omit for stateless entities.
-- **Unit of work** — the one entity the operator's day turns on (the ticket, the case, the job). It anchors the home surface.
-- **Core loop** — the verb sequence the operator runs on the unit of work (triage → assign → work → resolve → close).
-
-Two modeling traps, both fatal to structure:
-
-- **Metrics are not entities.** CAC, open-ticket-count, and p95-latency are instances of one Metric object, not entity rows. They render on a dashboard; they never earn their own list surface.
-- **One entity, one home.** An entity's data and actions gather on one surface, cross-linked from everywhere else — never scattered across screens.
-
-## The temporal probe
-
-Runs inside the object pass — temporal semantics are model facts, not styling facts, and the brief states none of them. Probe five questions:
-
-- **Intermediate states** — does an action pass through pending / saving / processing / awaiting-approval before its terminal state?
-- **Read-model lag** — is there delay between write and read visibility? Where yes, staleness is marked honestly downstream.
-- **Deletion semantics** — archive, trash, hard delete, or regulatory retention? Each is a different surface and a different affordance.
-- **History** — is prior state auditable or required? Its answer surfaces as a model fact — a History/audit entity, a timeline, or a versioned attribute.
-- **Failure paths** — validation, server error, disconnection, concurrent edit.
-
-Four answers land in the map's `temporal` block (`intermediate-states`, `read-model-lag`, `deletion`, `failure-paths`); history's answer lands wherever the model puts it (an entity, an attribute, a surface). The probe is what makes the lifecycle phase's states bindable — the tool spends most of its life in states the brief never mentions.
-
-## Archetype assignment
-
-Each entity and workflow claims surfaces from the closed six-archetype catalog. `data/operator-pack/surface-catalog.md` is canonical for the choosing rules, the per-archetype density modifier, and the exemplar pointer; the assignment reads them. Orientation:
-
-| archetype | claimed when |
-| --- | --- |
-| `list-detail` | a high-cardinality collection worked one item at a time — the unit of work's home |
-| `dashboard` | a read-first overview answering a few standing questions across entities (Metric instances) |
-| `entity-detail` | one rich entity's attributes, relationships, and actions gathered on a single surface |
-| `create-edit` | minting or editing one entity — a stepper that mirrors edit; templates prefill |
-| `log-stream` | append-only, high-volume, time-ordered events — read and filter, rarely edit |
-| `command-center` | a live multi-pane monitor over several entities at once, with drill-down |
-
-Membership is closed. New archetypes enter only as pack data, ledger-recorded — never invented per run.
-
-**Navigation derives from the object model, never decorated on.** Top-level nav entries are the primary entities and their home surfaces; secondary entities are reached through their parent's detail surface, not promoted. The unit of work is the home. Cap top-level entries at what stays countable on one hand — nav categories the model does not carry are a structural defect, not a convenience.
-
-## The delight budget — permission is structural
-
-The object pass classifies **every** surface with a mandatory `budget` — `baseline` or `brand-forward`. Permission is a structural fact decided here, not a look value: the budget grants which token *vocabulary* a surface may consume, never a value. `scaffold.mjs` stamps the budget into each route file's header comment (`// Surface: baseline` / `// Surface: brand-forward (delight-allowing)`); `phase-gate.mjs surfaces` reads the stamp back.
-
-**Defaults by archetype** — assign the default, override only against a recorded reason:
-
-| Archetype | Default | Note |
-| --- | --- | --- |
-| `list-detail`, `log-stream`, `command-center` | `baseline` | throughput surfaces; decoration is noise here |
-| `dashboard`, `entity-detail` (header region), `create-edit` (empty / success moments) | `brand-forward` **candidate** | granted when the look's `delight` is `expressive` or the brief asks for presence; else `baseline` |
-
-- **Overridable, against a recorded reason.** A budget that contradicts the archetype default — a `brand-forward` stamp on a `baseline`-default archetype — carries a `budget-reason` on that surface entry, or the surfaces gate fails. Candidacy is not a grant: a candidate archetype still defaults `baseline` and only rises to `brand-forward` when the look or brief earns it.
-- **`baseline` blocks decoration, never signal.** A `baseline` stamp never suppresses status or feedback color — error red, warning amber, the success tick all render at every budget. It withholds *ornament*: the display ramp step, elevation lifts, washes, arrival motion.
-- **What `brand-forward` unlocks** — all still tokens, all still on-scale: the `display` ramp step (one per surface), `elevation.lg`, the `wash.*` tokens, the motion moments in `motion.csv`, and the generous spacing tier.
-- **What no budget ever unlocks:** literal colors, off-manifest values, slop-gradient vocabulary, serif in dashboards. The floor is budget-independent — a brand-forward surface clears the same rules a baseline one does. Expressiveness is granted *inside* the floor, never as an exception to it.
-
-## The map: `docs/design/structure.md`
-
-The derivation's whole output. Human prose above the block; the fenced `yaml structure` block is the machine contract — `scaffold.mjs` reads it, so the field names are law. Scaffold generates routes, navigation wiring, and per-surface state-shell stubs from `surfaces[]`, and keys fixture wiring off `entities[]`.
-
-```yaml structure
-unit-of-work: <entity>
-core-loop: <verb → verb → verb>
-entities:
-  - name: <Entity>
-    attributes: [<field>, ...]
-    lifecycle: [<state>, ...]        # omit for stateless entities
-    relationships:
-      - { to: <Entity>, cardinality: one-to-one | one-to-many | many-to-one | many-to-many }
-temporal:
-  intermediate-states: [<state>, ...]
-  read-model-lag: <none | description>
-  deletion: <archive | trash | hard | retained>
-  failure-paths: [validation, server-error, disconnection, concurrent-edit, ...]
-surfaces:
-  - name: <Surface>
-    archetype: list-detail | dashboard | entity-detail | create-edit | log-stream | command-center
-    route: /<path>
-    entity: <Entity>
-    density-modifier: <integer step; positive = denser; mirrors the catalog's per-archetype modifier>
-    budget: baseline | brand-forward           # mandatory; the surface's delight budget
-    budget-reason: <one line>                  # required only when budget overrides the archetype default
-    states: [loading, empty, error, partial]   # applicable subset; data surfaces carry all four
-```
-
-## OOUX structural diagnostics
-
-Four judged diagnostics for a wrong object model (after Sophia Prater's OOUX vocabulary). Run them over the map and over any UI under review; each is a one-line detection question:
-
-- **Shapeshifter** — is one entity rendered inconsistently across surfaces? (Does a Ticket's status pill look different in the queue than in the detail?)
-- **Masked** — is an entity hidden inside another's UI, with no surface of its own? (Is Customer only ever a string on a Ticket, never its own object?)
-- **Broken** — is an entity's data or actions split across surfaces with no complete home? (Are a Device's config and its telemetry on two unrelated screens?)
-- **Isolated** — is an entity unreachable from the navigation and from its relationships? (Can the operator reach an Agent from anywhere?)
-
-These are judgment, not machine rules — no waiver, no score. A finding is raised, ranked, and fixed at the model layer, never patched at the surface.
-
-## Worked example — a ticket queue
-
-Brief: *"A support ticket queue. Agents triage incoming tickets, assign them, work them to resolution, and close them. Tickets come from customers."*
-
-```yaml structure
-unit-of-work: Ticket
-core-loop: triage → assign → work → resolve → close
-entities:
-  - name: Ticket
-    attributes: [subject, body, status, priority, channel, requester, assignee, created_at, updated_at]
-    lifecycle: [new, open, pending, resolved, closed]
-    relationships:
-      - { to: Customer, cardinality: many-to-one }
-      - { to: Agent, cardinality: many-to-one }
-  - name: Customer
-    attributes: [name, email, org]
-    relationships:
-      - { to: Ticket, cardinality: one-to-many }
-  - name: Agent
-    attributes: [name, email, role, availability]
-    relationships:
-      - { to: Ticket, cardinality: one-to-many }
-temporal:
-  intermediate-states: [assigning, saving-reply, pending-customer]
-  read-model-lag: none            # single-writer per ticket
-  deletion: archive               # tickets are retained for audit, never hard-deleted
-  failure-paths: [validation, server-error, disconnection, concurrent-edit]
-surfaces:
-  - name: Ticket Queue
-    archetype: list-detail
-    route: /tickets
-    entity: Ticket
-    density-modifier: 1
-    budget: baseline
-    states: [loading, empty, error, partial]
-  - name: Ticket Detail
-    archetype: entity-detail
-    route: /tickets/:id
-    entity: Ticket
-    density-modifier: 0
-    budget: baseline
-    states: [loading, empty, error, partial]
-  - name: New Ticket
-    archetype: create-edit
-    route: /tickets/new
-    entity: Ticket
-    density-modifier: -1
-    budget: baseline
-    states: [loading, error]
-```
-
-Navigation: top-level is **Tickets** — the unit of work's home. Customer and Agent are reached through Ticket Detail, not promoted to top-level nav (derived, not decorated). History — the audit of status changes and replies — surfaces as a timeline on the detail, not a fifth temporal key. OOUX pass: the status pill renders identically on queue and detail (no Shapeshifter), and Customer links out to its own detail rather than living only as a string (no Masked). Budgets: every surface stamps `baseline` — the brief states no expressive delight, so the two candidate archetypes (Ticket Detail's header, New Ticket's success moment) stay at their default; a queue is `baseline` outright. No `budget-reason` is needed because no stamp overrides an archetype default.