@adia-ai/a2ui-mcp 0.0.4 → 0.1.0

package/scripts/smoke-state-cache.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// Smoke test: state-cache (LRU + state-id minting).
+// Spec: docs/specs/genui-multiturn-architecture.md §2.2 + §4.4.
+import {
+  StateCache,
+  mintStateId,
+  mintNextStateId,
+  getStateCache,
+  resetStateCache,
+} from '../../compose/engines/zettel/state-cache.js';
+
+let pass = 0, fail = 0;
+const t = (label, ok, detail = '') => {
+  if (ok) { console.log(`  ✓ ${label}`); pass++; }
+  else    { console.log(`  ✗ ${label}  ${detail}`); fail++; }
+};
+
+console.log('=== State-cache LRU ===');
+
+const cache = new StateCache({ maxSize: 3 });
+t('empty cache size 0', cache.size() === 0);
+t('miss returns null', cache.get('nope') === null);
+t('has returns false on miss', cache.has('nope') === false);
+
+cache.set('a', { intent: 'a', html: '<a/>' });
+cache.set('b', { intent: 'b', html: '<b/>' });
+cache.set('c', { intent: 'c', html: '<c/>' });
+t('size at capacity', cache.size() === 3);
+t('list returns insertion order', JSON.stringify(cache.list()) === JSON.stringify(['a', 'b', 'c']));
+t('has returns true on hit', cache.has('a') && cache.has('b') && cache.has('c'));
+
+// Eviction: 4th set drops oldest
+cache.set('d', { intent: 'd', html: '<d/>' });
+t('LRU evicts oldest on overflow', cache.size() === 3 && !cache.has('a') && cache.has('d'));
+
+// Recency touch via get: bump 'b' to most-recent, then set 'e'.
+// Order before: [b, c, d]. After get('b'): [c, d, b]. After set('e'): evict c → [d, b, e].
+cache.get('b');
+cache.set('e', { intent: 'e', html: '<e/>' });
+t('get touches recency', cache.has('b') && cache.has('e') && !cache.has('c'));
+
+// peek does NOT touch recency.
+// Order: [d, b, e]. peek('b') → unchanged [d, b, e]. set('f') → evict d → [b, e, f].
+const peeked = cache.peek('b');
+t('peek returns entry', peeked?.intent === 'b');
+cache.set('f', { intent: 'f', html: '<f/>' });
+t('peek does not touch recency', cache.has('b') && cache.has('e') && cache.has('f') && !cache.has('d'));
+
+// Update existing key bumps recency.
+// Order before: [b, e, f]. set('b', ...) → delete-then-insert → [e, f, b].
+cache.set('b', { intent: 'b-updated', html: '<b2/>' });
+t('update existing key bumps recency', cache.get('b').intent === 'b-updated');
+t('update preserves cache size', cache.size() === 3);
+
+// Evict
+t('evict returns true on hit', cache.evict('e') === true);
+t('evict returns false on miss', cache.evict('e') === false);
+t('evict drops entry', !cache.has('e') && cache.size() === 2);
+
+// Clear
+cache.clear();
+t('clear empties cache', cache.size() === 0 && cache.list().length === 0);
+
+console.log('\n=== State-id minting ===');
+
+const id1 = mintStateId('admin dashboard with KPIs', 1);
+t('id format: prefix-rand4-vN-unixmin', /^admin-[a-f0-9]{4}-v1-\d+$/.test(id1));
+
+const id2 = mintStateId('build me a pricing page');
+t('id uses first word as prefix', id2.startsWith('build-'));
+
+t('id with empty intent uses fallback', /^state-[a-f0-9]{4}-v1-\d+$/.test(mintStateId('')));
+t('id with whitespace-only intent uses fallback', /^state-[a-f0-9]{4}-v1-\d+$/.test(mintStateId('   ')));
+t('id strips non-alphanumeric chars', /^foo-/.test(mintStateId('foo!@#$ bar')));
+
+// Different mints → different ids in the vast majority of cases.
+const ids = new Set();
+for (let i = 0; i < 50; i++) ids.add(mintStateId('dash', 1));
+t('50 mints produce mostly distinct rand4 values', ids.size >= 45);
+
+// Next-id chain
+const root = mintStateId('dash', 1);
+const child = mintNextStateId(root, 2);
+const [pref5, rand5] = root.split('-');
+const [pref6, rand6, v6] = child.split('-');
+t('next-id preserves prefix', pref5 === pref6);
+t('next-id preserves rand4', rand5 === rand6);
+t('next-id bumps version', v6 === 'v2');
+
+const fallback = mintNextStateId('not-a-valid-id', 2);
+t('next-id falls back on bad parent', /^[a-z]+-[a-f0-9]{4}-v2-\d+$/.test(fallback));
+
+const fallbackEmpty = mintNextStateId(undefined, 3);
+t('next-id falls back on undefined parent', /^state-[a-f0-9]{4}-v3-\d+$/.test(fallbackEmpty));
+
+console.log('\n=== Singleton ===');
+
+resetStateCache({ maxSize: 5 });
+const c1 = getStateCache();
+const c2 = getStateCache();
+t('singleton returns same instance', c1 === c2);
+c1.set('x', { intent: 'x' });
+t('singleton state shared', c2.has('x'));
+
+const c3 = resetStateCache();
+t('reset replaces singleton', c3 !== c1 && c3.size() === 0);
+
+console.log('\n=== Env-driven sizing ===');
+
+process.env.A2UI_STATE_CACHE_SIZE = '7';
+const sized = resetStateCache();
+t('env-driven maxSize', sized.maxSize === 7);
+
+delete process.env.A2UI_STATE_CACHE_SIZE;
+const defaulted = resetStateCache();
+t('default maxSize 64', defaulted.maxSize === 64);
+
+process.env.A2UI_STATE_CACHE_SIZE = 'not-a-number';
+const garbage = resetStateCache();
+t('garbage env value falls back to default', garbage.maxSize === 64);
+delete process.env.A2UI_STATE_CACHE_SIZE;
+
+// Constructor opts override env
+process.env.A2UI_STATE_CACHE_SIZE = '7';
+const explicit = resetStateCache({ maxSize: 12 });
+t('constructor maxSize wins over env', explicit.maxSize === 12);
+delete process.env.A2UI_STATE_CACHE_SIZE;
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);

