@adia-ai/adia-ui-forge 0.8.53 → 0.8.55

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.55] — 2026-08-28
+
+### Changed
+- **`.codex-plugin/` regenerated for the release window** — `.codex-plugin/plugin.json`'s embedded `version` moves with the lockstep bump (derived from `.claude-plugin/plugin.json`, not an independent edit).
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.55 work shipped in button-ui flex-shrink:0 default fix (gh#2180/gh#2181). See `packages/web-components/CHANGELOG.md#0855--2026-08-28` for details.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
+## [0.8.54] — 2026-08-27
+
+### Fixed
+- **`package-release`'s cut pipeline was missing a post-bump regen step for both plugins' Hermes/Pi manifest tree — the same gap gh#1899 already closed for the Codex tree (discovered live during the v0.8.53 release PR #2138: it shipped stale `plugin.yaml`/`__init__.py`, caught by CI's `check:harness-manifests-fresh` and fixed by hand on the release branch).** `release-pack.mjs`'s Step 4 now runs `scripts/build/harness-manifests.mjs` after the version bump and verifies with `npm run check:harness-manifests-fresh` before continuing (`skills/package-release/scripts/release-pack.mjs`); Step 5's staging pathspec now carries both plugins' `plugin.yaml`, `__init__.py`, `prompts/*.md`, and (adia-ui-factory only) `hermes-mcp.yaml`, so the regen actually lands in the release commit instead of riding untracked. `selftest` extended to assert the new step and its staging pathspec.
+- **`patterns-index.md` (both `@adia-ai/mcp`'s `factory/resources/` copy and `adia-ui-factory`'s `skills/pattern-catalog/references/` copy) had no freshness gate at all — it went undetected-stale through the entire v0.8.53 cut, only regenerated as a side effect of an unrelated F-N1 CHANGELOG-coverage fix, never because a gate asserted it.** Added gate 33 (`npm run verify:patterns-index`) to the pre-flight roster, appended after gate 32 with the same numbering discipline as gates 30-32 (`skills/package-release/scripts/gate-roster.mjs`).
+
+### Docs
+- **`a2ui-maintenance/references/pipeline-overview.md`'s Critical Rule #5 stated a stale, now-superseded claim that A2UI never carries CSS — corrected per ADR-0022's 2026-08-24 amendment.** `UpdateStylesMessage`/`RemoveStylesMessage` are ratified protocol scope (a first-class CSS channel, not a carve-out); what still holds is narrower — compose/zettel LLM-synthesis itself never emits `updateStyles`, so the GENERATION-pipeline claim stays correct while the PROTOCOL-scope claim needed the fix. `skills/a2ui-maintenance/references/pipeline-overview.md`.
+- **`gen-ui-review/references/corpus-html-patterns.md` carried the same stale ADR-0022 claim as a secondary citation — corrected alongside the primary fix above.** `skills/gen-ui-review/references/corpus-html-patterns.md`.
+- **`primitive-authoring/references/yaml-contract.md`'s `category:` field documentation was missing ADR-0065's ratified 12-value canonical category vocabulary entirely (`action|agent|container|data|display|feedback|form|input|layout|navigation|shells|utility`) — added as a new passage, including the fold table for the 6 one-off drift values ADR-0065 retired.** `skills/primitive-authoring/references/yaml-contract.md`.
+- **`primitive-authoring/references/lifecycle-patterns.md`'s `slot="caret"` compliant-component list corrected twice this cycle, net result: `drilldown-ui` added.** ADR-0085 first added `drilldown-ui` to the exemption list (kept `slot="chevron"`); ADR-0092 then reversed that ruling (gh#1977 — migrate, don't exempt) and drilldown-ui's row chevron actually migrated to `slot="caret"` (see `@adia-ai/web-components`'s own 0.8.54 entry) — this file now lists `drilldown-ui` as compliant alongside `tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`, citing ADR-0036 + ADR-0092. `skills/primitive-authoring/references/lifecycle-patterns.md`.
+- **`primitive-authoring/references/module-promotion.md` was missing a second, distinct ADR-0012 correction: ADR-0015 (ADR-0087) reclassifies 6 nav elements from modules-tier to primitives-tier (consolidated to 3 — `nav-ui`/`nav-group-ui`/`nav-item-ui`) and retires 4 legacy element names — added near the file's existing, unrelated ADR-0012 citation so a future reader classifying nav elements doesn't land them in the wrong tier.** `skills/primitive-authoring/references/module-promotion.md`.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump only** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+
 ## [0.8.53] — 2026-08-26
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.53",
+  "version": "0.8.55",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-forge"
-version: "0.8.53"
+version: "0.8.55"
 description: "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin)."
 manifest_version: 1

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -105,6 +105,17 @@ for any constant or decision lives in git and PR descriptions
 5. **A2UI describes LAYOUT, not behavior.** Generation emits component trees +
    props + slot bindings; never JS or per-canvas CSS. Behavior delegates to
    traits or pre-built apps. "Make the generator emit JS/CSS" is a won't-fix.
