@adia-ai/adia-ui-forge 0.8.62 → 0.8.64

package/skills/a2ui-maintenance/references/zettel-calibration.md

@@ -1,4 +1,4 @@
-# Zettel calibration — constants + history + locator/modifier two-pass
+# Zettel calibration, constants + history + locator/modifier two-pass
 
 **Calibration history is the substrate.** Each tweak left a trail; the same
 value may have been tried and rejected before. Recover any decision's context
@@ -20,8 +20,8 @@ is calibrated against the held-out intent set or production telemetry.
   "form"/"page" score 1/1/0/0), plus **+3 per distinct content token matched**;
   a candidate needs ≥2 content-token hits OR a direct name-token hit to score
   at all. Adding/removing corpus entries does not shift any specific
-  (query, composition) score — the sum is deterministic per pair. **Don't
-  recalibrate as a function of corpus size** — that's a misdiagnosis.
+  (query, composition) score: the sum is deterministic per pair. **Don't
+  recalibrate as a function of corpus size**, that's a misdiagnosis.
   Practical consequence: short queries need their entity words IN the chunk
   name to clear 40.
 - **Tradeoff**: more LLM calls (slower, costlier) ↔ compositional variety.
@@ -33,37 +33,35 @@ is calibrated against the held-out intent set or production telemetry.
 - **Scale**: corpus-size-**independent** absolute keyword score from
   `chunk-library.js#keywordScore()`: first name-word matches a token **+10**,
   full-query substring **+5**, whole-word token in name **+3**, substring /
-  haystack hits **+1** each. Anything below 8 is a "retrieval too weak —
-  synthesize" signal.
+  haystack hits **+1** each. Anything below 8 is a "retrieval too weak, synthesize" signal.
 - **Async path**: `searchChunksAsync` blends `kw + cos*5`. Cosine ranges 0..1,
-  so embeddings contribute 0..5 — a pure-cosine match maxes at 5 and can never
+  so embeddings contribute 0..5, a pure-cosine match maxes at 5 and can never
   clear 8 alone. **Embeddings are a tie-breaker, not the primary signal. This
   is intentional** (WONTFIX): letting cosine clear the fast-path gate made
   retrieval non-deterministic and flipped top-1 rankings unpredictably.
 - **Different scale** than `STRONG_MATCH_THRESHOLD=40` (which scores
-  name/keyword/tag/description sums). Never normalize the two — they measure
+  name/keyword/tag/description sums). Never normalize the two, they measure
   different things.
 
 ## `PRE_SEARCH_LIMIT = 30`
 
 - **Files**: `chunk-synthesizer.js` + `chunk-refiner.js` (`grep -n PRE_SEARCH_LIMIT`)
-- **Reason**: token-budget mitigation — pre-filter the catalog before the LLM
+- **Reason**: token-budget mitigation, pre-filter the catalog before the LLM
   sees it; the full catalog per prompt would burn tens of thousands of tokens.
-- **Synthesizer**: kind-aware allocation —
-  `limit: PRE_SEARCH_LIMIT - pageChunks.length - panelChunks.length`. All pages
+- **Synthesizer**: kind-aware allocation, `limit: PRE_SEARCH_LIMIT - pageChunks.length - panelChunks.length`. All pages
   and panels ride unconditionally; blocks fill the remainder. Self-tuning by
   structure.
 - **Refiner**: block-only `limit: PRE_SEARCH_LIMIT`, plus all pages/panels on
-  top — intentionally more generous because refinement does targeted edits and
+  top, intentionally more generous because refinement does targeted edits and
   the LLM needs options.
-- **Don't naively divide by corpus size** to assess over-permissiveness — the
+- **Don't naively divide by corpus size** to assess over-permissiveness, the
   kind-aware allocation makes the math non-linear.
 
 ## `SCOPE_DRIFT_RATIO = 1.5` + `SCOPE_DRIFT_MIN_ACTUAL = 20`
 
 - **File**: `chunk-synthesizer.js` (exported; `grep -n SCOPE_DRIFT`)
 - Composed envelope's component count > 1.5× the sum of bound chunks' counts
