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

package/skills/adia-ui-release/assets/case-studies/2026-05-20-version-skip-correction-v0.6.12.md

@@ -1,114 +0,0 @@
-# Case study — v0.6.12 version-skip correction
-
-**Cycle:** 2026-05-20 (v0.6.11 → v0.6.12) **Scenario:** `recovery-paths.md` § Scenario 1 (version-skip) **Source ledger:** `.brain/audit-history/2026-05-20-release-v0.6.12.json` **Outcome:** Peer commit mislabeled v0.6.13; corrected in-place to v0.6.12 across 25 files; shipped cleanly.
-
----
-
-## §The shape
-
-User asked: _"prepare and initiate 0.6.12 release"_.
-
-Operator re-baselined and found:
-
-- All 9 `package.json` at version `0.6.13` (not `0.6.12`).
-- NO `v0.6.12` tags anywhere.
-- npm latest: `0.6.11` (operator had shipped it 1 turn earlier).
-- The most recent commit: `e8490d96d release(*): v0.6.13 lockstep — admin-shell composition anchors + legacy CSS bridges retired (FB-04 follow-up / FB-05 dogfood / ADR-0032)`. **Unpushed.**
-
-A peer agent had cut a release commit labeled v0.6.13, jumping straight from v0.6.11 → v0.6.13. The CHANGELOG bodies even referenced both _"the v0.6.12 dogfooding sweep"_ AND _"the v0.6.13 cut"_ as if they were separate releases. Inspecting the commit content showed they were the same work.
-
----
-
-## §The diagnosis
-
-The peer had executed a multi-phase plan (`.brain/notes/2026-05-20-v0.6.13-admin-shell-composition-anchors.md`) that originally staged the work across v0.6.12 + v0.6.13 + v0.7.0, then collapsed all the phases into one commit but kept the v0.6.13 label.
-
-Symptoms confirming "single commit mislabeled" (vs "two separate releases, one missing"):
-
-- One release commit, not two.
-- `e8490d96d`'s file footprint matched the cumulative diff for both "phases" the CHANGELOGs described.
-- ADR-0032 named `v0.6.13` as the cut version (singular).
-- `.brain/notes/2026-05-20-v0.6.12-bespoke-css-coverage-audit.md` (the audit note) line 19 explicitly: _"Scope decision (corrected from plan (then-named v0.7.0, shipped as v0.6.13) §Phase 0 Step 4)"_ — the peer themselves had already flagged the misattribution but hadn't reconciled the version label.
-
-User wanted v0.6.12. The peer's work was v0.6.12-shape. The label was the only thing wrong.
-
----
-
-## §The fix
-
-**One correction commit on top** of the peer's commit (NOT amending — the peer's commit is preserved for archaeology; `b62992aa0` is the repo precedent for forensic correction-commits).
-
-The correction rewrote every occurrence of the wrong version:
-
-| Category | Files | Touches |
-| --- | --- | --- |
-| `package.json` version field | 9 | 9 |
-| `CHANGELOG.md` headers + body refs | 9 | ~18 |
-| admin-shell CSS header comments | 4 | ~8 |
-| ADR-0032 (lockstep cut + Decision/Consequences/Verification refs) | 1 | ~6 |
-| FEEDBACK-05 ticket draft (status line) | 1 | 1 |
-| v0.6.12 audit note (factual ref) | 1 | 1 |
-| `package-lock.json` (regenerated via `npm install --package-lock-only`) | 1 | many |
-| **Total** | **25 files** | **~50 edits** |
-
-A Node script (`/tmp/v0612-correct.mjs`) handled the mechanical sweep with two regex patterns:
-
-```js
-// Most files — replace 0.6.13 → 0.6.12 unconditionally
-txt.replace(/v0\.6\.13/g, 'v0.6.12');
-
-// ADR-0032 — preserve the plan-note filename ref while changing
-// version claims; negative-lookahead the filename pattern
-txt.replace(/v0\.6\.13(?!-admin-shell-composition-anchors)/g, 'v0.6.12');
-```
-
-The plan note `.brain/notes/v0.6.13-admin-shell-composition-anchors-*` file was NOT renamed — it's archaeological planning material; renaming would cascade to every reference in ADR-0032 + the audit note. The correction commit kept the original filename and treated it as a plan-history artifact rather than a current-state claim.
-
-Commit message named the problem + the fix + the precedent:
-
-```text
-fix(release): correct v0.6.13 version-skip → v0.6.12
-
-The preceding release commit e8490d96d ("release(*): v0.6.13 lockstep")
-bumped all 9 packages 0.6.11 → 0.6.13, skipping 0.6.12 entirely.
-0.6.12 was never tagged, never published — npm latest is 0.6.11. The
-next contiguous version is 0.6.12, not 0.6.13.
-
-Corrected 0.6.13 → 0.6.12 across 25 files: ...
-```
-
-Then the standard cycle resumed: tag v0.6.12 at the correction commit HEAD, F-N1, push, publish, GH releases, site deploy, ledger.
-
----
-
-## §The lesson
-
-1. **Re-baseline catches version-skip BEFORE you tag.** The user asked for v0.6.12; the operator checked package.json + tags + npm latest + git log; the mismatch surfaced in 3 commands.
-2. **Correction commit, not amend.** A NEW commit on top preserves the peer's commit (and its message + SHA) as archaeology. The audit-history ledger documents what happened. Future cycles can trace.
-3. **Don't rename filenames carrying historical context.** Plan notes with version-prefixed names are archaeological; their reference graph (ADRs, audit notes, ledgers) is brittle. Treat them as immutable once committed. Use the commit message + ledger to reconcile the version-label conflict.
-4. **Negative-lookahead regex protects filename references** from a blanket version replace. `/v0\.6\.13(?!-admin-shell-...)/g` is the pattern.
-
----
-
-## §Ledger fragment
-
-The v0.6.12 audit-history ledger captured this in a dedicated `version_skip_correction` block:
-
-```json
-"version_skip_correction": {
-  "issue": "Peer release commit e8490d96d ('release(*): v0.6.13 lockstep') bumped all 9 packages 0.6.11 → 0.6.13, skipping 0.6.12 entirely. 0.6.12 was never tagged or published (npm latest was 0.6.11). The commit's CHANGELOG bodies further framed the work as two separate releases ('v0.6.12 dogfooding sweep' + 'v0.6.13 cut') though it is a single commit.",
-  "root_cause": "Original multi-phase plan staged work across v0.6.12 / v0.6.13 / v0.7.0; phases collapsed into one commit but the version label landed on 0.6.13 instead of the contiguous-next 0.6.12.",
-  "fix": "Correction commit 2ee4a1f18 — 0.6.13 → 0.6.12 across 9 package.json + 9 CHANGELOG (headers/body/anchors) + 4 admin-shell CSS comment refs + ADR-0032 + FEEDBACK-05 + the v0.6.12 audit note + package-lock.json regen. The plan-note filename (v0.6.13-admin-shell-...) was intentionally left as archaeological planning material; authoritative records (CHANGELOG/ADR/package.json) are correct."
-}
-```
-
-The presence of this block in a ledger is the signal — `grep -l "version_skip_correction" .brain/audit-history/*.json` lists every cycle that needed this scenario applied.
-
----
-
-## §Cross-references
-
-- `../../references/recovery-paths.md` § Scenario 1 — the canonical resolution checklist
-- `../../references/multi-agent-baseline.md` § Re-baseline — the discipline that surfaces this scenario in the first 3 commands
-- `../../references/ledger-discipline.md` § What ELSE to capture per kind — the `version_skip_correction` block schema
-- Repo precedent: `b62992aa0 chore(forensic): v0.6.10 release-prep misattribution` — the prior cycle that established the forensic-correction-commit pattern.

