@adia-ai/adia-ui-forge 0.1.3 → 0.8.1

package/skills/adia-a2ui/references/eval-diagnostics.md

@@ -0,0 +1,86 @@
+# Eval diagnostics — gap diagnosis + regression triage
+
+**Diagnostics run before code changes — always.** The #1 anti-pattern is
+"tweak and hope": changing a prompt or adding a chunk without knowing why the
+score is low burns real-LLM eval runs and teaches nothing.
+
+## Phase 0 — author a stub-mode diagnostic (zero LLM cost)
+
+For each failing intent, capture four signals:
+
+1. **Search ranking** — what `searchChunks()` returns for the intent query.
+2. **Composition output** — what the pipeline emitted (HTML or plan).
+3. **Tag inventory** — every custom-element-like tag in the emitted HTML.
+4. **Coverage delta** — expected_components vs found_components.
+
+Template (runnable with `llmAdapter: null`):
+
+```js
+async function diagnose(intent) {
+  const search = searchChunks(intent.intent, { limit: 10 });
+  const comp = await composeFromIntent({ intent: intent.intent, llmAdapter: null });
+  const tags = [...comp.html.matchAll(/<([a-z]+-[a-z-]+)[\s>]/gi)]
+    .map(m => m[1]).filter((v, i, a) => a.indexOf(v) === i);
+  const found = intent.expected_components.filter(tag =>
+    new RegExp(`<${kebab(tag)}-ui[\\s>]`).test(comp.html));
+  return { search, tags, found,
+    missing: intent.expected_components.filter(t => !found.includes(t)) };
+}
+```
+
+## Phase 1 — classify failures
+
+| Bucket | Symptom | Root cause | Cost |
+| --- | --- | --- | --- |
+| A. Holdout misalignment | Top-1 retrieved ≠ expected_chunk | Holdout drifted from corpus | minutes |
+| B. Coverage gap | Chunk retrieved but HTML lacks expected tags | Chunk HTML doesn't contain those components | hours (new chunks) |
+| C. Wrong shell | Retrieval OK, LLM picks wrong page shell | Prompt ambiguity / missing domain→shell mapping | hours (prompt tuning) |
+| D. Broken render | HTML emitted but console errors / blank | Missing registrations or bad markup | hours (harvester bug) |
+| E. Measurement bug | Output looks right, score low | Scorer regex/casing/substring bug | minutes |
+| F. Embedding drift | Async top-1 ≠ sync top-1 | Cosine boosts flip rankings non-deterministically | minutes |
+
+**Fix order: A → E → F → C → B → D.** Fix measurement before content (else
+scores can't be trusted); fix determinism before adding content (else evals
+fluctuate).
+
+## Phase 2 — fixes per bucket
+
+- **A. Holdout alignment** — map each intent's `expected_chunk` to the actual
+  top-1; update `packages/a2ui/corpus/evals/holdout-compose-from-chunks.jsonl`.
+- **E. Measurement traps** — PascalCase→kebab (`AgentTrace` → `agent-trace`,
+  not `agenttrace`); substring false positives (`pane` vs `panel`,
+  `textarea-ui` contains `text-ui` — word boundaries); case sensitivity (`/i`).
+- **F. Embedding drift** — prefer sync keyword search for deterministic
+  fast-path tiers; keep async cosine for the synthesis tier only (embeddings
+  are a tie-breaker by design — see zettel-calibration).
+- **C. Wrong shell** — check the `SYSTEM_PROMPT` domain→shell mapping in
+  `chunk-synthesizer.js`; add explicit examples for the failing domain and a
+  negative constraint ("NEVER default to dashboard-admin-page for
+  non-dashboard intents").
+- **B. Coverage gap** — author a block chunk the HTML-first way
+  ([chunk-authoring](chunk-authoring.md)): demo page in a harvest root (e.g.
+  `catalog/ui-patterns/app/<name>/`), `data-chunk` + `data-chunk-kind="block"`
+  markers, real component tags so coverage scoring matches, then
+  `npm run harvest:chunks`.
+- **D. Broken render** — `packages/a2ui/mcp/scripts/render-fidelity.mjs`
+  output (console errors, blank viewport, undefined elements); verify
+  registrations in `packages/web-components/index.js`; check the harvester
+  didn't strip `data-chunk-slot` from page shells.
+
+## Verification
+
+```bash
+npm run eval:compose-from-chunks                       # stub first: fast, free
+npm run eval:compose-from-chunks -- --real-llm --report-file   # then real LLM
+```
+
+Stop only when all intents pass and the average is stable across 3 runs, and
+the SKILL.md floors hold.
+
+## The eval suite's dimensions
+
+`packages/a2ui/mcp/scripts/test-evals.mjs` scores 5 weighted dimensions:
+structural_validity 30% · intent_alignment 25% · component_coverage 20% ·
+card_model_compliance 15% · anti_pattern_count 10%. `--save-baseline`
+(`npm run test:evals:baseline`) stores scores; later runs flag any dimension
+dropping >5 points or aggregate >3 (exit code 2 = regression).

package/skills/adia-a2ui/references/format-extension-decisions.md

@@ -0,0 +1,66 @@
+# Format-extension decisions — when a component's contract can't express something
+
+A component's A2UI JSON contract sometimes can't carry a content shape the
+authored HTML has — a table cell with mixed prose and inline `<code>`, a
+label needing an icon, a slot needing arbitrary nested markup. Read this
+before extending any component's declarative contract to close a gap like
+that; it doesn't cover corpus/chunk decisions (see
+[leverage-rules](leverage-rules.md)) — it's about the component's own
+prop/construct surface.
+
+## The three-tier ladder, in order of preference
+
+1. **Extend an existing declarative registry the component already has** —
+   e.g. `table-ui`'s `components/table/cell-types.js` (`badge`, `progress`,
+   `link`, …). Add a new named type; the component dispatches rendering
+   through the registry it already owns. **Smallest blast radius**: no new
+   A2UI construct, no runtime/validator changes, no registry entry in
+   `packages/a2ui/runtime/registry.js`. **Ceiling**: only covers formats the
+   registry's render contract can express (inline-safe content, not
+   arbitrary nested block markup). Building the new registry entry is a
+   web-components primitive edit — hand off to `adia-author` for the
+   implementation half; this reference only decides the tier.
+2. **New A2UI primitive(s)**, each slot/cell a normal construct subtree (any
+   registered component nestable inside it) — matches how `Column`/`Row`
+   already compose. **Most expressive** — no ceiling on what can nest.
+   **Largest blast radius**: new constructs need transpiler synthesis,
+   runtime rendering support, and validator rules; changes what the
+   containing component MEANS in the A2UI graph model. Reserve for cases
+   tier 1 genuinely can't reach.
+3. **Raw-HTML/markup passthrough**, wired through an existing visual-only
+   escape hatch (e.g. `table-ui[raw]`) registered as an A2UI construct
+   carrying sanitized markup as a string prop. **Fastest to ship** — reuses
+   infrastructure verbatim. **Weakest fit for a generative pipeline**: an
+   LLM composing pages would need to emit raw HTML strings instead of
+   constructs, undermining the JSON-graph value the A2UI format exists for.
+   Acceptable ONLY as a narrowly-scoped escape hatch (e.g. a docs-migration
+   pipeline), never as a pattern taught to the generation engines.
+
+**Default to tier 1.** Climb to tier 2 or 3 only when a concrete case proves
+tier 1's ceiling — don't pre-emptively build the more expressive, more
+invasive tier for a gap tier 1 can still close.
+
+## Worked precedent — TKT-0008 (table-ui rich cells, 2026-07-13)
+
+`table-ui`'s `{columns, data}` contract only carried plain-string cells;
+docs reference tables with inline `<code>` in cells (e.g. `` `variant` `` in
+a props table) fell back to a preserved-HTML `Code` block instead of a
+`Table` component — the table never reached the A2UI graph. All three tiers
+were scoped (rich-cell vocabulary / new `TableRow`/`TableCell` primitives /
+raw-HTML passthrough via the existing `table-ui[raw]` prop); tier 1 was
+ratified and built: a new `markdown` cell type in `cell-types.js`, rendered
+via `core/markdown.js`'s `inline()` (exported for this reuse — the exact
+client-side counterpart to the docs-transpiler's own `convertInline()`).
+Measured result: the targeted failure class (`structural:tables` in the
+strict re-verification sweep) dropped 39→7 pages out of 98 measured; the
+residual 7 carry cells genuinely outside tier 1's reach (block content,
+component tags) and are an open tier-2/3 follow-up
+(`docs/tickets/TKT-0008-table-ui-cannot-express-rich-cells.md`).
+
+## Why this generalizes
+
+The same ladder applies to any AdiaUI primitive with a per-item/per-cell
+render dispatch (table columns, list-item variants, chart series formats,
+…): check for an existing registry FIRST, size the ceiling honestly against
+the concrete case at hand, and only pay the blast-radius cost of a new
+construct or a raw-passthrough when the registry provably can't reach it.

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

