@adia-ai/adia-ui-forge 0.1.2 → 0.8.0

package/skills/adia-release/references/notes-authoring.md

@@ -0,0 +1,90 @@
+# `notes-authoring.md` — release notes: GH body · Slack post · multi-version rollup
+
+> Load for the end-of-cycle notes step or a notes-only request. The GH release
+> body attached to each per-package tag is the **durable record**; drafts live in
+> the session scratch dir and the operator copy-pastes — the skill never posts to
+> Slack directly.
+
+## §Author from the diff, not the intent
+
+Draft every note from `git diff <prev-tag>..HEAD` — what actually shipped — never from an ADR's intent or a PR's plan. The first two commands of any draft:
+
+```bash
+git log --oneline <prev-tag>..HEAD
+git diff --stat <prev-tag>..HEAD
+```
+
+If the diff contradicts the plan (a feature deferred, a refactor split across cuts), the notes follow the diff. This is a discipline because the inverse shipped a real defect: notes copied from an ADR once claimed features that were never staged into the cut. F-N1 catches *undocumented diff*, not *over-claimed notes* — that guard is the author's.
+
+## §The GH release body (single version, ~80–200 lines)
+
+All 9 packages get the same body (`gh release create <pkg>-vX.Y.Z --notes-file …`).
+
+```markdown
+## vX.Y.Z — <one-line tagline>
+
+9-package lockstep **PATCH** cut. <One sentence on scope.>
+
+### `@adia-ai/<substantive-pkg>`
+- **<Bold-prefix headline>.** <Why → what → inline file paths.> Closes <FEEDBACK-NN>.
+
+### Ride-along stubs
+`@adia-ai/<pkg1>`, `@adia-ai/<pkg2>`, … — version bump only.
+
+### Verification
+- `check:lockstep` OK at `X.Y.Z / ^X.Y.0`
+- **N/N vitest** · typecheck clean · `components --verify` clean · `verify:traits` 100%
+- `check:demo-shells` · `check:lightningcss-build` · `verify:corpus` 0/0 · `check:embeddings-fresh` OK
+- `smoke:engines` · `smoke:register-engine` 11/11 · `eval:diff zettel` cov=N% avg=N · `check:links` clean
+
+### Install
+npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
+```
+
+Shape rules: open with the tagline, no preamble; group by `### @adia-ai/<pkg>`; bold-prefix every bullet then why → what → files; cite tickets by ID; before/after fenced blocks for consumer-facing markup changes; paste the verification block from the actual pre-flight output (the cycle-to-cycle repetition is a feature); a breaking cut adds a `⚠️` paragraph linking its MIGRATION GUIDE section. Anti-patterns: marketing language, vague verbs, missing file paths.
+
+## §The Slack post (~40–80 lines)
+
+```markdown
+🚀 **AdiaUI vX.Y.Z** is out — <tagline>
+
+npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
+
+9-package lockstep PATCH cut. <One sentence.>
+
+## 🔷 `@adia-ai/<pkg>` — <headline>
+<2–4 sentences.> Closes <FEEDBACK-NN>.
+
+## ✅ Verification
+<one line>
+
+## 📚 Links
+- GH Releases: https://github.com/adiahealth/gen-ui-kit/releases (filter `vX.Y.Z`)
+- Live demos: https://ui-kit.exe.xyz/site/playground/gen-ui
+```
+
+- **Install matrix is mandatory, npm + CDN, both packages**: npm always names `web-components` AND `web-modules`; the CDN block pins the `@0.X` minor range — `web-components@0.X/dist/web-components.min.{css,js}` plus `web-modules@0.X/dist/everything.min.js` as the all-in-one `<script>`.
+- Section emojis: 🔷 feature · 🛠️ DX fix · 🎨 visual · 🧹 cleanup · ⚠️ breaking/behavior · ✅ verification · 📚 links.
+- Slack renders standard markdown (fenced blocks, `-` bullets, `[text](URL)`); no legacy mrkdwn needed.
+- **Every `https://ui-kit.exe.xyz/site/<route>` URL must be verified against `site/sitemap.json` first** — the docs site is an SPA; an unmatched route returns 200 and renders blank, so curl proves nothing. The Gen UI Canvas is `/site/playground/gen-ui`; there is no `/site/gen-ui/`.
+
+Save drafts to the session scratch dir (e.g. `<scratch>/release-vX.Y.Z/notes.md`); strip nothing for Slack, and the GH body is the same content without the rocket header.
+
+## §Rollup — multi-version retrospective (≥2 versions since the last broadcast)
+
+Audience: consumers or teammates catching up on a window (vA.B.C → vX.Y.Z). Five-section skeleton:
+
+1. **Header** — `🚀 AdiaUI vA.B.C → vX.Y.Z — <tagline>` + install snippet + 2–4 sentences on the window (releases count, what held across all of them, e.g. "internal deps held at ^0.X.0 throughout").
+2. **🧵 Framing section — pick ONE:**
+   - **A. The arcs** — 2–4 thematic strands, each naming its contributing versions. Best mid-cycle with no dominant theme.
+   - **B. The headline event** — one milestone (graduation, ADR ratification) with the package cuts as substrate. Best for milestone windows.
+   - **C. Net deltas** — what consumers see differently end-to-end: new primitives / new APIs / breaking-ish / retired, as a bullet list. Best when the window includes a MINOR or a consumer is jumping a big gap.
+3. **📦 Per-version breakdown** — one block per version: `### vN.M.X — <tagline>` + 3–5 bold-prefix bullets if substantive, 1–2 if small, a single sentence for stub-only versions. **Skip ride-along stubs entirely** — naming 6 no-change packages per version is noise.
+4. **⚠️ Behavior-changes table** (only if the window has ≥2): `| Version | Change | Opt-out / migration |`.
+5. **✅ Verification baseline** — one paragraph, not the full table: test-count growth across the window, gate roster held, eval floors held, F-N1 clean at every cut. Show the *growth* — it's the window's velocity signal. Close with one paragraph naming what the window accomplished, echoing the framing.
+
+Save to `<scratch>/release-vA.B.C-vX.Y.Z/rollup.md`; announcement-grade rollups (milestone, MINOR) can also land as a GH "milestone" release body — operator's call.
+
+## §What NOT to put in notes
+
+Internal ticket fields; implementation details with no consumer effect; "coming soon" futures; jokes — notes are a permanent artifact attached to a tag.

