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

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

@@ -1,129 +0,0 @@
-# `independent-package-release.md` — class-B cut (an independently-versioned package outside the lockstep)
-
-> Loaded by **mode 12 (Independent-package release)**. Load when releasing a package
-> that versions **independently** of the lockstep set — it is excluded from the
-> lockstep-coherence gate, carries no umbrella tag, and triggers no demo-site deploy.
-> For the lockstep cut (the primary path), use `cycle-happy-path.md` (modes 1–4).
-
-> **Worked example — the @adia-ai monorepo's `packages/plugins/*`.** The concrete
-> package names, gate names, and workflow files below are **the worked example** of
-> this class, drawn from the @adia-ai monorepo's two Claude Code plugins —
-> `@adia-ai/adia-ui-factory` (versioned `0.2.x`) and `@adia-ai/adia-ui-forge`
-> (versioned `0.1.x`) — which live under `packages/plugins/*`, version
-> independently, and are EXCLUDED from the 9-package lockstep. A _different_
-> @adia-ai-style monorepo with its own independently-versioned package keeps this
-> skeleton and substitutes its own package path, exclusion comment, and publish
-> workflow. `$REPO` below = the monorepo root.
-
-## §Why a separate class — two release classes in one monorepo
-
-A lockstep monorepo can host packages that do **not** move with the lockstep set:
-plugins, tools, or any package whose release cadence is deliberately decoupled.
-These are a **class-B independent-package release**, distinct from the **class-A
-lockstep cut** the rest of this skill describes.
-
-| | Class A — lockstep cut (modes 1–4) | Class B — independent-package release (mode 12) |
-| --- | --- | --- |
-| **Versioning** | The whole set bumps together | Each package on its own version line |
-| **Lockstep gate** | Enforced (`check:lockstep` 9/9) | **Excluded** — the gate skips the package by design |
-| **Umbrella tag** | Yes (`vX.Y.Z` + per-package) | **None** — per-package tags only (versions differ) |
-| **`dist-tag` ordering** | Cross-package publish ordering matters | N/A (independent versions; no cross-package `latest` race) |
-| **Demo-site deploy** | Yes (the worked example's `ui-kit.exe.xyz`) | **None** |
-| **Publish trigger** | Tag-triggered per-package workflow | Tag-triggered per-package workflow (same mechanism) |
-
-`SKILL.md §ReleaseInvariants` govern the **class-A lockstep cut**. Class B's
-invariants are the §Posture operator-confirmation checkpoints plus the onboarding
-trip-wires below — and the same verify-against-reality discipline (verify the npm
-registry, not the workflow's reported "success").
-
-> **Worked example.** In the @adia-ai monorepo, `scripts/release/check-lockstep.mjs`
-> skips `packages/plugins/*` by design (there's a comment there saying so), and the
-> plugins publish via their own tag-triggered workflows
-> (`.github/workflows/publish-adia-ui-{factory,forge}.yml`) — exactly like the
-> framework packages but on independent versions. No umbrella tag, no `dist-tag`
-> cross-package ordering, no EXE deploy.
-
-## §New-package onboarding — the three trip-wires a FIRST independent cut hits
-
-A package that is **new to the release tooling** fails three gates the established
-set long since passed. These are **substrate** fixes (release scripts / lockfile /
-CHANGELOG), not skill edits — per the §Teach decision tree, branch A (substrate).
-The skill only *cites* them here. Onboard the package **once**; the fixes land as a
-normal substrate PR on `main` *before* tagging.
-
-1. **Lockfile.** A new workspace package isn't in the lockfile → the pre-commit
-   lockfile-check hook blocks the commit, and the publish workflow's clean install
-   (`npm ci`) fails the same way.
-   *Fix:* regenerate the lockfile only and stage it —
-   `npm install --package-lock-only && git add package-lock.json`.
-2. **Release-trip-wire package registry.** The release trip-wire (F-N1,
-   `check:release`) validates each pushed tag against a registry of known packages.
-   An unregistered tag fails the **pre-push** hook with an `unknown package` error.
-   *Fix:* register the package in that list — its tag-prefix + path.
-   *(Worked example: `scripts/release/check-release.mjs` has a hardcoded `PACKAGES`
-   array — the framework 9; add
-   `{ tagPrefix: '<name>', path: 'packages/plugins/<name>' }`.)*
-3. **CHANGELOG bracket form.** The trip-wire's entry check requires the
-   Keep-a-Changelog `## [<version>]` (brackets) heading. A bare `## <version>`
-   heading fails with a "no `## [<version>]` entry" error.
-   *Fix:* bracket the version headings.
-
-## §Procedure
-
-> The gate/workflow names below are the @adia-ai worked example; substitute your
-> monorepo's own pre-publish gate and publish workflow.
-
-0. **Re-baseline** (the multi-agent baseline assumption). `git fetch`; know HEAD +
-   whether the shared working tree is on a peer's branch.
-1. **Land the package(s) on `main`** via PR — the usual PR-merge gate: resolve
-   **every** review thread (e.g. CodeRabbit) before an admin-merge. A PR-merge gate
-   that requires resolved review threads before `gh pr merge --admin` is a hard
-   precondition — an admin merge over unresolved threads is the failure this guards
-   against. *(See `SKILL.md §Posture` / your monorepo's merge convention.)*
-2. **Pre-publish gate.** Run the per-package version-coherence check (the worked
-   example: `npm run verify:plugins` → N/N synced — `package.json` ↔ the plugin
-   manifest versions). The lockstep gate still passes for the lockstep set (the
-   independent package is excluded). Confirm the names are free on npm:
-   `npm view @adia-ai/<pkg> version` → `E404` means available.
-3. **Tag at the published commit** — `git tag <pkg>-vX.Y.Z` per package (versions
-   differ; **no umbrella tag**). The tag must point at a commit whose `package.json`
-   + bracketed CHANGELOG match: dry-run the release trip-wire over the tag list
-   (worked example: `node scripts/release/check-release.mjs <tags>` → clean) before
-   pushing. **If the shared working tree is on a peer's branch, push the tags from a
-   throwaway worktree on `origin/main`** — never carry a peer's branch state into a
-   tag push.
-4. **Push the tags** → the per-package publish workflows run the clean-install →
-   pre-publish-gate → publish sequence (worked example:
-   `npm ci → verify:plugins → npm publish --access public` with the repo's npm token).
-5. **Verify (against npm, not the workflow).** `npm view @adia-ai/<pkg> version`
-   returns the new version for each package. Watch each workflow to completion
-   (`gh run watch <id> --exit-status`) — but the registry, not the workflow's green
-   check, is the source of truth.
-6. **Marketplace cut-over** (if a plugin marketplace repo exists). Point the
-   marketplace manifest's per-plugin `source` at npm —
-   `{ "source": "npm", "package": "@adia-ai/<pkg>" }` — and `git rm -r` any vendored
-   copies (the canonical home is the monorepo). Validate the JSON, commit, push.
-   Consumers then add the marketplace + install the plugin from npm (e.g.
-   `/plugin marketplace add <org>/<repo>` → `/plugin install <pkg>@<repo>`).
-7. **Audit-history ledger** — same as class A; record the **per-package** versions
-   (independent — they differ per package).
-
-## §Verify Target
-
-The published package(s) on the **npm registry** at their independent versions, plus
-(if a marketplace exists) it references npm. **NOT** "the whole lockstep set + the
-demo site" — that's class A. Verify against the registry, never the workflow's
-reported "success."
-
-## §Gotchas — from the first independent cut (worked example: 2026-06-07, factory v0.2.2 + forge v0.1.2)
-
-- The independent package is **NOT** lockstep — never add it to the lockstep gate,
-  and never tag it with the lockstep umbrella tag.
-- Publish-workflow YAMLs are **token-bearing** — keep `persist-credentials: false`
-  on the checkout step (match the established publish workflows' action-pinning
-  convention).
-- A marketplace repo's **org + visibility is an operator call** — creating a public
-  repo is outward-facing; confirm before `gh repo create`. The repo home may differ
-  from the primary org (the marketplace manifest's `owner` field is the signal; a
-  member without org repo-create rights falls back to a personal repo).
-- Run a **secret-scan of the full history** before pushing any repo public.

package/skills/adia-ui-release/references/ledger-discipline.md

@@ -1,232 +0,0 @@
-# `ledger-discipline.md` — audit-history JSON schema + what to capture
-
-> Loaded by mode 1 Step 11 (Ledger), mode 4 (batch-push ledger), and mode 8 (Investigation — reads past ledgers).
-
-Every release cycle writes a JSON ledger to `.brain/audit-history/YYYY-MM-DD-<kind>-vX.Y.Z.json`. The ledger is the long-term memory of the cycle — what shipped, what was excluded, what was learned. Future cycles read past ledgers (mode 8) and the post-mortem flow (mode 7 + `ops-postmortem` skill) cross-references them.
-
-This file documents the canonical schema + what to capture for each release-kind.
-
----
-
-## §The canonical schema
-
-```json
-{
-  "kind": "release-cut" | "batch-push" | "p1-hotfix" | "post-release-fix",
-  "audit_id": "YYYY-MM-DD-<kind>-vX.Y.Z",
-  "repo": "<org>/<repo>",
-  "released_at": "YYYY-MM-DD",
-  "version": "X.Y.Z",
-  "release_type": "MAJOR" | "MINOR" | "PATCH",
-  "summary": "<one-paragraph>",
-  "scope": { /* free-form keys, one per substantive package or topic */ },
-  "release_commit": "<sha>",
-  "tag_commit": "<sha>",
-  "tags": [ /* all 10 tags */ ],
-  "verification": { /* gate-by-gate summary */ },
-  "publish_workflows": { "dispatched": "9/9 ...", "conclusions": "9/9 success" },
-  "notes": [ /* one entry per lesson, exclusion, anomaly */ ]
-}
-```
-
-The `audit_id` is the file's basename (without `.json`). The `.brain/audit-history/` directory accumulates one such ledger per release cycle. (`make-ledger.mjs` scaffolds the file from git state + `--repo-slug`; the `9/9` counts below are the @adia-ai monorepo's 9-package worked example — substitute your monorepo's package count.)
-
-No `$schema` key: ledgers are self-describing local audit records, so `make-ledger.mjs` deliberately emits no `$schema` (it pointed at a non-bundled external host that this skill does not own or validate against). If your ops setup validates ledgers against a hosted JSON Schema, add the `$schema` field in your own post-processing.
-
----
-
-## §What every ledger MUST capture
-
-These fields are required and the cycle is incomplete without them:
-
-### `audit_id` + `released_at` + `version`
-
-- `audit_id` matches the filename. Format: `YYYY-MM-DD-release-vX.Y.Z` (single-version) or `YYYY-MM-DD-batch-push-vA-vZ` (batch).
-- `released_at` is the YYYY-MM-DD cycle date.
-- `version` is the published semver (no `v` prefix).
-
-### `summary` (the one-paragraph)
-
-A single paragraph (4–6 sentences) covering: substantive packages + scope + new primitives/APIs + retracted features + bundled skill cuts. This is what future operators READ when grepping `.brain/audit-history/`.
-
-Example (v0.6.21):
-
-> "9-package lockstep PATCH cut, authored from scratch. @adia-ai/web- components: table-ui truncate-by-default with [wrap]/[data-wrap] opt-in (§403), toast/feed-item variant text colour fix, input-ui slot-label spacing. @adia-ai/web-modules: `<admin-entity-item>` row- inset alignment, FEEDBACK-37 retraction (admin-shell spurious slot- contract console.warn removed), page-header title-row :first-of-type selector fix. @adia-ai/a2ui-corpus: catalog regen."
-
-### `release_commit` + `tag_commit`
-
-- `release_commit`: the SHA of the actual `chore(release):` or `release(*):` commit (typically the same as `tag_commit` unless an enrichment-pass amended it).
-- `tag_commit`: the SHA the 10 tags point at (= HEAD at tag time).
-
-If those differ (F-N1 enrichment scenario), record BOTH and explain in a `notes` entry.
-
-### `tags` array
-
-All 10 tags (umbrella + 9 per-package), in that order.
-
-### `verification` (gate-by-gate)
-
-A flat object with gate-name → status. Use the same keys across cycles so future search can find regression patterns:
-
-```json
-"verification": {
-  "check_lockstep": "OK at X.Y.Z / ^X.Y.0",
-  "test_unit": "NNNN/NNNN across NN files",
-  "typecheck": "clean",
-  "components_verify": "clean — NN files",
-  "verify_traits": "56/56 (100%)",
-  "check_demo_shells": "clean — NN shells",
-  "check_lightningcss_build": "NN CSS files clean",
-  "verify_corpus": "0 errors / 0 warns",
-  "check_embeddings_fresh": "OK",
-  "check_links": "NNNN files clean",
-  "smoke_engines": "green",
-  "smoke_register_engine": "11/11",
-  "eval_diff_zettel": "cov=N% avg=N (floor cov≥5% avg≥85)",
-  "fn1_trip_wire": "9/9 per-package clean ...",
-  "npm_latest": "X.Y.Z across all 9 packages",
-  "exe_serves": "HTTP 200 (gen-ui)",
-  "gh_releases": "9 created per-package"
-}
-```
-
-Use underscores (`check_demo_shells`) not colons (`check:demo-shells`) in JSON keys — colons aren't valid JSON identifier punctuation.
-
-If a gate FAILED at first and was recovered — record the recovery in `notes`, not in `verification` (which shows final state).
-
-### `publish_workflows`
-
-```json
-"publish_workflows": {
-  "dispatched": "9/9 via gh workflow run --ref <pkg>-vX.Y.Z",
-  "conclusions": "9/9 success"
-}
-```
-
-For batch push, expand:
-
-```json
-"publish_workflows": {
-  "dispatched": "18/18 — vA.B.C set dispatched + settled FIRST, then vA.B.D set (ordering ensures npm latest lands on vA.B.D)",
-  "conclusions": "18/18 success"
-}
-```
-
-### `notes` (the lesson log)
-
-Array of strings, one per significant observation. Examples:
-
-- "STALE TEST FIXED: ..." — when a stale test required updating.
-- "PEER-IN-FLIGHT EXCLUDED: ..." — when a peer file was stashed.
-- "STRAY UNCOMMITTED CHANGE EXCLUDED: ..." — when an uncommitted-but-undocumented change was stashed.
-- "F-N1 flagged N cosmetic diff-coverage warns; enrichment pass applied to ..." — when the enrichment pass ran.
-- "Companion: `<companion-plugin>` vX.Y.Z bundled with this cut" — when a tooling/skill update rides along.
-- "Umbrella tag vX.Y.Z fails F-N1 pattern check — expected; lockstep convention" — boilerplate but worth keeping for archaeological consistency.
-
-The `notes` array is the **highest-information part of the ledger**. This is what future operators read first when investigating a past release.
-
----
-
-## §What ELSE to capture per kind
-
-### `kind: release-cut` (standard single-version)
-
-Add `scope` keys per substantive package:
-
-```json
-"scope": {
-  "web_components": "<one-sentence per substantive feature in this package, with FEEDBACK numbers>",
-  "web_modules": "<same>",
-  "a2ui_corpus": "<same>",
-  "ride_along_stubs": "@adia-ai/llm, @adia-ai/a2ui-compose, ... — version bump only."
-}
-```
-
-### `kind: batch-push` (multi-version)
-
-Add `versions` array + per-version `tag_commits` + `scope` per-version:
-
-```json
-"versions": ["A.B.C", "A.B.D"],
-"tag_commits": {
-  "vA.B.C": "<sha>",
-  "vA.B.D": "<sha>"
-},
-"scope": {
-  "vA.B.C": "<one-paragraph summary of this version>",
-  "vA.B.D": "<same>"
-}
-```
-
-### `kind: p1-hotfix` (urgent fix without normal cycle)
-
-Add `incident` block:
-
-```json
-"incident": {
-  "trigger": "<the symptom that demanded a hotfix>",
-  "detection_lag": "<when shipped → when noticed>",
-  "scope_minimization": "<what was deliberately NOT included to keep the hotfix small>"
-}
-```
-
-Cross-reference `ops-postmortem` skill — the hotfix usually pairs with a postmortem doc.
-
-### `kind: post-release-fix` (correction after publish)
-
-Add `corrects` block:
-
-```json
-"corrects": {
-  "version": "<the version being corrected>",
-  "issue": "<what was wrong>",
-  "resolution_path": "<how — typically a follow-up release>"
-}
-```
-
-Example: a future "v0.6.21.1" or "v0.6.22 fix-only" cycle correcting a v0.6.21 defect would carry this block.
-
----
-
-## §Where to write it
-
-Path: `.brain/audit-history/YYYY-MM-DD-release-vX.Y.Z.json`.
-
-Convention:
-
-- Date is the cycle's `released_at` field (not strictly the local filesystem date; they should match but the field is authoritative).
-- For batch push: `.brain/audit-history/YYYY-MM-DD-batch-push-vA-vZ.json` where A is the oldest and Z is the newest version in the batch.
-
-The file MUST be added in a separate `chore(audit-history)` commit after the release commit ships. Don't bundle it into the release commit — the ledger commit is the cycle's epilogue.
-
----
-
-## §Reading past ledgers (mode 8)
-
-When the operator asks "what shipped in v0.6.X?" or "did we ever fix `<symptom>`?":
-
-```bash
-# Single-version lookup
-cat .brain/audit-history/*-release-v0.6.X.json | jq .
-
-# Search across cycles
-grep -l "FEEDBACK-37" .brain/audit-history/*.json | sort
-grep -l "stale test" .brain/audit-history/*.json | sort
-grep -l "version-skip" .brain/audit-history/*.json | sort
-
-# What gates were ever flagged?
-for f in .brain/audit-history/*.json; do
-  echo "$(basename $f):"
-  jq -r '.notes[] | select(test("FAILED|enrichment|STASHED|EXCLUDED"))' "$f" 2>/dev/null
-done
-```
-
-Memory: `reference_findings_index_and_postmortems` — there's a `.brain/findings/INDEX.md` for open follow-ups and `.brain/postmortems/` for incident write-ups. The audit-history ledgers complement those: ledgers are per-cycle, INDEX/postmortems are per-issue.
-
----
-
-## §When this reference is "done v1"
-
-- Every cycle's ledger uses the canonical schema with no key drift (verifiable via a JSON schema validator or `jq` keys diff).
-- The `notes` array has at least one entry per cycle (the umbrella F-N1 boilerplate counts as the minimum).
-- The next mode-8 investigation (what shipped in v0.6.X?) reads the ledger first, not the GH release page.

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

@@ -1,174 +0,0 @@
-# `migration-guide-authoring.md` — authoring the MIGRATION GUIDE when cutting a breaking release
-
-> Loaded by **mode 11 (Author a migration guide)** and by **mode 1 / 2** whenever the cut is a **MINOR** (an API-surface break — removed/renamed prop, attribute, slot, event, token, or tag). The **producer** side of migrations: you are shipping the breaking change, so you author the guide section consumers will follow. Companion: `changelog-discipline.md` (the CHANGELOG records _what_ landed; the migration guide tells consumers _how to absorb it_).
-
-This is the **producer counterpart** to consumer-side migration. When the framework ships a breaking release, `MIGRATION GUIDE.md` is the canonical record of every BREAKING item + its mechanical search-and-replace recipe. The **consumer side** (sweeping a consumer app's call sites with `git grep` + `perl -i -pe`, then verifying with the build gate) lives in the separate consumer/app-author plugin — it READS this guide. Your job here is to WRITE the section it reads.
-
-> **Scope split (don't blur it):**
->
-> - **Producer (this skill, this file)** — author the `MIGRATION GUIDE.md` version section + migrate the IN-REPO surfaces (demo / exemplar / playground / catalog pages) so the release ships clean.
-> - **Consumer (separate plugin)** — sweep a downstream consumer app against a published guide section. NOT this skill.
-> - **Designing the breaking change itself** — a contract decision, not a migration. Upstream of both.
-
----
-
-## §When you need a migration guide section
-
-Author (or extend) a `MIGRATION GUIDE.md` section when the cut removes or renames a **public API symbol**:
-
-- a removed/renamed **prop or attribute** (e.g. `variant="danger"` → `color="danger"`);
-- a removed/renamed **slot** or **slot semantics flip** (e.g. `[open]` default-hidden → `[collapsed]` default-visible);
-- a removed/renamed **event name** (e.g. `chat-submit` → `submit`);
-- a removed/renamed **token** (e.g. `--n-*` → `--a-*`);
-- a removed/renamed **tag** (e.g. `app-shell` → `adia-shell`);
-- a **Boolean → enum** migration (e.g. `completed` → `status="completed"`);
-- a **default-value behavior change** wide enough that consumers must act.
-
-This is the same line as the **PATCH-vs-MINOR** rule in `cycle-happy-path.md` §Step 4b: **MINOR is reserved for API-surface breaks ONLY.** If you're cutting MINOR, you almost certainly owe a migration-guide section. If the change is a visible-behavior change with no removed/renamed symbol, it stays PATCH and usually needs only a CHANGELOG `### Changed` bullet — **not** a guide section.
-
-Additive cuts (new component, new opt-in attribute, new API) need **no** migration section — note "additive; no consumer sweep" in the version table and move on.
-
----
-
-## §Where the guide lives
-
-`MIGRATION GUIDE.md` is a **top-level consumer artifact at the repo root** (not under `docs/` — the space in the filename is intentional; it's surfaced to consumers as a first-class document). It is READ by the consumer side but MODIFIED only here, at producer time, when a new breaking release is cut.
-
-One section per release that introduces breaking changes, newest at the top. A consumer jumping multiple versions reads the merged span of all sections between their source and target.
-
----
-
-## §The authoring workflow
-
-### Step 1 — Enumerate the breaking surface
-
-From the cut's diff + CHANGELOG `[vX.Y.Z]` `### Removed` / `### Changed` entries, list every breaking item. For each, capture:
-
-- **The symbol** — the exact prop / attr / slot / event / token / tag.
-- **The before → after** — old shape and new shape.
-- **The kind** — pure rename (mechanical) · semantic flip (needs author judgment) · Boolean→enum · removal (no replacement).
-- **The audit grep** — the `git grep -nE` that surfaces call sites.
-- **The sweep** — the `git grep -lE | xargs perl -i -pe` incantation, OR "manual review" if the change can't be safely mechanized.
-
-### Step 2 — Write the section
-
-Section skeleton (per release):
-
-```markdown
-## Migrating to @adia-ai/web-components@X.Y.Z (YYYY-MM-DD)
-
-<one-line scope: how many breaking items, the headline.>
-
-### <item 1 — bold headline> (`old` → `new`)
-
-<one sentence: what changed and why.>
-
-**Audit:**
-
-\`\`\`bash
-git grep -nE '<pattern that surfaces call sites>'
-\`\`\`
-
-**Sweep:**
-
-\`\`\`bash
-git grep -nlE '<pattern>' \
-  | xargs perl -i -pe 's/<old>/<new>/g'
-\`\`\`
-
-### <item 2 …>
-...
-```
-
-Shape rules:
-
-- **One item = one subsection.** Each removed/renamed symbol gets its own `###` with audit + sweep (or a "manual review" note).
-- **Bold-prefix headline + before→after in the heading** — readers grep the heading for the symbol they hit.
-- **Audit grep first, sweep second.** The consumer side ALWAYS audits (lists call sites) before sweeping. Author both so they can.
-- **Mechanical vs manual, explicitly labeled.** A pure rename ships a `perl -i -pe`. A semantic flip / opt-out-Boolean / ownership-move ships a **"manual review — here's why"** note instead, because sed can't tell author intent (see §Manual-review classes below).
-- **One component per sweep regex.** Don't merge `<(toast|alert|tag)-ui …>` alternations — perl/sed alternation captures don't preserve the matched alternative cleanly. One component at a time.
-- **HTML-attribute regexes only match HTML/JSX.** A `<button-ui variant="danger">` sweep won't touch JS `el.variant = 'danger'` — author a separate JS-side regex when the symbol has a programmatic form.
-
-### Step 3 — Migrate the in-repo surfaces FIRST
-
-Before the cut ships, sweep the framework's OWN consumer surfaces — the demo pages, exemplars, playgrounds, and catalog — so the release doesn't ship broken examples of the thing it just changed. Run your own audit + sweep against `apps/`, `playgrounds/`, `catalog/`, `packages/web-components/components/*/*.html`. This is the producer dogfooding the migration: if the in-repo sweep is awkward, the consumer sweep will be worse — fix the recipe now.
-
-### Step 4 — Verify
-
-Run the cut's normal pre-flight gate roster (`cycle-happy-path.md` §Step 3). For a breaking cut, pay special attention to the structural/demo gates (`check:demo-shells`, the static-HTML probes) — they catch in-repo surfaces you missed. A **sweep-verification grep audit** across all extensions catches the trap where a vocabulary migration touched the markup but NOT the CSS selectors that style it or the JS comments that reference it (different files; a markup-only commit looks complete but leaves drift):
-
-```bash
-# For any vocabulary migration where legacy → new shapes coexist or get
-# retired, grep the full legacy-pattern set across ALL extensions at the
-# END of the in-repo sweep. 0 hits = sweep verified clean.
-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' 2>/dev/null
-done
-```
-
-### Step 5 — Cross-reference from the CHANGELOG + release notes
-
-- The breaking package's CHANGELOG `[vX.Y.Z]` `### Removed` / `### Changed` entry should name the symbol AND point at the guide ("see `MIGRATION GUIDE.md` §X.Y.Z").
-- The release notes (`notes-authoring.md`) carry a `⚠️` heads-up paragraph naming the break + linking the guide section, so consumers reading the announcement know to migrate.
-
----
-
-## §Manual-review classes (do NOT auto-sweep)
-
-Some breaking changes look mechanical but aren't. Document them as **manual review** with the reason, never as a `perl -i -pe`:
-
-- **Semantic flips** — a rename that inverts default behavior. Example: `[open]` (default-hidden, opt-in) → `[collapsed]` (default-visible, opt-out). The right migration depends on author intent: if the surface wanted the thing expanded, drop the attr; if hidden, add `collapsed`. List occurrences, ask.
-- **Opt-out Booleans that default true** — when `<x-ui filterable>` is the same as bare `<x-ui>` (filter on by default), the migration only matters where a consumer EXPLICITLY disabled an affordance (`searchable="false"`). Sed can't tell the difference.
-- **Ownership moves** — moving a message/prop from a wrapper to a child (e.g. `<field-ui error="…">` → the message moves to the slotted control) requires knowing which child is the form control; the slot may not exist yet. Manual.
-- **kebab-string property keys** — when the HTML _attribute_ name is unchanged but the JS _programmatic_ form changed (`el['submit-label']` → `el.submitLabel`), attribute-only consumers need no migration. Audit programmatic access only.
-- **Wide tag/token renames (50+ symbols)** — the `@agent-ui-kit/*` → `@adia-ai/*` namespace rename class: tag renames, token-namespace renames (`--n-*` → `--a-*`), class renames (`NanoElement` → `AdiaElement`). Don't auto-sweep the whole surface blind — false positives are likely (a `variant="danger"` on a non-`*-ui` element that shares a prefix). List by table; require human approval per cluster.
-
----
-
-## §The version-coverage table
-
-Maintain a table at the top of `MIGRATION GUIDE.md` that classifies every release so a consumer jumping a gap knows which sections apply:
-
-```markdown
-| Version | Type | Sweeps |
-|---|---|---|
-| `0.0.22` | additive | New shell components; net-new APIs. No consumer sweep needed. |
-| `0.0.21` | additive (no runtime change) | JSDoc/source-doc refresh. Bump the dep; no sweep. |
-| `0.0.20` | BREAKING (N items) | <bullet list of every breaking item + its sweep>. |
-| `0.0.5`–`0.0.19` | additive | No migration sweeps. Bump the dep version. |
-| `0.0.4` | structural | Runtime extracted to a new package; imports retarget. |
-| `@agent-ui-kit/*` → `@adia-ai/*` | rename | Tag + token + class renames (50+). Don't auto-migrate without approval. |
-```
-
-`additive` = bump and go. `BREAKING` = the version has a `###` section with audit + sweep per item. `structural` = import retargeting (package extraction / move). `rename` = wide namespace rename, manual-review by cluster.
-
----
-
-## §Forward-looking surfaces (the next guide author's heads-up)
-
-When a surface is currently additive but accumulating breaking pressure, note it at the bottom of the guide so the NEXT breaking-release author knows where the churn is concentrated — shell components, the gen-UI MCP op-type names, table-family opt-out attributes, etc. A future author reading "this area is volatile" writes a tighter section faster.
-
----
-
-## §Anti-patterns
-
-- **Authoring the guide AFTER the cut ships.** The guide section is part of the breaking-release scope — write it in the same cycle, before the in-repo sweep, so you dogfood the recipe.
-- **A `perl -i -pe` for a semantic flip.** If author intent decides the migration, it's manual review. A mechanical sweep applied to a flip silently mis-migrates surfaces.
-- **Merging component sweeps into one alternation regex.** One component per regex (capture-group preservation).
-- **Skipping the in-repo sweep.** Shipping a breaking release whose own demo pages still use the old shape teaches consumers the wrong thing and trips the demo gates.
-- **A bare CHANGELOG bullet with no guide section for a real break.** The CHANGELOG says _what_; the guide says _how_. A removed symbol needs both.
-- **Treating this as the consumer sweep.** This skill authors the guide + migrates in-repo surfaces. Sweeping a downstream consumer app is the separate consumer/app-author plugin's job.
-
----
-
-## §Verify target (mode 11)
-
-The migration-guide section is "done" when:
-
-1. Every breaking item in the cut's CHANGELOG has a matching `###` subsection (audit + sweep, or a labeled manual-review note).
-2. The in-repo surfaces (demo / playground / catalog) are swept and the sweep-verification grep audit reports **0 legacy hits**.
-3. The breaking cut's structural/demo gates pass.
-4. The release notes carry the `⚠️` heads-up linking the guide section.