@adia-ai/adia-ui-forge 0.8.51 → 0.8.52

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.52] — 2026-08-25
+
+### Added
+- **`cross-harness-authoring-standards` (renamed from `writing-harness-install-instructions`, which had only ever existed as uncommitted worktree content) + new sibling skill `cross-harness-compatibility-standards` (gh#1975, PR #2003).** The rename is byte-faithful aside from the three self-referential mentions (frontmatter name, H1, one in-body reference). The new skill is the upstream engineering standard for actually building a capability that works across Claude Code, Codex, Pi, and Hermes — distinct from the renamed sibling's downstream consumer-facing install-docs concern — extracted from ADR-0091 and the four PRs (#1997-#2000) that built and shipped it: the skill-vs-thin-adapter classification rule, verify-before-coding per harness, one authored skill body with every runtime as a thin consumer, one contract grammar (record-lint family) instead of a schema per runtime, and naming distribution channels distinctly. Codex and Hermes derived manifests regenerated for both skills; README/`AGENTS.md` skill-roster and count updated.
+
+### Changed
+- **`package-release`'s pre-cut roster runs in three phases instead of one serial for-loop (gh#2006, follow-up from gh#1987's audit)** — `release-pack.mjs`'s `step3PreFlight()` now runs gate 4 (`test:unit:serial`) solo, the eval-health chain (gates 16 → 27 → 28 — a real CSS-before-JS-shaped file-write ordering dependency: gate 28 reads whichever `evals/mcp/runs/` directory sorts lexically last, so gate 27's free-form run must land uninterrupted) strictly in order, and every other gate in a concurrency-capped pool (`PREFLIGHT_CONCURRENCY`, default 4) — all concurrent with the chain. Cuts real wall-clock with zero coverage loss: no gate dropped, none renumbered, none silently skipped. `--dry` previews are unchanged (still the original flat serial walk, byte-for-byte, so `selftest`'s exact-output assertions keep passing).
+- **All agent seats pinned to `sonnet` + `xhigh` reasoning effort, replacing the prior fable/opus ceiling-ladder pins (PR #1999).** Operator's direct standing instruction, applied across `a2ui-maintenance-agent`, `a2ui-planner-agent`, `demo-audit-agent`, `framework-checker`, `framework-planner-agent`, `gen-ui-review-agent`, `package-release-agent`, `primitive-authoring-agent`. See root `CHANGELOG.md` for the cross-plugin note.
+
+### Fixed
+- **`__init__.py`'s Hermes manifest generator's `register_skill` call passed a plain string where the runtime requires a `pathlib.Path` (calls `path.exists()`) — wrapped, discovered incidentally while building `adia-ui-factory`'s Hermes `delegate_task` command (PR #2000).**
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+
 ## [0.8.51] — 2026-08-24
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@ Re-engineered 2026-07 for the Fable 5 harness (design:
 `.claude/docs/specs/plugin-estate-v2.md`): one skill per job, explicit
 invocation dials, references for depth, mechanical rules in hooks, thin agents.
 
-## Skills (9)
+## Skills (11)
 
 | Skill | Species | Job |
 |---|---|---|
@@ -21,6 +21,8 @@ invocation dials, references for depth, mechanical rules in hooks, thin agents.
 | `site-deployment` | procedural | exe.dev service ops — site deploys, VM diagnosis, secret rotation |
 | `site-docs-authoring` | procedural | author/review `site/pages/` docs pages against the shared skeleton |
 | `ssr-compatibility` | knowledge | answers SSR failure-shape questions (linkedom/Astro consumers) |
+| `cross-harness-authoring-standards` | procedural | author consumer-facing multi-harness install instructions |
+| `cross-harness-compatibility-standards` | procedural | engineering standard for building a capability that genuinely works across Claude/Codex/Pi/Hermes (ADR-0091) |
 
 ## Agents (8, thin shells)
 

package/__init__.py

@@ -1,5 +1,6 @@
 """adia-ui-kit-forge — generated by scripts/build/harness-manifests.mjs. Do not edit."""
 import os
+from pathlib import Path
 
 _HERE = os.path.dirname(os.path.abspath(__file__))
 
@@ -7,46 +8,56 @@ _HERE = os.path.dirname(os.path.abspath(__file__))
 def register(ctx):
     ctx.register_skill(
         name="a2ui-maintenance",
-        path=os.path.join(_HERE, "skills", "a2ui-maintenance", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "a2ui-maintenance", "SKILL.md")),
         description="Maintains the A2UI pipeline (packages/gen-ui/a2ui/): the chunk corpus, compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval, validator, calibration, evals, the a2ui MCP server. Use to author/harvest/fix chunks, tune STRONG_MATCH or zettel thresholds, validate an A2UI document, diagnose an eval gap/regression or lift a semantic fail, change MCP tools (generate_ui, compose_from_chunks, check_anti_patterns, refine_composition), scan anti-patterns, run pipeline ops, or when a contract can't express a shape. NOT for app screens (screen-composition), runtime gen-UI features (gen-ui-wiring), primitive authoring (primitive-authoring), or gallery scoring (gen-ui-review).",
     )
+    ctx.register_skill(
+        name="cross-harness-authoring-standards",
+        path=Path(os.path.join(_HERE, "skills", "cross-harness-authoring-standards", "SKILL.md")),
+        description="Authors copy-paste install instructions for an adia-ui plugin (or any Claude Code plugin) across multiple agent harnesses — Claude Code, Codex, Pi, Hermes. Use when asked to \"write a Slack post for installing our plugins\", \"how do devs on Codex/Pi/Hermes install this\", \"update the multi-harness install docs\", or after a harness-distribution change (a new .codex-plugin/, plugin.yaml, or package.json \"pi\" field) needs its install instructions to catch up. NOT for the manifest/build mechanics themselves (package-release's Codex-manifest step, gh#1888/gh#1954) — this skill only writes the consumer-facing instructions once those exist.",
+    )
+    ctx.register_skill(
+        name="cross-harness-compatibility-standards",
+        path=Path(os.path.join(_HERE, "skills", "cross-harness-compatibility-standards", "SKILL.md")),
+        description="The engineering/architecture standard for actually BUILDING a Claude agent-family (or any multi-runtime capability) so it genuinely works across Claude Code, Codex, Pi, and Hermes — not the consumer-facing install docs once it already works (that's cross-harness-authoring-standards). Use when deciding whether a capability earns a new user-facing skill or should stay a thin runtime-specific agent/seat/extension, before writing a Pi extension or Hermes command and unsure whether the target API actually exists, defining a structured handoff record two or more runtimes must exchange, or naming a new plugin distribution/marketplace channel alongside an existing one. NOT for writing the resulting per-harness install commands (cross-harness-authoring-standards owns that, once the capability already works).",
+    )
     ctx.register_skill(
         name="demo-audit",
-        path=os.path.join(_HERE, "skills", "demo-audit", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "demo-audit", "SKILL.md")),
         description="Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, admin-shell composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`). Use for \"run a dogfood sweep\", \"find broken demos\", \"audit native primitive leaks\". NOT for gen-UI gallery scoring (gen-ui-review) or authoring primitives (primitive-authoring).",
     )
     ctx.register_skill(
         name="gen-ui-review",
-        path=os.path.join(_HERE, "skills", "gen-ui-review", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "gen-ui-review", "SKILL.md")),
         description="Closed-loop Gen UI gallery quality review — per cycle: derive ideal specs, decompose the rendered canvas, score the gap, root-cause, emit fix plans until every prompt clears the exit gate. Use for /gen-review, \"score the gallery\", \"review gen-ui outputs\". NOT for corpus fixes (a2ui-maintenance), primitive authoring (primitive-authoring), or a hand-authored demo/app-shell QA sweep (demo-audit).",
     )
     ctx.register_skill(
         name="llm-client-maintenance",
-        path=os.path.join(_HERE, "skills", "llm-client-maintenance", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "llm-client-maintenance", "SKILL.md")),
         description="Maintains @adia-ai/llm (packages/llm/core/): provider adapters (anthropic/openai/ gemini), the shared SSE parser, model registry, chat()/streamChat() facade, createAdapter() bridge. Use when adding or fixing a provider adapter, debugging streaming bugs (StreamChunk, no terminal `done` chunk), raw `stopReason`/usage mapping, buildRequest() or passthrough proxy dispatch (browser 401s, API key in browser), detectProvider/MODELS registry changes, or the stub adapter. NOT for wiring the client into an app (llm-wiring, adia-ui-factory plugin).",
     )
     ctx.register_skill(
         name="package-release",
-        path=os.path.join(_HERE, "skills", "package-release", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "package-release", "SKILL.md")),
         description="Release engineering for the @adia-ai lockstep monorepo. Use to cut and ship a release, promote [Unreleased] CHANGELOG entries, tag and push lockstep packages to origin, publish a 10-package release (roster: scripts/package-paths.mjs), publish a single plugin independently of the lockstep set (Class B), batch-push piled-up release commits, recover a cut that landed wrong or whose publish workflows didn't fire, fix a check:lockstep bump failure or an F-N1 CHANGELOG warning, verify release gates without cutting anything, or author release notes/a MIGRATION GUIDE section. NOT for consumer-app migration sweeps (app-migration) or exe.dev VM ops (site-deployment).",
     )
     ctx.register_skill(
         name="primitive-authoring",
-        path=os.path.join(_HERE, "skills", "primitive-authoring", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "primitive-authoring", "SKILL.md")),
         description="Author or modify AdiaUI framework source inside the monorepo — primitives (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos. Use to add a new primitive, fix a prop/slot/attribute/CSS variant, update a yaml, build or fix a shell (chat-shell, admin-shell, editor-shell — sidebar/pane/bespoke-tier composition), promote repeated inline content into a shared module, audit a component's four-axis contract/token usage/lifecycle for drift, or author a demo or examples.html. NOT for app screens (screen-composition), A2UI internals (a2ui-maintenance), @adia-ai/llm internals (llm-client-maintenance), or site/pages docs (site-docs-authoring).",
     )
     ctx.register_skill(
         name="site-deployment",
-        path=os.path.join(_HERE, "skills", "site-deployment", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "site-deployment", "SKILL.md")),
         description="Deploys and operates the AdiaUI site + services on exe.dev VMs — pushing a `site-v*` tag through the hardened rsync --delete deploy to ui-kit.exe.xyz (dry-run delete summary reviewed before the real deploy job runs), diagnosis (\"Port 8000 unbound\", a 502, a stale/404ing build behind npm after the last lockstep cut), rolling back a broken deploy, VM provisioning, secret rotation. Use for \"deploy to exe.dev\", \"push a site-v* tag\", \"the site is 502ing / looks stale\", \"roll back the last deploy\", \"restart/diagnose the exe service\", \"rotate keys on the VM\". NOT for cutting the release itself (package-release).",
     )
     ctx.register_skill(
         name="site-docs-authoring",
-        path=os.path.join(_HERE, "skills", "site-docs-authoring", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "site-docs-authoring", "SKILL.md")),
         description="Review or author pages under site/pages/{architecture,getting-started, guides,patterns,reference}/ — the docs site (count the pages on disk; it grows). Use when asked to add or edit a getting-started/architecture/guides/patterns/reference page, review a site docs page for consistency, fix a callout that reads as plain text, or explain why an inline-code chip or a demo gallery looks broken. NOT for a component's own .examples.html demo (primitive-authoring) or any pure-primitive-composition training-harvest page (governed by composition-and-examples.md's no-style-block rule; owner: a2ui-maintenance).",
     )
     ctx.register_skill(
         name="ssr-compatibility",
-        path=os.path.join(_HERE, "skills", "ssr-compatibility", "SKILL.md"),
+        path=Path(os.path.join(_HERE, "skills", "ssr-compatibility", "SKILL.md")),
         description="Answers why an AdiaUI component crashes, drops content, renders wrong, or mutates a byte-identical subtree under SSR (linkedom/Astro) — the known failure shapes, what's fixed vs open, how to prove a fix under the linkedom shim gate. Use for \"does this work under SSR\", why a component crashes on attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/ `instanceof Node` under a DOM shim, why table-ui/chart-ui/select-ui or a container CE renders empty or drops nested children server-rendered, whether getBoundingClientRect() is safe in connectedCallback, whether a custom render()/connected() path adopts-in-place or rebuilds a server-rendered subtree that already matches (zero-subtree-mutation / AC-004a-shaped asks), whether a querySelector-guard-before-innerHTML component is SSR-safe, or whether a shim can be deleted after a fix ships. ANSWERS only. NOT for a fix (primitive-authoring) or host/hydration wiring (host-wiring, adia-ui-factory).",
     )

