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

package/skills/adia-release/references/cut-procedure.md

@@ -0,0 +1,247 @@
+# `cut-procedure.md` — the standard lockstep cut
+
+> Load for any class-A lockstep cut (cut & ship · author from scratch · deploy
+> handoff). Companions: [`gates-catalog.md`](gates-catalog.md) (gate roster +
+> failure routing), [`changelog-discipline.md`](changelog-discipline.md) (promotion
+> + F-N1 enrichment), [`recovery-paths.md`](recovery-paths.md) (when it goes wrong).
+> The concrete gate names, 9 package paths, and `ui-kit.exe.xyz` deploy are the
+> @adia-ai monorepo's worked example of the portable discipline. `$REPO` = repo root.
+
+Two entry variants, converging at Step 5:
+
+- **Variant A — deploy handoff:** a peer pre-cut the release commit + CHANGELOG + bump + lockfile. Re-baseline, verify, then resume at Step 6 (tag).
+- **Variant B — author from scratch:** source landed under `## [Unreleased]` with no bump. Do Step 4 (promotion + bump + lockfile), then the full tail.
+
+`scripts/release-pack.mjs` (bundled) mechanizes the whole sequence with the three operator checkpoints preserved; the steps below are the manual/diagnostic form.
+
+| Step | Action | Mutates? |
+| --- | --- | --- |
+| 1 | Re-baseline (branch check + status + log + fetch) | No |
+| 2 | Classify uncommitted files; stash strays | Stash only |
+| 3 | Pre-flight gates (+ harvest preamble if source content changed) | No |
+| 4 | (Variant B) Promote `[Unreleased]`; bump; lockfile | Yes |
+| 5 | Stage the release allowlist; commit on `release/vX.Y.Z` | Yes |
+| 5.5 | Pre-commit freshness trip-wire | No |
+| 5.7 | Release PR: push branch → CI → merge → re-baseline on `main` | PR + merge |
+| 6 | Tag umbrella + per-package at post-merge HEAD — **checkpoint 1 first** | Yes |
+| 7 | F-N1 release trip-wire; enrich CHANGELOGs on warns | If warns |
+| 8 | Push tags (one per push; `main` already merged) — **checkpoint 2 first** | Push |
+| 9 | Dispatch publish workflows; wait; verify registry — **checkpoint 3 first** | Publish |
+| 10 | GH releases + site deploy | Deploy |
+| 11 | Author release notes (default, not optional) | No |
+
+---
+
+## §Step 1 — Re-baseline
+
+Context is stale at the start of every turn; run unconditionally:
+
+```bash
+git -C "$REPO" branch --show-current   # MUST print: main
+git -C "$REPO" status --short
+git -C "$REPO" log --oneline -8
+git -C "$REPO" fetch && git -C "$REPO" log HEAD..origin/main --oneline   # must be empty
+git -C "$REPO" tag --list 'vX.Y.Z' '*-vX.Y.Z'   # must NOT exist yet
+```
+
+`branch --show-current` ≠ `main` → stop; cutting on a feature branch pushes a stale `main` ref while the tags point at the feature tip. Recovery: [`recovery-paths.md`](recovery-paths.md) §Scenario 8. If multiple unpushed `release(*):` commits exist → this is a batch push, [`recovery-paths.md`](recovery-paths.md) §Scenario 2.
+
+## §Step 2 — Classify uncommitted files; stash strays
+
+Modified/untracked files you didn't author are classification decisions — diff each one. A **stray** = uncommitted + undocumented (no CHANGELOG entry or commit explains it) + behavior-visible + contradicting a release artifact. Stash strays; never revert (revert destroys the work):
+
+```bash
+git -C "$REPO" stash push <file1> <file2> -m "vX.Y.Z-cycle: <reason> — parked"
+```
+
+Keep the stash held through the site deploy (Step 10) — the tarball builds from the **tag** but the site builds from the **working tree**; an uncommitted stray leaks into the deployed site and not the packages, silently. Pop after the cycle; if pop reports "kept the stash", see [`recovery-paths.md`](recovery-paths.md) §Scenario 6. Record any exclusion in the release-commit message (`Excluded — in-flight: <file> (<reason>)`).
+
+## §Step 3 — Pre-flight gates
+
+### 3.0 Harvest preamble (only when source content changed in the window)
+
+If `git diff <prev-tag>..HEAD --name-only` touches component yaml / `.a2ui.json` sources, `*.contents.html`, catalog/site pages with `data-chunk-*` annotations — regenerate downstream artifacts proactively (otherwise the freshness gates force a tag-move recovery later):
+
+```bash
+node scripts/build/components.mjs      # catalog + per-component sidecars
+npm run harvest:chunks                 # chunk corpus from site/apps/playgrounds/catalog
+npm run build:embeddings:chunks        # embedding index (needs OPENAI_API_KEY)
+npm run build -w @adia-ai/llm          # tsc artifact build:bundle-js resolves
+npm run build:bundles                  # dist CSS+JS bundles
+```
+
+**Regen output supersedes working-tree state.** These outputs land in the release commit unconditionally, even when the same paths are also dirty from a peer — the fresh regen is authoritative; divergent uncommitted work rebases on top afterwards.
+
+### 3.1 The full roster — every gate runs; a subset = pre-flight failure
+
+```bash
+node scripts/build/components.mjs --verify    #  1 yaml ↔ sidecar ↔ .d.ts
+npm run verify:traits                          #  2 trait coverage
+npm run check:lockstep                         #  3 version coherence
+npm run test:unit                              #  4 vitest
+npm run typecheck                              #  5 tsc --noEmit
+npm run check:demo-shells                      #  6 demo imports cover composes:
+npm run check:lightningcss-build               #  7 CSS minifies
+npm run check:css-bundles-fresh                #  8 dist CSS matches source
+npm run check:js-bundles-fresh                 #  9 dist JS matches source
+npm run smoke:engines                          # 10 gen-UI engines
+npm run smoke:register-engine                  # 11 register-engine 11/11
+npm run verify:corpus                          # 12 corpus 0 errors
+npm run check:chunks-fresh                     # 13 chunk index vs sources
+npm run check:embeddings-fresh                 # 14 embeddings vs chunk index
+npm run check:links                            # 15 intra-repo links
+npm run eval:diff -- --engine zettel           # 16 eval floors
+npm run dogfood:status                         # 17 P0/P1 dogfood floor
+```
+
+Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source, re-run the narrowest gate, then re-run the full sequence. The canonical miss: a cut that ran 7 of the gates shipped a stale-embeddings defect that surfaced a day later and cost a tag-move recovery.
+
+## §Step 4 — (Variant B) Promote, bump, lockfile
+
+**4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`scripts/promote-unreleased.mjs`); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`scripts/insert-stub.mjs`). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
+
+**4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
+
+**4c. Lockfile.** `npm install --package-lock-only --no-audit --no-fund` — must land in the release commit. The publish workflows open with `npm ci`, which hard-fails on a version/lockfile mismatch: a bump without the regenerated lockfile passes locally and breaks **every** publish at clean-install.
+
+**4d.** `npm run check:lockstep` → `OK — all packages at X.Y.Z, all internal ranges at ^X.Y.0`.
+
+## §Step 5 — Stage and commit (on a release branch)
+
+The release commit lands via PR, never a direct push to `main` (repo
+policy, operator ruling 2026-07-12 — everything ships PR-first). Branch
+FIRST, then stage. Defensively clear the index, then stage by explicit
+allowlist (never `git add -A`; if peers may have pre-staged files,
+`git commit -o <paths>` also bypasses a polluted index):
+
+```bash
+git -C "$REPO" checkout -b "release/vX.Y.Z"
+git -C "$REPO" reset HEAD >/dev/null 2>&1
+git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
+  packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md   # + in-scope source + Step-3.0 regen outputs
+git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
+```
+
+Commit shape: `chore(release): vX.Y.Z lockstep — <summary>` with substantive scope per package, ride-along stub list, any `Excluded — in-flight:` lines, and the pasted gate summary.
+
+## §Step 5.5 — Pre-commit freshness trip-wire
+
+After `git add`, before `git commit`, re-run the three freshness gates against staged state:
+
+```bash
+node scripts/build/components.mjs --verify && npm run check:chunks-fresh && npm run check:embeddings-fresh
+```
+
+Drift here means a regen output was left out of the allowlist — stage it and re-run. <2s now vs ~5min of tag-move recovery after CI catches it. Do not proceed to tag with drift.
+
+## §Step 5.7 — Release PR: push the branch, merge, re-baseline
+
+The release commit reaches `main` through the standard PR flow:
+
+```bash
+git -C "$REPO" push -u origin "release/vX.Y.Z"
+gh pr create --title "release: vX.Y.Z lockstep" --body "<scope + gate summary>"
+# wait for required checks (fail-soft jobs excluded); then merge per house flow:
+gh pr merge <N> --admin --merge --delete-branch
+git -C "$REPO" checkout main && git -C "$REPO" pull
+```
+
+Post-merge fixes land as follow-up commits to the SAME release PR (or a
+second PR merged before tagging) — the tag point below is always `main`'s
+post-merge HEAD, so anything merged before tagging ships in the tarball.
+If unrelated PRs merged between yours and the tag step, that is fine: tag
+at HEAD is the invariant, and the window closes at the tag.
+
+## §Step 6 — Tag ← operator checkpoint 1 (before tagging)
+
+Show the operator the planned tag list + the F-N1 preview; proceed only on their go. Then tag **at `main`'s post-merge HEAD** (post-bump fixes belong in the tarball; the window's last merge is the tag point — exception: batch push tags each version at its own release-merge SHA):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/tag-lockstep.mjs" \
+  --version X.Y.Z                        # umbrella vX.Y.Z + 11 <pkg>-vX.Y.Z (incl. the 2 plugins, 2026-07-15 policy)
+```
+
+## §Step 7 — F-N1 release trip-wire
+
+```bash
+node scripts/release/check-release.mjs --all-pending
+```
+
+Per-package tags must be `✓ clean`; the umbrella-tag error is expected noise. On warns, run the enrichment pass ([`changelog-discipline.md`](changelog-discipline.md) §F-N1): fix the entry, land it as a follow-up commit through the PR flow (`--amend` is no longer possible — the release commit is already merged), delete + re-create the tags at the new post-merge SHA, re-run.
+
+## §Step 8 — Push tags ← operator checkpoint 2 (before pushing tags)
+
+`main` is already on the remote (the release PR merged in Step 5.7) —
+only the tags push here. Show the tag list + confirm
+`git rev-list --count origin/main..HEAD` is 0 (a non-zero count means
+local commits bypassed the PR flow — stop and route them through a PR
+first); on go:
+
+```bash
+for t in web-components-vX.Y.Z web-modules-vX.Y.Z llm-vX.Y.Z a2ui-runtime-vX.Y.Z \
+         a2ui-compose-vX.Y.Z a2ui-corpus-vX.Y.Z a2ui-mcp-vX.Y.Z \
+         a2ui-retrieval-vX.Y.Z a2ui-validator-vX.Y.Z \
+         adia-ui-factory-vX.Y.Z adia-ui-forge-vX.Y.Z; do
+  git -C "$REPO" push origin "$t"        # ONE tag per push — batched multi-tag
+done                                     # pushes drop the create event (Scenario 7)
+git -C "$REPO" push origin vX.Y.Z        # umbrella last; triggers nothing
+```
+
+## §Step 9 — Publish ← operator checkpoint 3 (before publishing)
+
+For batch pushes, confirm ordering with the operator: **oldest version publishes and settles first** — `npm dist-tag latest` is set by publish order. Then:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
+  --version X.Y.Z --verify-triggered     # re-dispatches only missing runs
+```
+
+Wait for the workflows to settle, then verify against the **registry**, never the workflow's green check:
+
+```bash
+for pkg in web-components web-modules llm a2ui-runtime a2ui-compose a2ui-corpus \
+           a2ui-mcp a2ui-retrieval a2ui-validator adia-ui-factory adia-ui-forge; do
+  echo -n "$pkg: "; npm view "@adia-ai/$pkg" version
+done
+npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
+```
+
+Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.md) §Scenario 7.
+
+## §Step 10 — GH releases + site deploy
+
+```bash
+for pkg in <the 9>; do
+  gh release create "$pkg-vX.Y.Z" --title "@adia-ai/$pkg vX.Y.Z" --notes-file <body>.md
+done
+# Site deploy goes through the pipeline, never a raw rsync (operator go required — deploy is checkpoint-class):
+gh workflow run "Deploy site (ui-kit.exe.xyz)" --repo adiahealth/gen-ui-kit --ref main
+```
+
+Deploy discipline (the release tenant of the demo-site host; VM/service ops belong to the deploy skill, `adia-deploy`):
+
+- `deploy-site.yml` owns build → pre-flight verify → snapshot → rsync → post-deploy verify → auto-rollback; it builds from `main`, so the release commit must already be merged (§Step 5.7 guarantees this). A raw local rsync bypasses every one of those gates.
+- **Verify deployed FILES, never SPA routes.** The docs site returns HTTP 200 + the same ~5 KB shell for *every* path; an unmatched route renders blank with no error. Curl a content file and grep for real bytes:
+
+  ```bash
+  curl -s -o /dev/null -w "%{http_code}\n" https://ui-kit.exe.xyz/packages/web-components/styles/host.css   # 200
+  curl -s https://ui-kit.exe.xyz/<this-cycle's-content-file> | grep -q "<unique string>" && echo OK
+  ```
+
+- Any docs **route** cited to the operator or in notes must exist in `site/sitemap.json` (`grep '"path":'`) — a plausible-looking route that isn't in the sitemap renders blank.
+
+Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
+
+## §Step 11 — Author release notes (default)
+
+Always author notes at end-of-cycle without being asked — context is freshest now. Single version → [`notes-authoring.md`](notes-authoring.md); ≥2 versions since the last broadcast → its §Rollup section. Surface the draft inline for copy-paste; the operator owns posting. Skip only on an explicit "no notes".
+
+---
+
+## §Variant A shortcut
+
+Peer pre-cut the release commit: Step 1 (confirm HEAD is the `release(*): vX.Y.Z` commit) → Step 2 → Step 3 → skip 4–5 → resume at Step 6.
+
+## §When to abort
+
+Stop and surface to the operator when: a gate fails outside the documented recoveries; F-N1 reports >1 warn per package tag or any non-umbrella error; the release-commit candidate fails `check:demo-shells` / `check:lockstep` / `check:embeddings-fresh` (→ [`recovery-paths.md`](recovery-paths.md) §Scenario 4); uncommitted files stay unclassifiable after diffing; or a publish workflow fails E404/E401 (npm-token rotation — operator-owned).

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 9 `@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` 9/9) | **excluded** — the gate skips `packages/plugins/*` by design |
+| 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 9 + 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.