@adia-ai/a2ui-mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -9,7 +9,59 @@ zettel strategies.
 
 ## [Unreleased]
 
-_No pending changes._
+_Nothing yet._
+
+---
+
+## [0.2.2] - 2026-05-02
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.1 → 0.2.2 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.1` → `0.2.2`.
+- `dependencies["@adia-ai/a2ui-compose"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.2.0` (covers `0.2.2`).
+
+### No source changes
+
+`a2ui-mcp` source is byte-identical to `0.2.1`. The cut bumps version + tracks dep ranges only. Consumers benefit from the panel-emission improvements that landed in `@adia-ai/a2ui-compose@0.2.2` and `@adia-ai/a2ui-retrieval@0.2.2` — the MCP `compose_from_chunks` and refine paths surface them automatically.
+
+---
+
+## [0.2.1] - 2026-05-02
+
+**Lockstep cut + `report_issue` trigger phrases + scope-drift auto-fire on canvas-drift detection.** All 8 published `@adia-ai/*` packages bump 0.2.0 → 0.2.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.0` → `0.2.1`.
+- `dependencies["@adia-ai/a2ui-compose"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.2.0` (covers `0.2.1`).
+- `tools/synthesis.js` is the surface that gained the new behavior (auto-fire + trigger phrases below). `scripts/eval-compose-from-chunks.mjs` updated to load the holdout fixture from its new home in `@adia-ai/a2ui-corpus/evals/` (the file moved out of `evals/` here in this cut).
+- `evals/compose-from-chunks-holdout.jsonl` removed from this package; relocated to `packages/a2ui/corpus/evals/holdout-compose-from-chunks.jsonl` to live next to the corpus it tests.
+
+### Added — `report_issue` trigger phrases + sibling Markdown ticket (2026-05-02)
+
+`report_issue` tool description now lists explicit trigger phrases ("file a ticket", "save the trace", "report this as a bug", "track this regression", "open a ticket for this", and 9 more) so the LLM knows when to fire it without guessing. The default trace depth flipped from `'summary'` to `'full'` when `state_id` is provided — the high-resolution Markdown ticket is now the design intent.
+
+Tool return shape extended with `markdown_path` alongside the existing `path` (.json). The tool description instructs the LLM to surface BOTH paths to the user with a marker so a maintainer can navigate to either:
+
+```
+📋 Logged ticket `{issue_id}` ({severity} · owner: {suggested_owner})
+• Trace report: `{markdown_path}` ← human-readable
+• Raw JSON:     `{path}`           ← machine-readable
+```
+
+### Added — `compose_from_chunks` auto-fires `scope-drift` on canvas-drift detection (2026-05-02)
+
+When the composer's scope-drift gate (a2ui-compose) flags `result.scopeDrift.drift === true`, the MCP handler auto-fires a `scope-drift` issue with `trace: 'full'`, writing both the JSON ticket and the high-res Markdown report. Tool response also echoes `scopeDrift` so the calling agent can read the ratio + decide its next move. Closes the original MCP feedback's "next time canvas-drift happens, a ticket files itself" ask.
 
 ## [0.2.0] - 2026-05-02
 
@@ -458,12 +510,12 @@ before HTML is materialized.
 
 ### Added (engine internals)
 
-- `packages/a2ui/compose/engines/zettel/chunk-composer.js` —
+- `packages/a2ui/compose/strategies/zettel/chunk-composer.js` —
   HTML-string-level composer that walks a page chunk and substitutes
   each `data-chunk-slot` region with the bound block-level chunks'
   HTML. Companion `validatePlan()` checks slot names + chunk-kind
   contracts before composition.
-- `packages/a2ui/compose/engines/zettel/chunk-synthesizer.js` —
+- `packages/a2ui/compose/strategies/zettel/chunk-synthesizer.js` —
   LLM-driven mix-and-match composition; pre-searches the catalog,
   builds a prompt with a one-shot in-context example, validates the
   LLM's binding plan against the catalog, retries with feedback on
@@ -535,7 +587,7 @@ exposes A2UI generation tools over JSON-RPC.
 Initial version at the time the monorepo was established. Contains:
 
 - MCP server (`server.js`) exposing `generate_ui`, `search_patterns`, `lookup_component`, `resolve_composition`, `validate_schema`, and related tools.
-- Engine plugin API via in-process `registerEngine()` (see `packages/a2ui/compose/engines/registry.js`).
+- Engine plugin API via in-process `registerEngine()` (see `packages/a2ui/compose/strategies/registry.js`).
 - Smoke tests (`scripts/smoke-*.mjs`) for engine registration, merged generation, and end-to-end A2UI tests.
 - Eval harnesses (`scripts/test-evals.mjs`, `scripts/test-a2ui.mjs`, `scripts/eval-fix.mjs`) for corpus regression measurement.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -10,7 +10,6 @@
     "server.js",
     "tools/",
     "scripts/",
-    "evals/",
     "personas/",
     "README.md",
     "CHANGELOG.md"

package/scripts/eval-compose-from-chunks.mjs

@@ -3,7 +3,7 @@
  * eval-compose-from-chunks.mjs — Hold-out eval for the chunk-aware
  * synthesizer. Per `docs/specs/compose-from-chunks-eval.md`.
  *
- * Reads `packages/a2ui/mcp/evals/compose-from-chunks-holdout.jsonl`,
+ * Reads `packages/a2ui/corpus/evals/holdout-compose-from-chunks.jsonl`,
  * runs each intent through `composeFromIntent`, and emits a per-intent
  * + aggregate report.
  *
@@ -52,7 +52,7 @@ import { composeFromIntent } from '../../compose/strategies/zettel/chunk-synthes
 import { searchChunksAsync } from '../../corpus/scripts/chunk-library.js';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
-const HOLDOUT = path.join(REPO_ROOT, 'packages/a2ui/mcp/evals/compose-from-chunks-holdout.jsonl');
+const HOLDOUT = path.join(REPO_ROOT, 'packages/a2ui/corpus/evals/holdout-compose-from-chunks.jsonl');
 const PASS_THRESHOLD = 80;
 
 const args = process.argv.slice(2);

package/server.js

@@ -74,6 +74,16 @@ import {
   searchChunks as searchGenUIChunks,
 } from '../corpus/scripts/chunk-library.js';
 
+// ── Inline-tool deps (transpiler / wiring / patterns / feedback) ──
+import { transpileHTML } from '../compose/transpiler/transpiler.js';
+import { getWiringCatalog } from '../retrieval/wiring-catalog.js';
+import { registerPattern } from '../retrieval/pattern-library.js';
+import { FeedbackCollector } from '../retrieval/feedback/feedback.js';
+import { feedbackStore } from '../retrieval/feedback/feedback-store.js';
+
+// ── Tools extracted to tools/ for modularity ──
+import { registerSynthesisTools } from './tools/synthesis.js';
+
 const _chunkIndex = getChunkIndex();
 if (_chunkIndex) {
   console.error(
@@ -279,9 +289,6 @@ server.tool(
 
 // ── Transpiler & Wiring Tools ──
 
-import { transpileHTML } from '../compose/transpiler/transpiler.js';
-import { getWiringCatalog } from '../retrieval/wiring-catalog.js';
-
 server.tool(
   'convert_html',
   'Convert HTML markup to A2UI flat adjacency component messages. Maps HTML tags to AdiaUI components, infers layout from styles, enforces Card content model.',
@@ -311,9 +318,6 @@ server.tool(
 
 // ── Pattern & Feedback Tools ──
 
-import { registerPattern } from '../retrieval/pattern-library.js';
-import { FeedbackCollector } from '../retrieval/feedback/feedback.js';
-
 const feedbackCollector = new FeedbackCollector();
 
 server.tool(
@@ -378,8 +382,6 @@ server.tool(
 
 // ── Quality metrics tool ──
 
-import { feedbackStore } from '../retrieval/feedback/feedback-store.js';
-
 server.tool(
   'get_quality_metrics',
   'Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.',
@@ -656,405 +658,16 @@ Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
   },
 );
 
-// ── Chunk-aware composition synthesizer (Phase C.2) ──────────────────
-// Mix-and-match: when retrieval returns no strong match, the LLM picks a
-// page chunk + binds block/panel chunks to its slots. Validator checks
-// chunk names + kind contracts; composer materializes to HTML.
+// ── Chunk-aware composition + multi-turn refinement ──────────────────
+// `compose_from_chunks`, `refine_composition`, `get_state`, `report_issue`
+// share the LLM bridge + state-cache + issue-reporter + chunk-refiner
+// stack. Extracted to tools/synthesis.js.
 //
-// Spec: docs/specs/genui-chunk-marker.md (§ "Harvester contract", future:
-// composition reasoning). Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
-
-import { composeFromIntent as composeFromChunksImpl } from '../compose/strategies/zettel/chunk-synthesizer.js';
-import { composeFromPlan, validatePlan } from '../compose/strategies/zettel/chunk-composer.js';
-import { createAdapter as createLLMAdapter } from '../compose/llm/llm-bridge.js';
-
-// ── Multi-turn architecture (Phase A) ────────────────────────────────
-// Spec: docs/specs/genui-multiturn-architecture.md (Draft v0.1.0).
-// Plan: docs/plans/genui-multiturn-rollout-2026-04-28.md (Phase A scoped).
-
-import {
-  getStateCache,
-  mintStateId,
-  mintNextStateId,
-} from '../compose/strategies/zettel/state-cache.js';
-import {
-  reportIssue as reportIssueImpl,
-  autoReport,
-  createIssueAccumulator,
-} from '../compose/strategies/zettel/issue-reporter.js';
-import {
-  refineFromIntent,
-  applyOps,
-  opsToA2UI,
-  validateOps,
-} from '../compose/strategies/zettel/chunk-refiner.js';
-
-const stateCache = getStateCache();
-
-const ENGINE_VERSION_INFO = {
-  mcp: '0.1.0',
-  corpus: '0.0.6',
-  engine: 'zettel',
-  llm_adapter: 'anthropic',
-  model: process.env.ANTHROPIC_MODEL || 'claude-opus-4-7',
-};
-
-server.tool(
-  'compose_from_chunks',
-  `Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
-
-Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
-  1. Pure-retrieval tier: if \`search_chunks\` returns a strong direct match, return
-     that chunk's HTML immediately (no LLM call).
-  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
-     binds block/panel chunks to its named slots. Output validated against the
-     chunk catalog (slot names exist, bound chunks exist, kinds match).
-
-Returns the composed HTML string + a binding plan describing which chunks plug
-where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
-country list") and no exact chunk has all those parts together — the LLM mixes
-and matches from the corpus.
-
-Two-call mode also available via \`plan\` parameter — pass a pre-baked binding
-plan to skip the LLM call and just materialize HTML.`,
-  {
-    intent: z.string().optional().describe('Natural-language description of what to build (uses LLM synthesis)'),
-    plan: z.object({
-      page: z.string(),
-      slot_bindings: z.record(z.union([z.string(), z.array(z.string())])),
-    }).optional().describe('Pre-baked binding plan (skips LLM, materializes directly)'),
-    max_attempts: z.number().int().min(1).max(5).default(2).describe('LLM retry budget for synthesis'),
-  },
-  async ({ intent, plan, max_attempts }) => {
-    if (plan) {
-      const validation = validatePlan(plan);
-      if (!validation.ok) {
-        return {
-          isError: true,
-          content: [{ type: 'text', text: JSON.stringify({ error: 'invalid plan', errors: validation.errors }, null, 2) }],
-        };
-      }
-      const result = composeFromPlan(plan);
-      const state_id = mintStateId(intent || plan.page || 'plan', 1);
-      stateCache.set(state_id, {
-        state_id,
-        intent: intent || `(plan) ${plan.page}`,
-        plan: result.plan,
-        html: result.html,
-        source: 'plan',
-        ops_history: [],
-        parent_state_id: null,
-        created_at: new Date().toISOString(),
-      });
-      return {
-        content: [{ type: 'text', text: JSON.stringify({
-          state_id,
-          html: result.html,
-          plan: result.plan,
-          warnings: result.warnings,
-          source: 'plan',
-        }, null, 2) }],
-      };
-    }
-
-    if (!intent) {
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or plan' }, null, 2) }],
-      };
-    }
-
-    try {
-      const llmAdapter = await createLLMAdapter();
-      const result = await composeFromChunksImpl({
-        intent,
-        llmAdapter,
-        maxAttempts: max_attempts,
-      });
-      const state_id = mintStateId(intent, 1);
-      stateCache.set(state_id, {
-        state_id,
-        intent,
-        plan: result.plan,
-        html: result.html,
-        source: result.source,
-        score: result.score,
-        ops_history: [],
-        parent_state_id: null,
-        warnings: result.warnings,
-        synthesis: result.synthesis,
-        created_at: new Date().toISOString(),
-      });
-      return {
-        content: [{ type: 'text', text: JSON.stringify({
-          state_id,
-          html: result.html,
-          plan: result.plan,
-          source: result.source,
-          score: result.score,
-          warnings: result.warnings,
-          synthesis: result.synthesis ? { attempts: result.synthesis.attempts } : undefined,
-        }, null, 2) }],
-      };
-    } catch (e) {
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
-      };
-    }
-  },
-);
-
-// ── Multi-turn refinement tools (Phase A) ─────────────────────────────
-// Spec: docs/specs/genui-multiturn-architecture.md §3.
-
-server.tool(
-  'refine_composition',
-  `Refine an existing chunk-composed UI based on a natural-language intent or an explicit op-list.
-
-Use when the user wants to modify an *existing* UI. Triggers on "change", "update", "modify", "add to", "remove from", "this", "it", "the X". Requires \`state_id\` from a prior \`compose_from_chunks\` call.
-
-Two modes:
-  - **Intent-driven** — pass \`intent\`. Engine runs two-pass synthesis (locator pass identifies which slots to modify; modifier pass emits chunk-plan ops). Validator-driven retry on op-validation failure.
-  - **Explicit ops** — pass \`ops\` directly. Skips the LLM entirely; engine applies + materializes.
-
-Returns a new \`state_id\` (versioned chain from the parent), the A2UI op-list applied, the post-op HTML, and a delta summary. Failed ops are reported in \`ops_failed\` with reasons.
-
-For *fresh creation* use \`compose_from_chunks\`, not this tool.`,
-  {
-    state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
-    intent: z.string().optional().describe('Natural-language description of what to change (e.g. "add a country list to page-content")'),
-    ops: z.array(z.any()).optional().describe('Pre-computed chunk-plan ops to apply directly (skips the LLM)'),
-    max_attempts: z.number().int().min(1).max(5).default(2).describe('Validator retry budget for synthesis'),
-  },
-  async ({ state_id, intent, ops, max_attempts }) => {
-    const priorState = stateCache.get(state_id);
-    if (!priorState) {
-      await autoReport(
-        'cache-miss-on-known-state',
-        { state_id, tool: 'refine_composition' },
-        { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
-      );
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({
-          error: 'state_id not found in cache',
-          hint: 'state cache is in-memory and bounded; re-run compose_from_chunks to mint a fresh state_id',
-          state_id,
-        }, null, 2) }],
-      };
-    }
-
-    if (!intent && !ops) {
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or ops' }, null, 2) }],
-      };
-    }
-
-    const issueAccumulator = createIssueAccumulator();
-    const issueCtx = { cache: stateCache, versionInfo: ENGINE_VERSION_INFO };
-    const startedAt = Date.now();
-
-    try {
-      let resolvedOps;
-      let delta_summary = '';
-      let synthesis = null;
-      let warnings = [];
-
-      if (ops && Array.isArray(ops)) {
-        // Explicit ops path — validate then apply
-        const validation = validateOps(ops, priorState);
-        if (!validation.ok) {
-          await issueAccumulator.flush(issueCtx);
-          return {
-            isError: true,
-            content: [{ type: 'text', text: JSON.stringify({
-              error: 'ops failed validation',
-              errors: validation.errors,
-            }, null, 2) }],
-          };
-        }
-        resolvedOps = ops;
-        delta_summary = `applied ${ops.length} explicit op(s)`;
-      } else {
-        // Intent path — two-pass synthesis with stub-friendly LLM bridge
-        const llmAdapter = await createLLMAdapter();
-        const refined = await refineFromIntent({
-          priorState,
-          intent,
-          llmAdapter,
-          maxAttempts: max_attempts,
-          issueAccumulator,
-        });
-        resolvedOps = refined.ops;
-        delta_summary = refined.delta_summary || '';
-        synthesis = refined.synthesis;
-        warnings = refined.warnings;
-
-        if (resolvedOps.length === 0) {
-          // Synthesizer gave up. Auto-fires already accumulated.
-          await issueAccumulator.flush(issueCtx);
-          const childId = mintNextStateId(state_id, (priorState.version || 1) + 1);
-          return {
-            content: [{ type: 'text', text: JSON.stringify({
-              state_id: childId,
-              ops_applied: [],
-              ops_failed: [],
-              delta_summary: '',
-              warnings,
-              synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted } : null,
-              html: priorState.html,
-            }, null, 2) }],
-          };
-        }
-      }
-
-      const applied = await applyOps({ priorState, ops: resolvedOps });
-
-      if (applied.ops_failed.length > 0) {
-        issueAccumulator.add('ops-failed-after-apply', {
-          state_id,
-          tool: 'refine_composition',
-          intent,
-        });
-      }
-
-      const a2uiMessages = opsToA2UI(applied.ops_applied, applied.newState);
-
-      const parentVersion = priorState.version || 1;
-      const newVersion = parentVersion + 1;
-      const newStateId = mintNextStateId(state_id, newVersion);
-
-      stateCache.set(newStateId, {
-        state_id: newStateId,
-        intent: intent || `(ops) ${priorState.intent}`,
-        plan: applied.newState.plan,
-        html: applied.newState.html,
-        source: 'refinement',
-        version: newVersion,
-        ops_history: [...(priorState.ops_history || []), ...a2uiMessages],
-        parent_state_id: state_id,
-        warnings: applied.newState.warnings,
-        delta_summary,
-        synthesis,
-        created_at: new Date().toISOString(),
-        duration_ms: Date.now() - startedAt,
-      });
-
-      await issueAccumulator.flush(issueCtx);
-
-      return {
-        content: [{ type: 'text', text: JSON.stringify({
-          state_id: newStateId,
-          ops_applied: a2uiMessages,
-          ops_failed: applied.ops_failed,
-          delta_summary,
-          warnings: [...warnings, ...(applied.newState.warnings || [])],
-          synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted, locatedTargets: synthesis.locatedTargets } : null,
-          html: applied.newState.html,
-        }, null, 2) }],
-      };
-    } catch (e) {
-      await issueAccumulator.flush(issueCtx);
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
-      };
-    }
-  },
-);
-
-server.tool(
-  'get_state',
-  `Inspect a cached composition state by state_id.
-
-Returns the full cache entry including the materialized HTML, the chunk binding plan, the chronological ops history (every refinement applied to this state's lineage), and the parent state_id (chain-back to the originating compose_from_chunks call).
+// Spec: docs/specs/genui-multiturn-architecture.md (Phase A) +
+// docs/specs/genui-chunk-marker.md.
 
-Useful for debugging refinement sequences, replaying a state's history, or verifying that a state_id is still cached before issuing a refine_composition call.
-
-Auto-fires a low-severity \`cache-miss-on-known-state\` issue when the state_id is not in the cache (the cache is bounded LRU; long-paused conversations may evict their state).`,
-  {
-    state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
-  },
-  async ({ state_id }) => {
-    const entry = stateCache.peek(state_id);
-    if (!entry) {
-      await autoReport(
-        'cache-miss-on-known-state',
-        { state_id, tool: 'get_state' },
-        { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
-      );
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({
-          error: 'state_id not found in cache',
-          state_id,
-        }, null, 2) }],
-      };
-    }
-    return {
-      content: [{ type: 'text', text: JSON.stringify({
-        state_id: entry.state_id,
-        intent: entry.intent,
-        plan: entry.plan,
-        html: entry.html,
-        source: entry.source,
-        version: entry.version || 1,
-        parent_state_id: entry.parent_state_id || null,
-        ops_history: entry.ops_history || [],
-        warnings: entry.warnings || [],
-        created_at: entry.created_at,
-      }, null, 2) }],
-    };
-  },
-);
-
-server.tool(
-  'report_issue',
-  `File a structured issue ticket when something is wrong with the gen-UI output, the tool surface, or the training data.
+registerSynthesisTools(server);
 
-Use when:
-  (a) the user explicitly says the output is broken / wrong / missing,
-  (b) you cannot satisfy the user's intent after retrying,
-  (c) you detect a mismatch between requested and produced output that you cannot fix.
-
-Include \`state_id\` for full trace attachment (input + output + LLM prompts/responses + validator results, when available in the cache).
-
-Do NOT call this for ordinary clarification or for output the user has not yet seen.
-
-Issue files land at \`.brain/audit-history/issues/<issue_id>.json\` (immutable; resolution lands in a sidecar file). Severity taxonomy matches the project's coherence-audit 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'),
-    title: z.string().max(80).describe('One-line title (≤ 80 chars)'),
-    body: z.string().describe('Markdown body — observed vs expected, repro steps'),
-    state_id: z.string().optional().describe('State id from a prior tool call; auto-attaches the trace'),
-    trace: z.enum(['full', 'summary', 'none']).optional().describe('Trace depth (default: summary if state_id provided, else none)'),
-    suggested_owner: z.enum(['synthesis', 'retrieval', 'validator', 'chunk-corpus', 'mcp-protocol', 'unknown']).optional().describe('Best-guess owner for triage'),
-    tags: z.array(z.string()).optional().describe('Free-form tags for filtering'),
-  },
-  async ({ type, severity, title, body, state_id, trace, suggested_owner, tags }) => {
-    try {
-      const result = await reportIssueImpl(
-        { type, severity, title, body, state_id, trace, suggested_owner, tags },
-        {
-          cache: stateCache,
-          versionInfo: ENGINE_VERSION_INFO,
-          reporter: 'llm',
-        }
-      );
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-      };
-    } catch (e) {
-      return {
-        isError: true,
-        content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
-      };
-    }
-  },
-);
 
 // ── Start ──
 

package/tools/synthesis.js

@@ -0,0 +1,436 @@
+/**
+ * Synthesis tools — chunk-based composition + multi-turn refinement.
+ *
+ * Extracts the 4 tools that share the LLM bridge + state-cache +
+ * issue-reporter + chunk-refiner stack: `compose_from_chunks`,
+ * `refine_composition`, `get_state`, `report_issue`.
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md (Phase A).
+ */
+
+import { z } from 'zod';
+
+import { composeFromIntent as composeFromChunksImpl } from '../../compose/strategies/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../../compose/strategies/zettel/chunk-composer.js';
+import { createAdapter as createLLMAdapter } from '../../compose/llm/llm-bridge.js';
+import {
+  getStateCache,
+  mintStateId,
+  mintNextStateId,
+} from '../../compose/strategies/zettel/state-cache.js';
+import {
+  reportIssue as reportIssueImpl,
+  autoReport,
+  createIssueAccumulator,
+} from '../../compose/strategies/zettel/issue-reporter.js';
+import {
+  refineFromIntent,
+  applyOps,
+  opsToA2UI,
+  validateOps,
+} from '../../compose/strategies/zettel/chunk-refiner.js';
+
+const stateCache = getStateCache();
+
+const ENGINE_VERSION_INFO = {
+  mcp: '0.2.0',
+  corpus: '0.2.0',
+  engine: 'zettel',
+  llm_adapter: 'anthropic',
+  model: process.env.ANTHROPIC_MODEL || 'claude-opus-4-7',
+};
+
+export { stateCache, ENGINE_VERSION_INFO, autoReport, reportIssueImpl };
+
+export function registerSynthesisTools(server) {
+  server.tool(
+    'compose_from_chunks',
+    `Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
+
+Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
+  1. Pure-retrieval tier: if \`search_chunks\` returns a strong direct match, return
+     that chunk's HTML immediately (no LLM call).
+  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
+     binds block/panel chunks to its named slots. Output validated against the
+     chunk catalog (slot names exist, bound chunks exist, kinds match).
+
+Returns the composed HTML string + a binding plan describing which chunks plug
+where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
+country list") and no exact chunk has all those parts together — the LLM mixes
+and matches from the corpus.
+
+Two-call mode also available via \`plan\` parameter — pass a pre-baked binding
+plan to skip the LLM call and just materialize HTML.`,
+    {
+      intent: z.string().optional().describe('Natural-language description of what to build (uses LLM synthesis)'),
+      plan: z.object({
+        page: z.string(),
+        slot_bindings: z.record(z.union([z.string(), z.array(z.string())])),
+      }).optional().describe('Pre-baked binding plan (skips LLM, materializes directly)'),
+      max_attempts: z.number().int().min(1).max(5).default(2).describe('LLM retry budget for synthesis'),
+    },
+    async ({ intent, plan, max_attempts }) => {
+      if (plan) {
+        const validation = validatePlan(plan);
+        if (!validation.ok) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({ error: 'invalid plan', errors: validation.errors }, null, 2) }],
+          };
+        }
+        const result = composeFromPlan(plan);
+        const state_id = mintStateId(intent || plan.page || 'plan', 1);
+        stateCache.set(state_id, {
+          state_id,
+          intent: intent || `(plan) ${plan.page}`,
+          plan: result.plan,
+          html: result.html,
+          source: 'plan',
+          ops_history: [],
+          parent_state_id: null,
+          created_at: new Date().toISOString(),
+        });
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id,
+            html: result.html,
+            plan: result.plan,
+            warnings: result.warnings,
+            source: 'plan',
+          }, null, 2) }],
+        };
+      }
+
+      if (!intent) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or plan' }, null, 2) }],
+        };
+      }
+
+      try {
+        const llmAdapter = await createLLMAdapter();
+        const result = await composeFromChunksImpl({
+          intent,
+          llmAdapter,
+          maxAttempts: max_attempts,
+        });
+        const state_id = mintStateId(intent, 1);
+        stateCache.set(state_id, {
+          state_id,
+          intent,
+          plan: result.plan,
+          html: result.html,
+          source: result.source,
+          score: result.score,
+          ops_history: [],
+          parent_state_id: null,
+          warnings: result.warnings,
+          synthesis: result.synthesis,
+          scopeDrift: result.scopeDrift,
+          created_at: new Date().toISOString(),
+        });
+
+        // Scope-drift auto-fire: composed HTML envelope exceeded the bound-
+        // chunk envelope by > SCOPE_DRIFT_RATIO. Fires a `scope-drift` issue
+        // (writes both .json and high-res .md) so post-mortem review can
+        // catch the canvas-drift regression class without manual reporting.
+        if (result.scopeDrift?.drift) {
+          await autoReport(
+            'scope-drift',
+            {
+              intent,
+              state_id,
+              scopeDrift: result.scopeDrift,
+              tags: ['canvas-drift'],
+              trace: 'full',
+            },
+            { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+          );
+        }
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id,
+            html: result.html,
+            plan: result.plan,
+            source: result.source,
+            score: result.score,
+            warnings: result.warnings,
+            scopeDrift: result.scopeDrift,
+            synthesis: result.synthesis ? { attempts: result.synthesis.attempts } : undefined,
+          }, null, 2) }],
+        };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+
+  // ── Multi-turn refinement (Phase A) ─────────────────────────────────
+  // Spec: docs/specs/genui-multiturn-architecture.md §3.
+
+  server.tool(
+    'refine_composition',
+    `Refine an existing chunk-composed UI based on a natural-language intent or an explicit op-list.
+
+Use when the user wants to modify an *existing* UI. Triggers on "change", "update", "modify", "add to", "remove from", "this", "it", "the X". Requires \`state_id\` from a prior \`compose_from_chunks\` call.
+
+Two modes:
+  - **Intent-driven** — pass \`intent\`. Engine runs two-pass synthesis (locator pass identifies which slots to modify; modifier pass emits chunk-plan ops). Validator-driven retry on op-validation failure.
+  - **Explicit ops** — pass \`ops\` directly. Skips the LLM entirely; engine applies + materializes.
+
+Returns a new \`state_id\` (versioned chain from the parent), the A2UI op-list applied, the post-op HTML, and a delta summary. Failed ops are reported in \`ops_failed\` with reasons.
+
+For *fresh creation* use \`compose_from_chunks\`, not this tool.`,
+    {
+      state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
+      intent: z.string().optional().describe('Natural-language description of what to change (e.g. "add a country list to page-content")'),
+      ops: z.array(z.any()).optional().describe('Pre-computed chunk-plan ops to apply directly (skips the LLM)'),
+      max_attempts: z.number().int().min(1).max(5).default(2).describe('Validator retry budget for synthesis'),
+    },
+    async ({ state_id, intent, ops, max_attempts }) => {
+      const priorState = stateCache.get(state_id);
+      if (!priorState) {
+        await autoReport(
+          'cache-miss-on-known-state',
+          { state_id, tool: 'refine_composition' },
+          { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+        );
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({
+            error: 'state_id not found in cache',
+            hint: 'state cache is in-memory and bounded; re-run compose_from_chunks to mint a fresh state_id',
+            state_id,
+          }, null, 2) }],
+        };
+      }
+
+      if (!intent && !ops) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or ops' }, null, 2) }],
+        };
+      }
+
+      const issueAccumulator = createIssueAccumulator();
+      const issueCtx = { cache: stateCache, versionInfo: ENGINE_VERSION_INFO };
+      const startedAt = Date.now();
+
+      try {
+        let resolvedOps;
+        let delta_summary = '';
+        let synthesis = null;
+        let warnings = [];
+
+        if (ops && Array.isArray(ops)) {
+          // Explicit ops path — validate then apply
+          const validation = validateOps(ops, priorState);
+          if (!validation.ok) {
+            await issueAccumulator.flush(issueCtx);
+            return {
+              isError: true,
+              content: [{ type: 'text', text: JSON.stringify({
+                error: 'ops failed validation',
+                errors: validation.errors,
+              }, null, 2) }],
+            };
+          }
+          resolvedOps = ops;
+          delta_summary = `applied ${ops.length} explicit op(s)`;
+        } else {
+          // Intent path — two-pass synthesis with stub-friendly LLM bridge
+          const llmAdapter = await createLLMAdapter();
+          const refined = await refineFromIntent({
+            priorState,
+            intent,
+            llmAdapter,
+            maxAttempts: max_attempts,
+            issueAccumulator,
+          });
+          resolvedOps = refined.ops;
+          delta_summary = refined.delta_summary || '';
+          synthesis = refined.synthesis;
+          warnings = refined.warnings;
+
+          if (resolvedOps.length === 0) {
+            // Synthesizer gave up. Auto-fires already accumulated.
+            await issueAccumulator.flush(issueCtx);
+            const childId = mintNextStateId(state_id, (priorState.version || 1) + 1);
+            return {
+              content: [{ type: 'text', text: JSON.stringify({
+                state_id: childId,
+                ops_applied: [],
+                ops_failed: [],
+                delta_summary: '',
+                warnings,
+                synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted } : null,
+                html: priorState.html,
+              }, null, 2) }],
+            };
+          }
+        }
+
+        const applied = await applyOps({ priorState, ops: resolvedOps });
+
+        if (applied.ops_failed.length > 0) {
+          issueAccumulator.add('ops-failed-after-apply', {
+            state_id,
+            tool: 'refine_composition',
+            intent,
+          });
+        }
+
+        const a2uiMessages = opsToA2UI(applied.ops_applied, applied.newState);
+
+        const parentVersion = priorState.version || 1;
+        const newVersion = parentVersion + 1;
+        const newStateId = mintNextStateId(state_id, newVersion);
+
+        stateCache.set(newStateId, {
+          state_id: newStateId,
+          intent: intent || `(ops) ${priorState.intent}`,
+          plan: applied.newState.plan,
+          html: applied.newState.html,
+          source: 'refinement',
+          version: newVersion,
+          ops_history: [...(priorState.ops_history || []), ...a2uiMessages],
+          parent_state_id: state_id,
+          warnings: applied.newState.warnings,
+          delta_summary,
+          synthesis,
+          created_at: new Date().toISOString(),
+          duration_ms: Date.now() - startedAt,
+        });
+
+        await issueAccumulator.flush(issueCtx);
+
+        return {
+          content: [{ type: 'text', text: JSON.stringify({
+            state_id: newStateId,
+            ops_applied: a2uiMessages,
+            ops_failed: applied.ops_failed,
+            delta_summary,
+            warnings: [...warnings, ...(applied.newState.warnings || [])],
+            synthesis: synthesis ? { attempts: synthesis.attempts, targeted: synthesis.targeted, locatedTargets: synthesis.locatedTargets } : null,
+            html: applied.newState.html,
+          }, null, 2) }],
+        };
+      } catch (e) {
+        await issueAccumulator.flush(issueCtx);
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+
+  server.tool(
+    'get_state',
+    `Inspect a cached composition state by state_id.
+
+Returns the full cache entry including the materialized HTML, the chunk binding plan, the chronological ops history (every refinement applied to this state's lineage), and the parent state_id (chain-back to the originating compose_from_chunks call).
+
+Useful for debugging refinement sequences, replaying a state's history, or verifying that a state_id is still cached before issuing a refine_composition call.
+
+Auto-fires a low-severity \`cache-miss-on-known-state\` issue when the state_id is not in the cache (the cache is bounded LRU; long-paused conversations may evict their state).`,
+    {
+      state_id: z.string().describe('State id from a prior compose_from_chunks or refine_composition call'),
+    },
+    async ({ state_id }) => {
+      const entry = stateCache.peek(state_id);
+      if (!entry) {
+        await autoReport(
+          'cache-miss-on-known-state',
+          { state_id, tool: 'get_state' },
+          { cache: stateCache, versionInfo: ENGINE_VERSION_INFO }
+        );
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({
+            error: 'state_id not found in cache',
+            state_id,
+          }, null, 2) }],
+        };
+      }
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          state_id: entry.state_id,
+          intent: entry.intent,
+          plan: entry.plan,
+          html: entry.html,
+          source: entry.source,
+          version: entry.version || 1,
+          parent_state_id: entry.parent_state_id || null,
+          ops_history: entry.ops_history || [],
+          warnings: entry.warnings || [],
+          created_at: entry.created_at,
+        }, null, 2) }],
+      };
+    },
+  );
+
+  server.tool(
+    'report_issue',
+    `File a structured issue ticket — writes BOTH a machine-readable JSON file AND a human-readable Markdown report containing the full session trace (intent, retrieval log, LLM prompts, every attempt's raw response, composer plan, generated HTML preview, component count, warnings, environment).
+
+When to call (any of these is a trigger):
+  (a) USER PHRASES — call immediately when the user says any of:
+      "file a ticket", "log a ticket", "save a ticket",
+      "report this as a bug", "report this issue", "log this issue",
+      "save the trace", "capture the session", "save the session for review",
+      "create a session ticket", "this is broken — debug it",
+      "download the trace", "export this for review",
+      "track this regression", "open a ticket for this".
+  (b) USER COMPLAINS the output is broken / wrong / missing.
+  (c) YOU CANNOT satisfy the user's intent after retrying.
+  (d) YOU DETECT a mismatch between requested and produced output you can't fix.
+
+ALWAYS pass \`state_id\` from the most-recent compose_from_chunks or refine_composition call when one exists. The default \`trace: "full"\` then writes the high-resolution Markdown ticket. (Pass \`trace: "summary"\` for compact tickets, or \`trace: "none"\` to suppress the trace entirely.)
+
+Do NOT call this for ordinary clarification or for output the user has not yet seen.
+
+The tool returns BOTH paths in its response: \`path\` (.json) and \`markdown_path\` (.md). Surface BOTH to the user so they can navigate / download either:
+
+  📋 Logged ticket \`{issue_id}\` (\`{severity}\` · owner: {suggested_owner})
+  • 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.`,
+    {
+      type: z.enum(['bug', 'training-gap', 'protocol-gap', 'ux-feedback']).describe('Issue category'),
+      severity: z.enum(['blocker', 'drift', 'nit']).describe('Severity tier'),
+      title: z.string().max(80).describe('One-line title (≤ 80 chars)'),
+      body: z.string().describe('Markdown body — observed vs expected, repro steps'),
+      state_id: z.string().optional().describe('State id from a prior tool call; auto-attaches the trace'),
+      trace: z.enum(['full', 'summary', 'none']).optional().describe('Trace depth — DEFAULT: "full" when state_id is provided (writes both .json + .md ticket with retrieval log, LLM prompts/attempts, plan, HTML preview). Use "summary" for compact tickets; "none" to suppress trace entirely.'),
+      suggested_owner: z.enum(['synthesis', 'retrieval', 'validator', 'chunk-corpus', 'mcp-protocol', 'unknown']).optional().describe('Best-guess owner for triage'),
+      tags: z.array(z.string()).optional().describe('Free-form tags for filtering'),
+    },
+    async ({ type, severity, title, body, state_id, trace, suggested_owner, tags }) => {
+      try {
+        const result = await reportIssueImpl(
+          { type, severity, title, body, state_id, trace, suggested_owner, tags },
+          {
+            cache: stateCache,
+            versionInfo: ENGINE_VERSION_INFO,
+            reporter: 'llm',
+          }
+        );
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+        };
+      }
+    },
+  );
+}