-  auto-fires a `scope-drift` issue — catches LLM creative expansion that
+  auto-fires a `scope-drift` issue, catches LLM creative expansion that
   hallucinates components beyond the bound chunks.
 - The MIN_ACTUAL=20 floor kills false positives on small UIs where
   slot-wrapper noise dominates: <20 components never trips the gate.
@@ -77,7 +75,7 @@ is calibrated against the held-out intent set or production telemetry.
 ## `DEFAULT_MAX_SIZE = 64` (state-cache)
 
 - **File**: `state-cache.js:27`; override via `A2UI_STATE_CACHE_SIZE` env var.
-- Per-process, in-memory — survives only as long as the MCP server; multi-turn
+- Per-process, in-memory, survives only as long as the MCP server; multi-turn
   refinement breaks across restarts.
 - **Eviction**: LRU on `set` at capacity; `get` and overwriting `set` touch
   recency; `peek` reads without touching.
@@ -91,11 +89,11 @@ is calibrated against the held-out intent set or production telemetry.
 
 Multi-turn refinements use two LLM passes:
 
-1. **Locator** — given the intent + a component map of slots and their bound
+1. **Locator**, given the intent + a component map of slots and their bound
    chunks, classifies the intent as `targeted` (specific slot/element named or
    verb implies a localized change) vs `untargeted` (broad: "more compact",
    "use teal").
-2. **Modifier** — emits ops from a fixed vocabulary:
+2. **Modifier**, emits ops from a fixed vocabulary:
    `{ rebindSlot, appendToSlot, removeFromSlot, replacePage }`, translated to
    A2UI `updateComponents` messages via `opsToA2UI()`.
 

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

@@ -1,17 +1,17 @@
 ---
 name: component-md-authoring
 description: >-
