@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/code/skills/boundary/SKILL.md

@@ -7,35 +7,38 @@ description: "Use when a plan or diff might break a cross-cutting contract. Boun
 
 You diagnose whether a plan's changes would break an application boundary.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Your job is to find those edges in the plan's path _before_ execution.
+A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them: the column a raw SQL string names, the JSON envelope a client unwraps, the event string a dispatcher parses, the env var a deploy script writes. Changing one side ships green — compiles, lints, tests pass — and breaks the other at runtime. Find those edges in the plan's path _before_ execution.
 
-**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — a change that fails the build loudly needs no diagnostic. Spend your reading on the edges with no static link.
+**The litmus is "would it ship green?"** An edge the compiler or an existing test already guards is not a boundary — spend your reading on the edges with no static link.
 
 ## Contract sources
 
 Three layers tell you what to look for; the code tells you what exists.
 
-- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
-- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
-- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
-
-The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
+- **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md): the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal fix, and severity, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
+- **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code; each pack carries one technology area's detect patterns, gotchas, and safe-change sequences. Load **only** the packs the touch list exhibits. The packs are a floor, not a fence: a contract no pack covers is still in scope — diagnose it from its mechanism and report it if it passes the litmus.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how a greenfield plan, with no code to trace, still gets checked.
 
 ## Run
 
-**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff / named code area for non-plan work. Everything below is identical either way; a diff's hunks stand in for the plan's steps.
+**Input:** a plan path (given, or the newest in `docs/history/plans/`) — or a diff or named code area for non-plan work, where the diff's hunks stand in for the plan's steps. Steps 1–5 are identical either way; the report's **Missing plan subsections** and **Docs the plan's ledger missed** sections, and step 6, apply only to a plan.
+
+1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities or state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+
+2. **Identify the contracts.** Read each touched file and its immediate imports. Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
 
-1. **Build the touch list.** Parse the plan's Proposed Changes: files created or modified, entities/state added or changed, API changes, anything the author flags as a cross-module contract. Note missing subsections.
+3. **Trace the other side.** The danger lives on the side the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`, doctrine as the doc path. At ≳10 contracts, fan the tracing out to parallel sub-agents — one per pack area, each prompt self-contained with its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
 
-2. **Identify the contracts.** Read each touched file (and its immediate imports). Against the mechanisms, the routed packs, and the repo doctrine, list the contracts this code participates in — the schema it queries, the envelope it emits, the events it publishes or parses, the auth checks it sits behind, the env it reads.
+4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Grade it:
 
-3. **Trace the other side.** A boundary has two sides; the danger lives on the one the plan _doesn't_ mention. For each contract, grep the shared name or shape across the repo — the column name in other SQL strings, the response field in client unwrappers, the event kind in subscribers, the route in fetch calls and scripts, the env key in deploy tooling. Record consumers as `file:line`; record doctrine as the doc path. When the touch list is large (≳10 contracts), fan the tracing out to parallel sub-agents — one per pack area, each with a self-contained prompt naming its contracts and grep targets — and judge the returned evidence yourself; a small diff traces inline.
+   | Severity | Meaning |
+   | --- | --- |
+   | **CRITICAL** | Can corrupt persisted data, or open an auth/money path — trust-invariants and persisted or replayed shapes live here |
+   | **HIGH** | Silent cross-module breakage that ships green |
+   | **MEDIUM** | Drift-prone coupling not yet broken (string-matched, duplicated constants) |
+   | **LOW** | Smell |
 
-4. **Judge each intersection.** Does the planned change alter a shape a traced consumer depends on, break an invariant the code or doctrine establishes (append-only vocabularies, idempotency keys, fail-closed checks, ordering guarantees), or introduce a new cross-module edge? Severity:
-   - **CRITICAL** — can corrupt persisted data, or open an auth/money path.
-   - **HIGH** — silent cross-module breakage that would ship green.
-   - **MEDIUM** — drift-prone coupling (string-matched, duplicated constants).
-   - **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH.
+   Loud, immediately visible runtime breakage caps at HIGH. Severity is intrinsic to the finding, never curved — three genuine CRITICALs in a small repo is signal, not inflation.
 
 5. **Report in chat:**
 
@@ -61,15 +64,23 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
    | Feature doc | Owned path in the touch list | In Doc Obligations? |
    ```
 
