@adia-ai/adia-ui-forge 0.8.35 → 0.8.37

package/skills/{adia-release → package-release}/scripts/bump.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// bump.mjs — bump the 11 lockstep @adia-ai/* package.json from --from to --to.
+// bump.mjs — bump every lockstep @adia-ai/* package.json from --from to --to.
+// The set is PACKAGE_ROSTER (package-paths.mjs) filtered to `lockstep !== false`,
+// never a count written here — that number went stale twice.
 //
 // Idempotent. Stops on the first mismatch (a package not at --from) so
 // you can investigate before any mutation lands.
@@ -8,11 +10,11 @@
 //   node bump.mjs --from 0.6.20 --to 0.6.21
 //   node bump.mjs --from 0.6.20 --to 0.6.21 --dry
 //
-// Part of the adia-release skill. Replaces the /tmp/vXXX-prep.mjs
+// Part of the package-release skill. Replaces the /tmp/vXXX-prep.mjs
 // improvisation pattern from the v0.6.13 → v0.6.21 cycles.
 //
 // Exits:
-//   0  — all 11 bumped successfully (or --dry succeeded)
+//   0  — every lockstep package bumped successfully (or --dry succeeded)
 //   1  — at least one package not at --from (no mutation)
 //   2  — bad args / file I/O error
 //   3  — partial mutation (shouldn't happen if --from validation passes)
