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

package/skills/a2ui-maintenance/references/leverage-rules.md

@@ -1,7 +1,7 @@
-# Leverage rules — when a repeated subtree earns its own corpus entry
+# Leverage rules, when a repeated subtree earns its own corpus entry
 
 Historical note first: the zettel **fragment mechanism is retired**
-(`$fragment` refs now render as visible drift placeholders — see
+(`$fragment` refs now render as visible drift placeholders, see
 `compose/strategies/zettel/composer.js`). The leverage discipline below
 outlived the mechanism: it now governs whether a repeated subtree gets split
 into its own `data-chunk` block vs staying inline in its parent chunk, and it
@@ -9,13 +9,13 @@ is the calibration for any future extraction tier.
 
 ## The leverage rule
 
-**Do not extract a reusable unit unless it has leverage ≥ 3** — at least 3
+**Do not extract a reusable unit unless it has leverage ≥ 3**, at least 3
 consumers would use it. Two exceptions:
 
-1. **Singleton closing a semantic gap** — a distinct domain primitive (e.g. a
+1. **Singleton closing a semantic gap**, a distinct domain primitive (e.g. a
    keyboard-shortcut row) justifies extraction at leverage 1 because the
    concept itself needs to be retrievable.
-2. **Intra-composition multi-use** — one composition instantiating the same
+2. **Intra-composition multi-use**, one composition instantiating the same
    subtree N ≥ ~10 times justifies extraction; reuse is measured per instance,
    not per referencing composition. Historical evidence: `calendar-day-cell`
    used 35× inside one calendar composition lifted corpus reuse 26.4% → 33.5%
@@ -46,7 +46,7 @@ corpus split, DO NOT lower the threshold. In order:
 
 1. Verify the parent's keywords were preserved (above).
 2. Check the new entry's name/description doesn't cannibalize the parent's
-   semantic space (retrieval collision — see
+   semantic space (retrieval collision, see
    [semantic-fail-lifting](semantic-fail-lifting.md) Strategy B).
 3. Only then consider threshold work, with
    [zettel-calibration](zettel-calibration.md) history read first.

package/skills/a2ui-maintenance/references/mcp-pipeline-ops.md

@@ -1,9 +1,9 @@
-# MCP pipeline operations — generate → validate → render → feedback
+# MCP pipeline operations, generate → validate → render → feedback
 
 Operator workflows against the a2ui MCP server. Tool schemas + wrappers:
 [mcp-tool-reference](mcp-tool-reference.md).
 
-## Full pipeline — one command
+## Full pipeline, one command
 
 ```bash
 node scripts/mcp-pipeline.cjs "dashboard with 4 stat cards and a revenue chart"
@@ -22,7 +22,7 @@ echo '<paste-messages-json>' | node scripts/a2ui-to-html.cjs
 node scripts/mcp-call.cjs check_anti_patterns '{"html":"<paste-rendered-html>"}'
 ```
 
-`validate_schema` is fast and deterministic — batch it over
+`validate_schema` is fast and deterministic, batch it over
 `packages/gen-ui/engine/corpus/chunks/*.json` templates to surface corpus drift without
 re-running the generator.
 
@@ -51,18 +51,18 @@ node scripts/mcp-call.cjs refine_composition '{"state_id":"abc123","intent":"add
 
 Two-pass synthesis (locator → modifier), validator-driven retry
 (`maxAttempts=2`). Each refinement chains through `parent_state_id`; walk
-history with `get_state`. The state cache is in-memory and bounded — after an
+history with `get_state`. The state cache is in-memory and bounded, after an
 MCP server restart, re-run `compose_from_chunks` for a fresh `state_id`.
 
 ## Reporting issues
 
 When the engine breaks expectations, fire `report_issue` with the most recent
 `state_id` (reporter: `llm` for agent self-fire, `user` for a human request).
-The record lands in the engine-internal telemetry store — scratch data for
+The record lands in the engine-internal telemetry store, scratch data for
 diagnosis. **[corrected 2026-08-23, ADR-0008 amendment]** that store is
 `qa/findings/issues/<issue_id>.json`
 (`packages/gen-ui/engine/compose/strategies/zettel/issue-reporter.js:10,26`,
-`DEFAULT_STORAGE_ROOT`) — not the original `.brain/audit-history/issues/`
+`DEFAULT_STORAGE_ROOT`), not the original `.brain/audit-history/issues/`
 path, which was retired. Anything worth durable tracking (a recurring
 pattern, a fix proposal) belongs in a GitHub issue or the PR description of
 the fixing change.
@@ -88,20 +88,19 @@ gap registry (`packages/gen-ui/engine/corpus/gaps/registry.json`).
 
 ### Human signal (gh#668)
 
-Every score in the store except a rating is self-graded — the validator marking
+Every score in the store except a rating is self-graded, the validator marking
 its own homework. Human thumbs are the only outside signal, and they arrive two
 ways, both through the SAME function
 (`packages/gen-ui/a2ui/retrieval/feedback/submit-feedback.js`) into the same JSONL:
 
 - `submit_feedback` (MCP), and
-- `POST /api/feedback` from a rendered surface — today the gen-UI gallery's
+- `POST /api/feedback` from a rendered surface, today the gen-UI gallery's
   `<agent-feedback-bar-ui>` row (thumbs-up = rating 5, thumbs-down = 2).
 
 `get_training_gaps` ranks weak domains on `blendedScore`
 (`retrieval/feedback/human-signal.js`): `0.7 * humanScore + 0.3 * selfScore`
 where a domain has both signals, `humanScore` alone where it has no self-grade,
-`selfScore` alone where it has no thumbs. **A missing signal is not a zero** —
-weighting an absent self-grade as 0 would rank a domain humans unanimously
+`selfScore` alone where it has no thumbs. **A missing signal is not a zero**, weighting an absent self-grade as 0 would rank a domain humans unanimously
 approved below an unrated one the validator liked. So a domain the pipeline
 scores 99 and humans thumb down ranks weak, not strong; `selfScore` averages
 execution scores plus any `score` a rating carries inline, and `engine` /

package/skills/a2ui-maintenance/references/mcp-tool-reference.md

@@ -1,7 +1,7 @@
-# MCP tool reference — the a2ui server's tool surface
+# MCP tool reference, the a2ui server's tool surface
 
-**Schema SoT is `packages/gen-ui/mcp/TOOLS.md` (the `gen-ui` section — 31 tools),
-generated alongside `server.js` — read it for input/output shapes; never
+**Schema SoT is `packages/gen-ui/mcp/TOOLS.md` (the `gen-ui` section, 31 tools),
+generated alongside `server.js`, read it for input/output shapes; never
 restate schemas here (they drift).** Tools register in
 `packages/gen-ui/mcp/gen-ui/server.js` +
 `packages/gen-ui/mcp/gen-ui/tools/{corpus,discovery,feedback,refine,synthesis,
@@ -10,10 +10,10 @@ validation,zettel}.js`. Any tool change updates TOOLS.md in the same commit.
 ## Stability rule (load-bearing)
 
 Changing an existing tool's input/output contract is a breaking change for
-every external MCP client. The full producer-side rule — dry-run schema diff,
+every external MCP client. The full producer-side rule, dry-run schema diff,
 explicit operator proceed, `@adia-ai/mcp` version bump, factory pin
 update, and the consumer-load-bearing subset whose contracts are
-frozen-unless-versioned — lives in
+frozen-unless-versioned, lives in
 [../../../references/contracts/a2ui-mcp-surface.md](../../../references/contracts/a2ui-mcp-surface.md).
 Adding tools is additive and safe; removing or renaming is breaking.
 
@@ -36,25 +36,24 @@ Selection heuristics:
 - **Fresh creation from a known page-shape** → `compose_from_chunks`
   (retrieval-first); generic/novel intent → `generate_ui`.
 - **Modifying an existing surface** ("change", "add to", "remove") →
-  `refine_composition` with the prior `state_id` — never re-generate.
+  `refine_composition` with the prior `state_id`, never re-generate.
 - **Catalog literacy** → `lookup_component` / `get_component_map`; the MCP is
-  the live catalog — don't memorize component names.
+  the live catalog, don't memorize component names.
 - **Trust gate on any LLM-emitted A2UI** → `validate_schema` then
   `check_anti_patterns` on the rendered HTML.
 
 ## Local wrappers (all verified in `scripts/`)
 
-- `scripts/mcp-pipeline.cjs "<intent>"` — full pipeline one-shot with a
+- `scripts/mcp-pipeline.cjs "<intent>"`, full pipeline one-shot with a
   combined report.
-- `scripts/mcp-call.cjs <tool> '<json-args>'` — single-tool call for stepping
+- `scripts/mcp-call.cjs <tool> '<json-args>'`, single-tool call for stepping
   through / inspecting intermediates.
-- `scripts/a2ui-to-html.cjs [file|stdin]` — renders A2UI message arrays to
+- `scripts/a2ui-to-html.cjs [file|stdin]`, renders A2UI message arrays to
   HTML between `validate_schema` and `check_anti_patterns`.
 
 ## When adding a tool
 
 1. Register in the matching `mcp/tools/<group>.js` file (zod input schema +
    description that names its trigger phrases and its non-goals).
-2. Update `TOOLS.md` in the same commit (generated with the server build —
-   `npm run build:mcp-server`).
+2. Update `TOOLS.md` in the same commit (generated with the server build, `npm run build:mcp-server`).
 3. Verify: `npm run mcp:smoke`, then a real-client round-trip.

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

@@ -1,35 +1,35 @@
-# Pipeline overview — generator + retrieval + engines (mode: modify pipeline internals)
+# Pipeline overview, generator + retrieval + engines (mode: modify pipeline internals)
 
-## Protocol layers — v1.0 Candidate terms
+## Protocol layers, v1.0 Candidate terms
 
 Two protocol layers coexist (ADR-0059, `docs/ops/spec/spec-a2ui-v1-conformance.md`):
 the shipping dialect this pipeline emits (Layer A, `packages/gen-ui/a2ui/`) and
 the A2UI v1.0 Candidate stack (Layer B, `packages/genui/`) reached
 through `packages/genui/wire-bridge/`. **[amended 2026-08-29, ADR-0096]**
 `adiahealth/gen-ui-system` is absorbed first-party under `packages/genui/`
-and the standalone repo is archived — Layer B is in-repo source, not a
+and the standalone repo is archived, Layer B is in-repo source, not a
 vendored dependency; `VENDOR.json` and the sync mechanism are gone (see
 this same note on siblings `data-model-reactivity.md` and
 `surface-lifecycle.md`). Candidate terminology is
-**renderer/agent** — never client/server: `callableFrom` values are
+**renderer/agent**, never client/server: `callableFrom` values are
 `rendererOnly`/`agentOnly`/`rendererOrAgent`; the wire function kinds are
 `callRendererFunction`/`callAgentFunction` +
 `rendererFunctionResponse`/`agentFunctionResponse`; the MIME type is
 `application/a2ui+json`; catalog resolution is strict (component `catalogId` →
 surface `catalogId` → error, no registry default). The producer's
 `wireFormat` flag (`packages/genui/adia-producer/exit-gate.js`) **[flipped
-2026-08-30, PR #2412]** now defaults to `'v1'`, not `'dialect'` — ADR-0072
+2026-08-30, PR #2412]** now defaults to `'v1'`, not `'dialect'`, ADR-0072
 ratified the flip (its precondition, genui-system#51's re-verification,
 re-scoped and satisfied via ADR-0096/PR #2401) and the flip itself has since
 executed. Documents authored here stay dialect-shaped; the bridge owns the
-translation — never hand-write Candidate envelopes from this skill's
+translation, never hand-write Candidate envelopes from this skill's
 surfaces.
 
 **Catalogs are opt-out scopes, not a taxonomy.** A2UI v1.0 lets a renderer
 mix catalogs within one surface: `createSurface.catalogId` is the default,
 and any component may carry its own `catalogId` to override it
 (a2ui.org/specification/v1.0-a2ui/, "Catalog Reference"). So the useful way
-to split a catalog is by what an app OMITS, never by component kind — Buttons
+to split a catalog is by what an app OMITS, never by component kind, Buttons
 and Inputs are never omitted together, whole feature areas are. This is the
 ratified basis of the five-catalog partition (gh#2211, Kim 2026-08-28):
 `adia.core` / `adia.navigation` / `adia.data` / `adia.agent` / `adia.shells`,
@@ -51,17 +51,15 @@ ruling was load-bearing on `wireFormat` defaulting to `'dialect'`, with a
 **Named expiry**: the flag-flip ADR that makes `'v1'` the shipping default
 had to re-rule site-a2ui's fitness (re-point vs retirement-by-attrition).
 
-**[resolved, ADR-0072 — retired 2026-08-31]** That trigger fired and was
+**[resolved, ADR-0072, retired 2026-08-31]** That trigger fired and was
 ruled: retirement, not re-point (Decision 2). Passive attrition never
-netted the promoted set down (355 pages and growing at last measurement —
-regen work kept adding rows faster than breakage retired them), so the
-operator converted it to an active drain (gh#2410): the mechanism —
-builder, ledger, artifact tree, gates, hook — is gone. The docs site now
+netted the promoted set down (355 pages and growing at last measurement, regen work kept adding rows faster than breakage retired them), so the
+operator converted it to an active drain (gh#2410): the mechanism, builder, ledger, artifact tree, gates, hook, is gone. The docs site now
 renders every route through the legacy template path only; site-a2ui is
 no longer part of this pipeline. The dialect side's regression-corpus
 coverage site-a2ui once provided (real-content-scale exercise of the
 dialect renderer, the ADR-0061 lifecycle path, and the engine transpiler)
-has no standing replacement — see ADR-0072 Decision 2 / gh#2410 for the
+has no standing replacement, see ADR-0072 Decision 2 / gh#2410 for the
 closure record.
 
 All paths repo-relative. Specs worth reading before structural changes:
@@ -90,21 +88,21 @@ for any constant or decision lives in git and PR descriptions
 
 | File | Role |
 | --- | --- |
-| `packages/gen-ui/engine/compose/core/generator.js` | `generate_ui` orchestrator — instant / pro / thinking / stream modes; multi-turn via `executionId` |
-| `packages/gen-ui/engine/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `monolithic-instant`, `monolithic-pro`, `monolithic-thinking`, `zettel`, `chunk-zettel`, `free-form` |
-| `packages/gen-ui/engine/compose/strategies/zettel/` | Zettel + chunk-zettel engines — see [strategy-engines](strategy-engines.md) for the per-file map |
+| `packages/gen-ui/engine/compose/core/generator.js` | `generate_ui` orchestrator, instant / pro / thinking / stream modes; multi-turn via `executionId` |
+| `packages/gen-ui/engine/compose/strategies/registry.js` | Engine registry, `registerEngine(name, factory)`. Reserved names: `monolithic`, `monolithic-instant`, `monolithic-pro`, `monolithic-thinking`, `zettel`, `chunk-zettel`, `free-form` |
+| `packages/gen-ui/engine/compose/strategies/zettel/` | Zettel + chunk-zettel engines, see [strategy-engines](strategy-engines.md) for the per-file map |
 | `packages/gen-ui/engine/compose/strategies/free-form-composer/` | Free-form engine (`index.js`, `system-prompt.js`, `transpile.js`) |
 | `packages/gen-ui/engine/compose/strategies/_shared/chunk-loader.js` | Shared chunk loading for engines |
-| `packages/gen-ui/engine/compose/shared/validate-and-repair.js` | Shared closed-loop validate→repair, adopted by every LLM-calling engine (thinking/pro fully; free-form validate-only) — see [strategy-engines](strategy-engines.md) §Closed-loop validation |
+| `packages/gen-ui/engine/compose/shared/validate-and-repair.js` | Shared closed-loop validate→repair, adopted by every LLM-calling engine (thinking/pro fully; free-form validate-only), see [strategy-engines](strategy-engines.md) §Closed-loop validation |
 | `packages/gen-ui/engine/compose/transpiler/transpiler.js` | HTML → A2UI transpile pass (used by harvester + convert_html) |
 
 ### Corpus + retrieval
 
 | File | Role |
 | --- | --- |
-| `packages/gen-ui/engine/corpus/scripts/chunk-library.js` | Chunk catalog API — `getChunk()`, `searchChunks()` (keyword), `searchChunksAsync()` (keyword + cosine), `listChunksByKind()`, `lookupChunksByPrimary()`. Reads `corpus/chunks/` + `_index.json` (moved from `packages/gen-ui/a2ui/` under ADR-0048's package split — corrected 2026-08-16) |
+| `packages/gen-ui/engine/corpus/scripts/chunk-library.js` | Chunk catalog API, `getChunk()`, `searchChunks()` (keyword), `searchChunksAsync()` (keyword + cosine), `listChunksByKind()`, `lookupChunksByPrimary()`. Reads `corpus/chunks/` + `_index.json` (moved from `packages/gen-ui/a2ui/` under ADR-0048's package split, corrected 2026-08-16) |
 | `packages/gen-ui/engine/compose/strategies/zettel/composition-library.js` | Composition loader + `searchAll()` scoring (normalizes harvested chunks to composition shape) |
-| `scripts/build/harvest-chunks.mjs` | `[data-chunk]` boundary walker over `site/pages/`, `apps/`, `playgrounds/`, `catalog/` — writes `corpus/chunks/<name>.json` + `_index.json`. Run via `npm run harvest:chunks` |
+| `scripts/build/harvest-chunks.mjs` | `[data-chunk]` boundary walker over `site/pages/`, `apps/`, `playgrounds/`, `catalog/`, writes `corpus/chunks/<name>.json` + `_index.json`. Run via `npm run harvest:chunks` |
 | `packages/gen-ui/engine/retrieval/intent/intent-categorizer.js` | Free-text intent → UI-category taxonomy |
 | `packages/gen-ui/engine/retrieval/feedback/feedback-analyzer.js` | Aggregates JSONL feedback (`corpus/feedback/*.jsonl`); promotion + gap candidates |
 | `packages/gen-ui/engine/retrieval/feedback/gap-registry.js` | Persistent gap tracking → `packages/gen-ui/engine/corpus/gaps/registry.json` |
@@ -115,22 +113,22 @@ for any constant or decision lives in git and PR descriptions
 
 | File | Role |
 | --- | --- |
-| `packages/llm/core/llm-bridge.js` | `createAdapter()` — real LLM or stub fallback |
+| `packages/llm/core/llm-bridge.js` | `createAdapter()`, real LLM or stub fallback |
 | `scripts/load-env.mjs` | Shared .env loader for Node scripts |
-| `packages/gen-ui/mcp/gen-ui/server.js` + `packages/gen-ui/mcp/gen-ui/tools/*.js` | MCP stdio server + tool registrations — see [mcp-tool-reference](mcp-tool-reference.md) |
+| `packages/gen-ui/mcp/gen-ui/server.js` + `packages/gen-ui/mcp/gen-ui/tools/*.js` | MCP stdio server + tool registrations, see [mcp-tool-reference](mcp-tool-reference.md) |
 
 ## Critical rules
 
-1. **Relative imports in `packages/llm/core/*.js`** — never `@llm/` Vite aliases;
+1. **Relative imports in `packages/llm/core/*.js`**, never `@llm/` Vite aliases;
    they don't resolve in Node and break published consumers.
-2. **`load-env.mjs` before any a2ui import in Node** — without it,
+2. **`load-env.mjs` before any a2ui import in Node**, without it,
    `createAdapter()` silently returns `StubLLMAdapter` (canned 6-component
    card). Feedback or diagnosis on stub output is noise.
 3. **Metadata IS the search index.** Descriptions + keywords are what retrieval
    matches. Enriching descriptions from structure (headings, labels, button
    text) took meaningful-description rate 40% → 95%. When search degrades,
    inspect chunk metadata before touching thresholds.
-4. **Instant-mode gate lives in `monolithic/generate-instant.js`** — words ≥3
+4. **Instant-mode gate lives in `monolithic/generate-instant.js`**, words ≥3
    chars pass; `GATE_STOPS` filters boilerplate. Grep the set before concluding
    "the gate rejects valid intents".
 5. **A2UI describes LAYOUT, not behavior.** Generation emits component trees +
@@ -138,24 +136,21 @@ for any constant or decision lives in git and PR descriptions
    traits or pre-built apps. "Make the generator emit JS/CSS" is a won't-fix.
    **This is a GENERATION-pipeline claim, not the protocol's outer bound**
    (ADR-0022 amendment, 2026-08-24): the protocol itself, as consumed by the
-   renderer and wire bridge, now carries a ratified CSS channel —
-   `UpdateStylesMessage`/`RemoveStylesMessage`
+   renderer and wire bridge, now carries a ratified CSS channel, `UpdateStylesMessage`/`RemoveStylesMessage`
    (`packages/gen-ui/a2ui/a2ui.schema.json:279-305`, renderer
-   `#updateStyles`/`#removeStyles` at `renderer.js:113-114,821-879`) — a
+   `#updateStyles`/`#removeStyles` at `renderer.js:113-114,821-879`), a
    first-class part of the protocol, not a carve-out. What stays true
    verbatim: compose/zettel synthesis itself still never emits
    `updateStyles`, so this rule's generation claim is unchanged; only the
    closed "the protocol never carries CSS at all" claim was falsified. JS
    remains fully out of scope for both the protocol and generation.
-6. **Renderer guards `textContent` against container wipe** —
-   `packages/gen-ui/a2ui/renderer.js` whitelists pure-text leaves
+6. **Renderer guards `textContent` against container wipe**, `packages/gen-ui/a2ui/renderer.js` whitelists pure-text leaves
    (`TEXT_TAG_OK`); everything else routes through the `text=` attribute so
    slotted children survive. Preserve this when touching the renderer.
 7. **Registry ↔ catalog parity.** A component in the runtime registry but
-   missing from catalog schemas silently drops from generated compositions —
-   `npm run check:registry-catalog-coherence` guards it; run it after catalog
+   missing from catalog schemas silently drops from generated compositions, `npm run check:registry-catalog-coherence` guards it; run it after catalog
    changes. `packages/gen-ui/a2ui/registry.js` is Class R (ADR-0069,
-   gh#3055): never hand-edit it — a new component enters through its yaml
+   gh#3055): never hand-edit it, a new component enters through its yaml
    `component:`/`tag:` fields, an alias or native-element mapping through
    `packages/gen-ui/a2ui/registry.exceptions.json`, then
    `node scripts/build/a2ui-registry.mjs` (derived-resync regenerates it on
@@ -170,28 +165,28 @@ for any constant or decision lives in git and PR descriptions
    the accumulator; never write records to disk directly. Durable issue
    tracking belongs in GitHub issues / PR descriptions, not the engine store.
 10. **A new LLM-calling engine adopts `validate-and-repair.js` as its final
-    stage** — full schema/catalog/anti-pattern conformance, orthogonal to
+    stage**, full schema/catalog/anti-pattern conformance, orthogonal to
     whatever narrower plan/grounding validation the engine already runs
     (chunk-zettel's slot bindings, free-form's ingredient grounding). It
     is NOT automatic: a raw-HTML-wrapper engine (chunk-zettel today, see
-    TKT-0009) gets zero value from it — check the engine's actual output
+    TKT-0009) gets zero value from it, check the engine's actual output
     shape is a real component graph before wiring it in.
 11. **Escalation across engine tiers is the dispatcher's call, never the
-    engine's own** — `registry.js`'s adapter wrappers (not
+    engine's own**, `registry.js`'s adapter wrappers (not
     `generate-instant.js`/`generate-pro.js` themselves) decide whether a
     hard-fail escalates to a stronger tier, capped at one hop. See
     `generateInstantAdapter`'s comment for the worked example.
 12. **`harvest-chunks.mjs` validates every templated chunk at admission
-    time** (validate-only, via the same shared module) — report-only by
+    time** (validate-only, via the same shared module), report-only by
     default; `--strict` refuses to write on any invalid chunk but is NOT
     the default for `npm run harvest:chunks` (TKT-0010: 27% of the corpus
     currently fails, mostly a schema-generation gap around `data-*`/`span`
-    attributes, not corpus-content defects — see the ticket before
+    attributes, not corpus-content defects, see the ticket before
     assuming a chunk is actually broken).
 13. **Every generated catalog schema carries three synthesized universal
     props today** (`slot`/`hidden`/`ariaLive`, none declared in any yaml
     SoT); ADR-0097 rules a fourth, `traits`, but that part is decided-not-
-    yet-shipped (gh#2513) — see `primitive-authoring/references/
+    yet-shipped (gh#2513), see `primitive-authoring/references/
     yaml-contract.md` §Synthesized universal props for the full contract.
 14. **Provider "extended thinking" is a strategy-level opt-in, not a
     global default** (gh#3516, LLD-0033). PR #3511 (gh#3477) made

package/skills/a2ui-maintenance/references/semantic-fail-lifting.md

@@ -1,4 +1,4 @@
-# Semantic fail lifting — sub-60 triage procedure
+# Semantic fail lifting, sub-60 triage procedure
 
 Use when `npm run eval:diff -- --engine zettel --semantic` reports intents
 with `semanticScore < 60` (or <70 for the watch list): the judge says the
@@ -6,26 +6,26 @@ emitted UI doesn't match what was asked for.
 
 ## The judge's three axes (`packages/gen-ui/engine/validate/semantic/index.js:32`)
 
-- **dominantPattern** (weight 0.5) — does the root/primary component match the
+- **dominantPattern** (weight 0.5), does the root/primary component match the
   intent type (chat, form, calendar, data-display, nav…)?
-- **requiredCapabilities** (weight 0.35) — are the specific controls the
+- **requiredCapabilities** (weight 0.35), are the specific controls the
   intent requires present?
-- **forbiddenNoise** (weight 0.15) — are off-topic components prominent?
+- **forbiddenNoise** (weight 0.15), are off-topic components prominent?
 
 A sub-60 score almost always means dominantPattern scored < 40.
 
 ## Triage
 
-1. Read the latest eval run's zettel report — rows with `semanticScore < 70`,
+1. Read the latest eval run's zettel report, rows with `semanticScore < 70`,
    ascending.
 2. Per row, read `semanticAxes.dominantPattern.{expected, observed}` and
    `semanticAxes.requiredCapabilities.missing`.
 3. Bucket each failure:
-   - **Thin composition** — the retrieved entry exists but is too sparse
+   - **Thin composition**: the retrieved entry exists but is too sparse
      (calendar with nav + weekday labels but no grid).
-   - **Wrong composition winning** — retrieval collision; another entry steals
+   - **Wrong composition winning**, retrieval collision; another entry steals
      the intent via keyword overlap.
-   - **No matching composition exists** — coverage gap; author a new one.
+   - **No matching composition exists**, coverage gap; author a new one.
 
 ## Fix strategies, in order of preference
 
@@ -37,14 +37,13 @@ semantically correct primitive fixes it instantly. Historical lifts:
 calendar → `CalendarPicker` root (32→65); chat → `Chat` with
 `Text[role=user|assistant]` children (52→70+); command palette → `Command` >
 `ActionItem` (42→70+). Check the live catalog before authoring children
-(`lookup_component` / `get_component_map` MCP tools) — invented child
+(`lookup_component` / `get_component_map` MCP tools), invented child
 components (`ChatMessage`, `CommandItem`) score zero and trip
 `noInventedComponents`.
 
-### B. Resolve retrieval collisions by keyword surgery — both sides
+### B. Resolve retrieval collisions by keyword surgery, both sides
 
-When an unrelated entry wins retrieval, don't just enrich the correct entry —
-**strip the overlapping keywords from the losing entry too**. Historical
+When an unrelated entry wins retrieval, don't just enrich the correct entry, **strip the overlapping keywords from the losing entry too**. Historical
 example: `empty-state` kept winning "error state with retry" (sem=32) even
 after a dedicated error-state entry existed, until "error state" and "retry"
 were removed from empty-state's keywords; then the right entry won at sem=91.
@@ -53,7 +52,7 @@ were removed from empty-state's keywords; then the right entry won at sem=91.
 
 Indicators: multiple intents fail pointing at the same wrong candidate, and no
 existing entry's purpose matches `dominantPattern.expected`. Author it the
-HTML-first way — a demo page with `data-chunk` markers, then
+HTML-first way, a demo page with `data-chunk` markers, then
 `npm run harvest:chunks` (see [chunk-authoring](chunk-authoring.md)). Put the
 pattern's signature affordance as the dominant child (steps-timeline for a
 wizard, textarea+richtext for an editor, accordion for settings) and give it a
@@ -68,7 +67,7 @@ node packages/gen-ui/mcp/gen-ui/scripts/eval-diff.mjs --engine zettel --semantic
 ```
 
 The semantic judge is cached, content-hashed on
-(rubricVersion, intent, a2ui-messages) — only changed generations re-judge.
+(rubricVersion, intent, a2ui-messages), only changed generations re-judge.
 Compare `avgSem` and the sub-60 list row by row; hold the zettel floors
 (cov≥87, avg≥85, MRR≥0.94) and require `avgSem` ≥ baseline before calling a
 lift done.

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

@@ -1,4 +1,4 @@
-# Strategy engines — zettel file map, strategy labels, issue telemetry
+# Strategy engines, zettel file map, strategy labels, issue telemetry
 
 ## File map (`packages/gen-ui/a2ui/compose/strategies/zettel/`, verified 2026-07)
 
@@ -29,13 +29,12 @@ corpus drift. Never author new `$fragment` refs.
   LLM adapter is present; no LLM → `fragment-candidates` (atoms for downstream
   assembly).
 - **`chunk-zettel`**: chunk-corpus synthesis + `chunk-refiner.js` for
-  history-aware iteration. The zettel session-iteration branch was retired —
-  turn≥2 on `zettel` takes the same path as turn 1 (fresh retrieval). True
+  history-aware iteration. The zettel session-iteration branch was retired, turn≥2 on `zettel` takes the same path as turn 1 (fresh retrieval). True
   modify-an-existing-canvas work goes through `chunk-zettel` + `state_id`.
 
 Both register independently in `strategies/registry.js`.
 
-## Strategy labels (public contract — emitted to the eval harness)
+## Strategy labels (public contract, emitted to the eval harness)
 
 | Label | Trigger | LLM call? |
 | --- | --- | --- |
@@ -46,9 +45,9 @@ Both register independently in `strategies/registry.js`.
 
 The eval harness scores per-label distribution; a calibration tweak that shifts
 the distribution shifts the score. Don't rename labels without a coordinated
-migration — eval, MCP tools, and dialog-recorder pattern-match on the strings.
+migration, eval, MCP tools, and dialog-recorder pattern-match on the strings.
 
-## Issue reporter — three call paths (`issue-reporter.js`)
+## Issue reporter, three call paths (`issue-reporter.js`)
 
 | Path | Trigger | `reporter` | Suppression |
 | --- | --- | --- | --- |
@@ -58,22 +57,21 @@ migration — eval, MCP tools, and dialog-recorder pattern-match on the strings.
 
 Records land in an engine-internal store (`DEFAULT_STORAGE_ROOT` in
 `issue-reporter.js`); traces >200KB spill to a sidecar `.trace.json`. The store
-is scratch telemetry — durable tracking of recurring patterns belongs in GitHub
+is scratch telemetry, durable tracking of recurring patterns belongs in GitHub
 issues / PR descriptions. Type taxonomy: `bug` / `training-gap` /
 `protocol-gap` / `ux-feedback`; severity `nit` < `drift` < `blocker`; owner
 `synthesis | retrieval | validator | chunk-corpus | mcp-protocol | unknown`.
 
-## Closed-loop validation — chunk-zettel is deliberately NOT wired in
+## Closed-loop validation, chunk-zettel is deliberately NOT wired in
 
 Every LLM-calling engine outside this directory (`generate-pro`,
 `generate-thinking`) routes its final candidate through the shared
-`packages/gen-ui/a2ui/compose/shared/validate-and-repair.js` — full schema +
+`packages/gen-ui/a2ui/compose/shared/validate-and-repair.js`, full schema +
 Ajv catalog + anti-pattern conformance, orthogonal to whatever narrower
 check the engine already runs. `chunk-zettel` (`chunk-synthesizer.js`'s
 `composeFromIntent`) does NOT get this: its result is a raw HTML
 **string**, wrapped by the caller (`registry.js`, `generator-adapter.js`)
-into a single node with an unregistered `component: 'article'` type —
-running full schema validation against that would report `invalid` on
+into a single node with an unregistered `component: 'article'` type, running full schema validation against that would report `invalid` on
 every single output, unconditionally, regardless of actual quality. See
 TKT-0009 for the three-direction decision this is waiting on before any
 change lands. `chunk-zettel`'s own `validatePlan` (chunk-existence/slot
@@ -81,7 +79,7 @@ checks) remains its complete validation contract for now.
 
 Separately, `harvest-chunks.mjs` (corpus admission) now runs every
 templated chunk through the same shared module (validate-only) at
-harvest time — report-only by default (`npm run harvest:chunks:dry`
+harvest time, report-only by default (`npm run harvest:chunks:dry`
 shows the results); `--strict` enforcement is deferred to TKT-0010
 (27% of the corpus currently fails, mostly a schema-generation gap
 around `data-*`/`span` attributes rather than corpus-content defects).
@@ -102,13 +100,13 @@ option: no consumer threads it through `generateUI()`.
 
 - **`STRONG_MATCH_THRESHOLD` was raised 22 → 40 post-incident.** Lowering it
   reverts to repetitive verbatim output. If retrieval feels cold, profile the
-  score distribution via `searchAll()` debugging first — don't lower the gate.
-- **`state-cache` is per-process** — multi-turn breaks across MCP server
+  score distribution via `searchAll()` debugging first, don't lower the gate.
+- **`state-cache` is per-process**, multi-turn breaks across MCP server
   restarts; the client must re-run `compose_from_chunks` for a fresh
   `state_id`. Nothing durable belongs in state-cache.
-- **`issueAccumulator` must be passed via `opts`** to refinement engines — a
+- **`issueAccumulator` must be passed via `opts`** to refinement engines, a
   newly wired engine that skips it silently drops auto-fired issues.
-- **`PRE_SEARCH_LIMIT = 30` is kind-aware, not linear** — see
+- **`PRE_SEARCH_LIMIT = 30` is kind-aware, not linear**, see
   [zettel-calibration](zettel-calibration.md) before judging it over-permissive.
 
 ## Verification

package/skills/a2ui-maintenance/references/surface-lifecycle.md

@@ -1,4 +1,4 @@
-# Surface lifecycle — the runtime pending/stale contract (ADR-0061)
+# Surface lifecycle, the runtime pending/stale contract (ADR-0061)
 
 The renderer runtime (`packages/gen-ui/a2ui/`) owns a per-surface lifecycle
 state machine, ratified by ADR-0061
@@ -21,31 +21,31 @@ empty → pending-first → live → pending-stale → live
   one surface, the newest generation's commit wins; a superseded bracket's
   messages are discarded, not interleaved.
 - **Stale content stays visible.** In `pending-stale` and `error-stale` the
-  previous answer keeps rendering — the blank-flash reset+replay shape is
+  previous answer keeps rendering: the blank-flash reset+replay shape is
   what this contract retired. Error state heals: the next successful commit
   clears `error-*`.
 
 ## The host API
 
-Four public runtime methods drive the machine — `beginSurfaceUpdate` /
+Four public runtime methods drive the machine, `beginSurfaceUpdate` /
 `applyTo` / `commitSurfaceUpdate` / `abortSurfaceUpdate`. Messages arriving
 inside a bracket buffer and apply atomically at commit. A `replace`-mode
-commit sweeps components the new answer no longer declares — the ONLY place
+commit sweeps components the new answer no longer declares, the ONLY place
 removal semantics exist; outside a bracket, `updateComponents` upserts
 exactly as before, so unbracketed streams and hosts are behavior-identical
 to the pre-lifecycle runtime (strictly additive, ADR-0061 Decision 4).
 `<a2ui-root>`'s `doc` setter routes through this replace bracket
-(`replaceDoc`) rather than reset+replay — a deliberate, ratified behavior
+(`replaceDoc`) rather than reset+replay, a deliberate, ratified behavior
 change for doc-setting hosts (ADR-0061 OD-2).
 
 ## The DOM contract
 
 Staleness is exposed as one attribute plus three events, never styling:
 
-- **`data-a2ui-lifecycle`** — a single enum attribute on the surface root
+- **`data-a2ui-lifecycle`**, a single enum attribute on the surface root
   reflecting the current state. This is the `data-a2ui-*` prefix's FIRST
   ratification (the pre-existing `data-a2ui-surface` stamp was accidental,
-  now ratified alongside it) — the runtime-owned `data-*` tier, sibling to
+  now ratified alongside it), the runtime-owned `data-*` tier, sibling to
   ADR-0060's trait tier.
 - **Three bubbling CustomEvents** mark the transitions.
 - Hosts and primitives style off the attribute with semantic tokens: stale
@@ -58,14 +58,13 @@ Staleness is exposed as one attribute plus three events, never styling:
 The lifecycle is renderer-runtime work on gen-ui-kit's side of the ADR-0059
 line. The three wire envelope kinds (`beginSurfaceUpdate` /
 `commitSurfaceUpdate` / `abortSurfaceUpdate` as v1.0 server kinds) are
-defined by the v1.0 Candidate reference implementation — `a2ui.schema.json`
+defined by the v1.0 Candidate reference implementation, `a2ui.schema.json`
 gains nothing, the dialect wire format is byte-identical. Never hand-write
 lifecycle envelopes from this skill's surfaces; the Bridge owns the mapping
 when the kinds land.
 
 **[amended 2026-08-29, ADR-0096]** `adiahealth/gen-ui-system` is absorbed
-first-party under `packages/genui/` and the standalone repo is archived —
-there is no external, separately-governed "upstream standard" to wait on
+first-party under `packages/genui/` and the standalone repo is archived, there is no external, separately-governed "upstream standard" to wait on
 any more. ADR-0096 Decision 5: gen-ui-kit "owns the whole stack now... and
 the v1.0 Candidate reference implementation itself, not only the consumer
 side of a vendor boundary." Stream-driven regeneration now proceeds on
@@ -75,6 +74,6 @@ not an upstream release.
 ## Interlock worth knowing
 
 The v1.0 conformance program's duplicate-`surfaceId` error (REQ-002)
-sequences AFTER this API — the silent `createSurface` no-op it removes was
+sequences AFTER this API, the silent `createSurface` no-op it removes was
 previously the only wire-visible re-target path, and the lifecycle bracket
 is its sanctioned replacement.