package/skills/adia-release/references/recovery-paths.md

@@ -0,0 +1,106 @@
+# `recovery-paths.md` — the 8 recovery scenarios
+
+> Load on any F-N1 / pre-flight failure, for a batch push, or for post-release
+> recovery. Each scenario: the **shape** (what the repo state looks like), the
+> **resolution** (commands + judgment calls), and what to record. Every scenario
+> is grounded in a real past incident; the durable record of a recovery is the
+> fix commit's message + the PR description — write the "what happened / root
+> cause / fix" there.
+
+---
+
+## §Scenario 1 — Version-skip correction
+
+**Shape:** a peer's release commit mislabels the version — package.json bumped 0.6.X → 0.6.X+2, skipping X+1; the CHANGELOG body may narrate the work as two releases. No tags yet, npm latest still 0.6.X, commit unpushed. (Real case: a "v0.6.13" cut that was actually v0.6.12's work.)
+
+**Resolution:**
+
+1. Verify the skip: `npm view <pkg> versions --json | tail` (no X+1 on npm) + `git tag --list 'vX.Y.*'` (no tags). Run pre-flight at the peer's commit to confirm it's shippable.
+2. Correct the version via a **new commit on top** (not amend — the peer's commit stays for history).
+3. Sweep every occurrence of the wrong version: 9 × package.json, 9 × CHANGELOG (headers + body refs), any doc/CSS-comment refs, then regenerate the lockfile. Preserve filename references that intentionally encode the original label.
+4. Commit as `fix(release): correct vX.Y.Z+1 version-skip → vX.Y.Z` documenting the discovery, then resume [`cut-procedure.md`](cut-procedure.md) at Step 5.
+
+## §Scenario 2 — Batch push
+
+**Shape:** multiple unpushed `release(*): vX.Y.Z` commits since the last published tag; operator asks to "publish what's accumulated."
+
+**Resolution:**
+
+1. Order the release commits oldest → newest.
+2. Per version: **tag at that version's release-commit SHA** (the batch-push exception to tag-at-HEAD), run F-N1 against each tag candidate.
+3. Push `main` once; push tags one-at-a-time (Scenario 7 prevention).
+4. **Publish in version order, oldest first, waiting for each version's workflows to settle** before dispatching the next — `npm dist-tag latest` is set by publish order. `dispatch-publish.mjs --after <prev-version>` gates on `dist-tag latest` to enforce it. If mis-ordered: `npm dist-tag add @adia-ai/<pkg>@<newest> latest` per package.
+5. One GH release note per version; site deploy once at the END (reflects HEAD).
+
+## §Scenario 3 — Author from scratch (`[Unreleased]` promotion)
+
+**Shape:** source + CHANGELOG entries landed under `## [Unreleased]`, no bump, no release commit.
+
+**Resolution:** [`cut-procedure.md`](cut-procedure.md) Variant B; `scripts/promote-unreleased.mjs` mechanizes the heading swap; fresh blocks per [`changelog-discipline.md`](changelog-discipline.md) §Authoring.
+
+## §Scenario 4 — `[Unreleased]` extension (early cut + entangled fix)
+
+**Shape:** a peer pre-cut the release commit early, then landed more commits including a fix that **completes the early cut's own scope** (e.g. the demo-shell import its feature broke) entangled with unrelated `[Unreleased]` work. The early commit fails a release-blocking gate (`check:demo-shells`).
+
+**Resolution — two options:**
+
+1. Cherry-pick the fix onto the release commit (off-mainline tag; messy archaeology). Only when the operator explicitly wants minimal scope.
+2. **Extend the release to HEAD** ← default. Verify HEAD passes all gates; promote the `[Unreleased]` content into `[vX.Y.Z]`; author fresh blocks for changed-but-unlogged packages; commit the CHANGELOG merge with a message documenting the boundary decision; tag at the new HEAD.
+
+## §Scenario 5 — Stale test detection
+
+**Shape:** a pre-flight test fails, but it asserts a behavior a peer *deliberately* changed (the change is CHANGELOG-documented); the test was never updated.
+
+**Resolution:** read three things — the assertion, the CHANGELOG entry, the production source. Code matches the CHANGELOG's described behavior → the test is stale: update the assertion, add an inline comment naming the vX.Y.Z change, optionally pin the new contract with an extra assertion, include the test update in the release allowlist. Code matches the test → real regression (or the CHANGELOG is wrong) — fix that instead.
+
+## §Scenario 6 — Concurrent peer mid-cycle
+
+**Shape:** the working tree shifts between commands; `git stash pop` reports a conflict or "kept the stash."
+
+**Resolution:** don't fight the peer. First confirm the release itself is fully shipped (tags pushed + npm + GH releases + site). Then for a kept stash: `git stash show -p stash@{0}` vs the file's recent `git log -p` — if the peer committed the same content, the stash is redundant → `git stash drop`; if not, leave the stash for the peer/operator to decide. Never blind-drop.
+
+## §Scenario 7 — Tags pushed, ZERO publish workflows fired
+
+**Shape:** all 10 tags exist on origin, but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
+
+**Root cause:** pushing many tags in **one** `git push` fires a single batched create event that GitHub Actions routinely drops. Re-pushing is a no-op (the tags already exist remotely).
+
+**Resolution:**
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
+  --version X.Y.Z --verify-triggered   # re-dispatches ONLY packages with no run; idempotent
+```
+
+For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `release-pack.mjs` does this automatically and follows with `--verify-triggered`.
+
+## §Scenario 8 — Cut on the wrong branch
+
+**Shape:** the cut landed on a peer's local feature branch instead of `main`; caught at push (origin/main at a mid-window commit, tags pointing at the feature tip). (Real case: v0.7.4.)
+
+**Resolution:** recovery is clean **while nothing has published** — publish is `workflow_dispatch`-driven, so npm stays put through the tangle. If the feature tip fast-forwards from main: `git branch -f main <release-sha>` → `git checkout main` → `git push origin main`. Verify `origin/main == vX.Y.Z tag == HEAD` **before** dispatching any publish. Moving tags while local is free (`tag-lockstep.mjs --delete` + re-tag); moving them after a publish is not. **Prevention:** the Step-1 `branch --show-current` check.
+
+---
+
+## §Decision flowchart
+
+```text
+Pre-flight or F-N1 gate failed?
+├── check:demo-shells fails at the release-commit candidate?
+│   └── a later fix exists but is entangled with [Unreleased] work → Scenario 4
+│       otherwise → author the fix in this cycle (Variant B)
+├── check:lockstep fails → peer edited an internal range mid-PATCH → fix in place
+├── verify:corpus fails → corpus drift → route to the A2UI-pipeline skill
+├── check:embeddings-fresh fails → npm run build:embeddings:chunks; stage; note in
+│   the a2ui-corpus CHANGELOG
+├── test:unit fails → Scenario 5 (stale test) OR real regression
+│   (assertion vs CHANGELOG vs source tells them apart)
+└── F-N1 cosmetic warns → enrichment pass (changelog-discipline.md)
+
+Multiple unpushed release commits            → Scenario 2 (batch push)
+Commit's CHANGELOG version ≠ its bump        → Scenario 1 (version skip)
+Tags on origin, no publish runs, npm stale   → Scenario 7 (batched tag push)
+branch --show-current ≠ main                 → Scenario 8 (wrong branch)
+Working tree dirty at cycle start            → classify + stash per
+                                               cut-procedure.md §Step 2
+```

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

@@ -8,7 +8,7 @@
 //   node bump.mjs --from 0.6.20 --to 0.6.21
 //   node bump.mjs --from 0.6.20 --to 0.6.21 --dry
 //
-// Phase 1 of the adia-ui-release skill. Replaces the /tmp/vXXX-prep.mjs
+// Part of the adia-release skill. Replaces the /tmp/vXXX-prep.mjs
 // improvisation pattern from the v0.6.13 → v0.6.21 cycles.
 //
 // Exits:
@@ -31,8 +31,21 @@ const PACKAGES = [
   'packages/a2ui/retrieval',
   'packages/a2ui/runtime',
   'packages/a2ui/validator',
+  // Plugins joined the lockstep 2026-07-15 (see check-lockstep.mjs's POLICY
+  // note). Each also carries a .claude-plugin/plugin.json whose version MUST
+  // move with package.json — plugin.json is the /plugin-update cache key
+  // (verify:plugins gates the sync).
+  'packages/plugins/adia-ui-factory',
+  'packages/plugins/adia-ui-forge',
 ];
 
+// Sibling manifests bumped in the same pass as package.json (path relative to
+// the package dir). Today: the Claude Code plugin manifests.
+const SIBLING_MANIFESTS = {
+  'packages/plugins/adia-ui-factory': '.claude-plugin/plugin.json',
+  'packages/plugins/adia-ui-forge': '.claude-plugin/plugin.json',
+};
+
 function parseArgs(argv) {
   const args = { from: null, to: null, dry: false, repo: process.cwd() };
   for (let i = 0; i < argv.length; i++) {
@@ -96,6 +109,18 @@ function bumpAll(packages, from, to, dry) {
     if (!dry) fs.writeFileSync(p.path, out);
     bumped++;
     console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}: ${from} → ${to}`);
