@adia-ai/adia-ui-forge 0.8.30 → 0.8.32

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.30",
+  "version": "0.8.32",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.32] — 2026-08-09
+
+### Fixed
+- **adia-release `release-pack.mjs` deploy-settle wait tracks the dispatched run, requires success, and names the blocking run (gh#762).** The handoff's "waiting for the deploy workflow to settle" loop polled the NEWEST run's status in silence — it could settle on the previous completed run before the dispatch registered, accepted failure/cancelled as settled, and gave no signal while a forgotten run WAITING at the `production-site` gate held the `deploy-site` concurrency group (56h on Aug 5–8). Now: the newest run id is captured before dispatch, the handoff waits for the NEW run to appear, polls that run by id, requires `conclusion=success` (anything else fails the handoff), and each poll reports the gate-waiting blocker's id, wait-start, and URL ("BLOCKED BEHIND run X — approve or cancel it"). Pairs with the repo-level `reap-stale-deploy-gate.yml` auto-cancel (root CHANGELOG).
+- **adia-release `release-pack.mjs` from-scratch guard rails (gh#765).** Three fixes from the v0.8.29 cut's failure modes: (1) a parse-time guard — `--mode from-scratch` whose `--substantive-packages` ∪ `--stub-packages` doesn't cover the 13-package roster now fails immediately, naming the ride-alongs that would be missing a `[VERSION]` CHANGELOG section, instead of dying at Step 4e after the ~15-min pre-flight (mirrors the handoff `--gh-notes-file` guard); (2) `sh()`/`shQuiet()` failures now print the failing command, exit status, and the inner command's captured stdout/stderr instead of a bare execSync stack; (3) a half-cut tree (all versions bumped + CHANGELOGs promoted by an aborted Step-4 run) is detected before pre-flight and the run RESUMES — hygiene gates validate at the cut version and Step 4 skips promote/stub/bump — instead of false-failing gate 24; a mixed partial bump hard-stops with a recovery pointer.
+- **adia-release `dispatch-publish.mjs --verify-triggered` is conclusion-aware and registry-gated (gh#763).** The verify used to count ANY run for the tag as "triggered" — after the v0.8.29 runner-starvation wave stamped 5 publish runs `cancelled`, it would have reported all 13 packages fine and refused to re-dispatch the dead ones. Now: a run satisfies the check only on `conclusion: success`; in-progress/queued runs get a bounded wait (6 × 20s rechecks); cancelled/failed/timed-out runs and missing runs are re-dispatch candidates. Every re-dispatch is additionally gated behind `npm view <pkg>@<version>` — a version already on the registry is published regardless of run conclusion (the v0.8.29 compose run published, then got stamped cancelled by the 10m job clock), so re-dispatching over it would only 403. Registry remains the final arbiter; workflow conclusions are explicitly not publish truth. Selftest extended with negative controls for both the run-classification and the registry-gate decision tables.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (13 file(s), e.g. `adia-author/SKILL.md`) — carried by the entries above.
+
+## [0.8.31] — 2026-08-07
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.31 work shipped in post-0.8.30 fix wave: double-submit boundaries, list-item render gate, segmented allow-empty + adapter kebab-case booleans, MCP multi-session + idle TTL, feedback signal:none, swatch auto-contrast, tabs strip-gap spacing + vertical clearance. See `packages/web-components/CHANGELOG.md#0831--2026-08-07` for details.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+
 ## [0.8.30] — 2026-08-07
 
 ### Maintenance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.30",
+  "version": "0.8.32",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/adia-author/SKILL.md

@@ -41,15 +41,13 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 | Contract / token / lifecycle drift audit on an existing component | [token-contract.md](references/token-contract.md) + [anti-patterns.md](references/anti-patterns.md) |
 | Demo for a composite/module — any `packages/web-modules/**/*.{examples,contents}.html` | [composite-demo-protocol.md](references/composite-demo-protocol.md) — NOT the primitive or promotion paths; they lack the canonical-survey discipline |
 | Convention question ("is this idiomatic?") | [code-style.md](references/code-style.md) — cite the rule, don't expand it inline |
+| Trait detail page (`site/pages/traits/<name>/`) | [trait-pages.md](references/trait-pages.md) — the ADR-0019 required-section template (traits are this skill's charter; adia-site-docs does not own `traits/`) |
 
-Depth references, loaded only when an entry reference cross-links them:
-[api-contract.md](references/api-contract.md) ·
-[css-patterns.md](references/css-patterns.md) ·
-[lifecycle-patterns.md](references/lifecycle-patterns.md) ·
-[yaml-contract.md](references/yaml-contract.md) ·
-[canonical-pattern-index.md](references/canonical-pattern-index.md) ·
-[common-gotchas.md](references/common-gotchas.md) ·
-[worked-example.md](references/worked-example.md).
+Full retrieval map — one line per reference file, grouped by axis:
+[references/INDEX.md](references/INDEX.md). Depth references (api-contract,
+css-patterns, lifecycle-patterns, yaml-contract, canonical-pattern-index,
+common-gotchas, worked-example) load only when an entry reference or the
+INDEX cross-links them.
 
 The `demo-postwrite-pattern-gate` hook enforces the demo `Pattern source:`
 citation mechanically on every web-modules demo write; the

package/skills/adia-author/references/INDEX.md

@@ -0,0 +1,41 @@
+# adia-author references — retrieval map
+
+One line per file: `path — the question it answers`. Load this first; load
+files on demand from it. Axes are topical (no severity ranking applies).
+The skill body's task-shape table routes entry asks; this map covers every
+file, including the depth references those entries cross-link.
+
+## Authoring lifecycle
+
+- [primitive-audit.md](primitive-audit.md) — does the primitive I'm about to build already exist? The mandatory §0 affordance-by-affordance audit before ANY new component.
+- [authoring-cycle.md](authoring-cycle.md) — what are the 5 steps to author a new primitive or modify an existing one, and which rules are non-negotiable?
+- [worked-example.md](worked-example.md) — what does a finished primitive look like end to end? Two annotated builds: `<badge-ui>` (presentation) and `<counter-ui>` (form-associated).
+
+## Contracts (API · yaml · tokens · CSS · lifecycle)
+
+- [api-contract.md](api-contract.md) — how do I declare `static properties` (type, default, reflect, attribute) and avoid the `attr:` silent-typo trap?
+- [yaml-contract.md](yaml-contract.md) — what fields does the `<name>.yaml` SoT take, and how does it feed the generated `.a2ui.json` sidecar?
+- [token-contract.md](token-contract.md) — is this component's CSS honoring the two-block `@scope` token contract, and why does it misrender under a theme?
+- [css-patterns.md](css-patterns.md) — how do I structure a component stylesheet: two-block `@scope`, variants vs modes, token layering?
+- [lifecycle-patterns.md](lifecycle-patterns.md) — how do I keep `connected()`/`disconnected()` symmetric for listeners, timers, observers, and popovers?
+
+## Shells & modules
+
+- [shell-patterns.md](shell-patterns.md) — how do I author a shell or a bespoke cluster child (`<admin-*>` `<chat-*>` `<editor-*>` `<simple-*>`) per ADR-0023?
+- [module-promotion.md](module-promotion.md) — when and how do I lift a UI block duplicated across consumers into a shared `packages/web-modules/` element (the 5-phase arc)?
+
+## Demos & doc surfaces
+
+- [composite-demo-protocol.md](composite-demo-protocol.md) — what discipline governs any `packages/web-modules/**` demo edit, beyond what the `Pattern source:` gate can see?
+- [canonical-pattern-index.md](canonical-pattern-index.md) — which canonical `.contents.html` files should I survey for a given UI type? Auto-generated; regenerate via `scripts/build-canonical-pattern-index.mjs`.
+- [trait-pages.md](trait-pages.md) — which sections, in which order, must a `site/pages/traits/<name>/` detail page carry (ADR-0019 template)?
+
+## Conventions & failure catalog
+
+- [code-style.md](code-style.md) — is this idiomatic AdiaUI? The conventions (`<*-ui>` elements, tokens, layout primitives) and the working feature each protects.
+- [anti-patterns.md](anti-patterns.md) — what named mistake shapes (AP-##) has the coherence audit already caught, so I don't repeat them?
+- [common-gotchas.md](common-gotchas.md) — which authoring traps render broken without console errors: CSS/composition layering (§§1–5), async-lifecycle races (§6), regeneration ordering (§7)?
+
+## Historical
+
+- [llm-bridge.md](llm-bridge.md) — superseded 2026-07-18 pointer: `@adia-ai/llm` internals belong to `adia-llm-internals`; kept only to redirect.

package/skills/adia-author/references/anti-patterns.md

@@ -597,6 +597,30 @@ disconnected() {
 
 ---
 
+## Registration / Composition
+
+### AP-R1 · Cross-primitive `import` inside a primitive's `.js`
+
+```javascript
+// ❌ input.js
+import '../button/button.js';
+import '../icon/icon.js';
+```
+
+Each primitive's `.js` registers ONLY its own `customElements.define()`. Composition is the **consumer's** responsibility, never the producer's: demo shells, consumer apps, and barrel-using packages import every primitive a fragment uses explicitly, or take the full barrel (`import '@adia-ai/web-components'`).
+
+Three load-bearing arguments:
+
+1. **The composition graph is dynamic.** `<input-ui>` stamps `<button-ui>` + `<icon-ui>` only when `type="number"`; static ES modules have no conditional import, so a producer-side import makes every plain-text-input consumer pay the stepper's bundle cost. Bundle size would couple to the compose-graph instead of the usage graph.
+2. **The full barrel exists.** Consumers who don't want to think about composition import the barrel; piecemeal importers have opted into caring about bundle size, so explicit is the right tradeoff for them.
+3. **The silent failure has a one-liner detector.** An unregistered composed tag renders as an inert `HTMLUnknownElement` with no console error; probe with `customElements.get('button-ui')` (the `smoke:consumers` sweep spot-checks registration).
+
+If you author a primitive that programmatically creates another (`document.createElement('button-ui')`, or via `innerHTML`/template strings), verify its demo shell `<x>.html` imports each composed primitive explicitly.
+
+Source: ADR-0027.
+
+---
+
 ## Rapid-fire anti-patterns (mined from incident history)
 
 One line each; every entry is a shipped bug or a CRITICAL gate. Same axes as above, too small for a full entry.

package/skills/adia-author/references/api-contract.md

@@ -203,3 +203,18 @@ render() {
 ```
 
 Rule of thumb: if CSS can do the work via an attribute selector (`:scope[disabled] { ... }`), prefer CSS. Reserve `render()` for propagating state into child inputs, recalculating positions, or reflecting data changes that attribute selectors can't express.
+
+## Popover `placement` defaults — picked by popover-to-trigger width ratio
+
+Every popover-bearing primitive exposes a consumer-overridable `placement` attribute (declare it in the yaml SoT, with the default documented in the prop description). The DEFAULT is selected by the popover's natural width relative to its trigger — never by component identity:
+
+| Case | Default |
+|---|---|
+| Popover ≈ trigger width (≤ ~1.5×; listboxes / action menus, anything that `matchWidth`s the trigger) | `bottom-start` |
+| Popover materially wider than trigger (calendar grids, date/time/color pickers, filter panels) | `bottom` (centered) |
+| Trigger sits at a container's right edge **by construction** (toolbar spillover, right-pinned "more") | `bottom-end` |
+| Non-bottom-axis surfaces | component-specific: `tooltip-ui` → `top`, `nav-group-ui` collapsed flyout → `right` |
+
+Rationale: `bottom-start` on a wide popover under a right-anchored trigger fires `anchor.js`'s right-edge overflow recovery, snapping the panel far past the trigger's left edge (the v0.6.35 date-range-picker incident — ~800px panel under a ~280px button). Centered `bottom` shifts at most half the overflow distance. Classification is done once at authoring time; borderline cases resolve by what the popover *wants*: if it `matchWidth`s the trigger it is trigger-width regardless of absolute size. "The consumer placed their button on the right of the layout" is a call-site `placement="bottom-end"` override, never a default. The overflow-recovery logic in `anchor.js` is the safety net and stays unchanged — the default's job is to make recovery rarely fire.
+
+Source: ADR-0034.

package/skills/adia-author/references/css-patterns.md

@@ -355,6 +355,25 @@ When a card-like container (drawer-ui, pane-ui, full-height cards) needs a heade
 
 **Gotcha:** the sticky background must be opaque. If the header is transparent, content scrolls visibly underneath. Match the sticky element's `background` to the panel's `--*-bg` token.
 
+## Cascade layers — precedence is declared once, never fought per-rule
+
+`styles/index.css` declares the single ordered list, before any layered rule:
+
+```css
+@layer reset, tokens, elements, components, utilities, context, overrides;
+```
+
+The precedence law: a later layer beats an earlier layer **regardless of selector specificity**; within a layer, normal specificity applies. Component `@scope` rules live inside `@layer components` — `@scope` sets proximity *inside* the layer, `@layer` sets inter-group order; they compose, they are not substitutes.
+
+Consequences for component authors:
+
+- **Consumer overrides always win** — unlayered consumer CSS, or `@layer overrides`, beats everything by layer order. Never add `:where()` wraps, matched-specificity selectors, or `!important` to "let the consumer win"; the layer order already guarantees it.
+- **Utilities beat component defaults by layer order.** The global attribute API (`api/*`) sits in `utilities`, so a component cannot out-specific it — a component repurposing a global attribute (e.g. `color=` on a filled control) must opt out explicitly (see the `[color]`/`[weight]` trap below).
+- **`@layer` governs rule precedence only.** The `var()` token chains (token indirection), genuine element-default `:where()`s, and allowlisted a11y `!important`s serve other mechanisms and are not retired by layers.
+- `npm run check:cascade-layers` gates the model: canonical order declared once, `!important` ≤ allowlist, no precedence-`:where()` in layered files.
+
+Source: ADR-0038.
+
 ## Raw-CSS traps (mined from incident history)
 
 One line each; every entry is a shipped bug.

package/skills/adia-author/references/lifecycle-patterns.md

@@ -291,6 +291,26 @@ disconnected() {
 
 Especially important for components that are attached/detached frequently (modals, toasts, drawers) — each incarnation leaks its old subtree into memory if refs aren't released.
 
+## Adopt-or-stamp — slot content is the source of truth
+
+Every slot-bearing primitive that exposes both an attribute and a slot for the same logical content (`text=` + `<span slot="text">`) follows the `#stampMark` / `#wasStamped` policy (working reference: `list-item-ui`, `packages/web-components/components/list/list.js`):
+
+1. `connected()` either **adopts** the consumer-authored slotted child or **stamps** a new one, tagging it `data-{component}-stamped`.
+2. `render()` may only mutate or remove elements carrying the stamp. An unstamped slotted child is consumer-owned — leave it alone, even when the matching attribute is empty.
+3. The attribute stays a convenience shorthand that produces a stamped element; both forms render identically and are interchangeable.
+
+The failure this prevents: a `render()` that overwrites `textContent` from the attribute, or hides/removes the slot element when the attribute is empty, silently destroys consumer-authored rich content (links, `<strong>`, inline icons). A 13-page audit found 73 slot uses where the slotted form is the only way to author the intended content (the destructive render() confirmed in 3 primitives) before the policy landed — from the page author's seat it looks like "the docs are broken", from the component author's seat like "the consumer didn't pass the attribute"; both are wrong-blame. Source: ADR-0010.
+
+### `slot="caret"` — the one disclosure-indicator slot
+
+The expand/collapse (and dropdown) directional-indicator slot is named `caret` on every primitive that exposes composition slots (`tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`). `chevron` is retired — a hard rename with no compat alias, and `--*-chevron-*` tokens became `--*-caret-*` (Phosphor names the glyphs `caret-right` / `caret-down`; there is no `chevron-*` icon).
+
+- The mechanism is adopt-or-stamp (above): honor a declarative `<… slot="caret">` child if present, else stamp `<icon-ui slot="caret" name="caret-right">`. The same adopt-or-stamp rule applies to **every** composition slot the stamp builds (e.g. `slot="actions"`).
+- Rotation is driven by host open-state CSS (`:scope[open]` / `[collapsed]` / `[expanded]`) — never by swapping the icon name.
+- Internal-render components with no composition slots (`agent-trace`, `agent-reasoning`) keep `[data-*-caret]` styling hooks — the convention governs slots, not internal hooks.
+
+Source: ADR-0036.
+
 ## Anti-patterns to watch for
 
 - **Inline arrow + `removeEventListener`** — the listener isn't really being removed. Silent leak.

package/skills/adia-author/references/token-contract.md

@@ -89,7 +89,7 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 
 If you find a raw value elsewhere, either:
 
-- Fix it by adding a proper token at `packages/web-components/styles/tokens.css`
+- Fix it by adding a proper token in the owning `styles/` dimension×layer file (see "Where foundation styles live" below — `tokens.css` is a compat barrel, not a home)
 - Or document the exemption in `.claude/docs/specs/component-token-contract.md`
 
 ## Chrome token palette
@@ -107,6 +107,20 @@ Added in v0.5.0 — use these for UI chrome:
 
 For charts, stat colors, category markers — use `--a-data-0` through `--a-data-9`. Do NOT hardcode chart colors.
 
+## Where foundation styles live — dimension × layer
+
+Every file under `packages/web-components/styles/` answers two questions — which *dimension* (color · type · space · size · radius · motion · elevation) and which *layer* (primitive → semantic → role → element → attribute-API → context → reset) — and declares its cell with a machine-readable header tag `adia:<layer>/<dimension>`. When adding or moving a declaration:
+
+- Spatial / size / radius / motion / elevation primitives → `styles/foundation/` (one file per dimension)
+- Type scale (L1/L2), roles (L3), native-element defaults → `styles/type/`
+- Color layers → `styles/colors/` (parameters · primitives-* · surfaces · scrims · semantics/*)
+- The global attribute API (`[size]` `[density]` `[gap]` `[padding]` `[margin]` …) → `styles/api/{sizing,text,layout}.css` — the ONLY home for global `[attr]` selectors
+- `tokens.css`, `typography.css`, `colors/semantics.css`, etc. remain **compat barrels** at their public paths — they only `@import`; never add declarations to them
+
+Enforced by `scripts/release/check-foundation-layer-placement.mjs` (wired into `npm run check`): header tags present, primitive files free of attribute selectors, the attribute API confined to `api/`, no orphan files. Import order inside `colors/semantics/` is load-bearing (`aliases.css` last) and asserted in file headers.
+
+Source: ADR-0035.
+
 ## When to update this reference
 
 If you add a new token category (like `--a-chrome-*` was added), update both this file and `.claude/docs/specs/component-token-contract.md`. The spec doc is the live source of truth; this file is the practitioner's checklist.

package/skills/adia-author/references/trait-pages.md

@@ -0,0 +1,38 @@
+# Trait Detail Pages — the required template
+
+Every trait detail page under `site/pages/traits/<name>/` follows one binding section template. The 41-page Phase B sweep proved what a loose contract produces: bimodal quality (portfolio-grade pages next to abstract-box demos) and zero pages teaching restraint. Navigate-by-template is the contract. Source: ADR-0019.
+
+Trait pages are this skill's charter (traits live in `packages/web-components/traits/`); `adia-site-docs` owns `site/pages/{architecture,getting-started,guides,patterns,reference}` — not `traits/`.
+
+## Required sections, in order
+
+| # | Section (`data-property=`) | Required? | Purpose |
+|---|---|---|---|
+| 1 | `<header>` | always | `<h1>` trait name + `<tag-ui>trait</tag-ui>` + category tag matching `_catalog.json` SoT |
+| 2 | `hero` | always | "In context" demo with real product chrome — no abstract boxes |
+| 3 | `minimal` | always | Single-tag declarative usage; `<h2>` reads "Bare minimum" |
+| 4 | `declarative` | always | `<X traits="trait-name">` code-ui block |
+| 5 | `config` | conditional | Only when the trait declares `config` attrs in `defineTrait()`; live sliders + readouts |
+| 6 | `reduced-motion` | motion-only | Toggleable `prefers-reduced-motion: reduce` degradation demo. Required for any trait touching transform / opacity / animation |
+| 7 | `accessibility` | always | 1–3 bullets on pointer-only, touch-confused, AT-silent reality |
+| 8 | `performance` | always | 1 sentence on rAF cost, observer count, listener cost |
+| 9 | `when-not-to-use` | always | 2–4 opinionated bullets on overuse, audience-mismatch, perf cost |
+| 10 | `api` | always | Auto-stamped from `_api-table.js` |
+| 11 | `composes` | always | ≥ 1 trait demonstrated in a WORKING composition; ≥ 4 traits listed |
+
+Trait-specific extras (`state`, `lifecycle`, scenario `usage` recipes) slot between `config` (5) and `accessibility` (7).
+
+## Naming and sourcing rules
+
+- `data-property` values are lowercase hyphen-separated tokens; canonical set as in the table. **`minimal`, not `bare`.**
+- `data-artifact-label` values are lowercase descriptive prose ("settle log") OR code-shaped strings describing the demo axis (`speed=120 (slow, dramatic)`). HTML-entity escapes inside attribute values are correct.
+- Header category tag MUST match the trait's `category` in `packages/web-components/traits/_catalog.json` — catalog SoT, never page-author judgment.
+- Imports in code-ui blocks use the full package name `@adia-ai/web-components/traits` — never internal aliases like `@traits/index.js`.
+- Inline-style tokens use canonical names: `--a-border` (dashed borders), `--a-radius-md` / `--a-radius-lg`, `--a-accent` / `--a-accent-fg`.
+
+## The two teeth
+
+- **`when-not-to-use` is the highest-impact section.** A page shipping without it defaults to "this trait is good, please use it" — wrong for every trait once overuse, density, or a11y tradeoffs enter. The restraint mandate is the pedagogy differentiator (Motion / GSAP / React Spring all whiff on it). Fewer than 2 bullets requires an articulated why.
+- **Composes must SHOW.** Listing trait names with prose-only descriptions does not satisfy the contract — at least one composition runs as a working demo.
+
+No mechanical gate enforces this template yet (ADR-0019's verify-trait-pages.mjs was deferred and does not exist) — the 11-section contract is enforced at PR review. Source: ADR-0019.

package/skills/adia-release/SKILL.md

@@ -95,7 +95,7 @@ assumed pass, or "published" without the actual `npm view` output.
 
 `release-pack.mjs` walks the cycle in two phases per invariant 3 — `--mode cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now — a peer's hand-authored section must be promoted whichever mode cut it, and a loud guard blocks the bump if any roster package still carries non-empty `[Unreleased]` content after promotion), run Step 4f (pre-tag coverage `--fix` with the authoritative F-N1 matcher), and stop at the release commit (PR → merge); `--mode handoff` tags/publishes/deploys from post-merge main. **`--go` is the standard invocation for an operator-initiated release** — the single authorization covers the cycle; evidence blocks print as a log; granular `--yes`/`--push`/`--publish` remain for cautious manual runs (`--push` still refuses to auto-fire past any F-N1 finding). `--mode batch` is not implemented — it hard-rejects with a pointer to [`recovery-paths.md`](references/recovery-paths.md) §Scenario 2 rather than silently misbehaving; a real batch tags each version at its own release-merge SHA, which this single-version orchestrator has no model for. Pre-flight (Step 3) runs the full 24-gate roster from the single shared list in `scripts/gate-roster.mjs` — the same list [`cut-procedure.md`](references/cut-procedure.md) §3.1 transcribes, so a subset run requires editing that one file, not two.
 
-The pieces are callable alone: `bump.mjs` (version fields + the factory `.mcp.json` a2ui-mcp pin, invariant 8), `promote-unreleased.mjs` / `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (12 tags, `--delete` to move), `dispatch-publish.mjs` (publish workflows; `--verify-triggered` re-dispatches only missing runs; `--after` enforces batch ordering — dispatch output states what WAS done, never a to-do phrased as if it hadn't fired), and `pr-bridge.mjs` (the two-phase bridge: pushes the release branch, opens the PR, waits out CI, and merges ONLY on all-non-fail-soft-checks-green + zero unresolved threads + no changes-requested; any other state stops with evidence — §5.7 mechanized, `--dry` to preview the decision). All fail fast outside a monorepo root (`assert-monorepo-root.mjs`); fork-configurable via `--host` / `--scope`. All 6 CLI scripts (plus `scripts/release/check-release.mjs`) have a `selftest` mode wired into CI's Plugin bin selftests step; the 3 helper modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are exercised through the CLIs' selftests, not their own.
+The pieces are callable alone: `bump.mjs` (version fields + the factory `.mcp.json` a2ui-mcp pin, invariant 8), `promote-unreleased.mjs` / `insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (12 tags, `--delete` to move), `dispatch-publish.mjs` (publish workflows; `--verify-triggered` re-dispatches missing AND dead — cancelled/failed/timed-out — runs, each gated behind an npm-registry check so an already-published version is never re-dispatched (gh#763); `--after` enforces batch ordering — dispatch output states what WAS done, never a to-do phrased as if it hadn't fired), and `pr-bridge.mjs` (the two-phase bridge: pushes the release branch, opens the PR, waits out CI, and merges ONLY on all-non-fail-soft-checks-green + zero unresolved threads + no changes-requested; any other state stops with evidence — §5.7 mechanized, `--dry` to preview the decision). All fail fast outside a monorepo root (`assert-monorepo-root.mjs`); fork-configurable via `--host` / `--scope`. All 6 CLI scripts (plus `scripts/release/check-release.mjs`) have a `selftest` mode wired into CI's Plugin bin selftests step; the 3 helper modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are exercised through the CLIs' selftests, not their own.
 
 Site deploy (Step 10 of the handoff) dispatches `deploy-site.yml` (its own pre-flight verify → snapshot → hardened rsync → post-deploy verify → auto-rollback), never a raw local `rsync` — H1 (forge-campaign gh#268 audit): the script had drifted into bypassing that pipeline even though this doc already taught the workflow-dispatch path. The dispatch rides the cycle's single authorization (`--go`, or `--publish` on a manual run); the workflow's own GitHub environment gate is the human stop for the deploy itself.
 

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

@@ -148,20 +148,36 @@ tag-creation/tag-push/publish-dispatch commands until it passes, and
 shipped tarballs with unpromoted `[Unreleased]` CHANGELOG headers because
 this class of check ran only after tagging).
 
-**4-resume. Resuming a cut that died mid-Step-4** (v0.8.10 hit this live):
-`release-pack.mjs` always re-runs the FULL sequence from Step 1, and
-`promote-unreleased.mjs` hard-errors on already-promoted packages ("already
-has ## [X.Y.Z]") — so once ANY promotion has landed, re-invoking the
-orchestrator can never get past Step 4. That error is the idempotency guard
-working, not a corrupted state. Do NOT hand-edit CHANGELOGs back to
-`[Unreleased]` to appease it. Instead, verify the promotion state with the
-authoritative gate — `node scripts/release/check-release-docs.mjs --version
-X.Y.Z` covers every lockstep package (including the nested `a2ui/*` and
-`plugins/*` paths a shallow `packages/*` glob misses) and fails on any
-leftover `[Unreleased]` content or missing `[X.Y.Z]` heading; it will still
-flag the not-yet-generated `docs/releases/vX.Y.Z.md`, which 4e below creates.
-Then run the remaining steps as the standalone pieces the Mechanization
-section already names, in this order:
+**4-resume. Resuming a cut that died mid-Step-4** (v0.8.10 and v0.8.29 hit
+this live). Two shapes, told apart by the lockstep versions — `release-pack.mjs`
+checks them itself at startup (gh#765):
+
+- **Complete bump (all 13 `package.json` versions at the cut version):**
+  just RE-RUN the same `release-pack.mjs` command. It detects the half-cut
+  tree before the pre-flight, prints a `[resume]` banner, validates the
+  hygiene gates at the CUT version (no more gate-24 false-fail at the
+  previous version), and skips promote/stub/bump in Step 4 — re-running only
+  the idempotent substeps (lockfile, catalog, 4e notes, 4f coverage, 4g
+  hygiene) and continuing to Step 5. The `promote-unreleased.mjs`
+  "already has ## [X.Y.Z]" hard-error can no longer be reached on this path.
+  Do NOT hand-edit CHANGELOGs back to `[Unreleased]` first — the resumed run
+  expects the promoted state and re-proves it with the
+  unpromoted-`[Unreleased]` guard.
+- **Mixed versions (some packages bumped, some not — a mid-bump abort):**
+  the orchestrator hard-stops listing the stragglers and will neither resume
+  nor roll back. Recover by hand: restore the tree (`git status` /
+  `git checkout -- <files>`, or finish the bump with `bump.mjs` directly),
+  then re-run. To verify the promotion state along the way, the
+  authoritative gate is `node scripts/release/check-release-docs.mjs
+  --version X.Y.Z` — it covers every lockstep package (including the nested
+  `a2ui/*` and `plugins/*` paths a shallow `packages/*` glob misses) and
+  fails on any leftover `[Unreleased]` content or missing `[X.Y.Z]` heading;
+  it will still flag the not-yet-generated `docs/releases/vX.Y.Z.md`, which
+  4e creates.
+
+The fully manual fallback (both shapes, if the orchestrator itself is
+suspect) remains the standalone pieces the Mechanization section names, in
+this order:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/bump.mjs" --from X.Y.Z-1 --to X.Y.Z   # 4b
@@ -300,7 +316,7 @@ Log the current registry snapshot (per-package versions + `dist-tags.latest`) be
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
-  --version X.Y.Z --verify-triggered     # re-dispatches only missing runs
+  --version X.Y.Z --verify-triggered     # re-dispatches missing/dead runs; registry-gated (gh#763)
 ```
 
 Wait for the workflows to settle, then verify against the **registry**, never the workflow's green check:

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

@@ -71,7 +71,7 @@
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/dispatch-publish.mjs" \
-  --version X.Y.Z --verify-triggered   # re-dispatches ONLY packages with no run; idempotent
+  --version X.Y.Z --verify-triggered   # re-dispatches packages with no run OR a dead (cancelled/failed/timed-out) run; registry-gated; idempotent
 ```
 
 For a batch, preserve npm-latest ordering (`--after <prev>`). Verify against the registry, not the workflows. **Prevention:** push tags one-at-a-time ([`cut-procedure.md`](cut-procedure.md) §Step 8); `` `${CLAUDE_PLUGIN_ROOT}/skills/adia-release/scripts/release-pack.mjs` `` does this automatically and follows with `--verify-triggered`.

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

@@ -17,7 +17,7 @@
 // Part of the adia-release skill. Mechanizes the dispatch loop
 // + handles the npm-latest ordering rule for batch pushes.
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import process from 'node:process';
 import { assertMonorepoRoot } from './assert-monorepo-root.mjs';
 import { PACKAGE_NAMES } from './package-paths.mjs';
@@ -49,10 +49,14 @@ function parseArgs(argv) {
       console.log('--after            Verify npm latest is at the given version before dispatching this one.');
       console.log('                   Used in batch push to ensure publish ordering.');
       console.log('--verify-triggered Instead of dispatching, check whether each per-package publish-<pkg>.yml');
-      console.log('                   ALREADY has a run for the <pkg>-vX.Y.Z tag (i.e. push-on-tag fired), and');
-      console.log('                   re-dispatch ONLY the misses. This is the recovery for the batch-tag-push');
-      console.log('                   skip (recovery-paths.md §Scenario 7) — a single `git push <12 tags>` can');
-      console.log('                   trigger ZERO publish workflows. Idempotent: re-dispatches nothing if all 11 fired.');
+      console.log('                   has a SUCCESSFUL run for the <pkg>-vX.Y.Z tag, and re-dispatch the misses.');
+      console.log('                   Conclusion-aware (gh#763): a cancelled/failed/timed-out run is a miss, not');
+      console.log('                   a pass; in-progress/queued runs get a bounded wait. Every re-dispatch is');
+      console.log('                   gated behind an npm-registry check — if <pkg>@<version> is already on the');
+      console.log('                   registry the publish succeeded regardless of run conclusion (a run can');
+      console.log('                   publish, then be stamped cancelled by the job clock), and re-dispatching');
+      console.log('                   would only 403. Covers the batch-tag-push skip (recovery-paths.md');
+      console.log('                   §Scenario 7) AND dead runs from runner starvation. Idempotent.');
       console.log(`--scope            npm scope the packages publish under (default: ${DEFAULT_SCOPE};`);
       console.log('                   or set $ADIA_NPM_SCOPE). The --after npm-latest check uses this scope.');
       process.exit(0);
@@ -65,18 +69,23 @@ function parseArgs(argv) {
   return args;
 }
 
-function run(cmd, dry) {
+// All gh/npm invocations go through execFileSync with ARGUMENT ARRAYS —
+// never a shell string. --version/--scope are CLI-attacker-controlled;
+// interpolating them into a shell command is command injection (PR #774
+// review). `run` logs a printable form in dry mode and execs the array.
+function run(bin, argv, dry, opts = {}) {
+  const printable = `${bin} ${argv.join(' ')}`;
   if (dry) {
-    console.log(`  [dry] ${cmd}`);
+    console.log(`  [dry] ${printable}`);
     return '';
   }
-  return execSync(cmd, { encoding: 'utf8' });
+  return execFileSync(bin, argv, { encoding: 'utf8', ...opts });
 }
 
 function checkAfter(afterVersion, scope) {
   console.log(`Checking npm latest is at ${afterVersion} before dispatching...`);
   try {
-    const latest = execSync(`npm view ${scope}/web-components dist-tags.latest`, { encoding: 'utf8' }).trim();
+    const latest = run('npm', ['view', `${scope}/web-components`, 'dist-tags.latest'], false).trim();
     if (latest !== afterVersion) {
       console.error(`error: npm ${scope}/web-components latest is '${latest}', expected '${afterVersion}'`);
       console.error('  This means the previous batch hasn\'t completed publishing.');
@@ -92,9 +101,8 @@ function checkAfter(afterVersion, scope) {
 
 function dispatch(pkg, version, dry) {
   const ref = `${pkg}-v${version}`;
-  const cmd = `gh workflow run "publish-${pkg}.yml" --ref "${ref}"`;
   try {
-    const out = run(cmd, dry);
+    const out = run('gh', ['workflow', 'run', `publish-${pkg}.yml`, '--ref', ref], dry);
     if (!dry && out) {
       const url = out.split('\n').find((l) => l.startsWith('http')) || '';
       console.log(`  ✓ dispatched ${pkg} (${url.trim()})`);
@@ -114,53 +122,163 @@ async function sleep(ms) {
   return new Promise((res) => setTimeout(res, ms));
 }
 
-// Has publish-<pkg>.yml already run for the <pkg>-vX.Y.Z tag? Tag-triggered runs
+// Classify a run's {status, conclusion} into what --verify-triggered should do
+// with it. Pure — selftest exercises it with negative controls.
+//   'success' — completed + success: the publish run is satisfied.
+//   'pending' — queued / in_progress / waiting / requested: recheck (bounded wait).
+//   'dead'    — completed but NOT success (cancelled / failure / timed_out /
+//               skipped / anything unknown): re-dispatch candidate. gh#763: the
+//               v0.8.29 starvation wave stamped runs `cancelled` — one of them
+//               had already published to npm, which is why every re-dispatch is
+//               additionally gated behind the registry check below.
+function classifyRun(status, conclusion) {
+  if (status !== 'completed') return 'pending';
+  return conclusion === 'success' ? 'success' : 'dead';
+}
+
+// Latest run of publish-<pkg>.yml for the <pkg>-vX.Y.Z tag. Tag-triggered runs
 // report the tag in the `headBranch` field, so we filter the run list by it.
-// Returns true if at least one run exists for that tag, false otherwise.
+// Returns 'none' | 'success' | 'pending' | 'dead' | 'unknown' — existence
+// alone is NOT satisfaction (gh#763: a cancelled run used to count as
+// "triggered"), and a FAILED QUERY is NOT verified absence (PR #774 review:
+// fail-open here read a gh rate limit as "no run" and re-dispatched over a
+// possibly in-flight publish).
 function triggeredForTag(pkg, version, dry) {
   const tag = `${pkg}-v${version}`;
-  const cmd = `gh run list --workflow="publish-${pkg}.yml" --branch "${tag}" --limit 1 --json databaseId -q '.[0].databaseId // empty'`;
+  const argv = ['run', 'list', `--workflow=publish-${pkg}.yml`, '--branch', tag, '--limit', '1', '--json', 'status,conclusion', '-q', '.[0] // empty'];
   if (dry) {
-    console.log(`  [dry] ${cmd}`);
-    return false; // dry preview assumes not-triggered so the re-dispatch path is shown
+    console.log(`  [dry] gh ${argv.join(' ')}`);
+    return 'none'; // dry preview assumes not-triggered so the re-dispatch path is shown
   }
   try {
-    const out = execSync(cmd, { encoding: 'utf8' }).trim();
-    return out.length > 0;
+    const out = execFileSync('gh', argv, { encoding: 'utf8' }).trim();
+    if (!out) return 'none'; // gh answered: genuinely zero runs for the tag
+    const run = JSON.parse(out);
+    return classifyRun(run.status, run.conclusion);
   } catch {
-    // gh error (auth / rate limit / missing workflow) — treat as "unknown".
-    // Conservative: report not-triggered so the miss is re-dispatched rather than
-    // silently skipped. A redundant re-dispatch is harmless (publish is idempotent
-    // per the workflow's own guard); a skipped publish is the failure we're fixing.
-    return false;
+    // gh error (auth / rate limit / missing workflow) — we could not observe
+    // the runs. Fail CLOSED: 'unknown' stops the loop with a nonzero result
+    // instead of dispatching blind.
+    return 'unknown';
   }
 }
 
-// The batch-tag-push-skip recovery: verify each per-package publish workflow
-// actually triggered off its pushed tag, and re-dispatch ONLY the misses.
-// Idempotent — re-dispatches nothing if all 11 fired.
-function verifyTriggeredAndRedispatch(version, dry) {
-  console.log(`\nVerifying publish-on-tag triggered for all ${PACKAGES.length} packages (v${version}):`);
+// Registry truth: is <scope>/<pkg>@<version> already published? A workflow
+// run's conclusion is NOT publish truth — the v0.8.29 compose run published
+// successfully, then got stamped `cancelled` by the 10m job clock. If the
+// version is on the registry, the publish succeeded, full stop; re-dispatching
+// would only hit npm's publish-over-published 403.
+// Returns true (published) | false (npm answered: version absent, E404) |
+// null (query FAILED — network/auth; absence NOT verified, fail closed:
+// PR #774 review — a transient npm failure must not re-open the 403).
+function onRegistry(pkg, version, scope, dry) {
+  const argv = ['view', `${scope}/${pkg}@${version}`, 'version'];
+  if (dry) {
+    console.log(`  [dry] npm ${argv.join(' ')}`);
+    return false; // dry preview assumes not-published so the re-dispatch path is shown
+  }
+  try {
+    return execFileSync('npm', argv, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim() === version;
+  } catch (e) {
+    const stderr = `${e.stderr || ''}`;
+    if (stderr.includes('E404') || stderr.includes('404 Not Found')) return false; // definitive: not published
+    return null; // npm/network error — absence unverified
+  }
+}
+
+// What to do with a package whose latest run is not a clean success, given
+// registry truth (`published`: true | false | null-unverified). Pure —
+// selftest proves the 403-avoidance and fail-closed invariants here.
+//   published === true → 'satisfied'  — npm has the version; the publish
+//                        succeeded whatever the run conclusion says. NEVER
+//                        re-dispatch over an already-published version (403).
+//   either query failed→ 'unknown'    — run state or registry state was NOT
+//                        observed (rate limit, network). Fail closed: stop
+//                        with a nonzero result, never dispatch blind.
+//   pending, absent    → 'wait'       — a run may still be publishing; do not
+//                        race it with a second dispatch.
+//   dead/none, absent  → 'redispatch' — no run, or a cancelled/failed/
+//                        timed-out one, and the registry lacks the version.
+function decidePackage(state, published) {
+  if (published === true) return 'satisfied';
+  if (state === 'unknown' || published === null) return 'unknown';
+  if (state === 'pending') return 'wait';
+  return 'redispatch';
+}
+
+// Bounded wait for in-progress/queued runs before judging them: a healthy
+// publish run finishes in ~30s; 6 × 20s covers a slow queue without stalling
+// the recovery loop forever.
+const PENDING_RECHECKS = 6;
+const PENDING_RECHECK_SECONDS = 20;
+
+// The publish-run recovery: verify each per-package publish workflow has a
+// SUCCESSFUL run for its tag (batch-tag-push skip AND dead runs — cancelled /
+// failed / timed_out, e.g. runner starvation), wait out in-progress runs, and
+// re-dispatch only true misses — never over a version the registry already has.
+// Idempotent — re-dispatches nothing if all publishes landed.
+async function verifyTriggeredAndRedispatch(version, scope, dry) {
+  console.log(`\nVerifying publish-on-tag succeeded for all ${PACKAGES.length} packages (v${version}):`);
+  let pending = PACKAGES;
+  const unresolved = new Map(); // pkg → state, after the bounded wait
+  for (let attempt = 0; attempt <= PENDING_RECHECKS && pending.length > 0; attempt++) {
+    if (attempt > 0) {
+      console.log(`  … ${pending.length} run(s) still pending — recheck ${attempt}/${PENDING_RECHECKS} in ${PENDING_RECHECK_SECONDS}s`);
+      await sleep(PENDING_RECHECK_SECONDS * 1000);
+    }
+    const stillPending = [];
+    for (const pkg of pending) {
+      const state = triggeredForTag(pkg, version, dry);
+      if (state === 'success') {
+        console.log(`  ✓ ${pkg} — successful publish run for ${pkg}-v${version}`);
+      } else if (state === 'pending' && attempt < PENDING_RECHECKS && !dry) {
+        stillPending.push(pkg);
+      } else {
+        unresolved.set(pkg, state);
+      }
+    }
+    pending = stillPending;
+  }
+
+  // Registry gate: for every non-success, npm is the arbiter — already
+  // published → satisfied regardless of run conclusion; absent → re-dispatch.
   const misses = [];
-  for (const pkg of PACKAGES) {
-    if (triggeredForTag(pkg, version, dry)) {
-      console.log(`  ✓ ${pkg} — publish run found for ${pkg}-v${version}`);
+  for (const [pkg, state] of unresolved) {
+    const decision = decidePackage(state, onRegistry(pkg, version, scope, dry));
+    if (decision === 'satisfied') {
+      console.log(`  ✓ ${pkg} — run state '${state}' but ${scope}/${pkg}@${version} IS on the registry → published, no re-dispatch`);
+    } else if (decision === 'unknown') {
+      console.log(`  ! ${pkg} — run or registry state could NOT be observed (gh/npm query failed) → NOT dispatching blind; fix gh/npm access and re-run --verify-triggered`);
+      misses.push({ pkg, redispatch: false });
+    } else if (decision === 'wait') {
+      console.log(`  ? ${pkg} — run still pending after bounded wait and not on the registry → NOT re-dispatching over an in-flight run; re-run --verify-triggered once it settles`);
+      misses.push({ pkg, redispatch: false });
     } else {
-      console.log(`  ✗ ${pkg} — NO publish run for ${pkg}-v${version} (batch-push skip) → will re-dispatch`);
-      misses.push(pkg);
+      const why = state === 'none' ? 'NO publish run (batch-push skip)' : 'run cancelled/failed/timed-out';
+      console.log(`  ✗ ${pkg} — ${why} for ${pkg}-v${version}, not on the registry → will re-dispatch`);
+      misses.push({ pkg, redispatch: true });
     }
   }
   if (misses.length === 0) {
-    console.log(`\n[verify-triggered] all ${PACKAGES.length} publish workflows triggered — nothing to re-dispatch.`);
+    console.log(`\n[verify-triggered] all ${PACKAGES.length} publishes verified (successful run or on-registry) — nothing to re-dispatch.`);
     return 0;
   }
-  console.log(`\n[verify-triggered] ${misses.length} miss(es) — re-dispatching via workflow_dispatch:`);
+  const toDispatch = misses.filter((m) => m.redispatch);
   let redispatched = 0;
-  for (const pkg of misses) {
-    if (dispatch(pkg, version, dry)) redispatched++;
+  if (toDispatch.length > 0) {
+    console.log(`\n[verify-triggered] ${toDispatch.length} miss(es) — re-dispatching via workflow_dispatch:`);
+    for (const { pkg } of toDispatch) {
+      if (dispatch(pkg, version, dry)) redispatched++;
+    }
+    console.log(`\n[verify-triggered] re-dispatched ${redispatched}/${toDispatch.length} ${dry ? '(dry)' : ''}`);
+    if (!dry) {
+      console.log('  Registry is the final arbiter — confirm each with:');
+      console.log(`    npm view ${scope}/<pkg>@${version} version`);
+    }
   }
-  console.log(`\n[verify-triggered] re-dispatched ${redispatched}/${misses.length} ${dry ? '(dry)' : ''}`);
-  return redispatched === misses.length ? 0 : 1;
+  const unresolvedCount = misses.length - toDispatch.length;
+  if (unresolvedCount > 0) console.log(`\n[verify-triggered] ${unresolvedCount} package(s) unresolved (run still pending, or gh/npm query failed) — re-run --verify-triggered once they settle / access is restored.`);
+  return redispatched === toDispatch.length && unresolvedCount === 0 ? 0 : 1;
 }
 
 async function main() {
@@ -169,10 +287,11 @@ async function main() {
   assertMonorepoRoot(process.cwd());
   if (args.after) checkAfter(args.after, args.scope);
 
-  // Recovery mode — verify each publish workflow triggered off its pushed tag,
-  // re-dispatch only the misses (the batch-tag-push skip). Skips the blind dispatch.
+  // Recovery mode — verify each publish workflow SUCCEEDED for its pushed tag
+  // (or the version is on the registry), re-dispatch only true misses (batch-
+  // tag-push skip + dead runs, gh#763). Skips the blind dispatch.
   if (args.verifyTriggered) {
-    const rc = verifyTriggeredAndRedispatch(args.version, args.dry);
+    const rc = await verifyTriggeredAndRedispatch(args.version, args.scope, args.dry);
     process.exit(rc);
   }
 
@@ -211,31 +330,75 @@ async function main() {
   if (succeeded !== PACKAGES.length) process.exit(1);
 }
 
-// dry mode never shells out (run()/dispatch() short-circuit before
-// execSync), so this exercises the real functions without touching gh/npm.
-function selftest() {
+// dry mode never shells out (run()/dispatch()/triggeredForTag()/onRegistry()
+// short-circuit before execFileSync), so this exercises the real functions
+// without touching gh/npm.
+async function selftest() {
+  const fail = (msg) => { console.error(`selftest FAIL: ${msg}`); process.exit(1); };
+
   let allOk = true;
   for (const pkg of PACKAGES) {
     if (!dispatch(pkg, '9.9.9', true /* dry */)) allOk = false;
   }
-  if (!allOk) { console.error('selftest FAIL: dry dispatch() reported a failure for at least one package'); process.exit(1); }
+  if (!allOk) fail('dry dispatch() reported a failure for at least one package');
+
+  // classifyRun() — the gh#763 core: conclusion decides, existence does not.
+  if (classifyRun('completed', 'success') !== 'success') fail("classifyRun(completed,success) must be 'success'");
+  // Negative controls: the exact states the v0.8.29 starvation wave produced
+  // must NOT satisfy the verify — a cancelled run counting as "triggered" is
+  // the defect this script no longer has.
+  for (const dead of ['cancelled', 'failure', 'timed_out', 'skipped', null]) {
+    if (classifyRun('completed', dead) !== 'dead') fail(`classifyRun(completed,${dead}) must be 'dead', never satisfied`);
+  }
+  for (const status of ['queued', 'in_progress', 'waiting', 'requested']) {
+    if (classifyRun(status, null) !== 'pending') fail(`classifyRun(${status}) must be 'pending' (bounded recheck)`);
+  }
+
+  // decidePackage() — the registry gate. Negative controls: the v0.8.29
+  // a2ui-compose shape (run cancelled, version PUBLISHED) must never
+  // re-dispatch — that's the publish-over-published 403.
+  if (decidePackage('dead', true) !== 'satisfied') fail('decidePackage(dead, published) must be satisfied — never re-dispatch over a published version');
+  if (decidePackage('none', true) !== 'satisfied') fail('decidePackage(none, published) must be satisfied');
+  if (decidePackage('pending', true) !== 'satisfied') fail('decidePackage(pending, published) must be satisfied');
+  if (decidePackage('dead', false) !== 'redispatch') fail('decidePackage(dead, absent) must re-dispatch');
+  if (decidePackage('none', false) !== 'redispatch') fail('decidePackage(none, absent) must re-dispatch');
+  if (decidePackage('pending', false) !== 'wait') fail('decidePackage(pending, absent) must wait, never race an in-flight run');
+  // Fail-closed negative controls (PR #774 review): a FAILED query is not
+  // verified absence — 'unknown' must never dispatch. A gh rate limit could
+  // hide an in-flight run; a transient npm failure could hide an
+  // already-published version (the 403 again).
+  for (const state of ['unknown', 'none', 'dead', 'pending']) {
+    if (decidePackage(state, null) !== 'unknown') fail(`decidePackage(${state}, registry-unverified) must be 'unknown' — never dispatch blind`);
+  }
+  for (const published of [false, null]) {
+    if (decidePackage('unknown', published) !== 'unknown') fail(`decidePackage(run-unknown, ${published}) must be 'unknown' — never dispatch blind`);
+  }
+  // Positive registry truth still wins even when the run query failed:
+  if (decidePackage('unknown', true) !== 'satisfied') fail('decidePackage(unknown, published) must be satisfied — registry is the arbiter');
+
+  // triggeredForTag() in dry mode must conservatively report 'none' — the
+  // whole point is re-dispatching misses; silently assuming "triggered"
+  // would let a real miss through.
+  if (triggeredForTag('web-components', '9.9.9', true) !== 'none') {
+    fail("dry triggeredForTag() must report 'none' (conservative default)");
+  }
 
-  // triggeredForTag() in dry mode must conservatively report "not yet
-  // triggered" — verifyTriggeredAndRedispatch's whole point is to re-dispatch
-  // misses; silently assuming "triggered" would let a real miss through.
-  if (triggeredForTag('web-components', '9.9.9', true) !== false) {
-    console.error('selftest FAIL: dry triggeredForTag() must report false (conservative default)'); process.exit(1);
+  // onRegistry() in dry mode must report not-published — assuming published
+  // would suppress the re-dispatch preview AND, inverted, the real registry
+  // gate is what prevents the publish-over-published 403.
+  if (onRegistry('web-components', '9.9.9', '@adia-ai', true) !== false) {
+    fail('dry onRegistry() must report false (conservative default)');
   }
 
-  const rc = verifyTriggeredAndRedispatch('9.9.9', true);
-  if (rc !== 0) { console.error(`selftest FAIL: dry verifyTriggeredAndRedispatch() should report rc=0, got ${rc}`); process.exit(1); }
+  const rc = await verifyTriggeredAndRedispatch('9.9.9', '@adia-ai', true);
+  if (rc !== 0) fail(`dry verifyTriggeredAndRedispatch() should report rc=0, got ${rc}`);
 
   console.log('selftest OK');
 }
 
 const topArgv = process.argv.slice(2);
 if (topArgv[0] === 'selftest') {
-  selftest();
+  selftest().catch((e) => { console.error(`selftest FAIL: ${e.message}`); process.exit(1); });
 } else {
   main().catch((e) => {
     console.error(`error: ${e.message}`);

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

@@ -147,6 +147,52 @@ function parseArgs(argv) {
   // 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
   // error must never cost half a shipped release.
+  // From-scratch needs FULL roster CHANGELOG coverage at Step 4 — every
+  // package gets its [VERSION] section from either promote-unreleased
+  // (--substantive-packages) or insert-stub (--stub-packages). Validate at
+  // PARSE time, not there: on the v0.8.29 cut the missing --stub-packages
+  // surfaced only at Step 4e's generate-release-notes ("no [X.Y.Z] CHANGELOG
+  // section in: <8 ride-alongs>") — AFTER the ~15-min pre-flight, promote,
+  // and bump had all run, and each abort left a half-cut tree (gh#765).
+  // Mirrors the handoff --gh-notes-file guard below. Mode cut is exempt: a
+  // peer may have pre-staged the [VERSION] sections by hand.
+  // EITHER package flag arms the guard (CodeRabbit, PR #772): keying on
+  // --substantive-packages alone let a stub-only invocation bypass both the
+  // coverage check and the --substantive/--xref pairing check below — and a
+  // stub list without that pairing makes Step 4 silently skip insert-stub,
+  // the exact Step-4e death this guard exists to prevent. (A ZERO-flag
+  // from-scratch can't be judged here — it may be a half-cut resume whose
+  // sections already exist; main() rules on it after detectHalfCut.)
+  if (args.mode === 'from-scratch' && (args.substantivePackages || args.stubPackages)) {
+    // Flags accept both name form (a2ui-corpus) and path form (a2ui/corpus);
+    // normalize to name form for the roster set-difference.
+    const toName = (p) => (PACKAGE_NAMES.includes(p) ? p : p.replaceAll('/', '-'));
+    const covered = new Set([
+      ...(args.substantivePackages ?? []).map(toName),
+      ...(args.stubPackages ?? []).map(toName),
+    ]);
+    const missing = PACKAGE_NAMES.filter((p) => !covered.has(p));
+    if (missing.length > 0) {
+      console.error(`error: --mode from-scratch covers only ${covered.size} of the ${PACKAGE_NAMES.length} lockstep`);
+      console.error('       packages — Step 4e (generate-release-notes) would die on a missing');
+      console.error(`       [${args.version}] CHANGELOG section in the ${missing.length} ride-along(s):`);
+      console.error(`         ${missing.join(', ')}`);
+      console.error('       Add them to --stub-packages (pure ride-alongs get the lockstep stub;');
+      console.error('       insert-stub also needs --substantive and --xref) or to');
+      console.error('       --substantive-packages if they carry real [Unreleased] content.');
+      console.error('       Failing now, BEFORE the ~15-min pre-flight (v0.8.29 burned three');
+      console.error('       full re-runs discovering this at Step 4e — gh#765).');
+      process.exit(2);
+    }
+    // insert-stub silently no-ops without --substantive/--xref (Step 4's
+    // guard condition) — same Step 4e death, so same parse-time fail.
+    if (args.stubPackages && (!args.substantive || !args.xref)) {
+      console.error('error: --stub-packages requires --substantive and --xref (insert-stub.mjs');
+      console.error('       needs both for the stub block; without them Step 4 silently skips');
+      console.error('       stub insertion and Step 4e dies on the missing CHANGELOG sections).');
+      process.exit(2);
+    }
+  }
   if (args.mode === 'handoff') {
     if (!args.ghNotesFile) {
       console.error('error: --mode handoff requires --gh-notes-file (Step 10 creates the 11 GH');
@@ -210,12 +256,39 @@ async function checkpoint(label, evidence, autoConfirmed) {
   }
 }
 
+// A failed inner command must surface WHAT it said, not a bare execSync
+// stack: the v0.8.29 cut died at Step 4e with only `Error: Command failed`
+// — the generator's real message ("no [X.Y.Z] CHANGELOG section in: …") was
+// invisible until the command was re-run by hand (gh#765). Print the failing
+// command + exit status + any CAPTURED stdout/stderr (piped calls; inherit
+// calls already streamed it live), then rethrow a marked, stack-free error
+// so main()'s catch doesn't re-dump a useless execSync trace over it.
+function shFailure(cmd, e) {
+  const status = e.status ?? (e.signal ? `signal ${e.signal}` : '?');
+  console.error(`\n✗ command failed (exit ${status}): ${cmd}`);
+  const captured = [e.stdout, e.stderr]
+    .map((s) => (s || '').toString().trim())
+    .filter(Boolean);
+  if (captured.length > 0) {
+    console.error('  ── the command\'s own output ──');
+    console.error(captured.join('\n').split('\n').map((l) => `  ${l}`).join('\n'));
+    console.error('  ──');
+  }
+  const err = new Error(`command failed (exit ${status}): ${cmd}`);
+  err.reported = true; // main()'s catch prints e.message only, no stack
+  return err;
+}
+
 function sh(cmd, args, opts = {}) {
   if (args.dry) {
     console.log(`  [dry] ${cmd}`);
     return '';
   }
-  return execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: opts.stdio || 'inherit' });
+  try {
+    return execSync(cmd, { cwd: REPO, encoding: 'utf8', stdio: opts.stdio || 'inherit' });
+  } catch (e) {
+    throw shFailure(cmd, e);
+  }
 }
 
 function shQuiet(cmd, args) {
@@ -223,7 +296,11 @@ function shQuiet(cmd, args) {
     console.log(`  [dry] ${cmd}`);
     return '';
   }
-  return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
+  try {
+    return execSync(cmd, { cwd: REPO, encoding: 'utf8' });
+  } catch (e) {
+    throw shFailure(cmd, e);
+  }
 }
 
 /** Run a command for its EXIT STATUS only — true on 0, false on anything
@@ -266,6 +343,56 @@ function shCapture(cmd, args) {
   }
 }
 
+// ── Half-cut detection (gh#765) ──────────────────────────────────
+// An aborted Step-4 run (the v0.8.29 cut aborted three times at Step 4e)
+// leaves a half-cut tree: package versions bumped to the cut version +
+// CHANGELOGs promoted. A plain re-run then FALSE-FAILS the pre-flight —
+// gate 24 (cut-hygiene) validates version currency at args.previous, which
+// the half-done bump has already moved past.
+//
+// DETECT-AND-RESUME, not rollback — the smaller and safer of the two:
+// resume is pure detection at the next invocation's start, so it works no
+// matter HOW the previous run died (crash, SIGINT, kill -9 — a rollback
+// handler never runs for those), and it never touches the working tree,
+// so it cannot discard operator hand-edits the way a `git checkout --`
+// rollback could. The already-correct Step-4 work is kept, not redone.
+//
+// Marker: the lockstep bump is the last tree-wide mutation before the
+// abort point, so ALL roster package.json versions at args.version ⇒ the
+// promote+bump half completed — resume. A MIX of cut/previous versions is
+// a mid-bump abort this orchestrator cannot reason about: hard-stop with
+// the manual recovery pointer. CHANGELOG promotion is then re-proved by
+// Step 4's existing unpromoted-[Unreleased] guard, and the remaining Step-4
+// substeps (lockfile, catalog, 4e notes, 4f fix, 4g hygiene) are idempotent
+// regenerations that simply run again.
+function detectHalfCut(args) {
+  if (args.mode === 'handoff' || args.dry) return false;
+  const versions = PACKAGE_ROSTER.map(({ name, dir }) => {
+    const p = path.join(REPO, dir, 'package.json');
+    return { name, version: JSON.parse(fs.readFileSync(p, 'utf8')).version };
+  });
+  const bumped = versions.filter((v) => v.version === args.version);
+  if (bumped.length === 0) return false; // fresh cut — nothing bumped yet
+  if (bumped.length < versions.length) {
+    console.error(`ERROR: mixed lockstep versions — ${bumped.length}/${versions.length} packages are already`);
+    console.error(`       at ${args.version}, the rest are not (a mid-bump abort?):`);
+    for (const v of versions.filter((x) => x.version !== args.version)) {
+      console.error(`         ✗ ${v.name}: ${v.version}`);
+    }
+    console.error('       This orchestrator can neither resume nor safely roll back a partial');
+    console.error('       bump. Restore the tree first (git status / git checkout -- <files>,');
+    console.error('       or re-run bump.mjs by hand), then re-run.');
+    process.exit(1);
+  }
+  console.log(`
+[resume] half-cut tree detected: all ${versions.length} lockstep packages already at ${args.version}
+         (an earlier run's Step 4 promote+bump completed before it aborted — gh#765).
+         Resuming: pre-flight hygiene validates at ${args.version} instead of
+         ${args.previous}, and Step 4 skips promote/stub/bump, re-running only its
+         idempotent substeps (lockfile, catalog, notes, coverage, hygiene).`);
+  return true;
+}
+
 // ── Step 1 — Re-baseline ──────────────────────────────────────────
 function step1ReBaseline(args) {
   console.log('\n=== Step 1 — Re-baseline ===');
@@ -310,8 +437,11 @@ function step3PreFlight(args) {
     // README "Current version" claim still equals the PREVIOUS version (the
     // bump moves it in Step 4; Step 4g then re-proves at the cut version) —
     // while handoff runs POST-MERGE, where the claim already equals the CUT
-    // version and validating at previous fails by construction.
-    const hygieneVersion = args.mode === 'handoff' ? args.version : args.previous;
+    // version and validating at previous fails by construction. A RESUMED
+    // half-cut run (gh#765) is post-bump too: the earlier aborted run already
+    // moved every reference to the cut version, so validating at previous
+    // false-fails gate 24 exactly like handoff would.
+    const hygieneVersion = (args.mode === 'handoff' || args.resume) ? args.version : args.previous;
     const cmd = g.versionArg ? `${g.cmd} --version ${hygieneVersion}` : g.cmd;
     console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${cmd}   # ${g.what}`);
     try {
@@ -371,16 +501,25 @@ function step4PromoteAndBump(args) {
   // optional per window, so `root` joins the promote list exactly when its
   // [Unreleased] carries real content. A repo-level-only window (0.8.7 was
   // one) promotes root with zero substantive packages.
-  const promoteTargets = [...(args.substantivePackages ?? [])];
-  if (unpromotedUnreleased(REPO, 'root')) promoteTargets.push('root');
-  if (promoteTargets.length > 0) {
-    const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${promoteTargets.join(',')}`;
-    sh(cmd, args);
-  }
+  // A resumed half-cut run (gh#765, detected in main) already promoted,
+  // stubbed, and bumped — re-running promote/insert-stub would double-insert
+  // sections and bump.mjs --from would no longer match. Skip those three;
+  // the unpromoted-[Unreleased] guard below still re-proves the promotion
+  // actually completed, and every later substep is an idempotent regenerate.
+  if (!args.resume) {
+    const promoteTargets = [...(args.substantivePackages ?? [])];
+    if (unpromotedUnreleased(REPO, 'root')) promoteTargets.push('root');
+    if (promoteTargets.length > 0) {
+      const cmd = `node ${SCRIPT_DIR}/promote-unreleased.mjs --version ${args.version} --date ${args.date} --packages ${promoteTargets.join(',')}`;
+      sh(cmd, args);
+    }
 
-  if (args.stubPackages && args.substantive && args.xref) {
-    const cmd = `node ${SCRIPT_DIR}/insert-stub.mjs --version ${args.version} --date ${args.date} --previous-version ${args.previous} --substantive "${args.substantive}" --xref "${args.xref}" --packages ${args.stubPackages.join(',')}`;
-    sh(cmd, args);
+    if (args.stubPackages && args.substantive && args.xref) {
+      const cmd = `node ${SCRIPT_DIR}/insert-stub.mjs --version ${args.version} --date ${args.date} --previous-version ${args.previous} --substantive "${args.substantive}" --xref "${args.xref}" --packages ${args.stubPackages.join(',')}`;
+      sh(cmd, args);
+    }
+  } else {
+    console.log('  [resume] promote/stub already applied by the aborted run — skipping');
   }
 
   // Loud guard: after promotion, NO package in the lockstep set (including
@@ -404,7 +543,11 @@ function step4PromoteAndBump(args) {
     console.log(`  ✓ no unpromoted [Unreleased] content across all ${PACKAGES.length} packages + root`);
   }
 
-  sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
+  if (!args.resume) {
+    sh(`node ${SCRIPT_DIR}/bump.mjs --from ${args.previous} --to ${args.version}`, args);
+  } else {
+    console.log(`  [resume] versions already at ${args.version} — skipping bump`);
+  }
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
 
@@ -751,11 +894,58 @@ async function step10GhAndSite(args) {
     `builds from main, runs pre-flight verify → snapshot → hardened rsync →\n` +
     `post-deploy verify → auto-rollback. NOT a raw rsync (the bypass this replaced).`;
   await checkpoint('Deploy site — before dispatching deploy-site.yml', evidence, args.publish);
-  sh(`gh workflow run "Deploy site (${args.host})" --repo adiahealth/gen-ui-kit --ref main`, args);
-  console.log('  Waiting for the deploy workflow to settle...');
-  if (!args.dry) sh('sleep 10', args);
-  sh(`until [ "$(gh run list --workflow=deploy-site.yml --limit 1 --json status -q '.[0].status')" = "completed" ]; do sleep 5; done`, args);
-  console.log('  ✓ deploy-site.yml settled');
+  // gh#762 + PR #775 review: dispatch and settle-wait are ONE shell block so
+  // the tracked run id survives between steps. Three fixes over the old
+  // "poll the newest run for status=completed" shape:
+  //   1. It could settle on the PREVIOUS completed run before the dispatch
+  //      registered — so capture the newest id BEFORE dispatching and wait
+  //      for a NEW id to appear.
+  //   2. It accepted failure/cancelled as settled — so poll the tracked run
+  //      by id and require conclusion=success, else fail the handoff.
+  //   3. It waited in silence while a forgotten run at the production-site
+  //      gate held the deploy-site concurrency group for 56h — so each poll
+  //      names the gate-waiting blocker (id, since, URL).
+  // reap-stale-deploy-gate.yml auto-cancels gate-waiters older than 24h, but
+  // a live handoff should not wait hours to find out.
+  console.log('  Dispatching and waiting for the deploy workflow to settle...');
+  sh(String.raw`
+    prev_id=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 1 --json databaseId -q '.[0].databaseId')
+    gh workflow run "Deploy site (${args.host})" --repo adiahealth/gen-ui-kit --ref main
+    run_id=""
+    tries=0
+    while [ "$tries" -lt 60 ]; do
+      sleep 5
+      run_id=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 1 --json databaseId -q '.[0].databaseId')
+      if [ -n "$run_id" ] && [ "$run_id" != "$prev_id" ]; then break; fi
+      run_id=""
+      tries=$((tries + 1))
+    done
+    if [ -z "$run_id" ]; then
+      echo "ERROR: the dispatched deploy-site run never appeared within 5 min (newest is still $prev_id) — inspect the Actions tab before retrying" >&2
+      exit 1
+    fi
+    echo "  Tracking dispatched run $run_id..."
+    while :; do
+      status=$(gh run view "$run_id" --repo adiahealth/gen-ui-kit --json status -q .status)
+      [ "$status" = "completed" ] && break
+      blocker=$(gh run list --workflow=deploy-site.yml --repo adiahealth/gen-ui-kit --limit 10 \
+        --json databaseId,status,createdAt,url \
+        -q '[.[] | select(.status == "waiting")] | last | if . == null then "" else "run \(.databaseId) — waiting at the production-site gate since \(.createdAt): \(.url)" end')
+      if [ "$status" = "waiting" ]; then
+        echo "  … run $run_id is at the production-site approval gate: ${'$'}{blocker:-approve it in the Actions UI}"
+      elif [ -n "$blocker" ]; then
+        echo "  … run $run_id is '$status' — BLOCKED BEHIND $blocker (gh#762: approve or cancel that run to release the deploy-site concurrency group)"
+      else
+        echo "  … run $run_id: $status"
+      fi
+      sleep 15
+    done
+    conclusion=$(gh run view "$run_id" --repo adiahealth/gen-ui-kit --json conclusion -q .conclusion)
+    if [ "$conclusion" != "success" ]; then
+      echo "ERROR: deploy-site run $run_id completed with conclusion '$conclusion' — the site deploy did NOT land; investigate the run before re-dispatching" >&2
+      exit 1
+    fi
+    echo "  ✓ deploy-site.yml run $run_id settled: success"`, args);
   // Verify a deployed CONTENT FILE, never an SPA route — the docs site
   // returns HTTP 200 + a blank shell for ANY unmatched route (v0.7.4 trap).
   sh(`curl -s -o /dev/null -w "EXE host.css: HTTP %{http_code}\\n" https://${args.host}/packages/web-components/styles/host.css`, args);
@@ -767,6 +957,23 @@ async function main() {
   // Fail-fast guard: refuse to git/npm/gh/curl against a non-monorepo directory.
   assertMonorepoRoot(REPO);
   console.log(`adia-release release-pack — v${args.version} (${args.mode})${args.dry ? ' [DRY]' : ''}`);
+  // gh#765: an aborted Step-4 run leaves bumped versions + promoted
+  // CHANGELOGs; detect BEFORE pre-flight so gate 24 validates at the right
+  // version and Step 4 skips the already-done promote/stub/bump.
+  args.resume = detectHalfCut(args);
+  // The zero-flag from-scratch shape parseArgs deferred (CodeRabbit, PR #772):
+  // with NEITHER package flag, no CHANGELOG gets a [VERSION] section and
+  // Step 4e is a guaranteed death — unless this is a half-cut RESUME, where
+  // the aborted run already wrote the sections. Only detectHalfCut can tell
+  // the two apart, so the ruling lives here — still BEFORE the pre-flight.
+  if (args.mode === 'from-scratch' && !args.resume && !args.substantivePackages && !args.stubPackages) {
+    console.error('error: --mode from-scratch needs --substantive-packages and/or --stub-packages');
+    console.error(`       covering all ${PACKAGE_NAMES.length} lockstep packages — with neither, no CHANGELOG gets`);
+    console.error(`       a [${args.version}] section and Step 4e (generate-release-notes) dies after`);
+    console.error('       the ~15-min pre-flight (gh#765). A resumed half-cut tree is exempt,');
+    console.error('       but this tree is not half-cut (versions are not at the cut version).');
+    process.exit(2);
+  }
   step1ReBaseline(args);
   step3PreFlight(args);
   step4PromoteAndBump(args);
@@ -859,6 +1066,83 @@ function selftest() {
       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
+    // Step 4e). Mirror of the handoff --gh-notes-file guard below.
+    let guardFailed = false;
+    let guardOut = '';
+    try {
+      execSync(
+        `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --substantive-packages web-components --dry`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      guardFailed = true;
+      guardOut = (e.stdout || '') + (e.stderr || '');
+    }
+    if (!guardFailed || !guardOut.includes('ride-along') || !guardOut.includes('a2ui-validator')) {
+      console.error('selftest FAIL: from-scratch without --stub-packages must hard-reject at parse time, naming the ride-alongs');
+      process.exit(1);
+    }
+    if (guardOut.includes('Step 3') || guardOut.includes('gate roster')) {
+      console.error('selftest FAIL: the ride-along guard must fire BEFORE the pre-flight, not after');
+      process.exit(1);
+    }
+
+    // CodeRabbit (PR #772): the guard must arm on EITHER flag — a stub-only
+    // invocation used to bypass it entirely. Three shapes: stub-only partial
+    // coverage rejects naming ride-alongs; stub-only full coverage without
+    // the --substantive/--xref pairing rejects (insert-stub would silently
+    // no-op); zero-flag from-scratch on a NON-half-cut tree rejects in main
+    // after detectHalfCut, still before the pre-flight.
+    const rejectShapes = [
+      { flags: '--substantive x --xref y --stub-packages llm', marker: 'ride-along' },
+      { flags: `--stub-packages ${PACKAGE_NAMES.join(',')}`, marker: '--substantive and --xref' },
+      { flags: '', marker: 'needs --substantive-packages and/or --stub-packages' },
+    ];
+    for (const { flags, marker } of rejectShapes) {
+      let failed = false;
+      let out = '';
+      try {
+        execSync(
+          `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+          `--commit-message-file "${commitFile}" ${flags} --dry`,
+          { cwd: REPO, encoding: 'utf8' },
+        );
+      } catch (e) {
+        failed = true;
+        out = (e.stdout || '') + (e.stderr || '');
+      }
+      if (!failed || !out.includes(marker) || out.includes('gate roster')) {
+        console.error(`selftest FAIL: from-scratch shape "${flags || '(no package flags)'}" must reject pre-flight with "${marker}"`);
+        process.exit(1);
+      }
+    }
+
+    // …and a fully covered from-scratch roster (substantive ∪ stub = all
+    // packages) must pass the guard and assemble its dry plan normally.
+    const stubs = PACKAGE_NAMES.filter((p) => p !== 'web-components').join(',');
+    let coveredOut;
+    try {
+      coveredOut = execSync(
+        `node "${scriptPath}" --mode from-scratch --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ` +
+        `--commit-message-file "${commitFile}" --gh-notes-file "${notesFile}" ` +
+        `--substantive "selftest" --xref "CHANGELOG.md#999" ` +
+        `--substantive-packages web-components --stub-packages ${stubs} --dry --yes`,
+        { cwd: REPO, encoding: 'utf8' },
+      );
+    } catch (e) {
+      console.error('selftest FAIL: fully covered from-scratch --dry must pass the ride-along guard');
+      console.error((e.stdout || '') + (e.stderr || ''));
+      process.exit(1);
+    }
+    if (!coveredOut.includes('STOPPING per invariant 3')) {
+      console.error('selftest FAIL: covered from-scratch dry plan missing the invariant-3 stop');
+      process.exit(1);
+    }
+
     // Handoff without --gh-notes-file must die at PARSE time (v0.8.10: the old
     // Step-10-only check fired after tags+publish were irreversible).
     let handoffFailed = false;
@@ -892,7 +1176,10 @@ if (topArgv[0] === 'selftest') {
   selftest();
 } else {
   main().catch((e) => {
-    console.error(e);
+    // sh()/shQuiet() failures already printed the failing command + its
+    // captured output (gh#765) — a full stack re-dump would bury it again.
+    if (e && e.reported) console.error(e.message);
+    else console.error(e);
     rl.close();
     process.exit(1);
   });