+   **This is a GENERATION-pipeline claim, not the protocol's outer bound**
+   (ADR-0022 amendment, 2026-08-24): the protocol itself, as consumed by the
+   renderer and wire bridge, now carries a ratified CSS channel —
+   `UpdateStylesMessage`/`RemoveStylesMessage`
+   (`packages/gen-ui/a2ui/a2ui.schema.json:279-305`, renderer
+   `#updateStyles`/`#removeStyles` at `renderer.js:113-114,821-879`) — a
+   first-class part of the protocol, not a carve-out. What stays true
+   verbatim: compose/zettel synthesis itself still never emits
+   `updateStyles`, so this rule's generation claim is unchanged; only the
+   closed "the protocol never carries CSS at all" claim was falsified. JS
+   remains fully out of scope for both the protocol and generation.
 6. **Renderer guards `textContent` against container wipe** —
    `packages/gen-ui/a2ui/renderer.js` whitelists pure-text leaves
    (`TEXT_TAG_OK`); everything else routes through the `text=` attribute so

package/skills/gen-ui-review/references/corpus-html-patterns.md

@@ -70,7 +70,14 @@ HTML pages (apps/, catalog/, packages/web-modules/)      ← SoT
   primitives" fix plan.
 - A2UI describes **layout, not behavior** (ADR-0022): trees carry components +
   props + slot bindings only. Fix plans must never ask the generator to emit JS
-  or per-canvas CSS — that class of plan is won't-fix.
+  or per-canvas CSS — that class of plan is won't-fix. This is a
+  generation-pipeline claim, not a statement about the protocol's outer
+  bound: per ADR-0022's 2026-08-24 amendment, the protocol itself now
+  carries a ratified CSS channel (`UpdateStylesMessage`/`RemoveStylesMessage`,
+  consumed by the renderer and wire bridge) — compose/zettel synthesis still
+  never emits it, so a review fix plan asking the generator to produce CSS
+  is still won't-fix, but "the protocol never carries CSS" is no longer
+  accurate framing if a fix plan touches the renderer or wire-bridge layer.
 
 ---
 

package/skills/package-release/scripts/gate-roster.mjs