-   **The doc cross-check is free and you are the only one who can make it.** You already hold the touch list; resolving those paths against the ownership index and comparing the result to the plan's **Doc Obligations** rows costs one lookup. The plan's author wrote that ledger, so it is the one gate artifact nobody independently checked — a `None` that contradicts your touch list is the failure this section exists to catch. Report the gap; never edit the ledger yourself.
+   **Fill the doc cross-check from the touch list you already hold:** resolve its paths against the ownership index and compare the result to the plan's **Doc Obligations** rows. The plan's author wrote that ledger and nobody else checks it — a `None` that contradicts your touch list is the failure this section catches. Report the gap; **never** edit the ledger yourself.
+
+   **BLOCK** = any CRITICAL; a blocked plan folds the amendments and re-runs the check. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the pack entry's **Safe change** or the mechanism's **Universal fix**.
+
+6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly one of:
 
-   **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — the invoking session folds the amendments into the plan in the same pass, before the plan is shown as finished. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
+   | Verdict | Segment |
+   | --- | --- |
+   | PASS | `Boundary: passed YYYY-MM-DD` |
+   | PASS WITH AMENDMENTS | `Boundary: passed YYYY-MM-DD` — written only once the amendments are folded |
+   | BLOCK | `Boundary: blocked YYYY-MM-DD` |
 
-6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps exactly this segment — implementation edits inside the plan's scope stay blocked while it reads `Boundary: pending` (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
+   The compliance hook greps exactly this segment and blocks implementation edits inside the plan's scope until it reads `passed` — `pending` and `blocked` wall alike (the other gates are enforced by section presence, not segment text). A plan with no `Gates:` line gets one added; never skip the write-back.
 
 ## Rules
 
-- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan in the same pass, then writes the segment to `passed`; a plan is not finished until it does. The single write you own is the plan's `Gates:` line (step 6), your segment only.
-- **Verify in source.** Never flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
-- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it isn't a violation — it's a **new edge**: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
+- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the invoking session folds your amendments into the plan; a plan is not finished until its segment reads `passed`. The single write you own is the plan's `Gates:` line (step 6), your segment only.
+- **Verify in source.** **Never** flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
+- **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it is a **new edge**, not a violation: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
 - **A clean report is valid.** Zero violations means say so — the coverage table is the evidence it was checked, not skipped. Don't pad findings.

package/data/harnesses/code/skills/boundary/references/index.md

@@ -1,16 +1,14 @@
 # Pack routing index
 
-Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes. Several packs matching is normal (a full-stack feature typically routes 2–4). A technology matching nothing here is still in scope — diagnose it from its mechanism, and check `packs/generic-tail.md` for a thin entry.
+Load when: every boundary check, right after `mechanisms.md`. Match the touch list against the signals below and load **only** the packs whose signals appear in the touched files or the plan's Proposed Changes — a full-stack feature typically routes 2–4. A technology matching no row has a thin entry in `packs/generic-tail.md` or none; either way, diagnose it from its mechanism.
 
 | Pack | Load when the touch list shows |
 | --- | --- |
 | `packs/persistence.md` | `schema.ts`, `init.sql`, `sqliteTable(`, `drizzle-kit`, `pgTable`, migrations, `*.seed.sql`, seed generators, JSON columns, `pgEnum`, pgvector, Redis `get`/`set` caching |
 | `packs/wire-api.md` | Express routes/middleware (`app.use(`, `router.`), `res.json({ status`, zod schemas on requests, axios clients/interceptors, `cors(`, inbound webhooks, `rateLimit(` |
-| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
+| `packs/frontend.md` | `createSlice`/`configureStore`, RTK Query (`tagTypes`), react-router tables/`useParams`, Tailwind CSS (`@theme`, `personality.css`, `design.tokens.css`, `globals.css`), `vite.config.*` (alias, env), `@nurix/components`, localforage/redux-persist, date formatting |
 | `packs/auth.md` | `jwtVerify(`/jose, `betterAuth(`/`auth.api.`, session cookies, CSRF, OAuth callbacks/`redirect_uri`, `tenantId`/`organizationId` scoping, password hashing, auth middleware mounts |
 | `packs/cloudflare.md` | `wrangler.jsonc`/`wrangler.toml`, `env.X` bindings, `extends DurableObject`/`[[migrations]]`, KV/R2/D1/Queues, `scheduled(`/crons, `WorkerEntrypoint`, `compatibility_date`, static assets config |
 | `packs/async-messaging.md` | BullMQ (`new Queue(`/`new Worker(`), Redis pub/sub or Streams, WebSockets/socket.io, SSE (`text/event-stream`), channel-name templates, outbound webhook senders |
 | `packs/build-config-runtime.md` | `package.json` (deps/`exports`/scripts/`packageManager`), lockfiles, `.env*`, tsconfig `paths`, Dockerfiles/compose, `.github/workflows/`, pino config, `trust proxy`, ports/healthchecks |
 | `packs/generic-tail.md` | GraphQL, gRPC/protobuf, tRPC, OpenAPI codegen, Kafka/schema registry/CDC, workflow engines, event sourcing, Postgres RLS/pooling/collation, SSR/hydration, module federation, i18n, analytics plans, hosted feature flags, K8s probes/shutdown/limits, service mesh, IaC outputs, SAML, Lambda, IPC |
-
-Two files never route — they always load: `mechanisms.md` (the seven failure mechanisms + domain contracts) and this index.

package/data/harnesses/code/skills/boundary/references/mechanisms.md

@@ -1,10 +1,8 @@
 # Boundary Mechanisms
 
-Load when: every boundary check — this is the core reference. The technology packs under `packs/` instantiate these mechanisms with exact detect signals and gotchas; `index.md` routes to the packs the touched code exhibits.
+Load when: every boundary check — this is the core reference. The packs under `packs/` instantiate these mechanisms with exact detect signals and gotchas.
 
-A boundary is a contract between two pieces of code (or code and infra) that share an assumption with **no static link** between them. The litmus is **"would it ship green?"** — change one side, everything compiles, lints, and tests pass, and the other side breaks at runtime. An edge the compiler or an existing test already guards is not a boundary.
-
-Every boundary instantiates one of seven mechanisms. The mechanism tells you what to grep for, what the universal fix is, and how bad a break is — including for technologies no pack covers. When touched code exhibits a contract that matches no pack entry, diagnose it from its mechanism.
+Every boundary instantiates one of seven mechanisms. The mechanism tells you what to grep for, what the universal fix is, and how bad a break is — which is how you diagnose a technology no pack covers.
 
 ---
 
@@ -91,9 +89,4 @@ Two contracts come from the product's information architecture, not from any tec
 
 ## Severity recap
 
-- **CRITICAL** — can corrupt persisted data, or open an auth/money path. Trust-invariants and persisted/replayed shapes live here.
-- **HIGH** — silent cross-module breakage that ships green.
-- **MEDIUM** — drift-prone coupling (string-matched, duplicated constants) not yet broken.
-- **LOW** — smell. Loud, immediately-visible runtime breakage caps at HIGH; statically-guarded edges are out of scope entirely.
-
-Severity is intrinsic to the finding, not curved: three genuine CRITICALs in a small repo is correct signal, not inflation.
+The scale is `SKILL.md` step 4; each mechanism's **Severity** line above places a finding on it.

package/data/harnesses/code/skills/boundary/references/packs/build-config-runtime.md