package/skills/adia-ui-release/assets/case-studies/2026-05-21-author-from-scratch-v0.6.18.md

@@ -1,139 +0,0 @@
-# Case study — v0.6.18 `[Unreleased]` promotion + demo-shell fix
-
-**Cycle:** 2026-05-21 (v0.6.17 → v0.6.18) **Scenario:** `recovery-paths.md` § Scenario 4 (`[Unreleased]` extension on incomplete release commit) **Source ledger:** `.brain/audit-history/2026-05-21-release-v0.6.18.json` **Outcome:** Peer's early release commit failed a release-blocking gate; cycle extended to HEAD via `[Unreleased]` → `[0.6.18]` promotion.
-
----
-
-## §The shape
-
-User asked: _"prepare and initiate 0.6.18 release"_.
-
-Operator re-baselined and found 15 unpushed commits since the v0.6.17 ledger. Among them:
-
-- `f167b72bc release(*): v0.6.18 lockstep — loading state (FB-12 P2) + text-ui overlay attrs (FB-10)` — the peer's release commit, **cut early**.
-- 14 commits AFTER it, including:
-  - `8da3825b7 skill v2.11.0`
-  - `dfeb712d4 docs(admin-shell) sidebar gallery`
-  - `9207e801e fix(*): resolve outbox tickets FB-14/15/16/17/18`
-  - `d6d980072 fix(demo-shells): import skeleton-ui in stat + table demo shells` — ← **completes v0.6.18's own scope**
-  - `fec55d82d skill v2.12.0`
-  - `5c739a659 fix(check:skills)`
-  - (and more)
-
-One of the post-commits had a CHANGELOG fragment naming itself "post-v0.6.18": _"docs(tickets): update TRIAGE-2026-05-21 + file FB-12 followup post-v0.6.18"_. The peer's intent was clear: `f167b72bc` IS v0.6.18; everything after is for a future release, staged under `## [Unreleased]`.
-
----
-
-## §The diagnosis (the surprising part)
-
-Operator did a detached checkout to f167b72bc and ran the pre-flight gates AT THAT COMMIT:
-
-```text
-=== check:demo-shells (at f167b72bc) ===
-    demo:     packages/web-components/components/table/table.html
-    missing:  skeleton-ui
-    declared: check-ui, icon-ui, progress-ui, pagination-ui, skeleton-ui, badge-ui
-✗ FAIL
-```
-
-**`f167b72bc` failed `check:demo-shells`.** The cycle's own substantive feature (FB-12 `stat-ui loading` + `table-ui loading` shipped via `<skeleton-ui>`) was used in the stat/table demo `.html` shells, but those shells didn't import `<skeleton-ui>`. The demo pages would render `<skeleton-ui>` as `HTMLUnknownElement` — unstyled, unregistered.
-
-The fix existed: `d6d980072 fix(demo-shells): import skeleton-ui in stat + table demo shells` — but it landed **10 commits later**, entangled with FB-13/14/15/17 `[Unreleased]` work.
-
-Two choices:
-
-- **Option A**: Cherry-pick `d6d980072` onto `f167b72bc` to make the release commit shippable in its original scope. Off-mainline tag (the new commit isn't on `main`'s mainline). Messy archaeology.
-- **Option B**: Extend v0.6.18 to HEAD by promoting the `[Unreleased]` content into `[0.6.18]`. The release becomes larger but ships everything consistent.
-
-Operator chose **Option B**. Rationale: the peer had clearly intended to ship `f167b72bc` as v0.6.18 + had documented further work as `[Unreleased]` for the next cut — but the demo-shell fix is **part of v0.6.18's own scope** (it completes the feature the cut introduced). Extending v0.6.18 to absorb everything is the honest framing.
-
----
-
-## §The fix
-
-### 1. Verify HEAD passes all gates
-
-```bash
-git checkout main  # return from detached HEAD
-npm run check:demo-shells  # PASSES at HEAD
-```
-
-### 2. Promote `[Unreleased]` → `[0.6.18]` across affected CHANGELOGs
-
-The `[Unreleased]` blocks on `main` (post-`f167b72bc`) had:
-
-- `packages/web-components/CHANGELOG.md` — FB-14 (toggle-scheme `[data-scheme]`) + FB-15 (button-ui warn)
-- `packages/web-modules/CHANGELOG.md` — FB-17 (admin-sidebar resize-handle diagnostic) + sidebar-gallery docs
-
-The `[0.6.18]` block at line ~17 of each was a STUB ("Lockstep version bump only. No source changes in this package") — but the package DID change post-cut. The peer hadn't reconciled the stub.
-
-The merge:
-
-- web-components: delete the `## [Unreleased]` heading; FB-14 + FB-15 sections fall under `[0.6.18]` (with the existing FB-12 + FB-10 entries from the original cut).
-- web-modules: delete the `## [Unreleased]` heading AND the stub `## [0.6.18]` block; FB-17 + sidebar-gallery sections become the new `## [0.6.18]` block.
-- a2ui-corpus: had no `[Unreleased]` block but the catalog regenerated post-cut. Authored a fresh `## [0.6.18]` entry per `changelog-discipline.md` § Authoring.
-
-### 3. Commit + tag
-
-```bash
-git add packages/web-components/CHANGELOG.md \
-        packages/web-modules/CHANGELOG.md \
-        packages/a2ui/corpus/CHANGELOG.md
-
-git commit -m "$(cat <<'EOF'
-chore(release): promote [Unreleased] → [0.6.18] — v0.6.18 = HEAD
-
-The v0.6.18 release commit f167b72bc (loading state FB-12 + text-ui
-FB-10) cannot be tagged in isolation: it fails check:demo-shells —
-its own skeleton-ui demos (stat.html / table.html) don't import
-skeleton-ui. The fix landed 10 commits later in d6d980072,
-interleaved with unrelated [Unreleased] feedback work (FB-13/14/15/16/17),
-so the demo-shell fix cannot be cleanly cherry-picked onto f167b72bc.
-
-Resolution: v0.6.18 absorbs everything through HEAD. The peer parked
-post-f167b72bc work under ## [Unreleased] expecting the next release
-cut to promote it — this IS that cut. ...
-EOF
-)"
-```
-
-Then tag v0.6.18 at THIS new commit (the `[Unreleased]` merge), **NOT** at f167b72bc. Per the standard tag-at-HEAD invariant.
-
-```bash
-git tag v0.6.18
-# + 9 per-package tags
-```
-
-### 4. F-N1 + push + publish + GH releases + site + ledger
-
-Standard cycle from here. F-N1 was clean at 9/9 (the CHANGELOG promotion brought all the post-cut work under documented `[0.6.18]` entries).
-
-### 5. Document the boundary decision in the ledger
-
-```json
-"boundary_decision": {
-  "issue": "Early release commit f167b72bc failed check:demo-shells. Fix landed in d6d980072, entangled with [Unreleased] work that includes FB-13/14/15/17.",
-  "resolution": "v0.6.18 absorbs everything through HEAD. [Unreleased] CHANGELOG sections promoted to [0.6.18] across web-components + web-modules + a2ui-corpus. v0.6.18 tags land at the [Unreleased]-merge commit.",
-  "verified": "f167b72bc check:demo-shells FAIL confirmed via detached checkout; HEAD check:demo-shells PASS confirmed (124 shells)."
-}
-```
-
----
-
-## §The lesson
-
-1. **A release commit can fail its own scope.** When a new feature needs demo-shell updates and the cut happens before those updates land, the release commit is incomplete. Pre-flight the release-commit candidate, not just HEAD.
-2. **Detached checkout is the rigorous diagnostic tool.** `git checkout <release-commit-sha>` + `npm run check:demo-shells` tells you the truth — does the tag candidate ship a working demo?
-3. **Extending vs cherry-picking.** When the completing fix is ENTANGLED with unrelated `[Unreleased]` work (10 commits later, interleaved with feedback fixes), extension via `[Unreleased]` promotion is the clean path. Cherry-picking off-mainline produces messy archaeology.
-4. **The peer's `[Unreleased]` parking IS the next-release signal.** Keep-a-Changelog's `[Unreleased]` block exists precisely so the NEXT release cut can promote it. When the peer cut early and continued building, the operator's job is to read `[Unreleased]` as v0.X.Y intent.
-5. **The boundary-decision block in the ledger.** Every cycle that extends a release-commit's scope deserves a documented rationale. Future cycles reading `.brain/audit-history/` can trace what happened.
-
----
-
-## §Cross-references
-
-- `../../references/recovery-paths.md` § Scenario 4 — the canonical checklist
-- `../../references/gates-catalog.md` § Category 3 § `check:demo-shells` — the gate that triggered this scenario; failure is **HIGH severity**
-- `../../references/changelog-discipline.md` § Promotion — the heading-swap mechanic that merged `[Unreleased]` into `[0.6.18]`
-- `../../references/changelog-discipline.md` § Authoring — the fresh-block authoring path for a2ui-corpus
-- `../../references/ledger-discipline.md` — the `boundary_decision` block schema (extended in this case study)

