@nurix/etna 0.19.10 → 0.19.12

package/data/harnesses/code/skills/design/references/ux-patterns/verbs.md

@@ -0,0 +1,45 @@
+---
+id: verbs
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.3"
+license: open
+---
+# Pass: verbs & actions
+
+**Inputs:** per verb — `verbKind` (transition | edit | association | collaboration | communication | conversion | break-glass | approval-gated), `reversible`, `outwardFacing`, `bulk`, `blastRadius` (single-record | many-records | external-fanout), `thresholdVariant`.
+**Owns:** `requiredMechanics`, `requiredStates`, `containers` (confirmation surfaces only), `clarifications`.
+**Output artifact:** the verb matrix — object × state × role → available actions — the single inventory that generates every button, quick action, bulk action, row action, context-menu entry, and empty-state CTA. No surface invents its own buttons; each shows a slice of the matrix (header: the 1–3 highest frequency × criticality verbs for this state and role; row hover: 2–3 highest-frequency; bulk bar: the bulk-capable set; context menu: the full legal set). A verb keeps the same name, icon, and semantics on every surface.
+
+## The rule
+
+**Actions = f(object, state, role).** There is no fixed button set: transitions read directly off the state-machine graph (Refund only on succeeded, Void only on open), and role gates which legal verbs this viewer may perform, including threshold variants (refund up to $500; above that the verb becomes approval-gated).
+
+**Reversibility dictates confirmation UX.** Reversible → optimistic commit + undo toast; confirm dialogs destroy flow and train users to click through them. Irreversible or outward-facing (leaves the building: send to customer, charge a card) → explicit confirmation scaled to stakes, up to typed confirmation. Undo requires the data model to be able to restore — soft-delete and the Logged class exist to guarantee it; decide reversibility in the model, then let the confirmation follow. If reversibility is undeclared on a mutating verb, clarify before choosing either treatment.
+
+**Verb classes with hard invariants:**
+- **Communication** — internal note and customer-facing send are *different verbs*, never a toggle buried in one composer: distinct affordance, distinct color, distinct confirmation weight. Sending to the wrong audience is a severity-1 failure.
+- **Conversion** — born-from transformations (Lead → Account + Contact + Opportunity) create several records atomically and need a preview of what will be created and how fields map; conversion output never passes through a create form.
+- **Break-glass** — overrides require reason capture at invocation and Logged history on everything touched; never bulk-capable — reason capture is per-incident by definition.
+- **Approval-gated** — invocation submits, never executes: the object enters a pending-approval state and an approver receives Approve/Reject with required rationale in their queue.
+- **Collaboration** — watch, assign, comment are ordinary asset-level verbs in the matrix; only their output (viewer-relative relationship data) is special.
+
+**Bulk variants** get preview-before-commit when blast radius is large ("38 leads → owner: Priya") and per-row partial-failure reporting after ("34 updated, 4 failed" with reasons) — never a blanket success.
+
+```json decision-table
+{"pass": "verbs", "rows": [
+  {"when": {"verbKind": "transition"}, "then": {"requiredMechanics": {"mustInclude": ["state-gated-availability", "verb-consistency-across-surfaces"]}}, "reason": "transitions-read-off-the-graph"},
+  {"when": {"verbKind": "edit"}, "then": {"requiredMechanics": {"mustInclude": ["inline-edit-default"]}}, "reason": "edit-verbs-are-rarely-buttons"},
+  {"when": {"verbKind": "communication"}, "then": {"requiredMechanics": {"mustInclude": ["audience-split-verbs", "distinct-send-affordances"], "mustNotInclude": ["audience-toggle-single-composer"]}}, "reason": "audience-safety-is-a-verb-split"},
+  {"when": {"verbKind": "conversion"}, "then": {"requiredMechanics": {"mustInclude": ["conversion-preview-mapping", "atomic-multi-record-create"]}}, "reason": "conversion-shows-what-it-creates"},
+  {"when": {"verbKind": "break-glass"}, "then": {"requiredMechanics": {"mustInclude": ["reason-capture-required", "logged-history-class"], "mustNotInclude": ["bulk-capability"]}}, "reason": "override-without-audit-is-liability"},
+  {"when": {"verbKind": "approval-gated"}, "then": {"requiredMechanics": {"mustInclude": ["submit-not-execute", "approver-queue-routing", "approve-reject-rationale"]}, "requiredStates": {"mustInclude": ["pending-approval"]}}, "reason": "invocation-submits-not-executes"},
+  {"when": {"verbKind": "collaboration"}, "then": {"requiredMechanics": {"mustInclude": ["ordinary-verb-treatment", "viewer-context-render-outputs"]}}, "reason": "collaboration-verbs-are-ordinary"},
+  {"when": {"thresholdVariant": true}, "then": {"requiredMechanics": {"mustInclude": ["threshold-conditional-approval"]}}, "reason": "threshold-splits-direct-and-gated"},
+  {"when": {"reversible": true, "outwardFacing": false}, "then": {"requiredMechanics": {"mustInclude": ["optimistic-commit", "undo-toast"], "mustNotInclude": ["confirm-dialog"]}, "containers": {"forbidden": ["center-modal"]}}, "reason": "undo-preserves-flow"},
+  {"when": {"reversible": false}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}, "containers": {"acceptable": ["center-modal"]}}, "reason": "irreversible-confirms"},
+  {"when": {"outwardFacing": true}, "then": {"requiredMechanics": {"mustInclude": ["explicit-confirmation-scaled"]}}, "reason": "outward-facing-confirms"},
+  {"when": {"bulk": true}, "then": {"requiredMechanics": {"mustInclude": ["bulk-preview-before-commit", "per-row-partial-failure-report"]}}, "reason": "blast-radius-needs-preview"},
+  {"when": {"verbKind": ["transition", "edit"], "reversible": "__absent__"}, "then": {"clarifications": ["reversibility-unspecified"]}, "reason": "reversibility-decides-confirmation-ux"}
+]}
+```

