@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-release/references/gates-catalog.md

@@ -0,0 +1,222 @@
+# `gates-catalog.md` — pre-flight gate roster + failure → recovery map
+
+> Load for a verify-only run or on any gate failure during a cut. Maps every
+> release-flow gate × what it checks × typical failure × recovery. Gates are
+> grouped by **failure category** — how the operator routes when one goes red —
+> not by alphabetical namespace. Cited scripts live in the target monorepo's
+> `package.json` (`check:*` / `verify:*` / `smoke:*` / `test:*`).
+
+Row layout per gate: **What** · **Typical failure** · **Recovery**.
+
+---
+
+## §Category 1 — Release identity (hard-fail any cut)
+
+### `npm run check:lockstep`
+
+- **What:** all 11 `@adia-ai/*` packages declare the same `version`; internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
+- **Typical failure:** one package forgot to bump; a peer edited an internal range mid-PATCH; a `^0.0.x` range slipped in.
+- **Recovery:** version drift → `scripts/bump.mjs` (bundled with this skill); range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
+- **Why `^0.0.x` is forbidden:** npm pre-1.0 semver only widens the caret when major+minor aren't both zero — `^0.0.6` resolves to `>=0.0.6 <0.0.7`, locked to exactly 0.0.6. An internal dep pinned that way silently installs a *stale* sibling on every fresh `npm i` (this shipped a real ~4-day-latent bug before the lockstep policy). The `^X.Y.0` floor (Y≥1) widens correctly across patches; trust the gate, don't reason about caret semantics by hand. Moot at 1.0.0.
+
+### `node scripts/release/check-release.mjs --all-pending` (F-N1, the release trip-wire)
+
+- **What:** for every unpushed tag, verifies CHANGELOG coverage of the diff between this tag and the package's previous tag.
+- **Cosmetic failure:** "diff `packages/<pkg>/components/` touched but CHANGELOG `[X.Y.Z]` doesn't mention 'components'" — the entry names the component (`table-ui`) but not the literal path keyword. Regex miss, change IS documented.
+- **Real failure:** a touched directory has NO matching CHANGELOG entry at all — the cycle missed documenting a change.
+- **Recovery:** cosmetic → add the path keyword to a relevant entry (`table.yaml` → `components/table/table.yaml`); real → author the missing entry. Either way: amend the release commit, delete + re-create the tags at the new SHA, re-run. Full discipline: [`changelog-discipline.md`](changelog-discipline.md) §F-N1 enrichment.
+- The umbrella tag's "doesn't match `<pkg>-v<version>`" **error is expected — ignore it**; only per-package warns need action.
+
+### `npm run check:changelog-coverage`
+
+- **What:** every published package has a `[vX.Y.Z]` CHANGELOG block for the current `package.json` version.
+- **Recovery:** add the block (stub if genuinely no source change — but classify by the diff first, see [`changelog-discipline.md`](changelog-discipline.md) §Detecting source-changing packages).
+
+---
+
+## §Category 2 — Generated-file coherence (hard-fail any cut)
+
+### `node scripts/build/components.mjs --verify`
+
+- **What:** every component yaml has an up-to-date `.a2ui.json` sidecar; `.d.ts` codegen current. (Generated files are also hook-guarded against hand edits.)
+- **Recovery:** `node scripts/build/components.mjs` (no `--verify`) regenerates; stage the sidecars.
+
+### `npm run verify:traits`
+
+- **What:** `traits/_catalog.json` reflects every `defineTrait()` call; 100% coverage.
+- **Recovery:** `npm run build:traits`; stage.
+
+### `npm run verify:a2ui-schema`
+
+- **What:** the A2UI JSON Schema is in sync with the `@adia-ai/a2ui-runtime` TS types.
+- **Recovery:** `node scripts/build/a2ui-schema-types.mjs`; stage.
+
+### `npm run verify:tsconfig-strictness`
+
+- **What:** per-package `tsconfig.json` doesn't silently relax flags set strict in `tsconfig.base.json` (ADR-0029). A relaxation needs a `// TS-MIG-NNN` tracking comment.
+- **Recovery:** remove the override, or add the tracking comment.
+
+---
+
+## §Category 3 — Component / primitive structural drift
+
+### `npm run check:demo-shells`
+
+- **What:** every component demo `.html` imports all primitives named in its yaml `composes:` list.
+- **Typical failure:** a yaml gained a `composes:` entry but the demo shell didn't get the matching `<script>` import.
+- **Recovery:** add `<script type="module" src="../<tag>/<tag>.js">` to the demo shell. **Release-blocking: HIGH** — a commit failing this gate ships broken demo pages in its tarball. If the fix already landed later but entangled with `[Unreleased]` work → [`recovery-paths.md`](recovery-paths.md) §Scenario 4.
+
+Smaller siblings in this category (same recovery shape — fix the declaration or regenerate the registry):
+
+| Gate | What |
+| --- | --- |
+| `check:composes` | every yaml `composes:` entry resolves to a real primitive |
+| `check:dts-sibling-presence` | every component `.js` has a sibling `.d.ts` |
+| `check:registry-catalog-coherence` | runtime registry ↔ A2UI catalog parity (both directions) |
+| `check:required-icons` | every referenced `<icon-ui>` name is registered |
+| `check:standalone-html-phosphor` | standalone demos using Phosphor icons include the loader |
+| `check:substitutable-set-drift` | substitutable-element registry in sync |
+
+---
+
+## §Category 4 — CSS spec compatibility
+
+### `npm run check:lightningcss-build`
+
+- **What:** every CSS file under `packages/web-{components,modules}/` minifies cleanly under LightningCSS + current Vite default targets.
+- **Recovery:** fix the offending CSS. Most common sub-case ↓
+
+### `npm run check:scope-bare-descendants`
+
+- **What:** no `@scope { > X {} }` bare-combinator descendants (LightningCSS rejects as "Invalid empty selector").
+- **Recovery:** `node scripts/build/codemod-scope-bare-descendants.mjs` rewrites `> X` → `& > X`.
+
+Also: `check:no-self-import-css` (no transitively self-importing barrel) · `check:rolldown-glob` (`import.meta.glob` works under Rolldown).
+
+---
+
+## §Category 5 — Browser safety / module hygiene
+
+### `npm run check:browser-safe`
+
+- **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
+- **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/a2ui/retrieval/component-catalog.js`.
+
+Siblings: `check:absolute-imports` (no leading-`/` imports — rewrite relative) · `check:template-interp` (template `${expr}` contract) · `check:yaml-events` (yaml `events:` match runtime `dispatchEvent` calls) · `check:yaml-impl-coverage` (every yaml prop implemented in the JS class).
+
+---
+
+## §Category 6 — Visual / structural integrity
+
+| Gate | What |
+| --- | --- |
+| `check:card-structure` / `check:drawer-structure` | card/drawer body wraps in `<section>` (strict variants of the `audit:*` twins) |
+| `check:with-css-pairing` | every shell with paired `.js` + `.css` has a `/with-css` companion + exports-map entry |
+| `verify:no-legacy-shell-shapes` | no legacy `<main>` / `[data-content-*]` shapes under `<admin-shell>` (ADR-0032) |
+| `audit:native-primitive-leak` | native `<button>`/`<input>`/… where a `*-ui` equivalent exists; criticals must be replaced or annotated `data-native-ok="<reason>"` |
+| `audit:shell-composition` | admin-shell compositions missing canonical parts (statusbar, `[data-spacer]`/`[data-actions]`, …); escape hatch `data-shell-opt-out="<reason>"` |
+
+The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findings get folded into release notes if non-zero. Recovery for both is manual — slot/attr semantics need a human eyeball, never auto-fix.
+
+---
+
+## §Category 7 — Corpus / bundle freshness
+
+### `npm run verify:corpus`
+
+- **What:** every chunk in `packages/a2ui/corpus/chunks/*.json` is reachable and well-formed.
+- **Recovery:** corpus remediation routes to the A2UI-pipeline skill, not this one.
+
+### `npm run check:chunks-fresh`
+
+- **What:** `chunks/_index.json` matches on-disk chunks and source fragments.
+- **Recovery:** `npm run harvest:chunks`; stage the corpus outputs.
+
+### `npm run check:embeddings-fresh`
+
+- **What:** `chunk-embeddings.json` at-or-newer-than `chunks/_index.json`.
+- **Recovery:** `npm run build:embeddings:chunks` (needs `OPENAI_API_KEY`; ~6s). Stage `chunk-embeddings.json` + note the regen in the a2ui-corpus CHANGELOG `[vX.Y.Z]`.
+
+### `npm run check:css-bundles-fresh` / `npm run check:js-bundles-fresh`
+
+- **What:** the `dist/` CDN bundles (`web-components.min.{css,js}`, `everything.min.js`, per-shell `*.min.js`, `icons-manifest.js`) match source. Stale bundles mean jsdelivr/unpkg serve yesterday's build. **Blocking in CI** (2026-06-08).
+- **Recovery:** `npm run build -w @adia-ai/llm` **FIRST** (its `index.js` is a gitignored tsc artifact `build:bundle-js` resolves — a fresh worktree can't bundle without it), then `npm run build:bundles` (or `build:bundle-css` / `build:bundle-js` individually). Stage both `dist/` trees.
+- **Manual spot-checks** (complement the gate; the v0.6.29–31 cycles shipped a shells-only `everything.min.js` that hard-crashed CDN consumers):
+
+  ```bash
+  grep "import '@adia-ai/web-components'" packages/web-modules/everything.js   # must be present
+  grep -oE '"[a-z][a-z-]*-ui"' packages/web-modules/dist/everything.min.js | sort -u | wc -l   # ≥100
+  node -e "const m=require('./packages/web-components/dist/icons-manifest.js'); \
+    console.log('regular:', m.default.regular.length, '| cdn:', m.default.cdn)"   # non-empty + cdn key
+  ```
+
+### `npm run audit:chunk-reconcile`
+
+- **What:** duplicate-reconciliation report for the chunk corpus (fingerprint collisions, near-duplicates, structural twins). Advisory, not blocking.
+
+---
+
+## §Category 8 — Tests + types + evals
+
+### `npm run test:unit`
+
+- **What:** the vitest suite (~1000+ tests).
+- **Stale-test failure:** the test asserts a behavior a peer deliberately changed (CHANGELOG-documented) without updating the assertion. Tell it apart by reading assertion vs CHANGELOG vs source: if the code matches the CHANGELOG's described behavior, the test is stale — update the assertion (see [`recovery-paths.md`](recovery-paths.md) §Scenario 5). Real regression → fix the regression.
+- **Parallel-contention flake:** heavy web-modules composite suites can fail under full parallelism on a loaded machine (`signals: drain loop exceeded 100 iterations`). Load-dependent, not a code defect. **Gate on `npx vitest run --no-file-parallelism`** (sequential is the source of truth); don't treat a one-off parallel flake as a blocker, and don't raise the drain guard.
+
+### `npm run eval:diff -- --engine zettel`
+
+- **What:** end-to-end gen-UI eval. Floors (preserve-not-regress):
+  - **Zettel**: cov ≥ 87%, avg ≥ 85, MRR ≥ 0.94
+  - **Free-form**: cov ≥ 90%, avg ≥ 83, F1 ≥ 55
+  - **Monolithic**: cov = 100%, avg ≥ 95
+  - **Dogfood**: 20/20, avg ≥ 95
+- **Recovery:** retrieval/corpus regression — routes to the A2UI-pipeline skill.
+
+Siblings: `typecheck` (`tsc --noEmit`) · `smoke:engines` (gen-UI engines + retrieval probes) · `smoke:register-engine` (11/11) · `test:a2ui` (22/22, +1 skipped OK).
+
+---
+
+## §Category 9 — Misc release safety
+
+### `npm run dogfood:status`
+
+- **What:** aggregator over the component dogfood audits; classifies findings P0–P3 and regenerates the tracker at `qa/findings/dogfood-tracker.md`. Exit-1 when P0+P1 > 0; P2/P3 are advisory.
+- **Pre-cut policy: must pass before tag.** Any P0/P1 means a paid-down bug class was re-introduced; open the tracker, apply the canonical fix template at the cited file:line, re-run. ~5s.
+
+### `npm run verify:pack`
+
+- **What:** `npm pack --dry-run` succeeds per package — catches malformed `files`/`exports`. Note: the npm `files:` array supports negation (`!components/**/*.html`); verify tarball contents with `--dry-run` after touching it.
+
+Siblings: `check:links` (intra-repo markdown links resolve) · `check:cdn-pins` (docs' CDN `@0.X` pins match the current minor — catches a stale `@0.6` after a `0.7` cut) · `verify:contrast` / `verify:palette` (WCAG pairs / OKLCH ramps).
+
+---
+
+## §Standard subsets
+
+**Minimum 6 (verify-only default)** — fastest set that catches release-blockers:
+
+```bash
+node scripts/build/components.mjs --verify
+npm run check:lockstep
+npm run verify:traits
+npm run test:unit
+npm run typecheck
+npm run check:demo-shells
+```
+
+Add `verify:corpus` + `check:embeddings-fresh` if chunks were touched; `check:lightningcss-build` if CSS was touched; F-N1 if unpushed release tags exist.
+
+**Full pre-cut sweep** — the 17-gate roster in [`cut-procedure.md`](cut-procedure.md) §Step 3. ~90s wall time.
+
+**Omnibus** — `npm run check` invokes everything. Heavy; use when re-baselining a stale checkout.
+
+**Suffix variants:** most gates have `:strict` (warns fail), `:fix` (auto-apply, e.g. `check:lockstep:fix`), `:json` / `:quiet` (output form) variants.
+
+---
+
+## §Gate stewardship
+
+- **This catalog must stay in sync with `package.json` `scripts`.** When a cycle meets a release-flow gate not listed here, add its row in the same change.
+- **New CI gates ship advisory first** (`continue-on-error: true`), promoted to blocking after 5+ green runs. Two freshness-gate traps: mtime checks are permanently red on fresh `actions/checkout` (clone-time mtimes — need `fetch-depth: 0` + git-restore-mtime); a dir-watching gate needs its own workflow whose `pull_request: paths:` covers the watched dirs.
+- **New/extended `scripts/release/check-*.mjs` slots run against `main` immediately**; close every finding same-cycle. Before adding a slot, grep the existing ones — the gap is often a regex limit in a current slot, not a missing slot.

package/skills/adia-release/references/independent-package-release.md

@@ -0,0 +1,52 @@
+# `independent-package-release.md` — class-B cut (independently-versioned package)
+
+> Load when releasing a package versioned **independently** of the lockstep set —
+> excluded from the lockstep gate, no umbrella tag, no demo-site deploy.
+> **Class B currently has NO members** (2026-07-15 policy change, operator
+> ruling): the Claude Code plugins under `packages/plugins/*` joined the
+> lockstep after class-B independence let npm drift a full harness-reset
+> behind the repo (npm served forge 0.1.3/factory 0.2.4 pre-reset content
+> while the rewritten estate sat unpublished at a regressed 0.1.0). This
+> procedure is retained for future genuinely-independent packages. The
+> lockstep cut is [`cut-procedure.md`](cut-procedure.md).
+
+## §Two release classes in one monorepo
+
+| | Class A — lockstep cut | Class B — independent package |
+| --- | --- | --- |
+| Versioning | whole set bumps together | own version line per package |
+| Lockstep gate | enforced (`check:lockstep` 11/11) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (none currently exist; `packages/plugins/*` joined class A 2026-07-15) |
+| Umbrella tag | `vX.Y.Z` + per-package | **none** — per-package tags only (versions differ) |
+| `dist-tag` ordering | cross-package publish order matters | N/A |
+| Demo-site deploy | yes | **none** |
+| Publish trigger | tag-triggered per-package workflow | same mechanism (`.github/workflows/publish-adia-ui-{factory,forge}.yml`) |
+
+Class B keeps the operator checkpoints and the verify-against-the-registry discipline; it drops every lockstep-specific invariant.
+
+## §New-package onboarding — the three trip-wires a FIRST cut hits
+
+Substrate fixes (release scripts / lockfile / CHANGELOG), landed once as a normal PR on `main` *before* tagging:
+
+1. **Lockfile.** A new workspace package absent from the lockfile blocks the pre-commit hook and fails the workflow's `npm ci`. Fix: `npm install --package-lock-only && git add package-lock.json`.
+2. **Release-trip-wire package registry.** F-N1 validates each pushed tag against `scripts/release/check-release.mjs`'s hardcoded `PACKAGES` array; an unregistered tag fails the pre-push hook with `unknown package`. Fix: add `{ tagPrefix: '<name>', path: 'packages/plugins/<name>' }`.
+3. **CHANGELOG bracket form.** The trip-wire requires Keep-a-Changelog `## [<version>]` headings; bare `## <version>` fails with "no `## [<version>]` entry".
+
+## §Procedure
+
+1. **Re-baseline** — `git fetch`; confirm the checkout isn't on a peer's branch.
+2. **Land the package(s) on `main`** via PR; resolve every review thread before an admin-merge (this repo's merge gate).
+3. **Pre-publish gate.** `npm run verify:plugins` (package.json ↔ plugin-manifest versions synced). Plugin-specific structural gates: `npm run audit:plugin-coupling` + `npm run check:factory-bare-repo` (ADR-0040 — the plugin must work in a bare consumer repo, no monorepo coupling). The lockstep gate still passes for the lockstep set. First publish of a name: `npm view @adia-ai/<pkg> version` → `E404` means the name is free.
+4. **Tag at the published commit** — `git tag <pkg>-vX.Y.Z` per package; versions differ; no umbrella. Dry-run the trip-wire over the tags (`node scripts/release/check-release.mjs <tags>`) before pushing. If the shared working tree is on a peer's branch, push tags from a throwaway worktree on `origin/main`.
+5. **Push the tags** → the per-package workflows run `npm ci → verify:plugins → npm publish --access public`.
+6. **Verify against npm, not the workflow:** `npm view @adia-ai/<pkg> version` returns the new independent version for each package. Watch runs (`gh run watch <id> --exit-status`), but the registry is the source of truth.
+7. **Marketplace cut-over** (if a plugin marketplace repo exists): point the manifest's per-plugin `source` at npm (`{ "source": "npm", "package": "@adia-ai/<pkg>" }`), `git rm -r` vendored copies, validate the JSON, commit, push. Consumers then `/plugin marketplace add <org>/<repo>` → `/plugin install <pkg>@<repo>`.
+
+## §Verify target
+
+The published package(s) on the **npm registry** at their independent versions, plus (if a marketplace exists) its manifest referencing npm. NOT "all 11 + the demo site" — that's class A.
+
+## §Gotchas (from the first independent cut, factory v0.2.2 + forge v0.1.2)
+
+- Never add the package to the lockstep gate or tag it with the umbrella.
+- Publish-workflow YAMLs are token-bearing — keep `persist-credentials: false` on the checkout step, matching the established workflows' action-pinning.
+- A marketplace repo's org + visibility is an **operator call** — a public `gh repo create` is outward-facing; confirm first, and run a secret-scan of full history before pushing any repo public.

package/skills/adia-release/references/migration-guide-authoring.md

@@ -0,0 +1,86 @@
+# `migration-guide-authoring.md` — authoring the MIGRATION GUIDE on a breaking cut
+
+> Load whenever the cut is **MINOR** (an API-surface break) or on an explicit
+> "author the migration guide" ask. This is the **producer** side of migrations:
+> the release ships the breaking change, so the release authors the guide section
+> consumers follow. The shared producer/consumer format contract is
+> [`../../../references/contracts/migration-guide-format.md`](../../../references/contracts/migration-guide-format.md)
+> — the factory's `adia-migrate` skill consumes exactly that shape.
+>
+> Scope split: **producer (this skill)** authors the guide section + migrates the
+> framework's own in-repo surfaces. **Consumer** (a downstream app sweep) is the
+> factory plugin's `adia-migrate` — decline and redirect. Designing the breaking
+> change itself is a contract decision upstream of both.
+
+The guide lives at **`.claude/docs/MIGRATION GUIDE.md`** (the space in the filename is intentional; it's a first-class consumer artifact). One section per breaking release, newest at top; a consumer jumping versions reads the merged span. Every cut — breaking or not — gets a version-scope bullet in the top index (see the format contract).
+
+## §When a section is owed
+
+Author (or extend) a section when the cut removes or renames a **public API symbol**: a prop/attribute (`variant="danger"` → `color="danger"`), a slot or slot-semantics flip, an event name, a token (`--n-*` → `--a-*`), a tag, a Boolean → enum migration, or a default-value change wide enough that consumers must act. Same line as the PATCH-vs-MINOR rule: cutting MINOR almost certainly owes a section. Additive cuts need none — note "additive; no consumer sweep" in the version-coverage table and move on.
+
+## §The authoring workflow
+
+**1. Enumerate the breaking surface** from the cut's diff + CHANGELOG `### Removed`/`### Changed` entries. Per item capture: the symbol · before → after · the kind (pure rename / semantic flip / Boolean→enum / removal) · the audit grep · the sweep (or "manual review").
+
+**2. Write the section** — one `###` subsection per item:
+
+```markdown
+## Migrating to @adia-ai/web-components@X.Y.Z (YYYY-MM-DD)
+
+<one-line scope: N breaking items, the headline.>
+
+### <item — bold headline> (`old` → `new`)
+
+<one sentence: what changed and why.>
+
+**Audit:**
+git grep -nE '<pattern that surfaces call sites>'
+
+**Sweep:**
+git grep -nlE '<pattern>' | xargs perl -i -pe 's/<old>/<new>/g'
+```
+
+Shape rules:
+
+- **Audit grep first, sweep second** — the consumer always lists call sites before sweeping; author both.
+- **Mechanical vs manual, explicitly labeled.** A pure rename ships a `perl -i -pe`; a semantic flip ships a "manual review — here's why" note (sed can't tell author intent).
+- **One component per sweep regex** — alternation captures (`<(toast|alert)-ui`) don't preserve the matched alternative cleanly.
+- **HTML-attribute regexes only match HTML/JSX** — author a separate JS-side regex when the symbol has a programmatic form (`el.variant = 'danger'`).
+
+**3. Migrate the in-repo surfaces FIRST.** Before the cut ships, run the audit + sweep against `apps/`, `playgrounds/`, `catalog/`, `packages/web-components/components/*/*.html` — the release must not ship broken examples of the thing it changed, and dogfooding the recipe here is what proves it works for consumers.
+
+**4. Verify.** Run the cut's normal gate roster; the structural/demo gates catch missed in-repo surfaces. Then the **sweep-verification grep** across ALL extensions — the trap is a vocabulary migration that touched markup but not the CSS selectors or JS comments referencing it:
+
+```bash
+LEGACY_PATTERNS=( '<old-tag' 'old-attr=' '--old-token' )
+for pat in "${LEGACY_PATTERNS[@]}"; do
+  echo "=== $pat ==="
+  grep -rln -E "$pat" apps playgrounds catalog \
+    --include='*.css' --include='*.html' --include='*.js' --include='*.yaml'
+done   # 0 hits = sweep verified clean
+```
+
+**5. Cross-reference.** The breaking package's CHANGELOG entry names the symbol AND points at the guide section; the release notes carry a `⚠️` heads-up linking it. Anchors are stable — never retitle an existing section (release notes and consumer tooling link them).
+
+## §Manual-review classes (never auto-sweep)
+
+- **Semantic flips** — a rename that inverts default behavior (`[open]` default-hidden → `[collapsed]` default-visible): the right migration depends on author intent. List occurrences, ask.
+- **Opt-out Booleans defaulting true** — the migration only matters where a consumer explicitly disabled the affordance; sed can't tell.
+- **Ownership moves** — a prop moving from wrapper to slotted child; the target child may not exist yet.
+- **kebab-string property keys** — attribute name unchanged, only the JS programmatic form changed; audit programmatic access only.
+- **Wide namespace renames (50+ symbols)** — tag/token/class rename waves: list by table, require human approval per cluster; blind sweeps hit false positives on shared prefixes.
+
+## §The version-coverage table
+
+Maintained at the top of the guide; classifies every release so a gap-jumping consumer knows which sections apply: `additive` (bump and go) · `BREAKING (N items)` (has a section) · `structural` (import retargeting) · `rename` (wide namespace rename, manual-review by cluster). Note forward-looking volatile surfaces at the bottom of the guide so the next breaking-release author knows where churn concentrates.
+
+## §Anti-patterns
+
+Authoring the guide after the cut ships (it's part of the release scope) · a `perl -i -pe` for a semantic flip · merged alternation sweeps · skipping the in-repo sweep · a CHANGELOG bullet with no guide section for a real break (the CHANGELOG says *what*, the guide says *how*) · doing the consumer sweep from here.
+
+## §Done when
+
+1. Every breaking item in the cut's CHANGELOG has a matching subsection (audit + sweep, or a labeled manual-review note).
+2. In-repo surfaces swept; the sweep-verification grep reports 0 legacy hits.
+3. The cut's structural/demo gates pass.
+4. The release notes carry the `⚠️` heads-up linking the section.

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 11 packages get the same body (`gh release create <pkg>-vX.Y.Z --notes-file …`).
+
+```markdown
+## vX.Y.Z — <one-line tagline>
+
+11-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
+
+11-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 12 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,11 +8,11 @@
 //   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:
-//   0  — all 9 bumped successfully (or --dry succeeded)
+//   0  — all 11 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)
@@ -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`);