@@ -142,6 +142,16 @@ export const GATE_ROSTER = [
   // gate 31's Codex tree is — a stale copy is the same real install hazard.
   // Appended, not inserted — same numbering discipline as gate 30/31.
   { n: 32, cmd: 'npm run check:harness-manifests-fresh', what: 'Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT' },
+  // v0.8.53 retro: patterns-index.md (both @adia-ai/mcp's factory/resources/
+  // copy and adia-ui-factory's skills/pattern-catalog/references/ copy,
+  // consumed by the pattern-catalog skill and ui-architect) went undetected-
+  // stale through the whole v0.8.53 cut — it happened to be regenerated as
+  // a side effect of an unrelated F-N1 CHANGELOG-coverage fix, not because
+  // any gate asserted it. A stale index here is the same class of
+  // install/consumption hazard gates 31/32 close for the Codex/Hermes/Pi
+  // manifest trees. Appended, not inserted — same numbering discipline as
+  // gate 30/31/32.
+  { n: 33, cmd: 'npm run verify:patterns-index', what: 'pattern-index.md (mcp + adia-ui-factory) vs corpus source' },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/package-release/scripts/release-pack.mjs

@@ -440,11 +440,11 @@ function step1ReBaseline(args) {
 
 // ── Step 3 — Pre-flight gates (gh#2006) ───────────────────────────
 //
-// gh#1987's audit found the real "feels slow" lever isn't roster size (all
-// 32 gates are justified defense-in-depth — `main`'s branch protection only
+// gh#1987's audit found the real "feels slow" lever isn't roster size (every
+// gate is justified defense-in-depth — `main`'s branch protection only
 // hard-requires the browser-scheme probe, so the `npm run check` name-
 // duplicates in this roster are real re-checks, not dead weight) — it's
-// that step3PreFlight ran every gate one at a time. Most of the 32 are
+// that step3PreFlight ran every gate one at a time. Most gates are
 // independent, read-only checks with no shared mutable state; this splits
 // them into three phases instead of one flat serial for-loop. Two real
 // sequencing requirements survived the audit — everything else runs
@@ -852,6 +852,32 @@ function step4PromoteAndBump(args) {
     console.log('  ✓ Codex plugin manifests fresh after regeneration');
   }
 
+  // Step 4d.7 — regenerate the Hermes/Pi plugin manifests (gh#1954): both
+  // plugins' plugin.yaml + __init__.py embed `version` from
+  // .claude-plugin/plugin.json, which the bump above just moved — the exact
+  // same "derived artifact embeds the lockstep version" class as 4d.6's
+  // Codex tree. Gate 32 (check:harness-manifests-fresh) runs pre-bump in
+  // Step 3, so it only proves freshness against the PREVIOUS version;
+  // without this step nothing re-ran the generator after the bump — the
+  // v0.8.53 release PR (#2138) shipped stale manifests as a result (Static
+  // checks + MCP smoke failed on check:harness-manifests-fresh, fixed by
+  // hand on the release branch — the doc at cut-procedure.md's step 4d.7
+  // described this step for two cuts before the script actually ran it).
+  // Step 5 stages both plugins' plugin.yaml + __init__.py, factory's
+  // hermes-mcp.yaml, and prompts/*.md.
+  console.log('\n  Step 4d.7 — regenerate Hermes/Pi plugin manifests (version embeds the lockstep bump):');
+  sh('node scripts/build/harness-manifests.mjs', args);
+  if (args.dry) {
+    console.log('  [dry] npm run check:harness-manifests-fresh (post-regen proof)');
+  } else if (!shOk('npm run check:harness-manifests-fresh')) {
+    console.error('\nERROR: Hermes/Pi plugin manifests still stale after regeneration — harness-manifests.mjs');
+    console.error('       did not produce output matching check:harness-manifests-fresh\'s expectations.');
+    console.error('       Run both by hand to diagnose before re-running the cut.');
+    process.exit(1);
+  } else {
+    console.log('  ✓ Hermes/Pi plugin manifests fresh after regeneration');
+  }
+
   // Step 4e — generate docs/ops/releases/vX.Y.Z.md (gh#399: neither this step nor
   // its staging into the release commit existed before — check-cut-hygiene's
   // "notes present" claim (Step 4g, below) went unverified until
@@ -982,8 +1008,14 @@ function step5Commit(args) {
         // and the per-skill count isn't statically knowable (same shape as
         // the chunk-corpus directory pathspec above).
         files.push(`${dir}/.codex-plugin/plugin.json`, `${dir}/skills/*/agents/openai.yaml`);
+        // gh#1954: Step 4d.7 regenerates both plugins' Hermes/Pi manifest
+        // tree post-bump, the same class of drift 4d.6's Codex tree fixes
+        // above — stage it here or CI catches it the way v0.8.53's release
+        // PR (#2138) did. `prompts/*.md` is a glob for the same reason the
+        // Codex `agents/openai.yaml` glob above is.
+        files.push(`${dir}/plugin.yaml`, `${dir}/__init__.py`, `${dir}/prompts/*.md`);
       }
-      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`);
+      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`);
       return files;
     }),
   ];