package/skills/adia-ui-release/assets/case-studies/2026-05-21-feedback37-retraction-v0.6.21.md

@@ -1,124 +0,0 @@
-# Case study — FEEDBACK-37 retraction (v0.6.20 → v0.6.21)
-
-**Cycles:** 2026-05-21 (v0.6.19 → v0.6.20 → v0.6.21) **Scenario:** `recovery-paths.md` § Scenario 6 (concurrent peer mid-cycle) + `../../references/recovery-paths.md` § post-publish revert **Source ledgers:** `2026-05-21-release-v0.6.20.json`, `2026-05-21-release-v0.6.21.json` **Outcome:** Feature shipped in v0.6.20; retracted one cycle later in v0.6.21 after a peer-led re-diagnosis ratified by ADR-0033.
-
----
-
-## §The shape — v0.6.20 cycle
-
-User asked: _"prepare and initiate 0.6.20 release"_. The cycle was a substantial Mode 2 (author from scratch) with claims-ui-v5 feedback batch FB-34–39 already landed under `[Unreleased]`, plus a new `<admin-entity-item>` shell primitive.
-
-Among the FEEDBACK closures: **FEEDBACK-37** — _"admin-shell warns when `<admin-topbar>` / `<admin-statusbar>` is missing its slot."_ The fix added a `#checkSlotContracts()` method to `admin-shell.js` that emitted a one-shot `console.warn` when an `<admin-topbar>` or `<admin-statusbar>` element was placed inside `<admin-sidebar>` or `<admin-content>` without `slot="header"` / `slot="footer"`.
-
-The web-modules `[0.6.20]` CHANGELOG documented this as:
-
-> `### Added — admin-shell warns when <admin-topbar> / <admin-statusbar> is missing its slot (FEEDBACK-37)`
-
----
-
-## §The mid-cycle discovery
-
-While operator was staging the v0.6.20 release commit, `git status` showed an UNEXPECTED uncommitted change:
-
-```text
- M packages/web-modules/shell/admin-shell/admin-shell.js
-```
-
-Diffing it: a peer had **uncommitted-staged a REVERT** of the FEEDBACK-37 method — `#checkSlotContracts()` was being removed, `static #warnedSlots = new WeakSet()` was being removed, the call site in `connected()` was being removed.
-
-But the v0.6.20 CHANGELOG documented FEEDBACK-37 as **added**. The peer's uncommitted revert directly contradicted the release's own documentation.
-
-Operator applied `multi-agent-baseline.md` § Discipline 4 (stash workflow for strays):
-
-```bash
-git stash push packages/web-modules/shell/admin-shell/admin-shell.js \
-  .agents/skills/<companion-skill>/SKILL.md \
-  -m "v0.6.20-cycle: peer-in-flight FEEDBACK-37 revert in admin-shell.js + SKILL.md — excluded from release"
-```
-
-v0.6.20 shipped with FEEDBACK-37 PRESENT (matching the CHANGELOG), the stashed revert preserved for the peer.
-
----
-
-## §The post-publish discovery
-
-Right after v0.6.20 publishes settled, operator ran `git stash pop` to restore the peer's working state. The pop reported "kept the stash" — a conflict.
-
-Investigation:
-
-```bash
-git log d7d44a727..HEAD --oneline
-# 664cb3f55 fix(*): 0.6.20 follow-up — revert admin-shell slot warn + toast/input fixes
-```
-
-**The peer had committed the revert RIGHT AFTER v0.6.20 publishes settled.** The commit message named the intent: _"0.6.20 follow-up — revert admin-shell slot warn."_
-
-So FEEDBACK-37 shipped in v0.6.20 and the peer immediately reverted it for v0.6.21. The "follow-up" naming implied the peer had already diagnosed this as a misdiagnosis and wanted to retract.
-
-The stash became redundant — the peer committed the same content. Operator dropped the stash:
-
-```bash
-git stash drop stash@{0}
-```
-
-The v0.6.20 ledger named the situation in `notes`:
-
-> "PEER-IN-FLIGHT EXCLUDED: a concurrent peer had an uncommitted revert of the FEEDBACK-37 slot-contract diagnostic in admin-shell.js (removed #checkSlotContracts() + #warnedSlots). v0.6.20's CHANGELOG documents FEEDBACK-37 as ADDED, and the feature IS committed (d32e34b4f). The uncommitted revert directly contradicts the [0.6.20] CHANGELOG, so it was git-stashed and excluded — v0.6.20 ships the committed state (FEEDBACK-37 present). The revert + SKILL.md edit were restored to the working tree post-release for the peer. FLAGGED to operator: a peer may be reconsidering FEEDBACK-37; if the revert lands, v0.6.21 would remove what v0.6.20 adds."
-
----
-
-## §The v0.6.21 cycle — retraction
-
-User asked: _"prepare and initiate 0.6.21 release"_.
-
-The v0.6.21 cycle was a normal Mode 2 (author from scratch). The web-modules `[Unreleased]` block now had:
-
-> `### Fixed — admin-shell no longer emits a spurious slot-contract console.warn`
-
-Phrased as a **fix** (a spurious warn was removed), not a **removal** (the feature was rescinded). The peer's framing: the v0.6.20 diagnostic had been **misdiagnosed**, and emitted false positives on legitimate compositions where `<admin-topbar>` / `<admin-statusbar>` landed in the default body slot LEGITIMATELY (per the Light-DOM substrate's `slot=` decorative-not-directive semantics).
-
-The cycle also ratified the framing as **ADR-0033 "Light-DOM substrate"** — making explicit the stance that `slot=` is decorative metadata, not a projection directive; positioning is by CSS rules matching tag + ancestor + DOM order. This is the _zeroth question_ to ask when output looks wrong: "am I treating `slot=` as if it's directive when the substrate is Light-DOM?"
-
-v0.6.21 shipped the retraction + ADR-0033. The release notes carried a **heads-up paragraph** naming the round-trip:
-
-> **Heads-up:** v0.6.20 shipped a FEEDBACK-37 slot-contract `console.warn` that was found to misdiagnose legitimate compositions. v0.6.21 retracts it. If you're on v0.6.20 and saw the warn fire, you can ignore it — upgrade to v0.6.21.
-
----
-
-## §The lesson
-
-1. **A peer's uncommitted revert is a SIGNAL.** Diff it, classify per `multi-agent-baseline.md` § Discipline 2, decide. Don't silently ship; don't silently revert.
-2. **CHANGELOG-contradicting strays MUST be excluded.** v0.6.20's CHANGELOG documented FEEDBACK-37 as ADDED; shipping with the revert applied would have made the CHANGELOG dishonest.
-3. **One-version round-trips are recoverable.** A feature shipped in vN.M.X and retracted in vN.M.Y+1 isn't catastrophic — the retraction note explains it. The cost is a one-line "if you saw X, upgrade" in the v0.6.21 release notes.
-4. **Ratification via ADR.** When a retraction reveals a deeper framing issue (here, Light-DOM substrate mechanics), write an ADR. ADR-0033 is the durable artifact; the retracted feature becomes the prompt that surfaced the architectural decision.
-5. **Stash-then-restore preserves peer work.** The stash workflow meant zero data loss for the peer; the peer committed the same content shortly after; the stash became redundant.
-6. **The flagged-to-operator note in the v0.6.20 ledger correctly predicted v0.6.21.** Future cycles reading the ledger can trace "feature shipped + ledger flagged thrash risk + retracted next cycle" as a pattern.
-
----
-
-## §Ledger fragments
-
-### v0.6.20 ledger (the flag)
-
-```json
-"notes": [
-  "PEER-IN-FLIGHT EXCLUDED: a concurrent peer had an uncommitted revert of the FEEDBACK-37 slot-contract diagnostic in admin-shell.js. v0.6.20's CHANGELOG documents FEEDBACK-37 as ADDED, and the feature IS committed (d32e34b4f). The uncommitted revert directly contradicts the [0.6.20] CHANGELOG, so it was git-stashed and excluded — v0.6.20 ships the committed state (FEEDBACK-37 present). FLAGGED to operator: a peer may be reconsidering FEEDBACK-37; if the revert lands, v0.6.21 would remove what v0.6.20 adds."
-]
-```
-
-### v0.6.21 ledger (the retraction)
-
-```json
-"feedback_37_round_trip": "FEEDBACK-37 (admin-shell slot-contract diagnostic) shipped in v0.6.20 and is retracted in v0.6.21 — found to misdiagnose legitimate compositions. One-version round-trip. Post-mortem at journal §398; correction-loop discipline captured in a companion skill; Light-DOM substrate stance made explicit at ADR-0033."
-```
-
----
-
-## §Cross-references
-
-- `../../references/recovery-paths.md` § Scenario 6 — concurrent peer mid-cycle
-- `../../references/multi-agent-baseline.md` § Discipline 4 — stash workflow
-- `../../references/notes-authoring.md` § Cross-references — heads-up paragraph pattern in single-version notes
-- `../../references/ledger-discipline.md` § notes (the lesson log) — the PEER-IN-FLIGHT EXCLUDED phrasing
-- ADR-0033 — Light-DOM substrate
-- a companion consultant skill — the correction-loop discipline that generalizes the lesson (diagnose layer-of-origin before patching)

