@adia-ai/adia-ui-forge 0.8.41 → 0.8.42

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.41",
+  "version": "0.8.42",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.42] — 2026-08-17
+
+### Maintenance
+- Knowledge packs harvest the ADR-0061..0070 ratifications (PR #1564: gen-ui-wiring + wave-coordination corpora); rename-wave W2 doc migration (PR #1567).
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (7 file(s), e.g. `a2ui-maintenance/SKILL.md`) — carried by the entries above.
+
 ## [0.8.41] — 2026-08-17
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.41",
+  "version": "0.8.42",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/a2ui-maintenance/SKILL.md

@@ -41,6 +41,22 @@ surface `catalogId` → error, no registry default). The producer's
 dialect-shaped; the bridge owns the translation — never hand-write Candidate
 envelopes from this skill's surfaces.
 
+site-a2ui (the build-time HTML→A2UI docs-site transpile) is RULED fit as the
+**dialect side's regression corpus**, not a v1.0 conformance bed (ADR-0068):
+it exercises the dialect renderer, the ADR-0061 lifecycle path, and the
+engine transpiler at real-content scale in production, but never touches the
+producer, the bridge, or the `wireFormat` flag — so it neither blocks the
+v1.0 migration nor gets re-pointed at the v1 wire. **Named expiry:** that
+ruling is load-bearing on `wireFormat` defaulting to `'dialect'`; the flag-flip
+ADR that makes `'v1'` the shipping default MUST re-rule site-a2ui's fitness
+(re-point vs retirement-by-attrition) — the fitness verdict expires with the
+`'dialect'` default. Expanding site-a2ui — new message kinds, new consumers,
+or a promotion PROGRAM toward all routes — also invalidates the ruling's
+basis and needs a new decision; burn-down of existing
+`visual-drift`/`blocked-format-gap` rows (including a route thereby becoming
+parity-promoted) is ordinary maintenance and stays permitted (ADR-0068
+Decision 5).
+
 ## Route by task shape
 
 | Task shape | Load |
@@ -55,6 +71,7 @@ envelopes from this skill's surfaces.
 | Add or change an MCP tool | [mcp-tool-reference](references/mcp-tool-reference.md) |
 | Tune the anti-pattern catalogue | [anti-patterns](references/anti-patterns.md) |
 | A component's contract can't express a content shape — decide how to extend it | [format-extension-decisions](references/format-extension-decisions.md) |
+| Surface regeneration, pending/stale rendering, the `doc`-setter replace bracket | [surface-lifecycle](references/surface-lifecycle.md) (ADR-0061) |
 
 Unmatched work defaults to pipeline-overview and re-classifies from there.
 

package/skills/a2ui-maintenance/references/surface-lifecycle.md

