@adia-ai/adia-ui-forge 0.8.3 → 0.8.5

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

@@ -13,7 +13,13 @@
 //   --mode cut          (Mode 1 — peer pre-staged [Unreleased] or pure stub; STOPS at the release commit)
 //   --mode from-scratch (Mode 2 — promote [Unreleased] → [VERSION]; STOPS at the release commit)
 //   --mode handoff      (Mode 3 — the second phase: tag at post-merge main → publish → deploy)
-//   --mode batch        (Mode 4 — multiple merged cuts; pass --version-list)
+//
+// `--mode batch` is NOT implemented here — a batch push tags each version at
+// its OWN release-merge SHA and enforces oldest-first publish ordering, which
+// this single-version orchestrator has no model for. Passing it hard-errors
+// with a pointer to the manual procedure: references/recovery-paths.md
+// §Scenario 2 (Batch push). Silently falling through to the single-version
+// path was the H2 audit finding this replaced.
 //
 // REQUIRED:
 //   --version 0.6.22
@@ -25,26 +31,37 @@
 //   --gh-notes-file <path>            : GH release notes body (one per cycle)
 //   --substantive "<one-line>"        : for the stub block xref
 //   --xref "<changelog-anchor>"       : for the stub block
-//   --substantive-packages a,b,c      : packages with [Unreleased] to promote
+//   --substantive-packages a,b,c      : packages with [Unreleased] to promote (cut AND from-scratch)
 //   --stub-packages a,b,c             : packages getting the lockstep stub
 //
 // FLAGS:
 //   --dry                : preview all commands, no mutation, no prompts
-//   --yes                : skip the 3 operator checkpoints (CI / scripted)
+//   --yes                : auto-confirm CHECKPOINT 1 ONLY (before tagging). Tag
+//                          creation is the least destructive of the three
+//                          mutating boundaries (moving/deleting a local-only
+//                          tag is free); push and publish each need their own
+//                          explicit go — --yes does not cover them (H5/defect-2:
+//                          a single --yes used to flatten all 3 checkpoints).
+//   --push               : auto-confirm CHECKPOINT 2 (before pushing tags)
+//   --publish            : auto-confirm CHECKPOINT 3 (before dispatching publishes)
 //   --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
 // references/cut-procedure.md while preserving operator judgment at
-// the 3 mutating-checkpoint boundaries.
+// the 3 mutating-checkpoint boundaries. Every checkpoint prints its evidence
+// block BEFORE the prompt (H5) — never a bare y/N.
 
 import { execSync } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { resolvePackageChangelog } from './package-paths.mjs';
+import { GATE_ROSTER } from './gate-roster.mjs';
 
 const SCRIPT_DIR = path.dirname(new URL(import.meta.url).pathname);
 const REPO = process.cwd();