package/agents/a2ui-maintenance-agent.md

@@ -12,10 +12,12 @@ description: |
 tools: Read, Grep, Glob, Edit, Write, Bash
 skills:
   - a2ui-maintenance
-# Explicit pin (gh#618): never `inherit` — a Fable/planning caller would
-# silently run this seat's pipeline-tuning and eval-diagnosis work on the
-# caller's tier. Coding/execution seat → opus.
-model: opus
+# Explicit pin (gh#618): never `inherit` — a caller on a cheaper tier would
+# silently run this seat's pipeline-tuning and eval-diagnosis work on its
+# own tier instead. Operator's explicit standing instruction for this seat
+# family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The a2ui-maintenance-agent works the pipeline to the preloaded `a2ui-maintenance` procedure:

package/agents/a2ui-planner-agent.md

@@ -15,11 +15,11 @@ skills:
   - break-down-problem
   - doc-writing-rules
   - a2ui-maintenance
-# Planning & architecture row (agent-writing-rules' seat ladder): fable + high, never
-# below fable. Same reasoning as framework-planner-agent — a catalog-cohesion decision
-# sets the ceiling on what a2ui-maintenance-agent builds against it.
-model: fable
-effort: high
+# Explicit pin: never `inherit` — a catalog-cohesion decision sets the
+# ceiling on what a2ui-maintenance-agent builds against it. Operator's
+# explicit standing instruction for this seat family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The a2ui-planner-agent decomposes one named A2UI catalog-system change via the preloaded