@@ -0,0 +1,73 @@
+# Surface lifecycle — the runtime pending/stale contract (ADR-0061)
+
+The renderer runtime (`packages/gen-ui/a2ui/`) owns a per-surface lifecycle
+state machine, ratified by ADR-0061
+(`docs/ops/adr/adr-0061-surface-lifecycle-pending-stale.md`; requirements and
+build order in `docs/ops/spec/spec-a2ui-surface-lifecycle.md`). Load this file
+when a change touches surface regeneration, `<a2ui-root>`'s `doc` setter,
+pending/stale rendering, or a host's update bracketing.
+
+## The state machine
+
+```text
+empty → pending-first → live → pending-stale → live
+              └→ error-empty         └→ error-stale
+                  (both error-* heal on the next successful commit)
+```
+
+- **Pending is per-surface, never global.** Each renderer surface record
+  carries its own machine; one surface regenerating never dims another.
+- **Latest-generation-wins arbitration.** When two update brackets race on
+  one surface, the newest generation's commit wins; a superseded bracket's
+  messages are discarded, not interleaved.
+- **Stale content stays visible.** In `pending-stale` and `error-stale` the
+  previous answer keeps rendering — the blank-flash reset+replay shape is
+  what this contract retired. Error state heals: the next successful commit
+  clears `error-*`.
+
+## The host API
+
+Four public runtime methods drive the machine — `beginSurfaceUpdate` /
+`applyTo` / `commitSurfaceUpdate` / `abortSurfaceUpdate`. Messages arriving
+inside a bracket buffer and apply atomically at commit. A `replace`-mode
+commit sweeps components the new answer no longer declares — the ONLY place
+removal semantics exist; outside a bracket, `updateComponents` upserts
+exactly as before, so unbracketed streams and hosts are behavior-identical
+to the pre-lifecycle runtime (strictly additive, ADR-0061 Decision 4).
+`<a2ui-root>`'s `doc` setter routes through this replace bracket
+(`replaceDoc`) rather than reset+replay — a deliberate, ratified behavior
+change for doc-setting hosts (ADR-0061 OD-2).
+
+## The DOM contract
+
+Staleness is exposed as one attribute plus three events, never styling:
+
+- **`data-a2ui-lifecycle`** — a single enum attribute on the surface root
+  reflecting the current state. This is the `data-a2ui-*` prefix's FIRST
+  ratification (the pre-existing `data-a2ui-surface` stamp was accidental,
+  now ratified alongside it) — the runtime-owned `data-*` tier, sibling to
+  ADR-0060's trait tier.
+- **Three bubbling CustomEvents** mark the transitions.
+- Hosts and primitives style off the attribute with semantic tokens: stale
+  content dims; skeletons (the existing `skeleton` primitive) appear only in
+  `pending-first`. `@adia-ai/a2ui` ships state, never styling, and stays
+  zero-dependency.
+
+## Layer boundary (ADR-0059)
+
+The lifecycle is renderer-runtime work on gen-ui-kit's side of the ADR-0059
+line. The three wire envelope kinds (`beginSurfaceUpdate` /
+`commitSurfaceUpdate` / `abortSurfaceUpdate` as v1.0 server kinds) are a
+genui-system standard PROPOSAL, not dialect schema — `a2ui.schema.json`
+gains nothing, the dialect wire format is byte-identical, and stream-driven
+regeneration waits on the upstream standard (the dialect escape hatch was
+explicitly denied at ratification). Never hand-write lifecycle envelopes
+from this skill's surfaces; the Bridge owns the mapping when the standard
+lands.
+
+## Interlock worth knowing
+
+The v1.0 conformance program's duplicate-`surfaceId` error (REQ-002)
+sequences AFTER this API — the silent `createSurface` no-op it removes was
+previously the only wire-visible re-target path, and the lifecycle bracket
+is its sanctioned replacement.

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -21,7 +21,7 @@ the live admin-dashboard example.
    a bare `<nav-ui>` direct child overflows long lists
 5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
    (user menu) — ★ commonly missing
-6. Sidebar `<div data-resize></div>` — REQUIRED when `resizable` is on
+6. Sidebar `<div data-sidebar-resize></div>` — REQUIRED when `resizable` is on
 7. `<admin-content>` inner `<admin-topbar>` containing
    `<button-ui data-sidebar-toggle="leading" icon="sidebar">` +
    `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>` —

package/skills/primitive-authoring/references/svg-authoring.md

@@ -234,29 +234,34 @@ correctness rather than just aesthetics), set `shape-rendering: crispEdges`
 explicitly** — the browser default (`auto`, effectively anti-aliased) is
 correct for everything else and should stay the default.
 
-## 8. Attribute-shadowing on SVG-adjacent primitives (ADR-0053/0054)
+## 8. Attribute-shadowing on SVG-adjacent primitives (ADR-0053/0054/0070)
 
-Two of the pre-existing global-attribute-grammar collisions gh#1335 surfaced
-are specifically SVG-rendered primitives, and both cite the SVG-specific
-reasoning for their proposed resolution rather than the generic
-rename/converge path:
+Two of the global-attribute-grammar collisions gh#1335 surfaced are
+specifically SVG-rendered primitives; both exemptions are **GRANTED**
+(ADR-0070, ratified 2026-08-17), closing the last 2 of gh#1335's 17 and
+emptying `check-attribute-shadowing.mjs`'s `KNOWN_FINDINGS` — the gate now
+enforces via `attribute-api-system.md`'s ratified §11 table alone:
 
 - **`qr-code-ui[color]`** — a free-form CSS color string (drives the raw
   `fill` baked into the generated matrix SVG, §5 above), structurally