package/skills/adia-ui-release/assets/case-studies/2026-05-21-fn1-enrichment-pass-v0.6.19.md

@@ -1,125 +0,0 @@
-# Case study — F-N1 diff-coverage enrichment pass (v0.6.19)
-
-**Cycle:** 2026-05-21 (v0.6.18 → v0.6.19) **Scenario:** `recovery-paths.md` § F-N1 cosmetic warns → enrich path keywords **Source ledger:** `.brain/audit-history/2026-05-21-release-v0.6.19.json` **Outcome:** 2 cosmetic warns converted to 9/9 clean via 2-line CHANGELOG wording tweaks + commit amend + re-tag.
-
----
-
-## §The shape
-
-Operator authored v0.6.19 from scratch (claims-ui-v4 FB-22…33 batch). After tagging, F-N1 (`check:release --all-pending`) reported 2 warns:
-
-```text
-⚠ [warn] diff 'packages/a2ui/corpus/chunks/' touched between
-  a2ui-corpus-v0.6.18 → a2ui-corpus-v0.6.19 but CHANGELOG [0.6.19]
-  doesn't mention 'chunks'
-
-⚠ [warn] diff 'packages/web-components/core/' touched between
-  web-components-v0.6.18 → web-components-v0.6.19 but CHANGELOG [0.6.19]
-  doesn't mention 'core'
-```
-
-Both changes WERE documented:
-
-- a2ui-corpus entry described "~235 chunk JSON files re-harvested" + "Companion `chunk-reconcile` triage" — but neither literally used the keyword `chunks` (path token).
-- web-components entry described "`UIElement.ensure()` part-wipe invariant" — described `UIElement` extensively but didn't say `core` (path token).
-
-F-N1's diff-coverage regex matches **literal path tokens**. The entries were content-complete but missed the regex's keyword.
-
----
-
-## §The diagnosis
-
-Cosmetic vs real failure decision (per `changelog-discipline.md` § F-N1 enrichment):
-
-> Read the CHANGELOG entry: does any bullet describe the touched files (by component name, by what the change does)? If yes → cosmetic → enrich. If no → real → author.
-
-Both bullets described the touched code — `~235 chunk JSON files` and `UIElement.ensure() part-wipe invariant`. Cosmetic warns.
-
----
-
-## §The fix
-
-Two minimal wording tweaks to inject the path keywords naturally:
-
-### a2ui-corpus entry
-
-Before:
-
-```text
-Freshened the stale chunk corpus: ~235 chunk JSON files re-harvested/reconciled
-```
-
-After:
-
-```text
-Freshened the stale corpus chunks: ~235 JSON files under `chunks/` re-harvested/reconciled
-```
-
-Word reorder ("chunk corpus" → "corpus chunks") + add the path reference `under \`chunks/\``. Both keywords now present; reads naturally; conveys the same information.
-
-### web-components entry (FEEDBACK-31 section)
-
-Before:
-
-```text
-- `ensure()` marks stamped structural parts with `_uiPart = true` and its
-  doc comment states the invariant: ...
-```
-
-After:
-
-```text
-- `UIElement.ensure()` (`core/element.js`) marks stamped structural parts
-  with `_uiPart = true` and its doc comment states the invariant: ...
-```
-
-Add the file path inline as a parenthetical. Now mentions `core/`; also makes the entry more accurate (names the actual file).
-
-### Amend + re-tag + re-run
-
-```bash
-git add packages/a2ui/corpus/CHANGELOG.md packages/web-components/CHANGELOG.md
-git commit --amend --no-edit
-
-# Delete + re-create 10 tags (SHA moved)
-git tag -d v0.6.19 web-components-v0.6.19 web-modules-v0.6.19 ... # all 10
-git tag v0.6.19
-for pkg in web-components web-modules llm a2ui-runtime a2ui-compose \
-           a2ui-corpus a2ui-mcp a2ui-retrieval a2ui-validator; do
-  git tag "$pkg-v0.6.19"
-done
-
-# Re-run
-node scripts/release/check-release.mjs --all-pending
-# → 9/9 per-package ✓ clean (umbrella error expected)
-```
-
----
-
-## §The lesson
-
-1. **F-N1 cosmetic warns are common and trivially fixed.** Two wording tweaks resolved both. Total work: ~5 minutes.
-2. **Read the warn for the keyword.** The message says exactly what string is missing (`'chunks'`, `'core'`). Add that string to a natural place in the entry.
-3. **Don't padding-pad.** Forcing a keyword into the entry as a sidecar parenthetical reads worse than weaving it in. The "components/table/table.yaml" path-reference style is the standard — it conveys file path AND makes the entry more accurate.
-4. **Amend, don't add a new commit.** The CHANGELOG enrichment IS part of the release commit conceptually. `git commit --amend --no-edit` keeps the release commit clean. The tag SHA moves; just re-tag.
-5. **Bonus — the v0.6.21 cycle adopted this discipline at authoring time.** Peer commit `d8cbbd30c` was explicitly named _"uses full path so F-N1 gate matches"_ — i.e. the peer learned the pattern and started authoring entries with full file paths from the start. By v0.6.21 the F-N1 cycle was 9/9 clean on first pass.
-
----
-
-## §Ledger fragment
-
-```json
-"notes": [
-  "F-N1 flagged 2 cosmetic diff-coverage warns on the first tag pass (a2ui-corpus chunks/ + web-components core/ touched but CHANGELOG lacked the literal path keyword). Both fixed by minor wording tweaks; release commit amended; re-tagged at 8d48845ad; F-N1 re-run 9/9 clean."
-]
-```
-
-`grep -l "diff-coverage" .brain/audit-history/*.json` finds cycles that needed this enrichment pass.
-
----
-
-## §Cross-references
-
-- `../../references/changelog-discipline.md` § F-N1 diff-coverage enrichment — the canonical procedure
-- `../../references/gates-catalog.md` § Category 1 § F-N1 — the gate definition + cosmetic-vs-real failure decision tree
-- Repo precedent: peer commit `d8cbbd30c docs(web-components/CHANGELOG): §403 table-ui entry uses full path so F-N1 gate matches` — the peer adopting the discipline at authoring time