@@ -0,0 +1,52 @@
+# 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
+`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
+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
+consumers would use it. Two exceptions:
+
+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
+   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%
+   on its own.
+
+Sub-leverage extraction bloats the corpus, slows retrieval, and adds
+maintenance without improving reuse. Common candidates that DO clear the bar:
+card headers, key-value rows, icon+text rows, labeled progress bars, stat
+tiles, notification rows.
+
+## Keyword preservation (the extraction-drift lesson)
+
+Extraction SHRINKS the parent's keyword surface: before, the parent contained
+the subtree's text; after, it only references the child. Historically,
+extracting a card-header from the login-form pattern dropped its retrieval
+score 28 → 24 because "login / sign in / email password" tokens left with the
+extract; explicitly re-adding those keywords to the parent restored 28.
+
+**Rule: every parent that loses a subtree must be re-enriched with the
+semantic tokens that left.** In today's corpus this means the parent chunk's
+`data-chunk-keywords` (and re-harvest). Without it, retrieval degrades
+silently.
+
+## Threshold discipline after extraction
+
+If a known-good intent starts scoring below a retrieval threshold after a
+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-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/adia-a2ui/references/mcp-pipeline-ops.md

@@ -0,0 +1,83 @@
+# 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
+
+```bash
+node scripts/mcp-pipeline.cjs "dashboard with 4 stat cards and a revenue chart"
+```
+
+Pipes `intent → generate_ui → validate_schema → a2ui-to-html →
+check_anti_patterns` and prints the scores. Fastest whole-stack confirmation
+after a change.
+
+## Step-by-step (inspect intermediates)
+
+```bash
+node scripts/mcp-call.cjs generate_ui '{"intent":"dashboard with 4 stat cards","mode":"instant"}'
+node scripts/mcp-call.cjs validate_schema '{"messages":"<paste-messages-json>"}'
+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
+`packages/a2ui/corpus/chunks/*.json` templates to surface corpus drift without
+re-running the generator.
+
+## Compose from the chunk corpus
+
+When the intent matches a known page-shape (auth flow, dashboard layout, error
+shell), prefer `compose_from_chunks` over `generate_ui`:
+
+```bash
+node scripts/mcp-call.cjs compose_from_chunks '{"intent":"sign-in card with email + password + OAuth"}'
+```
+
+Tier 1 returns a matched chunk's HTML when the retrieval score ≥ 8; otherwise
+the LLM picks a `{page, slot_bindings}` plan from a pre-filtered ~30-entry
+catalog and the chunk composer materializes it, validating slot-name +
+chunk-kind contracts. Returns `{state_id, html, plan, candidates}`.
+
+## Multi-turn refinement (state_id chain)
+
+```bash
+# Turn 1 → returns state_id "abc123"
+node scripts/mcp-call.cjs compose_from_chunks '{"intent":"sign-in card with email + password"}'
+# Turn 2 → updateComponents messages + new state_id
+node scripts/mcp-call.cjs refine_composition '{"state_id":"abc123","intent":"add OAuth row with Google + GitHub"}'
+```
+
+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
+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
+diagnosis. Anything worth durable tracking (a recurring pattern, a fix
+proposal) belongs in a GitHub issue or the PR description of the fixing
+change.
+
+## Validation checks
+
+`validate_schema` runs a weighted checklist (target aggregate ≥ 80). Common
+failures when the corpus drifts: `hasRootComponent` (missing `id: "root"`),
+`cardContentModel` (section without Column wrapper, or heading inside section
+instead of header), `headingHierarchy` (skipped levels), `flatAdjacency`
+(nested components instead of sibling id references). Full list + weights:
+`packages/a2ui/mcp/TOOLS.md`.
+
+## Feedback loop
+
+Score runs with `submit_feedback` keyed on the `executionId` from
+`generate_ui`. The analyzer
+(`packages/a2ui/retrieval/feedback/feedback-analyzer.js`) aggregates
+`corpus/feedback/*.jsonl` into per-intent trends, promotion candidates
+(≥95 score + ≥4 rating across 3+ runs → `npm run feedback:promote`), and the
+gap registry (`packages/a2ui/corpus/gaps/registry.json`).
+`npm run feedback:report` surfaces the current state.

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