@@ -43,26 +45,51 @@ const SIBLING_MANIFESTS = Object.fromEntries(
 // version (SKILL invariant 8 — the consumer never floats). bump.mjs left this
 // untouched through the 0.8.6 + 0.8.7 cuts, forcing a manual edit + amend each
 // time; check-lockstep's mcp-pin guard now catches a drift, this moves it.
+//
+// Each package maps to an ARRAY of pin configs — the factory README's own
+// prose echo of the same pin (`server pinned: @adia-ai/a2ui-mcp@X`) is a
+// SECOND file invariant 8 covers, and check:plugin-count-claims' "factory
+// README a2ui-mcp pin" EQUALITY check enforces the two agree. Left out of
+// this array through the 0.8.35 + 0.8.36 cuts, it needed the same manual
+// hand-commit .mcp.json used to (gh#1198) — same file set, invariant 8's own
+// scope, so it moves alongside .mcp.json rather than getting its own key.
+//
+// ANY NAME THIS PIN HAS CARRIED (ADR-0048 P5, retargeted gh#1240 2026-08-14):
+// the generation MCP is `@adia-ai/mcp` (its `gen-ui` surface) since the
+// MCP-distribution fold — P2 had planned `@adia-ai/gen-ui-mcp`, which never
+// published — but the pin keeps naming the old package until the P7 cut
+// flips it in the release commit itself (see lockstep-checks.mjs MCP_PIN_RE
+// for why an early flip pins consumers to a 404). Matching every name means
+// the version bump works before AND after either flip, with no cut-day edit
+// to this file.
+const A2UI_MCP_PIN = {
+  label: 'generation-MCP pin (@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp})',
+  // `@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp}@<from>` (not a prefix of a longer version) → `@<to>`
+  // Escape EVERY regex metacharacter in `from`, not just dots: a prerelease or
+  // build-metadata version (`0.9.0-rc+1`) would otherwise inject `+` as a
+  // quantifier and silently match the wrong text. Same class as the truncating
+  // MCP_PIN_RE suffix CodeRabbit found on PR #1229.
+  pattern: (from) =>
+    new RegExp(`(@adia-ai/(?:(?:a2ui|gen-ui)-mcp|mcp)@)${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])`),
+  replace: (to) => `$1${to}`,
+};
 const PINNED_REFS = {
-  'packages/plugins/adia-ui-factory': {
-    file: '.mcp.json',
-    label: '@adia-ai/a2ui-mcp pin',
-    // `@adia-ai/a2ui-mcp@<from>` (not a prefix of a longer version) → `@<to>`
-    pattern: (from) => new RegExp(`(@adia-ai/a2ui-mcp@)${from.replace(/\./g, '\\.')}(?![\\d.])`),
-    replace: (to) => `$1${to}`,
-  },
+  'packages/plugins/adia-ui-factory': [
+    { ...A2UI_MCP_PIN, file: '.mcp.json' },
+    { ...A2UI_MCP_PIN, file: 'README.md', label: 'generation-MCP pin (README prose)' },
+  ],
   // web-modules' internal peers pin the EXACT lockstep version (gh#489 —
   // a caret peer never moves on a lockstep bump; adia-v2 sat on llm 0.8.19
   // under web-modules 0.8.22). Same file bumpAll already rewrote for
   // "version", so this pass re-reads it from disk before matching. The
   // check:lockstep peer-exact-mismatch guard catches a pin left behind.
-  'packages/web-modules': {
+  'packages/web-modules': [{
     file: 'package.json',
     label: '@adia-ai/* exact peer pins',
     pattern: (from) =>
       new RegExp(`("@adia-ai/[a-z0-9-]+":\\s*")${from.replace(/\./g, '\\.')}(?![\\d.])`, 'g'),
     replace: (to) => `$1${to}`,
-  },
+  }],
 };
 
 // Repo-level version references (path relative to REPO ROOT, not a package) —
@@ -131,13 +158,15 @@ function loadPackageJsons(repo) {
 // half-bumped tree whose re-run then failed validateAllAtFrom.)
 function loadPinnedRefs(repo) {
   const out = [];
-  for (const [pkg, cfg] of Object.entries(PINNED_REFS)) {
-    const p = path.join(repo, pkg, cfg.file);
-    if (!fs.existsSync(p)) {
-      console.error(`error: missing ${p}`);
-      process.exit(2);
+  for (const [pkg, cfgs] of Object.entries(PINNED_REFS)) {
+    for (const cfg of cfgs) {
+      const p = path.join(repo, pkg, cfg.file);
+      if (!fs.existsSync(p)) {
+        console.error(`error: missing ${p}`);
+        process.exit(2);
+      }
+      out.push({ pkg, cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
     }
-    out.push({ pkg, cfg, path: p, txt: fs.readFileSync(p, 'utf8') });
   }
   for (const cfg of REPO_PINNED_REFS) {
     const p = path.join(repo, cfg.file);
@@ -206,17 +235,19 @@ function bumpAll(packages, from, to, dry) {
       if (!dry) fs.writeFileSync(sibPath, sibOut);
       console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${sibling}: ${from} → ${to}`);
     }
-    const pin = PINNED_REFS[p.pkg];
-    if (pin) {
-      const pinPath = path.join(path.dirname(p.path), pin.file);
-      const pinTxt = fs.readFileSync(pinPath, 'utf8');
-      const pinOut = bumpPinnedRef(pinTxt, pin, from, to);
-      if (pinOut === pinTxt) {
-        console.error(`error: ${p.pkg}/${pin.file} — ${pin.label} '@${from}' not found (invariant 8 drift? set the pin to @${from} and re-run, or use \`npm run check:lockstep:fix\`)`);
-        return -1;
+    const pins = PINNED_REFS[p.pkg];
+    if (pins) {
+      for (const pin of pins) {
+        const pinPath = path.join(path.dirname(p.path), pin.file);
+        const pinTxt = fs.readFileSync(pinPath, 'utf8');
+        const pinOut = bumpPinnedRef(pinTxt, pin, from, to);
+        if (pinOut === pinTxt) {
+          console.error(`error: ${p.pkg}/${pin.file} — ${pin.label} '@${from}' not found (invariant 8 drift? set the pin to @${from} and re-run, or use \`npm run check:lockstep:fix\`)`);
+          return -1;
+        }
+        if (!dry) fs.writeFileSync(pinPath, pinOut);
+        console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${pin.file} ${pin.label}: @${from} → @${to}`);
       }
-      if (!dry) fs.writeFileSync(pinPath, pinOut);
-      console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${pin.file} ${pin.label}: @${from} → @${to}`);
     }
   }
   return bumped;
@@ -268,7 +299,7 @@ function selftest() {
   }
 
   // PINNED_REFS — the .mcp.json a2ui-mcp pin (invariant 8) moves in lockstep.
-  const pinCfg = PINNED_REFS['packages/plugins/adia-ui-factory'];
+  const [pinCfg, readmePinCfg] = PINNED_REFS['packages/plugins/adia-ui-factory'];
   const pinBefore = '{"args":["-y","@adia-ai/a2ui-mcp@0.8.6"]}';
   const pinAfter = bumpPinnedRef(pinBefore, pinCfg, '0.8.6', '0.8.7');
   if (!pinAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || pinAfter.includes('@0.8.6')) {
@@ -279,9 +310,25 @@ function selftest() {
     console.error('selftest FAIL: PINNED_REFS pattern prefix-matched a longer version'); process.exit(1);
   }
 
+  // gh#1198 — the factory README's OWN prose echo of the same pin
+  // (`server pinned: @adia-ai/a2ui-mcp@X`) must move alongside .mcp.json;
+  // check:plugin-count-claims' "factory README a2ui-mcp pin" EQUALITY check
+  // is what caught this drift on the v0.8.35 + v0.8.36 cuts.
+  if (readmePinCfg.file !== 'README.md') {
+    console.error('selftest FAIL: expected the second factory pin config to target README.md'); process.exit(1);
+  }
+  const readmeBefore = '`a2ui` server pinned: `@adia-ai/a2ui-mcp@0.8.6` (tool SoT: `packages/mcp/TOOLS.md`)';
+  const readmeAfter = bumpPinnedRef(readmeBefore, readmePinCfg, '0.8.6', '0.8.7');
+  if (!readmeAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || readmeAfter.includes('@0.8.6')) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the README a2ui-mcp prose pin'); process.exit(1);
+  }
+  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.60', readmePinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.60') {
+    console.error('selftest FAIL: README pin pattern prefix-matched a longer version'); process.exit(1);
+  }
+
   // web-modules exact peer pins (gh#489) — all three move in one pass; a
   // longer version must not prefix-match.
-  const peerCfg = PINNED_REFS['packages/web-modules'];
+  const [peerCfg] = PINNED_REFS['packages/web-modules'];
   const peersBefore = '{"peerDependencies":{"@adia-ai/web-components": "0.8.22","@adia-ai/a2ui-runtime": "0.8.22","@adia-ai/llm": "0.8.22"}}';
   const peersAfter = bumpPinnedRef(peersBefore, peerCfg, '0.8.22', '0.8.23');
   if ((peersAfter.match(/0\.8\.23/g) || []).length !== 3 || peersAfter.includes('0.8.22')) {

package/skills/{adia-release → package-release}/scripts/dispatch-publish.mjs

@@ -14,7 +14,7 @@
 //   # Dry mode:
 //   node dispatch-publish.mjs --version 0.6.22 --dry
 //
-// Part of the adia-release skill. Mechanizes the dispatch loop
+// Part of the package-release skill. Mechanizes the dispatch loop
 // + handles the npm-latest ordering rule for batch pushes.
 
 import { execFileSync } from 'node:child_process';

package/skills/{adia-release → package-release}/scripts/gate-roster.mjs

@@ -45,11 +45,11 @@ export const GATE_ROSTER = [
   // 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 adia-tokens pack's generated half honest.
+  // token-semantics-sync keeps the token-selection pack's generated half honest.
   { 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: 'adia-tokens generated references vs token sources' },
+  { 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 —
   // components/modules with .examples.html need a /site/components route,
   // catalog patterns need their Pattern Library sitemap entry.
@@ -73,12 +73,12 @@ export const GATE_ROSTER = [
   { n: 25, cmd: 'python3 packages/plugins/adia-ui-factory/scripts/adia-scaffold selftest', what: 'scaffold specifiers resolve in packed tarballs' },
   // gh#1137 (factory-dx-ws6-measurement SPEC, REQ-05) — FLAGGED FOR
   // CONFIRMATION: this entry was authored by the WS-6 build without a live
-  // adia-release sign-off (no operator was available mid-build to confirm
+  // package-release sign-off (no operator was available mid-build to confirm
   // the exact freshness window / regression semantics). Asserts a
   // qa/dx/sweeps/ record exists dated within this cut's window AND its
   // verdict is not a regression-RED (a plain floors<=1 baseline RED does
   // NOT block a cut — only a floor that DROPPED since the prior sweep
-  // does). CONFIRMED by adia-release on the first live cut (v0.8.35,
+  // does). CONFIRMED by package-release on the first live cut (v0.8.35,
   // 2026-08-13): semantics hold, with one correction — the previous-cut
   // comparison excludes the in-flight target version (self-reference fired
   // on the handoff re-run, since the promoted heading was already on main).
@@ -93,14 +93,25 @@ export const GATE_ROSTER = [
   // concern this is not) — hence `targetVersionArg` rather than
   // `versionArg`, a distinct flag release-pack.mjs's step3PreFlight reads.
   { n: 28, cmd: 'node scripts/release/write-eval-health.mjs', what: 'evals/health/<version>.json committed, AC-01/AC-02 run for real', targetVersionArg: true },
+  // ADR-0048 (gh#1192) estate-split latch. Between P1 (mint @adia-ai/gen-ui)
+  // and P5 (shims + roster) the tree is correct in-repo but deliberately
+  // NOT publishable: the old package dirs are `private: true` stubs the
+  // roster still points at, and a2ui-mcp depends on @adia-ai/gen-ui, which
+  // is not on npm until P7. Prose in this doc does not stop a 2am cut; this
+  // gate does. It is a tree property (private / unrostered dep edges), not a
+  // phase number, so it clears itself when P5 lands — and then stays as a
+  // permanent no-cost invariant against any future private-dep edge.
+  // Appended rather than inserted: gate numbers are cited as identities in
+  // shipped release notes, so renumbering would falsify them.
+  { n: 29, cmd: 'node scripts/release/check-estate-split-latch.mjs', what: 'no lockstep cut mid estate-split (ADR-0048)' },
 ];
 
 // -- CLI ------------------------------------------------------------------
 // Only runs when invoked directly (not when imported by release-pack.mjs).
 // realpathSync BOTH sides (CodeRabbit, PR #289): a naive string/URL compare
 // breaks under a symlinked invocation — this skill is normally reached
-// through `.claude/skills/adia-release` -> `packages/plugins/adia-ui-forge/
-// skills/adia-release`, and Node resolves `import.meta.url` through that
+// through `.claude/skills/package-release` -> `packages/plugins/adia-ui-forge/
+// skills/package-release`, and Node resolves `import.meta.url` through that
 // symlink to the real file while `process.argv[1]` keeps the as-invoked
 // path, so an unresolved compare never matches even when this IS the entry
 // point. Verified directly (see embeddings-chunks.mjs's identical guard).

package/skills/{adia-release → package-release}/scripts/insert-stub.mjs

@@ -9,9 +9,9 @@
 //     --substantive "<one-line summary>" \
 //     --xref "packages/web-modules/CHANGELOG.md#0622--2026-05-22" \
 //     --previous-version 0.6.21 \
-//     --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
+//     --packages llm,a2ui-compose,a2ui-mcp,a2ui-retrieval,a2ui-runtime,a2ui-validator
 //
-// Part of the adia-release skill. Replaces the inline stub-
+// Part of the package-release skill. Replaces the inline stub-
 // insertion pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21
 // cycles.
 
@@ -82,8 +82,20 @@ function insertStub(repo, pkg, anchor, stubBlock, version, dry) {
   }
   const txt = fs.readFileSync(p, 'utf8');
   if (txt.includes(`## [${version}]`)) {
-    console.error(`  ERROR ${pkg} — already has [${version}] heading`);
-    return 'already-present';
+    // TRUE idempotency across partial runs (the gh#976 lesson, learned
+    // here on the v0.8.36 cut's r4): an earlier aborted run already
+    // inserted this stub — that's the DONE state, not an error. The
+    // BOTH-headings danger promote-unreleased guards (real [Unreleased]
+    // content that would miss the release) applies here too: a stub
+    // package whose [Unreleased] still carries content means it was
+    // wrongly classified as a stub — loud stop.
+    const un = txt.match(/^## \[Unreleased\][^\n]*\n([\s\S]*?)(?=^## \[|(?![\s\S]))/m);
+    if (un && un[1].trim().length > 0) {
+      console.error(`  ERROR ${pkg} — has [${version}] heading AND non-empty [Unreleased] content: this package is substantive, not a stub — move it to --substantive-packages`);
+      return 'already-present';
+    }
+    console.log(`  ok ${pkg} — stub already present (idempotent skip)`);
+    return 'inserted';
   }
   if (!txt.includes(anchor)) {
     console.error(`  ERROR ${pkg} — anchor '${anchor}' not found`);
@@ -147,10 +159,20 @@ function selftest() {
       console.error('selftest FAIL: stub must land ABOVE the previous-version anchor, not below'); process.exit(1);
     }
 
-    // Idempotency: re-inserting against an already-stubbed target must fail
-    // loudly, not create a duplicate [0.2.0] block.
+    // TRUE idempotency across partial runs (gh#976 lesson, v0.8.36 r4): a
+    // re-run against an already-stubbed target is the DONE state — ok skip,
+    // file untouched, never a duplicate block.
+    const beforeRerun = fs.readFileSync(clPath, 'utf8');
     const r2 = insertStub(tmp, 'llm', anchor, stub, '0.2.0', false);
-    if (r2 !== 'already-present') { console.error(`selftest FAIL: expected 'already-present' on re-run, got '${r2}'`); process.exit(1); }
+    if (r2 !== 'inserted') { console.error(`selftest FAIL: expected idempotent 'inserted' on re-run, got '${r2}'`); process.exit(1); }
+    if (fs.readFileSync(clPath, 'utf8') !== beforeRerun) { console.error('selftest FAIL: idempotent re-run must not modify the file'); process.exit(1); }
+    if ((fs.readFileSync(clPath, 'utf8').match(/## \[0\.2\.0\]/g) || []).length !== 1) { console.error('selftest FAIL: duplicate stub block'); process.exit(1); }
+
+    // The one loud stop left: stub heading present BUT non-empty [Unreleased]
+    // — a substantive package misclassified as a stub.
+    fs.writeFileSync(clPath, `# C\n\n## [Unreleased]\n\n### Fixed\n- real content\n\n## [0.2.0] — 2026-02-02\n\n- stub\n\n${anchor}\n\n- prior\n`);
+    const r3 = insertStub(tmp, 'llm', anchor, stub, '0.2.0', false);
+    if (r3 !== 'already-present') { console.error(`selftest FAIL: expected 'already-present' for misclassified stub, got '${r3}'`); process.exit(1); }
 
     console.log('selftest OK');
   } finally {

package/skills/{adia-release → package-release}/scripts/package-paths.mjs

@@ -55,6 +55,13 @@ import path from 'node:path';
 // trip-wire (check-release.mjs's per-tag `checkTag` lookup) reads the FULL
 // roster unfiltered — every pushed tag, lockstep or not, still needs its
 // package.json/CHANGELOG validated, so it must recognize a class-B tag too.
+// `shim` (added ADR-0048 P5): `true` marks an old npm name riding exactly ONE
+// cut as a re-export shim before retirement. It changes NOTHING about how the
+// cut treats the entry — a shim versions, tags, publishes and changelogs like
+// any other lockstep member. It exists so P7's retirement PR has a mechanical
+// answer to "which rows go away", instead of a name list someone has to
+// re-derive from a doc. Absent = a permanent package.
+//
 // Every lockstep-scoped consumer must filter `p.lockstep !== false` itself
 // (this module intentionally does NOT pre-filter PACKAGE_NAMES/PACKAGE_DIRS —
 // they stay full-roster projections so a consumer's own filter is visible at
@@ -65,12 +72,43 @@ export const PACKAGE_ROSTER = [
   { name: 'llm',             dir: 'packages/llm',                       lockstep: true },
   { name: 'agent',           dir: 'packages/agent',                     lockstep: true },
   { name: 'persona',         dir: 'packages/persona',                   lockstep: true },
-  { name: 'a2ui-runtime',    dir: 'packages/a2ui/runtime',              lockstep: true },
-  { name: 'a2ui-compose',    dir: 'packages/a2ui/compose',              lockstep: true },
-  { name: 'a2ui-corpus',     dir: 'packages/a2ui/corpus',               lockstep: true },
-  { name: 'a2ui-mcp',        dir: 'packages/a2ui/mcp',                  lockstep: true },
-  { name: 'a2ui-retrieval',  dir: 'packages/a2ui/retrieval',            lockstep: true },
-  { name: 'a2ui-validator',  dir: 'packages/a2ui/validator',            lockstep: true },
+  // ── ADR-0048 P5 — the estate split's published names ────────────────────
+  //
+  // The successors of the six old a2ui-* names. `a2ui`/`gen-ui` join here,
+  // which is what turns gate 29 (check-estate-split-latch) green: every
+  // workspace dependency edge — web-components → a2ui, mcp/gen-ui → gen-ui,
+  // the shims → their successors — now points at a name some cut actually
+  // publishes.
+  //
+  // `mcp` (gh#1240, operator ruling 2026-08-14, roster 17 → 16): folds what
+  // were TWO planned rows — `gen-ui-mcp` (P2 rename target) and
+  // `a2ui-protocol-mcp` (minted fresh at P4) — into ONE published name,
+  // `@adia-ai/mcp`, at `packages/mcp/`. Neither predecessor name ever
+  // published a 0.8.x, so this fold has no npm deprecation cycle to run —
+  // unlike the SIX old a2ui-* shims below, which really did publish and need
+  // one. The two-SERVER decision (ADR-0048 §3) is unchanged; only the
+  // npm-distribution row count dropped by one.
+  { name: 'a2ui',              dir: 'packages/a2ui',                    lockstep: true },
+  { name: 'gen-ui',            dir: 'packages/gen-ui',                  lockstep: true },
+  { name: 'mcp',               dir: 'packages/mcp',                     lockstep: true },
+  // ── ADR-0048 P5 — the six old names, riding EXACTLY ONE cut as shims ────
+  //
+  // `npm unpublish` is impossible, so each retired name gets one final publish
+  // as a re-export shim (packages/shims/<name>, generated by
+  // scripts/build/generate-shims.mjs) plus an `npm deprecate` pointer run
+  // post-publish. They are on the roster only so that cut versions, tags,
+  // CHANGELOGs and publish workflows treat them like any other package.
+  //
+  // `shim: true` is the retirement marker, not decoration: P7's follow-up PR
+  // deletes exactly the entries carrying it, together with packages/shims/,
+  // their publish workflows, and resolvePackageDir's `shims/` fallback below.
+  // Nothing else in the roster is allowed to carry it.
+  { name: 'a2ui-runtime',    dir: 'packages/shims/a2ui-runtime',        lockstep: true, shim: true },
+  { name: 'a2ui-compose',    dir: 'packages/shims/a2ui-compose',        lockstep: true, shim: true },
+  { name: 'a2ui-corpus',     dir: 'packages/shims/a2ui-corpus',         lockstep: true, shim: true },
+  { name: 'a2ui-mcp',        dir: 'packages/shims/a2ui-mcp',            lockstep: true, shim: true },
+  { name: 'a2ui-retrieval',  dir: 'packages/shims/a2ui-retrieval',      lockstep: true, shim: true },
+  { name: 'a2ui-validator',  dir: 'packages/shims/a2ui-validator',      lockstep: true, shim: true },
   // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
   // each carries a .claude-plugin/plugin.json that bumps with package.json.
   { name: 'adia-ui-factory', dir: 'packages/plugins/adia-ui-factory',   lockstep: true, plugin: true },
@@ -98,6 +136,13 @@ export const PACKAGE_DIRS = PACKAGE_ROSTER.map((p) => p.dir);
 // error against the resolved path).
 export function resolvePackageDir(repo, pkg) {
   if (fs.existsSync(path.join(repo, 'packages', pkg))) return pkg;
+  // ADR-0048 P3 — the old a2ui-* names now live at packages/shims/<old-name>.
+  // Tried before the legacy packages/a2ui/<x> nesting below so the shim wins
+  // while both could exist; both fallbacks die when P5 retires the shims.
+  if (/^a2ui-/.test(pkg)) {
+    const shim = path.join('shims', pkg);
+    if (fs.existsSync(path.join(repo, 'packages', shim))) return shim;
+  }
   const m = /^a2ui-(.+)$/.exec(pkg);
   if (m) {
     const nested = path.join('a2ui', m[1]);

package/skills/{adia-release → package-release}/scripts/pr-bridge.mjs

@@ -37,7 +37,7 @@
 //
 // Exit: 0 merged + main re-baselined · 1 stopped (evidence printed) · 2 bad args.
 //
-// Part of the adia-release skill. Registered in CI's "Plugin bin selftests".
+// Part of the package-release skill. Registered in CI's "Plugin bin selftests".
 
 import { execSync, execFileSync } from 'node:child_process';
 import fs from 'node:fs';

package/skills/{adia-release → package-release}/scripts/promote-unreleased.mjs

@@ -14,7 +14,7 @@
 //   node promote-unreleased.mjs --version 0.6.22 --date 2026-05-22 \
 //     --packages web-components,web-modules --dry
 //
-// Part of the adia-release skill. Replaces the inline heading-swap
+// Part of the package-release skill. Replaces the inline heading-swap
 // pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21 cycles.
 //
 // Exits:

package/skills/{adia-release → package-release}/scripts/release-pack.mjs

@@ -55,7 +55,7 @@
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
-// Part of the adia-release skill. Mechanizes the cut procedure from
+// Part of the package-release skill. Mechanizes the cut procedure from
 // references/cut-procedure.md. Every confirmation boundary prints its evidence
 // block BEFORE the prompt (H5) — never a bare y/N — whether it waits for input
 // (manual flags) or auto-confirms (--go).
@@ -223,7 +223,7 @@ function help() {
     --substantive "<one-line>" \\
     --xref "packages/web-modules/CHANGELOG.md#0$X$Y$Z--YYYY-MM-DD" \\
     --substantive-packages web-components,web-modules,a2ui/corpus \\
-    --stub-packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
+    --stub-packages llm,a2ui-compose,a2ui-mcp,a2ui-retrieval,a2ui-runtime,a2ui-validator
 
 Flags: --go   (single-authorization: the operator's cut-start go covers the
                whole cycle — auto-confirms ALL checkpoints; stops only on
@@ -691,6 +691,16 @@ function step5Commit(args) {
     'packages/genui/adia-catalog/base.json',
     'packages/genui/adia-catalog/adia-pack.json',
     'packages/genui/adia-catalog/catalog-data.js',
+    // gh#1197: gate 28 (write-eval-health.mjs, Step 3) writes this
+    // COMMITTED per-cut health record — WS-4 REQ-06's contract — but it
+    // never rode the release commit: v0.8.35's and v0.8.36's records both
+    // sat untracked until a session close-out swept them by hand (PR
+    // #1196). Named after args.version (gate 28 is a targetVersionArg gate,
+    // so it always writes at the CUT version, never previous — see Step 3's
+    // targetVersionArg comment above). Under --skip-gates the record was
+    // never written (Step 3 returned early), so staging it would make the
+    // whole `git add` fail on a missing pathspec (PR #1204 review).
+    ...(args.skipGates ? [] : [`evals/health/${args.version}.json`]),
     ...LOCKSTEP_ROSTER.flatMap(({ name, dir, plugin }) => {
       // Roster-driven (H3): each package stages its manifest + CHANGELOG;
       // plugins also stage .claude-plugin/plugin.json (the /plugin-update
@@ -1009,13 +1019,13 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
-  console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  console.log(`package-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
   // Stale-plugin-cache self-check (v0.8.32 cut, first failure): the INSTALLED
   // plugin cache only refreshes on a version bump, so running this script from
   // the cache mid-cycle can execute a version that predates its own guards
   // (SKILL.md §Plugin cache). If the repo carries its own copy and the bytes
   // differ, warn loudly — the repo copy is almost always the newer one.
-  const repoCopy = path.join(REPO, 'packages/plugins/adia-ui-forge/skills/adia-release/scripts/release-pack.mjs');
+  const repoCopy = path.join(REPO, 'packages/plugins/adia-ui-forge/skills/package-release/scripts/release-pack.mjs');
   const selfPath = new URL(import.meta.url).pathname;
   if (fs.existsSync(repoCopy) && path.resolve(selfPath) !== path.resolve(repoCopy)) {
     const self = fs.readFileSync(selfPath, 'utf8');
@@ -1115,6 +1125,10 @@ function selftest() {
       'STOPPING per invariant 3',
       // gh#358 — the release branch must actually be created, not just documented.
       'git checkout -b release/v9.9.9',
+      // gh#1197 — Step 5's staging pathspec must carry gate 28's committed
+      // health record, or it rides untracked past the release commit
+      // (v0.8.35/v0.8.36 both did, PR #1196 swept them by hand).
+      'evals/health/9.9.9.json',
     ];
     for (const marker of need) {
       if (!out.includes(marker)) {

package/skills/{adia-release → package-release}/scripts/tag-lockstep.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // tag-lockstep.mjs — create the lockstep tag set (umbrella vX.Y.Z + one
 // per-package <pkg>-vX.Y.Z per roster entry — package-paths.mjs is the
-// live census; 14 tags as of gh#607) at HEAD or at a specified SHA.
+// live census; 17 tags as of gh#1240) at HEAD or at a specified SHA.
 //
 // Usage:
 //   node tag-lockstep.mjs --version 0.6.22
@@ -9,7 +9,7 @@
 //   node tag-lockstep.mjs --version 0.6.22 --delete     # delete existing tags
 //   node tag-lockstep.mjs --version 0.6.22 --dry        # print commands without running
 //
-// Part of the adia-release skill. Mechanizes the tag loop used
+// Part of the package-release skill. Mechanizes the tag loop used
 // every cycle.
 
 import { execSync } from 'node:child_process';

package/skills/{adia-author → primitive-authoring}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: adia-author
+name: primitive-authoring
 description: >-
   Author or modify AdiaUI framework source inside the monorepo — primitives
   (packages/web-components), shells/composites (packages/web-modules), yaml
@@ -10,19 +10,19 @@ description: >-
   module, audit a component's four-axis contract/token usage/lifecycle
   (connected/disconnected symmetry) for drift, or author/write a demo or
   examples.html for a component or composite. NOT for composing app screens
-  from primitives (adia-compose), A2UI pipeline internals (adia-a2ui),
-  @adia-ai/llm adapter/streaming/bridge internals (adia-llm-internals), or
-  site/pages docs pages (adia-site-docs).
+  from primitives (screen-composition), A2UI pipeline internals (a2ui-maintenance),
+  @adia-ai/llm adapter/streaming/bridge internals (llm-client-maintenance), or
+  site/pages docs pages (site-docs-authoring).
 disable-model-invocation: false
 user-invocable: true
 ---
 
-# adia-author
+# primitive-authoring
 
 Guard rails for code that lands INSIDE the adia-ui monorepo: primitives
 (`packages/web-components/`), shells and composites (`packages/web-modules/`),
 their `<name>.yaml` SoTs, and composite demos. `@adia-ai/llm` internals
-(adapters, streaming, the bridge) are `adia-llm-internals`'s charter, not
+(adapters, streaming, the bridge) are `llm-client-maintenance`'s charter, not
 this skill's — route there.
 Light-DOM is load-bearing: `slot=` attributes are decorative metadata,
 positioning is CSS by tag + ancestor + DOM order — never `::slotted()`,
@@ -41,7 +41,7 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 | Contract / token / lifecycle drift audit on an existing component | [token-contract.md](references/token-contract.md) + [anti-patterns.md](references/anti-patterns.md) |
 | Demo for a composite/module — any `packages/web-modules/**/*.{examples,contents}.html` | [composite-demo-protocol.md](references/composite-demo-protocol.md) — NOT the primitive or promotion paths; they lack the canonical-survey discipline |
 | Convention question ("is this idiomatic?") | [code-style.md](references/code-style.md) — cite the rule, don't expand it inline |
-| Trait detail page (`site/pages/traits/<name>/`) | [trait-pages.md](references/trait-pages.md) — the ADR-0019 required-section template (traits are this skill's charter; adia-site-docs does not own `traits/`) |
+| Trait detail page (`site/pages/traits/<name>/`) | [trait-pages.md](references/trait-pages.md) — the ADR-0019 required-section template (traits are this skill's charter; site-docs-authoring does not own `traits/`) |
 
 Full retrieval map — one line per reference file, grouped by axis:
 [references/INDEX.md](references/INDEX.md). Depth references (api-contract,

package/skills/{adia-author → primitive-authoring}/evals/evals.json

@@ -1,5 +1,5 @@
 {
-  "skill": "adia-author",
+  "skill": "primitive-authoring",
   "note": "Trigger-routing suite (gh#369). expect=trigger: the skill should fire on the prompt in a fresh session. expect=no-trigger: a near-miss owned elsewhere (owner named per case) or generic knowledge with no AdiaUI skill involved. Cases derived from evals/routing-corpus.json's phrases array (gh#355 vetted corpus) plus the SKILL.md description's own trigger/NOT-fence language.",
   "cases": [
     { "id": "t01", "prompt": "Add a new <toggle-ui> primitive component from scratch", "expect": "trigger" },
@@ -11,12 +11,12 @@
     { "id": "t07", "prompt": "Audit the four-axis contract for table-ui — token usage and lifecycle symmetry", "expect": "trigger" },
     { "id": "t08", "prompt": "Author a demo for the billing-overview composite, an examples.html", "expect": "trigger" },
     { "id": "t09", "prompt": "Add a pane behaviour to admin-shell per the bespoke shell-tier convention", "expect": "trigger" },
-    { "id": "n01", "prompt": "Compose this Figma mock into AdiaUI components for our consumer app", "expect": "no-trigger", "owner": "adia-compose" },
-    { "id": "n02", "prompt": "Cut a release of the next version and publish the npm packages", "expect": "no-trigger", "owner": "adia-release" },
-    { "id": "n03", "prompt": "Tune the zettel composition coverage, the eval is at 38%", "expect": "no-trigger", "owner": "adia-a2ui" },
-    { "id": "n04", "prompt": "Deploy the API service to the hosting platform", "expect": "no-trigger", "owner": "adia-deploy" },
-    { "id": "n05", "prompt": "The gemini adapter is dropping usage tokens on streamed responses", "expect": "no-trigger", "owner": "adia-llm-internals" },
-    { "id": "n06", "prompt": "Extend the LLM bridge in @adia-ai/llm to add a new provider", "expect": "no-trigger", "owner": "adia-llm-internals" },
+    { "id": "n01", "prompt": "Compose this Figma mock into AdiaUI components for our consumer app", "expect": "no-trigger", "owner": "screen-composition" },
+    { "id": "n02", "prompt": "Cut a release of the next version and publish the npm packages", "expect": "no-trigger", "owner": "package-release" },
+    { "id": "n03", "prompt": "Tune the zettel composition coverage, the eval is at 38%", "expect": "no-trigger", "owner": "a2ui-maintenance" },
+    { "id": "n04", "prompt": "Deploy the API service to the hosting platform", "expect": "no-trigger", "owner": "site-deployment" },
+    { "id": "n05", "prompt": "The gemini adapter is dropping usage tokens on streamed responses", "expect": "no-trigger", "owner": "llm-client-maintenance" },
+    { "id": "n06", "prompt": "Extend the LLM bridge in @adia-ai/llm to add a new provider", "expect": "no-trigger", "owner": "llm-client-maintenance" },
     { "id": "n07", "prompt": "Explain how React hooks work in general", "expect": "no-trigger" }
   ]
 }