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

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

@@ -516,6 +516,75 @@ const EVAL_HEALTH_CHAIN_NUMBERS = [16, 27, 28]; // eval:diff zettel → eval:dif
 // for a dedicated/idle host.
 const PREFLIGHT_CONCURRENCY = Number(process.env.PREFLIGHT_CONCURRENCY) || 4;
 
+// gh#2195 — gate 4 flake-retry, scoped to the solo phase only.
+//
+// gh#2195's own diagnosis found two mechanisms behind "test:unit:serial
+// flakes under host load": a real wall-clock timing race in one test (fixed
+// separately, PR #2290) and genuine 45s timeouts under contention on the
+// same shared, multi-tenant host an operator or agent session runs
+// everything else on. There is no separate "release pre-flight runner" with
+// its own core count to recalibrate worker-cap.mjs against — Phase 1 above
+// already runs gate 4 solo, with no sibling PRE-FLIGHT gate competing, so
+// what is left is contention from OTHER, unrelated concurrent processes on
+// that same host (other agents' builds, other `npm run check` runs) that no
+// single process's static worker-cap formula can see or size against.
+//
+// A file that fails once under that kind of contention and then passes
+// clean on an immediate, unmodified re-run was never proving a code
+// regression — gate 4 exists to prove one, and a transient scheduling stall
+// isn't that. A file that fails twice in a row almost certainly is a real
+// regression (a genuine bug reproduces deterministically; host contention
+// does not), so this retries AT MOST ONCE, and only the files gate 4 itself
+// named as failed — never the whole suite, never a second retry. Scoped to
+// gate 4's solo phase alone: every other gate, and every OTHER invocation of
+// `npm run test:unit:serial` (CI, local dev, `npm run check`), stays
+// single-shot and strict — this never masks a real regression anywhere else.
+const FAILED_TEST_FILE_RE = /^ FAIL\s+(\S+)/gm;
+
+// Pure — extracts the deduped list of failed test file paths from vitest's
+// default-reporter output. Its "Failed Tests" section prints a leading
+// ` FAIL  <file> > ...` line per failing test — the same line is emitted for
+// an assertion failure and for a per-test timeout alike.
+function extractFailedTestFiles(text) {
+  const files = new Set();
+  for (const m of (text || '').matchAll(FAILED_TEST_FILE_RE)) files.add(m[1]);
+  return [...files];
+}
+
+// Runs the solo gate; on failure, extracts which file(s) it named as failed
+// and — only if at least one was parseable — retries gate 4 scoped to
+// exactly those files, once. An unparseable failure (e.g. vitest itself
+// crashed before printing a summary) fails closed: no retry, same behavior
+// as before this change.
+async function runSoloGateWithRetry(soloGate, args) {
+  const first = await runGateCaptured(soloGate, args);
+  printGateResult(first);
+  if (first.ok) return first;
+
+  const failedFiles = extractFailedTestFiles(`${first.stdout || ''}\n${first.stderr || ''}`);
+  if (failedFiles.length === 0) {
+    console.error('\n  Gate 4 failed with no parseable failed-file list — not retrying (fail closed, gh#2195).');
+    return first;
+  }
+
+  console.log(`\n  Gate 4 failed on ${failedFiles.length} file(s) — retrying once, scoped to just those files (host-contention tolerance, gh#2195):`);
+  for (const f of failedFiles) console.log(`    - ${f}`);
+  const retryGate = {
+    n: soloGate.n,
+    cmd: `${soloGate.cmd} -- ${failedFiles.map((f) => `"${f}"`).join(' ')}`,
+    what: `${soloGate.what} — retry of ${failedFiles.length} flaky file(s)`,
+  };
+  const retry = await runGateCaptured(retryGate, args);
+  printGateResult(retry);
+
+  if (retry.ok) {
+    console.log(`\n  ✓ gate 4 passed on retry — treating the first failure as host contention, not a regression (gh#2195).`);
+    return { ...retry, note: `passed on retry after 1 failure (gh#2195 host-contention tolerance); first attempt failed: ${failedFiles.join(', ')}` };
+  }
+  console.error('\n  Gate 4 failed again on retry — a real regression, not a flake. Aborting.');
+  return { ...retry, note: `failed again on retry (gh#2195); first attempt failed: ${failedFiles.join(', ')}` };
+}
+
 // Resolves one gate's actual command string — the same versionArg/
 // targetVersionArg/resume branching step3PreFlight has always applied.
 // Returns null for a versionArg gate deferred by an in-flight resume (Step
