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

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

@@ -1,262 +0,0 @@
-# `recovery-paths.md` — the 7 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.
-
----
-
-## §Scenario 7 — Tags pushed but ZERO publish workflows triggered (the batch-tag-push skip)
-
-**Shape:** The cut commit is pushed, all 10 tags (umbrella + 9 per-package) exist on `origin` — but **no `publish-<pkg>.yml` workflow ran**. `gh run list --workflow=publish-<pkg>.yml` shows no run for the new tag. npm `latest` is still the previous version. The packages are NOT on the registry at the new version. Nothing errored; the publishes simply never started.
-
-**Root cause:** GitHub's `on: push: tags:` trigger fires a single `create` event for the whole ref-set when you push many tags in **one** `git push` invocation (`git push origin <tag1> <tag2> … <tag10>` or `git push origin --tags`). GitHub Actions routinely **drops** that batched create event — so ZERO publish-on-tag workflows trigger. This is not a flake you can retry by re-pushing (the tags already exist on the remote; a no-op push fires nothing). Memory: `feedback_publish_workflow_batch_push`.
-
-**Canonical case:** the v0.7.14 cut. All 10 tags pushed in one `git push origin <10 tags>`; zero `publish-*` runs fired. Recovered by manually `gh workflow run publish-<pkg>.yml` (workflow_dispatch) for each package.
-
-**Resolution (recover):**
-
-1. Confirm the symptom — for each package: `gh run list --workflow=publish-<pkg>.yml --branch <pkg>-vX.Y.Z --limit 1`. Empty for all (or most) = the batch skip.
-2. **Re-dispatch the misses via `workflow_dispatch`** (the tags are valid refs; the workflow just never ran for them). The bundled helper does exactly this, idempotently:
-   ```bash
-   node "${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-release/scripts/dispatch-publish.mjs" \
-     --version X.Y.Z --verify-triggered
-   ```
-   `--verify-triggered` checks each `publish-<pkg>.yml` for an existing run on the `<pkg>-vX.Y.Z` tag and re-dispatches ONLY the packages with no run (so it's safe to run after a *partial* trigger too — it won't double-publish the ones that fired). `--dry` previews without calling `gh`.
-3. For a **batch push** (Scenario 2), preserve npm-latest ordering: re-dispatch + settle the OLDER version's 9 before the newer version's 9. `--after X.Y.Z-1` gates on `npm dist-tag latest` to enforce it.
-4. Wait for settle + verify against the **registry** (not the workflow's "success"): `npm view <scope>/<pkg> version` for all 9 + `npm view <scope>/web-components dist-tags.latest`.
-
-**Resolution (prevent — next cut):** push per-package tags **one-at-a-time** so each gets its own create event:
-```bash
-git push origin main
-for t in web-components-vX.Y.Z web-modules-vX.Y.Z … a2ui-validator-vX.Y.Z; do
-  git push origin "$t"
-done
-git push origin vX.Y.Z   # umbrella last — triggers nothing
-```
-`release-pack.mjs` Step 8 now does this automatically, and Step 9 runs `--verify-triggered` to fill any gap; the `tag-lockstep.mjs` push hint prints the per-tag loop + the verify-triggered command. The one-at-a-time push is the primary fix; `--verify-triggered` is the belt-and-suspenders safety net.
-
-**What to write in the ledger:**
-
-```json
-"publish_workflows": {
-  "trigger_anomaly": "Batched tag push (git push origin <10 tags>) triggered ZERO publish-on-tag workflows (the GitHub batch-push create-event skip). Recovered by dispatch-publish.mjs --verify-triggered → re-dispatched N/9 via workflow_dispatch.",
-  "dispatched": "9/9 (workflow_dispatch)",
-  "conclusions": "9/9 success — verified on npm registry, not workflow self-report"
-}
-```
-
----
-
-## §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)
-
-Tags pushed (all 10 exist on origin) but NO publish-<pkg>.yml ran +
-npm latest unchanged?
-└── Scenario 7 (batch-tag-push skip) — re-dispatch misses via
-    dispatch-publish.mjs --verify-triggered; next cut push tags one-at-a-time
-
-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 7) 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.