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

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
@@ -120,6 +122,8 @@ npm run eval:diff -- --engine free-form                    # 27 fresh free-form
 node scripts/release/write-eval-health.mjs --version <cut>  # 28 evals/health/<version>.json committed, AC-01/AC-02 run for real (gh#1135, WS-4 SPEC REQ-06)
 node scripts/release/check-estate-split-latch.mjs           # 29 no lockstep cut mid estate-split (ADR-0048 / gh#1192) — see the note below
 npm run check:catalog-tiers                    # 30 tier-index.json vs committed catalog (gh#1494 — ADR-0069 moved its PR-blocking half to derived-resync; the pre-cut roster re-asserts Class-R freshness before a tag. Gate 13 can't catch this: the harvester hashes tier-index.json as a SOURCE)
+npm run check:codex-manifests-fresh            # 31 Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT (gh#1888)
+npm run check:harness-manifests-fresh          # 32 Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT (gh#1954)
 ```
 
 **Gate 29 was the ADR-0048 latch; since P5 it is a permanent invariant.** Between P1 and P5 the repo was correct in-repo but deliberately **not publishable** (old-name stubs marked `private: true` that the roster still mapped, plus dependency edges onto workspace packages no cut published), and a cut in that window would have shipped broken packages that npm cannot unpublish. **P5 cleared it by landing the real thing** — the six stubs became publishable shims and `PACKAGE_ROSTER` gained the three remaining new names, at which point all 9 offending edges resolved and the gate went green on its own. No gate logic was changed.
@@ -153,6 +157,8 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 **4d.6. Regenerate the Codex plugin manifests** (gh#1888, gh#1899): `node scripts/build/codex-manifests.mjs`, then `npm run check:codex-manifests-fresh` to confirm. Both plugins' `.codex-plugin/plugin.json` embed `version` from `.claude-plugin/plugin.json`, which the 4b bump just moved — same "derived artifact carries the lockstep version" class as 4d.5's genui catalog. Gate 31 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; nothing re-ran the generator post-bump before this line existed — the v0.8.48 release PR (#1897) shipped stale manifests as a result, caught by `check:codex-manifests-fresh` in CI and fixed by hand on the release branch. `packages/plugins/*/.codex-plugin/plugin.json` and `packages/plugins/*/skills/*/agents/openai.yaml` ride the release commit (Step 5 stages them).
 
+**4d.7. Regenerate the Hermes/Pi plugin manifests** (gh#1954): `node scripts/build/harness-manifests.mjs`, then `npm run check:harness-manifests-fresh` to confirm. Same hazard as 4d.6, same fix — both plugins' `plugin.yaml` embed `version` from `.claude-plugin/plugin.json`. Gate 32 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; run this post-bump every cut, not just when a skill/command changed. `packages/plugins/*/plugin.yaml`, `packages/plugins/*/__init__.py`, `packages/plugins/*/hermes-mcp.yaml` (factory only), and `packages/plugins/*/prompts/*.md` ride the release commit (Step 5 stages them).
+
 **4e. Release docs + team notes** (gated, not optional): review the entry
 files the release touches (root README/CHANGELOG, per-package READMEs —
 content currency is YOUR judgment; the gate only proves presence), then
@@ -215,6 +221,7 @@ npm install --package-lock-only --no-audit --no-fund
 npm run check:lockstep                                                                        # 4d
 node scripts/build/derive-genui-catalog.mjs                                                   # 4d.5 — catalogId carries the bumped version (gh#617)
 node scripts/build/codex-manifests.mjs                                                        # 4d.6 — Codex manifest version carries the bumped version (gh#1899)
+node scripts/build/harness-manifests.mjs                                                      # 4d.7 — Hermes/Pi manifest version carries the bumped version (gh#1954)
 node scripts/release/check-release.mjs --pending-version X.Y.Z --fix                          # 4f — AFTER the stubs exist
 node scripts/release/generate-release-notes.mjs --version X.Y.Z --write                       # 4e
 node scripts/release/check-release-docs.mjs --version X.Y.Z                                   # 4e gate

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

@@ -137,6 +137,11 @@ export const GATE_ROSTER = [
   // hazard the same way a stale dist bundle is a real Claude-install
   // hazard. Appended, not inserted — same numbering discipline as gate 30.
   { n: 31, cmd: 'npm run check:codex-manifests-fresh', what: 'Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT' },
+  // gh#1954: the Hermes (plugin.yaml + __init__.py + hermes-mcp.yaml) and Pi
+  // (prompts/*.md) external-distribution overlays are derived the same way
+  // gate 31's Codex tree is — a stale copy is the same real install hazard.
+  // Appended, not inserted — same numbering discipline as gate 30/31.
+  { n: 32, cmd: 'npm run check:harness-manifests-fresh', what: 'Hermes/Pi plugin.yaml + __init__.py + prompts vs .claude-plugin/plugin.json + commands SoT' },
 ];
 
 // -- CLI ------------------------------------------------------------------

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/INDEX.md

@@ -16,7 +16,7 @@ file, including the depth references those entries cross-link.
 - [api-contract.md](api-contract.md) — how do I declare `static properties` (type, default, reflect, attribute), avoid the `attr:` silent-typo trap, and expose a selection-item's `selected` state (declared reflected prop, never a `data-*` stamp — ADR-0056)?
 - [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?
+- [css-patterns.md](css-patterns.md) — how do I structure a component stylesheet: two-block `@scope`, variants vs modes, token layering, deriving an inset item's border-radius from its rounded container (concentric-corner radius)?
 - [lifecycle-patterns.md](lifecycle-patterns.md) — how do I keep `connected()`/`disconnected()` symmetric for listeners, timers, observers, and popovers?
 - [svg-authoring.md](svg-authoring.md) — viewBox/coordinate scaling, stroke-width, text-anchor/dominant-baseline, card-bleed clipping, currentColor vs `var()` inside SVG markup, hit-testing — for `chart-ui`/`qr-code-ui`/`icon-ui`/any new `<svg>`-emitting primitive.
 - [form-control-sizing.md](form-control-sizing.md) — does a form-control host fill its container or hug its content, and where does the legibility floor live (ADR-0077)?