package/skills/adia-ui-release/assets/case-studies/2026-05-21-stale-test-detection-v0.6.20.md

@@ -1,142 +0,0 @@
-# Case study — stale test detection (v0.6.20)
-
-**Cycle:** 2026-05-21 (v0.6.19 → v0.6.20) **Scenario:** `recovery-paths.md` § Scenario 5 (stale test detection) **Source ledger:** `.brain/audit-history/2026-05-21-release-v0.6.20.json` **Outcome:** A v0.6.17 regression guard failed against v0.6.20's deliberate CSS change; assertion updated to match the new contract + a guard for the new behavior added.
-
----
-
-## §The shape
-
-Operator ran `npm run test:unit` at HEAD as part of v0.6.20 pre-flight. Result: **1 fail / 1078 pass / 1079 total**.
-
-The failing test:
-
-```text
-FAIL  packages/web-modules/shell/admin-shell/admin-shell.test.js
-  > admin-shell.collapsed.css — vanilla HTML fallback (v0.6.17)
-  > contains the vanilla-HTML fallback block
-
-AssertionError: expected '/* ══...' to match /\[slot="heading"\]\s*\{[\s\S]*?display:\s*none/
-```
-
-The test was a **v0.6.17 regression guard**: when v0.6.17 added the forgiving-fallback block to `admin-shell.collapsed.css` (clipping vanilla-HTML overflow when the sidebar collapses), the test was added to verify the block stays present. It asserted the rule existed via:
-
-```js
-expect(collapsedCSS).toMatch(/\[slot="heading"\]\s*\{[\s\S]*?display:\s*none/);
-```
-
-— i.e. `[slot="heading"]` IMMEDIATELY followed by `{ ... display: none`.
-
----
-
-## §The diagnosis
-
-The v0.6.20 cycle's `[Unreleased]` block included:
-
-> `### Fixed — collapsed sidebar [slot="heading"] hide no longer wipes composed wrappers (FEEDBACK-38 addendum)`
-
-— a deliberate change to the CSS the test was asserting against.
-
-The OLD rule (v0.6.17):
-
-```css
-[slot="heading"] {
-  display: none;
-}
-```
-
-The NEW rule (v0.6.20 FB-38 addendum):
-
-```css
-:is(span, p, div, h1, h2, h3, h4, h5, h6)[slot="heading"],
-[slot="heading"]:not(:has(> [slot])) {
-  display: none;
-}
-```
-
-The new rule **narrows** the hide: plain-text headings (`<span slot="heading">`) are still hidden, but composed wrappers carrying their own slot contract (`<admin-entity-item slot="heading">`) survive collapse via the `:not(:has(> [slot]))` guard.
-
-The test's regex `\[slot="heading"\]\s*\{` requires `[slot="heading"]` to be immediately followed by `{`. In the new CSS, `[slot="heading"]` is followed by `:not(:has(> [slot]))` before `{`. **The test wasn't updated to match the deliberate change.**
-
-This is a **stale test**, not a regression. The peer shipped the CSS change but didn't update the regression guard.
-
-Decision per `recovery-paths.md` § Scenario 5:
-
-> 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.
->
-> Read the actual production code. If it matches the CHANGELOG entry's description → the test is stale.
-
-Confirmed: CHANGELOG describes the FB-38 addendum behavior; the CSS matches the CHANGELOG; the test is stale.
-
----
-
-## §The fix
-
-Two assertion changes in `admin-shell.test.js`:
-
-### 1. Update the existing assertion to the new shape
-
-Before:
-
-```js
-expect(collapsedCSS).toMatch(/\[slot="heading"\]\s*\{[\s\S]*?display:\s*none/);
-```
-
-After:
-
-```js
-// v0.6.20 (FEEDBACK-38 addendum): the heading-hide rule narrowed from a
-// blanket `[slot="heading"]` to plain-text headings + headings without
-// slotted children, so composed wrappers (<admin-entity-item slot="heading">)
-// survive collapse. The rule still resolves to `display: none`.
-expect(collapsedCSS).toMatch(/\[slot="heading"\][^{]*\{\s*display:\s*none/);
-```
-
-Change: `\s*\{` (whitespace then `{`) → `[^{]*\{` (any non-brace chars then `{`). This matches both the old blanket shape AND the new narrowed shape.
-
-### 2. Add a guard assertion for the FB-38-addendum contract
-
-```js
-expect(collapsedCSS).toMatch(/\[slot="heading"\]:not\(:has\(>\s*\[slot\]\)\)/);
-```
-
-This asserts the `:not(:has(> [slot]))` composed-wrapper guard is present. If a future cycle accidentally reverts the FB-38 addendum, this assertion fires.
-
-### Run the suite
-
-```bash
-npx vitest run packages/web-modules/shell/admin-shell/admin-shell.test.js
-# Test Files  1 passed (1)
-# Tests  6 passed (6)
-```
-
-Then ship — `admin-shell.test.js` is part of v0.6.20's release commit allowlist (it's a test update that completes the FB-38-addendum work).
-
----
-
-## §The lesson
-
-1. **Stale test ≠ regression.** When a test fails against a deliberate CHANGELOG-documented change, the test is stale. Don't "fix the regression" — update the test.
-2. **The diagnostic triangle: assertion + CHANGELOG + source code.** Read all three. The two that agree are correct; the one that disagrees is stale.
-3. **Update + add — don't just patch.** When the production behavior changes, the test should pin the NEW behavior. Add a guard assertion for the new contract so future regressions fire here.
-4. **Inline comment with the cycle ref.** Add a comment in the test naming the cycle (v0.6.20) and the closed feedback (FEEDBACK-38 addendum). Future operators reading the test understand why the assertion has the new shape.
-5. **The test update belongs in the release commit.** It's part of the work that ships the CSS change. Stage it explicitly in the release-commit allowlist.
-
----
-
-## §Ledger fragment
-
-```json
-"notes": [
-  "STALE TEST FIXED: admin-shell.test.js 'contains the vanilla-HTML fallback block' (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 that rule (: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. Deploy session updated the assertion to match the new shape + added a guard assertion for the :not(:has(> [slot])) clause. Not a regression — a stale test."
-]
-```
-
-`grep -l "STALE TEST" .brain/audit-history/*.json` finds cycles that required this scenario.
-
----
-
-## §Cross-references
-
-- `../../references/recovery-paths.md` § Scenario 5 — the canonical diagnosis checklist
-- `../../references/gates-catalog.md` § Category 8 § `test:unit` — the gate definition + the stale-test-vs-regression triage
-- `../../references/cycle-happy-path.md` § Step 5 — staging the test update alongside the release commit