@adia-ai/a2ui-mcp 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -11,6 +11,70 @@ zettel strategies.
 
 _No pending changes._
 
+## [0.3.3] - 2026-05-07
+
+**Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` ranges stay at `^0.3.0` (patch-cut asymmetry — caret floats `0.3.x`).
+
+### Added
+
+- **`TOOLS.md`** — single-page reference for all 24 MCP tools
+  exposed by `server.js`. Tools grouped into 7 categories
+  (composition, retrieval, validation, refinement, telemetry,
+  catalog, debug) with descriptions extracted from `server.js`.
+  (closes backlog #96)
+
+- **Smoke retrieval-quality probe** in
+  `scripts/smoke-engine-registry.mjs`. Runs 3 canonical intents
+  (login form, pricing tiers, sign-up form) through `generateUI()`
+  and verifies output text content overlaps intent keywords.
+  Catches retrieval regressions (wrong-domain top hit) that pure
+  shape-validation gates miss. 3/3 probes pass. (closes backlog #46)
+
+### Changed
+
+- **README** — corrected stale 25-tool count to 24, removed phantom
+  `compose_from_chunks` entry from the table, replaced inline tool
+  table with pointer to `TOOLS.md`. Added "Multi-turn limitations"
+  Gotcha entry documenting per-process state-cache limitation
+  (session-store + state-cache are in-memory, ephemeral; restarting
+  the server drops every multi-turn chain in flight; consumers
+  needing durability should checkpoint to their own store + pass
+  `currentCanvas` on resume). (closes backlog #47)
+
+- **`tools/synthesis.js`** — issue-reporter prompt vocabulary swept:
+  `'coherence-audit'` → `'ui-audit-coherence'` (matches the renamed
+  skill).
+
+- **`scripts/smoke-issues.mjs`** — extended `AUTO_FIRE_POLICY exports
+  expected reasons` test to include the new
+  `iteration-synthesis-failure` reason (62/62 pass).
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### Added
+
+- **Render-fidelity scoring** — `scripts/render-fidelity.mjs`: Playwright
+  headless evaluates synthesized HTML on console errors, blank-page
+  detection, and unregistered custom-element count. Integrated into
+  `eval-compose-from-chunks.mjs` at full 30% weight.
+- **`eval:compose-from-chunks` framework** — 20-intent hold-out set with
+  real-LLM runner (structural 30% + coverage 20% + retrieval 20% +
+  render 30%). Threshold: 80. Result: 20/20 passing, avg 88.
+- **`chunk-zettel` engine baseline** — comparison vs classic zettel on same
+  hold-out (88 avg / 20 passing vs 77 avg / 11 passing).
+- **Zettel baseline runner** — `scripts/zettel-baseline.mjs` for cross-engine
+  comparison.
+- **Nightly eval CI** — `.github/workflows/nightly-eval.yml` with stub
+  eval + zettel-diff + summary jobs.
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).
@@ -396,7 +460,7 @@ ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multitur
   reporter kinds: LLM self-fire (this tool with `reporter: 'llm'`),
   consumer-fire (passed through directly), engine auto-fire (internal,
   per `AUTO_FIRE_POLICY` in the issue-reporter module). Severity vocabulary
-  `blocker | drift | nit` matches the existing `coherence-audit`
+  `blocker | drift | nit` matches the existing `ui-audit-coherence`
   discipline. Trace levels: `'full' | 'summary' | 'none'`; oversized
   traces (> 200 KB) spill to a sidecar `.trace.json` file. Tool count
   goes from 25 → 28.

package/README.md

@@ -42,35 +42,19 @@ export GEMINI_API_KEY=AIza…
 
 ## Tools
 
-The server registers 25 tools. Shape is stable; argument schemas via Zod.
-
-| Tool                    | What it does                                              |
-|-------------------------|-----------------------------------------------------------|
-| `generate_ui`           | Intent → A2UI tree. Engine (`monolithic`/`zettel`) + mode. |
-| `validate_schema`       | Run the 15-check validator on an A2UI tree; returns 0-100. |
-| `classify_intent`       | Extract concepts, entities, implied components, steelman.  |
-| `lookup_component`      | Resolve a component name (alias-aware) to its schema.      |
-| `get_component_map`     | Full tag→class map including alias normalizations.         |
-| `search_patterns`       | Keyword-rank the monolithic pattern corpus.                |
-| `assemble_context`      | Build the system prompt context for a given intent.        |
-| `check_anti_patterns`   | Scan a tree for canonical anti-patterns (chart-legend, …). |
-| `get_traits`            | List trait catalog + their host-binding rules.             |
-| `convert_html`          | Raw HTML → best-effort A2UI tree (import path).            |
-| `get_wiring_catalog`    | Declarative wiring-engine recipes.                         |
-| `import_pattern`        | Commit a generated result into the pattern library.        |
-| `submit_feedback`       | Append a user-feedback event to the feedback store.        |
-| `get_quality_metrics`   | Aggregate pass/fail scores over a window.                  |
-| `get_training_gaps`     | Intents that currently miss coverage.                      |
-| `run_eval`              | Run the held-out benchmark; return pass/fail per intent.   |
-| `get_fragment`          | Fetch a single zettel fragment by id.                      |
-| `get_composition`       | Fetch a named multi-fragment composition.                  |
-| `resolve_composition`   | Expand a composition reference into its fragments.         |
-| `get_graph`             | Dump the zettel fragment-dependency graph.                 |
-| `zettel_stats`          | Corpus counts (fragments, compositions, reuse ratio, …).   |
-| **`search_chunks`**     | Semantic + keyword search over the gen-UI training-chunk corpus (since 0.0.2). |
-| **`get_chunk`**         | Full record (HTML + metadata + slots) for one chunk.       |
-| **`lookup_chunk`**      | List every chunk whose primary element is `<component>`.   |
-| **`compose_from_chunks`** | Retrieval-first / LLM-mix-and-match composition. Picks a page chunk + binds block/panel chunks to its slots when retrieval is weak. Validator enforces slot+kind contracts. **Embedding-blended retrieval as of 0.0.3** (was keyword-only in 0.0.2). |
+The server registers **24 tools**. Argument schemas via Zod; shape is stable across the v0.3.x line.
+
+**See [`TOOLS.md`](./TOOLS.md) for the full reference** — tool names, descriptions, grouping, and source pointers. Quick map:
+
+| Group | Tools |
+|---|---|
+| **Generation** | `generate_ui` |
+| **Discovery** | `get_component_map`, `lookup_component`, `lookup_chunk`, `get_traits`, `get_wiring_catalog` |
+| **Retrieval** | `search_chunks`, `get_chunk`, `search_patterns`, `get_fragment`, `get_composition`, `get_graph`, `resolve_composition`, `zettel_stats` |
+| **Intent + context** | `classify_intent`, `assemble_context` |
+| **Validation + conversion** | `validate_schema`, `check_anti_patterns`, `convert_html` |
+| **Feedback + evaluation** | `submit_feedback`, `get_quality_metrics`, `get_training_gaps`, `run_eval` |
+| **Authoring** | `import_pattern` |
 
 ## Layout
 
@@ -141,6 +125,20 @@ On start, the server:
   names in the registry guard against accidental shadowing.
 - **Validator score < 70 is still returned.** Consumers should gate on
   the `passed` boolean or raw `score` — the tool doesn't auto-retry.
+- **Multi-turn state is per-process, in-memory, ephemeral.** Both the
+  zettel `state-cache` (keyed by `state_id` for refinement chains) and
+  the zettel `session-store` (keyed by `sessionId` for follow-up
+  iteration) live in the MCP process's heap. **Restarting the server
+  drops every multi-turn chain in flight.** Consumers that need
+  durability across restarts should checkpoint the canvas to their own
+  store between turns and pass `currentCanvas` on resume rather than
+  relying on `executionId` / `sessionId`. A future phase may add
+  file-backed persistence as opt-in via `A2UI_STATE_CACHE_PATH`; not
+  implemented today.
+- **`session-store` and `state-cache` overlap intentionally.** Different
+  lifecycles (MCP-call multi-turn vs engine-internal stable-id resolution),
+  different APIs, kept separate by design — see `state-cache.js` and
+  `session-store.js` for the contracts.
 
 ## Evals + regression floors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -33,4 +33,4 @@
     "@adia-ai/llm": "^0.3.0",
     "zod": "^3.24.0"
   }
-}
+}

package/scripts/smoke-engine-registry.mjs

@@ -40,4 +40,39 @@ const ok =
   Array.isArray(r2.messages) && r2.validation;
 console.log(`\n[smoke] shape invariants: ${ok ? 'ok' : 'FAIL'}`);
 
-if (!ok) process.exit(1);
+// Retrieval-quality probe — for each canonical intent, the generated
+// component tree's text content must overlap the intent's keywords.
+// This catches retrieval regressions (wrong-domain top hit) that pure
+// shape-validation gates miss.
+const RETRIEVAL_PROBES = [
+  { intent: 'login form with email and password',     engine: 'zettel',       expectKeywords: ['sign in', 'login', 'email', 'password'] },
+  { intent: 'pricing tiers with three plans',          engine: 'zettel',       expectKeywords: ['pricing', 'tier', 'plan', 'starter', 'pro', 'enterprise', '$'] },
+  { intent: 'sign up form for a new account',          engine: 'zettel',       expectKeywords: ['sign up', 'register', 'create account', 'email'] },
+];
+
+function extractText(messages) {
+  const parts = [];
+  for (const msg of messages || []) {
+    for (const c of msg.components || []) {
+      if (c.textContent) parts.push(String(c.textContent));
+      if (c.label) parts.push(String(c.label));
+      if (c.placeholder) parts.push(String(c.placeholder));
+      if (c.text) parts.push(String(c.text));
+    }
+  }
+  return parts.join(' ').toLowerCase();
+}
+
+let probeOk = true;
+for (const probe of RETRIEVAL_PROBES) {
+  const r = await generateUI({ intent: probe.intent, engine: probe.engine });
+  const text = extractText(r.messages);
+  const matched = probe.expectKeywords.some((k) => text.includes(k.toLowerCase()));
+  const tag = matched ? 'ok' : 'FAIL';
+  const preview = text.slice(0, 60).replace(/\s+/g, ' ');
+  console.log(`[smoke/retrieval] "${probe.intent.slice(0, 38)}…" → strategy=${r.strategy} text="${preview}…" ${matched ? '✓' : `✗ expected one of [${probe.expectKeywords.slice(0, 3).join(', ')}]`} [${tag}]`);
+  if (!matched) probeOk = false;
+}
+console.log(`\n[smoke] retrieval-quality probes: ${probeOk ? 'ok' : 'FAIL'}`);
+
+if (!ok || !probeOk) process.exit(1);

package/scripts/smoke-issues.mjs

@@ -257,7 +257,7 @@ console.log('\n=== AUTO_FIRE_POLICY exported ===');
 t('AUTO_FIRE_POLICY exports expected reasons',
   ['synthesizer-exhausted', 'validator-exhausted', 'locator-empty-targets',
    'retrieval-zero-then-synthesis-fail', 'cache-miss-on-known-state',
-   'ops-failed-after-apply'].every((r) => AUTO_FIRE_POLICY[r])
+   'ops-failed-after-apply', 'scope-drift', 'iteration-synthesis-failure'].every((r) => AUTO_FIRE_POLICY[r])
 );
 
 await rm(TMP, { recursive: true, force: true });

package/tools/synthesis.js

@@ -401,7 +401,7 @@ The tool returns BOTH paths in its response: \`path\` (.json) and \`markdown_pat
   • Trace report: \`{markdown_path}\` ← human-readable, scan this first
   • Raw JSON:     \`{path}\`           ← machine-readable
 
-Issue files land under \`.brain/audit-history/issues/\` (immutable; resolution lands in a sidecar file). Severity taxonomy matches the project's coherence-audit vocabulary: blocker = contract violation; drift = quality erosion; nit = cosmetic.`,
+Issue files land under \`.brain/audit-history/issues/\` (immutable; resolution lands in a sidecar file). Severity taxonomy matches the project's ui-audit-coherence vocabulary: blocker = contract violation; drift = quality erosion; nit = cosmetic.`,
     {
       type: z.enum(['bug', 'training-gap', 'protocol-gap', 'ux-feedback']).describe('Issue category'),
       severity: z.enum(['blocker', 'drift', 'nit']).describe('Severity tier'),