-  identical to the already-ratified `swatch-ui`/`noodles-ui[color]` §11
-  exemptions ("the component's entire subject is a color") — proposed for
-  the same exemption rather than a rename.
-- **`icon-ui[weight]`** — Phosphor's icon-rendering weight vocabulary
+  identical to the ratified `swatch-ui`/`noodles-ui[color]` §11 exemptions
+  ("the component's entire subject is a color"). The exemption covers the
+  free-form value space AND the hardcoded `#000000` scanability fallback
+  (deliberately never theme-derived — light-on-dark won't scan), plus its
+  contract pairing with `[background]`.
+- **`icon-ui[weight]`** — Phosphor's own glyph-variant vocabulary
   (`thin/light/regular/bold/fill/duotone`, selecting which pre-rendered SVG
-  asset variant `getIcon()` loads) is a DIFFERENT CONCEPT from CSS
-  `font-weight` (`thin/light/normal/medium/semibold/bold`) despite the
-  shared attribute name — gh#1335 names it "the strongest candidate for a
-  ratified §11 exemption rather than a rename," the same reasoning as
-  `swatch-ui[color]`.
-
-Neither is resolved yet (both remain in `check-attribute-shadowing.mjs`'s
-`KNOWN_FINDINGS` list per gh#1335) — cite this section, not a fresh
-investigation, if either surfaces again in a yaml audit.
+  set `getIcon()` loads) is a DIFFERENT CONCEPT from CSS `font-weight`
+  despite the shared name; the global utility's `font-weight` is inert on
+  the inline SVG, so the collision has no cascade effect.
+
+Known residual (documented in the §11 justification, accepted not fixed):
+global-only `weight` values (`normal|medium|semibold`) select no Phosphor
+set and fall back to `regular`; a semantic-enum value on `qr-code-ui[color]`
+(`color="danger"`) passes to the SVG fill verbatim, unresolved through
+tokens. Cite this section — ADR-0070 — not a fresh investigation, if either
+attribute surfaces again in a yaml audit; the next colliding
+`color`/`weight` on any OTHER component still needs its own ADR.
 
 ## When to load this file
 

package/skills/primitive-authoring/references/token-contract.md

@@ -138,7 +138,52 @@ mechanics; never work from this summary alone):
   the global name always means the global thing. Before minting any attribute
   in a component yaml, check it against the spec's attribute inventory; the
   only sanctioned collisions live in the spec's §11 Global-Attribute Exemption