package/evals/compose-from-chunks-holdout.jsonl

@@ -1,20 +0,0 @@
-{"id":"intent-001","kind":"compose","category":"data-display","intent":"kpi grid with 4 stat cards: users, revenue, sessions, churn","expected_components":["Card","Stat","Grid"],"expected_chunk":"kpi-grid-4-card"}
-{"id":"intent-002","kind":"compose","category":"forms","intent":"sign-in form with email + password + 'forgot password' link","expected_components":["Card","Input","Button","Field"],"expected_chunk":"auth-sign-in"}
-{"id":"intent-003","kind":"compose","category":"layout","intent":"settings page with three tabs (general, integrations, billing)","expected_components":["Tabs","Tab","Card","Section"],"expected_chunk":"settings-tabs-3"}
-{"id":"intent-004","kind":"compose","category":"data","intent":"data table of users with role badge + last-active timestamp","expected_components":["Table","Badge"],"expected_chunk":"users-table"}
-{"id":"intent-005","kind":"compose","category":"data-viz","intent":"conversion funnel chart over 6 stages, with drop-off labels","expected_components":["Chart","Card","ChartLegend"],"expected_chunk":"conversion-funnel"}
-{"id":"intent-006","kind":"compose","category":"agent","intent":"agent activity feed with reasoning steps + final artifact","expected_components":["AgentTrace","AgentReasoning","AgentArtifact"],"expected_chunk":"agent-activity-feed"}
-{"id":"intent-007","kind":"compose","category":"layout","intent":"split-pane editor: code on the left, preview on the right","expected_components":["EditorShell","Pane","Code"],"expected_chunk":"editor-split"}
-{"id":"intent-008","kind":"compose","category":"overlay","intent":"command palette modal with grouped results (recent, suggestions)","expected_components":["Command","Modal"],"expected_chunk":"command-grouped"}
-{"id":"intent-009","kind":"compose","category":"forms","intent":"registration step 2 of 5 — profile setup with 4 fields","expected_components":["Card","StepProgress","Field","Input"],"expected_chunk":"reg-step-shell"}
-{"id":"intent-010","kind":"compose","category":"layout","intent":"404 error page with breadcrumb + back-to-home link","expected_components":["Card","Breadcrumb","Button"],"expected_chunk":"error-404"}
-{"id":"intent-011","kind":"refine","category":"data-display","intent":"dashboard for project metrics","refine":"add a date-range filter at the top","expected_components":["Card","Stat","Select"],"expected_chunk":"project-dashboard"}
-{"id":"intent-012","kind":"refine","category":"display","intent":"user profile card","refine":"make the email editable inline","expected_components":["Card","Avatar","Input"],"expected_chunk":"user-profile-card"}
-{"id":"intent-013","kind":"refine","category":"data","intent":"kanban board with 3 columns","refine":"add a count badge to each column header","expected_components":["Card","Badge","Header"],"expected_chunk":"kanban-3col"}
-{"id":"intent-014","kind":"refine","category":"chat","intent":"chat surface with streaming reply","refine":"add a stop button while streaming","expected_components":["ChatShell","Button","ChatInput"],"expected_chunk":"chat-streaming"}
-{"id":"intent-015","kind":"refine","category":"forms","intent":"sign-up form with email + password","refine":"add password strength meter","expected_components":["Card","Input","Progress"],"expected_chunk":"auth-sign-up"}
-{"id":"intent-016","kind":"refine","category":"settings","intent":"settings tab for notifications","refine":"split email + push into separate sections","expected_components":["Card","Section","Switch"],"expected_chunk":"settings-notifications"}
-{"id":"intent-017","kind":"refine","category":"data","intent":"table of orders","refine":"add a bulk-action toolbar above the table","expected_components":["Table","TableToolbar","Button"],"expected_chunk":"orders-table"}
-{"id":"intent-018","kind":"refine","category":"agent","intent":"agent reasoning panel","refine":"collapse intermediate steps by default, expandable","expected_components":["AgentReasoning","Accordion"],"expected_chunk":"agent-reasoning-collapsed"}
-{"id":"intent-019","kind":"refine","category":"overlay","intent":"modal confirming destructive action","refine":"require typing the resource name to confirm","expected_components":["Modal","Input","Button"],"expected_chunk":"destructive-confirm"}
-{"id":"intent-020","kind":"refine","category":"display","intent":"marketing landing hero","refine":"add a secondary 'see demo' CTA","expected_components":["Card","Heading","Button"],"expected_chunk":"marketing-hero"}