package/agents/demo-audit-agent.md

@@ -16,10 +16,10 @@ tools: Read, Grep, Glob, Bash
 skills:
   - demo-audit
 # Explicit pin (gh#618, tier corrected gh#1045): a review/critic seat's
-# verdict must not depend on the caller's model tier — never `inherit`,
-# never below fable (the ceiling ladder's Review row).
-model: fable
-effort: high
+# verdict must not depend on the caller's model tier — never `inherit`.
+# Operator's explicit standing instruction for this seat family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The demo-audit-agent runs the preloaded dogfood sweep procedure and returns

package/agents/framework-checker.md

@@ -13,11 +13,11 @@ description: |
 tools: Read, Grep, Glob, Bash
 skills:
   - primitive-authoring
-# Review / hard-bug analysis row (agent-writing-rules' seat ladder), pinned explicitly —
-# never `inherit`, same reasoning as demo-audit-agent's own explicit pin (gh#618): a
-# critic's verdict must not depend on the caller's tier.
-model: fable
-effort: high
+# Explicit pin (gh#618) — never `inherit`, same reasoning as demo-audit-agent's
+# own explicit pin: a critic's verdict must not depend on the caller's tier.
+# Operator's explicit standing instruction for this seat family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The framework-checker sweeps the named scope (the whole primitive corpus, or a

package/agents/framework-planner-agent.md

@@ -14,12 +14,13 @@ tools: Read, Grep, Glob, Write, Edit
 skills:
   - break-down-problem
   - doc-writing-rules
-# Planning & architecture row (agent-writing-rules' seat ladder, ratified 2026-07-12):
-# fable + high, never below fable, effort range high-xhigh. A decomposition seat's
-# output sets the ceiling on everything primitive-authoring-agent builds downstream from
-# it; a cheap tier would make load-bearing architectural calls with no independent check.
-model: fable
-effort: high
+# Explicit pin: never `inherit` — a decomposition seat's output sets the
+# ceiling on everything primitive-authoring-agent builds downstream from it;
+# a cheap tier would make load-bearing architectural calls with no
+# independent check. Operator's explicit standing instruction for this seat
+# family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The framework-planner-agent decomposes one named framework change via the preloaded

package/agents/gen-ui-review-agent.md

@@ -17,10 +17,10 @@ tools: Read, Grep, Glob, Bash
 skills:
   - gen-ui-review
 # Explicit pin (gh#618, tier corrected gh#1045): a review/critic seat's
-# verdict must not depend on the caller's model tier — never `inherit`,
-# never below fable (the ceiling ladder's Review row).
-model: fable
-effort: high
+# verdict must not depend on the caller's model tier — never `inherit`.
+# Operator's explicit standing instruction for this seat family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The gen-ui-review-agent runs the preloaded gen-ui-review cycle and returns

package/agents/package-release-agent.md

@@ -14,8 +14,10 @@ skills:
   - package-release
 # Explicit pin (gh#618): never `inherit` — this seat runs UNATTENDED cuts,
 # where a cheap caller tier would make live gate-failure judgment calls
-# with no operator watching. Execution seat with real judgment → opus.
-model: opus
+# with no operator watching. Operator's explicit standing instruction for
+# this seat family: sonnet + xhigh.
+model: sonnet
+effort: xhigh
 ---
 
 The package-release-agent runs the preloaded `package-release` procedure under its

package/agents/primitive-authoring-agent.md

@@ -11,6 +11,7 @@ tools: Read, Grep, Glob, Edit, Write, Bash
 skills:
   - primitive-authoring
 model: sonnet
+effort: xhigh
 ---
 
 The primitive-authoring-agent builds framework source to the preloaded `primitive-authoring`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — 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/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-forge"
-version: "0.8.51"
+version: "0.8.52"
 description: "Maintain the adia-ui (@adia-ai) framework itself — 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-ui-kit-factory (the consumer/app-author plugin)."
 manifest_version: 1

