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

package/skills/adia-ui-release/references/multi-agent-baseline.md

@@ -1,207 +0,0 @@
-# `multi-agent-baseline.md` — peer-in-flight classification + stash discipline
-
-> Loaded by every mode when the working tree shows files you didn't author. Companion to `AGENTS.md` § "Multi-agent baseline assumption" — release-side specialization.
-
-The AdiaUI monorepo is **always** worked on by multiple agents concurrently. At any moment a peer agent may be: writing source, drafting tickets, updating skills, regenerating corpus chunks, fixing demo shells, or running an unrelated cycle. Your context is stale at the start of every turn.
-
-Release work is unusually sensitive to peer activity because:
-
-- A release commit's CHANGELOG makes claims (`### Added — X`); peer files in the working tree may **contradict** those claims (the classic v0.6.20 case: peer revert of FEEDBACK-37 while the v0.6.20 CHANGELOG documented FEEDBACK-37 as added).
-- A release tarball is built from the tag's tree; peer-in-flight uncommitted files don't ship — but the site build (working-tree driven) DOES include them. This split is silent and easy to miss.
-- A `git add -A` on a peer-dirty tree sweeps in peer work without consent. The release commit then makes claims it doesn't authorize.
-
-This reference encodes the four disciplines that prevent these defects.
-
----
-
-## §Discipline 1 — Re-baseline at every turn
-
-Non-negotiable. The first **four** commands of every release-cycle turn:
-
-```bash
-git -C $REPO branch --show-current     # MUST equal main before cutting
-git -C $REPO status --short
-git -C $REPO log --oneline -8
-git -C $REPO fetch && git -C $REPO log HEAD..origin/main --oneline
-```
-
-Then read the output BEFORE running anything mutating:
-
-- `branch --show-current` shows the checked-out branch. **It must be `main`.** Peers in this shared clone sometimes work on local feature branches (`fix/*`, `feat/*`) — the AGENTS.md session snapshot saying "Current branch: main" reflects the _prior_ session, not now. Cutting on a feature branch means `git push origin main` pushes the stale `main` ref (not your release commit) while the tags point at the feature tip → tags ahead of main. See the §Wrong-branch recovery below.
-- `status` shows working-tree changes. Every modified or untracked file is a classification decision.
-- `log -8` shows recent commits. Peer commits since your last turn? New work staged for the release? An unexpected revert?
-- `fetch && log HEAD..origin/main` shows remote drift. Did someone else push?
-
-> **§Wrong-branch recovery (v0.7.4 incident, 2026-06-02).** Cut the release on a peer's local-only `fix/font-family-floor-and-css-rollups` instead of main; caught at push (origin/main landed at a mid-window commit, tags pointed at the feature tip). Recovery was clean **because publish is `workflow_dispatch`, not tag-triggered** — npm stayed at the prior version through the whole tangle. If the feature tip's parent is an ancestor of the old main (it was: ff-able), recover with `git branch -f main <release-sha>` → `git checkout main` (no churn since main now == HEAD) → `git push origin main` to fast-forward origin/main to the release commit. Verify `origin/main == vX.Y.Z tag == HEAD` BEFORE dispatching publish. Moving tags while local is free (`tag-lockstep --delete`); moving them after a publish is not.
-
-If anything is unexpected, **diff before deciding**:
-
-```bash
-git -C $REPO diff <path>         # working-tree changes
-git -C $REPO show <sha> --stat   # peer commits
-```
-
-Never proceed past surprising state without classifying it.
-
----
-
-## §Discipline 2 — Classification taxonomy
-
-Every modified or untracked file falls into one of these buckets:
-
-| Bucket | Definition | Action |
-| --- | --- | --- |
-| **Mine** | You authored this in the current turn | Stage explicitly |
-| **Peer-release-relevant** | Peer authored, part of THIS release's scope (the peer's release-prep work — Variant A) | Stage explicitly |
-| **Peer-in-flight, release-relevant, undocumented, contradicts CHANGELOG** | Peer authored, would change the release's behavior but has no CHANGELOG entry and may contradict an existing one | **Stash** — exclude from release; flag to operator |
-| **Peer-in-flight, future-release scope** | Peer's working-tree progress destined for a later cut (e.g. `[Unreleased]` block additions, demo-page updates not yet documented) | Leave uncommitted — not yours to commit |
-| **Ticket-lane / skill / journal** | `.agents/team/tickets/**`, `.agents/skills/**`, `docs/journal/**` peer work | Leave uncommitted — ticket / skill / docs lane |
-| **Generated / regenerable** | `package-lock.json` after a bump, sidecar `.a2ui.json`, `chunk-embeddings.json` after regen | Stage iff you ran the generator this turn |
-| **Unknown** | Diff doesn't tell you intent | Ask the operator OR check the most recent commit message for clues OR check `.brain/notes/` for a peer prep note |
-
-The decision is **per-file**, not per-directory. A peer might have modified `admin-shell.js` (release-relevant) AND `SKILL.md` (skill-lane) in the same turn — they get different verdicts.
-
----
-
-## §Discipline 3 — Explicit allowlist staging
-
-**Never** `git add -A` or `git add .` on a peer-dirty tree. The staging area is opaque without inspection; a peer may have left files staged from a prior partial workflow.
-
-The defensive pattern:
-
-```bash
-# 1. Reset the staging area defensively.
-git -C $REPO reset HEAD >/dev/null 2>&1
-
-# 2. Stage the explicit allowlist by name.
-git -C $REPO add \
-  package-lock.json \
-  packages/web-components/package.json \
-  packages/web-components/CHANGELOG.md \
-  packages/web-modules/package.json \
-  packages/web-modules/CHANGELOG.md \
-  packages/llm/package.json \
-  packages/llm/CHANGELOG.md \
-  packages/a2ui/compose/package.json \
-  packages/a2ui/compose/CHANGELOG.md \
-  packages/a2ui/corpus/package.json \
-  packages/a2ui/corpus/CHANGELOG.md \
-  packages/a2ui/mcp/package.json \
-  packages/a2ui/mcp/CHANGELOG.md \
-  packages/a2ui/retrieval/package.json \
-  packages/a2ui/retrieval/CHANGELOG.md \
-  packages/a2ui/runtime/package.json \
-  packages/a2ui/runtime/CHANGELOG.md \
-  packages/a2ui/validator/package.json \
-  packages/a2ui/validator/CHANGELOG.md
-
-# 3. Verify staged count matches the allowlist.
-git -C $REPO diff --cached --stat | tail -3
-# Expected: "19 files changed" for a pure-stub release; more if you
-# also staged source files (test updates, etc.)
-
-# 4. Confirm peer-in-flight files are NOT in the staged set.
-git -C $REPO diff --cached --name-only | sort
-# Eyeball — no surprises.
-```
-
-The memory `feedback_git_commit_targeted` records this rule as a "4th incident" — peer renames absorbed silently 4 times before the `git reset HEAD` defensive prefix became standard.
-
----
-
-## §Discipline 4 — Stash workflow for strays
-
-A stray = a peer-in-flight file that is:
-
-1. Uncommitted,
-2. Undocumented (no CHANGELOG entry covers it, no commit message explains it),
-3. Would change behavior visible to consumers, AND
-4. Contradicts an existing release-relevant artifact.
-
-The canonical example: `admin-shell.tokens.css` `--page-content-header-bg` changed from `--a-canvas-1` to `--a-canvas-0` uncommitted, with the inline comment still describing `canvas-1`. Sat across v0.6.17/0.6.18/0.6.19 cycles. Resolved when the operator confirmed "keep canvas-0" in the v0.6.19→v0.6.20 boundary.
-
-The stash workflow:
-
-```bash
-# 1. Stash the stray file(s) by name. Include a clear message so the
-#    next operator (or you next turn) understands why.
-git -C $REPO stash push <path1> <path2> \
-  -m "vX.Y.Z-cycle: <stray reason> — parked during release"
-
-# 2. Verify the working tree is sane.
-git -C $REPO status --short
-# Stashed files no longer appear as modified.
-
-# 3. Do the full release (Steps 3–10 of cycle-happy-path.md).
-
-# 4. Restore the stash AFTER the cycle ships.
-git -C $REPO stash pop
-# If "Dropped stash" prints, it applied cleanly.
-# If "kept the stash" prints, there's a conflict — the working tree
-# moved while you were releasing. Investigate before dropping.
-```
-
-**Always stash, never revert** unless the operator explicitly says "discard." Revert (`git checkout <file>`) destroys peer work; stash preserves it.
-
-**Note the stash in the audit-history ledger** so the next operator can see what was excluded and why.
-
-The 4 case studies in `assets/case-studies/` covering this discipline:
-
-- `2026-05-21-stale-test-detection-v0.6.20.md` — peer changed CSS, didn't update test; deploy session updated the test (NOT stashed — fixed forward because the test was legitimately stale).
-- `2026-05-21-feedback37-retraction-v0.6.21.md` — peer staged a revert of FEEDBACK-37 mid-cycle; stashed (would contradict the v0.6.20 CHANGELOG); the peer committed the revert post-publish for v0.6.21.
-- `2026-05-20-version-skip-correction-v0.6.12.md` — peer mislabeled the cut v0.6.13; corrected 25 files across the release commit.
-- (Phase 3) `2026-05-21-stash-pop-conflict-v0.6.20.md` — concurrent peer activity caused stash pop to keep-the-stash. Resolution: drop if the working tree has caught up (committed the same content); preserve if not. Never blind drop.
-
----
-
-## §Pre-cut state classification flowchart
-
-When you re-baseline at Step 1 and find a non-clean working tree, walk this in order. The output is "what mode" + "what to stash."
-
-```text
-Is there an unpushed release commit (`release(*): vX.Y.Z`)?
-├── Yes, exactly one → Mode 3 (Deploy handoff) — peer pre-cut
-│   └── Are there commits AFTER it?
-│       ├── Yes, with CHANGELOG additions to [Unreleased] → §Boundary check
-│       │   (see recovery-paths.md § [Unreleased] promotion, Phase 2 —
-│       │    the v0.6.18 case: peer release commit fails check:demo-shells
-│       │    because the demo-shell fix landed entangled with future work)
-│       └── No → Mode 3 happy path; tag at HEAD
-├── Yes, multiple → Mode 4 (Batch push)
-│   (see recovery-paths.md § batch-push, Phase 2 — the v0.6.14+v0.6.15
-│    case: publish in version order for npm latest)
-└── No → Mode 2 (Author from scratch); promote [Unreleased] → [vX.Y.Z]
-
-Is the working tree clean?
-├── Yes → proceed with the determined mode.
-└── No → classify per the §Discipline 2 taxonomy.
-    For every file: Mine? Peer-release-relevant? Stray? Ticket-lane?
-    Stash strays, leave ticket-lane alone, stage release-relevant.
-```
-
----
-
-## §The audit-history ledger contract
-
-Every cycle's ledger (Step 11 of `cycle-happy-path.md`) includes a `notes` array. Entries about peer-in-flight handling go there. Standard phrasings:
-
-```json
-"notes": [
-  "STRAY UNCOMMITTED CHANGE EXCLUDED: <file> — <one-line summary>. git-stashed during the release; restored to the working tree after. Flagged to operator.",
-  "PEER-IN-FLIGHT EXCLUDED: <file> — <one-line summary>. v0.X.Y ships the committed state, NOT the peer's uncommitted change. The revert was restored post-release.",
-  "Peer cycle activity: skill v2.X.Y / journal §NNN / ticket-lane grooming rode along on main inside the unpushed range — already committed by peers; not npm release artifacts.",
-  "Concurrent peer modified <file> mid-cycle; was committed by the peer in <sha> as `<message>`. v0.X.Y absorbed / excluded per <reason>."
-]
-```
-
-The ledger is the long-term memory of the peer-classification decision. Future cycles read past ledgers (Mode 8 — Phase 3 Investigation).
-
----
-
-## §When this reference is "done v1"
-
-- Every modified file in a release cycle classifies cleanly into one bucket from §Discipline 2 (zero "unknown" verdicts).
-- Every stash command in the release uses the `vX.Y.Z-cycle:` prefix
-  - a meaningful reason.
-- Every audit-history ledger has at least one `notes` entry per excluded / stashed / peer-in-flight file.
-- The §Pre-cut state classification flowchart correctly routes the next 3 cycles without operator override.

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.