@adia-ai/adia-ui-forge 0.8.58 → 0.8.59

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -154,7 +154,13 @@ for any constant or decision lives in git and PR descriptions
 7. **Registry ↔ catalog parity.** A component in the runtime registry but
    missing from catalog schemas silently drops from generated compositions —
    `npm run check:registry-catalog-coherence` guards it; run it after catalog
-   changes.
+   changes. `packages/gen-ui/a2ui/registry.js` is Class R (ADR-0069,
+   gh#3055): never hand-edit it — a new component enters through its yaml
+   `component:`/`tag:` fields, an alias or native-element mapping through
+   `packages/gen-ui/a2ui/registry.exceptions.json`, then
+   `node scripts/build/a2ui-registry.mjs` (derived-resync regenerates it on
+   main; `check:a2ui-registry` is the advisory freshness gate,
+   `check:a2ui-registry:validate` the blocking validity gate).
 8. **Multi-turn emits A2UI `updateComponents` messages, not new compositions.**
    The chunk-refiner mutates the binding plan via four ops (`rebindSlot` /
    `appendToSlot` / `removeFromSlot` / `replacePage`); state chains via

package/skills/component-md-authoring/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   component's states, composed children, aria behavior, or error/empty/
   loading handling changes and it already has (or should grow) a
   `component.md`, or when asked to "add component.md for X" / "write the
-  screen-reader spec for X" / "why did check:component-md-fresh fail". NOT
+  screen-reader spec for X" / "why is check:component-md-fresh warning". NOT
   the yaml prop/slot/event/token contract itself (primitive-authoring owns
   that — this skill only owns the two authored yaml fields,
   `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui
@@ -39,14 +39,16 @@ regenerated from them. This is deliberate, not incidental:
   gaps — screen-reader and behavioral judgment — get the SAME treatment:
   authored once, in yaml, transcluded everywhere else (component.md today;
   gen-ui corpus derivation once a2ui-maintenance wires it in).
-- **The freshness gate is PR-blocking, not staleness-only.** Because the
-  authored content lives in a yaml field, `component.md` is 100%
-  mechanically regenerable — `check:component-md-fresh` can do a real byte-
-  diff, the same shape as `check:reference-docs-fresh`, except PR-blocking
-  (operator ruling 2026-08-31) rather than advisory-only. A hand-edit
-  directly in `component.md` will be silently clobbered by the next
-  `npm run docs:component-md` and will fail the gate as "not fresh" — this
-  is the guard rail, not a bug.
+- **`component.md` is Class R, derived on main, not authored in the PR
+  (gh#3172, ADR-0069).** Because the authored content lives in a yaml
+  field, `component.md` is 100% mechanically regenerable — a PR commits
+  only the `screenReader`/`behavioral` yaml edit; `check:component-md-fresh`
+  runs advisory-only inside `check:pr-ready` (WARN, never fails the run)
+  and the `push: main` `derived-resync` job regenerates `component.md`
+  itself once the PR merges. A hand-edit directly in `component.md` will
+  still be silently clobbered by the next `npm run docs:component-md` or
+  by `derived-resync` on main — that's the guard rail, not a bug, even
+  though nothing blocks the PR on it.
 
 ## Authoring a component's two sections
 
@@ -79,7 +81,7 @@ regenerated from them. This is deliberate, not incidental:
    ```bash
    node scripts/build/components.mjs --validate   # schema-valid yaml
    npm run docs:component-md                      # regenerate component.md
-   npm run check:component-md-fresh                # PR-blocking gate
+   npm run check:component-md-fresh                # advisory gate (check:pr-ready); derived-resync owns main
    ```
 
 6. If this is the component's FIRST component.md (yaml previously had
@@ -110,7 +112,9 @@ defeats the point of a rollout plan).
 - `scripts/schemas/component.yaml.schema.json` — `intent`/`screenReader`/
   `behavioral` field definitions (all optional; a component with a `.yaml`
   but neither authored field simply has no `component.md` yet).
-- `scripts/verify/check-component-md-fresh.mjs` — the PR-blocking gate:
-  byte-freshness (component.md matches a fresh render) AND same-PR
-  coverage (a component.md-bearing component's source/yaml change must
-  touch component.md in the same diff).
+- `scripts/verify/check-component-md-fresh.mjs` — the freshness gate:
+  byte-freshness (component.md matches a fresh render). Advisory-only in
+  `check:pr-ready` (gh#3172, ADR-0069) — a PR commits the yaml edit alone
+  and `derived-resync` regenerates `component.md` on `push: main`; the
+  same-PR coverage check this gate used to run was removed outright
+  (LLD-0020 §1c), not demoted.

package/skills/demo-audit/SKILL.md

@@ -2,8 +2,8 @@
 name: demo-audit
 description: >-
   Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe,
-  app-shell QA, attr-quote typos, native-primitive leak, admin-shell
-  composition, card anatomy, plus an aggregated token/contrast/lifecycle
+  app-shell QA, attr-quote typos, native-primitive leak, shell (admin/chat/
+  editor) composition, card anatomy, plus an aggregated token/contrast/lifecycle
   drift battery (`npm run dogfood:status`). Use for "run a dogfood sweep",
   "find broken demos", "audit native primitive leaks". NOT for gen-UI
   gallery scoring (gen-ui-review) or authoring primitives (primitive-authoring).
@@ -33,7 +33,7 @@ below — load it before running or triaging.
 | 2 | App-shell QA — after `apps/` structural sweeps; before a release | [app-shell-pitfalls](references/app-shell-pitfalls.md) |
 | 3 | HTML attr-quote typo sweep — nested `"` broke an attribute boundary | [html-attr-sweep](references/html-attr-sweep.md) |
 | 4 | Native-primitive leak — `<button>` where `<button-ui>` exists | [native-leak-annotations](references/native-leak-annotations.md) |
-| 5 | Admin-shell composition — incomplete `<admin-shell>` anatomy | [admin-shell-anatomy](references/admin-shell-anatomy.md) |
+| 5 | Shell composition — incomplete `<admin-shell>` / `<chat-shell>` / `<editor-shell>` anatomy | [admin-shell-anatomy](references/admin-shell-anatomy.md), [chat-shell-anatomy](references/chat-shell-anatomy.md), [editor-shell-anatomy](references/editor-shell-anatomy.md) |
 | 6 | Card structure + anatomy docs coverage | [card-anatomy-sweep](references/card-anatomy-sweep.md) |
 | 7 | Token/contrast/lifecycle/yaml drift battery — independent of modes 1–6 | [mode7-status-battery](references/mode7-status-battery.md) |
 

package/skills/demo-audit/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Demo Audit"
-  short_description: "Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, admin-shell composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`)."
+  short_description: "Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, shell (admin/chat/ editor) composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`)."

package/skills/demo-audit/references/app-shell-pitfalls.md

@@ -4,7 +4,10 @@ Script: `node scripts/dev/audit-app-shells.mjs` (repo-local). Walks every
 `apps/<name>/…/<page>.html` shell headlessly and checks console errors,
 custom-element registration, collapsed heights, icon-ui presence, demo-root
 flex, and network 4xx/5xx. Flags: `--only=NAME` · `--fail-fast` ·
-`--compare-prod` (diff registered tags against the prod deploy).
+`--compare-prod` (diff registered tags against the prod deploy) ·
+`--playgrounds` (gh#3197 — also sweeps `playgrounds/<name>/app/<name>.html`,
+same shell shape; opt-in because that root carries other pre-existing,
+unaudited findings — combine with `--only=NAME` to scope to one playground).
 
 Prerequisites: `npm run dev` running (vite `:5173`); `npm run proxy` only when
 probing chat / gen-ui pages. If vite is mid dep-reoptimization the first sweep
@@ -42,6 +45,8 @@ with no console error, regardless of real content height.
 | `button-ui` (with `icon=`) | `icon-ui` |
 | `badge-ui` (with `icon=`) | `icon-ui` |
 | `menu-item-ui` | `icon-ui`, `text-ui` |
+| `admin-roster-ui` | `upload-ui`, `menu-item-ui` |
+| `table-toolbar-ui` | `search-ui`, `select-ui`, `menu-ui`, `menu-item-ui` |
 
 ## Registration diagnosis rules
 

package/skills/demo-audit/references/chat-shell-anatomy.md

@@ -0,0 +1,98 @@
+# Mode 5b — Chat-shell composition: the canonical parts
+
+Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
+`audit:shell-composition{,:strict,:all}`. Static AST walk over
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
+no browser needed; pre-commit fast. Shares one script and one output
+contract with the `<admin-shell>` census
+([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own `CHAT_PARTS`
+array is the mechanical census; this file is the human review standard.
+Canonical source: `packages/web-modules/chat/chat-shell/chat-shell.yaml`
+(the behavioral contract) and `playgrounds/chat/app/chat.contents.html`
+(the canonical rendered reference, cited by `apps/genui/PATTERNS.md`'s
+chrome-decision table as chat-shell's canonical demo).
+
+`gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
+(gen-ui, factory-chat) is a real `<chat-shell>` consumer that a
+`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+blind spot.
+
+## The canonical parts
+
+1. `<chat-shell provider="…" model="…" proxy-url="…">` outer.
+2. `<chat-thread>` direct child — the message scroll surface. Required:
+   without it there is nowhere for the host's rendering pipeline to append
+   messages.
+3. `<chat-thread> > <chat-empty>` as (typically first) child — the
+   empty-state placeholder shown via the `[empty]` reflected attribute
+   before any message exists.
+4. `<chat-composer>` direct child — the input region.
+5. `<chat-composer> > <chat-input-ui>` (or `<input-ui>`) inner child — the
+   actual input; a composer with no primitive input inside has nothing to
+   submit.
+6. `<chat-header>` direct child — optional top chrome bar (name, status,
+   actions). When present, expected to carry `[slot="name"]` and
+   `[slot="status"]` (typically a `<chat-status>`) — a header with neither
+   is bare chrome with no identifying content.
+7. `<chat-sidebar slot="leading"|"trailing">` — optional conversation-history
+   or inspector rail.
+8. No generic layout primitive (`<col-ui>`, `<row-ui>`, `<stack-ui>`) as a
+   **direct child** of `<chat-shell>` — the shell's CSS lays out children by
+   tag selector (`chat-thread`, `chat-composer`, etc.); a generic wrapper
+   defeats that and the shell's `:has(chat-thread[streaming])` cross-cut
+   styling.
+
+## Severity mapping
+
+- **critical** — `<chat-shell>` present but missing `<chat-thread>` or
+  `<chat-composer>` (parts 2, 4). The shell can't render a usable
+  conversation surface without both.
+- **warning** — `<chat-composer>` has no inner `<chat-input-ui>`/`<input-ui>`
+  (part 5); a `<chat-header>` present but missing both `[slot="name"]` and
+  `[slot="status"]` content (part 6); a generic layout primitive
+  (`col-ui`/`row-ui`/`stack-ui`) authored as a direct child (part 8).
+- **info** — `<chat-thread>` missing its `<chat-empty>` first child (part 3;
+  a thread pre-seeded with real messages legitimately skips this);
+  `<chat-header>` absent entirely (part 6 is optional chrome);
+  `<chat-sidebar>` absent (part 7, forward-looking per the yaml — chat is
+  typically single-pane).
+
+## What the script flags (mechanical subset)
+
+| Symptom | Diagnosis |
+|---|---|
+| `<chat-shell>` with no `<chat-thread>` | critical — part 2 |
+| `<chat-shell>` with no `<chat-composer>` | critical — part 4 |
+| `<chat-composer>` with no `<chat-input-ui>`/`<input-ui>` child | warning — part 5 |
+| `<chat-header>` present, no `[slot="name"]` and no `[slot="status"]`/`<chat-status>` | warning — part 6 |
+| `<chat-shell>` direct child is `col-ui`/`row-ui`/`stack-ui` | warning — part 8 (legacy-generic-layout leak) |
+| `<chat-thread>` with no `<chat-empty>` child | info — part 3 |
+
+## Opt-out contract
+
+Same annotation mechanism as admin-shell: `<chat-shell
+data-shell-opt-out="reason">` downgrades every finding on that shell to
+info and prints the reason for reviewers.
+
+## Triage
+
+- Canonical product surface (`apps/genui` chat/factory-chat pages,
+  `playgrounds/chat/*`) → fix mandatory.
+- A narrow single-feature playground isolating one chat behavior → fix
+  optional; annotate the opt-out.
+- Never point this audit at `packages/web-modules/chat/**/*.examples.html`
+  or `packages/web-components/components/*/*.html` (single-primitive
+  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  already keeps those out of scope, same as admin-shell.
+- `:strict` is the CI/publish posture; keep warn-only while iterating
+  locally.
+
+## Legacy shapes — never re-authored
+
+`chat-shell.yaml`'s own description lists the ADR-0024-retired legacy
+data-attribute shapes (`<section data-chat-messages>`, `<chat-input-ui
+data-chat-input>`, `<empty-state-ui data-chat-empty>`, `<header
+data-chat-name>`) as silently unrecognized, not merely deprecated. This
+audit does not re-detect them (a separate concern from anatomy
+completeness) — `verify:no-legacy-shell-shapes` in `npm run check` already
+covers that ground.

package/skills/demo-audit/references/editor-shell-anatomy.md

@@ -0,0 +1,109 @@
+# Mode 5c — Editor-shell composition: the canonical parts
+
+Script: `scripts/dev/audit-shell-composition.mjs` (repo-local), npm gates
+`audit:shell-composition{,:strict,:all}`. Static AST walk over
+`apps/**/*.html`, `playgrounds/**/*.html`, `catalog/page-shells/**/*.html` —
+no browser needed; pre-commit fast. Shares one script and one output
+contract with the `<admin-shell>` census
+([admin-shell-anatomy](admin-shell-anatomy.md)) — the script's own
+`EDITOR_PARTS` array is the mechanical census; this file is the human
+review standard. Canonical source:
+`packages/web-modules/editor/editor-shell/editor-shell.yaml` (the
+behavioral contract) and `apps/construct-canvas/app/construct-canvas.contents.html`
+(the canonical rendered reference, cited by `apps/genui/PATTERNS.md`'s
+chrome-decision table as editor-shell's canonical demo, alongside
+`apps/genui`'s own a2ui-editor consumer).
+
+`gh#2909`/`apps/genui/PATTERNS.md:329-337` established that `apps/genui`
+(a2ui-editor) is a real `<editor-shell>` consumer that a
+`<admin-shell>`-only mode 5 sweep never scanned — this anatomy closes that
+blind spot.
+
+## The canonical parts
+
+1. `<editor-shell>` outer.
+2. `<editor-canvas>` direct child — the central work surface. Required:
+   without it there is nowhere for artboards/document body/canvas content
+   to land, the editor equivalent of admin-shell's `<admin-content>`.
+3. `<editor-toolbar>` direct child — the app-scope top chrome bar (document
+   title, run/save/undo/redo, focus-mode toggle). Recommended; an editor
+   with no toolbar has no document-wide action surface.
+4. `<editor-canvas> > <editor-canvas-empty>` as (typically first) child —
+   the empty-state placeholder shown via the parent's `[empty]` reflected
+   attribute before any content exists.
+5. `<editor-canvas> > <editor-canvas-toolbar>` — optional canvas-scope
+   chrome (view-mode tabs, breadcrumbs) sticky to the canvas top edge;
+   distinct from part 3's app-scope toolbar.
+6. `<editor-statusbar>` direct child — bottom chrome bar (save/sync state,
+   zoom, cursor position). Recommended; loses the canonical status-strip
+   without it.
+7. `<editor-sidebar slot="leading"|"trailing">` — optional navigator or
+   inspector rail.
+8. When an `<editor-sidebar>` is present, it must wrap `<pane-ui
+   resizable>` (or at minimum `<pane-ui>`) — editor-sidebar is the one
+   bespoke shell child that **delegates** rather than duplicates a
+   primitive's resize behavior (per `shell-patterns.md`'s "FIRST bespoke
+   shell child that delegates" note); an editor-sidebar with no inner
+   `<pane-ui>` reimplements drag by hand instead of reusing the primitive.
+9. No bare `<header>` / `<footer>` native elements as direct children of
+   `<editor-shell>` — these are the ADR-0024-retired legacy chrome shapes
+   that `<editor-toolbar>` / `<editor-statusbar>` replaced.
+
+## Severity mapping
+
+- **critical** — `<editor-shell>` present but missing `<editor-canvas>`
+  (part 2). The shell can't render usable content without it.
+- **warning** — no `<editor-toolbar>` (part 3); no `<editor-statusbar>`
+  (part 6); an `<editor-sidebar>` present with no inner `<pane-ui>` (part
+  8); a bare native `<header>`/`<footer>` direct child (part 9, the
+  retired-legacy-shape leak).
+- **info** — `<editor-canvas>` missing its `<editor-canvas-empty>` first
+  child (part 4; a canvas pre-seeded with real content legitimately skips
+  this); no `<editor-canvas-toolbar>` (part 5, optional canvas chrome); no
+  `<editor-sidebar>` at all (part 7 — `construct-canvas`'s own comment
+  notes "no leading pane today", a legitimately sidebar-less composition).
+
+## What the script flags (mechanical subset)
+
+| Symptom | Diagnosis |
+|---|---|
+| `<editor-shell>` with no `<editor-canvas>` | critical — part 2 |
+| `<editor-shell>` with no `<editor-toolbar>` | warning — part 3 |
+| `<editor-shell>` with no `<editor-statusbar>` | warning — part 6 |
+| `<editor-sidebar>` present, no inner `<pane-ui>` | warning — part 8 (delegation contract violated) |
+| `<editor-shell>` direct child is native `<header>`/`<footer>` | warning — part 9 (retired-legacy-shape leak) |
+| `<editor-canvas>` with no `<editor-canvas-empty>` child | info — part 4 |
+
+## Opt-out contract
+
+Same annotation mechanism as admin-shell: `<editor-shell
+data-shell-opt-out="reason">` downgrades every finding on that shell to
+info and prints the reason for reviewers.
+
+## Triage
+
+- Canonical product surface (`apps/construct-canvas`, `apps/genui`'s
+  a2ui-editor) → fix mandatory.
+- A narrow single-feature playground isolating one editor behavior → fix
+  optional; annotate the opt-out.
+- Never point this audit at `packages/web-modules/editor/**/*.examples.html`
+  or `packages/web-components/components/*/*.html` (single-primitive
+  spotlights) — the script's `isShowcaseDemo`/showcase-path exclusion
+  already keeps those out of scope, same as admin-shell.
+- **Don't nest `<editor-shell>` inside `<admin-shell>`** as page chrome —
+  `editor-shell.examples.html` documents them as sibling surfaces, not
+  nested; this audit doesn't mechanically flag the nesting mistake (a
+  cross-shell structural rule, not a within-shell anatomy gap), but a
+  reviewer seeing both tags in one file should treat it as a design smell.
+- `:strict` is the CI/publish posture; keep warn-only while iterating
+  locally.
+
+## Legacy shapes — never re-authored
+
+`editor-shell.yaml`'s own description lists the ADR-0024-retired legacy
+data-attribute shapes (`<header>`, `<div data-editor-body>`, `<pane-ui
+data-left|data-right>`, `<div data-canvas>`, `<footer>`, `<span
+data-spacer>`) as silently unrecognized, not merely deprecated. Part 9
+above catches the two structural container tags (`<header>`/`<footer>`)
+mechanically; the finer-grained data-attribute forms are already covered
+by `verify:no-legacy-shell-shapes` in `npm run check`.

package/skills/package-release/references/cut-procedure.md

@@ -23,6 +23,7 @@ Two entry variants, converging at Step 5:
 | 1 | Re-baseline (branch check + status + log + fetch) | No |
 | 2 | Classify uncommitted files; stash strays | Stash only |
 | 3 | Pre-flight gates (+ harvest preamble if source content changed) | No |
+| 4a-pre | Assemble `changes/<pr>.md` fragments into the right `[Unreleased]` (REQ-W11-06) | Yes |
 | 4 | (Variant B) Promote `[Unreleased]`; bump; lockfile | Yes |
 | 4f | Pre-tag coverage `--fix` — authoritative F-N1 matcher, pre-PR | CHANGELOGs |
 | 5 | Stage the release allowlist; commit on `release/vX.Y.Z` | Yes |
@@ -100,6 +101,8 @@ When only source *hashes* move and chunk content does not, `check:embeddings-fre
 
 **Regen output supersedes working-tree state.** These outputs land in the release commit unconditionally, even when the same paths are also dirty from a peer — the fresh regen is authoritative; divergent uncommitted work rebases on top afterwards.
 
+**Staging a read-only report without cutting** (gh#3063): `node scripts/release/preflight-dry-run.mjs --version X.Y.Z` runs this same roster (`gate-roster.mjs` SoT) inside a throwaway `npm ci` clone and prints per-gate PASS/FAIL plus a tail-of-log on failure — no bump, no tag, no CHANGELOG promotion, nothing lands on the real repo. This mechanizes the ad-hoc procedure the 0.8.59 staging pre-flight hand-drove (gh#2870 comments 5526330460 + addendum); use it whenever a "how healthy is main right now" report is wanted ahead of an actual cut. `--dry-run` lists the roster with no clone/npm ci; `--keep` preserves the throwaway clone for inspection.
+
 ### 3.1 The full roster — every gate runs; a subset = pre-flight failure
 
 **Execution model (gh#2006): three phases, not one serial walk.** `step3PreFlight()` runs gate 4 solo first (see its own note below), then gates 16 → 27 → 28 strictly in order (the eval-health write-then-read dependency — gate 28 reads whichever `evals/mcp/runs/` directory sorts lexically LAST, so nothing else may write there between 27 and 28), concurrently with a bounded pool running every other gate at once (`PREFLIGHT_CONCURRENCY`, default 4 — override for a dedicated/idle host). Every gate still resolves the same command, still fails the whole pre-flight on a red result, and still reports its own number — only the WALL-CLOCK schedule changed, never the roster below or its numbering. `--dry` previews stay the original flat serial walk unchanged.
@@ -140,6 +143,8 @@ npm run check:harness-manifests-fresh          # 32 Hermes/Pi plugin.yaml + __in
 npm run verify:patterns-index                  # 33 pattern-index.md (mcp + adia-ui-factory) vs corpus source
 node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details  # 34 yaml events: blocks vs runtime dispatch — no phantom/missing events (gh#2829)
 node scripts/release/check-yaml-impl-coverage.mjs --strict                       # 35 yaml schema fields vs implementation coverage (gh#2829)
+npm run check:treeshake                        # 36 single-import build matrix (esbuild+rollup) — byte budgets + marker-leak + CSS purity + whole-lib delta + docs grep-gate (gh#2912)
+npm run check:lint-efficacy                    # 37 lint rule bank: seeded catch rate 100% + golden-set 0 error FPs + mutation hardening (gh#2911 — not in `npm run check`, ~100s over the <60s bar)
 ```
 
 **Gate 29 was the ADR-0048 latch; since P5 it is a permanent invariant.** Between P1 and P5 the repo was correct in-repo but deliberately **not publishable** (old-name stubs marked `private: true` that the roster still mapped, plus dependency edges onto workspace packages no cut published), and a cut in that window would have shipped broken packages that npm cannot unpublish. **P5 cleared it by landing the real thing** — the six stubs became publishable shims and `PACKAGE_ROSTER` gained the three remaining new names, at which point all 9 offending edges resolved and the gate went green on its own. No gate logic was changed.
@@ -157,10 +162,45 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 ## §Step 4 — (Variant B, or ANY variant with uncommitted `[Unreleased]` content) Promote, bump, lockfile
 
+**4a-pre. Assemble `changes/<pr>.md` fragments (REQ-W11-06, gh#2931), BEFORE promotion.** This
+repo's PRs land a `changes/<pr>.md` fragment instead of hand-editing a CHANGELOG directly —
+`check-changelog-pr-gate.mjs`'s own PR-time gate now REQUIRES a fragment for a roster-package
+change and refuses the direct edit outright (gh#3123; the root `CHANGELOG.md` was already
+fragment-only in practice before that ticket). Those fragments accumulate
+unreleased until something folds them into the right CHANGELOG's `[Unreleased]` section — that's
+this step, and it must run before 4a promotes `[Unreleased]` to a versioned heading, or a
+fragment folded in afterward would land under the WRONG (already-promoted) heading.
+
+```bash
+node scripts/release/assemble-changelog-fragments.mjs        # writes, deletes consumed fragments
+node scripts/release/assemble-changelog-fragments.mjs --verify   # must print PASS afterward
+```
+
+Routing rule (`scripts/release/assemble-changelog-fragments.mjs`'s own header, full detail
+there): a fragment's first line is `- <kind>: <sentence>` (kind in fix|feature|chore|docs,
+unchanged from `changelog_fragments.py`'s schema) or, this repo's own addition, `- <kind>
+(<package>): <sentence>` naming a `PACKAGE_ROSTER` (`package-paths.mjs`) entry. The
+parenthetical-package form routes to that package's own `packages/<dir>/CHANGELOG.md` — the
+norm for package-scoped fragments as of gh#3123, not a hypothetical; the plain form routes to
+the repo-root `CHANGELOG.md`, whose own header scopes
+it to exactly that shape of change ("tooling, CI, build scripts, cross-package work, docs").
+`kind` maps to a Keep-a-Changelog subsection: `feature`→Added, `fix`→Fixed, `chore`→Changed,
+`docs`→Docs — created under `## [Unreleased]` in that canonical order if the subsection doesn't
+already exist, otherwise appended to the existing one.
+
+**Deliberately NOT a pre-flight roster gate (§3.1).** Pending fragments are a NORMAL state
+between PRs, not a defect — a `--verify`-shaped freshness gate added to the pre-cut roster (which
+runs before this step, in Step 3) would fail on every cut that has any recent chore/fix/feature
+PR queued, which is the common case. The `--verify` invocation above is a post-assembly
+self-check (proves the assemble actually consumed everything it found), not a standing gate;
+`gate-roster.mjs`'s count is unchanged by this ticket.
+
 **Run 4a whenever a hand-authored `## [Unreleased]` section is still sitting uncommitted, not only on a strict Variant B.** `release-pack.mjs --mode cut` (a peer's pre-staged content, not yet promoted) needs it exactly as much as `--mode from-scratch` does — the v0.8.4 near-miss was `--mode cut` skipping this step entirely because the doc (and the script) only associated promotion with "from scratch". Both modes now run it and both hard-fail before the bump if any roster package still carries non-empty `[Unreleased]` content afterward.
 
 **4a. Promote** `## [Unreleased]` → `## [vX.Y.Z] — YYYY-MM-DD` per package (`` `<plugin-root>/skills/package-release/scripts/promote-unreleased.mjs` ``); author fresh blocks for changed-but-unlogged packages; stub the pure ride-alongs (`` `<plugin-root>/skills/package-release/scripts/insert-stub.mjs` ``). Classification recipe + shapes: [`changelog-discipline.md`](changelog-discipline.md).
 
+`release-pack.mjs` (both `--mode cut` and `--mode from-scratch`) now rejects any `--substantive-packages`/`--stub-packages` name whose entry in `scripts/package-paths.mjs`'s `PACKAGE_ROSTER` is unknown or `lockstep: false`, at parse time, before Step 1 runs (gh#2894) — the 0.8.58 cut passed `adia-plugins` (lockstep:false) in `--substantive-packages` and let `promote-unreleased.mjs` rewrite its `[Unreleased]` header to a version that package never ships, caught only at Step 5.6 after the full pre-flight had already run.
+
 **4b. Bump.** PATCH vs MINOR: **MINOR is reserved for API-surface breaks only** (removed/renamed prop, attribute, slot, event, token, or tag). Visible behavior changes, re-scalings, and opt-in features stay PATCH; a CHANGELOG bullet saying "(MINOR behavior change)" is prose, not a semver directive. Unqualified "bump version" = PATCH; don't round-trip to ask. `node "<plugin-root>/skills/package-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z`. On a MINOR cut, also bump the internal `@adia-ai/*` `^ranges` separately (bump.mjs touches `"version"` fields only) — and a MINOR cut owes a MIGRATION GUIDE section ([`migration-guide-authoring.md`](migration-guide-authoring.md)).
 
 **4c. Lockfile.** `npm install --package-lock-only --no-audit --no-fund` — must land in the release commit. The publish workflows open with `npm ci`, which hard-fails on a version/lockfile mismatch: a bump without the regenerated lockfile passes locally and breaks **every** publish at clean-install.
@@ -229,6 +269,7 @@ stub sections exist leaves it nothing to append to, and the gap resurfaces
 as F-N1 warns at the push boundary, costing a tag move:
 
 ```bash
+node scripts/release/assemble-changelog-fragments.mjs                                         # 4a-pre (idempotent — safe to re-run; no-op if already assembled)
 node "<plugin-root>/skills/package-release/scripts/insert-stub.mjs" \
   --version X.Y.Z --date YYYY-MM-DD --previous-version X.Y.Z-1 \
   --substantive "<one-line>" --xref "<anchor>" --packages <missing-stubs>   # 4a-stub — FIRST, only the missing ones (hard-errors on existing sections)

package/skills/package-release/scripts/bump.mjs

@@ -88,6 +88,23 @@ const PINNED_REFS = {
       new RegExp(`("@adia-ai/[a-z0-9-]+":\\s*")${from.replace(/\./g, '\\.')}(?![\\d.])`, 'g'),
     replace: (to) => `$1${to}`,
   }],
+  // icons-cdn.js's hand-typed PACKAGE_VERSION literal (gh#3228's jsDelivr
+  // manifest-fallback URL pin) must move with web-components' OWN version
+  // every cut — unlike the file's other literal (PINNED_VERSION, which
+  // tracks @phosphor-icons/core's independent release cadence and is
+  // updated by hand only when Phosphor cuts), this one pins the very
+  // package it lives in. Left unmoved by bump.mjs through the 0.8.58 cut,
+  // it would leave MANIFEST_CDN_FALLBACK_URL naming a stale version with
+  // check:lockstep staying green — no coherence source watched it until
+  // lockstep-checks.mjs's invariant 9 (gh#3240) and this pin closed the
+  // loop together.
+  'packages/web-components': [{
+    file: 'core/icons-cdn.js',
+    label: 'icons-cdn.js PACKAGE_VERSION literal (jsDelivr manifest fallback pin)',
+    pattern: (from) =>
+      new RegExp(`(const PACKAGE_VERSION = ')${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])(')`),
+    replace: (to) => `$1${to}$2`,
+  }],
 };
 
 // Repo-level version references (path relative to REPO ROOT, not a package) —
@@ -274,10 +291,14 @@ function main() {
 // script never calls fs.writeFileSync by pointing at a path whose directory
 // doesn't exist; a latent write bug would throw ENOENT instead of passing.
 function selftest() {
+  // A fixture pkg name deliberately NOT in PINNED_REFS/SIBLING_MANIFESTS —
+  // this proof exercises bumpAll's core version-field transform in
+  // isolation, so it must not collide with (and pull in the file reads for)
+  // any real package's pin config.
   const fake = [{
-    pkg: 'packages/web-components',
+    pkg: 'packages/fixture-pkg',
     path: '/nonexistent-fixture-dir/package.json',
-    txt: '{\n  "name": "@adia-ai/web-components",\n  "version": "0.8.4"\n}\n',
+    txt: '{\n  "name": "@adia-ai/fixture-pkg",\n  "version": "0.8.4"\n}\n',
     version: '0.8.4',
   }];
   if (!validateAllAtFrom(fake, '0.8.4')) {
@@ -341,6 +362,24 @@ function selftest() {
     console.error('selftest FAIL: peer-pin pattern prefix-matched a longer version'); process.exit(1);
   }
 
+  // icons-cdn.js PACKAGE_VERSION literal (gh#3240, invariant 9) — must move
+  // with web-components' own version, and must not touch the file's OTHER
+  // literal-looking pin (PINNED_VERSION, @phosphor-icons/core's version,
+  // updated by hand on its own independent cadence).
+  const [iconsCdnCfg] = PINNED_REFS['packages/web-components'];
+  const iconsCdnBefore =
+    "const PINNED_VERSION = '2.1.1';\n\nconst PACKAGE_VERSION = '0.8.58';\n";
+  const iconsCdnAfter = bumpPinnedRef(iconsCdnBefore, iconsCdnCfg, '0.8.58', '0.8.59');
+  if (!iconsCdnAfter.includes("PACKAGE_VERSION = '0.8.59'") || iconsCdnAfter.includes("PACKAGE_VERSION = '0.8.58'")) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the icons-cdn.js PACKAGE_VERSION literal'); process.exit(1);
+  }
+  if (!iconsCdnAfter.includes("PINNED_VERSION = '2.1.1'")) {
+    console.error('selftest FAIL: icons-cdn.js pin bump touched the unrelated PINNED_VERSION (phosphor) literal'); process.exit(1);
+  }
+  if (bumpPinnedRef("const PACKAGE_VERSION = '0.8.580';", iconsCdnCfg, '0.8.58', '0.8.59') !== "const PACKAGE_VERSION = '0.8.580';") {
+    console.error('selftest FAIL: icons-cdn.js pin pattern prefix-matched a longer version'); process.exit(1);
+  }
+
   // validatePinsAtFrom — the mutation-free pre-flight (reviewer finding: the
   // mid-loop pin check fired only after two files were already written).
   const goodPin = [{ pkg: 'packages/plugins/adia-ui-factory', cfg: pinCfg, path: '/nonexistent/.mcp.json', txt: pinBefore }];

package/skills/package-release/scripts/gate-roster.mjs

@@ -163,6 +163,33 @@ export const GATE_ROSTER = [
   // inserted — same numbering discipline as gate 30/31/32/33.
   { n: 34, cmd: 'node scripts/release/check-yaml-events-vs-runtime.mjs --strict --strict-details', what: 'yaml events: blocks vs runtime dispatch (no phantom/missing events)' },
   { n: 35, cmd: 'node scripts/release/check-yaml-impl-coverage.mjs --strict', what: 'yaml schema fields vs implementation coverage' },
+  // gh#2912, plan-top-priority-verification.md item 4 (G1): the full
+  // 10-component x 2-bundler single-import build matrix — byte budgets +
+  // 0-foreign-marker-leak + paired-CSS-purity + whole-lib-delta + docs
+  // grep-gate. Too slow/heavy to gate every `npm run check` run (it spins
+  // up real esbuild AND rollup builds per cell); a 3-cell fast canary is
+  // wired into `npm run check` instead (check:treeshake:canary) as a
+  // regression tripwire, with the full matrix reserved for cut time. The
+  // matrix surfaced 14 real, pre-existing cross-component marker leaks
+  // (tracked as gh#2922, not fixed by this ticket) that are held under a
+  // known-red allowlist in check-treeshake.mjs itself — a cell diverging
+  // from its allowlisted finding, or any non-allowlisted cell failing,
+  // still reds this gate; the script also reports an allowlisted cell that
+  // comes back clean as promotable rather than staying silent about it.
+  // With the allowlist, this gate is currently all-green. Appended, not
+  // inserted — same numbering discipline as gate 30/31/32/33/34/35.
+  { n: 36, cmd: 'npm run check:treeshake', what: 'single-import build matrix (esbuild+rollup) — byte budgets + marker-leak + CSS purity + whole-lib delta + docs grep-gate' },
+  // gh#2911 (plan-top-priority-verification.md item 3 G1): the lint rule
+  // bank's seeded-violation catch-rate + false-positive golden-set sweep +
+  // 5-rule mutation hardening. NOT in `npm run check` — the golden-set FP
+  // sweep alone measured ~100s (every rule in the bank re-parses every one
+  // of ~440 `*.examples.html`/`*.contents.html` files; the generated
+  // composition rules each call `tagTree()` independently rather than
+  // sharing one parse per file — a real perf gap, filed as gh#2937,
+  // not fixed here), over AGENTS.md's <60s bar for the PR-blocking
+  // aggregate. Appended, not inserted — same numbering discipline as gate
+  // 30/31/32/33/34/35/36.
+  { n: 37, cmd: 'npm run check:lint-efficacy', what: 'lint rule bank: seeded catch rate 100% + golden-set 0 error FPs + mutation hardening' },
 ];
 
 // -- CLI ------------------------------------------------------------------

package/skills/package-release/scripts/release-pack.mjs

@@ -88,6 +88,26 @@ const DEFAULT_NPM_SCOPE = '@adia-ai';
 const LOCKSTEP_ROSTER = PACKAGE_ROSTER.filter((p) => p.lockstep !== false);
 const PACKAGES = LOCKSTEP_ROSTER.map((p) => p.name);
 
+// Reject a --substantive-packages/--stub-packages name whose roster entry is
+// unknown or lockstep:false, BEFORE Step 1 runs (gh#2894). The 0.8.58 cut
+// passed `adia-plugins` (lockstep:false, gh#1133) in --substantive-packages;
+// promote-unreleased.mjs happily rewrote its CHANGELOG's [Unreleased] header
+// to a version that package doesn't ship, and the cut only caught it at Step
+// 5.6's unstaged-tracked-files guard — AFTER the 34-gate pre-flight had
+// already run. Matches PACKAGE_ROSTER by name form (`adia-plugins`) or dir
+// form minus the `packages/` prefix (`plugins/adia-plugins`).
+function assertLockstepPackages(names) {
+  for (const pkg of names) {
+    const entry = PACKAGE_ROSTER.find(
+      (p) => p.name === pkg || p.dir.replace(/^packages\//, '') === pkg,
+    );
+    if (!entry || entry.lockstep === false) {
+      console.error(`error: --substantive-packages/--stub-packages package "${pkg}" is not lockstep:true in scripts/package-paths.mjs PACKAGE_ROSTER (unknown or class-B) — rejected before Step 1.`);
+      process.exit(2);
+    }
+  }
+}
+
 function parseArgs(argv) {
   const args = {
     version: null, date: null, previous: null, mode: null,
@@ -148,6 +168,12 @@ function parseArgs(argv) {
     console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
+  // Roster validation (gh#2894), before any mode-specific check below —
+  // applies to BOTH cut and from-scratch (the script's own --help text shows
+  // both flags on a `cut` invocation).
+  if (args.substantivePackages || args.stubPackages) {
+    assertLockstepPackages([...(args.substantivePackages ?? []), ...(args.stubPackages ?? [])]);
+  }
   // Handoff needs the GH-notes body at Step 10 — validate at PARSE time, not
   // there: on the v0.8.10 cut the missing flag surfaced only after tags and
   // npm publish were already irreversible (Step 10 is the LAST step). An arg
@@ -1753,6 +1779,37 @@ async function selftest() {
       process.exit(1);
     }
 
+    // gh#2894 — a --substantive-packages/--stub-packages name whose roster
+    // entry is lockstep:false (or unknown) must die at PARSE time, naming
+    // the roster file, BEFORE Step 1 runs. The 0.8.58 cut passed
+    // `adia-plugins` (lockstep:false) in --substantive-packages and only
+    // caught it at Step 5.6, after the 34-gate pre-flight had already run.
+    const rosterRejectShapes = [
+      { flags: '--substantive-packages adia-plugins', name: 'adia-plugins' },
+      { flags: '--stub-packages totally-unknown-package', name: 'totally-unknown-package' },
+    ];
+    for (const { flags, name } of rosterRejectShapes) {
+      let failed = false;
+      let out = '';
+      try {
+        execSync(
+          `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ${flags} --dry`,
+          { cwd: REPO, encoding: 'utf8' },
+        );
+      } catch (e) {
+        failed = true;
+        out = (e.stdout || '') + (e.stderr || '');
+      }
+      if (!failed || !out.includes(name) || !out.includes('package-paths.mjs PACKAGE_ROSTER')) {
+        console.error(`selftest FAIL: --substantive-packages/--stub-packages "${name}" must hard-reject naming scripts/package-paths.mjs PACKAGE_ROSTER`);
+        process.exit(1);
+      }
+      if (out.includes('=== Step 1') || out.includes('gate roster')) {
+        console.error(`selftest FAIL: the roster guard for "${name}" must fire BEFORE Step 1, not after`);
+        process.exit(1);
+      }
+    }
+
     // gh#765 — from-scratch with substantive-but-no-stub packages must die at
     // PARSE time, naming the ride-alongs, BEFORE any pre-flight gate runs
     // (v0.8.29 burned three ~15-min pre-flight re-runs discovering it at