package/data/harnesses/code/skills/design/references/ux-patterns/viewer-context.md

@@ -0,0 +1,40 @@
+---
+id: viewer-context
+class: b2
+sourced: 2026-07-12
+source: "b2b-ux-patterns ch.4"
+license: open
+---
+# Pass: access & viewer context
+
+**Inputs:** `denialKind` (role | plan), `entitlementKind` (boolean | metered), `fieldLevelSecurity`, `requiredFieldHidden`, `existenceLeakRisk`, `viewerKind` (human | agent), `concurrentViewers`, `collaboration`, `environmentSeparation`.
+**Owns:** `requiredMechanics`, `clarifications`.
+**Output artifact:** the access model (who can see and do what, at which tier) and the viewer-context rules — what changes per viewer even among users with identical permissions. The governing axiom: **every render is a function of (data, viewer)**; no page, form, table, or button set is universal.
+
+## The rule
+
+**Access is a union, not a role lookup:** role baseline + additive permission sets + record-level sharing (ownership, hierarchy rollup, territory) + field-level security. Two users with the same role legitimately see different rows, fields, and actions — normal operation, not an edge case. Field-level security silently reshapes every surface: a hidden field vanishes from detail, form, column picker, filter builder, export, and API — so forms and tables render from schema + viewer access, never a hard-coded field list. The classic trap: a field *required* for the object but *hidden* from a role makes creation impossible for that persona — validate layouts per role. "Read-only" is often an access artifact, not a page property.
+
+**Role-denied and plan-denied render differently.** Role-denied → hidden (or disabled where discoverability matters); never sell a user a feature their admin withheld. Plan-denied → visible but locked with an upgrade path; metered entitlements get the quota render ("4 of 5 seats used") with its own upgrade door. Conflating the two produces invisible revenue or unusable noise.
+
+**The existence contract:** denied must never render as empty — users conclude the data is missing and re-create it. Decide per object whether a forbidden record admits existence (explicit no-access, ideally with a request path) or denies it (not-found, the GitHub-404 move) when even revealing existence leaks information.
+
+**Collaboration is personalization of data display**, not a feature layer: ownership decoration, watch state and fresh-activity markers, viewer-relative filters ("Assigned to me" is typically the most-used view — a default, not a user-built filter), read/unread state, presence and edit-conflict warnings. Notification records are ordinary child objects emitted by watch/assign/mention verbs; their delivery matrix lives in `standard-pages`.
+
+**Agent principals join the union** with their own permissions and audit trail, carrying a delegated-subject chain ("acting for whom") on every read and write — effective access is the intersection of the agent's grants and its delegating subject's, never a stale copy. "Delegated to my agents" is a distinct filter from "Assigned to me". Impersonation/view-as (with a persistent banner and full audit logging) is the only honest debugger once record- and field-level access exist; a test-vs-live environment fork needs a loud persistent banner — acting in the wrong environment is one of the costliest B2B errors.
+
+```json decision-table
+{"pass": "viewer-context", "rows": [
+  {"when": {"denialKind": "role"}, "then": {"requiredMechanics": {"mustInclude": ["hidden-or-disabled-affordance"], "mustNotInclude": ["visible-locked-upsell"]}}, "reason": "role-denied-hides"},
+  {"when": {"denialKind": "plan", "entitlementKind": "boolean"}, "then": {"requiredMechanics": {"mustInclude": ["visible-locked-upsell"], "mustNotInclude": ["hidden-or-disabled-affordance"]}}, "reason": "plan-denied-sells"},
+  {"when": {"denialKind": "plan", "entitlementKind": "metered"}, "then": {"requiredMechanics": {"mustInclude": ["metered-quota-render", "upgrade-door"]}}, "reason": "metered-entitlement-render"},
+  {"when": {"fieldLevelSecurity": true}, "then": {"requiredMechanics": {"mustInclude": ["schema-driven-rendering", "per-viewer-field-filtering"], "mustNotInclude": ["hard-coded-field-list"]}}, "reason": "fls-reshapes-every-surface"},
+  {"when": {"requiredFieldHidden": true}, "then": {"requiredMechanics": {"mustInclude": ["per-role-layout-validation"]}}, "reason": "required-hidden-field-blocks-persona"},
+  {"when": {"existenceLeakRisk": true}, "then": {"requiredMechanics": {"mustInclude": ["not-found-render"], "mustNotInclude": ["denied-renders-as-empty"]}}, "reason": "existence-itself-leaks"},
+  {"when": {"existenceLeakRisk": false, "denialKind": "role"}, "then": {"requiredMechanics": {"mustInclude": ["explicit-no-access-render", "request-access-path"], "mustNotInclude": ["denied-renders-as-empty"]}}, "reason": "denied-never-reads-empty"},
+  {"when": {"viewerKind": "agent"}, "then": {"requiredMechanics": {"mustInclude": ["agent-principal-access-union", "delegated-subject-chain", "agent-audit-trail", "delegated-to-my-agents-filter"]}}, "reason": "agent-is-a-governed-principal"},
+  {"when": {"collaboration": "concurrent"}, "then": {"requiredMechanics": {"mustInclude": ["viewer-relative-filters", "assigned-to-me-default", "read-unread-state"]}}, "reason": "render-is-f-data-viewer"},
+  {"when": {"concurrentViewers": true}, "then": {"requiredMechanics": {"mustInclude": ["presence-indicators", "edit-conflict-warning"]}}, "reason": "live-viewer-context"},
+  {"when": {"environmentSeparation": true}, "then": {"requiredMechanics": {"mustInclude": ["environment-banner"]}}, "reason": "wrong-environment-costliest-error"}
+]}
+```

