@adia-ai/a2ui-mcp 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -11,6 +11,105 @@ zettel strategies.
 
 ---
 
+## [0.1.0] - 2026-04-28
+
+**Multi-turn gen-UI tool surface (Phase A code-complete).** Adds three new
+MCP tools that turn the chunk-composition pipeline from single-shot into a
+multi-turn surface, plus extends `compose_from_chunks` to mint a `state_id`
+for refinement chains.
+
+Spec: [`docs/specs/genui-multiturn-architecture.md`](../../../docs/specs/genui-multiturn-architecture.md) (Active v0.1.0).
+Plan: [`docs/plans/genui-multiturn-rollout-2026-04-28.md`](../../../docs/plans/genui-multiturn-rollout-2026-04-28.md) (Phase A scoped).
+ADR: [`0008-multiturn-genui-architecture.md`](../../../.brain/adrs/0008-multiturn-genui-architecture.md).
+
+### Added (MCP tools)
+
+- **`refine_composition(state_id, intent | ops, max_attempts?)`** — takes a
+  `state_id` from a prior `compose_from_chunks` (or `refine_composition`)
+  call plus either a natural-language intent OR an explicit op-list, runs
+  the chunk-refiner's two-pass synthesis (locator → modifier; validator-
+  driven retry on op-validation failure), applies the resulting chunk-plan
+  ops, re-materializes HTML, mints a child `state_id` chained back to the
+  parent, and returns A2UI `updateComponents` messages (the wire format).
+  Failed ops surface in `ops_failed` with reasons; the new state is cached
+  for further refinement.
+- **`get_state(state_id)`** — read-only inspection of a cached composition
+  state. Returns the chunk binding plan, materialized HTML, ops history
+  (chronological list of every refinement applied to this state's lineage),
+  and `parent_state_id` (chain-back). Auto-fires `cache-miss-on-known-state`
+  (severity `nit`) when the id is absent.
+- **`report_issue(type, severity, title, body, state_id?, trace?, …)`** —
+  first-class telemetry / dev-process feedback tool. Writes a structured
+  JSON ticket to `.brain/audit-history/issues/<issue_id>.json`. Three
+  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`
+  discipline. Trace levels: `'full' | 'summary' | 'none'`; oversized
+  traces (> 200 KB) spill to a sidecar `.trace.json` file. Tool count
+  goes from 25 → 28.
+
+### Changed
+
+- **`compose_from_chunks`** now mints a `state_id` and caches the result
+  before returning. The response shape gains a `state_id` field; existing
+  fields (`html`, `plan`, `source`, `score`, `warnings`, `synthesis`)
+  are unchanged. Backward-compatible — consumers ignoring `state_id` see
+  no behavior change.
+- **MCP server boot** instantiates a `getStateCache()` singleton and an
+  `ENGINE_VERSION_INFO` block (mcp 0.1.0, corpus 0.0.6, engine zettel,
+  llm_adapter anthropic) that's threaded through every issue-reporter
+  call so written tickets carry environment metadata.
+
+### Auto-fire policy (engine-driven)
+
+`refine_composition` and `get_state` auto-fire `report_issue` on these
+failure paths via the per-tool-call `IssueAccumulator`:
+
+| Path | Type | Severity |
+|---|---|---|
+| Synthesizer exhausts retries | bug | drift |
+| Validator exhausts retries on refinement | bug | blocker |
+| Locator pass returns empty for targeted intent | bug | drift |
+| Retrieval 0 + synthesis fallback fails | training-gap | drift |
+| `get_state` called with absent `state_id` | bug | nit |
+| `refine_composition` ops_failed list non-empty | bug | drift |
+
+Multiple auto-fires within one tool call coalesce into a single issue
+(highest severity wins; reasons listed in body + tags).
+
+### Smoke + eval
+
+- `smoke:state-cache` — 34/34.
+- `smoke:issues` — 62/62.
+- `smoke:refine` — 51/51 (stub LLM).
+- `test:a2ui` — 25/25 + 1 skipped (was 19/19 + 1; +6 multi-turn assertions).
+- `mcp:smoke` — server boots clean with 28 tools registered.
+- **`eval:refine-synthesis`** — 15/15 PASS. Ops 100%, validate 100%,
+  0 auto-fires, 67 s.
+- **No regression:** `eval:chunk-synthesis` 10/10, `eval:diff zettel`
+  coverage 83 / score 89 / MRR 0.986.
+
+### Dependencies
+
+- Bumps `@adia-ai/a2ui-compose` requirement from `^0.0.1` to `^0.1.0`.
+
+### Migration
+
+Additive surface; no breaking changes. The existing 25 tools are
+unchanged behaviorally; `compose_from_chunks` adds a `state_id` field to
+its response that ignoring consumers can safely drop.
+
+### Phase A simplification (documented)
+
+Refinement ops internally use a chunk-plan vocabulary
+(`rebindSlot | appendToSlot | removeFromSlot | replacePage`), wrapped
+on output as standard `updateComponents` A2UI messages with
+`components[].html` carrying the materialized payload. Strict
+component-tree shape upgrade is queued for Phase B.
+
+---
+
 ## [0.0.5] - 2026-04-28
 
 **Retires the legacy exemplar auto-ingest.** Server boot no longer pulls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@adia-ai/a2ui-compose": "^0.0.1",
+    "@adia-ai/a2ui-compose": "^0.1.0",
     "@adia-ai/a2ui-retrieval": "^0.0.1",
     "@adia-ai/a2ui-validator": "^0.0.1",
     "@adia-ai/a2ui-corpus": "^0.0.6",

package/scripts/eval-refine-synthesis.mjs

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Real-LLM eval set for the chunk-refiner — multi-turn refinement engine.
+ *
+ * Walks 5 seed compositions × 3 refinement intents = 15 total. Seeds are
+ * deterministic chunk-binding plans (no LLM cost on the create side); the
+ * refiner exercises the full two-pass synthesis (locator → modifier),
+ * validator-driven retry, and op-application path.
+ *
+ * Pass criteria (per spec §6.2 + plan §1.7):
+ *   - ≥ 80% of refinements produce ops (no all-fail outcome).
+ *   - ≥ 90% of returned ops apply cleanly (validator + applyOps).
+ *   - ≤  5 auto-fired issues across the full run (plan §1.8 #3).
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md (Active v0.1.0).
+ * Plan: docs/plans/genui-multiturn-rollout-2026-04-28.md (Phase A).
+ *
+ * Usage:
+ *   ANTHROPIC_API_KEY=… node packages/a2ui/mcp/scripts/eval-refine-synthesis.mjs
+ */
+
+import '../../../../scripts/load-env.mjs';
+import {
+  refineFromIntent,
+  applyOps,
+} from '../../compose/engines/zettel/chunk-refiner.js';
+import { mintStateId } from '../../compose/engines/zettel/state-cache.js';
+import { createIssueAccumulator } from '../../compose/engines/zettel/issue-reporter.js';
+import { composeFromPlan } from '../../compose/engines/zettel/chunk-composer.js';
+import { listChunksByKind, getChunk } from '../../corpus/scripts/chunk-library.js';
+import { createAdapter } from '../../compose/llm/llm-bridge.js';
+
+// ── Discover corpus shape ────────────────────────────────────────────
+// Pick a page with ≥ 2 slots so refinements have room to target.
+
+const pages = listChunksByKind('page');
+const panels = listChunksByKind('panel');
+const blocks = listChunksByKind('block');
+
+const slotsOf = (c) => (c.slots || c.instances?.[0]?.slots || []).map((s) => s.name);
+
+const samplePage =
+  pages.find((p) => slotsOf(p).length >= 2)
+  || panels.find((p) => slotsOf(p).length >= 2)
+  || pages[0]
+  || panels[0];
+
+if (!samplePage || slotsOf(samplePage).length === 0) {
+  console.error('Corpus has no page/panel chunks with declared slots — aborting eval');
+  process.exit(2);
+}
+
+const pageSlots = slotsOf(samplePage);
+const slotA = pageSlots[0];                  // typically the header slot
+const slotB = pageSlots[1] || pageSlots[0];  // typically the content slot
+
+// Pick at least 4 distinct block chunks. Filter out anything missing HTML.
+const usableBlocks = blocks
+  .filter((b) => (b.html || b.instances?.[0]?.html))
+  .slice(0, 8)
+  .map((b) => b.name);
+
+if (usableBlocks.length < 4) {
+  console.error(`Corpus has only ${usableBlocks.length} usable block chunks (need ≥ 4) — aborting eval`);
+  process.exit(2);
+}
+
+const [B0, B1, B2, B3, B4 = B0, B5 = B1] = usableBlocks;
+
+console.log(`▶ refine-synthesis eval`);
+console.log(`  page: ${samplePage.name} (${pageSlots.join(', ')})`);
+console.log(`  blocks: ${usableBlocks.slice(0, 6).join(', ')}`);
+console.log('');
+
+// ── Seeds + refinements ──────────────────────────────────────────────
+// 5 seeds × 3 refinements = 15 hold-out intents.
+
+const SEEDS = [
+  {
+    label: 'two-block-content',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1, B2] },
+    },
+    refinements: [
+      `add another block to ${slotB}`,
+      `remove one block from ${slotB}`,
+      `swap the ${slotA} for a different option`,
+    ],
+  },
+  {
+    label: 'single-block-content',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1] },
+    },
+    refinements: [
+      `add a second block alongside the existing one in ${slotB}`,
+      `replace the ${slotA} with a more concise header`,
+      `preserve the existing block and append another to ${slotB}`,
+    ],
+  },
+  {
+    label: 'three-block-stack',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1, B2, B3] },
+    },
+    refinements: [
+      `remove the middle block from ${slotB}`,
+      `drop the last block from ${slotB}`,
+      `make the layout more compact`,
+    ],
+  },
+  {
+    label: 'header-only',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B1] },
+    },
+    refinements: [
+      `add an additional block to ${slotB}`,
+      `change the ${slotA}`,
+      `preserve everything and add a new block to ${slotB}`,
+    ],
+  },
+  {
+    label: 'mixed-stack',
+    plan: {
+      page: samplePage.name,
+      slot_bindings: { [slotA]: [B0], [slotB]: [B2, B3] },
+    },
+    refinements: [
+      `swap the first block in ${slotB} for a different one`,
+      `add another block at the end of ${slotB}`,
+      `drop the last block from ${slotB}`,
+    ],
+  },
+];
+
+// ── Run ──────────────────────────────────────────────────────────────
+
+const llmAdapter = await createAdapter();
+const startedAt = Date.now();
+const results = [];
+const autoFires = { total: 0, byReason: {} };
+
+for (const seed of SEEDS) {
+  // Materialize the seed plan (no LLM call; pure compose-from-plan).
+  const composed = composeFromPlan(seed.plan);
+  if (!composed.html) {
+    console.log(`✗ seed [${seed.label}] failed to materialize — skipping refinements`);
+    for (const intent of seed.refinements) {
+      results.push({
+        seed: seed.label, intent, ms: 0, ops_count: 0, attempts: 0,
+        targeted: null, ops_applied: 0, ops_failed: 0,
+        auto_fires: [], error: 'seed-materialize-failed',
+      });
+    }
+    continue;
+  }
+
+  const priorState = {
+    state_id: mintStateId(seed.label, 1),
+    intent: `[seed] ${seed.label}`,
+    plan: seed.plan,
+    html: composed.html,
+    version: 1,
+  };
+
+  console.log(`── seed [${seed.label}] · ${seed.plan.slot_bindings[slotB].length} block(s) in ${slotB}`);
+
+  for (const intent of seed.refinements) {
+    const acc = createIssueAccumulator();
+    const t0 = Date.now();
+    const row = {
+      seed: seed.label, intent, ms: 0, ops_count: 0, attempts: 0,
+      targeted: null, ops_applied: 0, ops_failed: 0,
+      auto_fires: [], error: null,
+    };
+
+    try {
+      const refined = await refineFromIntent({
+        priorState,
+        intent,
+        llmAdapter,
+        maxAttempts: 2,
+        issueAccumulator: acc,
+      });
+      row.ms = Date.now() - t0;
+      row.ops_count = refined.ops.length;
+      row.attempts = refined.synthesis?.attempts ?? 0;
+      row.targeted = refined.synthesis?.targeted ?? null;
+
+      if (refined.ops.length > 0) {
+        const applied = await applyOps({ priorState, ops: refined.ops });
+        row.ops_applied = applied.ops_applied.length;
+        row.ops_failed = applied.ops_failed.length;
+      }
+    } catch (e) {
+      row.ms = Date.now() - t0;
+      row.error = e.message;
+    }
+
+    row.auto_fires = acc.reasons();
+    autoFires.total += row.auto_fires.length;
+    for (const r of row.auto_fires) {
+      autoFires.byReason[r] = (autoFires.byReason[r] || 0) + 1;
+    }
+
+    results.push(row);
+
+    const flag = row.ops_count > 0 && row.ops_failed === 0 ? '✓' : (row.ops_count > 0 ? '~' : '✗');
+    const tgtTag = row.targeted === true ? 'tgt' : row.targeted === false ? 'unt' : '???';
+    const padMs = row.ms.toString().padStart(5);
+    console.log(`  ${flag} [${tgtTag}] ${padMs}ms ops=${row.ops_count} att=${row.attempts} ${intent}`);
+    if (row.error) console.log(`        error: ${row.error}`);
+    if (row.ops_failed > 0) console.log(`        ops_failed: ${row.ops_failed}`);
+    if (row.auto_fires.length) console.log(`        auto-fires: ${row.auto_fires.join(', ')}`);
+  }
+}
+
+// ── Summary ──────────────────────────────────────────────────────────
+
+const total = results.length;
+const producedOps = results.filter((r) => r.ops_count > 0).length;
+const totalOpsReturned = results.reduce((s, r) => s + r.ops_count, 0);
+const totalOpsApplied = results.reduce((s, r) => s + r.ops_applied, 0);
+const totalOpsFailed = results.reduce((s, r) => s + r.ops_failed, 0);
+
+const opsRate = total ? producedOps / total : 0;
+const validateRate = totalOpsReturned ? totalOpsApplied / totalOpsReturned : 0;
+
+console.log(`\n── Summary ──`);
+console.log(`  Refinements: ${total}`);
+console.log(`  Produced ops: ${producedOps}/${total} (${(opsRate * 100).toFixed(0)}%)`);
+console.log(`  Ops returned: ${totalOpsReturned}; applied: ${totalOpsApplied}; failed: ${totalOpsFailed} (validate ${(validateRate * 100).toFixed(0)}%)`);
+console.log(`  Auto-fires: ${autoFires.total}`);
+if (autoFires.total > 0) {
+  for (const [reason, n] of Object.entries(autoFires.byReason)) {
+    console.log(`    ${reason}: ${n}`);
+  }
+}
+const targeted = results.filter((r) => r.targeted === true).length;
+const untargeted = results.filter((r) => r.targeted === false).length;
+console.log(`  Targeted vs untargeted: ${targeted} / ${untargeted}`);
+console.log(`  Total time: ${((Date.now() - startedAt) / 1000).toFixed(1)}s`);
+
+const opsThreshold = 0.8;
+const validateThreshold = 0.9;
+const autoFireCeiling = 5;
+
+const opsPass = opsRate >= opsThreshold;
+const validatePass = totalOpsReturned === 0 || validateRate >= validateThreshold;
+const autoFirePass = autoFires.total <= autoFireCeiling;
+
+const allPass = opsPass && validatePass && autoFirePass;
+
+console.log('');
+console.log(`  ops rate ≥ ${opsThreshold * 100}%:   ${opsPass ? '✓' : '✗'} (${(opsRate * 100).toFixed(0)}%)`);
+console.log(`  validate ≥ ${validateThreshold * 100}%:    ${validatePass ? '✓' : '✗'} (${(validateRate * 100).toFixed(0)}%)`);
+console.log(`  auto-fires ≤ ${autoFireCeiling}:    ${autoFirePass ? '✓' : '✗'} (${autoFires.total})`);
+
+if (allPass) {
+  console.log(`\n✓ PASS`);
+  process.exit(0);
+} else {
+  console.log(`\n✗ FAIL`);
+  process.exit(1);
+}

package/scripts/smoke-issues.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+// Smoke test: issue-reporter (write, trace attach, auto-fire, coalesce, evalMode).
+// Spec: docs/specs/genui-multiturn-architecture.md §3.5 + §4.6 + §6.4 + §11.
+
+import {
+  reportIssue,
+  autoReport,
+  attachTrace,
+  createIssueAccumulator,
+  AUTO_FIRE_POLICY,
+} from '../../compose/engines/zettel/issue-reporter.js';
+import { StateCache } from '../../compose/engines/zettel/state-cache.js';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+let pass = 0, fail = 0;
+const t = (label, ok, detail = '') => {
+  if (ok) { console.log(`  ✓ ${label}`); pass++; }
+  else    { console.log(`  ✗ ${label}  ${detail}`); fail++; }
+};
+
+const TMP = await mkdtemp(join(tmpdir(), 'a2ui-issues-'));
+const ctx = {
+  storageRoot: TMP,
+  versionInfo: { mcp: '0.1.0', corpus: '0.0.6', engine: 'zettel', llm_adapter: 'stub', model: 'test' },
+};
+
+console.log(`Storage root: ${TMP}`);
+console.log('\n=== reportIssue: basic write ===');
+
+const r1 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Test issue with simple title',
+  body: 'Test body content.',
+}, { ...ctx, reporter: 'user' });
+
+t('returns issue_id', !!r1.issue_id);
+t('issue-id format YYYY-MM-DD-slug-rand4', /^\d{4}-\d{2}-\d{2}-[a-z0-9-]+-[a-f0-9]{4}$/.test(r1.issue_id));
+t('returns ack: logged', r1.ack === 'logged');
+t('returns absolute path', r1.path.startsWith(TMP));
+
+const file1 = JSON.parse(await readFile(r1.path, 'utf8'));
+t('written file has expected type', file1.type === 'bug');
+t('written file has expected severity', file1.severity === 'drift');
+t('written file has status open', file1.status === 'open');
+t('written file has reporter.kind', file1.reporter.kind === 'user');
+t('written file has environment', file1.environment?.mcp === '0.1.0');
+t('written file has linked_specs default', Array.isArray(file1.linked_specs) && file1.linked_specs.length > 0);
+t('related_issue_ids defaults to empty array', Array.isArray(file1.related_issue_ids) && file1.related_issue_ids.length === 0);
+t('tags defaults to empty array', Array.isArray(file1.tags));
+t('suggested_owner defaults to "unknown"', file1.suggested_owner === 'unknown');
+
+console.log('\n=== validation guards ===');
+
+let threw = false;
+try { await reportIssue({ type: 'invalid', severity: 'drift', title: 't', body: 'b' }, ctx); }
+catch (e) { threw = /type must be/.test(e.message); }
+t('rejects invalid type', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'oops', title: 't', body: 'b' }, ctx); }
+catch (e) { threw = /severity must be/.test(e.message); }
+t('rejects invalid severity', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 'x'.repeat(81), body: 'b' }, ctx); }
+catch (e) { threw = /≤ 80 chars/.test(e.message); }
+t('rejects title > 80 chars', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 't', body: 'b', trace: 'partial' }, ctx); }
+catch (e) { threw = /trace must be/.test(e.message); }
+t('rejects invalid trace depth', threw);
+
+threw = false;
+try { await reportIssue({ type: 'bug', severity: 'drift', title: 't', body: 'b', tags: 'not-an-array' }, ctx); }
+catch (e) { threw = /tags must be an array/.test(e.message); }
+t('rejects non-array tags', threw);
+
+console.log('\n=== state_id trace attachment ===');
+
+const cache = new StateCache({ maxSize: 10 });
+cache.set('dash-3f9a-v1-26042817', {
+  state_id: 'dash-3f9a-v1-26042817',
+  intent: 'admin dashboard',
+  tool: 'compose_from_chunks',
+  input: { intent: 'admin dashboard' },
+  output: { html: '<dashboard/>', plan: { page: 'dashboard-admin-page' } },
+  ops_history: [
+    { type: 'createSurface', surfaceId: 'main' },
+    { type: 'updateComponents', surfaceId: 'main', components: [] },
+  ],
+  delta_summary: 'Created admin dashboard',
+  warnings: [],
+  duration_ms: 1234,
+  internal: {
+    locator_prompt: 'PROMPT_LOCATOR_v1',
+    locator_response: 'RESPONSE_LOCATOR_v1',
+    modifier_prompt: 'PROMPT_MODIFIER_v1',
+    modifier_response: 'RESPONSE_MODIFIER_v1',
+    validator_results: [{ ok: true }],
+    retries: 0,
+  },
+});
+
+const traceSummary = await attachTrace('dash-3f9a-v1-26042817', 'summary', cache);
+t('summary trace populates state_id', traceSummary?.state_id === 'dash-3f9a-v1-26042817');
+t('summary trace populates input', traceSummary?.input?.intent === 'admin dashboard');
+t('summary trace populates output.ops', Array.isArray(traceSummary?.output?.ops));
+t('summary trace omits internal field', traceSummary?.internal === undefined);
+
+const traceFull = await attachTrace('dash-3f9a-v1-26042817', 'full', cache);
+t('full trace includes internal.locator_prompt', traceFull?.internal?.locator_prompt === 'PROMPT_LOCATOR_v1');
+t('full trace includes internal.modifier_response', traceFull?.internal?.modifier_response === 'RESPONSE_MODIFIER_v1');
+t('full trace includes validator_results', Array.isArray(traceFull?.internal?.validator_results));
+
+const traceMiss = await attachTrace('not-a-real-id', 'summary', cache);
+t('attachTrace returns null on cache miss', traceMiss === null);
+
+const traceNoCache = await attachTrace('dash-3f9a-v1-26042817', 'summary', null);
+t('attachTrace returns null when no cache', traceNoCache === null);
+
+// reportIssue with state_id integrates trace
+const r2 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Issue tied to a state',
+  body: 'Reproducible on dashboard generation.',
+  state_id: 'dash-3f9a-v1-26042817',
+  trace: 'full',
+}, { ...ctx, cache });
+const file2 = JSON.parse(await readFile(r2.path, 'utf8'));
+t('reportIssue with state_id+full attaches trace.input', file2.trace?.input?.intent === 'admin dashboard');
+t('reportIssue with full trace attaches internal', file2.trace?.internal?.locator_prompt === 'PROMPT_LOCATOR_v1');
+
+// peek does not touch recency — verify the cache state didn't bump dash- to most-recent.
+// Insert a few more entries, ensure dash- stays the LRU candidate.
+// (This is exercised indirectly: state-cache smoke covers peek-recency directly.)
+
+console.log('\n=== oversized trace spills to sidecar ===');
+
+cache.set('big-state', {
+  state_id: 'big-state',
+  intent: 'big',
+  tool: 'compose',
+  input: {},
+  ops_history: [],
+  internal: { huge_dump: 'x'.repeat(300 * 1024) },
+});
+const r3 = await reportIssue({
+  type: 'bug',
+  severity: 'drift',
+  title: 'Big trace test',
+  body: 'Has an oversized trace.',
+  state_id: 'big-state',
+  trace: 'full',
+}, { ...ctx, cache });
+const file3 = JSON.parse(await readFile(r3.path, 'utf8'));
+t('oversized trace replaced by sidecar pointer', !!file3.trace?.sidecar);
+t('sidecar path has expected shape', /^traces\/.+\.trace\.json$/.test(file3.trace.sidecar));
+const sidecar = await stat(join(TMP, file3.trace.sidecar));
+t('sidecar file exists with non-zero size', sidecar.size > 0);
+
+console.log('\n=== autoReport: policy lookup ===');
+
+const a1 = await autoReport('validator-exhausted', { tool: 'refine_composition' }, ctx);
+const file_a1 = JSON.parse(await readFile(a1.path, 'utf8'));
+t('validator-exhausted: type=bug', file_a1.type === 'bug');
+t('validator-exhausted: severity=blocker', file_a1.severity === 'blocker');
+t('validator-exhausted: suggested_owner=validator', file_a1.suggested_owner === 'validator');
+t('validator-exhausted: reporter.kind=auto', file_a1.reporter.kind === 'auto');
+t('validator-exhausted: reporter.context=validator-exhausted', file_a1.reporter.context === 'validator-exhausted');
+t('validator-exhausted: tags include "auto-fire"', file_a1.tags.includes('auto-fire'));
+
+const a2 = await autoReport('retrieval-zero-then-synthesis-fail', { intent: 'pricing page' }, ctx);
+const file_a2 = JSON.parse(await readFile(a2.path, 'utf8'));
+t('retrieval-zero-then-synthesis-fail: type=training-gap', file_a2.type === 'training-gap');
+t('retrieval-zero-then-synthesis-fail: suggested_owner=chunk-corpus', file_a2.suggested_owner === 'chunk-corpus');
+t('retrieval-zero-then-synthesis-fail: title carries intent', /pricing page/.test(file_a2.title));
+
+const a3 = await autoReport('cache-miss-on-known-state', { state_id: 'gone-12ab-v1-0' }, ctx);
+const file_a3 = JSON.parse(await readFile(a3.path, 'utf8'));
+t('cache-miss-on-known-state: severity=nit', file_a3.severity === 'nit');
+
+threw = false;
+try { await autoReport('unknown-reason', {}, ctx); }
+catch (e) { threw = /unknown reason/.test(e.message); }
+t('autoReport rejects unknown reason', threw);
+
+console.log('\n=== evalMode suppresses auto-fire ===');
+
+const evalCtx = { ...ctx, evalMode: true };
+const aSuppressed = await autoReport('validator-exhausted', { tool: 'refine_composition' }, evalCtx);
+t('autoReport returns null when evalMode=true', aSuppressed === null);
+
+// Manual reportIssue still writes during evalMode (eval-suppression is auto-fire only)
+const aManual = await reportIssue({
+  type: 'bug',
+  severity: 'blocker',
+  title: 'Manual call during evalMode',
+  body: 'should still write',
+}, evalCtx);
+t('manual reportIssue ignores evalMode', !!aManual.issue_id);
+const file_manual = JSON.parse(await readFile(aManual.path, 'utf8'));
+t('manual call during evalMode writes file', file_manual.title === 'Manual call during evalMode');
+
+console.log('\n=== coalescing accumulator ===');
+
+const acc = createIssueAccumulator();
+t('empty accumulator size 0', acc.size() === 0);
+const flushEmpty = await acc.flush(ctx);
+t('empty accumulator flush returns null', flushEmpty === null);
+
+acc.add('locator-empty-targets', { intent: 'change title' });
+t('single-entry accumulator size 1', acc.size() === 1);
+const flushOne = await acc.flush(ctx);
+const file_flush_one = JSON.parse(await readFile(flushOne.path, 'utf8'));
+t('single-entry flush writes normal auto-issue', file_flush_one.reporter.kind === 'auto' && file_flush_one.reporter.context === 'locator-empty-targets');
+t('single-entry flush resets accumulator', acc.size() === 0);
+
+acc.add('locator-empty-targets', { intent: 'change title' });
+acc.add('validator-exhausted', { tool: 'refine_composition' });
+acc.add('ops-failed-after-apply', {});
+t('three-entry accumulator size 3', acc.size() === 3);
+const flushThree = await acc.flush(ctx);
+const file_flush_three = JSON.parse(await readFile(flushThree.path, 'utf8'));
+t('coalesced issue: severity=blocker (highest of three)', file_flush_three.severity === 'blocker');
+t('coalesced issue: type=bug', file_flush_three.type === 'bug');
+t('coalesced issue: reporter.context=coalesced', file_flush_three.reporter.context === 'coalesced');
+t('coalesced issue: tags include "coalesced"', file_flush_three.tags.includes('coalesced'));
+t('coalesced issue: tags include all reasons',
+  ['locator-empty-targets', 'validator-exhausted', 'ops-failed-after-apply'].every((r) => file_flush_three.tags.includes(r))
+);
+t('coalesced issue: body lists every reason',
+  file_flush_three.body.includes('locator-empty-targets') &&
+  file_flush_three.body.includes('validator-exhausted') &&
+  file_flush_three.body.includes('ops-failed-after-apply')
+);
+t('coalesced flush resets accumulator', acc.size() === 0);
+
+// evalMode + coalesce → no write
+const accEval = createIssueAccumulator();
+accEval.add('validator-exhausted', {});
+accEval.add('ops-failed-after-apply', {});
+const flushEval = await accEval.flush({ ...ctx, evalMode: true });
+t('coalesce flush returns null when evalMode=true', flushEval === null);
+
+threw = false;
+try { acc.add('not-a-real-reason'); }
+catch (e) { threw = /unknown reason/.test(e.message); }
+t('accumulator.add rejects unknown reason', threw);
+
+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])
+);
+
+await rm(TMP, { recursive: true, force: true });
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail ? 1 : 0);