@@ -656,8 +725,7 @@ async function step3PreFlight(args) {
   const poolGates = GATE_ROSTER.filter((g) => g.n !== SOLO_GATE_NUMBER && !chainNumbers.has(g.n));
 
   console.log(`\n-- Phase 1/2: gate ${SOLO_GATE_NUMBER} solo (test:unit:serial) --`);
-  const soloResult = await runGateCaptured(soloGate, args);
-  printGateResult(soloResult);
+  const soloResult = await runSoloGateWithRetry(soloGate, args);
   if (!soloResult.ok) {
     console.error('\n  Pre-flight aborted at Phase 1 — fix the gate failure before proceeding.');
     console.error('  See references/gates-catalog.md for failure-mode → recovery.');
@@ -799,10 +867,11 @@ function step4PromoteAndBump(args) {
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
 
-  // Step 4d.5 — regenerate the derived genui catalog (gh#617): its catalogId
-  // embeds the lockstep version (`adia.base@X.Y.Z`), so the bump above just
-  // invalidated base.json/adia-pack.json. The v0.8.26 cut skipped this and
-  // check:genui-catalog failed in CI one push later. Step 5 stages both files.
+  // Step 4d.5 — regenerate the derived genui catalog (gh#617; gh#2211/ADR-0093
+  // repartitioned): each catalog's catalogId embeds the lockstep version
+  // (`adia.<scope>@X.Y.Z`), so the bump above just invalidated all five.
+  // The v0.8.26 cut skipped this and check:genui-catalog failed in CI one
+  // push later. Step 5 stages all five files.
   console.log('\n  Step 4d.5 — regenerate derived genui catalog (catalogId carries the lockstep version):');
   sh('node scripts/build/derive-genui-catalog.mjs', args);
 
@@ -907,6 +976,39 @@ function step4PromoteAndBump(args) {
   }
 }
 
+// Pure so the selftest can lock the parse without a real git tree (gh#2473,
+// same "pure so selftest can lock the transform" shape as bump.mjs's
+// bumpPinnedRef). Takes `git status --porcelain` output, returns the tracked
+// paths Step 5.6's guard should block on — worktree status (porcelain
+// column Y, index 1) 'M' or 'D'; 'A'/'?' (new/untracked) are out of scope,
+// see the guard's own comment. Handles the two porcelain path shapes a
+// plain `line.slice(3)` mishandles: C-style-quoted paths (git quotes any
+// path containing a space, or a rename's `->` separator surrounded by
+// spaces) and rename/copy entries (`R  old -> new`, `C  old -> new`),
+// where the file that actually needs staging is the NEW path.
+function unstagedTrackedLeftovers(porcelainOutput) {
+  const leftover = [];
+  for (const line of porcelainOutput.split('\n')) {
+    if (line.length <= 3 || !/[MD]/.test(line[1])) continue;
+    let rest = line.slice(3).trim();
+    // Rename/copy: "old -> new" (both sides may independently be quoted) —
+    // the worktree-dirty path to report is the NEW (post-rename) side.
+    const arrow = rest.indexOf(' -> ');
+    if (arrow !== -1) rest = rest.slice(arrow + 4).trim();
+    // git C-quotes a path containing a space, a quote, or a control char as
+    // a double-quoted, backslash-escaped string — strip the wrapper and
+    // undo the escaping rather than reporting the literal quoted form.
+    if (rest.length >= 2 && rest[0] === '"' && rest[rest.length - 1] === '"') {
+      rest = rest
+        .slice(1, -1)
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    }
+    leftover.push(rest);
+  }
+  return leftover;
+}
+
 // ── Step 5 — Commit ──────────────────────────────────────────────
 function step5Commit(args) {
   if (args.mode === 'handoff') {
@@ -956,14 +1058,18 @@ function step5Commit(args) {
     `docs/ops/releases/v${args.version}.md`,
     // gh#617: Step 4d.5 regenerates these post-bump (catalogId embeds the
     // lockstep version); unstaged, check:genui-catalog fails in CI (v0.8.26).
-    // catalog-data.js is the same derivation's third output (the browser-safe
-    // ES-module projection of base.json/adia-pack.json) — check-genui-catalog.mjs
-    // verifies its freshness too, but this list never carried it (found live
-    // during the v0.8.33 cut: base.json/adia-pack.json staged and committed
-    // fine, catalog-data.js sat modified-uncommitted, CI caught the drift a
-    // fresh checkout exposes that a local working tree doesn't).
-    'packages/genui/adia-catalog/base.json',
-    'packages/genui/adia-catalog/adia-pack.json',
+    // gh#2211 (ADR-0093): the old base/pack pair retired in favor of five
+    // opt-out-scoped catalogs. catalog-data.js is the same derivation's sixth
+    // output (the browser-safe ES-module projection of all five) —
+    // check-genui-catalog.mjs verifies its freshness too, but this list never
+    // carried it (found live during the v0.8.33 cut: the JSON catalogs staged
+    // and committed fine, catalog-data.js sat modified-uncommitted, CI caught
+    // the drift a fresh checkout exposes that a local working tree doesn't).
+    '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',
     'packages/genui/adia-catalog/catalog-data.js',
     // gh#1361: Step 4d.5b regenerates the catalog tier index post-bump (it
     // derives from the catalog derive-genui-catalog.mjs just refreshed) and,
@@ -1015,12 +1121,54 @@ function step5Commit(args) {
         // Codex `agents/openai.yaml` glob above is.
         files.push(`${dir}/plugin.yaml`, `${dir}/__init__.py`, `${dir}/prompts/*.md`);
       }
-      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`);
+      // gh#2473: bump.mjs's PINNED_REFS also rewrites the factory README's
+      // OWN prose echo of the generation-MCP pin (`server pinned:
+      // @adia-ai/mcp@X` — see bump.mjs's A2UI_MCP_PIN comment,
+      // check:plugin-count-claims' "factory README generation-MCP pin"
+      // equality check) — same invariant-8 scope as .mcp.json, but this
+      // list only ever staged .mcp.json + hermes-mcp.yaml, so the README
+      // edit rode along unstaged/uncommitted every cut until Step 5.6
+      // (below) started catching it.
+      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`, `${dir}/README.md`);
       return files;
     }),
   ];
   sh(`git add ${releaseFiles.join(' ')}`, args);
   sh('git diff --cached --stat | tail -3', args);
+
+  // Step 5.6 — unstaged-tracked-files guard (gh#2473). Numbered 5.6, not
+  // 5.5: cut-procedure.md's own §Step 5.5 already names a DIFFERENT,
+  // pre-existing manual freshness trip-wire (components.mjs --verify +
+  // check:chunks-fresh + check:embeddings-fresh) that this script doesn't
+  // automate — reusing "5.5" here would collide with that doc section for
+  // an operator reading both. This guard slots before §Step 5.7 (the
+  // release PR), the next free number in the doc's own sequence.
+  //
+  // The release commit's file allowlist above has drifted from what
+  // bump.mjs / cut-hygiene actually edit more than once (gh#1198, gh#1899,
+  // gh#1954, gh#2473 itself) — a step upstream starts writing a new file
+  // and nobody remembers to add it here, so it rides through Step 5
+  // uncommitted and either ships a half-bumped release commit or gets
+  // discovered only when a later gate (or a human diff) trips over it.
+  // Fail loud, right here, rather than trusting the allowlist is
+  // exhaustive: after staging everything this list knows about, anything
+  // STILL modified-in-the-worktree on a tracked path means the allowlist
+  // missed a file this cut's bump/hygiene pass touched.
+  if (args.dry) {
+    console.log("  [dry] git status --porcelain (Step 5.6 guard: no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched)");
+  } else {
+    const leftover = unstagedTrackedLeftovers(shQuiet('git status --porcelain', args));
+    if (leftover.length > 0) {
+      console.error(`\nERROR: ${leftover.length} tracked file(s) modified by this cut are still unstaged after Step 5's allowlist ran:`);
+      for (const f of leftover) console.error(`  ✗ ${f}`);
+      console.error('\n  bump.mjs (or a cut-hygiene step) edited these but Step 5\'s `releaseFiles`');
+      console.error('  allowlist does not know about them — add the missing path(s) and re-run,');
+      console.error('  or `git add` + `git commit --amend` them onto the release commit by hand.');
+      process.exit(1);
+    }
+    console.log("  ✓ no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched");
+  }
+
   if (!args.commitMessageFile) {
     console.error('ERROR: --commit-message-file required for cut/from-scratch mode');
     process.exit(2);
@@ -1403,9 +1551,120 @@ async function main() {
 // must never proceed to tag/push/publish on its own). A fixture temp dir
 // supplies the operator-authored content files (--commit-message-file /
 // --gh-notes-file) so nothing here depends on real repo state.
-function selftest() {
+async function selftest() {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'release-pack-selftest-'));
   try {
+    // gh#2195 — gate-4 retry: extractFailedTestFiles() must parse vitest's
+    // default-reporter ` FAIL  <file> > ...` lines, and
+    // runSoloGateWithRetry() must retry exactly once, scoped to exactly
+    // those files, accepting a clean retry as a host-contention flake but
+    // never masking a failure that reproduces, and never retrying at all
+    // when the failure has no parseable failed-file list.
+    {
+      const sample = [
+        ' FAIL  packages/a/b.test.js > describe > one',
+        ' FAIL  packages/a/b.test.js > describe > two',
+        ' FAIL  packages/c/d.test.js > describe > three',
+      ].join('\n');
+      const files = extractFailedTestFiles(sample);
+      if (files.length !== 2 || !files.includes('packages/a/b.test.js') || !files.includes('packages/c/d.test.js')) {
+        console.error(`selftest FAIL: extractFailedTestFiles() expected 2 deduped files, got: ${JSON.stringify(files)}`);
+        process.exit(1);
+      }
+
+      const flakyMarker = path.join(tmp, 'flaky-invocation-count');
+      const flakyScript = path.join(tmp, 'flaky-once.mjs');
+      fs.writeFileSync(flakyScript, `
+        import { writeFileSync } from 'node:fs';
+        const isRetry = process.argv.slice(2).includes('--');
+        if (!isRetry) {
+          writeFileSync(${JSON.stringify(flakyMarker)}, '1');
+          console.log(' FAIL  packages/fake/flaky.test.js > describe > flaky test');
+          console.error('Error: Test timed out in 45000ms.');
+          process.exit(1);
+        }
+        console.log(' retry ran clean');
+        process.exit(0);
+      `);
+      const flakyGate = { n: 4, cmd: `node "${flakyScript}"`, what: 'selftest flaky gate' };
+      const flakyResult = await runSoloGateWithRetry(flakyGate, {});
+      if (!flakyResult.ok || !flakyResult.note || !flakyResult.note.includes('packages/fake/flaky.test.js')) {
+        console.error(`selftest FAIL: runSoloGateWithRetry() must accept a clean retry as a flake; got: ${JSON.stringify(flakyResult)}`);
+        process.exit(1);
+      }
+
+      const alwaysFailsScript = path.join(tmp, 'always-fails.mjs');
+      fs.writeFileSync(alwaysFailsScript, `
+        console.log(' FAIL  packages/fake/broken.test.js > describe > broken test');
+        process.exit(1);
+      `);
+      const alwaysFailsGate = { n: 4, cmd: `node "${alwaysFailsScript}"`, what: 'selftest always-fails gate' };
+      const alwaysFailsResult = await runSoloGateWithRetry(alwaysFailsGate, {});
+      if (alwaysFailsResult.ok) {
+        console.error('selftest FAIL: runSoloGateWithRetry() must NOT mask a failure that reproduces on retry');
+        process.exit(1);
+      }
+
+      const sentinel = path.join(tmp, 'unparseable-retried');
+      const unparseableScript = path.join(tmp, 'unparseable-fails.mjs');
+      fs.writeFileSync(unparseableScript, `
+        import { existsSync, writeFileSync } from 'node:fs';
+        const sentinel = ${JSON.stringify(sentinel)};
+        writeFileSync(sentinel, existsSync(sentinel) ? 'RETRIED' : 'FIRST-RUN');
+        console.error('Segmentation fault (core dumped)');
+        process.exit(139);
+      `);
+      const unparseableGate = { n: 4, cmd: `node "${unparseableScript}"`, what: 'selftest unparseable-crash gate' };
+      const unparseableResult = await runSoloGateWithRetry(unparseableGate, {});
+      if (unparseableResult.ok) {
+        console.error('selftest FAIL: an unparseable gate-4 failure must never be treated as passing');
+        process.exit(1);
+      }
+      if (fs.readFileSync(sentinel, 'utf8') !== 'FIRST-RUN') {
+        console.error('selftest FAIL: an unparseable failure (no FAIL lines) must fail closed — no retry');
+        process.exit(1);
+      }
+    }
+
+    // gh#2473 — Step 5.6's guard: unstagedTrackedLeftovers() must find a
+    // plain modified/deleted tracked file, unquote a C-quoted path
+    // (spaces), and report the NEW side of a rename/copy — all from a
+    // fixture porcelain string, independent of `--dry` and independent of
+    // any real git tree (the `--mode cut --dry` subprocess run below can
+    // only ever prove the code path executes and prints a fixed success
+    // string; it can't reach the `else` branch at all, since `sh()`'s dry
+    // short-circuit never runs `git status`). This exercises the exact
+    // logic Step 5.6 runs for real.
+    {
+      const porcelain = [
+        ' M packages/plugins/adia-ui-factory/README.md',
+        ' D packages/plugins/adia-ui-factory/hermes-mcp.yaml',
+        'M  packages/already/staged.json', // staged-only (X=M, Y=space) — NOT a leftover
+        '?? packages/new/untracked.json', // untracked — out of scope, NOT a leftover
+        ' M "packages/has space/quoted file.md"',
+        'RM packages/old-name.md -> packages/new-name.md', // renamed AND further worktree-modified (Y=M) — a leftover
+        'R  packages/clean-rename-old.md -> packages/clean-rename-new.md', // renamed, no further worktree change (Y=space) — NOT a leftover
+      ].join('\n');
+      const leftover = unstagedTrackedLeftovers(porcelain);
+      const want = [
+        'packages/plugins/adia-ui-factory/README.md',
+        'packages/plugins/adia-ui-factory/hermes-mcp.yaml',
+        'packages/has space/quoted file.md',
+        'packages/new-name.md',
+      ];
+      const gotJson = JSON.stringify(leftover);
+      const wantMissing = want.filter((w) => !leftover.includes(w));
+      const wantExtra = leftover.filter((l) => !want.includes(l));
+      if (wantMissing.length > 0 || wantExtra.length > 0 || leftover.length !== want.length) {
+        console.error(`selftest FAIL: unstagedTrackedLeftovers() expected ${JSON.stringify(want)}, got ${gotJson}`);
+        process.exit(1);
+      }
+      if (unstagedTrackedLeftovers('').length !== 0) {
+        console.error('selftest FAIL: unstagedTrackedLeftovers() must return [] on empty porcelain output (the clean-tree case Step 5.6 hits on every normal cut)');
+        process.exit(1);
+      }
+    }
+
     const commitFile = path.join(tmp, 'commit.txt');
     const notesFile = path.join(tmp, 'notes.md');
     fs.writeFileSync(commitFile, 'selftest fixture commit message\n');
@@ -1462,6 +1721,16 @@ function selftest() {
       'packages/plugins/adia-ui-factory/__init__.py',
       'packages/plugins/adia-ui-factory/hermes-mcp.yaml',
       'packages/plugins/adia-ui-factory/prompts/*.md',
+      // gh#2473 — Step 5's staging pathspec must carry the factory README's
+      // own prose echo of the generation-MCP pin (bump.mjs's A2UI_MCP_PIN
+      // README target), or it rides unstaged/uncommitted past the release
+      // commit the same way .mcp.json itself did before gh#1198.
+      'packages/plugins/adia-ui-factory/README.md',
+      // gh#2473 — Step 5.6's unstaged-tracked-files guard must actually run
+      // (as a no-op) on a clean --dry plan. Its real leftover-detection
+      // logic is unit-tested directly above via unstagedTrackedLeftovers();
+      // this marker only proves the --dry code path reaches its console.log.
+      "no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched",
     ];
     for (const marker of need) {
       if (!out.includes(marker)) {
@@ -1597,7 +1866,10 @@ function fileURLToPathCompat(url) {
 const topArgv = process.argv.slice(2);
 if (topArgv[0] === 'selftest') {
   rl.close();
-  selftest();
+  selftest().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
 } else {
   main().catch((e) => {
     // sh()/shQuiet() failures already printed the failing command + its

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

@@ -23,8 +23,8 @@ closable: { type: Boolean, default: true, reflect: true }
 | --- | --- |
 | `modal-ui[closable]` (default `true`) | `modal-ui[permanent]` (default `false`) |
 | `skeleton-ui[animate]` | `skeleton-ui[static]` |
-| `stream-ui[cursor]` | `stream-ui[hideCursor]` |
-| `chart-ui[average]` | `chart-ui[hideAverage]` |
+| `stream-ui[cursor]` | `stream-ui[noCursor]` |
+| `chart-ui[average]` | `chart-ui[noAverage]` |
 | `toggle-group-ui[multiple]` | `toggle-group-ui[single]` |
 | `swiper-ui[pause-on-hover]` | `swiper-ui[noPauseOnHover]` |
 

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

@@ -66,8 +66,8 @@ AdiaUI conventions require `default: false` on Boolean props in the standard sha
 | --- | --- | --- |
 | Modal can be dismissed | `closable` | `permanent` |
 | Skeleton animates | `animate` | `static` |
-| Stream shows blinking cursor | `cursor` | `hideCursor` |
-| Chart shows average line | `average` | `hideAverage` |
+| Stream shows blinking cursor | `cursor` | `noCursor` |
+| Chart shows average line | `average` | `noAverage` |
 | Toggle group allows multi-select | `multiple` | `single` |
 | Swiper pauses on hover | `pause-on-hover` | `noPauseOnHover` |
 
@@ -253,9 +253,22 @@ Reserve `error` for validation state (`[error]` on form inputs matches ARIA patt
 <toggle-group-ui single>...</toggle-group-ui>
 ```
 
+**[historical, 2026-08-31, ADR-0056 amendment]** `<toggle-group-ui>` /
+`<toggle-option-ui>` were cut outright in `0.8.43` (gh#1617), before the
+migration this ADR's Decision 2 anticipated ever ran — moot, not
+falsified. `segmented-ui`/`segment-ui` absorbed the role
+(`segmented.yaml`'s `multiple` prop description names the absorption
+directly, gh#1369/#1363 C1). The example above stays as written because it
+illustrates the Boolean-false naming rule against a real historical prop
+name, not because `<toggle-group-ui>` still exists — `segmented-ui`
+deliberately does NOT follow this same polarity (`[multiple]` is
+positive-polarity by design, matching `select-ui[multiple]`; there is no
+`segmented-ui[single]` opt-out), so it is not a drop-in replacement
+example for this rule.
+
 ## Selection-item state — a declared, reflected `selected` prop, never a private `data-*` stamp
 
-A **selection-item primitive** (one selectable option inside a selection-group parent — `segment-ui` in `segmented-ui`, `toggle-option-ui` in `toggle-group-ui`) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
+A **selection-item primitive** (one selectable option inside a selection-group parent — `segment-ui` in `segmented-ui`; historically also `toggle-option-ui` in `toggle-group-ui`, cut in `0.8.43`/gh#1617 — see the dated note below) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
 
 ```javascript
 // child — the declared API surface
@@ -286,7 +299,7 @@ Rules:
 - **The parent's `value` is the single source of truth**; the parent writes `selected` on its children (`segmented.class.js:146,149` sets/removes the attribute; `toggle-group.class.js:104-111` assigns `opt.selected`). Authors and generated markup drive the group's `value`, never `[selected]` on a child (`toggle-group.yaml`'s rules block says so in so many words).
 - **No private `data-*` stamp for API-conceptual state.** `data-selected` hides the state from the yaml SoT, the catalog, and generative authoring — a consumer or the A2UI grammar cannot express "this option is selected" against a stamp that no schema declares. `toggle-group-ui` used to stamp `data-selected` + style `:scope[data-selected]`; it converged onto `segment-ui`'s mechanism (`toggle-option.yaml:38-46`, `toggle-group.css:14`, `toggle-group.test.js:64` asserts the stamp is gone).
 - **Parent-stamped ARIA stays as-is — ARIA is wiring, not API.** `segment-ui` derives `aria-checked` from `selected` (`segment.class.js:42`); `toggle-option-ui` derives `aria-pressed` (`toggle-group.class.js:65`). The reflected prop is the API; the ARIA attribute follows it.
-- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`); `toggle-option-ui` is the converged second instance. A new selection-item primitive copies this shape — extending one of the two by analogy is what produced the divergence in the first place (gh#1303).
+- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`) is the current, live reference. **[historical, 2026-08-31, ADR-0056 amendment]** `toggle-option-ui`/`toggle-group-ui` were the converged second instance at ratification time, but both were cut outright in `0.8.43` (gh#1617), before any migration ran — `segmented-ui`/`segment-ui` absorbed the role. A new selection-item primitive copies `segment-ui`'s shape directly; there is no second live instance to extend by analogy anymore (the divergence gh#1303 describes was between `segment-ui` and the now-deleted `toggle-option-ui`).
 
 Migration note: removing `data-selected` was a breaking change for external CSS that targeted it, so it shipped in two halves — the additive `selected` prop in `0.8.39`, the stamp removal on the `0.8.40` breaking wave with a migration-guide entry (`packages/web-components/CHANGELOG.md`; the ADR text names the wave `0.9.0` — it shipped as `0.8.40`).
 

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

@@ -31,7 +31,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 ### API / Attributes
 
-1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `hideCursor`, `average` → `hideAverage`, `pause-on-hover` → `noPauseOnHover`.
+1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `noCursor`, `average` → `noAverage`, `pause-on-hover` → `noPauseOnHover`. `no-*` is the canonical negation prefix (ADR-0063 decision 1) — a new rename lands on `no-*` directly, never `hide-*`.
 
 2. **No magic-value sentinels in numeric props.** Indeterminate = `null`, not `-1`. Consumers branch on `value == null`, which is explicit.
 

package/skills/primitive-authoring/references/code-style.md

@@ -239,7 +239,7 @@ Every Boolean prop on a component must default to `false`. If the expected defau
 | --------------------------------- | ------------------------------ |
 | `<drawer-ui permanent>`           | `<drawer-ui closable>`         |
 | `<chart-ui static>`               | `<chart-ui animate>`           |
-| `<cursor-ui hide-cursor>`         | `<cursor-ui cursor>`           |
+| `<cursor-ui no-cursor>`           | `<cursor-ui cursor>`           |
 | `<carousel-ui no-pause-on-hover>` | `<carousel-ui pause-on-hover>` |
 
 Default behavior is the absent attribute. Attributes exist to opt OUT or carry a value — never to opt INTO the expected default.

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/form-control-sizing.md

@@ -20,10 +20,24 @@ posture flip.
 
 ## Where legibility floors live
 
-A `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on
-`input-ui`/`select-ui`/`combobox-ui`) belongs on `:scope[inline]` only, never
-on the plain `:scope`. In the fill state the container owns the width, all
-the way down — no exception, no re-added floor. Two floor classes are
+**[retired 2026-08-28, ADR-0095]** The `--*-min-width: 20ch`-class floor
+described below is no longer permitted anywhere, including on
+`:scope[inline]`. A primitive never floors its own inline-size independent
+of its own geometry — the only permitted floor is
+`min-inline-size: var(--<component>-height)` (a square minimum). ADR-0095
+Decision Class 1 removes the 20ch-class field-width floor for
+`input-ui`/`select-ui`/`combobox-ui` (plus `--input-label-min-width`,
+`--date-range-picker-trigger-min-width`) and replaces it with the square
+floor, generalizing the `button-ui` keep-square pattern already named below
+to the field-width components.
+
+*(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
+`input-ui`/`select-ui`/`combobox-ui`) used to belong on `:scope[inline]`
+only, never on the plain `:scope`. In the fill state the container owns the
+width, all the way down — no exception, no re-added floor. Two floor
+classes are
 explicitly NOT sizing-posture floors and stay in both states: inner
 `min-width: 0` flex unclampers (the ellipsis-reset machinery) and
 `min-width: var(--*-height)` squareness floors (`button-ui`'s keep-square
@@ -35,9 +49,10 @@ posture, and also stay in both states.
 
 - Plain `:scope` (no `[inline]`): block-level, `width: auto` in block flow,
   `width: 100%` in flex/grid parents. No `min-width` legibility floor here.
-- `:scope[inline]`: inline-level display, shrink-wrap sizing, and — only if
-  the component is a floor-carrier (input/select/combobox-class) — the
-  `--*-min-width: 20ch`-class floor moves here.
+- `:scope[inline]`: inline-level display, shrink-wrap sizing. Per ADR-0095,
+  no `--*-min-width: 20ch`-class floor moves here any more — a floor-carrier
+  component uses the square minimum (`min-inline-size:
+  var(--<component>-height)`) instead, in both states.
 - A component that wants to own its line but still hug has no attribute for
   that state (ADR-0077 Decision item 6, accepted consequence) — tell the
   consumer to use explicit sizing (`width: fit-content` or an explicit

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

@@ -154,6 +154,11 @@ ADR-0053/0054 don't cover. Any new attribute follows these:
   opt-out. `chart-legend[static]` retires to `[interactive]` (inverted
   default). Applies to single-purpose toggles only — `noodles`'s
   `editable`/`readonly` pair is two orthogonal booleans and stays.
+- **One spelling survives a documented alias; the alias retires
+  everywhere it appeared** — never a deprecation window. `alert[dismissible]`
+  retired (`[closable]` survives, the implemented prop); `card`'s style
+  enum's duplicate `outline` member retired (`outlined` survives, the
+  ADR-0044 style-axis token).
 - **Two sanctioned multi-value encodings, never a hand-rolled delimited
   string:** (a) `multiple` boolean + a structured option model (`select`'s
   `options`/`<option>` shape); (b) a native array-typed JS property,