+    const sibling = SIBLING_MANIFESTS[p.pkg];
+    if (sibling) {
+      const sibPath = path.join(path.dirname(p.path), sibling);
+      const sibTxt = fs.readFileSync(sibPath, 'utf8');
+      const sibOut = sibTxt.replace(FROM_PATTERN, TO_LITERAL);
+      if (sibOut === sibTxt) {
+        console.error(`error: ${p.pkg}/${sibling} — regex did not match (plugin.json out of sync?)`);
+        return -1;
+      }
+      if (!dry) fs.writeFileSync(sibPath, sibOut);
+      console.log(`  ${dry ? '[dry] ' : ''}bumped ${p.pkg}/${sibling}: ${from} → ${to}`);
+    }
   }
   return bumped;
 }
@@ -106,7 +131,7 @@ function main() {
   if (!validateAllAtFrom(packages, args.from)) process.exit(1);
   const bumped = bumpAll(packages, args.from, args.to, args.dry);
   if (bumped < 0) process.exit(3);
-  console.log(`\n[bump] ${bumped}/9 ${args.dry ? '(dry — no files written)' : 'bumped'}`);
+  console.log(`\n[bump] ${bumped}/${PACKAGES.length} ${args.dry ? '(dry — no files written)' : 'bumped'}`);
   if (!args.dry) {
     console.log(`\n[next] regenerate the lockfile:`);
     console.log(`  npm install --package-lock-only --no-audit --no-fund`);

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

@@ -14,7 +14,7 @@
 //   # Dry mode:
 //   node dispatch-publish.mjs --version 0.6.22 --dry
 //
-// Phase 2 of the adia-ui-release skill. Mechanizes the dispatch loop
+// Part of the adia-release skill. Mechanizes the dispatch loop
 // + handles the npm-latest ordering rule for batch pushes.
 
 import { execSync } from 'node:child_process';
@@ -35,12 +35,16 @@ const PACKAGES = [
   'a2ui-mcp',
   'a2ui-retrieval',
   'a2ui-validator',
+  // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note).
+  'adia-ui-factory',
+  'adia-ui-forge',
 ];
 
 function parseArgs(argv) {
   const args = {
     version: null, after: null, dry: false, sleepBefore: 4,
     scope: process.env.ADIA_NPM_SCOPE || DEFAULT_SCOPE,
+    verifyTriggered: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const k = argv[i];
@@ -49,13 +53,19 @@ function parseArgs(argv) {
     else if (k === '--dry') args.dry = true;
     else if (k === '--sleep-before') args.sleepBefore = parseInt(argv[++i], 10);
     else if (k === '--scope') args.scope = argv[++i];
+    else if (k === '--verify-triggered') args.verifyTriggered = true;
     else if (k === '-h' || k === '--help') {
-      console.log('Usage: node dispatch-publish.mjs --version X.Y.Z [--after X.Y.Z-1] [--dry] [--sleep-before <seconds>] [--scope @org]');
+      console.log('Usage: node dispatch-publish.mjs --version X.Y.Z [--after X.Y.Z-1] [--verify-triggered] [--dry] [--sleep-before <seconds>] [--scope @org]');
       console.log('');
-      console.log('--after  Verify npm latest is at the given version before dispatching this one.');
-      console.log('         Used in batch push to ensure publish ordering.');
-      console.log(`--scope  npm scope the packages publish under (default: ${DEFAULT_SCOPE};`);
-      console.log('         or set $ADIA_NPM_SCOPE). The --after npm-latest check uses this scope.');
+      console.log('--after            Verify npm latest is at the given version before dispatching this one.');
+      console.log('                   Used in batch push to ensure publish ordering.');
+      console.log('--verify-triggered Instead of dispatching, check whether each per-package publish-<pkg>.yml');
+      console.log('                   ALREADY has a run for the <pkg>-vX.Y.Z tag (i.e. push-on-tag fired), and');
+      console.log('                   re-dispatch ONLY the misses. This is the recovery for the batch-tag-push');
+      console.log('                   skip (recovery-paths.md §Scenario 7) — a single `git push <10 tags>` can');
+      console.log('                   trigger ZERO publish workflows. Idempotent: re-dispatches nothing if all 9 fired.');
+      console.log(`--scope            npm scope the packages publish under (default: ${DEFAULT_SCOPE};`);
+      console.log('                   or set $ADIA_NPM_SCOPE). The --after npm-latest check uses this scope.');
       process.exit(0);
     }
   }
@@ -115,12 +125,68 @@ async function sleep(ms) {
   return new Promise((res) => setTimeout(res, ms));
 }
 
+// Has publish-<pkg>.yml already run for the <pkg>-vX.Y.Z tag? Tag-triggered runs
+// report the tag in the `headBranch` field, so we filter the run list by it.
+// Returns true if at least one run exists for that tag, false otherwise.
+function triggeredForTag(pkg, version, dry) {
+  const tag = `${pkg}-v${version}`;
+  const cmd = `gh run list --workflow="publish-${pkg}.yml" --branch "${tag}" --limit 1 --json databaseId -q '.[0].databaseId // empty'`;
+  if (dry) {
+    console.log(`  [dry] ${cmd}`);
+    return false; // dry preview assumes not-triggered so the re-dispatch path is shown
+  }
+  try {
+    const out = execSync(cmd, { encoding: 'utf8' }).trim();
+    return out.length > 0;
+  } catch {
+    // gh error (auth / rate limit / missing workflow) — treat as "unknown".
+    // Conservative: report not-triggered so the miss is re-dispatched rather than
+    // silently skipped. A redundant re-dispatch is harmless (publish is idempotent
+    // per the workflow's own guard); a skipped publish is the failure we're fixing.
+    return false;
+  }
+}
+
+// The batch-tag-push-skip recovery: verify each per-package publish workflow
+// actually triggered off its pushed tag, and re-dispatch ONLY the misses.
+// Idempotent — re-dispatches nothing if all 9 fired.
+function verifyTriggeredAndRedispatch(version, dry) {
+  console.log(`\nVerifying publish-on-tag triggered for all ${PACKAGES.length} packages (v${version}):`);
+  const misses = [];
+  for (const pkg of PACKAGES) {
+    if (triggeredForTag(pkg, version, dry)) {
+      console.log(`  ✓ ${pkg} — publish run found for ${pkg}-v${version}`);
+    } else {
+      console.log(`  ✗ ${pkg} — NO publish run for ${pkg}-v${version} (batch-push skip) → will re-dispatch`);
+      misses.push(pkg);
+    }
+  }
+  if (misses.length === 0) {
+    console.log(`\n[verify-triggered] all ${PACKAGES.length} publish workflows triggered — nothing to re-dispatch.`);
+    return 0;
+  }
+  console.log(`\n[verify-triggered] ${misses.length} miss(es) — re-dispatching via workflow_dispatch:`);
+  let redispatched = 0;
+  for (const pkg of misses) {
+    if (dispatch(pkg, version, dry)) redispatched++;
+  }
+  console.log(`\n[verify-triggered] re-dispatched ${redispatched}/${misses.length} ${dry ? '(dry)' : ''}`);
+  return redispatched === misses.length ? 0 : 1;
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to run npm/gh against a non-monorepo directory.
   assertMonorepoRoot(process.cwd());
   if (args.after) checkAfter(args.after, args.scope);
 
+  // Recovery mode — verify each publish workflow triggered off its pushed tag,
+  // re-dispatch only the misses (the batch-tag-push skip). Skips the blind dispatch.
+  if (args.verifyTriggered) {
+    const rc = verifyTriggeredAndRedispatch(args.version, args.dry);
+    process.exit(rc);
+  }
+
   if (args.sleepBefore > 0 && !args.dry) {
     console.log(`Sleeping ${args.sleepBefore}s to let GH index the new tags...`);
     await sleep(args.sleepBefore * 1000);

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

@@ -11,13 +11,13 @@
 //     --previous-version 0.6.21 \
 //     --packages llm,a2ui/compose,a2ui/mcp,a2ui/retrieval,a2ui/runtime,a2ui/validator
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline stub-
+// Part of the adia-release skill. Replaces the inline stub-
 // insertion pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21
 // cycles.
 
 import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
+import { resolvePackageChangelog } from './package-paths.mjs';
 
 function parseArgs(argv) {
   const args = {
@@ -72,7 +72,8 @@ function buildStub(version, date, substantive, xref) {
 }
 
 function insertStub(repo, pkg, anchor, stubBlock, version, dry) {
-  const p = path.join(repo, 'packages', pkg, 'CHANGELOG.md');
+  // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+  const p = resolvePackageChangelog(repo, pkg);
   if (!fs.existsSync(p)) {
     console.error(`  ERROR ${pkg} — CHANGELOG.md not found at ${p}`);
     return 'missing';
@@ -101,7 +102,8 @@ function main() {
   const PREV_HEADING_RE = new RegExp(`^## \\[${args.previous.replace(/\./g, '\\.')}\\] — \\d{4}-\\d{2}-\\d{2}$`, 'm');
   const stubBlock = buildStub(args.version, args.date, args.substantive, args.xref);
   const results = args.packages.map((pkg) => {
-    const p = path.join(args.repo, 'packages', pkg, 'CHANGELOG.md');
+    // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+    const p = resolvePackageChangelog(args.repo, pkg);
     if (!fs.existsSync(p)) {
       console.error(`  ERROR ${pkg} — not found`);
       return 'missing';

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

@@ -0,0 +1,50 @@
+// package-paths.mjs — package name-vs-path-form normalization for the
+// standalone CHANGELOG helpers.
+//
+// THE PROBLEM (bit all 6 a2ui packages at the v0.7.14 cut):
+//   The 6 a2ui packages live on disk under `packages/a2ui/<x>/` but carry the
+//   flat npm-name `a2ui-<x>` everywhere else in the tooling (release-pack.mjs,
+//   dispatch-publish.mjs, tag-lockstep.mjs all use the NAME form). The two
+//   standalone helpers (promote-unreleased.mjs, insert-stub.mjs) joined
+//   `packages/<arg>/CHANGELOG.md` with the raw arg, so calling them with the
+//   name form silently 404'd: `CHANGELOG.md not found at packages/a2ui-corpus/`.
+//   release-pack.mjs maps internally (`a2ui-corpus` → `packages/a2ui/corpus`),
+//   so the two forms diverged: name-form failed standalone, path-form failed
+//   when handed to the orchestrator-style callers.
+//
+// THE FIX:
+//   Accept BOTH forms. Try `packages/<arg>` first (path form, backward-compat).
+//   If that directory is absent AND the arg matches `a2ui-<x>`, fall back to
+//   `packages/a2ui/<x>`. So `a2ui-corpus` (name) and `a2ui/corpus` (path) both
+//   resolve to `packages/a2ui/corpus/`.
+//
+// Pure Node, stdlib only — keeps the scripts free of runtime deps.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Resolve a package arg to its on-disk directory under packages/, accepting
+// BOTH the name form (`a2ui-corpus`) and the path form (`a2ui/corpus`).
+// Returns the resolved relative directory (e.g. `a2ui/corpus`); does not
+// require the directory to exist (so callers can render a legible not-found
+// error against the resolved path).
+export function resolvePackageDir(repo, pkg) {
+  if (fs.existsSync(path.join(repo, 'packages', pkg))) return pkg;
+  const m = /^a2ui-(.+)$/.exec(pkg);
+  if (m) {
+    const nested = path.join('a2ui', m[1]);
+    if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
+  }
+  // Plugins live under packages/plugins/<name> but carry the flat name form
+  // (adia-ui-forge) in the release tooling — same name-vs-path split as a2ui.
+  if (/^adia-ui-/.test(pkg)) {
+    const nested = path.join('plugins', pkg);
+    if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
+  }
+  return pkg; // fall through with the original arg so the not-found error names what was asked for
+}
+
+// Resolve a package arg to its CHANGELOG.md path, accepting both forms.
+export function resolvePackageChangelog(repo, pkg) {
+  return path.join(repo, 'packages', resolvePackageDir(repo, pkg), 'CHANGELOG.md');
+}

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

@@ -11,7 +11,7 @@
 //   node promote-unreleased.mjs --version 0.6.22 --date 2026-05-22 \
 //     --packages web-components,web-modules --dry
 //
-// Phase 2 of the adia-ui-release skill. Replaces the inline heading-swap
+// Part of the adia-release skill. Replaces the inline heading-swap
 // pattern used across v0.6.18 / v0.6.19 / v0.6.20 / v0.6.21 cycles.
 //
 // Exits:
@@ -20,8 +20,8 @@
 //   2  — bad args / file I/O error
 
 import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
+import { resolvePackageChangelog } from './package-paths.mjs';
 
 function parseArgs(argv) {
   const args = { version: null, date: null, packages: null, dry: false, repo: process.cwd() };
@@ -52,7 +52,8 @@ function parseArgs(argv) {
 }
 
 function promote(repo, pkg, version, date, dry) {
-  const p = path.join(repo, 'packages', pkg, 'CHANGELOG.md');
+  // Accept both name-form (a2ui-corpus) and path-form (a2ui/corpus). See package-paths.mjs.
+  const p = resolvePackageChangelog(repo, pkg);
   if (!fs.existsSync(p)) {
     console.error(`  ERROR ${pkg} — CHANGELOG.md not found at ${p}`);
     return 'missing';

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

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 // release-pack.mjs — full-cycle orchestrator for an AdiaUI lockstep release.
 //
-// Chains the 6 Phase-1/2/3 CLI helpers (bump · promote-unreleased ·
-// insert-stub · tag-lockstep · dispatch-publish · make-ledger) plus the
-// non-helper steps (lockfile · pre-flight gates · git commit · F-N1 ·
-// push · GH releases · site deploy) into one walked sequence with 3
-// operator checkpoints (before tag, before push, before publish) per
-// SKILL.md §Posture.
+// Chains the 5 CLI helpers (bump · promote-unreleased · insert-stub ·
+// tag-lockstep · dispatch-publish) plus the non-helper steps (lockfile ·
+// pre-flight gates · git commit · F-N1 · push · GH releases · site
+// deploy) into one walked sequence with 3 operator checkpoints (before
+// tag, before push, before publish) per SKILL.md operator checkpoints.
 //
 // MODES:
 //   --mode cut          (Mode 1 — peer pre-staged [Unreleased] or pure stub)
@@ -33,8 +32,8 @@
 //   --skip-gates         : (DEBUG ONLY) skip pre-flight (don't ship anything!)
 //   --skip-site          : skip the EXE deploy step (rare; for offline cycles)
 //
-// PHASE 4 of the adia-ui-release skill. Mechanizes the 11-step cycle from
-// references/cycle-happy-path.md while preserving operator judgment at
+// 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.
 
 import { execSync } from 'node:child_process';
@@ -269,21 +268,50 @@ function step7Fn1(args) {
 }
 
 // ── Step 8 — Push ────────────────────────────────────────────────
+// Pushes per-package tags ONE-AT-A-TIME, not as a single batch.
+//
+// THE BATCH-PUSH SKIP (bit the v0.7.14 cut): `git push origin <10 tags>` in one
+// invocation fires the push-on-tag `create` event ONCE for the whole ref-set,
+// and GitHub Actions routinely drops it — ZERO publish-on-tag workflows trigger.
+// (recovery-paths.md §Scenario 7 — the batch-tag-push publish-skip.)
+// Pushing each per-package tag separately gives the per-package publish-<pkg>.yml
+// `on: push: tags:` trigger its own create event. The umbrella tag is pushed
+// last (it triggers nothing — convention only).
+//
+// Step 9 dispatches all 9 publishes via workflow_dispatch regardless, so the
+// 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) {
-  console.log('\n=== Step 8 — Push main + tags ===');
+  console.log('\n=== Step 8 — Push main + tags (per-tag, NOT batched) ===');
   const count = shQuiet('git rev-list --count origin/main..HEAD', args).trim();
   console.log(`  commits to push: ${count}`);
-  await checkpoint(`Ready to push ${count} commit(s) + 10 tags`, args);
+  await checkpoint(`Ready to push ${count} commit(s) + 10 tags (one-at-a-time)`, args);
   sh('git push origin main', args);
-  const tagList = [`v${args.version}`, ...PACKAGES.map((p) => `${p}-v${args.version}`)].join(' ');
-  sh(`git push origin ${tagList}`, args);
+  const perPkgTags = PACKAGES.map((p) => `${p}-v${args.version}`);
+  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('  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.');
 }
 
 // ── Step 9 — Publish ─────────────────────────────────────────────
+// Step 8 pushed per-package tags one-at-a-time, so push-on-tag may have fired
+// for some/all packages. --verify-triggered checks which publish-<pkg>.yml runs
+// 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 9 triggered (or none did), it does the right thing.
 async function step9Publish(args) {
-  console.log('\n=== Step 9 — Dispatch publishes ===');
-  await checkpoint('Ready to dispatch 9 npm publishes', args);
-  sh(`node ${SCRIPT_DIR}/dispatch-publish.mjs --version ${args.version} --scope ${args.scope}`, args);
+  console.log('\n=== Step 9 — Verify-triggered + re-dispatch misses ===');
+  await checkpoint('Ready to verify the 9 publish triggers + re-dispatch any misses', args);
+  // 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);
   console.log('\n  Waiting for publishes to settle...');
   sh(`until [ "$(gh run list --workflow=publish-a2ui-validator.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`, args);
   console.log('  ✓ publishes settled');
@@ -312,15 +340,9 @@ async function step10GhAndSite(args) {
   }
   sh('npm run build:site', args);
   sh(`rsync -az --delete dist/ ${args.host}:/srv/adia-ui/dist/`, args);
-  sh(`curl -s -o /dev/null -w "EXE gen-ui: HTTP %{http_code}\\n" https://${args.host}/site/gen-ui/`, args);
-}
-
-// ── Step 11 — Ledger ─────────────────────────────────────────────
-function step11Ledger(args) {
-  console.log('\n=== Step 11 — Audit-history ledger ===');
-  const cmd = `node ${SCRIPT_DIR}/make-ledger.mjs --version ${args.version} --date ${args.date} --summary "<TODO: paste from commit message>" --note "Shipped via release-pack.mjs mode=${args.mode}"`;
-  sh(cmd, args);
-  console.log('\n  Edit the generated ledger to fill in scope/verification details, then commit + push.');
+  // 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);
 }
 
 // ── Main ─────────────────────────────────────────────────────────
@@ -328,7 +350,7 @@ 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-ui-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
   step1ReBaseline(args);
   step3PreFlight(args);
   step4PromoteAndBump(args);
@@ -338,9 +360,8 @@ async function main() {
   await step8Push(args);
   await step9Publish(args);
   await step10GhAndSite(args);
-  step11Ledger(args);
   rl.close();
-  console.log('\n✓ release-pack complete. Don\'t forget to commit + push the ledger.');
+  console.log('\n✓ release-pack complete. Verify against the npm registry + GH releases, then author the release notes.');
 }
 
 main().catch((e) => {