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

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

@@ -1,212 +0,0 @@
-# `notes-authoring.md` — Slack + GH-release single-version notes
-
-> Loaded by mode 9 (Authoring discipline only) and by mode 1 Step 10 (GH releases). Covers both the per-version GH-release body and the Slack-flavored team announcement.
-
-The AdiaUI repo has two single-version note formats:
-
-1. **GH release body** — markdown, attached to each per-package tag's GH Release (created via `gh release create <pkg>-vX.Y.Z --notes-file ...`). All 9 packages get the same body.
-2. **Slack release post** — markdown, intended to be pasted into #releases or similar. Shorter, more conversational, has the `npm install` snippet at the top.
-
-Multi-version rollup notes are a separate format — see `rollup-notes.md`.
-
----
-
-## §The GH release body — single version
-
-Audience: external consumers reading the GH Releases page. Substantive
-
-- practical. Each entry should answer "what shipped" + "what do I do with it."
-
-**Standard structure (~80–200 lines per release):**
-
-```markdown
-## vX.Y.Z — <one-line tagline>
-
-9-package lockstep **PATCH** cut. <One sentence on the scope.>
-
-<Optional: a > heads-up callout if there's a behavior change or
-breaking thing.>
-
-### `@adia-ai/<substantive-pkg>`
-
-- **<Bold-prefix headline>.** <Why → what → file paths.> Closes <FEEDBACK-NN>.
-- **<Bold-prefix headline>.** <Same shape.>
-
-### `@adia-ai/<other-substantive-pkg>`
-
-- ...
-
-### 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** across NN files · typecheck clean
-- `components --verify` clean (NN files) · `verify:traits` 56/56
-- `check:demo-shells` clean · `check:lightningcss-build` clean (NN files)
-- `verify:corpus` 0/0 · `check:embeddings-fresh` OK
-- `smoke:engines` green · `smoke:register-engine` 11/11 · `eval:diff zettel` cov=N% avg=N · `check:links` NNNN clean
-
-### Install
-
-\`\`\`bash
-npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
-\`\`\`
-```
-
-**Shape rules:**
-
-- **Open with the tagline + one-sentence scope** — no preamble, no "we're excited to announce." Readers came to find out what's in it.
-- **Group by package** — `### @adia-ai/<pkg>` headings. Use the `@adia-ai/` prefix; it's the npm name + the search key.
-- **Bold-prefix every bullet** with the headline. Then 1–3 sentences: why → what → files. Inline backtick file paths.
-- **Cite tickets by ID** — `FEEDBACK-NN` (or `FB-NN`). Match the CHANGELOG entry's citation style for that cycle.
-- **Show before/after** when a change has consumer-facing markup difference. Use fenced code blocks.
-- **Stubs go in a one-line `### Ride-along stubs`** — list the packages by name. Don't repeat the "lockstep version bump only" text — readers see the same per-cycle.
-- **Verification section** is identical-style across cycles. Paste the gate output from your pre-flight. The repetition is a feature — readers learn what "all green" looks like.
-- **Install matrix** at the bottom — **npm + CDN, both packages** (same mandate as the Slack post). npm: always `@adia-ai/web-components` + `@adia-ai/web-modules` (the universal entry points). CDN: a jsdelivr block pinned `@0.X` — `web-components@0.X/dist/web-components.min.{css,js}` + the `web-modules@0.X/dist/everything.min.js` kitchen-sink. Other packages added if substantive in the cut.
-
-**Anti-patterns:**
-
-- Marketing language. The notes are technical.
-- Vague verbs. "Improved" / "polished" / "tweaked" without specifics is empty.
-- Missing file paths. Inline backticks like `packages/<pkg>/...` let readers grep.
-- Long preambles. Maximum 1 short paragraph before the per-package sections.
-
-### Template — copy this verbatim and fill in
-
-The template lives at `assets/templates/gh-release-notes.template.md` (Phase 2). It maps to a minimal cycle output (~80 lines for a stub-heavy release like v0.6.17, ~200 lines for a substantive cycle like v0.6.18).
-
-For now, the most recent cycles' release notes are reference templates:
-
-- `/tmp/release-v0.6.21.md` — table-ui truncate + FEEDBACK-37 retraction
-- `/tmp/release-v0.6.20.md` — claims-ui-v5 + admin-entity-item
-- `/tmp/release-v0.6.19.md` — claims-ui-v4 batch + corpus remediation
-
----
-
-## §The Slack release post
-
-Audience: internal team in #releases or similar. Shorter, more conversational, with the `npm install` snippet at the top so readers can copy-paste immediately.
-
-**Standard structure (~40–80 lines):**
-
-```markdown
-🚀 **AdiaUI vX.Y.Z** is out — <one-line tagline>
-
-\`\`\`bash
-npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
-\`\`\`
-
-9-package lockstep PATCH cut. <One sentence on scope.>
-
-## <emoji> `@adia-ai/<substantive-pkg>` — <subsection-headline>
-
-<2–4 sentences. The thing that matters.> Closes <FEEDBACK-NN>.
-
-\`\`\`html
-<example markup if useful>
-\`\`\`
-
-## <emoji> Ride-along
-
-<short>
-
-## ✅ Verification
-
-<one-line summary of the gate roster status>
-
-## 📚 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
-```
-
-> **Every `https://ui-kit.exe.xyz/site/<route>` URL cited in notes MUST be verified against `site/sitemap.json` first** (`grep '"path": "/site/…"'`). The docs site is an SPA — unmatched routes return HTTP 200 but render blank, so a curl check won't catch a wrong URL. There is no `/site/gen-ui/` route; the Gen UI Canvas is `/site/playground/gen-ui`. `<theme-panel>` has no standalone page — it's the palette popover on every page. (v0.7.4 incident: both cited URLs were blank.)
-
-**Shape rules:**
-
-- **Open with the rocket emoji + bold version + tagline.** Slack renders this prominently.
-- **Install matrix immediately under the header (MANDATORY — npm + CDN, both packages).** Every note carries the full install surface, in this order:
-  1. **npm** — `npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z` (BOTH packages, never just web-components).
-  2. **CDN** — a jsdelivr block pinned to the `@0.X` minor-range: `web-components@0.X/dist/web-components.min.css` (CSS) + `web-components@0.X/dist/web-components.min.js` (primitives JS), plus the `web-modules@0.X/dist/everything.min.js` kitchen-sink as the all-in-one `<script>` alternative. (CDN bundles ship since v0.6.29/0.6.30.) Operator standard since 2026-05-31. Canonical shape: `.brain/release-notes/0.7.0-release-notes.md`.
-- **Section emojis** — `🔷` (substantive feature), `🛠️` (DX fix), `🎨` (visual), `🧹` (cleanup), `⚠️` (breaking / behavior change), `✅` (verification), `📚` (links). Slack renders these natively.
-- **Skip the per-package grouping** when there's only 1 substantive package. Group by feature instead.
-- **Code blocks for examples** — Slack's modern rich-text composer (since 2020) renders standard markdown fenced code blocks. Memory: `feedback_slack_renders_standard_markdown` — `-` bullets + `[text](URL)` links work natively; legacy `•` + `<URL|text>` mrkdwn isn't needed.
-- **Links section at the bottom** — GH Releases + live demos at minimum.
-
-**Anti-patterns:**
-
-- Marketing speak ("we're thrilled..."). Engineers read this.
-- Long verification sections. One line is enough for Slack; details live in the GH release.
-- Multi-paragraph "context" sections. If the tagline + 2 sentences don't cover it, the change is too complex for a single Slack post — link to the GH release or a longer write-up.
-
-### Where to put the notes
-
-**Canonical home: `.brain/release-notes/{version}-release-notes.md`** (committed with the cycle's ledger — durable repo artifact, not `/tmp`, and not `.brain/notes/` which is for working notes/plans). Open with YAML frontmatter per `.brain/release-notes/README.md`:
-
-```yaml
----
-title: AdiaUI v{version} — release notes
-version: {version}
-topic: release-notes
-status: final
-created: <ISO-8601 UTC, from `date -u +%Y-%m-%dT%H:%M:%SZ`>
-last_edited: <same; bump on edit>
-author: adia-ui-release ({model})
----
-```
-
-The Slack post and GH-release body are **derived from** this file (strip frontmatter for the GH body — see `cycle-happy-path.md` §Step 10). If the operator wants a separate Slack-flavored draft, `/tmp/release-vX.Y.Z/slack.md` is fine for that scratch copy, but the `.brain/notes/` file is the source of record. The operator copy-pastes from whichever they prefer. The `release-pack.mjs` orchestrator (Phase 3) will support a `--push-slack <channel>` flag for direct send, but the default remains draft-to-file — the operator owns the announcement decision.
-
----
-
-## §The verification section — what to actually include
-
-Standard verification block (paste from the cycle's pre-flight output):
-
-- `check:lockstep` line
-- `test:unit` count
-- `typecheck` (one-word "clean")
-- `components --verify` (file count)
-- `verify:traits` (`56/56`)
-- `check:demo-shells` (shell count)
-- `check:lightningcss-build` (CSS file count)
-- `verify:corpus` (`0/0`)
-- `check:embeddings-fresh` (`OK`)
-- `smoke:engines` + `smoke:register-engine`
-- `eval:diff zettel` (cov + avg)
-- `check:links` (file count)
-
-For a substantive cycle, also include any NEW gates added in this cycle (e.g. v0.6.12 added `verify:no-legacy-shell-shapes`; first cycle shipping a new gate calls it out).
-
-Skip optional gates (`check:card-structure`, `check:drawer-structure`, etc.) unless one of them was the lesson of the cycle.
-
----
-
-## §Cross-references — when to cite siblings
-
-A single-version note may need to reference:
-
-- **A previous version** when the current cycle retracts / iterates on it. Example: v0.6.21 retracts FEEDBACK-37 from v0.6.20 — the v0.6.21 note has a heads-up paragraph naming v0.6.20.
-- **A future version** when something is deferred. Less common; use sparingly.
-- **A companion plugin/skill version** when the cycle bundles a tooling update alongside the package cut. Format: "Companion: `<companion-plugin>` **vX.Y.Z** — `<one-line>`."
-- **An ADR** when the cycle ratifies an architectural decision. Format: "Post-mortem at ADR-NNNN." Example: v0.6.21 → ADR-0033.
-
----
-
-## §What NOT to put in the notes
-
-- Internal-only ticket fields (assignee, status before/after, etc.).
-- Implementation details that don't affect consumers (file rename inside a package, refactor that didn't change API).
-- "Coming soon" announcements about future versions. Notes describe shipped work.
-- Profanity, jokes, or off-topic content. Notes are a permanent artifact attached to a tag.
-
----
-
-## §When this reference is "done v1"
-
-- The `gh-release-notes.template.md` and `slack-release.template.md` templates land in `assets/templates/`.
-- The next 3 cycles' notes are authored from the template + the per-cycle CHANGELOG content with no operator improvisation beyond filling in version-specific details.
-- The Slack post copy-paste shape works in Slack's rich-text composer with zero `mrkdwn` (legacy) overrides.

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

@@ -1,215 +0,0 @@
-# `recovery-paths.md` — the 5 recovery scenarios
-
-> Loaded by mode 2 (Author from scratch) when `[Unreleased]` promotion requires extension beyond the peer's early release commit; by mode 4 (Batch push); on F-N1 or pre-flight failure in mode 1; and by mode 7 (Post-release recovery — Phase 3 expansion).
-
-Each scenario below has the **shape** ("what does the repo state look like?"), the **canonical example** (the cycle where it happened), the **resolution** (commands + judgment calls), and **what to write in the ledger**.
-
----
-
-## §Scenario 1 — Version-skip correction
-
-**Shape:** Peer cut a release commit but mislabeled the version. Common form: package.json bumped 0.6.X → 0.6.X+2, skipping 0.6.X+1. The peer's CHANGELOG body may even reference both "the v0.6.X+1 sweep" and "the v0.6.X+2 cut" as if they were two separate releases. Tags don't exist yet; npm latest is still 0.6.X. The commit is unpushed.
-
-**Canonical case:** v0.6.12 correction (2026-05-20).
-
-Peer commit `e8490d96d release(*): v0.6.13 lockstep — admin-shell composition anchors + legacy CSS bridges retired` bumped 0.6.11 → 0.6.13, skipping 0.6.12. The CHANGELOGs referenced "the v0.6.12 dogfooding sweep" and "the v0.6.13 cut" as if both shipped. Operator asked for v0.6.12 release; investigation revealed it was the same body of work, mislabeled.
-
-**Resolution:**
-
-1. Verify the skip — `npm view <pkg> versions --json | tail` confirms no 0.6.X+1 on npm; `git tag --list 'v0.6.X+1*'` confirms no tags. Run pre-flight gates at the peer's commit to confirm content is shippable (no demo-shell fail etc.).
-2. **Correct the version in-place via a NEW commit on top of the peer's commit** (NOT amend — the peer's commit stays for history; `b62992aa0` is the repo precedent).
-3. Run a script (the v0.6.12 cycle used `/tmp/v0612-correct.mjs`) that rewrites every occurrence of the wrong version. For v0.6.12, 25 files needed edits:
-   - 9 × `package.json` (version field)
-   - 9 × `CHANGELOG.md` (header + any body refs)
-   - 4 × admin-shell CSS files (header comment refs)
-   - 1 × ADR-0032 (multiple body refs — be careful to preserve filename references like `v0.6.13-admin-shell-composition-anchors-...md` that intentionally encode the original label)
-   - 1 × FEEDBACK ticket (status line)
-   - 1 × audit note (factual reference)
-   - 1 × `package-lock.json` (regenerate via `npm install --package-lock-only`)
-4. Commit the correction with a `fix(release): correct v0.6.X+2 version-skip → v0.6.X+1` message that documents the discovery.
-5. **THEN** proceed to the standard cycle from Step 5 onward (`cycle-happy-path.md`). Tag, push, publish at v0.6.X+1.
-
-**What to write in the ledger:**
-
-```json
-"version_skip_correction": {
-  "issue": "Peer release commit <sha> ('release(*): v0.6.X+2 ...') bumped 0.6.X → 0.6.X+2, skipping 0.6.X+1. 0.6.X+1 was never tagged or published (npm latest was 0.6.X). The commit's CHANGELOG bodies further framed the work as two separate releases though it is a single commit.",
-  "root_cause": "<usually: multi-phase plan staged across versions; phases collapsed but the label landed on the higher version>",
-  "fix": "Correction commit <new-sha> — 0.6.X+2 → 0.6.X+1 across N files: 9 package.json + 9 CHANGELOG + ..."
-}
-```
-
----
-
-## §Scenario 2 — Batch push
-
-**Shape:** Multiple unpushed `release(*): vX.Y.Z` commits sit on `main` since the last published tag. Each one bumps the version, each has its own CHANGELOG block, each has its own substantive content. The operator asks to "initiate the latest version" or "publish what's accumulated."
-
-**Canonical cases:**
-
-- v0.6.1 → v0.6.6 (6-release batch, 2026-05-19)
-- v0.6.14 + v0.6.15 (2-release batch, 2026-05-20)
-
-**Resolution:**
-
-1. Re-baseline. Identify the cluster of unpushed `release(*):` commits. Order them oldest-to-newest.
-2. For EACH version's release commit:
-   - Identify the tag-point SHA. **Tag at each version's release-commit SHA**, not at HEAD. (Exception to the standard "tag at HEAD" rule — batch push tags each version where it was actually cut.) Memory: `feedback_tag_at_head_not_bump_commit`.
-   - Run pre-flight gates at that SHA (via detached checkout if you want full rigor; or trust the peer's verification if the commits were verified at cut time).
-   - Run F-N1 against the tag candidate — diff-coverage warns may differ per version.
-3. Push `main` (sweeps all commits at once).
-4. Push the per-version tags + umbrella tags (10 tags per version).
-5. **Publish in version order, oldest first**, waiting for each version's 9 workflows to settle before dispatching the next version's 9. This is non-negotiable — `npm dist-tag latest` is set by publish order. If you dispatch v0.6.15 before v0.6.14, you have to manually `npm dist-tag add @adia-ai/<pkg>@0.6.15 latest` after to fix it.
-6. GH releases — author one note per version, then `gh release create` each. The notes can be terser since users will read the rollup.
-7. Site deploy — once at the END (deploys reflect HEAD).
-8. Ledger — write **one batch-push ledger** at `.brain/audit-history/YYYY-MM-DD-batch-push-vA.B.C-vX.Y.Z.json` covering all the versions, instead of N per-version ledgers.
-
-**What to write in the ledger:**
-
-```json
-"kind": "batch-push",
-"audit_id": "YYYY-MM-DD-batch-push-vA-vZ",
-"versions": ["A.B.C", "A.B.D", "A.B.E"],
-"tag_commits": {
-  "vA.B.C": "<sha>",
-  "vA.B.D": "<sha>",
-  ...
-},
-"publish_workflows": {
-  "dispatched": "N/N — vA.B.C set dispatched + settled FIRST, then vA.B.D set, then vA.B.E set (ordering ensures npm latest lands on vA.B.E)",
-  "conclusions": "N/N success"
-}
-```
-
----
-
-## §Scenario 3 — Author from scratch (`[Unreleased]` promotion)
-
-**Shape:** Peer landed source changes + CHANGELOG entries under `## [Unreleased]` but didn't bump versions or cut a release commit. Operator asks to "initiate v0.6.X release."
-
-**Canonical cases:**
-
-- v0.6.19 (claims-ui-v4 FB-22-33 batch — 12 unpushed commits, all under `[Unreleased]`)
-- v0.6.20 (claims-ui-v5 FB-34-39 batch — 14 unpushed commits, all under `[Unreleased]`)
-- v0.6.21 (table-ui §403 + FB-37 retraction — 23 unpushed commits)
-
-**Resolution:** Standard `cycle-happy-path.md` Variant B (Step 4 inserts `[Unreleased]` → `[vX.Y.Z] — DATE` promotion). The CLI helper `scripts/promote-unreleased.mjs` mechanizes the heading swap. For packages that need fresh blocks (the corpus-regen case), author them per `changelog-discipline.md` § Authoring.
-
----
-
-## §Scenario 4 — `[Unreleased]` extension (early-cut release commit + post-bump work)
-
-**Shape:** Peer pre-cut a release commit early (e.g. `f167b72bc release(*): v0.6.18 lockstep — loading state + text-ui`) but then landed MORE commits on top that:
-
-- Have CHANGELOG entries under `[Unreleased]` (the peer was building the next release)
-- Include a fix that **completes the early release's own scope** (e.g. `d6d980072 fix(demo-shells): import skeleton-ui` — fixes the demo shells that f167b72bc's loading-state feature broke)
-
-The early release commit FAILS a release-blocking gate (`check:demo-shells` in v0.6.18). The completing fix is entangled with unrelated `[Unreleased]` work — can't be cleanly cherry-picked back.
-
-**Canonical case:** v0.6.18 — f167b72bc's stat/table demo shells used `<skeleton-ui>` without importing it; `check:demo-shells` failed at that commit. The fix `d6d980072` landed 10 commits later, interleaved with FB-13/14/15/17 `[Unreleased]` work.
-
-**Resolution:** Two options:
-
-1. **Cherry-pick the fix onto the release commit** to make it shippable in its original scope. Off-mainline tag — messy archaeology.
-2. **Extend the release to HEAD** by promoting the `[Unreleased]` content into `[VERSION]`. The release becomes larger but ships everything consistent. ← This is what v0.6.18 did.
-
-**Choose option 2** when the early release commit fails a gate AND the completing fix can't be isolated. Choose option 1 only if the operator explicitly wants the minimal scope.
-
-For option 2:
-
-1. Verify HEAD passes all gates (detached checkout from `f167b72bc` confirms the gate failure there; verify HEAD passes).
-2. Promote `[Unreleased]` → `[VERSION]` in the affected CHANGELOGs (`promote-unreleased.mjs`).
-3. For packages whose changes have NO `[Unreleased]` entry yet but DID change (corpus catalog regen — same case as `changelog-discipline.md` § Authoring), write a fresh `[VERSION]` block.
-4. Commit the CHANGELOG merge with a message that documents the boundary decision (the v0.6.18 cycle's `552bc825f` is the reference).
-5. Tag at the new HEAD; proceed.
-
-**What to write in the ledger:**
-
-```json
-"boundary_decision": {
-  "issue": "Early release commit <sha> failed <gate>. Fix landed in <fix-sha>, entangled with [Unreleased] work that includes <FB list>.",
-  "resolution": "v0.6.X absorbed everything through HEAD. <Unreleased> CHANGELOG sections promoted to [v0.6.X] across <pkg list>. v0.6.X tags land at <merge-sha>."
-}
-```
-
----
-
-## §Scenario 5 — Stale test detection
-
-**Shape:** A pre-flight test fails. The test asserts a behavior the peer deliberately changed in a `[Unreleased]` / `[VERSION]` entry. The failure isn't a regression — it's a stale test that was never updated to match the deliberate change.
-
-**Canonical case:** v0.6.20 — `admin-shell.test.js` 'contains the vanilla-HTML fallback block' test (a v0.6.17 regression guard) asserted the old blanket `[slot="heading"] { display: none }` shape. The v0.6.20 FEEDBACK-38-addendum fix deliberately narrowed it to `:is(span,p,div,h1-6)[slot="heading"], [slot="heading"]:not(:has(> [slot]))` (composed wrappers survive collapse). The peer shipped the CSS change but did NOT update the test.
-
-**Resolution:**
-
-1. **Read the test's assertion + read the CHANGELOG entry that documents the change.** Both should describe the same behavior. If they disagree → one of them is stale.
-2. **Read the actual production code** that the test asserts about. If the code matches the CHANGELOG entry's description → the test is stale. If the code matches the test → the CHANGELOG is wrong (or the change was reverted).
-3. For a stale test: update the assertion to match the new, documented behavior. **Add an inline comment** in the test explaining the v0.X.Y change so future operators don't repeat the diagnosis.
-4. Consider adding a NEW assertion that pins the v0.X.Y contract explicitly (the v0.6.20 case added the `:not(:has(> [slot]))` guard assertion).
-5. Run the test — confirm it passes.
-6. Include the test update in the release commit's allowlist (it's part of the release work — the operator authored the fix that the peer's change implied).
-
-**What to write in the ledger:**
-
-```json
-"notes": [
-  "STALE TEST FIXED: <test path> '<test name>' asserted the old <behavior>. The v0.X.Y <feature> fix deliberately changed it to <new behavior>. The peer shipped the source change but did not update the test. Deploy session updated the assertion to match the new shape + added a guard assertion for the <new contract>. Not a regression — a stale test."
-]
-```
-
----
-
-## §Scenario 6 (bonus) — Concurrent peer mid-cycle
-
-**Shape:** A peer agent is actively modifying files while you're running a release. You see the working tree shift between commands. `git stash pop` may report a conflict. New uncommitted files appear that weren't there 30 seconds ago.
-
-**Canonical case:** v0.6.20 post-stash-pop — the peer committed the FEEDBACK-37 revert (`664cb3f55`) RIGHT AFTER my release shipped, making my stashed admin-shell.js delta redundant. The pop reported "kept the stash."
-
-**Resolution:**
-
-1. **Don't fight the peer.** Their working-tree changes are theirs. Confirm v0.6.X is fully shipped (tag pushed + npm published + GH releases + site deployed + ledger committed) — if yes, the release itself is safe regardless of post-release working-tree chaos.
-2. If you stashed peer files at Step 2 of the cycle, after the cycle completes:
-   - Try `git stash pop`. If clean — great.
-   - If "kept the stash" — investigate: is the stash now redundant (peer committed the same content)? Compare via `git stash show -p stash@{0}` vs the relevant `git log -p` for the file.
-   - If redundant: `git stash drop` (the work was preserved in the peer's commit).
-   - If NOT redundant: leave the stash. It preserves the peer-in-flight change; the peer (or operator) decides next.
-3. Note the situation in the ledger so the next cycle has context.
-
----
-
-## §Decision flowchart — which scenario applies?
-
-```text
-Pre-flight or F-N1 gate failed?
-├── check:demo-shells fails at the release-commit candidate?
-│   └── Look at the post-commit diff: was there a fix-up?
-│       ├── Yes, but entangled with [Unreleased] work → Scenario 4
-│       └── No → Author the fix in this cycle (Mode 2 from scratch)
-├── check:lockstep fails? → typically a peer manually edited an
-│   internal range during a PATCH cut → Scenario 4 or fix in place
-├── verify:corpus fails? → corpus drift → routes to adia-ui-a2ui skill
-├── check:embeddings-fresh fails? → run npm run build:embeddings:chunks;
-│   stage chunk-embeddings.json; document in a2ui-corpus CHANGELOG
-├── test:unit fails? → Scenario 5 (stale test) OR real regression
-│   (read assertion vs CHANGELOG vs source code to tell apart)
-└── F-N1 warns (cosmetic)? → enrichment pass (changelog-discipline.md)
-
-Multiple unpushed release commits exist?
-└── Scenario 2 (batch push)
-
-Peer commit's CHANGELOG references a different version than its bump?
-└── Scenario 1 (version-skip correction)
-
-Working tree has uncommitted source files when you start the cycle?
-└── Apply multi-agent-baseline.md § classification taxonomy.
-    Stash strays per § Discipline 4 if they're release-relevant +
-    undocumented + contradicting.
-```
-
----
-
-## §When this reference is "done v1"
-
-- Each of the 5 (now 6) scenarios has a documented case study in `assets/case-studies/` (Phase 3).
-- The decision flowchart correctly routes the next 5 release cycles with no operator override.
-- Each scenario's ledger-template fragment is reused verbatim by the `make-ledger.mjs` helper (Phase 3) for that scenario.

package/skills/adia-ui-release/references/rollup-notes.md

@@ -1,208 +0,0 @@
-# `rollup-notes.md` — multi-version retrospective notes
-
-> Loaded by mode 5 (Author rollup release notes). Companion to `notes-authoring.md` (single-version notes).
-
-A rollup release note covers a RANGE of versions (e.g. v0.6.8 → v0.6.16, v0.6.16 → v0.6.21). Audience: someone catching up on multiple releases at once — typically external consumers who skipped a few cuts, or internal teammates returning from a holiday, or a Slack announcement for a milestone window.
-
-Two rollup formats have shipped from this skill's lineage:
-
-1. **`/tmp/release-v0.6.8-v0.6.16/rollup.md`** (9 PATCH cuts) — organized by **narrative arcs** (3 themes), with per-version bullet-summaries inside each arc.
-2. **`/tmp/release-v0.6.16-v0.6.21/rollup.md`** (6 PATCH cuts, skill-centric) — opened with the **skill as headline framing**, then per-version package work as substrate. Different headline, same per-version-bullet pattern below.
-
-Both share a common skeleton (this template) but the FRAMING is what makes them distinct.
-
----
-
-## §The 5-section skeleton
-
-```markdown
-🚀 **AdiaUI vA.B.C → vX.Y.Z** — <one-line tagline>
-
-\`\`\`bash
-npm i @adia-ai/web-components@X.Y.Z @adia-ai/web-modules@X.Y.Z
-\`\`\`
-
-<2–4 sentences setting up: how many releases, what the window is
-about, what's load-bearing across all of them (e.g. "internal deps
-held at ^0.6.0 throughout").>
-
----
-
-## 🧵 <Framing section — pick ONE>
-
-<This is the headline. It's the through-line that connects the N
-releases. See §Framing options below.>
-
----
-
-## 📦 Per-version breakdown
-
-### vA.B.C — <tagline>
-
-<3–5 bullets covering substantive work. Inline backtick file paths.
-Reference FEEDBACK-NN closures. Cite the substantive packages.>
-
-### vA.B.D — <tagline>
-
-<same shape>
-
-... (one block per version)
-
----
-
-## ⚠️ <Optional: behavior changes worth knowing>
-
-<Table summarizing breaking / behavior changes across the window
-with opt-out paths. Use sparingly — most PATCH cuts have none.>
-
----
-
-## ✅ Verification baseline (held across all N cuts)
-
-<one-paragraph summary: vitest count growth, gate roster status,
-eval floor held, etc.>
-
-## 📚 Links
-
-- GH Releases: <URL>
-- Live demos: <URL>
-
----
-
-**<Closing paragraph — name what the window accomplished as a whole.
-Connect to the framing section.>**
-```
-
----
-
-## §Framing options — pick ONE for the headline
-
-A rollup is more than a list of releases — it's a STORY. Pick the headline framing that matches the window:
-
-### Option A — "The arcs" (chronological + thematic)
-
-When the window has 2–4 distinct thematic strands. Each strand gets a short subsection naming the versions that contributed.
-
-Example (v0.6.8 → v0.6.16):
-
-> ## 🧵 The three arcs
->
-> **1. Toolchain + build-time correctness** (v0.6.8 / v0.6.9) HTML-parser and CSS-spec traps that broke real consumer builds.
->
-> **2. Consumer DX cliffs** (v0.6.10 / v0.6.11 / v0.6.15) Cold-start failure modes closed with diagnostics or opt-in carve-outs.
->
-> **3. The `<admin-shell>` composition arc** (v0.6.12 → v0.6.16) A five-release refinement of the admin-shell tier.
-
-Best when: the window is mid-cycle, no single dominant theme.
-
-### Option B — "The headline event" (one big thing)
-
-When the window IS one big thing surrounded by supporting work. A skill-graduation window (v0.6.16 → v0.6.21) used this — the headline was a companion consultant skill graduating to a major version; the package releases are substrate.
-
-Example:
-
-> **The headline of this window is not the package releases — it's the skill.** The companion consultant skill (v2.10.0 → v2.20.8) is now the official autonomous-consultant tooling for working with the framework in any LLM-driven coding harness. The package releases that follow are the substrate work that supports it.
-
-Best when: there's a milestone (skill graduation, ADR ratification, substrate completion). The package releases support a larger arc.
-
-### Option C — "Net deltas"
-
-When the window's main story is what consumers SEE differently end- to-end. Like a `git diff vA.B.C..vX.Y.Z` rendered as prose.
-
-Example shape:
-
-> ## 🧵 What changed for consumers
->
-> - **New primitives:** `<admin-entity-item>` (v0.6.20), `<list>`
-> - **New APIs:** `stat-ui loading`, `table-ui loading` (v0.6.18), `table-ui row-click` (v0.6.20), `<list>`
-> - **Breaking-ish:** `<admin-shell mode>` default changed v0.6.13 (rounded borderless); page-header bg iterated v0.6.14 → v0.6.16 → v0.6.20 (canvas-2 → canvas-1 → canvas-0)
-> - **Retired:** legacy `<main>` + `[data-content-*]` admin-shell shape (v0.6.12)
-
-Best when: the window includes a MINOR cut (cumulative change matters) or when a consumer is migrating across a big gap.
-
----
-
-## §Per-version block — sub-template
-
-Each version block has the same shape regardless of framing:
-
-```markdown
-### vN.M.X — <tagline>
-
-`@adia-ai/<pkg>`:
-- **<bold-prefix bullet>.** <One-sentence why → what. File paths
-  inline.> Closes <FEEDBACK-NN>.
-- **<bold-prefix bullet>.** <same shape>
-
-`@adia-ai/<other-pkg>`:
-- <bullets>
-
-Companion: `<companion-plugin>` **vX.Y.Z** — <one-line> (if applicable)
-```
-
-**Length per version**: 3–5 bullets if the version was substantive; 1–2 bullets if it was small. Stub-only versions get a single sentence at most ("v0.6.17 shipped only an admin-sidebar collapse fallback — see GH release for details").
-
-**Skip ride-along stubs** in a rollup. The reader knows lockstep exists; mentioning 6 packages did "no source change" 6 times is noise.
-
----
-
-## §The "behavior changes worth knowing" table
-
-Use a 3-column markdown table when the window has 2+ behavior changes that consumers should track:
-
-```markdown
-| Version | Change | Opt-out / migration |
-|---|---|---|
-| **v0.6.12** | Legacy `<admin-shell>` CSS bridges removed | Migrate to the 10-tag bespoke composition (zero audited consumers affected) |
-| **v0.6.13** | Bare `<admin-shell>` defaults to `mode="rounded borderless"` | Set `mode=""` for the flat legacy chrome |
-```
-
-Skip the table if the window has zero behavior changes. Don't pad it with non-changes.
-
----
-
-## §Verification — one paragraph, not the full table
-
-For a single-version note (`notes-authoring.md`), the verification section lists every gate's status. For a rollup, that's too much — compress to a paragraph:
-
-```markdown
-## ✅ Verification baseline (held across all N cuts)
-
-- **NNNN/NNNN vitest** across NN files at vX.Y.Z (up from NNNN at the
-  start of the arc — net +NN from <reasons>)
-- `check:lockstep` OK · `components --verify` clean · `verify:traits` 56/56 · typecheck clean
-- `check:demo-shells` clean · `check:lightningcss-build` clean (NN CSS files)
-- `verify:corpus` 0 errors / 0 warns · `check:embeddings-fresh` OK
-- `smoke:engines` green · `smoke:register-engine` 11/11 · `eval:diff zettel` cov=N% avg=N (baseline-identical across the window)
-- F-N1 release trip-wire 9/9 per-package clean at every cut
-```
-
-Show the **growth** (test count delta, new gate counts) — that's the window's velocity signal.
-
----
-
-## §The closing paragraph
-
-The last paragraph is the "what did this window accomplish." It echoes the framing section but as a conclusion.
-
-Example (v0.6.16 → v0.6.21, skill-centric framing):
-
-> **The v0.6.16 → v0.6.21 window is the maturation of the companion consultant skill from a documentation skill (v2.x.0) into the autonomous consultant posture (v2.20.8) — with a track record across two consumer cold-start batches (39 tickets between them, all triaged through the skill's own ticket pipeline) and an ADR ratifying the Light-DOM substrate stance the skill teaches first. The package releases are the substrate that backs every claim the skill makes.**
-
-Tight, evocative, names the window's _accomplishment_ (not just its contents).
-
----
-
-## §Where to put the rollup
-
-Save to `/tmp/release-vA.B.C-vX.Y.Z/rollup.md`. The operator copy-pastes where they want it — Slack #releases for an internal announcement, the GH Releases page as a "milestone" body, a CHANGELOG ROLLUP doc in the repo, or a blog post.
-
-If the rollup is **announcement-grade** (skill graduation, MINOR cut, ADR ratification), consider also publishing it to a permanent location (`docs/announcements/` or similar). Coordinate with the operator.
-
----
-
-## §When this reference is "done v1"
-
-- The `rollup-notes.template.md` template lands in `assets/templates/`.
-- The next 2 rollup notes are authored from the 5-section skeleton + one of the 3 framing options with no operator improvisation beyond filling in window-specific details.
-- Each framing option has at least one example in `assets/case-studies/` (Phase 3) so future authors see the shape applied to a real window.