package/scripts/test-a2ui.mjs

@@ -236,28 +236,135 @@ if (!THINKING) {
   }
 }
 
-// ── Test 6: Training data ingestion ─────────────────────────────────
+// ── Test 6: Training corpus surfaces ────────────────────────────────
+// (The legacy exemplar extract → ingest path was retired 2026-04-28 in
+// mcp 0.0.5. The chunk corpus is the training surface now.)
 
-console.log('\n6. Training data ingestion');
+console.log('\n6. Training corpus surfaces');
 
+// 6a. Hand-authored pattern library — should be ≥ 100 entries.
+const patterns = listPatterns();
+if (patterns.length >= 100) {
+  ok('Pattern library', `${patterns.length} hand-authored patterns`);
+} else {
+  bad('Pattern library', `only ${patterns.length} (expected ≥ 100)`);
+}
+
+// 6b. Gen-UI chunk corpus — should be ≥ 500 unique chunks across
+// page / panel / block kinds.
 try {
-  const { ingestAll } = await import('../../corpus/scripts/ingest.js');
-  const result = await ingestAll();
-  if (result.registered >= 0 && result.pages > 0) {
-    ok('Ingestion', `${result.pages} pages → ${result.registered} new, ${result.replaced} replaced, ${result.skipped} skipped`);
+  const { getChunkIndex } = await import('../../corpus/scripts/chunk-library.js');
+  const idx = getChunkIndex();
+  if (idx && idx.unique_names >= 500 && idx.by_kind.block && idx.by_kind.page) {
+    ok('Chunk corpus', `${idx.unique_names} chunks (${idx.total_instances} instances; block=${idx.by_kind.block}, panel=${idx.by_kind.panel || 0}, page=${idx.by_kind.page})`);
   } else {
-    bad('Ingestion', `unexpected result: ${JSON.stringify(result)}`);
+    bad('Chunk corpus', `unexpected index: ${JSON.stringify(idx)}`);
   }
 } catch (e) {
-  bad('Ingestion', e.message);
+  bad('Chunk corpus', e.message);
 }
 
-// Final check: pattern count after ingestion
-const afterPatterns = listPatterns();
-if (afterPatterns.length >= 200) {
-  ok('Post-ingest count', `${afterPatterns.length} patterns`);
-} else {
-  bad('Post-ingest count', `only ${afterPatterns.length} (expected 200+)`);
+// ── Test 7: Multi-turn refinement modules (Phase A) ─────────────────
+// Spec: docs/specs/genui-multiturn-architecture.md.
+
+console.log('\n7. Multi-turn refinement (Phase A)');
+
+try {
+  const { StateCache, mintStateId, mintNextStateId } = await import('../../compose/engines/zettel/state-cache.js');
+  const { createIssueAccumulator } = await import('../../compose/engines/zettel/issue-reporter.js');
+  const { refineFromIntent, applyOps, opsToA2UI, validateOps } = await import('../../compose/engines/zettel/chunk-refiner.js');
+  const { listChunksByKind } = await import('../../corpus/scripts/chunk-library.js');
+
+  // 7a. State cache + state-id chain
+  const cache = new StateCache({ maxSize: 8 });
+  const root = mintStateId('admin dashboard', 1);
+  cache.set(root, { state_id: root, intent: 'admin dashboard', plan: { page: 'p', slot_bindings: {} }, ops_history: [], version: 1 });
+  const child = mintNextStateId(root, 2);
+  if (child.startsWith(root.split('-').slice(0, 2).join('-')) && child.includes('v2')) {
+    ok('State-id chain preserves stem + bumps version');
+  } else {
+    bad('State-id chain', `child=${child} root=${root}`);
+  }
+
+  // 7b. validateOps catches unknown chunks
+  const pages = listChunksByKind('page');
+  const blocks = listChunksByKind('block');
+  if (pages.length === 0 || blocks.length < 3) {
+    bad('Refiner test setup', 'corpus missing chunks');
+  } else {
+    const samplePage = pages.find((p) => (p.slots || p.instances?.[0]?.slots || []).length >= 1) || pages[0];
+    const samplePageSlots = (samplePage.slots || samplePage.instances?.[0]?.slots || []).map((s) => s.name);
+    const targetedSlot = samplePageSlots[0];
+    const priorState = {
+      state_id: root,
+      intent: 'admin dashboard',
+      plan: { page: samplePage.name, slot_bindings: { [targetedSlot]: [blocks[0].name] } },
+      html: '<placeholder/>',
+      version: 1,
+    };
+
+    const badOps = validateOps(
+      [{ type: 'rebindSlot', slot: targetedSlot, chunks: ['no-such-chunk-zzz'] }],
+      priorState,
+    );
+    if (!badOps.ok && badOps.errors.some((e) => /not found/.test(e))) {
+      ok('validateOps rejects unknown chunk');
+    } else {
+      bad('validateOps unknown chunk', JSON.stringify(badOps));
+    }
+
+    // 7c. applyOps produces materialized HTML
+    const applied = await applyOps({
+      priorState,
+      ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [blocks[1].name] }],
+    });
+    if (applied.ops_applied.length === 1 && applied.newState.html) {
+      ok('applyOps materializes new HTML');
+    } else {
+      bad('applyOps materialize', `applied=${applied.ops_applied.length} html=${!!applied.newState.html}`);
+    }
+
+    // 7d. Two-pass refineFromIntent with stub LLM
+    const stubResponses = [
+      { targeted: true, target_slots: [targetedSlot] },
+      { ops: [{ type: 'rebindSlot', slot: targetedSlot, chunks: [blocks[1].name] }], delta_summary: 'test' },
+    ];
+    let qIdx = 0;
+    const stubLLM = {
+      complete: async () => ({ content: JSON.stringify(stubResponses[qIdx++]) }),
+    };
+    const refined = await refineFromIntent({
+      priorState,
+      intent: `change ${targetedSlot}`,
+      llmAdapter: stubLLM,
+      catalog: [{ name: blocks[1].name, kind: 'block', primary: 'div', slots: [] }],
+    });
+    if (refined.ops.length === 1 && refined.synthesis.targeted) {
+      ok('refineFromIntent two-pass synthesis');
+    } else {
+      bad('refineFromIntent', `ops=${refined.ops.length} targeted=${refined.synthesis.targeted}`);
+    }
+
+    // 7e. opsToA2UI emits updateComponents wire-format
+    const wire = opsToA2UI(refined.ops, applied.newState);
+    if (wire.length === 1 && wire[0].type === 'updateComponents' && wire[0].surfaceId === 'main') {
+      ok('opsToA2UI wraps as updateComponents');
+    } else {
+      bad('opsToA2UI', JSON.stringify(wire[0]));
+    }
+
+    // 7f. IssueAccumulator coalesces via reasons()
+    const acc = createIssueAccumulator();
+    acc.add('locator-empty-targets', { intent: 't' });
+    acc.add('validator-exhausted', { tool: 't' });
+    if (acc.size() === 2 && acc.reasons().length === 2) {
+      ok('IssueAccumulator collects multiple auto-fires');
+    } else {
+      bad('IssueAccumulator', `size=${acc.size()}`);
+    }
+  }
+} catch (e) {
+  bad('Multi-turn modules', e.message);
 }
 
 // ── Summary ─────────────────────────────────────────────────────────

