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

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

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

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

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

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.