@adia-ai/adia-ui-forge 0.8.59 → 0.8.61

package/skills/package-release/scripts/stale-copy-warning.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// stale-copy-warning.mjs: generalizes release-pack.mjs's own STALE-COPY
+// WARNING (ticket #3943 item 2, gh#3764 line 55) into a small helper this
+// skill's own scripts can share.
+//
+// WHY
+//
+// A script reached through an installed plugin cache
+// (`~/.claude/plugins/cache/...`) only refreshes on a version bump, so
+// running it mid-cycle can execute a version that predates the repo's own
+// copy at the same relative path. This is invisible to a repo grep: the
+// grep reads the repo's own, already-corrected file, while the running
+// process reads the cache's stale one: the filer of ticket #3943 hit this
+// exact shape twice in one night (gh#3886, and the filing session itself).
+//
+// This module names ONE detector and ONE formatter, both pure, plus a thin
+// convenience wrapper a script calls once near its own entrypoint. It never
+// errors and never exits the caller's process: per the ticket's own
+// framing, this is a documented check, not a gate: the repo copy is
+// "almost certainly newer," never provably so from bytes alone, so the
+// right response is a loud, named warning, not a failure.
+//
+// PACKAGE-LOCAL BY DESIGN (ticket #3943's own check:pr-ready finding): this
+// file lives here, inside package-release/scripts/, rather than the repo's
+// top-level scripts/lib/, because this skill publishes as its own npm
+// package (`@adia-ai/adia-ui-forge`, PACKAGE_ROSTER). A script inside that
+// package importing a file OUTSIDE its own package root resolves fine in a
+// pnpm worktree but is an unresolvable specifier once packed
+// (`npm run check:packed-imports`, which caught exactly this on the first
+// draft of this change: an escaped-root import out of the tarball). Same
+// reasoning `bump.mjs`'s own inlined `isEntryPoint()` already states for
+// not importing `scripts/lib/is-entry-point.mjs`; this file follows that
+// same precedent (its own inlined entry-point check below, no cross-
+// package import) rather than introducing a second copy of the hazard.
+// A future repo-TOOLING script under the top-level `scripts/` tree (never
+// packaged into any tarball) that wants this same pattern is free to copy
+// this file's own two pure functions there; nothing here assumes only one
+// copy may ever exist, the packaging boundary is exactly why one shared
+// copy cannot serve both sides.
+//
+// USAGE (a script inside this same package, e.g. a sibling in
+// package-release/scripts/):
+//
+//   import { warnIfStaleCopy } from './stale-copy-warning.mjs';
+//   warnIfStaleCopy(import.meta.url, REPO_ROOT, 'path/relative/to/REPO_ROOT/this-script.mjs');
+//
+// SELFTEST:
+//
+//   node packages/plugins/adia-ui-forge/skills/package-release/scripts/stale-copy-warning.mjs selftest
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Pure: compares `selfPath`'s own bytes against the repo's copy at
+ * `repoRoot/relativePath`. Returns `null` when there is nothing to warn
+ * about (no repo copy exists to compare against, `selfPath` already IS the
+ * repo copy, or the bytes agree); otherwise `{ repoCopyPath, selfPath }`,
+ * both resolved absolute paths.
+ * @param {{selfPath: string, repoRoot: string, relativePath: string, readFile?: Function, fileExists?: Function}} args
+ * @returns {{repoCopyPath: string, selfPath: string} | null}
+ */
+export function detectStaleCopy({ selfPath, repoRoot, relativePath, readFile = fs.readFileSync, fileExists = fs.existsSync }) {
+  const resolvedSelf = path.resolve(selfPath);
+  const repoCopyPath = path.resolve(repoRoot, relativePath);
+  if (!fileExists(repoCopyPath)) return null; // nothing at the repo's own path to compare against
+  if (resolvedSelf === repoCopyPath) return null; // already running the repo's own copy
+  let selfText;
+  let repoText;
+  try {
+    selfText = readFile(selfPath, 'utf8');
+    repoText = readFile(repoCopyPath, 'utf8');
+  } catch {
+    return null; // unreadable on either side; nothing this check can prove
+  }
+  if (selfText === repoText) return null;
+  return { repoCopyPath, selfPath: resolvedSelf };
+}
+
+/**
+ * Pure: renders `detectStaleCopy`'s own non-null result as the printable
+ * warning block, the same shape release-pack.mjs's own inline check used.
+ * @param {{repoCopyPath: string, selfPath: string}} hit
+ * @returns {string}
+ */
+export function formatStaleCopyWarning({ repoCopyPath, selfPath }) {
+  return [
+    '',
+    `⚠  STALE-COPY WARNING: this ${path.basename(selfPath)} differs from the repo's own copy at`,
+    `   ${repoCopyPath}`,
+    "   The installed plugin cache lags the repo between cuts (ticket #3943, gh#3764 line 55);",
+    '   the repo copy is almost certainly newer, prefer running it:',
+    `     node ${repoCopyPath} <same args>`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Convenience wrapper for a script's own top-level self-check: resolves its
+ * own path from `import.meta.url`, compares it against
+ * `repoRoot/relativePath`, and logs (never throws, never exits the caller)
+ * when the two diverge. Call this once, near the top of a script's own
+ * entrypoint, before any real work.
+ * @param {string} selfUrl the caller's own `import.meta.url`
+ * @param {string} repoRoot the target repo's own root, resolved the same way the caller resolves it for everything else
+ * @param {string} relativePath this script's own path, relative to `repoRoot`
+ * @param {{log?: Function}} [opts]
+ * @returns {boolean} whether a warning was logged
+ */
+export function warnIfStaleCopy(selfUrl, repoRoot, relativePath, { log = console.error } = {}) {
+  const selfPath = fileURLToPath(selfUrl);
+  const hit = detectStaleCopy({ selfPath, repoRoot, relativePath });
+  if (hit) log(formatStaleCopyWarning(hit));
+  return hit !== null;
+}
+
+// ---- selftest -------------------------------------------------------------
+
+function selftest() {
+  let ran = 0;
+  const assert = (cond, msg) => {
+    ran += 1;
+    if (!cond) throw new Error(`selftest failed: ${msg}`);
+  };
+
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'stale-copy-warning-'));
+  try {
+    const repoRoot = path.join(sandbox, 'repo');
+    const relativePath = path.join('scripts', 'thing.mjs');
+    const repoCopyPath = path.join(repoRoot, relativePath);
+    const cachePath = path.join(sandbox, 'cache-copy.mjs');
+    fs.mkdirSync(path.dirname(repoCopyPath), { recursive: true });
+
+    // Positive control: cache bytes differ from the repo's own copy.
+    fs.writeFileSync(repoCopyPath, 'v2 (repo, newer)\n');
+    fs.writeFileSync(cachePath, 'v1 (cache, stale)\n');
+    const diverged = detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath });
+    assert(diverged !== null, 'differing bytes must be detected');
+    assert(diverged.repoCopyPath === path.resolve(repoCopyPath), 'the hit names the resolved repo copy path');
+    const warning = formatStaleCopyWarning(diverged);
+    assert(warning.includes('STALE-COPY WARNING'), 'the formatted warning names itself');
+    assert(warning.includes(repoCopyPath), 'the formatted warning cites the repo copy path');
+
+    // Negative control: bytes agree.
+    fs.writeFileSync(cachePath, 'v2 (repo, newer)\n');
+    assert(
+      detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath }) === null,
+      'identical bytes must never warn',
+    );
+
+    // Negative control: the "self" path already IS the repo's own copy
+    // (release-pack.mjs's own first guard: never warn about itself).
+    assert(
+      detectStaleCopy({ selfPath: repoCopyPath, repoRoot, relativePath }) === null,
+      'running the repo copy directly must never warn',
+    );
+
+    // Negative control: no repo copy exists at all (nothing to compare
+    // against, e.g. a script the repo has since deleted).
+    assert(
+      detectStaleCopy({ selfPath: cachePath, repoRoot, relativePath: path.join('scripts', 'gone.mjs') }) === null,
+      'a missing repo copy must never warn (nothing provable)',
+    );
+
+    // warnIfStaleCopy: the convenience wrapper logs on divergence and
+    // reports it, using a real file:// URL the way a real caller's
+    // import.meta.url would.
+    fs.writeFileSync(cachePath, 'v1 (cache, stale)\n');
+    let logged = '';
+    const warned = warnIfStaleCopy(
+      new URL(`file://${cachePath}`).href,
+      repoRoot,
+      relativePath,
+      { log: (msg) => { logged += msg; } },
+    );
+    assert(warned === true, 'warnIfStaleCopy reports true when it warns');
+    assert(logged.includes('STALE-COPY WARNING'), 'warnIfStaleCopy actually logs the warning text');
+
+    // And stays silent (never throws, never exits) when bytes agree.
+    fs.writeFileSync(cachePath, 'v2 (repo, newer)\n');
+    let loggedAgain = '';
+    const clean = warnIfStaleCopy(
+      new URL(`file://${cachePath}`).href,
+      repoRoot,
+      relativePath,
+      { log: (msg) => { loggedAgain += msg; } },
+    );
+    assert(clean === false, 'warnIfStaleCopy reports false when bytes agree');
+    assert(loggedAgain === '', 'warnIfStaleCopy logs nothing when bytes agree');
+  } finally {
+    fs.rmSync(sandbox, { recursive: true, force: true });
+  }
+
+  console.log(`stale-copy-warning selftest, all assertions passed, ${ran} controls ran`);
+  return 0;
+}
+
+// Realpath-safe entry-point check, inlined rather than imported from the
+// top-level scripts/lib/is-entry-point.mjs (see the package-local-by-design
+// note above); mirrors bump.mjs's own identical inlining in this same dir.
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const topArgv = process.argv.slice(2);
+  process.exit(topArgv[0] === 'selftest' ? selftest() : 0);
+}