@@ -27,7 +27,7 @@ Load when: the touch list exhibits `package.json` (deps, `exports`, scripts, `pa
 **Safe change:** Declare every imported package in the importer's own `package.json` (workspace siblings as `"@nurix/x": "workspace:*"`); never widen `public-hoist-pattern` to fix a missing-module error — add the dep; verify with a fresh `pnpm install` on a clean clone.
 
 ## package-exports-subpath-map — HIGH · rendezvous-string
-**Contract:** Consumers' import specifiers (`@nurix/components/button`) must match literal keys in the package's `exports` map; the `files` allowlist and `types` conditions must cover the same paths.
+**Contract:** Consumers' import specifiers (`@nurix/components/element/button`) must match literal keys in the package's `exports` map; the `files` allowlist and `types` conditions must cover the same paths.
 **Detect:** `"exports"` and `"files"` in `package.json`, `from ['"]@nurix/[^'"]+/`, `"moduleResolution"` in `tsconfig.json`
 **Ships green, breaks:** Any subpath not mapped in `exports` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` at runtime — and tsc under `moduleResolution: "node10"` ignores `exports` entirely, so types resolve while Node throws (use `"bundler"`/`"nodenext"` to make tsc see the real contract); adding a new component file without an `exports` entry publishes fine and breaks every consumer import; a built `dist/` path referenced by `exports` but missing from the `files` allowlist installs cleanly and fails only on first import of the published tarball.
 **Safe change:** Add the `exports` subpath (with `types` condition first in each condition block) in the same change as the new file; confirm `files` includes everything `exports` references; check the shipped surface with `npm pack --dry-run`; treat removing/renaming an exports key as a breaking change for all consumers.

package/data/harnesses/code/skills/boundary/references/packs/frontend.md

@@ -1,6 +1,6 @@
 # Pack: frontend / client state / UI build
 
-Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore`), RTK Query tags, react-router route tables, Tailwind 4 CSS (`@theme`, `personality.css`, `globals.css`), Vite config (`resolve.alias`, env), `@nurix/components` imports, localforage/redux-persist, or date handling crossing the wire.
+Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore`), RTK Query tags, react-router route tables, Tailwind 4 CSS (`@theme`, `personality.css`, `design.tokens.css`, `globals.css`), Vite config (`resolve.alias`, env), `@nurix/components` imports, localforage/redux-persist, or date handling crossing the wire.
 
 ## redux-persist-shape-migration — CRITICAL · serialized-shape
 **Contract:** State shapes frozen in the user's browser storage by redux-persist must be readable by the *current* reducers' `initialState` — `version`/`migrate` is the only bridge, and `whitelist`/`blacklist` reference reducer-map keys by literal string.
@@ -51,10 +51,10 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Safe change:** Grep both consumer forms — utility stems (`bg-old`, `text-old`) and `var(--…-old)` including `node_modules/@nurix/components` dist CSS; keep the old token as an alias for one release; visually diff themed screens after the rename.
 
 ## tailwind-theme-inline-indirection — HIGH · config-elsewhere
-**Contract:** `@theme inline { --color-primary: var(--primary) }` makes utilities emit the *referenced* variable (`background-color: var(--primary)`), resolved per-element at runtime — the org's theming (personality.css vars swapped under `[data-theme]`/`[data-style]`) only flows through utilities via the `inline` form.
-**Detect:** `@theme inline`, plain `@theme {`, token values that are `var(--…)`, `[data-theme=`/`[data-style=` blocks in `personality.css`
-**Ships green, breaks:** Adding a var-referencing token to a plain (non-`inline`) `@theme` block compiles and looks correct in the default theme; switching `data-theme`/`data-style` then silently fails to restyle those utilities, because the theme variable captured the referenced var's value as resolved at `:root` — subtree/attribute-scoped overrides never reach it. No warning, no error; only the alternate theme is wrong.
-**Safe change:** Any token whose value is `var(--app-var)` goes in the `@theme inline` block, raw literal values in plain `@theme`; after adding tokens, toggle `data-theme` and `data-style` in devtools and confirm the new utilities respond in both states.
+**Contract:** `@theme inline { --color-primary: var(--primary) }` makes utilities emit the *referenced* variable (`background-color: var(--primary)`), resolved per-element at runtime — the org's theming (token values swapped under `.dark`, and the personality.css `:root`/`.dark` overrides) only flows through utilities via the `inline` form.
+**Detect:** `@theme inline`, plain `@theme {`, token values that are `var(--…)`, `:root:not(.dark)`/`:root.dark` blocks in `design.tokens.css`, `:root`/`.dark` blocks in `personality.css`
+**Ships green, breaks:** Adding a var-referencing token to a plain (non-`inline`) `@theme` block compiles and looks correct in light mode; toggling `.dark` or recompiling the personality then silently fails to restyle those utilities, because the theme variable captured the referenced var's value as resolved at `:root` — mode-scoped and subtree overrides never reach it. No warning, no error; only the alternate mode is wrong.
+**Safe change:** Any token whose value is `var(--app-var)` goes in the `@theme inline` block, raw literal values in plain `@theme`; after adding tokens, toggle the `.dark` class on the root element in devtools and confirm the new utilities respond in both modes.
 
 ## tailwind-source-detection — HIGH · generated-artifact
 **Contract:** The generated stylesheet contains only class names that appear as complete, unbroken literal strings in scanned source files — the build-time scanner vs class names assembled at runtime; the default scan set skips `.gitignore`d paths and `node_modules`.
@@ -62,16 +62,16 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Ships green, breaks:** `bg-${color}-500` builds and renders unstyled — the utility is simply absent from the CSS. Class names stored in data or composed in unscanned code work only as long as some scanned file coincidentally contains the same literal — deleting that last literal usage breaks a "different" feature. Gitignored source directories are silently excluded from scanning.
 **Safe change:** Always write full class literals and select via lookup maps (`{primary: 'bg-blue-600'}[variant]`); safelist genuinely dynamic sets with `@source inline("…")` (v4.1+); add explicit `@source "…"` for out-of-tree or ignored directories.
 
-## dark-variant-data-attributes — HIGH · rendezvous-string
-**Contract:** `@custom-variant dark (&:where([data-theme=dark] *))` and the personality selectors `[data-theme="…"]`/`[data-style="…"]` rendezvous on the exact attribute name+value that runtime JS stamps on `<html>` (`document.documentElement.dataset.theme/style`).
-**Detect:** `@custom-variant dark`, `[data-theme=`, `[data-style=`, `dataset.theme`, `setAttribute('data-theme'`, `classList.add('dark')`
-**Ships green, breaks:** Without the `@custom-variant dark` override, Tailwind's default `dark:` variant is the `prefers-color-scheme: dark` media query — every `dark:` class silently follows the OS setting and ignores the app's toggle entirely. A value or mechanism mismatch (JS writes `class="dark"` while CSS expects `[data-theme=dark]`, or a casing typo) leaves the alternate theme unreachable with zero errors. Org default is light: base tokens must stay scoped `:root, :root[data-theme="light"]` or unstamped pages render the wrong theme.
-**Safe change:** Define attribute name and values as one exported constant consumed by the toggle code; add `@custom-variant dark` the moment any `dark:` utility pairs with an attribute toggle; flip the attribute in devtools and verify both directions plus the no-attribute default.
+## dark-variant-class — HIGH · rendezvous-string
+**Contract:** `@nurix/components` declares `@custom-variant dark (&:is(.dark *))` and ships its dark values compiled as `.dark { … }`; the app's toggle, its own `dark:` utilities and its token blocks (`:root.dark`) rendezvous on the exact class `dark` stamped on the root element (`document.documentElement.classList`).
+**Detect:** `@custom-variant dark`, `classList.add('dark')`/`classList.toggle('dark'`, `:root.dark`, `.dark {`, and the mismatch signals `[data-theme=`, `dataset.theme`, `setAttribute('data-theme'`
+**Ships green, breaks:** A toggle that stamps `data-theme="dark"` instead of the class renders half-flipped with zero errors: the app's own attribute-keyed tokens invert while every library surface — its `dark:` variants, its compiled `.dark { … }` values, its theme toggle and toaster — stays light, because the library's selectors are compiled into distributed CSS and cannot be re-keyed. Without `@custom-variant dark` in the CSS entry, the app's own `dark:` classes fall back to Tailwind's default `prefers-color-scheme: dark` media query and follow the OS setting instead of the toggle. Light is the org default: light values sit on `:root:not(.dark)`, so a page with no class renders light.
+**Safe change:** Toggle only the `dark` class on the root element, from a pre-paint inline script plus the persisted-preference module; bind `@custom-variant dark (&:is(.dark *))` in the CSS entry; flip the class in devtools and verify both directions, plus the no-class default, on an app surface and a library component side by side.
 
 ## nurix-components-styles-tokens — HIGH · rendezvous-string
-**Contract:** `@nurix/components` is imported by subpath (`@nurix/components/button`) but styled through two separate channels — its own pre-built `styles.css` (imported in `globals.css`) and the app's semantic CSS variables (personality tokens like `--radius-*`, `--color-*`) that its rules read.
-**Detect:** `from '@nurix/components/`, the library `styles.css` `@import` line in `globals.css`, grep `var(--` in `node_modules/@nurix/components/**/styles.css`
-**Ships green, breaks:** Omitting the `styles.css` import renders every component fully functional but unstyled — no JS error, no build warning, no missing-module failure. Renaming or dropping a personality token the library reads silently degrades components to fallback/`initial` values (e.g. a flat archetype's `--radius-*: 0` re-assertion lost in a token refactor). The library is pre-built, so the app's Tailwind scanner never generates utilities for markup inside it — its shipped CSS is the only style source.
+**Contract:** `@nurix/components` is imported by layered subpath (`@nurix/components/element/button`) but styled through two separate channels — its `styles.css` (CSS-`@import`ed in `globals.css`) and the CSS variables its rules read: the app's theme colors and `--radius`, the `--intent-*` family, and the personality layer (`--radius-scale`, `--density-*`, `--edge-*`, `--ring-*`, `--elevation-*`).
+**Detect:** `from '@nurix/components/`, the library `styles.css` `@import` line in `globals.css`, grep `var(--` in `node_modules/@nurix/components/dist/styles.css`
+**Ships green, breaks:** Omitting the `styles.css` import renders every component fully functional but unstyled — no JS error, no build warning, no missing-module failure. Renaming or dropping a token the library reads silently degrades components to fallback/`initial` values (e.g. a sharp-edge personality's `--radius-scale` override lost in a token refactor). The app's Tailwind compiles the library's utilities: `styles.css` omits `@import "tailwindcss"` and carries an `@source` over the compiled JS, so its classes resolve against the app's theme — a JS `import` of `styles.css` (in `main.tsx`) compiles it standalone with no theme loaded and fails the build.
 **Safe change:** Keep the `styles.css` import at its mandated position in `globals.css`; before touching any personality token, grep the library's dist CSS for `var(--that-token)`; smoke-render a themed library component after every `@nurix/components` upgrade.
 
 ## vite-alias-tsconfig-paths — MED · dual-authority
@@ -81,10 +81,10 @@ Load when: the touch list exhibits Redux Toolkit (`createSlice`, `configureStore
 **Safe change:** Single-source the mapping (`vite-tsconfig-paths`, or generate both from one constant); update both files in the same commit on any directory move; when suspicious, log `import.meta.url` from the module in dev to see which file actually loaded.
 
 ## css-import-order — MED · lifecycle-protocol
-**Contract:** `globals.css` must import in the fixed sequence `@import "./personality.css"` → `@import "tailwindcss"` → the library's `styles.css` → `@theme inline {…}` — cascade-layer order is fixed at first appearance of each `@layer` name, so file position *is* the styling contract between Tailwind, the component library, and the personality tokens.
-**Detect:** first ~10 lines of `globals.css`, `@import "tailwindcss"`, `@import` of `@nurix/components` styles, `@layer` declarations inside the library CSS
-**Ships green, breaks:** Any reorder compiles and mostly renders — the breakage is visual-only and theme/element-specific: importing the library's `styles.css` before `@import "tailwindcss"` lets preflight's `@layer base` resets land after (and wipe) library button/form styling at equal specificity, and flips which side wins app-utility-vs-library override wars. Nothing logs; a form-heavy screen just looks subtly wrong.
-**Safe change:** Treat the four-line header as frozen; insert new global stylesheets at a deliberate position relative to `tailwindcss` and the library import, never appended blindly; after any reorder, visual-diff a form-heavy screen in every `data-theme`/`data-style` combination.
+**Contract:** The CSS entry (`globals.css`, or whatever the manifest names) must import in the fixed sequence `@import "./fonts.css"` → the project's `design.tokens.css` → `@import "tailwindcss"` → the library's `styles.css` → the project's `personality.css` → `@theme inline {…}` — cascade-layer order is fixed at first appearance of each `@layer` name, and `personality.css` is bare `:root`/`.dark` blocks that only *tie* the library's unlayered `:root`/`.dark` (0,1,0), so it wins only by following `styles.css`. File position *is* the styling contract between Tailwind, the component library, and the personality tokens.
+**Detect:** first ~10 lines of the CSS entry, `@import "tailwindcss"`, `@import` of `@nurix/components` styles, the `personality.css` `@import`, `@layer` declarations inside the library CSS
+**Ships green, breaks:** Any reorder compiles and mostly renders — the breakage is visual-only and theme/element-specific: importing the library's `styles.css` before `@import "tailwindcss"` lets preflight's `@layer base` resets land after (and wipe) library button/form styling at equal specificity, and flips which side wins app-utility-vs-library override wars; importing `personality.css` before `styles.css` lets the library's neutral personality defaults win the tie, so the product's density, motion, radius and depth silently revert to neutral. Nothing logs; a form-heavy screen just looks subtly wrong. (`design.tokens.css` writes `:root:not(.dark)`/`:root.dark` at (0,2,0) and wins wherever it sits.)
+**Safe change:** Treat the header as frozen; insert new global stylesheets at a deliberate position relative to `tailwindcss` and the library import, never appended blindly; after any reorder, visual-diff a form-heavy screen in light and dark (`.dark`).
 
 ## date-fns-local-tz — HIGH · serialized-shape
 **Contract:** Datetimes cross the wire as UTC ISO strings or date-only `YYYY-MM-DD`, but date-fns `format()` and accessors operate in the runtime's local timezone — serializer and formatter must agree on the zone, and nothing checks that they do.

package/data/harnesses/code/skills/boundary/references/packs/generic-tail.md

@@ -1,6 +1,6 @@
 # Generic tail — technologies outside the mandated stack
 
-Load when: the touched code exhibits one of these technologies and no dedicated pack covers it. Entries here are deliberately thin — one gotcha and the safe-change essence each; diagnose the rest from the mechanism (see `../mechanisms.md`). When the org adopts one of these seriously, promote its section into a full pack.
+Load when: the touched code exhibits one of these technologies and no dedicated pack covers it. Each entry is one gotcha and the safe-change essence; diagnose the rest from its mechanism in `mechanisms.md`. A technology the org adopts seriously gets its section promoted into a full pack.
 
 ## API styles
 

package/data/harnesses/code/skills/brainstorm/README.md

@@ -12,8 +12,8 @@ commits it.
 
 ## The architecture — one capability, two seats
 
-Prose obligations decay in the conversing seat: the fleet audit behind v3 found the same rules
-dying in every real session, even the successful ones. So the capability is split:
+Prose obligations decay in the conversing seat: an audit of real sessions finds the same rules
+dying in every one, the successful ones included. So the capability is split:
 
 | Seat | Component | Owns |
 | --- | --- | --- |
@@ -27,17 +27,15 @@ line, the twin writes the result — so reconciliation is observable, never asse
 
 ## The session lifecycle
 
-```
-/brainstorm start
-  → basis gate (a document, an old session folder of any format, or a brain dump)
-  → bootstrap docs/research/{topic}-brainstorm/ (ops/ untracked; twin writes the surface)
-  → converse: dump / interview / probe / blindspot / converge — steerable in plain language
-  → "let me read" anytime: compose on demand, read the thesis, come back
-/brainstorm stop
-  → converge → manifest → ONE user approval → apply → uselessness test
-  → folder moves to docs/history/brainstorms/{topic}/ (the completion marker)
-  → the user decides: delete or commit
-```
+- **`/brainstorm start`**
+  1. Basis gate — a document, a prior session folder in any format, or a brain dump.
+  2. Bootstrap `docs/research/{topic}-brainstorm/` — `ops/` untracked; the twin writes the surface.
+  3. Converse — dump, interview, probe, blindspot, converge — steerable in plain language.
+  4. "Let me read" anytime — compose on demand, read the thesis, come back.
+- **`/brainstorm stop`**
+  1. Converge → manifest → **one** user approval → apply → uselessness test.
+  2. The folder moves to `docs/history/brainstorms/{topic}/` — the completion marker.
+  3. The user decides: delete or commit.
 
 The working surface: `thesis.md` (claim → argument → what changed, recomposed whole, stamped),
 `forks.md` (open questions with close conditions — the only convergence currency), `ledger.md`