-  List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054).
+  List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054;
+  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
+
+Beyond the global grammar, ADR-0063
+(`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies six
+CROSS-SIBLING conventions for component-local attribute naming — the axis
+ADR-0053/0054 don't cover. Any new attribute follows these:
+
+- **`no-*` is the canonical negation prefix** — `hide-*` retires
+  (`chart[hideAverage|hideGrid|hideValues]` → `no*`, `stream[hide-cursor]`
+  → `[no-cursor]`).
+- **Interactivity is opt-in by a positively-named boolean, default `false`**
+  (the `stepper-item[interactive]` / `swatch[selectable]` shape) — never
+  opt-out. `chart-legend[static]` retires to `[interactive]` (inverted
+  default). Applies to single-purpose toggles only — `noodles`'s
+  `editable`/`readonly` pair is two orthogonal booleans and stays.
+- **Two sanctioned multi-value encodings, never a hand-rolled delimited
+  string:** (a) `multiple` boolean + a structured option model (`select`'s
+  `options`/`<option>` shape); (b) a native array-typed JS property,
+  JSON-serialized for attribute/form participation (`tags-input`'s
+  `.value`). One explicit, operator-ratified EXCEPTION for existing
+  components (recorded on gh#1563, 2026-08-17): `segmented-ui[multiple]`'s
+  comma-separated value IS accepted as the sanctioned multiple+options
+  encoding, and toggle-group's comma-string resolves under that same ruling
+  rather than being re-ticketed. This is a ruling on those two existing
+  components, not a loophole — a NEW component's multi-value attribute still
+  uses form (a) or (b) above, never a delimited string, unless a separate
+  ruling says otherwise.
+- **Cross-sibling naming convergence:** `pane[side]` → `pane[edge]`
+  (drawer keeps physical `side`); `menu-item[subtitle]` →
+  `menu-item[description]` (the ~20-component majority word); `placement`
+  ratified as-is for anchored popovers. Documented exception:
+  `input[maxlength]` — a primitive wrapping a genuine native `<input>`
+  keeps the native attribute's exact casing (ADR-0025/0055 conformance);
+  new non-native length constraints use the framework's
+  camelCase-property/kebab-attribute pair.
+- **`completed` is the stage-terminal word** for a `status` lifecycle enum
+  (`agent-reasoning[status]`'s `done` converges).
+- **`-picker` is reserved for the outer trigger+popover form-associated
+  composite** — never the inline substrate it composes. `color-picker-ui`
+  (the inline substrate) renames to `color-area-ui`.
+
+The renames above are follow-on BUILD work tracked as gh#1563, not yet
+landed in code (compat shims in 0.8.42; breaking cut rides 0.9.0) — when a
+yaml still shows an old name, the ADR is ratified and the code is behind,
+not the other way around.
 
 ## When to update this reference
 

package/skills/primitive-authoring/references/yaml-contract.md

@@ -177,6 +177,79 @@ have no v1.0 sidecar.
 
 ---
 
+## Semantic color-family axis — two role-classes, two names (ADR-0044, ADR-0064)
+
+Every component carries at most one STYLE axis and one FAMILY axis (the
+semantic color family: `default | info | success | warning | danger`,
+`+primary` where the role-class already carries brand emphasis), and every
+enum value belongs to exactly one axis. The family axis's ATTRIBUTE NAME is
+decided by role-class — never one universal name (a same-name meaning-flip
+is a silent-failure migration and poisons the trained corpus, per ADR-0044
+LLD §3):
+
+- **Role-class A — `variant` is unclaimed:** the family axis is named
+  `variant`. Badge/tag's ratified shape (ADR-0044), plus `rating-ui` and the
+  `variant`-only siblings (inline-message, feed-item, empty-state, menu-item,
+  progress-row).
+- **Role-class B — an existing identity/style axis already claims the
+  selector slot:** the family axis is named `color`. Button's shape
+  (`variant`=style, `color`=family), extended by ADR-0064 to `text-ui`
+  (`variant`=typography role), `chart-ui`/`heatmap-ui` (`type`=kind),
+  `icon-ui` (`weight`=glyph style), `spinner-ui` (`variant`=animation), and
+  `toggle-scheme-ui`. Renames owed by this ruling (follow-on build, gh#1376
+  — not yet landed): `icon-ui[tone]` → `[color]`, `heatmap-ui[colorScheme]`
+  → `[color]`, `spinner-ui[tone]` → `[color]`.
+
+`accent` is RETIRED from the family enum everywhere — ADR-0044 removed it
+from badge/tag/button; ADR-0064 removes it from the seven stragglers
+(text, chart, icon, heatmap, rating, spinner, toggle-scheme) with no
+replacement value. Never mint `accent` in a new enum.
+
+Two ratified non-family exceptions — the name without the semantics:
+
+- `swatch-ui[color]` / `noodles-ui[color]` — an arbitrary CSS color string,
+  not a semantic enum (ADR-0054 §11 exemption, unchanged).
+- `spinner-ui[color]` (post-rename) — a closed contrast-mode enum
+  (`current | subtle | inverse`), NOT the family vocabulary; never assume it
+  accepts `info`/`success`/`warning`/`danger` by analogy.
+
+---
+
+## Catalog tiers — L0–L4, `origin`, and the promotion rule (ADR-0050, ADR-0066)
+
+ADR-0050's L0–L4 ladder is the ONLY tier grammar — never mint a second
+manifest format. ADR-0066 refines it three ways:
+
+- **`origin: primitive | module` on every L0 entry** — both YAML source
+  roots (web-components primitives AND web-modules composites) compile into
+  the same `catalog-a2ui_0_9.json` through one shared contract;
+  `derive-catalog-tiers.mjs` stamps which root an entry came from onto
+  `tier-index.json`. A module is legitimately a member of TWO rungs at two
+  grains: its component API (props/events/slots) is L0, its assembled shell
+  composition is L3 — ruled correct, not a modeling defect.
+- **The promotion rule, stated once:** patterns/zettel compositions are the
+  SOLE promotion source, and they enter the ladder at exactly one point —
+  pattern → L1 widget, through `curate-l1-widgets.mjs`'s gates (which writes
+  only `l1-widgets.json`). The higher rungs (L1 → L2 → L3 → L4) are AUTHORED
+  edges — hand-written `tiers/l*-*.json` manifests whose `composes` reference
+  the rung below, reserved/unblocked per ADR-0050's own phasing; a module's
+  L3 membership comes from an authored L3 manifest, never from its yaml
+  (which contributes only the L0 entry + `origin`). There is no
+  patterns↔module edge, primitives and modules never "promote" into each
+  other, and nothing promotes automatically or in reverse — curation is the
+  one-way valve (ADR-0050: "corpus derives from catalogs, never the
+  reverse").
+- **The two pattern-facing outputs stay separate by design:**
+  `site/patterns-index.json` / `pattern-index.md` are a generated,
+  developer-facing index over the FULL pattern/template census, intentionally
+  independent of the L0–L4 machine-validated schema — a different audience,
+  never a convergence gap to "fix".
+
+(`status:` above is orthogonal to the tier ladder — tier = what an entry is
+composed of; status = how much to trust its contract today.)
+
+---
+
 ## `props:` field — prop schemas
 
 Each prop is a top-level key inside `props:`. The full prop schema:
@@ -266,7 +339,7 @@ string-list schema is the exact silent-mismatch shape.
 | --- | --- | --- |
 | `[data-col]` | `display: flex; flex-direction: column; gap: var(--page-grid-gap)` | column layout helper |
 | `[data-row]` | `display: flex; align-items: center; gap: var(--page-grid-gap)` | row layout helper |
-| `[data-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-grid="3"`) | 2- or 3-col grid helper |
+| `[data-layout-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-layout-grid="3"`) | 2- or 3-col grid helper |
 | `[data-actions]` | `display: flex; align-items: center; gap: var(--page-actions-gap)` | action button cluster |
 | `[data-spacer]` | `flex: 1` | flex spacer for pushing content to edges |
 

package/skills/site-deployment/references/deploy-playbooks.md

@@ -139,10 +139,18 @@ itself is unavailable.
    - **`build:site` copies packages but does NOT rebuild their dist bundles** — after
      component `.css`/`.js` source changes, rebuild first (`npm run build -w
      @adia-ai/llm`, then `npm run build:bundles`) or the deployed bundles are stale.
-   - **`scripts/build/site.mjs` is per-package (`copyX()` functions), not glob-based** —
-     every new or renamed package needs its own copy fn or `dist/` silently omits it
-     (local Vite works, prod 404s; caused the v0.3.0 `@adia-ai/llm` + `a2ui-runtime`
-     deploy gaps). After any package add/rename, check `site.mjs` before deploying.
+   - **Package registration is one manifest, `scripts/build/site-package-registry.mjs`
+     (ADR-0062)** — every `@adia-ai/*` package the site ships is one registry entry, from
+     which the dist copy, BOTH importmaps (one shared `renderImportMapBlock()` — the
+     `site/index.html` copy is a generated artifact, `npm run build:site-importmap`),
+     the `dist/node_modules` symlinks, and the CI build order all derive. The old
+     failure class (per-package `copyX()` hand-edits; local Vite works, prod 404s —
+     v0.3.0 llm/a2ui-runtime, v0.8.27 persona+agent) is gated mechanically:
+     `check:site-packages-registered` scans every shipped source root for an
+     unregistered bare `@adia-ai/*` import and fails naming file:line, alongside
+     `check:site-importmap-fresh` and `check:deploy-workflow-build-order` — all three
+     in `npm run check` and early in `deploy-site.yml`. After any package add/rename,
+     add the registry entry; the gates say the rest.
 2. **Dry-run first, and adjudicate every delete — BEFORE the real rsync, never after:**
    ```sh
    rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/' \