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

package/skills/a2ui-maintenance/references/eval-diagnostics.md

@@ -46,7 +46,7 @@ fluctuate).
 ## Phase 2 — fixes per bucket
 
 - **A. Holdout alignment** — map each intent's `expected_chunk` to the actual
-  top-1; update `packages/gen-ui/engine/corpus/evals/holdout-compose-from-chunks.jsonl`.
+  top-1; update `packages/gen-ui/engine/evals/corpus/holdout-compose-from-chunks.jsonl`.
 - **E. Measurement traps** — PascalCase→kebab (`AgentTrace` → `agent-trace`,
   not `agenttrace`); substring false positives (`pane` vs `panel`,
   `textarea-ui` contains `text-ui` — word boundaries); case sensitivity (`/i`).
@@ -82,7 +82,7 @@ the SKILL.md floors hold.
 The two `check:*-eval-regression` scripts own the floor numbers — read the source
 before quoting a number elsewhere; SKILL.md only mirrors them and can drift (it
 once silently regressed to `cov≥40` before the mechanical gate existed). Zettel's
-floors are a committed file, `evals/health/zettel-floor.json` (gh#1391) —
+floors are a committed file, `packages/gen-ui/engine/evals/health/zettel-floor.json` (gh#1391);
 `scripts/release/check-zettel-eval-regression.mjs` loads it at runtime and refuses
 to run without it, so re-baselining is a JSON diff, not a source edit. Free-form's
 floors are still `ALERT_FLOOR`/`HARD_FLOOR` constants in

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

@@ -193,6 +193,32 @@ for any constant or decision lives in git and PR descriptions
     SoT); ADR-0097 rules a fourth, `traits`, but that part is decided-not-
     yet-shipped (gh#2513) — see `primitive-authoring/references/
     yaml-contract.md` §Synthesized universal props for the full contract.
+14. **Provider "extended thinking" is a strategy-level opt-in, not a
+    global default** (gh#3516, LLD-0033). PR #3511 (gh#3477) made
+    `{ thinking, thinkingBudget }` reachable through
+    `AdiaUILLMBridge.complete()`/`stream()`, default off; two call sites
+    opt in for real, each behind its own fixed-constant budget rather than
+    a caller-threaded option: `generate-thinking.js`'s own generate call
+    (`THINKING_BUDGET_MONOLITHIC_THINKING`) and `free-form-composer/
+    index.js`'s ingredient-picker call, both its primary pick and its own
+    paraphrase-retry (`THINKING_BUDGET_FREE_FORM`), both starting at the
+    bridge's own `DEFAULT_THINKING_BUDGET`, lowered to 4000 (gh#3516 slice
+    3, conductor ruling 2026-09-08) after an n=5 measurement at 10000
+    showed no measurable quality gain with real cost. `auto` inherits
+    through the free-form picker call the moment it escalates that far -
+    `monolithic-thinking` itself is never reachable via `auto`'s own
+    escalation ladder. Every other LLM call site (`generate-pro.js`'s four
+    branches, zettel's locator/modifier/synthesizer, the shared
+    `validate-and-repair.js` repair loop) stays thinking-off deliberately,
+    a narrow first pass pending real eval numbers - do not assume a new
+    engine inherits thinking by proximity to one that has it.
+    `StubLLMAdapter` accepts and records `thinking`/`thinkingBudget` on
+    its own `calls` log for strategy-level test assertions.
+    `eval-diff.mjs` gained `--mode` (`instant`/`pro`/`thinking`), scoped
+    to `--engine mcp` only, so `--engine mcp --mode thinking` exercises
+    the opted-in path independently of the router's own default. See
+    `docs/ops/lld/lld-0033-strategy-thinking-opt-in.md` for the full
+    decision record and the conductor's D1-D5 rulings.
 
 ## Test + run commands (all verified in root package.json)
 

package/skills/a2ui-maintenance/references/strategy-engines.md

@@ -86,6 +86,18 @@ shows the results); `--strict` enforcement is deferred to TKT-0010
 (27% of the corpus currently fails, mostly a schema-generation gap
 around `data-*`/`span` attributes rather than corpus-content defects).
 
+## Provider thinking opt-in kill switch (gh#3516, LLD-3516 slice 1)
+
+`monolithic-thinking` and `free-form-composer` opt into provider thinking at
+a fixed strategy-level budget (`THINKING_BUDGET_MONOLITHIC_THINKING`,
+`THINKING_BUDGET_FREE_FORM`, both 4000 as of gh#3516 slice 3) via the shared
+`compose/shared/thinking-opt-in.js` helper. `ADIA_THINKING_OPT_IN=0` drops
+the `thinking`/`thinkingBudget` fields at both call sites entirely (not
+`thinking: false`, the adapter never sees the keys), giving the
+thinking-off baseline a runtime lever instead of a code revert. Unset (or
+`"1"`) keeps current behavior. This is an operations knob, not a caller
+option: no consumer threads it through `generateUI()`.
+
 ## Pitfalls
 
 - **`STRONG_MATCH_THRESHOLD` was raised 22 → 40 post-incident.** Lowering it

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

@@ -17,7 +17,7 @@ the live admin-dashboard example.
    `<select-ui avatar="…" value="…" variant="ghost">` context switcher —
    NOT `<menu-ui>` (legacy pattern) — ★ commonly mis-implemented
 4. Sidebar nav wrap around `<nav-ui>` — `<section>` (per the examples),
-   `<section-ui>` (card-style chrome), or `<admin-scroll>` all accepted;
+   `<section-ui>` (card-style chrome), or `<page-scroll>` all accepted;
    a bare `<nav-ui>` direct child overflows long lists
 5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
    (user menu) — ★ commonly missing
@@ -28,17 +28,23 @@ the live admin-dashboard example.
    ★ spacer + actions commonly missing
 8. `[data-actions]` contains `<popover-ui>` + `<theme-panel slot="content">`
    (there is no `<theme-picker-ui>`)
-9. `<admin-scroll>` wrapping optional `<aside data-subnav hidden>` +
-   `<router-ui>` (or `<admin-page>` directly for non-routed)
-   **[deprecated 2026-09-01, ADR-0098]** `admin-scroll` is a wholesale
-   rename to `page-scroll` (both modes carried over); `admin-scroll` stays
-   as a working compat alias for the deprecation window only.
+9. `<page-scroll>` wrapping optional `<aside data-subnav hidden>` +
+   `<router-ui>` (or `<page-ui band>` directly for non-routed)
+   **[deleted, ADR-0098 / gh#3745]** `admin-scroll` was a wholesale
+   rename to `page-scroll` (both modes carried over); its one-release
+   deprecation window has closed and the module is deleted (gh#3745).
+   The `admin-page` family (`admin-page`/`admin-page-header`/
+   `admin-page-body`) is deleted outright per ADR-0098, no compat alias.
+   `page-scroll` wrapping `page-ui[band]` is the sole successor for the
+   routed and non-routed case alike.
 10. `<admin-page>` with `<admin-page-header>` + `<admin-page-body>`
-    **[deprecated 2026-09-01, ADR-0098]** The `admin-page` family is
-    retired deprecate-then-delete in favor of `page-ui[band]` — `page-ui`
-    is now the one canonical page-chrome primitive; this anatomy still
-    describes the pre-migration shape for auditing legacy surfaces during
-    the deprecation window.
+    **[deleted, ADR-0098]** The `admin-page` family is deleted outright,
+    no compat alias and no open deprecation window, in favor of
+    `page-ui[band]`; `page-ui` is now the one canonical page-chrome
+    primitive (item 9 above shows the live composition: `page-scroll`
+    wrapping `page-ui[band]`). This item is kept only so this anatomy
+    still recognizes the retired shape when auditing legacy surfaces
+    that predate the migration; never author it in new surfaces.
 11. `<admin-statusbar>` at content footer (version strip) — ★ commonly missing
 12. Second `<admin-sidebar slot="trailing">` (inspector rail, hidden by
     default) — strongly recommended
@@ -64,7 +70,7 @@ the live admin-dashboard example.
 | content topbar missing `[data-spacer]` / `[data-actions]` | warning — part 7 |
 | content missing trailing `<admin-statusbar>` | warning — part 11 |
 | sidebar topbar contains only plain text | warning — part 3 context switcher |
-| `<admin-scroll>` missing around `<admin-page>` | critical — part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+page wrapper the content renders flush with the topbar, no margins) — **[deprecated 2026-09-01, ADR-0098]** `admin-scroll`/`admin-page` describe the pre-migration shape; the successor is `page-scroll` wrapping `page-ui[band]` |
+| `<page-scroll>` missing around `<page-ui band>` | critical, part 9 (the enforcing script `audit-shell-composition.mjs` tiers this critical: without the scroll+chrome wrapper the content renders flush with the topbar, no margins). **[deleted, ADR-0098 / gh#3745]** `admin-scroll` and the `admin-page` family are both deleted outright, no compat alias; the successor is `page-scroll` wrapping `page-ui[band]` |
 
 ## Opt-out contract
 

package/skills/gen-ui-review/scripts/gen-review-decompose.mjs

@@ -37,6 +37,16 @@ import { chromium } from 'playwright';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+// gh#3616: the shared overflow predicate, vendored (not import()able:
+// this script ships inside a published plugin package with no apps/ tree
+// in its files allowlist, see this repo's scripts/build/
+// overflow-detect-vendor.mjs for the derive-and-vendor build that keeps
+// this copy provably identical to apps/genui/app/_shared/overflow-detect.js).
+// Imported as an ordinary function and passed BY REFERENCE into
+// elementHandle.evaluate() below, which stringifies it into the browser's
+// page context, same mechanism scripts/qa/gen-review-decompose.mjs's own
+// (non-vendored, import()-able) copy uses.
+import { OVERFLOW_TAGS, detectOverflow } from './overflow-detect.generated.mjs';
 
 // The script lives inside the plugin but runs against the monorepo. All
 // monorepo paths are resolved from the working directory (the monorepo root),
@@ -259,7 +269,7 @@ for (const group of gallery.groups) {
     for (const engineKey of Object.keys(prompt.engines ?? {})) {
       const engineData = prompt.engines[engineKey];
       if (!engineData || engineData.dryRun) continue;
-      allPrompts.push({ group: group.slug, prompt: prompt.slug, engineKey, engineData });
+      allPrompts.push({ group: group.slug, prompt: prompt.slug, label: prompt.label, engineKey, engineData });
     }
   }
 }
@@ -321,7 +331,7 @@ const results = [];
 let renderFailureCount = 0;
 let idx = 0;
 
-for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
+for (const { group, prompt: promptSlug, label, engineKey, engineData } of allPrompts) {
   idx++;
   const slug = `${group}-${promptSlug}-${engineKey}`;
   process.stdout.write(`  [${idx}/${allPrompts.length}] ${slug.padEnd(50)} `);
@@ -331,7 +341,10 @@ for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
   // Each has a .gallery-canvas-wrap containing a canvas-ui.
   // We identify by matching the group anchor + prompt h3 text.
 
-  const promptLabel = promptSlug.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+  // gh#3249: use the gallery's real prompt.label (what the h3 actually renders), not a
+  // title-cased guess derived from the slug -- the two diverge whenever the authored label
+  // isn't the slug's mechanical title-case ("search-filters" vs "Search with Filters").
+  const promptLabel = label;
 
   // Scroll to the prompt section and wait for canvas settle
   await page.evaluate(({ groupSlug, label }) => {
@@ -407,41 +420,21 @@ for (const { group, prompt: promptSlug, engineKey, engineData } of allPrompts) {
   // canvas. Runs only when the canvas rendered (renderFailure = false).
   // Results land in decomposed.json as `overflowElements` — a non-empty array
   // is treated as P1 in Phase 4 regardless of the Phase 3 structural score.
-
-  const OVERFLOW_TAGS = new Set([
-    'text-ui', 'stat-ui', 'badge-ui', 'field-ui', 'button-ui',
-    'label', 'span', 'p', 'h1', 'h2', 'h3', 'h4',
-  ]);
+  //
+  // gh#3616: the predicate itself (both the TEXT-truncation and LAYOUT-
+  // overflow checks, plus every documented exclusion: hscroll boundary,
+  // <svg> subtree) now lives in overflow-detect.generated.mjs (vendored
+  // from apps/genui/app/_shared/overflow-detect.js), passed straight into
+  // elementHandle.evaluate() below rather than re-implemented here, so
+  // this plugin sweep and the in-repo QA script/live artifact pane provably
+  // run the same code. `canvasWrapEl` is the exact same `.gallery-canvas-
+  // wrap` element the screenshot/render-failure check above already
+  // resolved, so there's no need to re-locate it by groupSlug/label.
 
   let overflowElements = [];
 
   if (!renderFailure) {
-    overflowElements = await page.evaluate(({ groupSlug, label, overflowTags }) => {
-      const section = document.getElementById(`group-${groupSlug}`);
-      if (!section) return [];
-      const h3s = [...section.querySelectorAll('.gallery-prompt-heading')];
-      const h3 = h3s.find(h => h.textContent.trim().toLowerCase() === label.toLowerCase());
-      const wrap = h3?.closest('.gallery-prompt')?.querySelector('.gallery-canvas-wrap');
-      if (!wrap) return [];
-
-      const found = [];
-      function walk(el) {
-        const tag = el.tagName?.toLowerCase() ?? '';
-        if (overflowTags.includes(tag)) {
-          const style = getComputedStyle(el);
-          const hasHidden = style.overflow === 'hidden' || style.overflowX === 'hidden';
-          if (hasHidden && el.scrollWidth > el.clientWidth + 2) {
-            found.push({ tag, clippedWidth: true });
-          }
-          if (hasHidden && el.scrollHeight > el.clientHeight + 2) {
-            found.push({ tag, clippedHeight: true });
-          }
-        }
-        for (const child of el.children) walk(child);
-      }
-      walk(wrap);
-      return found;
-    }, { groupSlug: group, label: promptLabel, overflowTags: [...OVERFLOW_TAGS] });
+    overflowElements = await canvasWrapEl.evaluate(detectOverflow, OVERFLOW_TAGS);
   }
 
   // ── Primitive lookup + sanitize ──────────────────────────────────────────

package/skills/gen-ui-review/scripts/overflow-detect.generated.mjs

@@ -0,0 +1,101 @@
+// GENERATED, do not hand-edit. Source: apps/genui/app/_shared/overflow-detect.js
+// Rebuild: node scripts/build/overflow-detect-vendor.mjs
+// Freshness gate: node scripts/build/overflow-detect-vendor.mjs --verify (npm run check:overflow-detect-vendor-fresh)
+//
+// gh#3616: vendored so the gen-ui-review plugin's own decompose script (a
+// published package with no apps/ tree in its files allowlist) runs the
+// EXACT SAME overflow/clip predicate as the in-repo QA script and the live
+// artifact pane, instead of a hand-kept inline copy that can silently drift
+// (the gap gh#3616 closed, see that ticket for the pre-fix divergence).
+
+/**
+ * Tags the text-truncation check inspects for their own `overflow:hidden`
+ * clipping a2ui-root/canvas-ui render. Every other tag is still walked for
+ * the layout-overflow check below, which applies to any tag.
+ */
+export const OVERFLOW_TAGS = [
+  'text-ui', 'stat-ui', 'badge-ui', 'field-ui', 'button-ui',
+  'label', 'span', 'p', 'h1', 'h2', 'h3', 'h4',
+];
+
+/**
+ * Walks a rendered container and reports overflow/clip findings.
+ *
+ * Two independent clipping mechanisms (gh#3248):
+ *   - TEXT truncation: an element's own `overflow:hidden` clips its own
+ *     scrollWidth/scrollHeight (e.g. a Text node with no line-clamp room).
+ *     Checked only for `overflowTags` elements.
+ *   - LAYOUT overflow: an element's whole box lays out past the
+ *     container's edge, whether or not anything in its ancestor chain has
+ *     `overflow:hidden` (e.g. two sibling `[stretch]` buttons in a Row
+ *     each claiming full row width, one landing off-canvas). Checked for
+ *     every visible tag, horizontal only. Vertical overflow is never
+ *     flagged since the container is expected to scroll vertically (the
+ *     gallery's own `.gallery-canvas-wrap` is deliberately
+ *     `overflow-y: auto`), and a container never scrolls sideways so a
+ *     right-edge slice is always wrong.
+ *
+ * Both checks skip content inside a genuine horizontal-scroll boundary
+ * (table-ui's own scroll wrapper, swiper-ui, tabs-ui's overflow-x strip):
+ * content past the visible edge there is intentional, scrolled-to
+ * content, not a layout bug. Also skipped: content inside an `<svg>`
+ * subtree (icon-ui's glyph markup, chart-ui's rendered marks), since SVG
+ * coordinate-space geometry doesn't map onto DOM layout-box geometry the
+ * same way, confirmed via a live false positive on chart-ui's own
+ * sparkline. `<foreignObject>` re-enters normal HTML flow content inside
+ * that `<svg>` subtree (SVG spec), so the svg-exclusion resets for its
+ * own children rather than staying latched: a real HTML element nested
+ * there gets checked again.
+ *
+ * `container` itself is excluded from the horizontal-scroll-boundary test:
+ * per the CSS Overflow spec, pairing `overflow-y: auto` with the default
+ * `overflow-x: visible` computes overflow-x to `auto` too. Treating that
+ * as a real scroll boundary would mark every one of the container's own
+ * children as inside-hscroll and silently disable the layout-overflow
+ * check for the entire canvas, the opposite of what it exists to catch.
+ *
+ * @param {Element} container the rendered surface's outer boundary
+ *   (gen-review-decompose.mjs's `.gallery-canvas-wrap`; the live artifact
+ *   pane's own equivalent container).
+ * @param {string[]} overflowTags see OVERFLOW_TAGS; always pass this
+ *   explicitly (see the module-doc note on why there's no default value).
+ * @returns {Array<{tag: string, clippedWidth?: true, clippedHeight?: true, pushedPastContainer?: true}>}
+ */
+export function detectOverflow(container, overflowTags) {
+  const found = [];
+  const containerRect = container.getBoundingClientRect();
+  const TOLERANCE = 2; // matches the scrollWidth/clientWidth +2 slack below
+
+  function walk(el, insideHScroll, isContainer, insideSvg) {
+    const tag = el.tagName?.toLowerCase() ?? '';
+    const style = getComputedStyle(el);
+
+    if (overflowTags.includes(tag)) {
+      const hasHidden = style.overflow === 'hidden' || style.overflowX === 'hidden';
+      if (hasHidden && el.scrollWidth > el.clientWidth + TOLERANCE) {
+        found.push({ tag, clippedWidth: true });
+      }
+      if (hasHidden && el.scrollHeight > el.clientHeight + TOLERANCE) {
+        found.push({ tag, clippedHeight: true });
+      }
+    }
+
+    if (!insideHScroll && !insideSvg) {
+      const rect = el.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) {
+        if (rect.right > containerRect.right + TOLERANCE || rect.left < containerRect.left - TOLERANCE) {
+          found.push({ tag, pushedPastContainer: true });
+        }
+      }
+    }
+
+    const isHScrollRoot = !isContainer
+      && (style.overflowX === 'auto' || style.overflowX === 'scroll')
+      && el.scrollWidth > el.clientWidth + TOLERANCE;
+    const nowInsideSvg = tag === 'foreignobject' ? false : (insideSvg || tag === 'svg');
+    for (const child of el.children) walk(child, insideHScroll || isHScrollRoot, false, nowInsideSvg);
+  }
+
+  walk(container, false, true, false);
+  return found;
+}

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

@@ -105,6 +105,24 @@ When only source *hashes* move and chunk content does not, `check:embeddings-fre
 
 ### 3.1 The full roster — every gate runs; a subset = pre-flight failure
 
+**Precondition — tsc build for llm, agent, persona (gh#3342).** Gate 4
+(`test:unit:serial`) runs each package's root `*.test.js` files against its
+BUILT output, not its `src/*.ts`: `persona.test.js` imports `./index.js`
+directly, `agent.test.js`'s own docstring says "run against the BUILT
+output ... `npm run build -w @adia-ai/agent` first", and `llm/core` carries
+a dedicated `dist-check.test.js` that asserts the emitted artifacts exist
+and explicitly does not build them itself. All three packages' emitted
+`.js`/`.d.ts` are gitignored, so a fresh cut clone has none of them until
+something builds them — unlike §3.0's regen outputs, this is a plain build
+artifact, not a content-conditional regen, so `release-pack.mjs`'s
+`step3PreFlight()` now runs `npm run build -w @adia-ai/llm -w @adia-ai/agent
+-w @adia-ai/persona` unconditionally, every cut, immediately before gate 4
+(mechanized fix — a manual cut should run the same command first). The
+v0.8.59 cut hit this: §3.0's `npm run build -w @adia-ai/llm` line only
+fires when its source-content trigger list matches, and never named
+agent/persona at all, so a cut with no matching trigger reached gate 4 with
+stale or absent dist and failed on it.
+
 **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.
 
 ```bash
@@ -176,6 +194,11 @@ node scripts/release/assemble-changelog-fragments.mjs        # writes, deletes c
 node scripts/release/assemble-changelog-fragments.mjs --verify   # must print PASS afterward
 ```
 
+Since gh#3638 a fragment may also be named `changes/gh-<issue>.md` (the form a builder can use
+before a PR number exists). Assembly handles both: an issue-named fragment is credited to the PR
+that merged it, read off that merge commit's own `(#<pr>)` subject, and falls back to the issue
+number when no such commit is found. Nothing changes in this step's commands.
+
 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>
@@ -327,11 +350,20 @@ Drift here means a regen output was left out of the allowlist — stage it and r
 fails the cut if any tracked file is still modified-in-the-worktree —
 proof the allowlist covered everything bump.mjs / cut-hygiene touched this
 cut, not just what §Step 5.5's three named freshness gates happen to check.
-This is the fourth time the allowlist itself went stale (gh#1198, gh#1899,
-gh#1954, gh#2473 — most recently the factory README's generation-MCP pin
-prose), so the guard is generic rather than another named file. A manual
-cut should run the equivalent check by hand: `git status --porcelain`
-after staging must be empty of `M`/`D` lines.
+The allowlist itself went stale five times (gh#1198, gh#1899, gh#1954,
+gh#2473, gh#3342 — most recently `icons-cdn.js`'s PACKAGE_VERSION pin), so
+this guard is generic rather than another named file — it stays the
+fallback for anything below. **The PINNED_REFS-covered subset of the
+allowlist can no longer drift this way at all** (gh#3361): `release-pack.mjs`
+now derives those specific entries straight from `bump.mjs`'s own
+`PINNED_REFS`/`REPO_PINNED_REFS` tables (`pinnedRefFiles()`) instead of
+hand-listing the same paths a second time — a new pinned file in `bump.mjs`
+is automatically a new allowlist entry, no second edit needed. Everything
+NOT PINNED_REFS-covered (roster `package.json`/`CHANGELOG.md`, and the Step
+4d.5-4d.8 derived catalog/manifest/dist outputs) is still hand-listed and
+still relies on this guard as the safety net. A manual cut should run the
+equivalent check by hand: `git status --porcelain` after staging must be
+empty of `M`/`D` lines.
 
 ## §Step 5.7 — Release PR: push the branch, merge, re-baseline
 
@@ -454,6 +486,18 @@ npm view @adia-ai/web-components dist-tags.latest   # must equal X.Y.Z
 
 Zero workflows fired after a tag push → [`recovery-paths.md`](recovery-paths.md) §Scenario 7.
 
+**npm's async staged-publish path (gh#3342):** a large tarball can take up to
+~25 minutes to become visible on `npm view` after npm accepts it —
+`release-pack.mjs`'s own Step 9 poll accounts for this (`REGISTRY_POLL_MINUTES`,
+default 30, up from the 10-minute window the v0.8.59 cut exceeded with every
+publish run green). A re-dispatch attempted while a package is in that state
+fails its `npm publish` step with `npm error code E409` ("Cannot publish over
+previously staged version") — that is the staged-not-lost signal, never a real
+failure; release-pack's Step 9 detects it (the failing run's own log) and polls
+longer instead of hard-failing. See [`recovery-paths.md`](recovery-paths.md)
+§Scenario 9 for manual recovery, including resuming at Step 10 only
+(`--from-step10`) without re-running the pre-flight or re-tagging.
+
 ## §Step 10 — GH releases + site deploy dispatch
 
 ```bash

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

@@ -97,6 +97,26 @@ For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the
 
 ---
 
+## §Scenario 9 — Step 9 registry poll times out with every publish run green (npm E409)
+
+**Shape:** `release-pack.mjs --mode handoff` exits 1 at Step 9, but `gh run list --workflow=publish-<pkg>.yml` shows every run `success` and `npm view <scope>/<pkg> version` eventually returns the target version — it just took longer than the poll waited. A large tarball can take up to ~25 minutes to become visible on `npm view` after npm accepts it (asynchronous staged publish); the v0.8.59 cut's poll window was 10 minutes.
+
+**A re-dispatch made while a package is in this state fails its own `npm publish` step with `npm error code E409` / "Cannot publish over previously staged version".** That error is not a real failure — npm rejected the duplicate publish precisely because the real one already landed server-side. It is the staged-not-lost signal, never grounds to re-dispatch a third time.
+
+**Resolution:**
+
+- `release-pack.mjs`'s Step 9 (gh#3342) already extends its own poll to `REGISTRY_POLL_MINUTES` (default 30, override via env) and, for any package still stale after that, checks its latest `publish-<pkg>.yml` run for the E409 signature before deciding — an E409-confirmed package gets one more extended, isolated poll instead of an immediate hard-fail. Nothing to do by hand in that case; let it finish.
+- If Step 9 already exited 1 and you've confirmed by hand (registry + `gh run list`) that every package is actually published, don't re-run the full handoff — it would re-run the ~15min pre-flight (Step 3) and re-tag at HEAD (Step 6, wrong if anything merged since the original tag). Resume from Step 10 only:
+
+  ```bash
+  node "<plugin-root>/skills/package-release/scripts/release-pack.mjs" \
+    --mode handoff --version X.Y.Z --date YYYY-MM-DD --previous-version X.Y.Z-1 \
+    --gh-notes-file <path> --from-step10
+  ```
+
+  `--from-step10` skips Steps 1/3/4/5/6/7/8/9 entirely and runs only Step 10 (GH releases + site deploy) — the exact shape a hand-rolled one-off script (`/tmp/cut-0859-step10.sh`, never checked in) worked around live on the v0.8.59 cut. Before jumping, it hard-verifies the umbrella tag AND every per-package tag (`vX.Y.Z`, `<pkg>-vX.Y.Z`) already exist on origin and resolve to HEAD — without that check, `gh release create` on a tag that was never actually made would silently mint a NEW lightweight tag at whatever HEAD happens to be, attaching the release notes to the wrong commit. A missing or mismatched tag refuses the resume outright, naming which tag and why (either Step 8 never pushed it, or HEAD moved since); re-tag/push for real, or checkout the tagged commit, before retrying.
+- **Never** re-dispatch a package a third time once it shows E409 — a third attempt only 409s again. Wait for the registry; it always converges.
+
 ## §Decision flowchart
 
 ```text

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

@@ -22,6 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { PACKAGE_ROSTER } from './package-paths.mjs';
 
 // Single-sourced roster (H3, package-paths.mjs). Each plugin also carries a
@@ -60,7 +61,14 @@ const SIBLING_MANIFESTS = Object.fromEntries(
 // `gen-ui-mcp`) was narrowed back by the shim-deletion follow-up PR, matching
 // lockstep-checks.mjs's MCP_PIN_RE — a retired name in the pin must now fail
 // loudly instead of being bumped along.
-const A2UI_MCP_PIN = {
+// gh#3361: exported so release-pack.mjs's Step 5 can derive its
+// PINNED_REFS-covered allowlist entries from this table directly instead of
+// hand-duplicating the file list — the drift class this table itself was
+// born to fix (gh#1198/1899/1954/2473/3342, all "bump.mjs moved a pin,
+// release-pack.mjs's own list didn't know about it") can no longer recur
+// for anything PINNED_REFS already covers: a new entry here is now a new
+// entry there, structurally, not two edits.
+export const A2UI_MCP_PIN = {
   label: 'generation-MCP pin (@adia-ai/mcp)',
   // `@adia-ai/mcp@<from>` (not a prefix of a longer version) → `@<to>`
   // Escape EVERY regex metacharacter in `from`, not just dots: a prerelease or
@@ -71,7 +79,7 @@ const A2UI_MCP_PIN = {
     new RegExp(`(@adia-ai/mcp@)${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])`),
   replace: (to) => `$1${to}`,
 };
-const PINNED_REFS = {
+export const PINNED_REFS = {
   'packages/plugins/adia-ui-factory': [
     { ...A2UI_MCP_PIN, file: '.mcp.json' },
     { ...A2UI_MCP_PIN, file: 'README.md', label: 'generation-MCP pin (README prose)' },
@@ -113,7 +121,7 @@ const PINNED_REFS = {
 // once and the next cut fails the gate — so the bump moves it, like the
 // .mcp.json pin (H2 follow-through, 2026-07-19: found 0.7.13 claimed while
 // 0.8.7 was live — a full minor of README drift shipped to npm).
-const REPO_PINNED_REFS = [
+export const REPO_PINNED_REFS = [
   {
     file: 'README.md',
     label: '"Current version" claim',
@@ -407,6 +415,28 @@ function selftest() {
   console.log('selftest OK');
 }
 
-const topArgv = process.argv.slice(2);
-if (topArgv[0] === 'selftest') selftest();
-else main();
+// gh#3361: this module is now imported for its PINNED_REFS/REPO_PINNED_REFS
+// exports (release-pack.mjs's Step 5), not only run as a CLI — a bare
+// `topArgv[0] === 'selftest'` / `else main()` at module scope would fire
+// `main()` (which calls `parseArgs`, which prints "error: --from/--to
+// required" and `process.exit(2)`s) the moment ANYTHING imports this file,
+// killing the importer's own process. Realpath-safe (a naive
+// `argv[1] === fileURLToPath(import.meta.url)` reads false through a
+// symlink, same pitfall scripts/lib/is-entry-point.mjs documents) so this
+// stays correct if bump.mjs is ever ELM'd behind one; inlined rather than
+// importing that top-level helper, keeping this skill's own scripts/
+// self-sufficient.
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  const topArgv = process.argv.slice(2);
+  if (topArgv[0] === 'selftest') selftest();
+  else main();
+}

package/skills/package-release/scripts/dispatch-publish.mjs

@@ -20,6 +20,7 @@
 import { execFileSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
+import { warnIfStaleCopy } from './stale-copy-warning.mjs';
 import { PACKAGE_ROSTER } from './package-paths.mjs';
 
 // Instance data — fork-configurable. The npm scope the lockstep roster publishes under.
@@ -288,6 +289,13 @@ async function main() {
   const args = parseArgs(process.argv.slice(2));
   // Fail-fast guard: refuse to run npm/gh against a non-monorepo directory.
   assertMonorepoRoot(process.cwd());
+  // Stale-plugin-cache self-check (ticket #3943 item 2), same primitive
+  // release-pack.mjs's own top-level check now calls.
+  warnIfStaleCopy(
+    import.meta.url,
+    process.cwd(),
+    'packages/plugins/adia-ui-forge/skills/package-release/scripts/dispatch-publish.mjs',
+  );
   if (args.after) checkAfter(args.after, args.scope);
 
   // Recovery mode — verify each publish workflow SUCCEEDED for its pushed tag

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

@@ -103,15 +103,15 @@ export const GATE_ROSTER = [
   // on the handoff re-run, since the promoted heading was already on main).
   { n: 26, cmd: 'node scripts/release/check-dx-sweep-freshness.mjs', targetVersionArg: true, what: 'DX sweep fresh + not regression-RED' },
   // gh#1135 (WS-4 SPEC REQ-06): a fresh free-form eval run feeds the health
-  // record gate 28 writes — without it, "latest" under evals/mcp/runs/ could
+  // record gate 28 writes: without it, "latest" under packages/gen-ui/engine/evals/mcp/runs/ could
   // be a stale leftover from an earlier ad-hoc run, not this cut's own state.
-  { n: 27, cmd: 'npm run eval:diff -- --engine free-form',   what: 'fresh free-form eval run (evals/health input)' },
-  // REQ-06: commits evals/health/<version>.json — the version this record
+  { n: 27, cmd: 'npm run eval:diff -- --engine free-form',   what: 'fresh free-form eval run (packages/gen-ui/engine/evals/health input)' },
+  // REQ-06: commits packages/gen-ui/engine/evals/health/<version>.json; the version this record
   // names is the CUT's target version from the start, never the
   // pre/post-bump `hygieneVersion` gate 24 needs (a claim-validation
   // concern this is not) — hence `targetVersionArg` rather than
   // `versionArg`, a distinct flag release-pack.mjs's step3PreFlight reads.
-  { n: 28, cmd: 'node scripts/release/write-eval-health.mjs', what: 'evals/health/<version>.json committed, AC-01/AC-02 run for real', targetVersionArg: true },
+  { n: 28, cmd: 'node scripts/release/write-eval-health.mjs', what: 'packages/gen-ui/engine/evals/health/<version>.json committed, AC-01/AC-02 run for real', targetVersionArg: true },
   // ADR-0048 (gh#1192) estate-split latch. Between P1 (mint @adia-ai/gen-ui)
   // and P5 (shims + roster) the tree is correct in-repo but deliberately
   // NOT publishable: the old package dirs are `private: true` stubs the