@@ -1415,6 +1447,21 @@ function selftest() {
       'packages/plugins/adia-ui-forge/skills/*/agents/openai.yaml',
       'packages/plugins/adia-ui-factory/.codex-plugin/plugin.json',
       'packages/plugins/adia-ui-factory/skills/*/agents/openai.yaml',
+      // gh#2138 — Step 4 must regenerate the Hermes/Pi plugin manifests
+      // post-bump too, the same class of gap as gh#1899 above (the v0.8.53
+      // release PR #2138 shipped stale ones without this step).
+      'Step 4d.7 — regenerate Hermes/Pi plugin manifests',
+      '[dry] node scripts/build/harness-manifests.mjs',
+      // gh#2138 — Step 5's staging pathspec must carry both plugins'
+      // Hermes/Pi manifest tree, or it rides untracked/uncommitted past the
+      // release commit the same way the Codex tree did before gh#1899.
+      'packages/plugins/adia-ui-forge/plugin.yaml',
+      'packages/plugins/adia-ui-forge/__init__.py',
+      'packages/plugins/adia-ui-forge/prompts/*.md',
+      'packages/plugins/adia-ui-factory/plugin.yaml',
+      'packages/plugins/adia-ui-factory/__init__.py',
+      'packages/plugins/adia-ui-factory/hermes-mcp.yaml',
+      'packages/plugins/adia-ui-factory/prompts/*.md',
     ];
     for (const marker of need) {
       if (!out.includes(marker)) {

package/skills/primitive-authoring/references/lifecycle-patterns.md

@@ -320,13 +320,14 @@ The failure this prevents: a `render()` that overwrites `textContent` from the a
 
 ### `slot="caret"` — the one disclosure-indicator slot
 
-The expand/collapse (and dropdown) directional-indicator slot is named `caret` on every primitive that exposes composition slots (`tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`). `chevron` is retired — a hard rename with no compat alias, and `--*-chevron-*` tokens became `--*-caret-*` (Phosphor names the glyphs `caret-right` / `caret-down`; there is no `chevron-*` icon).
+The expand/collapse (and dropdown) directional-indicator slot is named `caret` on every primitive that exposes composition slots (`tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`, `drilldown-ui`). `chevron` is retired — a hard rename with no compat alias, and `--*-chevron-*` tokens became `--*-caret-*` (Phosphor names the glyphs `caret-right` / `caret-down`; there is no `chevron-*` icon).
 
 - The mechanism is adopt-or-stamp (above): honor a declarative `<… slot="caret">` child if present, else stamp `<icon-ui slot="caret" name="caret-right">`. The same adopt-or-stamp rule applies to **every** composition slot the stamp builds (e.g. `slot="actions"`).
 - Rotation is driven by host open-state CSS (`:scope[open]` / `[collapsed]` / `[expanded]`) — never by swapping the icon name.
 - Internal-render components with no composition slots (`agent-trace`, `agent-reasoning`) keep `[data-*-caret]` styling hooks — the convention governs slots, not internal hooks.
 
-Source: ADR-0036.
+Source: ADR-0036, ADR-0092 (`drilldown-ui`'s row-level caret migrated from `slot="chevron"`,
+retained under ADR-0085, to `slot="caret"`, reversing that exemption).
 
 ## Anti-patterns to watch for
 

package/skills/primitive-authoring/references/module-promotion.md

@@ -178,6 +178,8 @@ Either ship as a standalone lockstep cut (per the sibling **package-release** sk
 
 **ADR prose drift — don't trust an ADR's "Today's work" narrative for live paths.** ADR-0012 is the source for the primitives-vs-modules-vs-themes decision above, but its own "Today's work"/outcome-notes prose has drifted out from under its ratified Decision: that prose describes `packages/web-components/patterns/` as the shell/chat/editor/runtime source-clustering directory, but present-day `patterns/` holds 45+ usage-example dirs instead — source moved on to `packages/web-modules/{chat,editor,runtime,shell}/` per the later ADR-0015. The same drift claims `@adia-ai/web-themes` as a sibling workspace package; it never shipped that way — themes live under `packages/web-modules/theme/` as a subpath instead. An ADR's ratified **Decision** stays append-only-safe; its **"Today's work" / outcome-notes prose is not** — later reorganizations can strand it, and a reader following the literal directory claims today would git-mv into the wrong (docs-example) directory. Before executing a cluster-placement call cited from an ADR, verify the directory it names still matches the live tree (see "Path-rebase awareness" below) rather than trusting the ADR's narrative section verbatim.
 
+**A second, distinct ADR-0012 correction — the nav family's tier, and 4 retired element names (ADR-0087, partial supersession).** ADR-0012's "Today's work" cluster table and "What lives where today" table classified 6 nav elements (`<app-nav-ui>`, `<app-nav-group-ui>`, `<app-nav-item-ui>`, `<section-nav-ui>`, `<section-nav-group-ui>`, `<section-nav-item-ui>`) as modules-tier, living in `web-modules/shell/`. ADR-0015 corrected this same-day as "a misclassification ADR-0012 inherited from the patterns/ era": the nav family is primitives-tier, consolidated to 3 elements (`<nav-ui>`, `<nav-group-ui>`, `<nav-item-ui>`) in `web-components/components/`. Using ADR-0012's tables to classify a new nav-family element via the OD-001 decision table above would land it in modules-tier — wrong; nav elements are primitives per ADR-0015. ADR-0012's tables also named 4 element names since retired per ADR-0015's rename map: `<adia-chat-ui>` → `<chat-shell>`, `<adia-editor-ui>` → `<editor-shell>`, `<app-shell-ui>` → `<admin-shell>`, `<gen-ui>` → `<gen-root>`. ADR-0087 records this partial supersession formally (`supersedes: adr-0012`, scoped to these two tables only — the three-tier package model, the lateral-dependency rule, and the cluster boundaries all stand unchanged). Live authority: ADR-0015 itself, not ADR-0012's tables.
+
 ## Two rules from observed bugs
 
 ### OD-002 — Absorb the standalone-button-next-door

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

@@ -171,6 +171,19 @@ have no v1.0 sidecar.
 
 **Ratified, closed enum — compiler-enforced at build time, mirrored in the schema (ADR-0065).** These twelve values are the whole vocabulary; the census that ratified them found 18 free-form values in live use (typos like `forms`/`data-display`, one-off singletons, and three named misclassifications) — all folded or corrected onto this set as part of the same change. Enforcement: `scripts/build/components.mjs` holds `CATEGORY_VALUES` and `compileComponent()` throws on a MISSING `category:` field (unlike `status:`, `category:` is required, not defaulted) as well as on any out-of-enum value, the same place and severity as the `status:` check above — so `npm run verify:components` hard-fails an invalid OR absent category. `scripts/schemas/component.yaml.schema.json`'s `category` enum mirrors this list for the `$schema:` IDE contract; the hand-synced constant in `components.mjs` is the live gate, same relationship as `status`. Source: ADR-0065.
 
+**The six one-off drift values ADR-0065 folded**, each independently justified by what the component does, not a blanket rule:
+
+| Drift value | Folds to | Example |
+| --- | --- | --- |
+| `forms` | `form` | `toggle-option.yaml` — spelling drift against `form`'s existing members. |
+| `data-display` | `data` | `heatmap.yaml` — joins `tree.yaml`/`tree-item.yaml`, same spelling drift shape. |
+| `content` | `display` | `link.yaml` — inline content rendering, same role as `text-ui`/`code-ui`. |
+| `typography` | `display` | `mark.yaml` — a text-highlight element, same role as `text-ui`. |
+| `control` | `action` | `toggle-scheme.yaml` — a click-to-fire toggle, same shape as `button-ui`. |
+| `interaction` | `container` | `admin-command.yaml` — a command-palette surface, same role as `command-ui`. |
+
+Three named misclassifications were also fixed, not folded: `check.yaml`/`switch.yaml`/`textarea.yaml` (`layout` → `input` — bindable form controls, not structural primitives), `tabs.yaml` (`container` → `navigation`, unifying with `tab.yaml`), and `feed.yaml` (`container` → `feedback`, unifying with `feed-item.yaml`). Full rationale and the progress-family partial unification: ADR-0065 Decision §2–§4.
+
 **A sibling family (a wrapper + its child items, e.g. `tabs-ui`/`tab-ui`) is not required to share one category by default** — `menu-ui` (`container`) + `menu-item-ui` (`navigation`) is a deliberate, working split. Where a family's sibling values disagreed with no evident rationale, ADR-0065 unified them; new families should pick per-component, not assume unification is required.
 
 **Sidecar emission**: `x-adiaui.category` field in `<name>.a2ui.json`. `packages/gen-ui/engine/retrieval/catalog.js`'s `buildCatalog()` reads this directly per entry — no separate registration step.