package/skills/cross-harness-authoring-standards/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: cross-harness-authoring-standards
+description: >-
+  Authors copy-paste install instructions for an adia-ui plugin (or any
+  Claude Code plugin) across multiple agent harnesses — Claude Code, Codex,
+  Pi, Hermes. Use when asked to "write a Slack post for installing our
+  plugins", "how do devs on Codex/Pi/Hermes install this", "update the
+  multi-harness install docs", or after a harness-distribution change
+  (a new .codex-plugin/, plugin.yaml, or package.json "pi" field) needs its
+  install instructions to catch up. NOT for the manifest/build mechanics
+  themselves (package-release's Codex-manifest step, gh#1888/gh#1954) — this
+  skill only writes the consumer-facing instructions once those exist.
+disable-model-invocation: false
+user-invocable: true
+---
+
+# cross-harness-authoring-standards — one command per harness, zero invented syntax
+
+Every harness's install path is a claim someone will paste verbatim into a terminal. A
+plausible-looking command that was never verified against this repo's actual shipped
+manifests is worse than no instructions — it fails silently or errors somewhere the
+author never sees. The whole discipline is: **read the real generated file before
+describing what it does.**
+
+## The verification-before-writing gate `[gate]`
+
+Before writing one line of install instructions for a harness, verify against the strongest
+source actually reachable — never infer a harness's install surface from another harness's
+shape, and never invent a CLI subcommand you have not seen documented or confirmed:
+
+- **Strongest: the target harness's own agent, live.** If a Codex/Pi/Hermes agent is
+  reachable (a peer session, a cross-harness message), have it check or correct the draft
+  against its own real CLI/config surface directly — it knows its own tool's commands with
+  more authority than any manifest file a human read once and wrote down. A harness section
+  corrected this way outranks a manifest-file read on the same point; update the draft to
+  match, don't average the two.
+- **Fallback: the repo's own shipped manifest for that harness** (below), when no live
+  agent is reachable.
+
+| Harness | What to read before writing anything |
+| --- | --- |
+| Claude Code | The plugin's own `README.md` "Install" section + `.claude-plugin/marketplace.json` (or the published npm marketplace manifest) |
+| Codex | `.codex-plugin/plugin.json` + `codex.interface.json` + the repo's own `AGENTS.md` "Non-Claude harnesses" section (gh#1888 — the canonical degradation-table citation) |
+| Hermes | `plugin.yaml` + `__init__.py` at the package root, and whether an `hermes-mcp.yaml` (or equivalent) fragment exists — Hermes MCP is user-level config, not a plugin field, in every verified case so far |
+| Pi | `package.json`'s `"pi"` field + `pi-package` keyword, and `prompts/*.md` if present |
+
+If a harness's manifest file doesn't exist yet in the repo, that harness has **no verified
+install path** — say so plainly (`cross-harness-authoring-standards` never fabricates a
+"probably works like X" command) and route the gap to the maintainer skill/issue that owns
+harness-manifest generation, rather than guessing syntax.
+
+## The four-axis degradation table
+
+Every harness other than Claude Code lacks at least one of: commands, agent seats, hooks,
+native MCP. State the gap plainly per harness, in the instructions themselves — a dev who
+installs expecting the full surface and silently gets less is worse served than one told
+up front:
+
+- **Commands** → Codex/Pi/Hermes have no slash-command layer in the verified cases; a
+  command degrades to invoking its underlying skill directly (Codex, Hermes) or, where the
+  harness's own prompt-template layer supports genuine commands (Pi's `prompts/*.md`),
+  upgrades instead of degrading — check per harness, don't assume degradation is universal.
+- **Agent seats** → do not exist outside Claude Code. Never write "then invoke
+  `<agent-name>`" for Codex/Pi/Hermes; give the entry-point *skill* that agent dispatches
+  internally instead (see "The common starting prompt" below).
+- **Hooks** → Codex/Pi/Hermes have no hook runtime in the verified cases; state "no
+  hooks surface" rather than omitting the topic (an omission reads as "works the same").
+- **MCP** → the highest-risk gap. Verify per harness: does it read `.mcp.json` unmodified
+  (Codex — verified), read it via a third-party adapter the dev must separately install
+  (Pi's `pi-mcp-adapter` — verified 2026-08-24), or require hand-merging a generated
+  fragment into the harness's own user-level config (Hermes — verified, no plugin-level MCP
+  field exists)? If the plugin's whole value proposition is its MCP server, say that
+  explicitly before promising support — a silent no-op MCP install is the worst failure
+  mode this skill exists to prevent.
+
+## The common starting prompt
+
+A "getting started" prompt that opens with an agent name breaks on every harness but
+Claude Code. Give two forms:
+
+- **Claude Code**: name the coordinating agent directly (`Use <agent-name> to build
+  [...]`).
+- **Everywhere else**: name the entry-point *skill* that agent dispatches internally —
+  same routing, no agent-seat dependency. Confirm the skill is genuinely the entry point
+  (its own description says "run FIRST" / "cold-start router") rather than picking an
+  arbitrary skill from the roster.
+
+```
+Bad (breaks on Codex/Pi/Hermes — no agent seat exists):
+  Use ui-architect to build a settings page.
+
+Good (Claude Code):
+  Use ui-architect to build a settings page. Check pattern-catalog for an
+  existing pattern before composing from scratch.
+
+Good (Codex/Pi/Hermes — same routing, no agent dependency):
+  Use the app-planning skill to orient a new settings page. Check
+  pattern-catalog for an existing pattern before composing from scratch,
+  then use screen-composition to build it.
+```
+
+## Structure
+
+One block per harness, each self-contained (a reader only cares about their own harness):
+install command(s) → any manual wiring step (config file edit, separate adapter install) →
+the degradation summary (what's full-strength, what's reduced, what's absent) for that
+harness specifically. Never a single combined command block trying to cover two harnesses —
+the reader copy-pastes the whole block for their tool and nothing else.
+
+## Failure branches
+
+A harness with no verified manifest in the repo → report the gap, do not draft syntax for
+it. A degradation claim that contradicts what a just-read manifest file actually shows
+(e.g. writing "no MCP" for a harness whose `.mcp.json` passthrough is confirmed working) →
+re-read the source file; the manifest is authoritative over any prior draft, including this
+skill's own past output for an earlier plugin version.
+
+Done when every harness section cites the specific file it was verified against (in prose,
+not a footnote) and no command exists in the output that wasn't read from a real shipped
+artifact.

package/skills/cross-harness-authoring-standards/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Cross Harness Authoring Standards"
+  short_description: "Authors copy-paste install instructions for an adia-ui plugin (or any Claude Code plugin) across multiple agent harnesses — Claude Code, Codex, Pi, Hermes."

package/skills/cross-harness-compatibility-standards/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: cross-harness-compatibility-standards
+description: >-
+  The engineering/architecture standard for actually BUILDING a Claude
+  agent-family (or any multi-runtime capability) so it genuinely works
+  across Claude Code, Codex, Pi, and Hermes — not the consumer-facing
+  install docs once it already works (that's
+  cross-harness-authoring-standards). Use when deciding whether a
+  capability earns a new user-facing skill or should stay a thin
+  runtime-specific agent/seat/extension, before writing a Pi extension or
+  Hermes command and unsure whether the target API actually exists,
+  defining a structured handoff record two or more runtimes must exchange,
+  or naming a new plugin distribution/marketplace channel alongside an
+  existing one. NOT for writing the resulting per-harness install commands
+  (cross-harness-authoring-standards owns that, once the capability
+  already works).
+disable-model-invocation: false
+user-invocable: true
+---
+
+# cross-harness-compatibility-standards — build it portable, don't just document it
+
+`cross-harness-authoring-standards` covers the downstream concern: writing the
+consumer-facing install instructions once a capability already works across
+harnesses. This skill covers the upstream concern — the engineering standard
+for actually **building** that capability so it works on Claude Code, Codex,
+Pi, and Hermes in the first place. If you're drafting a "how to install"
+block, you want the other skill; if you're deciding whether something needs
+a new skill, writing a Pi/Hermes adapter, or designing a structured record
+two runtimes must exchange, you're in the right place.
+
+This standard is not invented doctrine — it is extracted from
+[ADR-0091](../../../../../docs/ops/adr/adr-0091-ui-architect-cross-harness-portability.md)
+and its companion
+[PRD](../../../../../docs/ops/prd/prd-ui-architect-cross-harness-portability.md)/
+[SPEC](../../../../../docs/ops/spec/spec-ui-architect-cross-harness-portability.md)/
+[LLD](../../../../../docs/ops/lld/lld-ui-architect-cross-harness-portability.md),
+ratified and built across four merged PRs (#1997 docs, #1998 skill + contracts
++ Codex marketplace, #1999 agent pinning, #2000 Pi extension + Hermes
+command) that made `ui-architect` portable. Every rule below cites the
+decision or requirement it comes from — re-read the source before extending
+this standard, don't paraphrase from this skill alone.
+
+## Rule 1 — skill vs. thin adapter: earn the promotion `[gate]`
+
+Substantive reusable behavior belongs in a portable skill body; a
+runtime-specific agent/seat/extension stays **only if** it provides one of:
+restricted tools, isolated context, parallelism, multi-skill preload, or a
+distinct model/effort configuration (ADR-0091 D1). Delete an agent, or fold
+it into its skill, if it provides none of those structural properties. Never
+convert every internal seat into a user-facing skill merely because
+portability is required — a capability is user-invocable only when a user
+has a sensible reason to request it directly, not because promoting it was
+convenient.
+
+Apply the rule by checking each existing seat against it, on the record, not
+by assertion:
+
+- `ui-architect` was the one seat of four in `adia-ui-factory` missing its
+  skill twin — it earned `skills/ui-architect/SKILL.md` because the
+  Gear-selection/wave/generator-≠-reviewer/four-lap-cap/failure-routing
+  procedure is exactly the "substantive reusable behavior" class the rule
+  routes to a skill, and Codex/Pi/Hermes users are the concrete "sensible
+  reason to request it directly." The agent seat was **retained, not
+  replaced**: no Write/Edit (restricted tools), dispatches into isolated
+  per-screen contexts (isolated context + parallelism), pinned `fable`/
+  `high` never-`inherit` (distinct model/effort) — independently sufficient
+  to keep it.
+- `app-planning-agent`, `screen-composition-agent`, `surface-qa-agent`
+  already each preloaded a same-named user-invocable skill before this
+  change touched anything — the rule was already satisfied; nothing about
+  their shape changed beyond the same Claude-adapter slimming (Rule 3)
+  applied to all four seats equally.
+- `wave-coordination` stayed `user-invocable: false`, Claude-only,
+  unpromoted — team-pattern *mechanics* for one runtime's dispatch model,
+  not a capability a Codex/Pi/Hermes user has a sensible reason to request
+  directly. Failing the rule's own admission test on purpose is a legitimate
+  outcome, not an oversight to fix later.
+
+## Rule 2 — verify before coding, per harness, every time `[gate]`
+
+Never assume a target harness's API, extension mechanism, or delegation
+surface from documentation alone. Check the actually-installed version
+live — read its real source, run its real CLI — before writing one line of
+adapter code against it. This is the single most load-bearing lesson from
+how `ui-architect`'s Pi and Hermes adapters were actually built (PR #2000):
+
+- **Pi** was verified present by reading the installed
+  `@earendil-works/pi-coding-agent` package directly: its own shipped
+  `examples/extensions/subagent/` proved a real subprocess-based
+  subagent-dispatch pattern (`registerCommand` + `child_process` spawn of a
+  nested `pi --mode json -p --no-session`), and `package.json`'s
+  `pi.extensions` field was confirmed real and documented — not inferred by
+  analogy to Claude's Agent tool. Once verified, the extension was
+  **live-tested end to end**: a real `pi` session ran `/ui-architect`
+  against a live model, dispatched all three isolated passes, wrote a real
+  file, took a real screenshot, and returned a clean `VerifyProof`.
+- **Hermes** was verified sufficient by reading the installed Hermes
+  Agent's own source — `PluginContext.register_command` + `dispatch_tool`,
+  and `tools/delegate_tool.py`'s `delegate_task(goal, context, role, ...)` —
+  confirmed as real, current APIs before the generator surgery (Rule 3)
+  was written against them. The generated command was built behind its own
+  `--selftest` fixture (a real `py_compile` check plus a fake `delegate_task`
+  double driving the actual generated logic against the real linters)
+  *before* wiring it into the real plugin tree, then verified live via
+  `hermes plugins doctor --ci`. A full interactive dispatch was blocked by
+  the build sandbox refusing to mutate Hermes's global plugin-enable
+  state — that limitation was **noted honestly in the README rather than
+  worked around or silently dropped**.
+
+If a required capability is genuinely absent, or materially different from
+what the docs claimed (SPEC REQ-011/012's capability-boundary discipline):
+stop that adapter at an explicit, clearly-labeled capability boundary and
+record four things — the API checked, the observed mismatch, the smallest
+viable fallback, and the remaining work. Never simulate success with an
+unverified manifest field or a dead adapter file that looks like it works
+but was never actually exercised. One of the two outcomes (working adapter
++ passing native smoke test, or a capability-boundary record with all four
+fields) must exist — never neither, never both.
+
+## Rule 3 — one authored copy, many thin consumers
+
+The portable behavior lives in exactly **one** skill body. Every runtime's
+own adapter mechanism *consumes* that one body — it never gets a second,
+hand-copied prose duplicate:
+
+- **Claude** preloads it (`skills:` frontmatter on the owning agent file).
+- **Codex** auto-derives its manifest sibling
+  (`skills/<name>/agents/openai.yaml`) from the same skill frontmatter via
+  this repo's own generator (`scripts/build/codex-manifests.mjs`) — no
+  manual authoring, ever.
+- **Pi**'s extension reads the skill file *at runtime* rather than copying
+  its prose into the extension source (`ui-architect`'s
+  `pi/ui-architect.extension.ts` loads agent descriptions from the
+  plugin-local skill directly).
+- **Hermes**'s command derives from the same source
+  (`scripts/build/harness-manifests.mjs`'s generated `__init__.py`
+  registers the skill; the generated `/ui-architect` command runs the same
+  planning/composition/QA loop through `delegate_task`, gated by the same
+  contracts).
+
+A change to the workflow means editing one file, not four. If you find
+yourself pasting a skill's prose into an agent file, an extension, or a
+generator template instead of citing or reading it, stop — that's the
+duplication this rule exists to prevent.
+
+## Rule 4 — one contract grammar, not a schema per runtime
+
+When two or more runtimes need to exchange a structured handoff record,
+define it once as a plain strict-prose-record shape validated by a small
+stdlib CLI linter — never introduce JSON Schema or another
+schema-validation library into every runtime's own toolchain to do the same
+job (ADR-0091 D3). This repo's own `record-lint` family is the reusable
+grammar: `<script> <file>|-|selftest`, exit 0 clean / 1 on findings, with
+`UNMEASURED — <reason>` as a legal per-slot value (silent omission is not
+legal). `OrientationRecord` (`scripts/record-lint`), `VerifyProof`
+(`scripts/verify-proof-lint`), and `BuildResult`
+(`scripts/build-result-lint`) — all three in `adia-ui-factory`'s
+`scripts/` — are structurally identical siblings, not three different
+formats doing the same job. Every runtime adapter that produces or consumes
+one of these contracts calls the same linter script; a second,
+runtime-specific parsing or validation implementation for the same contract
+is a defect, not a stylistic choice.
+
+Before minting a new contract shape, check whether an existing one already
+covers it under a different name — reuse beats a fourth near-duplicate
+grammar.
+
+## Rule 5 — name distribution channels distinctly
+
+When the same plugin ships **both** an in-repo/access-gated channel and a
+public/npm-sourced channel for the same runtime, name them distinctly. A
+collision — both channels sharing one marketplace name — makes
+`<plugin>@<marketplace-name>` resolution ambiguous for a consumer trying to
+install from a specific channel.
+
+The confirmed, working precedent is Claude's own two-channel split: the
+repo-root, access-gated `.claude-plugin/marketplace.json` is named
+`adia-ui-kit`; the public, npm-sourced
+`packages/plugins/adia-plugins/marketplace.json` is named `adia-plugins`
+(ADR-0091 D2's own table) — two distinct names, two distinct reachability
+tiers, no ambiguity for a consumer running `/plugin install
+<plugin>@<marketplace-name>`.
+
+ADR-0091 D2 designed the Codex side to mirror that same split (a
+repo-root/local-source channel alongside the existing
+`packages/plugins/adia-plugins/.agents/plugins/marketplace.json` npm
+sibling) — but the LLD (§C7) flagged the new manifest's `name` field as an
+explicit, unverified, build-time question: does Codex key off `name` for
+`<plugin>@<marketplace-name>` resolution the way Claude does? **Verify this
+against the actually-shipped manifests before citing the Codex side as a
+settled precedent** — Rule 2's verify-before-coding discipline applies to
+this rule's own worked example, not only to Pi/Hermes adapters. Diff the
+`name` field of both Codex marketplace manifests against each other before
+assuming they follow the Claude-side pattern.
+
+## Failure branches
+
+A capability promoted to a user-facing skill with none of Rule 1's five
+qualifying properties on its remaining agent seat → fold the seat into the
+skill or delete it; don't keep a Write/Edit-free, non-isolated, no-model-pin
+shell around "for consistency." An adapter written against a harness's
+documented API with no live verification → stop, verify against the
+installed runtime first (Rule 2); a passing test against a mocked or
+assumed API is not verification. A second hand-copied prose block for a
+skill's workflow anywhere outside its one `SKILL.md` → delete the copy,
+point the consumer at the source (Rule 3). A new structured record
+introduced as JSON Schema, or as a shape that already has a linter under a
+different name → stop, extend `record-lint`'s family instead or reuse the
+existing contract (Rule 4). A new distribution manifest reusing an existing
+sibling's marketplace name → rename before shipping (Rule 5).
+
+Done when: every new or promoted seat cites the specific Rule 1 property
+that keeps it (or is deleted/folded); every harness adapter names the API
+it verified live and how (Rule 2); the skill body has exactly one authored
+copy with every consumer citing or reading it, never duplicating it (Rule
+3); every cross-runtime contract has exactly one shape and one stdlib
+linter (Rule 4); and every distribution channel's marketplace name is
+diffed against its siblings and confirmed distinct (Rule 5).

package/skills/cross-harness-compatibility-standards/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Cross Harness Compatibility Standards"
+  short_description: "The engineering/architecture standard for actually BUILDING a Claude agent-family (or any multi-runtime capability) so it genuinely works across Claude Code, Codex, Pi, and Hermes — not the consumer-facing install docs once it already works (that's cross-harness-authoring-standards)."

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

@@ -89,6 +89,8 @@ 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
 
+**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
 node scripts/build/components.mjs --verify    #  1 yaml ↔ sidecar ↔ .d.ts
 npm run verify:traits                          #  2 trait coverage

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

@@ -60,7 +60,8 @@
 // block BEFORE the prompt (H5) — never a bare y/N — whether it waits for input
 // (manual flags) or auto-confirms (--go).
 
-import { execSync } from 'node:child_process';
+import { execSync, exec as execCb } from 'node:child_process';
+import { promisify } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import fs from 'node:fs';
@@ -347,6 +348,15 @@ function shCapture(cmd, args) {
   }
 }
 
+// Async, CAPTURING exec — the concurrent pre-flight phases (gh#2006) can't
+// use sh()'s stdio:'inherit' (N processes' live output interleaved is
+// unreadable), so every gate's stdout+stderr is captured and printed as one
+// block the moment that gate finishes instead. maxBuffer generous (64 MB) —
+// a truncated capture on a real failure (tsc, vitest) would read as a false
+// pass/silent-gap the same class of defect shFailure's own doc-comment warns
+// against.
+const execAsync = promisify(execCb);
+
 // ── 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 +
@@ -428,53 +438,245 @@ function step1ReBaseline(args) {
   console.log('  (empty — origin not ahead)');
 }
 
-// ── Step 3 — Pre-flight gates ────────────────────────────────────
-function step3PreFlight(args) {
-  if (args.skipGates) {
-    console.log('\n=== Step 3 — Pre-flight (SKIPPED via --skip-gates; danger!) ===');
+// ── Step 3 — Pre-flight gates (gh#2006) ───────────────────────────
+//
+// gh#1987's audit found the real "feels slow" lever isn't roster size (all
+// 32 gates are justified defense-in-depth — `main`'s branch protection only
+// hard-requires the browser-scheme probe, so the `npm run check` name-
+// duplicates in this roster are real re-checks, not dead weight) — it's
+// that step3PreFlight ran every gate one at a time. Most of the 32 are
+// independent, read-only checks with no shared mutable state; this splits
+// them into three phases instead of one flat serial for-loop. Two real
+// sequencing requirements survived the audit — everything else runs
+// concurrently:
+//
+//   Phase 1 (solo)       — gate 4 (test:unit:serial) alone, no sibling gate
+//     process running at the same time. Not a proven requirement — the
+//     roster's own "serial on purpose" note is about vitest's OWN
+//     --no-file-parallelism, not about co-running with sibling PROCESSES —
+//     but a deliberately conservative one: gate 4 is the roster's single
+//     heaviest gate, and this repo's own host-audit F3 remedy
+//     (scripts/dev/worker-cap.mjs, gh#1792) exists precisely because
+//     unbounded concurrent lanes on a shared multi-session host turn a gate
+//     that's clean in isolation red under contention. Revisit with real
+//     measurement before loosening this.
+//   Phase 2 (concurrent) — two workstreams launched together and awaited
+//     together:
+//       (a) a bounded-concurrency pool of every remaining gate EXCEPT the
+//           eval-health chain below — each independently read-only
+//           (--verify/--fix-gated/dry-diff, checked directly against every
+//           script in the roster) or, for gate 17 (dogfood:status), writing
+//           only to a gate-private path (qa/findings/dogfood-tracker.md)
+//           no other gate reads or writes;
+//       (b) the eval-health chain — gates 16 → 27 → 28 — run strictly
+//           serially relative to EACH OTHER (still concurrent with (a),
+//           since neither touches (a)'s files). This is the roster's one
+//           CSS-before-JS-shaped file-write ordering dependency: gate 27
+//           (`eval:diff --engine free-form`) writes a fresh
+//           evals/mcp/runs/<ISO>/ directory; gate 28
+//           (write-eval-health.mjs) reads whichever directory under
+//           evals/mcp/runs/ SORTS LEXICALLY LAST — not specifically the
+//           latest free-form run — and expects free-form.json there. Gate
+//           16 (`eval:diff --engine zettel`) writes its OWN fresh directory
+//           under that same root; if 16 and 27 ran concurrently and 16
+//           happened to finish after 27, gate 28 would silently pick 16's
+//           directory (no free-form.json) and commit
+//           evals/health/<version>.json with `engines.free-form: null` — a
+//           real, silent coverage loss the roster's fixed serial order
+//           prevents today only by construction. Keeping 16 before 27
+//           before 28, uninterrupted by any other evals/mcp/runs/ writer,
+//           preserves that guarantee.
+//
+// Fail-fast BETWEEN phases (a Phase 1 failure skips Phase 2 outright — no
+// point spending Phase 2's wall-clock once the roster's known-flakiest gate
+// is already red); fail-TOGETHER within Phase 2 (every Phase 2 gate runs to
+// completion regardless of a sibling's failure, so one red pre-flight run
+// reports every failing gate at once instead of the old one-at-a-time
+// discovery) — the explicit fail-fast-vs-fail-together decision gh#2006's
+// acceptance criteria calls for. Within the eval-health chain specifically,
+// a failure DOES stop the chain (16 failing skips 27 and 28; 27 failing
+// skips 28) — that trio has a real dependency relationship the rest of
+// Phase 2 doesn't, so it keeps today's strict fail-fast semantics.
+//
+// versionArg/targetVersionArg/resume-mode branching is unchanged — every
+// gate resolves its actual command through the same resolveGateCommand()
+// logic step3PreFlight always applied, now factored out so all three
+// phases share it verbatim.
+
+const SOLO_GATE_NUMBER = 4; // test:unit:serial — see the phase-model note above.
+const EVAL_HEALTH_CHAIN_NUMBERS = [16, 27, 28]; // eval:diff zettel → eval:diff free-form → write-eval-health.mjs
+
+// Concurrency cap for Phase 2's pool — a fixed, deliberately conservative
+// constant rather than the host's full core count. Most Phase-2 gates are
+// lightweight verify/diff scripts, but a few (typecheck, the bundle
+// verifiers, corpus verify) are real tsc/esbuild/Node processes, and
+// worker-cap.mjs's own host-audit F3 finding is that unbounded concurrent
+// lanes on a shared multi-session host reintroduce exactly the contention
+// class this ticket must not reintroduce. Override via PREFLIGHT_CONCURRENCY
+// for a dedicated/idle host.
+const PREFLIGHT_CONCURRENCY = Number(process.env.PREFLIGHT_CONCURRENCY) || 4;
+
+// Resolves one gate's actual command string — the same versionArg/
+// targetVersionArg/resume branching step3PreFlight has always applied.
+// Returns null for a versionArg gate deferred by an in-flight resume (Step
+// 4g re-runs it once the notes it needs actually exist).
+function resolveGateCommand(g, args) {
+  // versionArg gates take a MODE-DEPENDENT version (both directions bit the
+  // first 0.8.8 run): cut modes run pre-flight PRE-BUMP, where the 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. 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;
+  // A RESUMED run's versionArg gates (cut-hygiene) demand artifacts Step 4
+  // has not recreated yet — docs/ops/releases/vX.Y.Z.md exists only after 4e,
+  // which runs AFTER this pre-flight. Step 4g re-runs these same gates at
+  // the cut version once the notes exist, so skipping them here loses no
+  // coverage — running them here false-fails by construction (the v0.8.32
+  // cut hit exactly this: 23/24 green, gate 24 dead on the missing notes).
+  if (g.versionArg && args.resume) return null;
+  if (g.versionArg) return `${g.cmd} --version ${hygieneVersion}`;
+  // targetVersionArg (gh#1135, REQ-06) is a distinct flag from versionArg:
+  // write-eval-health.mjs NAMES a new file after the cut's target version
+  // from the very start — there is no pre/post-bump claim to reconcile the
+  // way gate 24's README-currency check has, so it always takes
+  // `args.version` verbatim regardless of mode or resume.
+  if (g.targetVersionArg) return `${g.cmd} --version ${args.version}`;
+  return g.cmd;
+}
+
+// Runs ONE gate to completion, capturing rather than streaming its output —
+// see the file-header note above for why. Never throws: a failed gate is a
+// normal, expected outcome the caller decides how to act on, exactly like
+// shOk()'s own contract.
+async function runGateCaptured(g, args) {
+  const cmd = resolveGateCommand(g, args);
+  if (cmd === null) {
+    return { n: g.n, cmd: g.cmd, what: g.what, ok: true, skipped: true,
+      note: '[resume] deferred to Step 4g (notes not regenerated yet)' };
+  }
+  const start = Date.now();
+  try {
+    const { stdout, stderr } = await execAsync(cmd, { cwd: REPO, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    return { n: g.n, cmd, what: g.what, ok: true, stdout, stderr, ms: Date.now() - start };
+  } catch (e) {
+    return {
+      n: g.n, cmd, what: g.what, ok: false, ms: Date.now() - start,
+      status: e.code ?? (e.signal ? `signal ${e.signal}` : '?'),
+      stdout: e.stdout, stderr: e.stderr,
+    };
+  }
+}
+
+// Prints one captured gate's result in the same shape a serial gate would
+// have streamed live, so a scan-back-through-the-log habit built on the old
+// stdio:'inherit' output still works.
+function printGateResult(r) {
+  if (r.skipped) {
+    console.log(`\n  ${r.n}/${GATE_ROSTER.length}. ${r.cmd}   # ${r.what} — ${r.note}`);
     return;
   }
-  console.log(`\n=== Step 3 — Pre-flight gates (${GATE_ROSTER.length}-gate roster — gate-roster.mjs) ===`);
+  console.log(`\n  ${r.n}/${GATE_ROSTER.length}. ${r.cmd}   # ${r.what} (${(r.ms / 1000).toFixed(1)}s)`);
+  const out = [r.stdout, r.stderr].map((s) => (s || '').toString().trim()).filter(Boolean).join('\n');
+  if (out) console.log(out.split('\n').map((l) => `    ${l}`).join('\n'));
+  if (!r.ok) {
+    console.error(`  ✗ FAILED (${r.n}/${GATE_ROSTER.length}): ${r.cmd} (exit ${r.status})`);
+  }
+}
+
+// Runs a fixed array of gates strictly one after another, in array order —
+// the eval-health chain (16 → 27 → 28), where the ordering IS the
+// correctness requirement (see the phase-model note above), never a
+// scheduling nicety. A failure stops the chain — the gates after it have a
+// real dependency on what it would have produced, unlike the pool below.
+async function runGateChain(gates, args) {
+  const results = [];
+  for (const g of gates) {
+    const r = await runGateCaptured(g, args);
+    printGateResult(r);
+    results.push(r);
+    if (!r.ok) break;
+  }
+  return results;
+}
+
+// Runs a list of gates concurrently, capped at `limit` in flight at once —
+// a minimal pool, not a dependency graph: every gate here is fully
+// independent, so order WITHIN the pool carries no meaning, only the cap
+// does. Every gate runs to completion regardless of a sibling's failure
+// (fail-together within the pool — see the file-header note above).
+async function runGatePool(gates, args, limit) {
+  const queue = [...gates];
+  const results = [];
+  async function worker() {
+    while (queue.length) {
+      const g = queue.shift();
+      const r = await runGateCaptured(g, args);
+      printGateResult(r);
+      results.push(r);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, gates.length) }, worker));
+  return results;
+}
+
+// DRY preview stays the original flat serial walk, byte-for-byte — no real
+// process ever spawns in dry mode, so there is no concurrency win to chase,
+// and selftest()'s exact-output assertions (below) only ever run `--dry`.
+function step3PreFlightDry(args) {
   for (const g of GATE_ROSTER) {
-    // versionArg gates take a MODE-DEPENDENT version (both directions bit
-    // the first 0.8.8 run): cut modes run pre-flight PRE-BUMP, where the
-    // 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. 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;
-    // A RESUMED run's versionArg gates (cut-hygiene) demand artifacts Step 4
-    // has not recreated yet — docs/ops/releases/vX.Y.Z.md exists only after 4e,
-    // which runs AFTER this pre-flight. Step 4g re-runs these same gates at
-    // the cut version once the notes exist, so skipping them here loses no
-    // coverage — running them here false-fails by construction (the v0.8.32
-    // cut hit exactly this: 23/24 green, gate 24 dead on the missing notes).
-    if (g.versionArg && args.resume) {
+    const cmd = resolveGateCommand(g, args);
+    if (cmd === null) {
       console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${g.cmd}   # ${g.what} — [resume] deferred to Step 4g (notes not regenerated yet)`);
       continue;
     }
-    // targetVersionArg (gh#1135, REQ-06) is a distinct flag from versionArg:
-    // write-eval-health.mjs NAMES a new file after the cut's target version
-    // from the very start — there is no pre/post-bump claim to reconcile
-    // the way gate 24's README-currency check has, so it always takes
-    // `args.version` verbatim regardless of mode or resume.
-    const cmd = g.versionArg
-      ? `${g.cmd} --version ${hygieneVersion}`
-      : g.targetVersionArg
-        ? `${g.cmd} --version ${args.version}`
-        : g.cmd;
     console.log(`\n  ${g.n}/${GATE_ROSTER.length}. ${cmd}   # ${g.what}`);
-    try {
-      sh(cmd, args, { stdio: 'inherit' });
-    } catch (e) {
-      console.error(`\n  ✗ FAILED (${g.n}/${GATE_ROSTER.length}): ${cmd}`);
-      console.error('  Pre-flight aborted. Fix the gate failure before proceeding.');
-      console.error('  See references/gates-catalog.md for failure-mode → recovery.');
-      process.exit(1);
-    }
+    sh(cmd, args, { stdio: 'inherit' }); // dry: logs `[dry] cmd`, never executes
+  }
+  console.log(`\n  ✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`);
+}
+
+async function step3PreFlight(args) {
+  if (args.skipGates) {
+    console.log('\n=== Step 3 — Pre-flight (SKIPPED via --skip-gates; danger!) ===');
+    return;
+  }
+  console.log(`\n=== Step 3 — Pre-flight gates (${GATE_ROSTER.length}-gate roster — gate-roster.mjs) ===`);
+  if (args.dry) {
+    step3PreFlightDry(args);
+    return;
+  }
+
+  const soloGate = GATE_ROSTER.find((g) => g.n === SOLO_GATE_NUMBER);
+  const chainGates = EVAL_HEALTH_CHAIN_NUMBERS.map((n) => GATE_ROSTER.find((g) => g.n === n));
+  const chainNumbers = new Set(EVAL_HEALTH_CHAIN_NUMBERS);
+  const poolGates = GATE_ROSTER.filter((g) => g.n !== SOLO_GATE_NUMBER && !chainNumbers.has(g.n));
+
+  console.log(`\n-- Phase 1/2: gate ${SOLO_GATE_NUMBER} solo (test:unit:serial) --`);
+  const soloResult = await runGateCaptured(soloGate, args);
+  printGateResult(soloResult);
+  if (!soloResult.ok) {
+    console.error('\n  Pre-flight aborted at Phase 1 — fix the gate failure before proceeding.');
+    console.error('  See references/gates-catalog.md for failure-mode → recovery.');
+    process.exit(1);
+  }
+
+  console.log(`\n-- Phase 2/2: ${poolGates.length} gates (concurrency ${PREFLIGHT_CONCURRENCY}) + eval-health chain (gates ${EVAL_HEALTH_CHAIN_NUMBERS.join(' → ')}) --`);
+  const [poolResults, chainResults] = await Promise.all([
+    runGatePool(poolGates, args, PREFLIGHT_CONCURRENCY),
+    runGateChain(chainGates, args),
+  ]);
+
+  const allResults = [soloResult, ...poolResults, ...chainResults].sort((a, b) => a.n - b.n);
+  const failed = allResults.filter((r) => !r.ok);
+  if (failed.length > 0) {
+    console.error(`\n  ✗ ${failed.length}/${GATE_ROSTER.length} gate(s) FAILED: ${failed.map((r) => r.n).join(', ')}`);
+    console.error('  Pre-flight aborted. Fix the gate failure(s) before proceeding.');
+    console.error('  See references/gates-catalog.md for failure-mode → recovery.');
+    process.exit(1);
   }
   console.log(`\n  ✓ all ${GATE_ROSTER.length}/${GATE_ROSTER.length} gates passed`);
 }
@@ -1129,7 +1331,7 @@ async function main() {
     process.exit(2);
   }
   step1ReBaseline(args);
-  step3PreFlight(args);
+  await step3PreFlight(args);
   step4PromoteAndBump(args);
   step5Commit(args);
   // Invariant 3 (operator ruling 2026-07-12): release commits land via PR,

package/skills/primitive-authoring/references/api-contract.md

@@ -143,6 +143,41 @@ pixel-diff/visual-eval gate, not unit tests or review alone. Source:
 [ADR-0081](../../../../../../docs/ops/adr/adr-0081-chart-2-0-foundations-attribute-grammar.md)
 Amendment (2026-08-21).
 
+## Canonical breakpoint scale (adr-0089)
+
+[verified 2026-08-25, gh#1984] `core/responsive.js`'s `BREAKPOINTS` export is
+the single canonical reference for any device-class threshold, whether the
+query mechanism is `@media` (the five sanctioned viewport primitives —
+`grid-ui`, `col-ui`, `row-ui`, `block-ui`, `text-ui` — plus top-layer/popover
+positioning with no ancestor box to query) or `@container` (everything else,
+per `adr-0088` — `spec-breakpoint-convention` REQ-004 forbids importing
+`core/responsive.js` itself outside those cases). This table MUST match
+`core/responsive.js`'s `BREAKPOINTS` export byte-for-byte — a gap here was
+exactly the drift `spec-breakpoint-convention` REQ-007 named and closed:
+
+| Name | Min-width |
+| --- | --- |
+| `xs` | `0` |
+| `sm` | `480px` |
+| `md` | `768px` |
+| `lg` | `1024px` |
+| `xl` | `1280px` |
+
+A `@container`/`@media` rule can't read a CSS custom property at parse time
+(forbidden-pattern #2 in [token-contract.md](token-contract.md)), so these
+values are cited as raw literals in component CSS, never tokenized — but
+every such literal MUST carry a preceding comment naming the rung it
+implements (device-class threshold) or the ergonomic reason for the number
+(a component-intrinsic threshold, exempt from this table entirely — `nav-ui`'s
+96px icon-rail floor, `table-toolbar-ui`'s compaction stages, `chart-ui`'s
+200px legend-hide are correctly exempt and are NOT migration candidates).
+`packages/web-components/core/breakpoint-observer.js` is the shared
+`ResizeObserver`-to-attribute helper for a component that needs
+JS-observable state (relocating a node, switching a positioning strategy)
+rather than a pure CSS layout switch — see its own module doc for the
+boolean-vs-named-value reflection modes. Full requirements:
+[spec-breakpoint-convention](../../../../../../docs/ops/spec/spec-breakpoint-convention.md).
+
 ## Numeric props — `null` over sentinels
 
 Indeterminate, unknown, or "not yet set" numeric state uses `null`, not `-1` or `Infinity`: