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

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

@@ -56,14 +56,17 @@ export const GATE_ROSTER = [
   // worktree.mjs && npm run dogfood:status` once under the pnpm layout too
   // before cutting (cut-procedure.md §3.1 states the per-gate layout need).
   { n: 17, cmd: 'npm run dogfood:status',                      what: 'P0/P1 dogfood floor (static-only under npm-ci; run once more under bootstrap layout for full coverage, gh#1359)' },
-  // gh#421: these four live in the `npm run check` aggregate but were never
-  // in the pre-cut roster, so a gate added to CI silently never reached a
-  // cut. examples-md + site-a2ui are the two generators an `.examples.html`
-  // edit invalidates (the v0.8.14 cut lost a CI round-trip to exactly that);
-  // contrast is the AA gate that gh#427 widened from 42 to 90 pairs;
-  // token-semantics-sync keeps the token-selection pack's generated half honest.
+  // gh#421: these live in the `npm run check` aggregate but were never in
+  // the pre-cut roster, so a gate added to CI silently never reached a cut.
+  // examples-md is the generator an `.examples.html` edit invalidates (the
+  // v0.8.14 cut lost a CI round-trip to exactly that); contrast is the AA
+  // gate that gh#427 widened from 42 to 90 pairs; token-semantics-sync keeps
+  // the token-selection pack's generated half honest.
+  // (Gate 19 was `verify:site-a2ui` — retired with the site-a2ui mechanism
+  // itself, ADR-0072 Decision 2 / gh#2410. Number left unassigned rather
+  // than renumbering 20+ — gate numbers are cited as identities in shipped
+  // release notes, same discipline gate 29's note states.)
   { n: 18, cmd: 'npm run check:examples-md-fresh',             what: '.examples.md vs .examples.html' },
-  { n: 19, cmd: 'npm run verify:site-a2ui',                    what: 'site-a2ui converted rows vs source fragments' },
   { n: 20, cmd: 'npm run verify:contrast',                     what: 'WCAG AA — canvas-text + text-on-fill pairs' },
   { n: 21, cmd: 'npm run check:token-semantics-sync',          what: 'token-selection generated references vs token sources' },
   // Operator directive 2026-07-27: demo surfaces must be discoverable —
@@ -152,6 +155,14 @@ export const GATE_ROSTER = [
   // 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' },
+  // gh#2829: gh#2808/PR #2815 (ADR-0108 ticket 3) promoted both yaml gates
+  // below into `npm run check` but deliberately left this pre-cut roster
+  // untouched — a cut could still ship a yaml `events:` block that phantoms
+  // or misses a runtime dispatch, or a schema field with no implementation
+  // coverage, without either failing the pre-flight. Appended, not
+  // inserted — same numbering discipline as gate 30/31/32/33.
+  { n: 34, cmd: 'node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details', what: 'yaml events: blocks vs runtime dispatch (no phantom/missing events)' },
+  { n: 35, cmd: 'node scripts/release/check-yaml-impl-coverage.mjs --strict', what: 'yaml schema fields vs implementation coverage' },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/primitive-authoring/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: primitive-authoring
 description: >-
-  Author or modify AdiaUI framework source inside the monorepo — primitives
+  Author or modify AdiaUI framework source inside the monorepo — components
   (packages/web-components), shells/composites (packages/web-modules), yaml
-  SoTs, demos. Use to add a new primitive, fix a prop/slot/attribute/CSS
+  SoTs, demos. Use to add a new component, fix a prop/slot/attribute/CSS
   variant, update a yaml, build or fix a shell (chat-shell, admin-shell,
   editor-shell — sidebar/pane/bespoke-tier composition), promote repeated
   inline content into a shared module, audit a component's four-axis
@@ -100,5 +100,8 @@ then the full sequence — never suppress.
   [authoring-cycle.md](references/authoring-cycle.md) Step 3 are fixed
   immediately; contract-neutral pattern drift is proposed in review, not
   blocked on.
+- **SoT-change / component.md check**: new or changed states or aria
+  behavior on a yaml with a `component.md` sibling → component-md-authoring's
+  authored `screenReader`/`behavioral` sections may need a pass.
 - A one-line bug that touches no props, CSS contract, or lifecycle doesn't
   need this skill's overhead — just read the code and edit.

package/skills/primitive-authoring/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Primitive Authoring"
-  short_description: "Author or modify AdiaUI framework source inside the monorepo — primitives (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."
+  short_description: "Author or modify AdiaUI framework source inside the monorepo — components (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."

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

@@ -646,6 +646,46 @@ If you author a primitive that programmatically creates another (`document.creat
 
 Source: ADR-0027.
 
+### AP-R2 · Folding two visually-converging widgets into a shared module (ADR-0101)
+
+Two widgets can converge visually — same tab-strip chrome, same header
+band, same "looks like the same component" impression on the catalog page
+— while carrying fundamentally different content models underneath. That
+visual overlap alone is not sufficient reason to extract a shared module
+or fold one into the other.
+
+`inspector-ui` (a live devtools pane: four fixed panes, content pushed in
+imperatively and repeatedly after connect via `update()`/`setHTML()`) and
+`preview-ui` (static docs demo chrome: content captured once on connect,
+shown two fixed ways) look like the same tabbed-view widget. They aren't:
+folding one into the other would force the static-capture component to
+grow a second, incompatible imperative-update mode it doesn't need for the
+job it already does correctly everywhere it's used — added surface, not
+removed surface. Extracting a shared tab-view module was evaluated and
+rejected for the same reason: no common substrate exists beneath the
+visual layer that both widgets could share without also merging their
+different content models (`tabs-ui`'s synthesized strip vs. a hand-rolled
+`role="tablist"` div built for single-panel content-swap semantics).
+
+**The resolution is a mirror, not a merge:** keep both components on their
+own contracts; restyle the trailing one to match the leading one's chrome
+via scoped CSS only (`@scope (inspector-ui)` overrides copying
+`preview-ui`'s header-tab anatomy, tokens, and typography) — no shared
+component, no deprecation. The tradeoff this accepts: because the
+mirroring is duplicated CSS, not a shared module, a future visual change
+to the pattern's source component doesn't automatically propagate: check
+the mirrored block for parallel drift when you next touch the pattern
+that's being mirrored — the same "primitives that compose primitives
+don't auto-import" discipline ADR-0027 already requires (AP-R1, above),
+now applied to a duplicated CSS block instead of a duplicated import.
+
+Before extracting a shared module for two things that "look the same,"
+verify they'd actually share the extracted contract (props, update
+semantics, lifecycle) — not just its rendered chrome. If they wouldn't,
+mirror the chrome and keep both components separate.
+
+Source: ADR-0101.
+
 ---
 
 ## Rapid-fire anti-patterns (mined from incident history)

package/skills/primitive-authoring/references/common-gotchas.md

@@ -16,7 +16,7 @@ Composite authors: read §§1–5 BEFORE Phase 3 sketch. Anyone adding an async
 4. [minmax(min, 1fr) inside repeat() fighting container queries](#4-minmaxmin-1fr-inside-repeat-fighting-container-queries)
 5. [Nested `<!-- ... -->` inside design-plan canonical-sketch fenced blocks](#5-nested----inside-design-plan-canonical-sketch-fenced-blocks)
 6. [Async load/render function completing out of order](#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough)
-7. [Minting a wrapper-shaped component before its registry.js entry lands](#7-minting-a-wrapper-shaped-component-before-its-registryjs-entry-lands--site-a2ui-silently-deletes-the-node-not-just-mis-types-it)
+7. [Minting a wrapper-shaped component before its registry.js entry lands](#7-minting-a-wrapper-shaped-component-before-its-registryjs-entry-lands--the-transpiler-silently-deletes-the-node-not-just-mis-types-it)
 
 ---
 
@@ -123,15 +123,15 @@ async #loadContent(route) {
 
 ---
 
-## 7. Minting a wrapper-shaped component before its registry.js entry lands — site-a2ui silently deletes the node, not just mis-types it
+## 7. Minting a wrapper-shaped component before its registry.js entry lands — the transpiler silently deletes the node, not just mis-types it
 
-**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Regenerate a site-a2ui row for a demo using a component minted in the SAME change, before its `registry.js` line lands, and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh`/`verify:site-a2ui` both report clean.
+**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Transpile a demo using a component minted in the SAME change, before its `registry.js` line lands (e.g. the chunk harvester, `node scripts/build/harvest-chunks.mjs`, or any other engine-transpiler consumer), and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh` reports clean.
 
-**Example**: minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): `site-a2ui/pages/site__patterns__bulk-action-toolbar.a2ui.json` contains zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. `verify:site-a2ui` reported 321/321 clean.
+**Example (historical — the illustrating consumer has since retired):** minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row (site-a2ui itself retired 2026-08-31, ADR-0072 Decision 2 / gh#2410 — the underlying registry-gating hazard below is unchanged, only that particular consumer is gone) before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): the converted artifact contained zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. The site-a2ui freshness gate of the day reported clean regardless, for the exact reason the Detector below still explains.
 
-**Detector**: none generic — `verify:site-a2ui`'s freshness check can't catch this (the row IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual route in a browser and confirming the new tag's node count is nonzero, or re-running `node scripts/build/site-a2ui.mjs --page <route>` (or `--stale`) after `registry.js` is updated and diffing the row for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
+**Detector**: none generic — a same-source freshness check can't catch this (the artifact IS fresh relative to its source, it transpiled correctly against a registry that was itself incomplete). The only catch is rendering the actual consuming surface and confirming the new tag's node count is nonzero, or re-running the transpile after `registry.js` is updated and diffing the output for the new component name. A non-wrapper-shaped new component (multiple children, or attributes that happen to map to real props) is lower-risk here — it survives as a visible-but-wrong Column, the gh#535 class, which at least has a visual tell.
 
-**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before regenerating any site-a2ui row that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run `node scripts/build/site-a2ui.mjs --page <route>` on the merged tree and browser-probe the tag actually appears — never trust `verify:site-a2ui`'s green alone for a route touching a component minted in the same change.
+**Fix**: the `registry.js` entry is what gates resolution — land it (not just run `components.mjs`, which is necessary for prop fidelity but not sufficient to avoid the retype) before transpiling anything that uses the new tag. When gating a dispatched agent's PR that did this out of order, re-run the transpile on the merged tree and confirm the tag actually appears in the output — never trust a freshness gate's green alone for a surface touching a component minted in the same change.
 
 **Generalizes to**: any hand-maintained resolution map (not build-generated) that a later regeneration step reads through — regenerating before the map is updated produces an internally-consistent-but-wrong artifact that passes a same-source freshness check; if the misresolved shape also happens to trip a downstream simplification/collapse rule, the failure escalates from "renders wrong" to "renders nothing," with no visual tell at all.
 

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

@@ -62,6 +62,18 @@ Every component CSS file has exactly this shape:
 
 When a parent tries to override `--component-bg`, specificity beats them. The zero-specificity layer is the contract.
 
+## Region elements never self-style (2026-09-01, ADR-0105)
+
+Native `<header>`/`<section>`/`<footer>` and `<header-ui>`/`<section-ui>`/`<footer-ui>` (a CSS-only slot-routing anatomy stub — no JS, no events, no `.css` file of its own) are **region elements**, not components in their own right. They carry zero layout CSS. Every grid, gap, sticky rule, and slot-vocabulary variant a region renders is written in the **closest host pattern's** `@scope (host-name)` block — `page-ui`, `card-ui`, `drawer-ui`, `modal-ui`, `anchor-bar`, the shells — matching the region by tag + attribute selector (`:scope > :where(header, header-ui)`, `:has(> [slot="action"])`, etc.), never in a region-owned stylesheet.
+
+**If you're authoring a new host pattern that accepts region children, you MUST ship its `@scope` treatment for every region shape it accepts before it ships.** A host that accepts `<header-ui>` without a matching grid/sticky/slot-vocabulary block is not a lesser-but-valid host — the region element structurally cannot supply the missing layout itself, so the host renders wrong (usually unstyled block flow, or — the observed failure mode — a stale layout that packs content into the wrong shape). gh#2760 is the live example: `page-ui`'s header-band `@scope` block didn't reproduce the retired `admin-page-header`'s action-cluster grid for a multi-item `[slot="action"]` containing a block-level `<tabs-ui>`, so tabs overlapped buttons instead of getting their own row — same markup, incomplete host coverage.
+
+**Bare `<header>` vs `<header-ui>`** — both reach a host's tag-matched rules identically (`:where(header, header-ui, …)` gives them equal zero specificity). They diverge only on rules keyed off a named-slot attribute selector (`:has(> [slot="icon"])`, etc.) — and there the divergence isn't mechanical (`slot=` is decorative everywhere, ADR-0033), it's documentation: `header-ui`'s own yaml is the only place the icon/heading/description/action vocabulary is written down and steered toward by `a2ui.rules`. Use bare `<header>`/`<section>`/`<footer>` only for unstructured default-slot content; use the `-ui` stub whenever content decomposes into the slot vocabulary — that's the only path an author or the A2UI generator discovers it exists.
+
+A region element acquiring its own `.css` file (layout rules scoped to `header-ui` itself, not the host) is the anti-pattern this section exists to name — see ADR-0105 for the full rationale and the corollary above.
+
+Source: [ADR-0105](../../../../../../docs/ops/adr/adr-0105-region-elements-never-self-style.md).
+
 ## Variants vs modes — the decision tree
 
 The rule: **variants change tokens; modes change layout.**

package/skills/primitive-authoring/references/form-control-sizing.md

@@ -31,6 +31,16 @@ Decision Class 1 removes the 20ch-class field-width floor for
 floor, generalizing the `button-ui` keep-square pattern already named below
 to the field-width components.
 
+**[amended 2026-08-31, gh#2534, ADR-0095]** The square-minimum rule governs
+a primitive's own OUTER inline-size floor against its own block-size only —
+it does not reach a component's INTERNAL grid-column sizing. A token like
+`field-ui[inline]`'s `--field-label-inline-min: 10ch` floors the label
+*column* inside the component's internal grid, to keep sibling rows
+aligned — not to prevent the host itself from collapsing — so it is not
+"a `--*-min-width: 20ch`-class floor" in ADR-0095's sense and is not
+retired by the Decision above. Don't apply the square-minimum rule to an
+internal grid-column token by analogy to the field-width class.
+
 *(Historical, pre-ADR-0095 rule — superseded by the retirement above, kept
 only for context on what the old convention was.)* A
 `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on

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

@@ -448,6 +448,13 @@ Consumers (CodeMirror layout, canvas redraw, dependent UI) listen on the shell o
 
 ### admin cluster (canonical reference)
 
+**[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-header`/
+`admin-page-body` are retired deprecate-then-delete; `admin-scroll` is
+renamed wholesale to `page-scroll`. `page-ui[band]` + `page-scroll` are
+now the canonical page-chrome pair — this cluster still describes
+`admin-shell`'s pre-migration internal composition, valid during the
+deprecation window.
+
 - **3 JS-bearing children** — `<admin-shell>` (host coordinator), `<admin-sidebar>` (resize+collapse+persist), `<admin-command>` (Cmd+K palette)
 - **7 CSS-only structural children** — `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>`
 - **CSS bridge** — `packages/web-modules/shell/admin-shell/css/admin-shell.bespoke.css` (~240 LOC)
@@ -547,7 +554,7 @@ When you encounter a legacy reference in old documentation or commit history, th
 
 - [authoring-cycle.md](authoring-cycle.md) — general 5-step authoring procedure; shell-specific rules layer on top
 - [api-contract.md](api-contract.md) — prop naming, reflection policy
-- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes
+- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes; §Region elements never self-style (ADR-0105) — a shell that hosts `<header-ui>`/`<section-ui>`/`<footer-ui>` region children (e.g. a bespoke `<X-header>` wrapping one) owns their `@scope` layout the same way `page-ui`/`card-ui`/`drawer-ui`/`modal-ui` do
 - [lifecycle-patterns.md](lifecycle-patterns.md) — teardown patterns; the cleanup-closure pile and document-listener rules above layer on top
 - [token-contract.md](token-contract.md) — zero-raw-color + L3 alias rules apply identically to shells
 - [module-promotion.md](module-promotion.md) — the _different_ activity of lifting a cross-cluster reusable element (theme panel, command palette) into a shared module

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

@@ -36,6 +36,23 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 }
 ```
 
+### `@scope` donor selectors must be tag-independent when a component can swap its own rendered tag (ADR-0102, 2026-09-01)
+
+A `@scope (my-component-ui)` donor selector matches by **literal tag
+name**. That's a live gap for any component whose own contract lets it
+render as a different tag than its own custom-element name — `text-ui`
+already did this coincidentally (`variant="body"` → `<p>`,
+`variant="caption"` → `<small>`), relying on ambient/bare-tag styling
+rather than the component's own `[variant]` rules. ADR-0102 (`text-ui`'s
+`level` prop, promoting the element to a real `<h1>`-`<h6>`) made this a
+first-class case, requiring the donor selector to stay tag-independent —
+e.g. `@scope (text-ui, [data-text])` with the renderer stamping a stable
+marker attribute on every such element regardless of the resolved tag —
+so a promoted `<h2 level="2" variant="heading">` keeps its component
+styling instead of silently falling back to bare-tag `:where(hN)`
+defaults elsewhere in the cascade. Any component that can render under a
+tag other than its own name needs the same tag-independent scope check.
+
 ## Hard rules
 
 1. **Zero raw color values** anywhere in component CSS
@@ -139,7 +156,8 @@ mechanics; never work from this summary alone):
   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;
-  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
+  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070;
+  `badge-ui[weight]` → `icon-ui[weight]`, ADR-0100).
 
 Beyond the global grammar, ADR-0063
 (`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven

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

@@ -123,6 +123,15 @@ per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
 validator enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier
 yamls (web-modules) now carry a v1.0 sidecar too and land in `adia.shells`.
 
+Once a component earns a `component.md` (both `screenReader:` and
+`behavioral:` authored, gh#2615), a non-empty `allowedParents`/
+`allowedChildren` also generates an enforced lint rule (LLD-0016 §C4,
+gh#2647): `scripts/build/gen-composition-rules.mjs` emits `scripts/lint/
+rules/generated/composition/<name>.mjs`, which flags a markup file where
+the tag nests under (or contains) a non-declared tag. Advisory (`warn`)
+until a corpus-wide rollout promotes it (`npm run build:composition-rules`
+/ `check:composition-rules-fresh`).
+
 ---
 
 ## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)
@@ -190,14 +199,18 @@ reported repro):
 { "id": "kpi-revenue", "component": "Card", "children": ["kpi-revenue-label", "kpi-revenue-value"] }
 ```
 
-**Enforcement**: `scripts/verify/check-example-ids.mjs` walks every yaml's
-`examples[].a2ui` nodes and reports ids that fail the grammar (a bare
-1-2 char id, a `^[a-z]\d+` positional pattern like `k1`/`c2`, non-kebab-case,
-or a within-example duplicate). gh#2492 Phase 2 swept the corpus-wide 526
-violations across 48 files to zero and flipped the gate to `npm run
-check:example-ids:strict` in the `npm run check` chain (non-zero exit on
-any violation) — a new example that violates the grammar now fails the
-build immediately, not just on a future sweep. Known gap: the checker's
+**Enforcement**: the `EXAMPLE-ID-GRAMMAR` rule
+(`scripts/lint/rules/shared/example-id-grammar.mjs`, gh#2649 — moved out of
+the retired `scripts/verify/check-example-ids.mjs` into the shared lint
+rule bank per LLD-0016 §C3) walks every yaml's `examples[].a2ui` nodes and
+reports ids that fail the grammar (a bare 1-2 char id, a `^[a-z]\d+`
+positional pattern like `k1`/`c2`, non-kebab-case, or a within-example
+duplicate). gh#2492 Phase 2 swept the corpus-wide 526 violations across 48
+files to zero; `npm run check:example-id-grammar` keeps that promotion
+build-blocking in the `npm run check` chain (non-zero exit on any
+violation) even though the rule's own bank-default severity is
+`advisory` — a new example that violates the grammar now fails the build
+immediately, not just on a future sweep. Known gap: the checker's
 positional-pattern regex catches `letter+digits` (`k1`, `c2`) but not a
 `letter-digit-letter-digit` chain like `g1i1` — out of scope for this
 sweep (nothing flagged it), left for a future refinement.
@@ -388,6 +401,22 @@ already has). As of this writing `deriveProps()` still synthesizes only the
 three props above and `catalog-validator.js` has no trait-name check —
 gh#2513 tracks the build.
 
+### Sentinel-0 defaults and tag-promoting props (ADR-0102, 2026-09-01)
+
+Not every escape hatch belongs on `CatalogComponentCommon` — a prop scoped
+to one component's own semantics stays on that component's own yaml, even
+when it changes the rendered tag. `text-ui`'s `level` (integer 0-6,
+default `0`) is the worked example: `0` is the sentinel for "no
+promotion, current behavior" — the same `0 = off` convention `text-ui`'s
+own `lines` prop already used (`lines: 0` = no clamp) — and `1`-`6`
+promotes the rendered element to a real native `<h1>`-`<h6>`, independent
+of `variant` (which stays presentational-only: typography tokens, never a
+tag). `deriveProps()` needs no change for this — a per-sidecar prop like
+`level` already flows into the generated catalog schema generically; only
+a `CatalogComponentCommon` universal (`slot`/`hidden`/`ariaLive`/`traits`,
+above) needs a wire-schema edit. See ADR-0102 for the full contract
+(renderer branch, dead-code removal, non-goals).
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.
@@ -502,9 +531,9 @@ section IS that call. The family stays `data-*`, undeclared in any yaml,
 with its contract documented at the shared source instead: `core/form.js`'s
 own header JSDoc (the mixin all consumers share) and the canonical
 `form-system` pattern doc (`packages/web-components/patterns/form-system/
-form-system.examples.html`, mirrored at `site-a2ui/pages/
-site__patterns__form-system.a2ui.json`) — both already enumerate the full
-family with a worked example. A future architectural pass that wants to
+form-system.examples.html`, rendered directly at `/site/patterns/form-system`)
+— both already enumerate the full family with a worked example. A future
+architectural pass that wants to
 promote this to a declared per-component contract needs its own ADR (the
 scope is a mixin-wide contract change, not a small-ticket edit); nothing
 here forecloses that, it only records today's call.
@@ -538,9 +567,9 @@ npm run check:genui-catalog                    # the drift gate that fails PR CI
 
 Any yaml change that alters a sidecar's prop schemas STALES the genui
 catalog. The main regen chain (`harvest:chunks` → `build:embeddings:chunks`
-→ `site-a2ui --stale` → `build:patterns-index`) does NOT cover it — it's a
-separate derivation with its own gate, and skipping it passes every local
-check that isn't `check:genui-catalog` itself.
+→ `build:patterns-index`) does NOT cover it — it's a separate derivation
+with its own gate, and skipping it passes every local check that isn't
+`check:genui-catalog` itself.
 
 ---
 

package/skills/site-docs-authoring/SKILL.md

@@ -47,21 +47,19 @@ skill routes to it and enforces it, it does not restate it.
 ## Verify after any change
 
 - `npm run check:links` — intra-repo links across the touched pages.
-- `node scripts/build/site-a2ui.mjs --page <route>` for every page whose
-  **markup** changed — regenerates the compiled A2UI artifact the
-  docs-transpiler produces from this source; a CSS-only fix needs no regen.
+  (Before ADR-0072 Decision 2 / gh#2410 retired site-a2ui, a markup change
+  also needed `node scripts/build/site-a2ui.mjs --page <route>` to
+  regenerate a compiled A2UI artifact. The docs site now renders each
+  route's fragment directly — no compile step, no artifact to regenerate.)
 - `npm run verify:contrast` for any new or changed token used for text or
   link contrast (that gate covers text/link AA pairs only — a non-text 3:1
   claim needs a hand-proved, cited ratio; no mechanical runner exists).
 - `npm run check:lightningcss-build` after any CSS change (`site/site.css`
   or a component's own `.css`).
 - **Visually verify any `alert-ui`/rich-slotted-content change in a
-  browser after regenerating** — a `valid:true` transpiler result and a
-  correct raw-HTML source do not prove the rendered order is correct;
-  the compiled `site-a2ui/pages/*.json` artifact is what's served, and
-  a wrong container tag (`<span>` instead of `<div>`) silently reorders
-  content while still passing schema validation. This is not optional
-  for this one content shape.
+  browser** — a wrong container tag (`<span>` instead of `<div>`) still
+  silently reorders mixed inline content on render even without a compile
+  step; this is not optional for this one content shape.
 
 A check that cannot run (missing script, no network for a build step) is a
 named blocker in the report — flag it and stop; never mark the page done on

package/hooks/hooks.json

@@ -1,44 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/sidecar-prewrite-guard\" --hook"
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/release-pretag-docs-gate\" --hook",
-            "timeout": 90
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Write|Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/forge-lint\" --hook"
-          },
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/demo-postwrite-pattern-gate\" --hook"
-          },
-          {
-            "type": "command",
-            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/site-postwrite-derivation-gate\" --hook"
-          }
-        ]
-      }
-    ]
-  }
-}