@@ -70,7 +87,7 @@ function parseArgs(argv) {
     versionList: null,
     host: process.env.ADIA_DEPLOY_HOST || DEFAULT_DEPLOY_HOST,
     scope: process.env.ADIA_NPM_SCOPE || DEFAULT_NPM_SCOPE,
-    dry: false, yes: false, skipGates: false, skipSite: false,
+    dry: false, yes: false, push: false, publish: false, skipGates: false, skipSite: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const k = argv[i];
@@ -89,6 +106,8 @@ function parseArgs(argv) {
     else if (k === '--scope') args.scope = argv[++i];
     else if (k === '--dry') args.dry = true;
     else if (k === '--yes') args.yes = true;
+    else if (k === '--push') args.push = true;
+    else if (k === '--publish') args.publish = true;
     else if (k === '--skip-gates') args.skipGates = true;
     else if (k === '--skip-site') args.skipSite = true;
     else if (k === '-h' || k === '--help') { help(); process.exit(0); }
@@ -98,8 +117,17 @@ function parseArgs(argv) {
     console.error('       see --help');
     process.exit(2);
   }
-  if (!['cut', 'from-scratch', 'handoff', 'batch'].includes(args.mode)) {
-    console.error(`error: --mode must be cut|from-scratch|handoff|batch (got: ${args.mode})`);
+  if (args.mode === 'batch') {
+    console.error('error: --mode batch is not implemented — a batch push tags each version at');
+    console.error('       its OWN release-merge SHA and enforces oldest-first publish ordering,');
+    console.error('       which this single-version orchestrator has no model for. Silently');
+    console.error('       falling through to the single-version path was the H2 defect this');
+    console.error('       replaced. Follow the manual procedure instead:');
+    console.error('         references/recovery-paths.md §Scenario 2 — Batch push');
+    process.exit(2);
+  }
+  if (!['cut', 'from-scratch', 'handoff'].includes(args.mode)) {
+    console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
   return args;
@@ -116,15 +144,28 @@ function help() {
     --substantive-packages web-components,web-modules,a2ui/corpus \\
     --stub-packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 
-Flags: --dry  (preview all)  --yes  (skip prompts)  --skip-site  (skip EXE deploy)
+Flags: --dry  (preview all)  --yes  (auto-confirm checkpoint 1 ONLY — tag)
+       --push  (auto-confirm checkpoint 2 — push tags)
+       --publish  (auto-confirm checkpoint 3 — dispatch publishes)
+       --skip-site  (skip EXE deploy)
 Instance: --host <deploy-host>  (default ${DEFAULT_DEPLOY_HOST}; or $ADIA_DEPLOY_HOST)
           --scope <@org>        (npm scope; default ${DEFAULT_NPM_SCOPE}; or $ADIA_NPM_SCOPE)`);
 }
 
 const rl = createInterface({ input: stdin, output: stdout });
-async function checkpoint(label, args) {
-  if (args.yes) {
-    console.log(`\n[checkpoint] ${label} — auto-confirmed (--yes)`);
+// Every checkpoint prints its evidence block BEFORE the y/N prompt (H5) —
+// `evidence` is a pre-formatted string (tag list, F-N1 results, registry
+// snapshot); `autoConfirmed` is the SPECIFIC flag that covers THIS checkpoint
+// (--yes for checkpoint 1 only; --push / --publish for 2 and 3 — H5/defect-2:
+// a single --yes used to flatten all three).
+async function checkpoint(label, evidence, autoConfirmed) {
+  if (evidence) {
+    console.log(`\n--- evidence for: ${label} ---`);
+    console.log(evidence);
+    console.log('---');
+  }
+  if (autoConfirmed) {
+    console.log(`\n[checkpoint] ${label} — auto-confirmed`);
     return;
   }
   const answer = await rl.question(`\n[CHECKPOINT] ${label} — proceed? [y/N]: `);
@@ -151,6 +192,24 @@ function shQuiet(cmd, args) {
   return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
 }
 
+// Runs a command and CAPTURES its combined output instead of streaming it —
+// used where the output itself becomes evidence in a later checkpoint's
+// evidence block (H5), rather than just scrolling past in the terminal.
+// Never throws: F-N1 legitimately exits non-zero on cosmetic warns; the
+// caller decides what a non-zero code means.
+function shCapture(cmd, args) {
+  if (args.dry) {
+    console.log(`  [dry] ${cmd}`);
+    return { code: 0, output: '[dry] (not run)' };
+  }
+  try {
+    const output = execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { code: 0, output };
+  } catch (e) {
+    return { code: e.status ?? 1, output: (e.stdout || '') + (e.stderr || '') };
+  }
+}
+
 // ── Step 1 — Re-baseline ──────────────────────────────────────────
 function step1ReBaseline(args) {
   console.log('\n=== Step 1 — Re-baseline ===');
@@ -173,32 +232,40 @@ function step3PreFlight(args) {
     console.log('\n=== Step 3 — Pre-flight (SKIPPED via --skip-gates; danger!) ===');
     return;
   }
-  console.log('\n=== Step 3 — Pre-flight gates ===');
-  const gates = [
-    'node scripts/build/components.mjs --verify',
-    'npm run verify:traits',
-    'npm run check:lockstep',
-    'npm run test:unit',
-    'npm run typecheck',
-    'npm run check:demo-shells',
-    'npm run check:lightningcss-build',
-    'npm run smoke:engines',
-    'npm run smoke:register-engine',
-    'npm run check:links',
-    'npm run check:embeddings-fresh',
-    'npm run verify:corpus',
-  ];
-  for (const g of gates) {
-    console.log(`\n  ${g}`);
+  console.log(`\n=== Step 3 — Pre-flight gates (${GATE_ROSTER.length}-gate roster — gate-roster.mjs) ===`);
+  for (const g of GATE_ROSTER) {
+    console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${g.cmd}   # ${g.what}`);
     try {
-      sh(g, args, { stdio: 'inherit' });
+      sh(g.cmd, args, { stdio: 'inherit' });
     } catch (e) {
-      console.error(`\n  ✗ FAILED: ${g}`);
+      console.error(`\n  ✗ FAILED (${g.n}/${GATE_ROSTER.length}): ${g.cmd}`);
       console.error('  Pre-flight aborted. Fix the gate failure before proceeding.');
       console.error('  See references/gates-catalog.md for failure-mode → recovery.');
       process.exit(1);
     }
   }
+  console.log(`\n  ✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`);
+}
+
+// Read a package's CHANGELOG at repo HEAD (working tree) and report whether a
+// `## [Unreleased]` heading still carries non-empty content — i.e. it rode
+// through un-promoted. Defect 1 (H1-adjacent, audit seed): `--mode cut` never
+// called promote-unreleased.mjs at all, so a peer's hand-authored
+// `## [Unreleased]` section shipped in the tarball unpromoted (bit the
+// v0.8.4 cut — the plugin packages needed hand-promotion because nothing
+// caught it). Returns null when clean, or a short description when dirty.
+function unpromotedUnreleased(repo, pkg) {
+  const p = resolvePackageChangelog(repo, pkg);
+  if (!fs.existsSync(p)) return null;
+  const txt = fs.readFileSync(p, 'utf8');
+  const m = txt.match(/^## \[Unreleased\][^\n]*\n([\s\S]*?)(?=^## \[|$(?![\s\S]))/m);
+  if (!m) return null;
+  // Strip subsection headers (### Added, ### Fixed, …) and blank lines — what's
+  // left is real content, not just empty scaffolding.
+  const body = m[1].replace(/^###.*$/gm, '').trim();
+  if (body.length === 0) return null;
+  const firstLine = body.split('\n')[0].slice(0, 100);
+  return `${pkg}: "${firstLine}${firstLine.length === 100 ? '…' : ''}"`;
 }
 
 // ── Step 4 — Promote + bump + lockfile ───────────────────────────
@@ -209,7 +276,12 @@ function step4PromoteAndBump(args) {
   }
   console.log('\n=== Step 4 — Promote + Bump + Lockfile ===');
 
-  if (args.mode === 'from-scratch' && args.substantivePackages) {
+  // Promotion runs for BOTH cut and from-scratch now — a peer's pre-staged
+  // [Unreleased] content needs promoting in either mode; only the CALLER
+  // (whether a peer already promoted vs. this cycle authoring fresh) differs,
+  // not whether promotion is needed. `--substantive-packages` is the same flag
+  // in both modes.
+  if (args.substantivePackages) {
     const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${args.substantivePackages.join(',')}`;
     sh(cmd, args);
   }
@@ -219,6 +291,23 @@ function step4PromoteAndBump(args) {
     sh(cmd, args);
   }
 
+  // Loud guard: after promotion, NO package in the lockstep set (including
+  // the 2 plugin packages, which required hand-promotion at v0.8.4) may still
+  // carry a non-empty [Unreleased] — that content would ride through the
+  // bump unpromoted, undocumented in the tarball's own CHANGELOG.
+  if (!args.dry) {
+    const dirty = PACKAGES.map((p) => unpromotedUnreleased(REPO, p)).filter(Boolean);
+    if (dirty.length > 0) {
+      console.error(`\nERROR: ${dirty.length} package(s) still have non-empty [Unreleased] content after promotion:`);
+      for (const d of dirty) console.error(`  ✗ ${d}`);
+      console.error('\n  Add the missing package(s) to --substantive-packages (or --stub-packages if');
+      console.error('  they are pure ride-alongs) and re-run. See changelog-discipline.md §Detecting');
+      console.error('  source-changing packages.');
+      process.exit(1);
+    }
+    console.log(`  ✓ no unpromoted [Unreleased] content across all ${PACKAGES.length} packages`);
+  }
+
   sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
@@ -262,23 +351,45 @@ function step5Commit(args) {
   sh(`git commit -F ${args.commitMessageFile}`, args);
 }
 
-// ── Step 6 — Tag ─────────────────────────────────────────────────
+// ── Step 6 — Tag ← operator checkpoint 1 (before tagging) ────────
 async function step6Tag(args) {
   console.log('\n=== Step 6 — Tag at HEAD ===');
-  await checkpoint('Ready to create 12 tags (umbrella + 11 per-package)', args);
+  const tagList = [`v${args.version}`, ...PACKAGES.map((p) => `${p}-v${args.version}`)];
+  const evidence = `Planned tags (${tagList.length} — umbrella + ${PACKAGES.length} per-package):\n` +
+    tagList.map((t) => `  ${t}`).join('\n');
+  // --yes covers ONLY this checkpoint (defect-2/H5) — moving/deleting a
+  // local-only tag is free, so this is the least destructive of the three.
+  await checkpoint('Create tags at HEAD — before tagging', evidence, args.yes);
   sh(`node ${SCRIPT_DIR}/tag-lockstep.mjs --version ${args.version}`, args);
+  console.log(`  ✓ created ${tagList.length} tags`);
 }
 
-// ── Step 7 — F-N1 ────────────────────────────────────────────────
+// ── Step 7 — F-N1 ─────────────────────────────────────────────────
+// Captures output (rather than streaming it) so checkpoint 2 can show the
+// per-package F-N1 results as evidence BEFORE the push prompt (H5) — the F-N1
+// output used to scroll past in Step 7 with no connection to Step 8's prompt.
 function step7Fn1(args) {
   console.log('\n=== Step 7 — F-N1 release trip-wire ===');
-  try {
-    sh('node scripts/release/check-release.mjs --all-pending', args);
-  } catch (e) {
-    // F-N1 sometimes exits non-zero on cosmetic warns; show the output and let the operator decide
-    console.warn('\n  F-N1 returned non-zero — review the warns above.');
-    console.warn('  See references/changelog-discipline.md § F-N1 diff-coverage enrichment.');
+  const { code, output } = shCapture('node scripts/release/check-release.mjs --all-pending', args);
+  console.log(output);
+  // CodeRabbit (PR #289): a non-zero exit here (without --strict, which this
+  // call doesn't pass) is ALWAYS a real `error` finding — check-release.mjs
+  // only sets a non-zero code for `error` severity; cosmetic `warn`s leave it
+  // 0. Treating non-zero as "just review the warns" let --push auto-confirm
+  // straight past a known trip-wire failure. Fail closed: hard-stop HERE,
+  // before Step 8 exists at all — no flag can skip this.
+  if (code !== 0 && !args.dry) {
+    console.error('\n  ✗ F-N1 reported an ERROR (not a cosmetic warn) — release-pack stops here.');
+    console.error('  Fix the finding above, land it as a new commit through the PR flow (the');
+    console.error('  release commit is already merged — see changelog-discipline.md §F-N1');
+    console.error('  diff-coverage enrichment), delete + re-create the tags, re-run.');
+    process.exit(1);
   }
+  // Cosmetic warns (exit 0, but the output carries `[warn]` lines) are real
+  // signal an operator should read before pushing — never let --push silently
+  // wave them through; only the interactive prompt may proceed past a warn.
+  const hasWarn = /\[warn\]/.test(output);
+  return { output, hasWarn };
 }
 
 // ── Step 8 — Push ────────────────────────────────────────────────
@@ -296,7 +407,7 @@ function step7Fn1(args) {
 // orchestrated cut does NOT rely on push-on-tag firing. The one-at-a-time push
 // is defensive (a cut aborted after Step 8 still has its publishes triggered)
 // AND keeps the standalone tag-lockstep.mjs hint honest.
-async function step8Push(args) {
+async function step8Push(args, fn1) {
   console.log('\n=== Step 8 — Push tags (per-tag, NOT batched) ===');
   // Invariant 3: main reached this state via a merged release PR — never a
   // direct push from here. Assert we're tagging the pushed history.
@@ -305,14 +416,22 @@ async function step8Push(args) {
     console.error(`ERROR: HEAD is ${ahead} commit(s) ahead of origin/main — release commits land via PR (invariant 3); merge first, then tag at post-merge main.`);
     process.exit(1);
   }
-  await checkpoint('Ready to push 12 tags (one-at-a-time)', args);
   const perPkgTags = PACKAGES.map((p) => `${p}-v${args.version}`);
+  const evidence = `F-N1 results (Step 7):\n${fn1?.output || '(none captured)'}\n` +
+    `Tags to push (${perPkgTags.length + 1} — one push per tag, umbrella last):\n` +
+    [...perPkgTags, `v${args.version}`].map((t) => `  ${t}`).join('\n');
+  // --push is its OWN flag — NOT covered by --yes (defect-2/H5). CodeRabbit
+  // (PR #289): a cosmetic F-N1 warn must still force the interactive prompt —
+  // --push may NOT auto-confirm past ANY F-N1 finding, only a fully clean
+  // run. (A real F-N1 error never reaches here — step7Fn1 hard-exits first.)
+  const autoConfirm = args.push && !fn1?.hasWarn;
+  await checkpoint('Push tags — before pushing', evidence, autoConfirm);
   for (const t of perPkgTags) {
     sh(`git push origin ${t}`, args);
   }
   // Umbrella tag last — triggers no workflow (convention only).
   sh(`git push origin v${args.version}`, args);
-  console.log(`\n  ${perPkgTags.length} per-package tags + 1 umbrella pushed individually.`);
+  console.log(`\n  ✓ pushed ${perPkgTags.length} per-package tags + 1 umbrella tag`);
   console.log('  NOTE: a single `git push origin <all tags>` can skip ALL publish-on-tag');
   console.log('  triggers (the GitHub batch-push skip). Step 9 dispatches via');
   console.log('  workflow_dispatch + verifies each triggered — see recovery-paths.md §Scenario 7.');
@@ -324,9 +443,30 @@ async function step8Push(args) {
 // exist for the <pkg>-vX.Y.Z tags and re-dispatches ONLY the misses — closing the
 // batch-tag-push skip without double-publishing the ones that already fired.
 // Idempotent: if all 11 triggered (or none did), it does the right thing.
+// Snapshot the CURRENT registry state — the "ordering evidence" for
+// checkpoint 3 (H5): what's live right now, before anything is dispatched,
+// so the operator can confirm publish order/target against reality rather
+// than a bare y/N.
+function registrySnapshot(args) {
+  if (args.dry) return '[dry] (registry snapshot skipped)';
+  const lines = [];
+  for (const pkg of PACKAGES) {
+    let v;
+    try { v = execSync(`npm view "${args.scope}/${pkg}" version`, { encoding: 'utf8' }).trim(); }
+    catch { v = 'MISSING/E404'; }
+    lines.push(`  ${pkg}: ${v}${v === args.version ? '  (already at target — idempotent re-dispatch)' : ''}`);
+  }
+  let latest = 'unknown';
+  try { latest = execSync(`npm view ${args.scope}/web-components dist-tags.latest`, { encoding: 'utf8' }).trim(); } catch { /* offline */ }
+  lines.push(`  dist-tags.latest: ${latest}`);
+  return `Registry state BEFORE publish (target = ${args.version}):\n${lines.join('\n')}`;
+}
+
 async function step9Publish(args) {
   console.log('\n=== Step 9 — Verify-triggered + re-dispatch misses ===');
-  await checkpoint('Ready to verify the 11 publish triggers + re-dispatch any misses', args);
+  const evidence = registrySnapshot(args);
+  // --publish is its OWN flag — NOT covered by --yes (defect-2/H5).
+  await checkpoint('Dispatch publishes — before publishing', evidence, args.publish);
   // Give GH a moment to index the runs created by the per-tag push in Step 8.
   if (!args.dry) sh('sleep 6', args);
   sh(`node ${SCRIPT_DIR}/dispatch-publish.mjs --version ${args.version} --scope ${args.scope} --verify-triggered`, args);
@@ -335,7 +475,7 @@ async function step9Publish(args) {
   console.log('  ✓ publishes settled');
   // Fail-closed: the registry is the verify target (SKILL.md) — a missing or
   // stale package aborts the cut here, before GH releases + site deploy.
-  console.log(`\n  Verify all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
+  console.log(`\n  Post-publish registry verification, all ${PACKAGES.length} at ${args.version} + npm latest (fail-closed):`);
   sh(
     `fail=0; ` +
     `for pkg in ${PACKAGES.join(' ')}; do ` +
@@ -369,8 +509,24 @@ async function step10GhAndSite(args) {
     console.log('  --skip-site set; skipping EXE deploy');
     return;
   }
-  sh('npm run build:site', args);
-  sh(`rsync -az --delete dist/ ${args.host}:/srv/adia-ui/dist/`, args);
+  // H1 (forge-campaign gh#268 audit): this used to `npm run build:site` +
+  // raw `rsync -az --delete` straight to the host — bypassing deploy-site.yml
+  // entirely (its build → pre-flight verify → snapshot → rsync → post-deploy
+  // verify → auto-rollback pipeline), even though cut-procedure.md §Step 10
+  // already documented the workflow-dispatch path as the correct one. A raw
+  // local rsync has no snapshot to roll back to on a bad deploy. Dispatch the
+  // real pipeline instead — gated behind its own confirm (deploy is
+  // outward-facing exactly like publish; --publish covers it, or an
+  // interactive confirm if not given).
+  const evidence = `Dispatching "Deploy site (${args.host})" (.github/workflows/deploy-site.yml) —\n` +
+    `builds from main, runs pre-flight verify → snapshot → hardened rsync →\n` +
+    `post-deploy verify → auto-rollback. NOT a raw rsync (the bypass this replaced).`;
+  await checkpoint('Deploy site — before dispatching deploy-site.yml', evidence, args.publish);
+  sh(`gh workflow run "Deploy site (${args.host})" --repo adiahealth/gen-ui-kit --ref main`, args);
+  console.log('  Waiting for the deploy workflow to settle...');
+  if (!args.dry) sh('sleep 10', args);
+  sh(`until [ "$(gh run list --workflow=deploy-site.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`, args);
+  console.log('  ✓ deploy-site.yml settled');
   // Verify a deployed CONTENT FILE, never an SPA route — the docs site
   // returns HTTP 200 + a blank shell for ANY unmatched route (v0.7.4 trap).
   sh(`curl -s -o /dev/null -w "EXE host.css: HTTP %{http_code}\\n" https://${args.host}/packages/web-components/styles/host.css`, args);
@@ -405,16 +561,91 @@ async function main() {
     return;
   }
   await step6Tag(args);
-  step7Fn1(args);
-  await step8Push(args);
+  const fn1 = step7Fn1(args);
+  await step8Push(args, fn1);
   await step9Publish(args);
   await step10GhAndSite(args);
   rl.close();
   console.log('\n✓ release-pack complete. Verify against the npm registry + GH releases, then author the release notes.');
 }
 
-main().catch((e) => {
-  console.error(e);
+// Plan-assembly selftest — spawns THIS script as a real subprocess with
+// --mode cut --dry (fully mutation-free per every step's own dry-guard) and
+// asserts the assembled plan carries the expected markers: the full
+// 17-gate roster (H3 — a subset run must be impossible without editing
+// gate-roster.mjs), and the invariant-3 stop-before-PR message (cut mode
+// 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() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'release-pack-selftest-'));
+  try {
+    const commitFile = path.join(tmp, 'commit.txt');
+    const notesFile = path.join(tmp, 'notes.md');
+    fs.writeFileSync(commitFile, 'selftest fixture commit message\n');
+    fs.writeFileSync(notesFile, 'selftest fixture notes\n');
+
+    const scriptPath = fileURLToPathCompat(import.meta.url);
+    let out;
+    try {
+      out = execSync(
+        `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --gh-notes-file "${notesFile}" ` +
+        `--substantive-packages web-components --stub-packages llm --dry --yes`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      console.error('selftest FAIL: --mode cut --dry plan assembly exited non-zero');
+      console.error(e.stdout || e.message);
+      process.exit(1);
+    }
+
+    const need = [
+      `${GATE_ROSTER.length}-gate roster`,
+      `✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`,
+      'STOPPING per invariant 3',
+    ];
+    for (const marker of need) {
+      if (!out.includes(marker)) {
+        console.error(`selftest FAIL: expected marker not found in plan output: "${marker}"`);
+        process.exit(1);
+      }
+    }
+
+    // The batch-mode hard-reject (H2) must fire BEFORE any of the above runs.
+    let batchOut = '';
+    let batchFailed = false;
+    try {
+      execSync(`node "${scriptPath}" --mode batch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8`, { cwd: REPO, encoding: 'utf8' });
+    } catch (e) {
+      batchFailed = true;
+      batchOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!batchFailed || !batchOut.includes('Scenario 2')) {
+      console.error('selftest FAIL: --mode batch must hard-reject with a pointer to recovery-paths.md §Scenario 2');
+      process.exit(1);
+    }
+
+    console.log('selftest OK');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// import.meta.url → filesystem path (works the same on the platforms this
+// skill runs on; avoids pulling in node:url's fileURLToPath just for this).
+function fileURLToPathCompat(url) {
+  return new URL(url).pathname;
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') {
   rl.close();
-  process.exit(1);
-});
+  selftest();
+} else {
+  main().catch((e) => {
+    console.error(e);
+    rl.close();
+    process.exit(1);
+  });
+}

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// tag-lockstep.mjs — create 10 lockstep tags (umbrella vX.Y.Z + 9
-// per-package <pkg>-vX.Y.Z) at HEAD or at a specified SHA.
+// tag-lockstep.mjs — create 12 lockstep tags (umbrella vX.Y.Z + 11
+// per-package <pkg>-vX.Y.Z, including the 2 plugin packages that joined
+// the lockstep 2026-07-15) at HEAD or at a specified SHA.
 //
 // Usage:
 //   node tag-lockstep.mjs --version 0.6.22
@@ -114,9 +115,30 @@ function main() {
   }
 }
 
-try {
-  main();
-} catch (e) {
-  console.error(`error: ${e.message}`);
-  process.exit(1);
+function selftest() {
+  const tags = buildTagList('1.2.3');
+  if (tags.length !== 12) {
+    console.error(`selftest FAIL: expected 12 tags (umbrella + 11 per-package), got ${tags.length}`); process.exit(1);
+  }
+  if (tags[0] !== 'v1.2.3') {
+    console.error('selftest FAIL: umbrella tag must be first'); process.exit(1);
+  }
+  for (const expected of ['web-components-v1.2.3', 'adia-ui-factory-v1.2.3', 'adia-ui-forge-v1.2.3']) {
+    if (!tags.includes(expected)) {
+      console.error(`selftest FAIL: expected tag '${expected}' missing from buildTagList output`); process.exit(1);
+    }
+  }
+  console.log('selftest OK');
+}
+
+const topArgv = process.argv.slice(2);
+if (topArgv[0] === 'selftest') {
+  selftest();
+} else {
+  try {
+    main();
+  } catch (e) {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+  }
 }

package/skills/adia-ssr/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: adia-ssr
+description: >-
+  Answers why an AdiaUI component crashes, drops content, or renders wrong
+  under SSR (linkedom/Astro consumers) — the three known failure shapes,
+  what's fixed vs open, how to test without a linkedom install. Use when
+  asked "does this work under SSR", "why does X crash/disappear when
+  server-rendered", or "is this connect-time read safe". ANSWERS only. NOT
+  for implementing a fix (adia-author) or consumer host/hydration wiring
+  (adia-host, adia-ui-factory plugin).
+disable-model-invocation: false
+user-invocable: false
+---
+
+# adia-ssr — does it work under SSR, and why not if it doesn't
+
+Two real consumers (adiav2's `admin-portal-fe` and `factory-dashboard`) server-render
+AdiaUI's light-DOM components via Astro 5 + `custom-elements-ssr`, which runs on
+linkedom — a DOM shim with no layout engine and missing browser APIs the framework's
+base class assumes exist. Every SSR bug that's surfaced maps onto one of three root-cause
+shapes; misclassifying a new report against the wrong shape sends the investigation
+to the wrong fix (or worse, invents a redundant one). This pack answers "which shape is
+this" and "what's the state of each shape's fix" — it never carries the fix itself.
+
+## The three shapes, in one line each
+
+1. **A browser-only API is called unconditionally → crash.** `attachInternals`,
+   the four Observer constructors, `document.adoptedStyleSheets`. **Fixed** (gh#285).
+2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.**
+   The mechanism is real, but **narrowed to a static audit** (gh#284, 2026-07-17) —
+   zero shipped components currently pair a non-null template with real light-DOM
+   content, so nothing is exposed today; a forward audit catches a future regression.
+3. **A connect-time layout measurement is treated as confirmed, not unknown.** A zero
+   rect (shim, or real pre-layout connect) drives a wrong persistent decision.
+   **Fixed for one component** (gh#286); the general pattern is unswept.
+
+A fourth item, **property-only components can't seed initial state from SSR HTML**
+(gh#288), is a feature gap explicitly blocked on shape 2's resolution — don't treat it
+as its own independent task.
+
+Full symptom → root-cause → status detail, cited to the actual shipped/open code:
+[`references/failure-shapes.md`](references/failure-shapes.md).
+
+## Consult table
+
+| Ask | Answer from |
+| --- | --- |
+| "why does `<text-ui>`/`<avatar-ui>`/a container lose its content under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §2 — shape 2, NARROWED (doesn't currently reproduce against any shipped component; see the survey before assuming a new report fits this shape) |
+| "why does this crash / throw at construction under SSR" | [`failure-shapes.md`](references/failure-shapes.md) §1 — shape 1, FIXED; the exact guard shape to copy for a NEW instance is [`guard-patterns.md`](references/guard-patterns.md) §1 |
+| "is this connect-time `getBoundingClientRect()`/measurement read safe" | [`failure-shapes.md`](references/failure-shapes.md) §3 + [`guard-patterns.md`](references/guard-patterns.md) §3 — the fixed component's exact shape, and the "unknown ≠ confirmed" principle to apply elsewhere |
+| "what's fixed vs still open for SSR support" | [`status-ledger.md`](references/status-ledger.md) — re-verify against `gh issue view` before trusting it, it drifts |
+| "how do I test an SSR gap — we have no linkedom installed" | [`test-without-linkedom.md`](references/test-without-linkedom.md) — the delete/try/finally pattern, and what it does NOT prove |
+| "what's the consumer's current workaround, and can they drop it yet" | [`consumer-workarounds.md`](references/consumer-workarounds.md) |
+| "table/chart/select renders empty in the SSR response" | [`failure-shapes.md`](references/failure-shapes.md) §4 — shape 4, blocked on shape 2 |
+
+## Deviation doctrine
+
+Every fix pattern this pack cites ([`guard-patterns.md`](references/guard-patterns.md))
+carries the reasoning for why it looks the way it does — the no-op `ElementInternals`
+shim exists because leaving the field `undefined` would relocate a crash, not remove
+it; deletion-based testing exists because this repo has no `linkedom` devDependency.
+If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
+new pattern. Route it through `adia-author` — don't force-fit the nearest existing
+shape.
+
+## Boundaries
+
+- **Implementing any fix — new or matching an existing pattern.** Route to
+  `adia-author`. This pack orients and cites; it never edits
+  `packages/web-components/core/` or any component source.
+- **Consumer-side SSR/hydration host wiring** (an app's own Astro/Next config, which
+  rendering mode to pick, how to structure the hydration boundary). Route to
+  `adia-host` (adia-ui-factory plugin) — this pack answers whether the FRAMEWORK's own
+  components are SSR-safe, not how a consumer app should be structured around them.
+- **A2UI runtime/generation-pipeline SSR concerns** (if any surface later). Route to
+  `adia-a2ui` — this pack is scoped to `UIElement`'s own lifecycle and the
+  component/trait/module layer, not the generative pipeline.
+- **Not a general web-components-SSR tutorial.** Every claim here is cited to this
+  specific framework's actual code, issues, and PRs — general SSR/custom-elements
+  theory that isn't grounded in this repo's own history doesn't belong in this pack.
+
+## Worked example — the answer contract
+
+**Ask:** "`<text-ui>Adia Admin</text-ui>` renders as an empty tag in our SSR output —
+is this a known issue?"
+
+**Answer:** It matches shape 2's SYMPTOM (`connectedCallback` destructively
+re-stamping existing DOM), but shape 2 was narrowed on 2026-07-17 — verify against
+the CURRENT code before reusing the old answer, because this is exactly the case it
+no longer covers. `text-ui`'s `static template` (`packages/web-components/components/text/text.class.js`)
+is `() => null` — `connectedCallback`'s `if (result) stamp(result, this)` never
+enters the branch, so `stamp()` never touches `<text-ui>`'s children at all. This
+component isn't exposed to shape 2; something else is dropping the text — check
+whether `text-ui` is even registered server-side (a different, structural gap: is
+the tag defined before the SSR pass runs?), or whether another mutation (a parent
+re-render, `innerHTML` elsewhere) is clearing it. **The general lesson, not just
+this one component:** before answering "yes, known issue, shape 2" for ANY new
+report, grep the component's own `static template` — if it's the literal
+`() => null`, shape 2 cannot be the cause, no matter how closely the symptom
+matches the old description. [`failure-shapes.md`](references/failure-shapes.md)
+§2 has the full survey (150 components checked) and cites exactly why every
+current children-accepting component is unaffected.
+
+## Corpus of record
+
+Routing-eval corpus: [`evals/routing-corpus.json`](evals/routing-corpus.json).
+This pack is hand-authored from verified session work (not a research-wave corpus) —
+re-sync it per [`status-ledger.md`](references/status-ledger.md)'s own instructions
+whenever an issue referenced here changes state, rather than letting the ledger and
+reality drift apart silently.