@adia-ai/adia-ui-forge 0.8.54 → 0.8.56

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.54",
+  "version": "0.8.56",
   "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.54",
+  "version": "0.8.56",
   "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,38 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.56] — 2026-08-31
+
+### Added
+- **New `component-md-authoring` skill (gh#2615).** Authors the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — typed directly into the yaml's new `screenReader:`/`behavioral:` fields (component.md itself is a generated shell, never hand-edited). Sits next to `primitive-authoring` in `packages/plugins/adia-ui-forge/skills/`; Codex (`agents/openai.yaml`) and Hermes/Pi (`__init__.py`) manifests regenerated to register it.
+- **`primitive-authoring`'s `yaml-contract.md` gains a semantic-id grammar for `examples[].a2ui` component ids (gh#2492 Phase 1).** The `.claude/docs/specs/a2ui-editor.md:170` "free-form" id convention was written for editor-generated ids only, not authored yaml examples — reading it as license for both produced a corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`) reported against `blockquote.yaml`, `badge.yaml`, `aside.yaml`, `alert.yaml`, and `anchor-bar.yaml`. New `## examples: field` section documents the grammar (kebab-case, role-descriptive, unique per example, a short-real-word root/wrapper exception) with before/after examples; `a2ui-editor.md:170` amended to scope its own claim to editor-generated ids and cross-reference the new grammar. Phase 2 (a separate dispatch) sweeps the corpus to match.
+- **Phase 2 (gh#2492): the corpus-wide sweep landed and `check-example-ids.mjs` flips from advisory to `npm run check:example-ids:strict` in the `npm run check` chain.** 526 violations across 48 yamls (`packages/web-components`, `packages/web-modules`) renamed to the Phase 1 grammar — see `packages/web-components/CHANGELOG.md` and `packages/web-modules/CHANGELOG.md` for the file list. `yaml-contract.md`'s `## examples: field` section updated to describe the gate as enforced, plus a noted known gap (the checker's positional regex doesn't catch a `letter-digit-letter-digit` chain like `g1i1`, out of scope for this sweep since nothing flagged it). `check-example-ids.mjs` itself gained an entrypoint guard (`if (import.meta.url === ...)`) — the CLI's `main()` was running as a side effect of importing `checkExampleIds` as a library function, which the sweep tooling does.
+
+### Fixed
+- **`package-release`'s Step 5 staging allowlist was missing the factory README's own prose echo of the generation-MCP pin — bump.mjs's `A2UI_MCP_PIN` rewrites both `adia-ui-factory/.mcp.json` and its README, but Step 5 only ever staged `.mcp.json`, so the README edit rode uncommitted through every cut (gh#2473).** `release-pack.mjs`'s Step 5 now also stages `packages/plugins/adia-ui-factory/README.md`. Added a new Step 5.6 unstaged-tracked-files guard right after staging (numbered 5.6, not 5.5 — `cut-procedure.md`'s own §Step 5.5 already names a different, pre-existing manual freshness trip-wire): it fails the cut loudly if any tracked file bump.mjs or a cut-hygiene step touched is still modified-in-the-worktree after Step 5's allowlist ran, so the next allowlist gap is caught at cut time instead of discovered by hand later. `selftest` extended with a direct unit test of the new `unstagedTrackedLeftovers()` parser (plain modifies/deletes, staged-only and untracked exclusions, C-quoted paths, rename/copy new-side reporting) plus a marker asserting the guard's `--dry` code path runs.
+
+### Changed
+- **`package-release`: gate 4 retries once on host-contention timeout (Mode A, gh#2195, #2362)**; `cut-procedure.md` fails fast on a pnpm-shaped `node_modules` in Step 1 and adds Step 12 (restore the pnpm dev layout after a cut) (#2197, #2202); `gates-catalog.md` follows.
+- **`a2ui-maintenance` references follow the A2UI runtime.** `data-model-reactivity.md`, `surface-lifecycle.md`, and `pipeline-overview.md` describe the vendored v1 data model after ADR-0078 P3/P4 (walker retirement, #2271), the `v0_9`→`v1_0` dialect rename (gh#2212, #2241), and the five opt-out-scoped catalogs (gh#2211, #2233, #2216).
+- **`primitive-authoring` references absorb the ADR-drift harvest (#2441) and ADR-0063 wave 2 (#2443)**: `anti-patterns.md`, `api-contract.md`, `authoring-cycle.md`, `code-style.md`, `form-control-sizing.md`, `token-contract.md`, and `yaml-contract.md` now state the ratified spellings (`no-*` negation prefix, `closable`, `outlined`, `status=completed`) and the amended ADR-0047/0056/0059/0061 rulings inline.
+- **`HARNESS-NOTES.md`** pointer for non-Claude harnesses (gh#2449).
+
+### Fixed
+- **`generate-release-notes.mjs` (gh#2474): two bugs found and hand-fixed live during the v0.8.56 cut, now fixed at the source.** (1) When a CHANGELOG `[X.Y.Z]` section carries two same-named `### Changed`/`### Fixed` blocks (one at cut time, another added by a later hand-fix), the generator now merges them into one heading in first-occurrence order before demoting to `####` — the duplicate `####` heading that tripped CodeRabbit's MD024 (db13eaebb) can't recur. (2) The Slack post's per-package headline now prefers a bullet starting with `- **BREAKING` over document order, falling back to the first bullet only when none is BREAKING (b378b5fd9). Added `mergeDuplicateHeadings()`, unit coverage in `scripts/release/generate-release-notes.test.js`, and `selftest` regression cases for both. `scripts/release/generate-release-notes.mjs`.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — 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.
+- **`skills/` touched in this release window** (14 file(s), e.g. `a2ui-maintenance/SKILL.md`) — carried by the entries above.
+
+## [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/__init__.py

@@ -11,6 +11,11 @@ def register(ctx):
         path=Path(os.path.join(_HERE, "skills", "a2ui-maintenance", "SKILL.md")),
         description="Maintains the A2UI pipeline (packages/gen-ui/a2ui/): the chunk corpus, compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval, validator, calibration, evals, the a2ui MCP server. Use to author/harvest/fix chunks, tune STRONG_MATCH or zettel thresholds, validate an A2UI document, diagnose an eval gap/regression or lift a semantic fail, change MCP tools (generate_ui, compose_from_chunks, check_anti_patterns, refine_composition), scan anti-patterns, run pipeline ops, or when a contract can't express a shape. NOT for app screens (screen-composition), runtime gen-UI features (gen-ui-wiring), primitive authoring (primitive-authoring), or gallery scoring (gen-ui-review).",
     )
+    ctx.register_skill(
+        name="component-md-authoring",
+        path=Path(os.path.join(_HERE, "skills", "component-md-authoring", "SKILL.md")),
+        description="Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a component's states, composed children, aria behavior, or error/empty/ loading handling changes and it already has (or should grow) a `component.md`, or when asked to \"add component.md for X\" / \"write the screen-reader spec for X\" / \"why did check:component-md-fresh fail\". NOT the yaml prop/slot/event/token contract itself (primitive-authoring owns that — this skill only owns the two authored yaml fields, `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token audit (component-token-audit).",
+    )
     ctx.register_skill(
         name="cross-harness-authoring-standards",
         path=Path(os.path.join(_HERE, "skills", "cross-harness-authoring-standards", "SKILL.md")),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.54",
+  "version": "0.8.56",
   "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.54"
+version: "0.8.56"
 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/SKILL.md

@@ -47,7 +47,7 @@ Unmatched work defaults to pipeline-overview and re-classifies from there.
 | Tune the anti-pattern catalogue | [anti-patterns](references/anti-patterns.md) |
 | A 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 bracket | [surface-lifecycle](references/surface-lifecycle.md) (ADR-0061) |
-| Data-model internals — `Cell`/`Derived`, RFC-6901 pointers, `path-pointer.js` call-site migration, watch semantics | [data-model-reactivity](references/data-model-reactivity.md) (ADR-0078) |
+| Data-model internals — `Cell`/`Derived`, RFC-6901 pointers, watch semantics (shipped) | [data-model-reactivity](references/data-model-reactivity.md) (ADR-0078) |
 
 ## Contracts that gate every change
 

package/skills/a2ui-maintenance/references/data-model-reactivity.md

@@ -1,14 +1,16 @@
 # v1 data-model reactivity — Cell/Derived, RFC-6901 pointers, value-identity cutoff
 
 Source of truth: [ADR-0078](../../../../../../docs/ops/adr/adr-0078-a2ui-runtime-adopts-v1-data-model.md)
-(ratified 2026-08-20, gh#1762; phased plan tracked in gh#1784). Read the ADR
-before touching `packages/gen-ui/a2ui`'s data-model internals, `path-pointer.js`
-call sites, or `surface.js`/`renderer.js` watch semantics — this file is the
-routing pointer + the shape of the adopted contract, not a restatement of the
-ruling, and NOT a claim that any phase has shipped (check gh#1784's own state
-before citing this as already-live behavior).
+(ratified 2026-08-20, gh#1762; phased plan tracked in gh#1784, **closed
+2026-08-28 — all four phases P1-P4 shipped**). Read the ADR before touching
+`packages/gen-ui/a2ui`'s data-model internals or `surface.js`/`renderer.js`
+watch semantics — this file is the routing pointer + the shape of the
+adopted contract, not a restatement of the ruling. `path-pointer.js` (the
+transitional three-walker shim gh#1763 staged) is deleted as of P4; every
+call site now uses the vendored `resolvePointer`/`setPointer`/`deletePointer`/
+`createDataModel` primitives directly.
 
-## What's decided (direction, not yet fully built)
+## What's decided (shipped — ADR-0078 P1-P4 complete, gh#1784 closed)
 
 The in-repo A2UI runtime (`packages/gen-ui/a2ui`, the 0.9 dialect) **adopts**
 the vendored `packages/genui` v1.0 data model internally — `Cell`/`Derived`
@@ -19,8 +21,11 @@ data model. This is an internal implementation swap, not a consumer
 migration or a wire-grammar change: the dialect's eight message kinds, the
 `{path}` binding-prop shape, `updateDataModel`, `HandlerContext.updateModel/
 setModel`, `registerController/Handler/Resolver`, and the `<a2ui-root>`
-element API are all unchanged (ADR-0078 Decision item 2 — falsified if any
-consumer needs a code change, or if `dialect-schema.source.mjs` diffs).
+element API are all unchanged. **[amended 2026-08-28, gh#2268/lld-0005,
+gh#2212]** Decision item 2's falsifier is narrowed to wire-GRAMMAR diffs
+only: it is falsified if any consumer needs a code change, or if
+`dialect-schema.source.mjs`'s wire grammar diffs — a bare `$id`/filename
+identifier rename in `dialect-schema.source.mjs` no longer falsifies it.
 Phased across future cuts, plan/LLD to follow — nothing rides in the cut
 this ADR itself was ratified for (item 6).
 
@@ -49,19 +54,25 @@ this ADR itself was ratified for (item 6).
   same identity-cutoff rule as R-R10). This supersedes `surface.js`'s
   prefix-descend rule and `renderer.js`'s re-apply-all-bindings behavior.
 
-## What's converging, and what it changes
+## What converged (P1-P4, complete)
 
-`path-pointer.js` (gh#1763) currently preserves three divergent legacy
-walkers (`getByPath`/`setByPath`, `getPath`/`setPath`, `getModelValue`) on
-purpose, as a staging step — each call site migrates to the vendored
-semantics above and retires when its last call site migrates. Every
-migration phase must name its own behavior deltas rather than changing
-silently (ADR-0078 item 4 is falsified by an unnamed semantics change) —
-known deltas already called out: `/a//b/` stops resolving forgivingly,
-`/name/length` on a string stops leaking the primitive's own property,
-and a2ui's own read/write asymmetry (today: `getByPath`/`getPath` treat
-absent-path/`""`/`"/"` alike, but `setByPath`/`setPath` no-op on root
-instead of replacing it) converges on the read/write split named above.
+`path-pointer.js` (gh#1763) preserved three divergent legacy walkers
+(`getByPath`/`setByPath`, `getPath`/`setPath`, `getModelValue`) as a
+deliberate staging step; each call site migrated to the vendored semantics
+above in turn (P2: `renderer.js`; P3: `surface.js`/`wiring-registry.js`),
+and P4 deleted the module once its last call site migrated — no divergent
+walker survives (Decision 4). Every migration phase named its own behavior
+deltas rather than changing silently (ADR-0078 item 4's falsifier): `/a//b/`
+stopped resolving forgivingly, `/name/length` on a string stopped leaking
+the primitive's own property, `~0`/`~1` escaping is now honored, and a2ui's
+own read/write asymmetry (previously: `getByPath`/`getPath` treated
+absent-path/`""`/`"/"` alike, but `setByPath`/`setPath` no-op'd on root
+instead of replacing it) converged on the read/write split named above. The
+full Δ1-Δ10 delta table lives in
+[lld-0001-a2ui-data-model-consumption §Data](../../../../../../docs/ops/lld/lld-0001-a2ui-data-model-consumption.md#data);
+the surviving regression proof for the pointer-only deltas is
+`packages/gen-ui/a2ui/data-model-pointer-semantics.test.js` (migrated from
+`path-pointer.test.js` in P4).
 
 ## What stays fixed (don't "fix" these under this ADR)
 
@@ -76,15 +87,24 @@ instead of replacing it) converges on the read/write split named above.
 - `record.js`'s bidirectional-overlap store — app-layer, outside this
   package, rides a separate review track (R2), not this ADR.
 
-## Consumption mechanism — open, LLD decides
+## Consumption mechanism — decided (build-time copy)
 
-`@adia-ai/a2ui` is a zero-runtime-deps package (ADR-0048 posture);
-`packages/genui` is a vendored, never-edited-in-place artifact (ADR-0059).
-Whether the adopted primitives land via a build-time vendor-copy (with a
-provenance stamp) or a workspace-internal import is NOT decided by
-ADR-0078 — whichever the LLD picks must either preserve the zero-deps
-posture or explicitly re-rule it. Check the LLD (once authored, per gh#1784)
-before assuming either mechanism.
+`@adia-ai/a2ui` is a zero-runtime-deps package (ADR-0048 posture).
+**[amended 2026-08-29, ADR-0096, gh#2373 — recorded in ADR-0078's own
+2026-08-29 amendment]**
+`packages/genui` is absorbed first-party in-repo source, not a vendored
+artifact — `packages/genui/VENDOR.json` and the vendor-and-sync mechanism
+are gone (gh#2372 closed; `VENDOR.json` confirmed absent from origin/main).
+[lld-0001](../../../../../../docs/ops/lld/lld-0001-a2ui-data-model-consumption.md)
+decided a build-time byte-identical copy of
+`packages/genui/renderer/dist/data-model.js` (+`.d.ts`) into
+`packages/gen-ui/a2ui/`, with a `data-model.provenance.json` sidecar and a
+freshness gate in `npm run check` — preserving the zero-deps posture (no new
+package dependency, no covert workspace-import). The provenance sidecar now
+points at the in-repo source path instead of a `VENDOR.json` sha: it stamps
+`source.js`/`source.dts` + `syncedAt` + `contentHash` only —
+`packages/genui/renderer/dist/data-model.js` — with no vendor-sha field at
+all.
 
 ## Eval-floor risk
 

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

@@ -4,34 +4,63 @@
 
 Two protocol layers coexist (ADR-0059, `docs/ops/spec/spec-a2ui-v1-conformance.md`):
 the shipping dialect this pipeline emits (Layer A, `packages/gen-ui/a2ui/`) and
-the vendored A2UI v1.0 Candidate stack (Layer B, `packages/genui/`) reached
-through `packages/genui/wire-bridge/`. Candidate terminology is
+the A2UI v1.0 Candidate stack (Layer B, `packages/genui/`) reached
+through `packages/genui/wire-bridge/`. **[amended 2026-08-29, ADR-0096]**
+`adiahealth/gen-ui-system` is absorbed first-party under `packages/genui/`
+and the standalone repo is archived — Layer B is in-repo source, not a
+vendored dependency; `VENDOR.json` and the sync mechanism are gone (see
+this same note on siblings `data-model-reactivity.md` and
+`surface-lifecycle.md`). Candidate terminology is
 **renderer/agent** — never client/server: `callableFrom` values are
 `rendererOnly`/`agentOnly`/`rendererOrAgent`; the wire function kinds are
 `callRendererFunction`/`callAgentFunction` +
 `rendererFunctionResponse`/`agentFunctionResponse`; the MIME type is
 `application/a2ui+json`; catalog resolution is strict (component `catalogId` →
 surface `catalogId` → error, no registry default). The producer's
-`wireFormat: 'v1'` flag exists and defaults to `'dialect'`
-(`packages/genui/adia-producer/exit-gate.js`). Documents authored here stay
-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).
+`wireFormat` flag (`packages/genui/adia-producer/exit-gate.js`) **[flipped
+2026-08-30, PR #2412]** now defaults to `'v1'`, not `'dialect'` — ADR-0072
+ratified the flip (its precondition, genui-system#51's re-verification,
+re-scoped and satisfied via ADR-0096/PR #2401) and the flip itself has since
+executed. Documents authored here stay dialect-shaped; the bridge owns the
+translation — never hand-write Candidate envelopes from this skill's
+surfaces.
+
+**Catalogs are opt-out scopes, not a taxonomy.** A2UI v1.0 lets a renderer
+mix catalogs within one surface: `createSurface.catalogId` is the default,
+and any component may carry its own `catalogId` to override it
+(a2ui.org/specification/v1.0-a2ui/, "Catalog Reference"). So the useful way
+to split a catalog is by what an app OMITS, never by component kind — Buttons
+and Inputs are never omitted together, whole feature areas are. This is the
+ratified basis of the five-catalog partition (gh#2211, Kim 2026-08-28):
+`adia.core` / `adia.navigation` / `adia.data` / `adia.agent` / `adia.shells`,
+every one a derived view over the yaml `category` axis and package path,
+never a hand list. Two facts that trip a re-derivation: the `category` axis
+had no `data` bucket for tables/charts (they declared `agent`; the partition's
+pre-step re-categorizes five components), and `packages/web-modules/**` is a
+path seam, not a category (its sidecars mostly declare `layout`/`container`).
+The partition lives on the Layer B side only; the dialect catalog stays one
+file per ADR-0059 §1. The 44 L1 harvested widgets are a pattern library, not
+catalog members.
+
+site-a2ui (the build-time HTML→A2UI docs-site transpile) was RULED fit as
+the **dialect side's regression corpus**, not a v1.0 conformance bed
+(ADR-0068): it exercised the dialect renderer, the ADR-0061 lifecycle path,
+and the engine transpiler at real-content scale in production, but never
+touched the producer, the bridge, or the `wireFormat` flag. That fitness
+ruling was load-bearing on `wireFormat` defaulting to `'dialect'`, with a
+**Named expiry**: the flag-flip ADR that makes `'v1'` the shipping default
+had to re-rule site-a2ui's fitness (re-point vs retirement-by-attrition).
+
+**[resolved, ADR-0072]** That trigger has fired and been ruled:
+retirement-by-attrition, not re-point (Decision 2) — promotion program
+closed, site-a2ui moves to breakage-only maintenance, an attrition-exit
+ticket tracks the wind-down (gh#2410), and the mechanism is removed once the
+promoted set reaches zero. The flip itself has since executed (PR #2412,
+merged 2026-08-30: `exit-gate.js` now defaults to `'v1'`) — site-a2ui is in
+its attrition window now, not a still-open future trigger. Burn-down of
+existing `visual-drift`/`blocked-format-gap` rows is no longer "ordinary
+maintenance toward parity promotion" (ADR-0068 Decision 5) — it is wind-down
+toward the mechanism's removal per gh#2410.
 
 All paths repo-relative. Specs worth reading before structural changes:
 `.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
@@ -151,6 +180,11 @@ for any constant or decision lives in git and PR descriptions
     currently fails, mostly a schema-generation gap around `data-*`/`span`
     attributes, not corpus-content defects — see the ticket before
     assuming a chunk is actually broken).
+13. **Every generated catalog schema carries three synthesized universal
+    props today** (`slot`/`hidden`/`ariaLive`, none declared in any yaml
+    SoT); ADR-0097 rules a fourth, `traits`, but that part is decided-not-
+    yet-shipped (gh#2513) — see `primitive-authoring/references/
+    yaml-contract.md` §Synthesized universal props for the full contract.
 
 ## Test + run commands (all verified in root package.json)
 

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

@@ -57,13 +57,20 @@ Staleness is exposed as one attribute plus three events, never styling:
 
 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.
+`commitSurfaceUpdate` / `abortSurfaceUpdate` as v1.0 server kinds) are
+defined by the v1.0 Candidate reference implementation — `a2ui.schema.json`
+gains nothing, the dialect wire format is byte-identical. Never hand-write
+lifecycle envelopes from this skill's surfaces; the Bridge owns the mapping
+when the kinds land.
+
+**[amended 2026-08-29, ADR-0096]** `adiahealth/gen-ui-system` is absorbed
+first-party under `packages/genui/` and the standalone repo is archived —
+there is no external, separately-governed "upstream standard" to wait on
+any more. ADR-0096 Decision 5: gen-ui-kit "owns the whole stack now... and
+the v1.0 Candidate reference implementation itself, not only the consumer
+side of a vendor boundary." Stream-driven regeneration now proceeds on
+gen-ui-kit's own schedule against the in-repo `packages/genui/` source,
+not an upstream release.
 
 ## Interlock worth knowing
 

package/skills/component-md-authoring/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: component-md-authoring
+description: >-
+  Author the two judgment sections of a component's `component.md` —
+  Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a
+  component's states, composed children, aria behavior, or error/empty/
+  loading handling changes and it already has (or should grow) a
+  `component.md`, or when asked to "add component.md for X" / "write the
+  screen-reader spec for X" / "why did check:component-md-fresh fail". NOT
+  the yaml prop/slot/event/token contract itself (primitive-authoring owns
+  that — this skill only owns the two authored yaml fields,
+  `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui
+  corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token
+  audit (component-token-audit).
+disable-model-invocation: false
+user-invocable: true
+---
+
+# component-md-authoring
+
+`component.md` (gh#2615) is a generated shell, per-component, sitting next
+to its `.yaml` SoT (`packages/web-components/components/<name>/component.md`,
+or `packages/web-modules/<cluster>/<name>/component.md` for a composite/
+shell). Every section except two is mechanically transcluded from the yaml
+by `scripts/build/gen-component-md.mjs` — Intent, API (props/events/slots),
+Structural (Light DOM anatomy + states + composes), Tokens, Rules,
+Anti-patterns, Related. This skill's whole charter is the two sections that
+aren't: **Screen-reader spec** and **Behavioral spec**.
+
+## The load-bearing decision: where the authoring happens
+
+You do not hand-edit `component.md`. You edit the yaml's `screenReader:`
+and `behavioral:` fields (and, ideally, `intent:`) — `component.md` is
+regenerated from them. This is deliberate, not incidental:
+
+- **No second source of truth.** plan-2615's evidence pass on gh#2615 found
+  most of component.md's "intent layer" already lives in the yaml
+  (`a2ui.rules`, `anti_patterns`, `related`, examples). The two genuine
+  gaps — screen-reader and behavioral judgment — get the SAME treatment:
+  authored once, in yaml, transcluded everywhere else (component.md today;
+  gen-ui corpus derivation once a2ui-maintenance wires it in).
+- **The freshness gate is PR-blocking, not staleness-only.** Because the
+  authored content lives in a yaml field, `component.md` is 100%
+  mechanically regenerable — `check:component-md-fresh` can do a real byte-
+  diff, the same shape as `check:reference-docs-fresh`, except PR-blocking
+  (operator ruling 2026-08-31) rather than advisory-only. A hand-edit
+  directly in `component.md` will be silently clobbered by the next
+  `npm run docs:component-md` and will fail the gate as "not fresh" — this
+  is the guard rail, not a bug.
+
+## Authoring a component's two sections
+
+1. Confirm the component doesn't already have adequate coverage — read its
+   existing `states:`, `a2ui.rules`, and `.class.js` source. Per
+   primitive-authoring's own first principle, **source wins**: verify every
+   claim you're about to write (focus order, aria attribute names, event
+   names) against the actual `.class.js`/`.js` file, not just the yaml
+   prose.
+2. **Screen-reader spec** — focus order across composed children (order
+   `showModal()`/connect moves focus, what wraps at the tab boundary),
+   live-region announcement sequence (what fires `role="alert"` or an
+   `aria-live` region, and when), and any keyboard map beyond the trait
+   default (`pressable`/`focusable` already cover Enter/Space/click — only
+   document what's ADDITIONAL, e.g. arrow-key grid nav, Escape-dismiss).
+   Do not restate a static `aria-*` attribute the yaml's `props`/`states`
+   already document plainly — that's derived content, not new judgment.
+3. **Behavioral spec** — dismiss/error/empty/loading states and
+   transitions NOT already modeled by `states:`. Distinguish "fetching" vs
+   "confirmed empty" where both exist (see `table.yaml`'s `screenReader`/
+   `behavioral` for a worked example: three distinct states, not one).
+   Name what is explicitly NOT handled (no built-in error state, no
+   built-in loading state) as clearly as what is — an absence is often the
+   more actionable fact for a consumer.
+4. Both fields require `minLength: 20` (schema-enforced) — a placeholder
+   one-liner will fail `check:components-valid`. Write real prose, grounded
+   in source, not a restatement of the component's `description`.
+5. Regenerate and verify:
+
+   ```bash
+   node scripts/build/components.mjs --validate   # schema-valid yaml
+   npm run docs:component-md                      # regenerate component.md
+   npm run check:component-md-fresh                # PR-blocking gate
+   ```
+
+6. If this is the component's FIRST component.md (yaml previously had
+   neither field), run `npm run build:components` too — the corpus/catalog
+   rebuild picks up the new yaml content, and `npm run eval:diff --
+   --engine zettel` should show no regression (preserve-not-regress floor,
+   owned by a2ui-maintenance).
+
+## Scope (gh#2615 pilot)
+
+`scripts/build/gen-component-md.mjs`'s `SCAN_ROOTS` covers
+`packages/web-components/components/` and `packages/web-modules/chat/`
+today — the pilot 5 (`button`, `modal`, `table`, `field`, `chat-shell`).
+Extending to every web-modules cluster, or sweeping the remaining ~145
+primitives, is deliberately out of scope for this pass (file a follow-up
+task rather than silently expanding `SCAN_ROOTS` for one-off need — a
+cluster added there without a plan for authoring every component inside it
+just produces components with a `.yaml` but no eligible `component.md`,
+which the generator already handles gracefully by skipping them, but which
+defeats the point of a rollout plan).
+
+## Cross-references
+
+- `primitive-authoring`'s authoring-cycle: add "new/changed states or aria
+  behavior → component-md-authoring's authored sections may need a pass"
+  to your own SoT-change checklist when editing a yaml that already has a
+  `component.md` sibling.
+- `scripts/schemas/component.yaml.schema.json` — `intent`/`screenReader`/
+  `behavioral` field definitions (all optional; a component with a `.yaml`
+  but neither authored field simply has no `component.md` yet).
+- `scripts/verify/check-component-md-fresh.mjs` — the PR-blocking gate:
+  byte-freshness (component.md matches a fresh render) AND same-PR
+  coverage (a component.md-bearing component's source/yaml change must
+  touch component.md in the same diff).

package/skills/component-md-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Component Md Authoring"
+  short_description: "Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh."

package/skills/package-release/references/cut-procedure.md

@@ -31,6 +31,7 @@ Two entry variants, converging at Step 5:
 | 9 | Dispatch publish workflows; wait; verify registry | Publish |
 | 10 | GH releases + site deploy dispatch | Deploy |
 | 11 | Author release notes (default, not optional) | No |
+| 12 | Restore the pnpm dev layout (`npm ci` left it npm-shaped) | node_modules only |
 
 ---
 
@@ -44,8 +45,18 @@ git -C "$REPO" status --short
 git -C "$REPO" log --oneline -8
 git -C "$REPO" fetch && git -C "$REPO" log HEAD..origin/main --oneline   # must be empty
 git -C "$REPO" tag --list 'vX.Y.Z' '*-vX.Y.Z'   # must NOT exist yet
+[ -d "$REPO/node_modules/.pnpm" ] && echo "STOP: pnpm-shaped node_modules — run npm ci first"   # gate 9 precondition, see §3.1 layout note
 ```
 
+**Check the `node_modules` layout here, not at gate 9.** The §3.1 layout note (gh#1359)
+already says gate 9 (`check:js-bundles-fresh`) needs the npm-ci layout, but it sits AFTER
+the gate roster and is easy to read past — the v0.8.55 cut (2026-08-28) ran the full
+33-gate pre-flight under a pnpm-shaped tree, lost ~12 minutes to gates 1-8 and 10-33
+passing, then failed gate 9 with phantom bundle drift (1.24 MB on disk vs 1.52 MB fresh
+on every JS entry — the Phosphor icon glob resolving differently, not a real source
+change). The one-line check above fails in under a second instead. `npm ci` to recover;
+`npm install` alone does NOT reshape an existing pnpm tree.
+
 `branch --show-current` ≠ `main` → stop; cutting on a feature branch pushes a stale `main` ref while the tags point at the feature tip. Recovery: [`recovery-paths.md`](recovery-paths.md) §Scenario 8. If multiple unpushed `release(*):` commits exist → this is a batch push, [`recovery-paths.md`](recovery-paths.md) §Scenario 2.
 
 ## §Step 2 — Classify uncommitted files; stash strays
@@ -244,7 +255,9 @@ git -C "$REPO" checkout -b "release/vX.Y.Z"
 git -C "$REPO" reset HEAD >/dev/null 2>&1
 git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
   packages/gen-ui/a2ui/*/package.json packages/gen-ui/a2ui/*/CHANGELOG.md \
-  packages/genui/adia-catalog/base.json packages/genui/adia-catalog/adia-pack.json \
+  packages/genui/adia-catalog/adia.core.json packages/genui/adia-catalog/adia.navigation.json \
+  packages/genui/adia-catalog/adia.data.json packages/genui/adia-catalog/adia.agent.json \
+  packages/genui/adia-catalog/adia.shells.json \
   docs/ops/releases/vX.Y.Z.md   # + in-scope source + Step-3.0 regen outputs
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
 ```
@@ -261,6 +274,19 @@ node scripts/build/components.mjs --verify && npm run check:chunks-fresh && npm
 
 Drift here means a regen output was left out of the allowlist — stage it and re-run. <2s now vs ~5min of tag-move recovery after CI catches it. Do not proceed to tag with drift.
 
+## §Step 5.6 — Unstaged-tracked-files guard (`release-pack.mjs`, gh#2473)
+
+`release-pack.mjs`'s Step 5 mechanizes this: right after its own `git add`
+(the allowlist above, as automated), it runs `git status --porcelain` and
+fails the cut if any tracked file is still modified-in-the-worktree —
+proof the allowlist covered everything bump.mjs / cut-hygiene touched this
+cut, not just what §Step 5.5's three named freshness gates happen to check.
+This is the fourth time the allowlist itself went stale (gh#1198, gh#1899,
+gh#1954, gh#2473 — most recently the factory README's generation-MCP pin
+prose), so the guard is generic rather than another named file. A manual
+cut should run the equivalent check by hand: `git status --porcelain`
+after staging must be empty of `M`/`D` lines.
+
 ## §Step 5.7 — Release PR: push the branch, merge, re-baseline
 
 The release commit reaches `main` through the standard PR flow. Mechanized
@@ -415,6 +441,25 @@ Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
 Always author notes at end-of-cycle without being asked — context is freshest now. Single version → [`notes-authoring.md`](notes-authoring.md); ≥2 versions since the last broadcast → its §Rollup section. Surface the draft inline for copy-paste; the operator owns posting. Skip only on an explicit "no notes".
 
+## §Step 12 — Restore the dev layout
+
+The cut runs under `npm ci` (Step 1's layout check, gate 9), and that leaves
+`node_modules` npm-shaped. The dev server refuses to start on that tree:
+`npm run dev`'s `predev` hook (`scripts/dev/check-pnpm-layout.mjs`) hard-stops
+because the Phosphor icon glob matches zero files under the hoisted layout and
+every `<icon-ui>` would render empty (gh#340). Put the tree back before handing
+the checkout to anyone, including yourself:
+
+```bash
+pnpm install                                    # single checkout
+node scripts/dev/bootstrap-worktree.mjs         # inside a linked worktree
+```
+
+Both are idempotent and touch no committed file (`pnpm-lock.yaml` is
+gitignored). Live cost of skipping this: the v0.8.55 cut (2026-08-28) left the
+operator's primary checkout unable to run `npm run dev` until the layout was
+restored by hand.
+
 ## §The 0.8.38 cut (the clean-world cut — delete this section after it lands)
 
 The first cut AFTER the estate-split bridge. Pre-conditions, all verifiable

package/skills/package-release/references/gates-catalog.md

@@ -159,6 +159,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 - **What:** the vitest suite (~1000+ tests).
 - **Stale-test failure:** the test asserts a behavior a peer deliberately changed (CHANGELOG-documented) without updating the assertion. Tell it apart by reading assertion vs CHANGELOG vs source: if the code matches the CHANGELOG's described behavior, the test is stale — update the assertion (see [`recovery-paths.md`](recovery-paths.md) §Scenario 5). Real regression → fix the regression.
 - **Parallel-contention flake:** heavy web-modules composite suites can fail under full parallelism on a loaded machine (`signals: drain loop exceeded 100 iterations`). Load-dependent, not a code defect. Sequential is the source of truth, and **the roster gate now runs it directly** (`npm run test:unit:serial` = `vitest run --no-file-parallelism`, gate 4 since 2026-07-19) — a parallel `test:unit` flake outside the roster still isn't a blocker, and don't raise the drain guard.
+- **Same-host contention timeout (gh#2195):** gate 4 running solo (Phase 1, see the execution-model note above) isolates it from every OTHER pre-flight gate, but not from unrelated concurrent load on the same shared, multi-tenant host — another agent's build, a peer's own `npm run check`. gh#2195's diagnosis found this surfaces as a genuine 45s per-test timeout on a DIFFERENT single file each run, with no repeat culprit (the contention signature, not an order-dependent leak) — and found no separate "release pre-flight runner" with its own core count exists to recalibrate `worker-cap.mjs` against; it's the same operator/agent host either way. `release-pack.mjs`'s `runSoloGateWithRetry()` now retries gate 4 exactly once, scoped to only the file(s) it named as failed, when the failure output has a parseable `FAIL <file>` list — a file that fails once and passes clean on that immediate re-run was contention, not a regression; a file that fails twice is treated as a real one and the pre-flight still aborts. No other gate, and no OTHER invocation of `test:unit:serial` (CI, local dev, `npm run check`), gets this retry.
 - **Exit 143 (SIGTERM):** the vitest process was KILLED (resource pressure / a stray terminator), not a test failure — re-run the gate directly (`npx vitest run --no-file-parallelism`) before diagnosing anything; a clean re-run means transient, proceed (v0.8.34 handoff hit this).
 - **First-time-at-cut failures are REAL (v0.8.34):** this serial suite runs tests PR CI never does — `exit-gate.corpus` (dialect-catalog conformance over real harvested chunks) surfaces yaml-schema drift (e.g. an array prop missing `items.type`, the command/combobox `DynamicStringList` mis-map) only HERE, potentially weeks after the yaml edit merged green. Treat such a failure as a genuine latent defect to root-cause at the yaml SoT, never as release-blocking noise. (Structural fix — promoting the corpus batch into PR CI — tracked as a follow-up.)