@@ -0,0 +1,59 @@
+# MCP tool reference — the a2ui server's tool surface
+
+**Schema SoT is `packages/a2ui/mcp/TOOLS.md` (30 tools), generated alongside
+`server.js` — read it for input/output shapes; never restate schemas here
+(they drift).** Tools register in `packages/a2ui/mcp/server.js` +
+`packages/a2ui/mcp/tools/{corpus,discovery,feedback,refine,synthesis,
+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,
+explicit operator proceed, `@adia-ai/a2ui-mcp` version bump, factory pin
+update, and the consumer-load-bearing subset whose contracts are
+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.
+
+## Tool map by job
+
+| Group | Tools | Registered in |
+| --- | --- | --- |
+| Generation | `generate_ui`, `refine_ui` (monolithic repair) | `synthesis.js`, `refine.js` |
+| Chunk synthesis + multi-turn | `compose_from_chunks`, `refine_composition`, `get_state`, `report_issue` | `synthesis.js` |
+| Chunk retrieval | `search_chunks`, `get_chunk`, `lookup_chunk` | `corpus.js` |
+| Catalog inspection | `lookup_component`, `get_component_map`, `get_traits`, `get_wiring_catalog`, `server_status` | `discovery.js` |
+| Composition/zettel inspection | `search_patterns`, `get_fragment`, `get_composition`, `get_graph`, `resolve_composition`, `zettel_stats` | `zettel.js` |
+| Intent + context | `classify_intent`, `assemble_context` | `discovery.js` |
+| Validation + conversion | `validate_schema`, `check_anti_patterns`, `convert_html` | `validation.js` |
+| Feedback + evaluation | `submit_feedback`, `get_quality_metrics`, `get_training_gaps`, `run_eval` | `feedback.js` |
+| Authoring (write path) | `import_pattern` | `zettel.js` |
+
+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.
+- **Catalog literacy** → `lookup_component` / `get_component_map`; the MCP is
+  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
+  combined report.
+- `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
+  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`).
+3. Verify: `npm run mcp:smoke`, then a real-client round-trip.

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

@@ -0,0 +1,115 @@
+# Pipeline overview — generator + retrieval + engines (mode: modify pipeline internals)
+
+All paths repo-relative. Specs worth reading before structural changes:
+`.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
+`.claude/docs/specs/genui-multiturn-architecture.md` (state cache, refiner,
+op format), `.claude/docs/specs/genui-chunk-marker.md` (chunk attributes),
+`.claude/docs/conventions/gen-ui-pipeline.md` (harvester wiring + embedding
+lifecycle), `.claude/docs/specs/package-architecture.md` (package relations).
+
+## Key files (verified 2026-07)
+
+### Engine orchestration
+
+| File | Role |
+| --- | --- |
+| `packages/a2ui/compose/core/generator.js` | `generate_ui` orchestrator — instant / pro / thinking / stream modes; multi-turn via `executionId` |
+| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `zettel`, `mcp`, `monolithic-*` |
+| `packages/a2ui/compose/strategies/zettel/` | Zettel + chunk-zettel engines — see [strategy-engines](strategy-engines.md) for the per-file map |
+| `packages/a2ui/compose/strategies/free-form-composer/` | Free-form engine (`index.js`, `system-prompt.js`, `transpile.js`) |
+| `packages/a2ui/compose/strategies/_shared/chunk-loader.js` | Shared chunk loading for engines |
+| `packages/a2ui/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/a2ui/compose/transpiler/transpiler.js` | HTML → A2UI transpile pass (used by harvester + convert_html) |
+
+### Corpus + retrieval
+
+| File | Role |
+| --- | --- |
+| `packages/a2ui/corpus/scripts/chunk-library.js` | Chunk catalog API — `getChunk()`, `searchChunks()` (keyword), `searchChunksAsync()` (keyword + cosine), `listChunksByKind()`, `lookupChunksByPrimary()`. Reads `corpus/chunks/` + `_index.json` |
+| `packages/a2ui/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` |
+| `packages/a2ui/retrieval/intent/intent-categorizer.js` | Free-text intent → UI-category taxonomy |
+| `packages/a2ui/retrieval/feedback/feedback-analyzer.js` | Aggregates JSONL feedback (`corpus/feedback/*.jsonl`); promotion + gap candidates |
+| `packages/a2ui/retrieval/feedback/gap-registry.js` | Persistent gap tracking → `packages/a2ui/corpus/gaps/registry.json` |
+| `packages/a2ui/retrieval/anti-patterns.js` | The `check_anti_patterns` rule source |
+| `packages/a2ui/compose/core/reference.js` | Thin wrappers over retrieval exports (`searchBlocks`, `searchBlocksSemantic`, …) |
+
+### LLM bridge + MCP
+
+| File | Role |
+| --- | --- |
+| `packages/llm/llm-bridge.js` | `createAdapter()` — real LLM or stub fallback |
+| `scripts/load-env.mjs` | Shared .env loader for Node scripts |
+| `packages/a2ui/mcp/server.js` + `mcp/tools/*.js` | MCP stdio server + tool registrations — see [mcp-tool-reference](mcp-tool-reference.md) |
+
+## Critical rules
+
+1. **Relative imports in `packages/llm/*.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,
+   `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
+   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 +
+   props + slot bindings; never JS or per-canvas CSS. Behavior delegates to
+   traits or pre-built apps. "Make the generator emit JS/CSS" is a won't-fix.
+6. **Renderer guards `textContent` against container wipe** —
+   `packages/a2ui/runtime/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
+   changes.
+8. **Multi-turn emits A2UI `updateComponents` messages, not new compositions.**
+   The chunk-refiner mutates the binding plan via four ops (`rebindSlot` /
+   `appendToSlot` / `removeFromSlot` / `replacePage`); state chains via
+   `parent_state_id`. Spec: `genui-multiturn-architecture.md`.
+9. **Issue telemetry goes through `ctx.issueAccumulator`** (suppressed when
+   `ctx.evalMode` is true so evals stay clean). New engine failure paths plumb
+   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
+    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
+    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
+    `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
+    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
+    assuming a chunk is actually broken).
+
+## Test + run commands (all verified in root package.json)
+
+```bash
+npm run test:a2ui              # smoke checks, no LLM (22/22, +1 skipped OK)
+npm run test:a2ui:full         # + thinking mode (calls API)
+npm run test:evals             # 5-dimension quality evals (mcp/evals/evals.json); --save-baseline via test:evals:baseline
+npm run generate "login form"  # instant-mode CLI (mcp/scripts/generate.mjs)
+npm run smoke:engines          # all registered engines
+npm run smoke:register-engine  # in-process registration (11/11)
+npm run eval:diff -- --engine zettel        # floors in SKILL.md
+npm run harvest:chunks         # re-harvest corpus (dry: harvest:chunks:dry)
+npm run smoke:chunks           # stub-LLM chunk smoke (re-harvests as side effect!)
+npm run eval:chunk-synthesis   # hold-out intents against real LLM
+npm run build:embeddings:chunks
+npm run smoke:refine && npm run smoke:state-cache && npm run smoke:issues
+npm run eval:refine-synthesis  # multi-turn refinement quality
+npm run feedback:report && npm run feedback:promote
+```

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