-  Author the two judgment sections of a component's `component.md` —
-  Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a
+  Author the two judgment sections of a component's `component.md`, Screen-reader spec and Behavioral spec, and keep it PR-fresh. Use when a
   component's states, composed children, aria behavior, or error/empty/
   loading handling changes and it already has (or should grow) a
   `component.md`, or when asked to "add component.md for X" / "write the
   screen-reader spec for X" / "why is check:component-md-fresh warning". NOT
   the yaml prop/slot/event/token contract itself (primitive-authoring owns
-  that — this skill only owns the two authored yaml fields,
+  that, this skill only owns the two authored yaml fields,
   `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui
   corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token
-  audit (component-token-audit).
+  audit (a capability referenced from adia-ui-factory's theme-audit skill,
+  not yet a shipped skill here, ticket 10036).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -22,7 +22,7 @@ user-invocable: true
 to its `.yaml` SoT (`packages/web-components/components/<name>/component.md`,
 or `packages/web-modules/<cluster>/<name>/component.md` for a composite/
 shell). Every section except two is mechanically transcluded from the yaml
-by `scripts/build/gen-component-md.mjs` — Intent, API (props/events/slots),
+by `scripts/build/gen-component-md.mjs`, Intent, API (props/events/slots),
 Structural (Light DOM anatomy + states + composes), Tokens, Rules,
 Anti-patterns, Related. This skill's whole charter is the two sections that
 aren't: **Screen-reader spec** and **Behavioral spec**.
@@ -30,50 +30,50 @@ aren't: **Screen-reader spec** and **Behavioral spec**.
 ## The load-bearing decision: where the authoring happens
 
 You do not hand-edit `component.md`. You edit the yaml's `screenReader:`
-and `behavioral:` fields (and, ideally, `intent:`) — `component.md` is
+and `behavioral:` fields (and, ideally, `intent:`), `component.md` is
 regenerated from them. This is deliberate, not incidental:
 
 - **No second source of truth.** plan-2615's evidence pass on gh#2615 found
   most of component.md's "intent layer" already lives in the yaml
   (`a2ui.rules`, `anti_patterns`, `related`, examples). The two genuine
-  gaps — screen-reader and behavioral judgment — get the SAME treatment:
+  gaps, screen-reader and behavioral judgment, get the SAME treatment:
   authored once, in yaml, transcluded everywhere else (component.md today;
   gen-ui corpus derivation once a2ui-maintenance wires it in).
 - **`component.md` is Class R, derived on main, not authored in the PR
   (gh#3172, ADR-0069).** Because the authored content lives in a yaml
-  field, `component.md` is 100% mechanically regenerable — a PR commits
+  field, `component.md` is 100% mechanically regenerable, a PR commits
   only the `screenReader`/`behavioral` yaml edit; `check:component-md-fresh`
   runs advisory-only inside `check:pr-ready` (WARN, never fails the run)
   and the `push: main` `derived-resync` job regenerates `component.md`
   itself once the PR merges. A hand-edit directly in `component.md` will
   still be silently clobbered by the next `npm run docs:component-md` or
-  by `derived-resync` on main — that's the guard rail, not a bug, even
+  by `derived-resync` on main, that's the guard rail, not a bug, even
   though nothing blocks the PR on it.
 
 ## Authoring a component's two sections
 
-1. Confirm the component doesn't already have adequate coverage — read its
+1. Confirm the component doesn't already have adequate coverage, read its
    existing `states:`, `a2ui.rules`, and `.class.js` source. Per
    primitive-authoring's own first principle, **source wins**: verify every
    claim you're about to write (focus order, aria attribute names, event
    names) against the actual `.class.js`/`.js` file, not just the yaml
    prose.
-2. **Screen-reader spec** — focus order across composed children (order
+2. **Screen-reader spec**, focus order across composed children (order
    `showModal()`/connect moves focus, what wraps at the tab boundary),
    live-region announcement sequence (what fires `role="alert"` or an
    `aria-live` region, and when), and any keyboard map beyond the trait
-   default (`pressable`/`focusable` already cover Enter/Space/click — only
+   default (`pressable`/`focusable` already cover Enter/Space/click, only
    document what's ADDITIONAL, e.g. arrow-key grid nav, Escape-dismiss).
    Do not restate a static `aria-*` attribute the yaml's `props`/`states`
-   already document plainly — that's derived content, not new judgment.
-3. **Behavioral spec** — dismiss/error/empty/loading states and
+   already document plainly, that's derived content, not new judgment.
+3. **Behavioral spec**, dismiss/error/empty/loading states and
    transitions NOT already modeled by `states:`. Distinguish "fetching" vs
    "confirmed empty" where both exist (see `table.yaml`'s `screenReader`/
    `behavioral` for a worked example: three distinct states, not one).
    Name what is explicitly NOT handled (no built-in error state, no
-   built-in loading state) as clearly as what is — an absence is often the
+   built-in loading state) as clearly as what is, an absence is often the
    more actionable fact for a consumer.
-4. Both fields require `minLength: 20` (schema-enforced) — a placeholder
+4. Both fields require `minLength: 20` (schema-enforced), a placeholder
    one-liner will fail `check:components-valid`. Write real prose, grounded
    in source, not a restatement of the component's `description`.
 5. Regenerate and verify:
@@ -85,7 +85,7 @@ regenerated from them. This is deliberate, not incidental:
    ```
 
 6. If this is the component's FIRST component.md (yaml previously had
-   neither field), run `npm run build:components` too — the corpus/catalog
+   neither field), run `npm run build:components` too, the corpus/catalog
    rebuild picks up the new yaml content, and `npm run eval:diff --
    --engine zettel` should show no regression (preserve-not-regress floor,
    owned by a2ui-maintenance).
@@ -94,10 +94,10 @@ regenerated from them. This is deliberate, not incidental:
 
 `scripts/build/gen-component-md.mjs`'s `SCAN_ROOTS` covers
 `packages/web-components/components/` and `packages/web-modules/chat/`