package/skills/package-release/scripts/tag-lockstep.mjs

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { warnIfStaleCopy } from './stale-copy-warning.mjs';
 import { PACKAGE_ROSTER } from './package-paths.mjs';
 
 // The roster is single-sourced in package-paths.mjs (H3) — the `adia-ui-*-v*`
@@ -60,6 +61,13 @@ function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to run git against a non-monorepo directory.
   assertMonorepoRoot(args.repo);
+  // Stale-plugin-cache self-check (ticket #3943 item 2), same primitive
+  // release-pack.mjs's own top-level check now calls.
+  warnIfStaleCopy(
+    import.meta.url,
+    args.repo,
+    'packages/plugins/adia-ui-forge/skills/package-release/scripts/tag-lockstep.mjs',
+  );
   const tags = buildTagList(args.version);
 
   if (args.deleteMode) {

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

@@ -30,6 +30,7 @@ file, including the depth references those entries cross-link.
 ## Demos & doc surfaces
 
 - [composite-demo-protocol.md](composite-demo-protocol.md) — what discipline governs any `packages/web-modules/**` demo edit, beyond what the `Pattern source:` gate can see?
+- [examples-structure.md](examples-structure.md): what order do a primitive's own `<name>.examples.html` `<h2 variant="section">` blocks follow, and where does `Typography registers` sit relative to `Edge Cases` and the generated API tail?
 - [canonical-pattern-index.md](canonical-pattern-index.md) — which canonical `.contents.html` files should I survey for a given UI type? Auto-generated; regenerate via `scripts/build-canonical-pattern-index.mjs`.
 - [trait-pages.md](trait-pages.md) — which sections, in which order, must a `site/pages/traits/<name>/` detail page carry (ADR-0019 template)?
 

package/skills/primitive-authoring/references/examples-structure.md

@@ -0,0 +1,52 @@
+# `<name>.examples.html` section order convention
+
+Every primitive's own `packages/web-components/components/<name>/<name>.examples.html`
+follows one binding `<h2 variant="section">` order. gh#4159: a merged-registers sweep
+(gh#3843) found the order inconsistent across five files, `alert` had "Typography
+registers" near the top, `code`/`command` had it after the generated API tail, and
+`accordion`/`divider` had it before Edge Cases, with no reference doc anywhere stating
+which shape was correct. `site-docs-authoring`'s own `intent.md` explicitly declines
+`packages/web-components/components/*/*.examples.html` and hands it here; this file is
+that hand-off's landing spot.
+
+## Required order
+
+1. **Variant/usage sections**, one `<h2 variant="section">` per prop value, state, or
+   usage recipe the component demonstrates (`inline`, `block with language`, `grouped`,
+   …). Author-ordered; no fixed sequence among these.
+2. **`Combinations`**, sections composed together in context.
+3. **`Typography registers`**, the three-register (`scale="ui-sm"` / regular /
+   `scale="content-md"`) showcase, when the component carries one. Hand-authored, so it
+   sits with the other hand-authored sections above, immediately after `Combinations`
+   and before `Edge Cases`, never after the generated API tail.
+4. **`Edge Cases`**, boundary conditions and unusual content.
+5. **Generated API sections**, in order: `Properties`, `Events`, `Methods` (when
+   applicable), `CSS Tokens`, `Slots`, `A2UI`, `Related`.
+
+Rationale for `Typography registers` landing before `Edge Cases` rather than after the
+API tail: it is hand-authored prose+markup like `Combinations`/`Edge Cases`, not a
+generated table like `Properties`/`Events`/`CSS Tokens`; grouping it with the other
+hand-authored sections keeps the generated-vs-authored boundary at one place in the file
+instead of two.
+
+## Why this also matters for `.examples.md`
+
+`scripts/build/generate-examples-md.mjs` derives each `<name>.examples.md` from the
+`.examples.html` source. Its main loop picks only the first `MAX_FRAGMENTS` (3)
+`data-section` blocks in document order, so a section sitting far down the file (several
+variant sections deep, as most shipped components run) would normally never be selected.
+`Typography registers` is the one named exception: `processComponent()` guarantees its
+inclusion regardless of ordinal position, so this convention is about authoring
+coherence and readability, not about whether the section survives derivation at all.
+
+## Enforcement
+
+`generate-examples-md.mjs`'s own `checkSectionOrder()`, run as part of `npm run
+check:examples-md-fresh` (`--verify` mode) and the plain generate run alike, parses
+every `packages/web-components/components/*/*.examples.html`'s ordered `<h2
+variant="section">` list and reds, naming the file and both indices, when `Typography
+registers` sits after `Edge Cases`. Pre-existing violations outside a given PR's own
+lane are grandfathered via `scripts/build/examples-registers-order-baseline.json` (a
+ratchet: printed as an advisory finding, never silently dropped, and never allowed to
+grow) so the gate never regresses unrelated work; shrink that list to zero as each
+file's own section order gets fixed.

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

@@ -448,17 +448,18 @@ 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)
-- **Tests** — `admin-sidebar.test.js` 10/10, `admin-command.test.js` 9/9
+**[deprecated 2026-09-01, ADR-0098]** The inline child enumeration this section
+used to carry is retired. `admin-page`/`admin-page-header`/`admin-page-body`
+were deleted outright (no compat alias); `admin-scroll` was renamed wholesale
+to `page-scroll`, and its own one-release deprecation window has since closed,
+the module deleted (gh#3745). `page-ui[band]` + `page-scroll` are the canonical
+page-chrome pair.
+
+For `admin-shell`'s own live composition, the current bespoke children (the
+`@scope`-per-tag CSS convention landed in gh#4103), and the full 13-part
+canonical anatomy, see
+[admin-shell-anatomy.md](../../demo-audit/references/admin-shell-anatomy.md),
+kept in sync with `site/index.html`'s live example rather than restated here.
 
 ### chat cluster (replicated pattern)
 

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

@@ -102,7 +102,7 @@ tag other than its own name needs the same tag-independent scope check.
 
 - `chart.css` data slots reference `--a-data-0..9` (tokens, not raw)
 - `card.css` mask uses `--a-chrome-light` (mask is opacity-only; value is semantic)
-- Drawer/modal scrims use `--a-chrome-backdrop`
+- Drawer/modal scrims use `--a-scrim-dialog` (aliases.css, gh#373: routes to `--a-chrome-scrim-dialog`, 80% black, not `--a-chrome-backdrop`)
 
 If you find a raw value elsewhere, either:
 
@@ -118,7 +118,7 @@ Added in v0.5.0 — use these for UI chrome:
 - `--a-chrome-border` — subtle hairline borders
 - `--a-chrome-ring-subtle` — focus rings, outlines
 - `--a-chrome-shadow-soft` — elevation shadows
-- `--a-chrome-backdrop` — modal/drawer backdrops
+- `--a-chrome-backdrop` - generic 50% chrome overlay, reserved for non-dialog UI chrome; no current consumers. Modal/drawer backdrops use `--a-scrim-dialog` instead (80% black, gh#373, see `--a-chrome-scrim-dialog` in features.css' CHROME block)
 
 ## Data palette
 

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

@@ -89,13 +89,26 @@ check) is unaffected either way — it only checks for a slot literally named
 ## `a2ui.allowedParents:` / `a2ui.allowedChildren:` — composition constraints (SPEC REQ-011, gh#1353)
 
 Optional keys inside the `a2ui:` block, alongside `rules:`. Each is a
-non-empty list of catalog `component:` names (NOT tags) naming the direct
-parents this component may sit under / the direct children it may contain.
-The reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
+non-empty list of catalog `component:` names (NOT tags) naming the parents
+this component may sit under / the direct children it may contain. The
+reserved name `Surface` (the A2UI v1.0 implicit root container) is legal
 only in `allowedParents` and means "may sit at the surface root". **Omitted
 means unconstrained** — never write an empty list (that would mean "allowed
 nowhere"; the build refuses it).
 
+`allowedParents` matches the nearest custom-element ancestor, not the
+immediate DOM parent (gh#3310): the generated lint rule's
+`compositionFindings()` walks up past native (non-hyphenated) wrapper
+elements — `section`, `div`, `td`, `tr`, `tbody`, and any other plain HTML
+tag — until it finds a real catalog component tag or reaches the surface
+root. This mirrors Light DOM's own composition reality (AGENTS.md: CSS
+positions by tag + ancestor + DOM order) — a wrapper interposed for layout
+or semantics (a `<section>` inside a card, a `<td>` in a table body) doesn't
+change a component's logical host. `allowedChildren`, by contrast, still
+matches DIRECT children only — a named-slot child that should be exempt
+from the default-slot list is a separate, open gap (gh#3308), not addressed
+by this semantics change.
+
 ```yaml
 a2ui:
   allowedParents:
@@ -112,6 +125,35 @@ children). A parent that adopts items through wrappers (menu.class.js's
 deliberate descendant query) must NOT constrain — a declared constraint
 stricter than the source is a defect, not documentation.
 
+**`allowedChildren` is a default-slot-only check (gh#3308).** A direct
+child carrying ANY `slot=` attribute is a sibling-level named slot, not a
+default-slot member — the lint-side matcher (`compositionFindings`)
+exempts it from `allowedChildren` entirely, regardless of the slot's name.
+This is why menu-ui can declare `allowedChildren: [MenuItem, MenuDivider,
+MenuLabel]` for its default slot while still accepting an arbitrary
+focusable element on `slot="trigger"` ("typically button-ui, but any
+focusable element works") without a false positive. When a named slot
+*should* be constrained too (rare — most named slots exist precisely
+because their content varies), add an `allowedChildrenBySlot:` map
+alongside `allowedChildren:`, keyed by slot name, same catalog-name-list
+shape:
+
+```yaml
+a2ui:
+  allowedChildren:
+    - MenuItem
+    - MenuDivider
+    - MenuLabel
+  allowedChildrenBySlot:
+    trigger:               # only if the trigger slot ITSELF needs constraining
+      - ButtonUI
+```
+
+A slot with no entry in `allowedChildrenBySlot` (or the key omitted
+entirely) stays unconstrained by design — this is the common case, and
+matches "omitted means unconstrained" for `allowedChildren`/`allowedParents`
+above.
+
 Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
 referenced name against the full catalog on a full build, and forwards the
 lists onto `x-adiaui` → `catalog-a2ui_1_0.json`.
@@ -122,16 +164,71 @@ per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
 `adia.shells.json`, gh#2211/ADR-0093), where the vendored `@genui/core`
 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/
+`allowedChildrenBySlot` (gh#3308) is NOT part of this catalog/sidecar
+pipeline — `components.mjs` never reads it, it never lands in
+`x-adiaui`/`catalog-a2ui_1_0.json`, and the A2UI v1.0 protocol validator
+never enforces it. It exists purely for the lint-side check below.
+
+A non-empty `allowedParents`/`allowedChildren`/`allowedChildrenBySlot`
+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`)
+the tag nests under (or contains) a non-declared tag — `allowedChildren`
+checked against default-slot children only, `allowedChildrenBySlot`
+against the matching named-slot children (see above). Advisory (`warn`)
 until a corpus-wide rollout promotes it (`npm run build:composition-rules`
 / `check:composition-rules-fresh`).
 
+### `a2ui.noCompositionConstraint:`: the audited "no contract needed" verdict (lld-0029 C2a, PR #3456)
+
+The third disposition a yaml can carry. Where `allowedParents` /
+`allowedChildren` declare a containment edge, `noCompositionConstraint`
+records that the authoring-rule audit above was actually run (read
+`<name>.class.js` for `querySelector` / `closest` / `this.children`
+child-tag expectations, then test any parent/child hypothesis against real
+markup in `apps/`, `site/`, `catalog/`, `packages/web-components/patterns/`)
+and found no constraint worth declaring. Its whole purpose is to let a
+reader, or a gate, tell "audited, categorically needs none" apart from
+"never audited". Do not write it as a shortcut: if the audit turns up a
+real constraint, the fix is a genuine `allowedParents` / `allowedChildren`
+addition, not this marker.
+
+Shape (`scripts/schemas/component.yaml.schema.json`, `a2ui.noCompositionConstraint`):
+an object with two required keys and nothing else. `reason` is the verdict
+quoted from the disposition table (schema `minLength: 8`); `ticket` is the
+issue whose table recorded it (`^gh#[0-9]+$`). As with every other schema
+constraint (ADR-0057), the shape is IDE-visible only: `compileComponent()`
+never reads this key, so a malformed block does not stop the build.
+
+Real example, `packages/web-components/components/badge/badge.yaml`:
+
+```yaml
+a2ui:
+  noCompositionConstraint:
+    reason: 'Referenced generically from a dozen+ unrelated components, not scoped to one parent; own rule says positioning, not ancestry.'
+    ticket: 'gh#3270'
+  rules:
+    - 'Use for small status/count labels attached to another element (notification counts, status pills, version tags).'
+```
+
+Relationship to the two lists. A yaml carries either the marker or a
+containment list, never both. This is now enforced (gh#3497), not just
+convention: `component.yaml.schema.json` declares the two mutually
+exclusive via the `a2ui` object's own `not` clause, and
+`compileCompositionConstraints()` in `scripts/build/components.mjs` throws
+at build time, naming the file and the offending field, when a yaml
+declares both. `npm run check:components-valid` (part of `npm run
+build:components`) is where that throw surfaces.
+
+Pipeline: none. The marker is a yaml-only annotation with no sidecar,
+`x-adiaui`, catalog, or generated-lint-rule forwarding (lld-0029 C2a, by
+design), so a PR that only adds it changes no derived artifact and commits
+no regen. The planned `check:composition-coverage` gate (lld-0029 C3,
+`scripts/verify/check-composition-coverage.mjs`, not landed as of
+2026-09-04) fails any yaml whose `a2ui` block has none of `allowedParents`,
+`allowedChildren`, or `noCompositionConstraint`, so the marker counts as
+coverage exactly as either list does.
+
 ---
 
 ## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)