@@ -0,0 +1,74 @@
+# 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
+emitted UI doesn't match what was asked for.
+
+## The judge's three axes (`packages/a2ui/validator/semantic/index.js:32`)
+
+- **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
+  intent requires present?
+- **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`,
+   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
+     (calendar with nav + weekday labels but no grid).
+   - **Wrong composition winning** — retrieval collision; another entry steals
+     the intent via keyword overlap.
+   - **No matching composition exists** — coverage gap; author a new one.
+
+## Fix strategies, in order of preference
+
+### A. Use a domain-specific primitive as the root
+
+The judge weights root identity heavily: a Card wrapping 38 Badges + 43 Texts
+reads as "data-display" even with a 7-column grid inside. Swapping to the
+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
+components (`ChatMessage`, `CommandItem`) score zero and trip
+`noInventedComponents`.
+
+### 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
+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.
+
+### C. Author the missing coverage
+
+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
+`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
+rich keyword set (15–20 terms) with exact intent phrases and domain synonyms.
+
+## Verify loop
+
+```bash
+node scripts/build/components.mjs --verify
+npm run smoke:engines && npm run smoke:register-engine && npm run test:a2ui
+node packages/a2ui/mcp/scripts/eval-diff.mjs --engine zettel --semantic
+```
+
+The semantic judge is cached, content-hashed on
+(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/adia-a2ui/references/strategy-engines.md

@@ -0,0 +1,109 @@
+# Strategy engines — zettel file map, strategy labels, issue telemetry
+
+## File map (`packages/a2ui/compose/strategies/zettel/`, verified 2026-07)
+
+```text
+generator-adapter.js   ← zettel entry: retrieval → strong-match / chunk-synthesis bridge / atoms
+generate.js            ← thin wrapper for direct invocation
+_smoke.js              ← in-tree smoke (npm run zettel:smoke)
+composition-library.js ← loads corpus/chunks/*.json, normalizes to composition shape, searchAll()
+composer.js            ← resolveComposition(): defensive copy + strip pass (see fragment note)
+session-store.js       ← multi-turn artifact tracking (in-memory analytics; no iteration branch)
+chunk-synthesizer.js   ← page-shell + slot-binding synthesis (chunk-corpus, 2-tier)
+chunk-composer.js      ← resolves a chunk plan into A2UI messages; slot/kind validation
+chunk-refiner.js       ← multi-turn refinement (locator → modifier two-pass)
+state-cache.js         ← bounded LRU keyed by state_id
+issue-reporter.js      ← runtime telemetry (see below)
+```
+
+**Fragments are retired.** `fragment-library.js` / `synthesizer.js` no longer
+exist; `composition-library.js` is the renamed successor and the harvested
+chunk corpus is the only retrieval substrate. `composer.js` is a passthrough:
+any lingering `$fragment` ref renders as a visible placeholder to surface
+corpus drift. Never author new `$fragment` refs.
+
+## Two engines under one directory
+
+- **`zettel`** (`generator-adapter.js`): `searchAll()` over compositions →
+  strong match emits verbatim; weak/no match bridges to chunk-synthesis when an
+  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
+  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)
+
+| Label | Trigger | LLM call? |
+| --- | --- | --- |
+| `composition-match` | Fresh retrieval, `searchAll` score ≥ `STRONG_MATCH_THRESHOLD` (40) | No |
+| `composition-synthesized` | Weak retrieval, chunk-synthesis bridge succeeded | Yes |
+| `synthesis-failed` | LLM tried + failed validation | Yes (failed) |
+| `fragment-candidates` | Weak retrieval + no LLM available → atoms only | No |
+
+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.
+
+## Issue reporter — three call paths (`issue-reporter.js`)
+
+| Path | Trigger | `reporter` | Suppression |
+| --- | --- | --- | --- |
+| LLM self-fire | `report_issue` MCP tool | `llm` | none |
+| Consumer-fire | Human requests a record | `user` | none |
+| Engine auto-fire | Internal failure (scope-drift, synthesis-failed) | `auto` | when `ctx.evalMode` is true |
+
+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
+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
+
+Every LLM-calling engine outside this directory (`generate-pro`,
+`generate-thinking`) routes its final candidate through the shared
+`packages/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
+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
+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`
+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).
+
+## Pitfalls
+
+- **`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
+  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
+  newly wired engine that skips it silently drops auto-fired issues.
+- **`PRE_SEARCH_LIMIT = 30` is kind-aware, not linear** — see
+  [zettel-calibration](zettel-calibration.md) before judging it over-permissive.
+
+## Verification
+
+```bash
+npm run zettel:smoke                       # fast, no LLM
+npm run smoke:engines
+npm run eval:diff -- --engine zettel       # slow, real LLM; floors in SKILL.md
+npm run eval:diff -- --engine chunk-zettel
+```