-today — the pilot 5 (`button`, `modal`, `table`, `field`, `chat-shell`).
+today, the pilot 5 (`button`, `modal`, `table`, `field`, `chat-shell`).
 Extending to every web-modules cluster, or sweeping the remaining ~145
 primitives, is deliberately out of scope for this pass (file a follow-up
-task rather than silently expanding `SCAN_ROOTS` for one-off need — a
+task rather than silently expanding `SCAN_ROOTS` for one-off need, a
 cluster added there without a plan for authoring every component inside it
 just produces components with a `.yaml` but no eligible `component.md`,
 which the generator already handles gracefully by skipping them, but which
@@ -109,12 +109,12 @@ defeats the point of a rollout plan).
   behavior → component-md-authoring's authored sections may need a pass"
   to your own SoT-change checklist when editing a yaml that already has a
   `component.md` sibling.
-- `scripts/schemas/component.yaml.schema.json` — `intent`/`screenReader`/
+- `scripts/schemas/component.yaml.schema.json`, `intent`/`screenReader`/
   `behavioral` field definitions (all optional; a component with a `.yaml`
   but neither authored field simply has no `component.md` yet).
-- `scripts/verify/check-component-md-fresh.mjs` — the freshness gate:
+- `scripts/verify/check-component-md-fresh.mjs`, the freshness gate:
   byte-freshness (component.md matches a fresh render). Advisory-only in
-  `check:pr-ready` (gh#3172, ADR-0069) — a PR commits the yaml edit alone
+  `check:pr-ready` (gh#3172, ADR-0069), a PR commits the yaml edit alone
   and `derived-resync` regenerates `component.md` on `push: main`; the
   same-PR coverage check this gate used to run was removed outright
   (LLD-0020 §1c), not demoted.

package/skills/component-md-authoring/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Component Md Authoring"
-  short_description: "Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh."
+  short_description: "Author the two judgment sections of a component's `component.md`, Screen-reader spec and Behavioral spec, and keep it PR-fresh."

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

@@ -2,35 +2,35 @@
 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,
+  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
+  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
+# 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
+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
+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
+  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.
@@ -40,37 +40,37 @@ shape, and never invent a CLI subcommand you have not seen documented or confirm
 | 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 |
+| 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
+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
+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.
+  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
+  (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
+  explicitly before promising support, a silent no-op MCP install is the worst failure
   mode this skill exists to prevent.
 
 ## The common starting prompt
@@ -80,20 +80,19 @@ 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
+- **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):
+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):
+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.
@@ -104,8 +103,7 @@ Good (Codex/Pi/Hermes — same routing, no agent dependency):
 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.
+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
 

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

@@ -1,3 +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."
+  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

@@ -3,7 +3,7 @@ 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
+  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
@@ -18,18 +18,18 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-# cross-harness-compatibility-standards — build it portable, don't just document it
+# 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
+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
+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)/
@@ -38,10 +38,10 @@ and its companion
 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
+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]`
+## 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:
@@ -49,7 +49,7 @@ 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
+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.
 
@@ -57,31 +57,31 @@ 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
+  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
+  `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
+  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,
+  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]`
+## 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
+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):
 
@@ -90,14 +90,15 @@ how `ui-architect`'s Pi and Hermes adapters were actually built (PR #2000):
   `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
+  `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, ...)` —
+  Agent's own source, `PluginContext.register_command` + `dispatch_tool`,
+  and, inside that same external Hermes Agent install (not a path in this
+  repo), `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`
@@ -105,29 +106,29 @@ how `ui-architect`'s Pi and Hermes adapters were actually built (PR #2000):
   *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
+  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
+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.
+fields) must exist, never neither, never both.
 
-## Rule 3 — one authored copy, many thin consumers
+## 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,
+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
+  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
@@ -141,36 +142,36 @@ hand-copied prose duplicate:
 
 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
+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
+## 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
+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
+`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
+(`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
+covers it under a different name, reuse beats a fourth near-duplicate
 grammar.
 
-## Rule 5 — name distribution channels distinctly
+## 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
+collision, both channels sharing one marketplace name, makes
 `<plugin>@<marketplace-name>` resolution ambiguous for a consumer trying to
 install from a specific channel.
 
@@ -178,18 +179,18 @@ 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
+(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
+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
+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.

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

@@ -1,3 +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)."
+  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)."