package/data/harnesses/code/skills/design/scripts/README-validator.md

@@ -0,0 +1,27 @@
+# validate-design-md.mjs — the design.md system's validator + token emitter
+
+**CLI:** `node validate-design-md.mjs <file|folder> [--mode admission|build|ship] [--json] [--emit]`
+File mode validates one design.md. Folder mode validates every `.md` in the tree (skipping `SCHEMA.md`) plus `index.csv` integrity.
+`admission` and `build` run the same checks; `ship` adds the dmv-11 drift check against a `design.tokens.css` beside the input file.
+`--json` prints `{file, fails:[{id,detail}], warns:[{id,detail}]}` (array in folder mode). Exit 0 on pass (warns allowed), 1 on any FAIL.
+
+**Emit:** `--emit` (single file) compiles the token artifact from the `yaml design-values` block to stdout — deterministic, byte-stable;
+redirect to `design.tokens.css`. Shape: `:root, :root[data-theme="light"]` + `:root[data-theme="dark"]` blocks (specificity armor, both
+0,2,0) carrying the 36 color roles as `--<role>`; the light block also carries `--font-display/sans/mono` (registered names quoted, with
+fallback stacks), `--text-<step>-size/-line/-weight` (+ `-family/-tracking/-features`), `--radius-*`, `--shadow-*`, `--duration-*`,
+`--ease-*`, and layout vars (`--space-base`, `--sidebar-width[-collapsed]`, `--topbar-height`, `--side-panel-width[-wide]`, `--content-max-width`).
+
+**Fails (close the gate):** dmv-01 frontmatter strict, per-tier keys, id = filename · dmv-02 the 12 sections in order, non-empty,
+plus trailing design-values block · dmv-03 value block parses as YAML · dmv-04 coverage: 36 roles × both themes, ramp, register-scope,
+elevation, motion base, iconography, charts, layout · dmv-05 contrast on every declared pairing (body ≥ 4.5:1; primary/accent/
+destructive/sidebar-primary fills ≥ 3:1, warn under 4.5) · dmv-06 no image reference anywhere · dmv-07 index.csv ↔ files, both
+directions, no duplicates · dmv-08 registered font names + fallback stacks · dmv-09 no claude.md (any case) · dmv-10 project tier:
+`primitives: nurix|native` + `source-package` · dmv-11 (ship) emitted artifact byte-matches recompilation.
+
+**Warns (recorded, never close):** dmw-01 background in the anti-cream band (L 0.84–0.97, C < 0.06, hue 40–100) · dmw-02 neutral
+surfaces pure gray (C < 0.005) or over-tinted (C > 0.015) · dmw-03 untinted black shadow above 0.15 alpha · dmw-04 ease-in entrance
+or duration over its element-class budget · dmw-05 display face granted a data register · dmw-06 dark ladder steps < ~0.04 L or hue
+drift · dmw-07 accent chroma delta between themes > 0.06.
+
+Stdlib-only: vendors its own YAML-subset parser and oklch → sRGB → WCAG-contrast math. The exact contrast pair table, thresholds,
+and emission order live in the script's header comment.