package/server.js

@@ -668,6 +668,37 @@ import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/z
 import { composeFromPlan, validatePlan } from '../compose/engines/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/engines/zettel/state-cache.js';
+import {
+  reportIssue as reportIssueImpl,
+  autoReport,
+  createIssueAccumulator,
+} from '../compose/engines/zettel/issue-reporter.js';
+import {
+  refineFromIntent,
+  applyOps,
+  opsToA2UI,
+  validateOps,
+} from '../compose/engines/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.
@@ -704,8 +735,20 @@ plan to skip the LLM call and just materialize HTML.`,
         };
       }
       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,
@@ -728,8 +771,23 @@ plan to skip the LLM call and just materialize HTML.`,
         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,
@@ -747,21 +805,266 @@ plan to skip the LLM call and just materialize HTML.`,
   },
 );
 
+// ── 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).
+
+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.
+
+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 ──
 
 async function main() {
   const transport = new StdioServerTransport();
 
-  // Auto-ingest training data into pattern library
-  try {
-    const { ingestAll } = await import('../corpus/scripts/ingest.js');
-    const result = await ingestAll();
-    if (result.registered > 0 || result.replaced > 0) {
-      console.error(`Training: ingested ${result.registered} new + ${result.replaced} replaced patterns (${result.pages} pages, ${result.chunks} chunks)`);
-    }
-  } catch (e) {
-    console.error(`Training: ingest skipped — ${e.message}`);
-  }
+  // (Auto-ingest of exemplar-derived patterns retired 2026-04-28 in
+  // mcp 0.0.5. The chunk corpus + chunk-aware synthesizer are the
+  // training surface now; the legacy extract → ingest path that pulled
+  // 70 patterns from prose exemplars on every server boot is gone.)
 
   await server.connect(transport);
   const catalog = await getCatalog();