@adia-ai/a2ui-compose 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -10,7 +10,70 @@ generator graph.
 
 ## [Unreleased]
 
-_No pending changes._
+_Nothing yet._
+
+---
+
+## [0.2.2] - 2026-05-02
+
+**Lockstep cut + reasoning-panel emission fixes.** 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-corpus"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.2.0` (covers `0.2.2`).
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.2.0` (covers `0.2.2`).
+- `core/generator.js` and `strategies/` are the surfaces that gained the new behavior below; no other compose directories touched.
+
+### Fixed — Reasoning-panel emissions surface confidence + retrieval candidates (2026-05-02)
+
+`generator.js` was emitting `status` events whose labels looked truthful but hid the data needed to judge their reliability. Two fixes that surface the missing data as `outcomes`:
+
+- **Interpret stage** now includes the domain confidence percentage and the matched signals. Previously `Domain: data` read identical at 3% confidence vs 95% — same label. Now: `Domain: data (3% confidence)` plus `Matched signals: pricing` as outcomes. Per memory `feedback_panel_label_reliability.md`.
+- **Analyze stage** runs a fast keyword `searchBlocks(intent)` and emits the top-5 candidates with scores + domains. Previously the stage reported `context.patterns.length` from `getContext(intent, 2)` — but the context-assembler only populates `result.patterns` at tier ≥ 3, so the count was structurally guaranteed to be 0. The label read "nothing relevant" when it actually meant "we didn't even look here." The fix runs a real retrieval at the analyze stage instead of relying on the wrong-tier context.
+
+Companion fix in `@adia-ai/a2ui-retrieval` Unreleased (web-research.js EXPLICIT/IMPLICIT pattern split). Both surfaces feed the same reasoning-panel deception class — five distinct bugs caught + fixed in commit `9986c71e`.
+
+---
+
+## [0.2.1] - 2026-05-02
+
+**Lockstep cut + scope-drift gate at composer time + skeleton harvest + Tier-1 block filter + high-resolution session ticket trace.** 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-corpus"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.2.0` (covers `0.2.1`).
+- `strategies/zettel/chunk-synthesizer.js` and `strategies/zettel/issue-reporter.js` are the surfaces that gained the new behavior below; no other directories under `strategies/` were touched.
+
+### Added — Scope-drift gate at composer time (2026-05-02)
+
+`composeFromIntent` now computes a scope-drift signal after every successful composition: composed-HTML component count vs. the sum of bound chunks' component counts. When `actual / expected > 1.5×` (with a 20-component floor to suppress small-UI noise), the synthesizer emits a warning with the ratio. The MCP layer auto-fires a `scope-drift` issue on detection, which writes both a JSON ticket and a high-resolution Markdown ticket showing the bound-chunk envelope, ratio, and a callout naming the canvas-drift regression class.
+
+- `chunk-synthesizer.js`: `computeScopeDrift(html, boundChunks)`, `SCOPE_DRIFT_RATIO = 1.5`, `SCOPE_DRIFT_MIN_ACTUAL = 20`. Tier-1 (single bound block) and Tier-2 (page chunk + every block resolved into a slot) both instrumented.
+- `issue-reporter.js`: new `'scope-drift'` reason in `AUTO_FIRE_POLICY` (type `bug`, severity `drift`, owner `synthesis`); `scopeDrift` flowed into the trace; ticket renderer extended with envelope + ratio + drift callout.
+
+Closes the loop on the canvas-drift regression class — the §37 fix patched the immediate symptom (84 components for a 4-stat retrieval), this trip-wire makes the class self-detecting.
+
+### Added — Skeleton harvest + Tier-1 block filter (2026-05-02)
+
+Two coordinated changes to the chunk-corpus pipeline that bound the synthesizer's output envelope.
+
+- **Skeleton harvest for nested chunks.** `harvest-chunks.mjs` now collapses each nested `data-chunk` element's inner content to `<!-- nested: <name> -->`, so page/panel chunks become compact skeletons. `dashboard-admin-page` shrank from 26,555c → 1,522c (-94%); `dashboard-overview-panel` from 12,493c → 898c (-93%); xl-bucket chunks (>10K chars) went from 2 → 0.
+- **Tier-1 retrieval `kind: 'block'` filter.** `composeFromIntent` restricts the fast-path retrieval to block-kind chunks; page/panel composition still works via Tier-2 LLM synthesis with slot-binding, where the skeleton is the right input.
+
+End-to-end: "trace documentation UI with stat cards" now produces 4 components (was 84). "kpi dashboard with stat cards" → 13 components. The retrieved chunk's component count is now an upper bound on the Tier-1 fast-path output.
+
+### Added — High-resolution session ticket trace (2026-05-02)
+
+The synthesizer now captures a `retrievalTrace` per attempt: Tier-1 hits with scores + kinds, Tier-2 catalog summary (page/panel/block counts, top-N block candidates), user-prompt char count, system-prompt hash, attempt-by-attempt LLM raw responses, validation results, plan, and HTML preview. The state cache stores it on every entry. `attachTrace('full')` (now the default when `state_id` is provided) returns the full session-replay payload.
+
+`issue-reporter.js` renders this as a sibling Markdown ticket alongside the JSON; sections cover header, description, reproduction, component count, retrieval log table, LLM attempts (raw responses), user prompt, composer plan, generated HTML preview, warnings, ops history, environment. A maintainer can replay any flagged session from the ticket alone.
 
 ---
 
@@ -21,7 +84,7 @@ packages now share one version, governed by
 [`docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../docs/specs/package-architecture.md#15-versioning-policy).
 This release also lands the `engine/` ↔ `engines/` collision fix from
 T3 of the
-[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../docs/plans/packages-architecture-fixes-2026-05-02.md)
+[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../.brain/archive/2026-Q2/PLAN-packages-architecture-fixes-2026-05-02.md)
 plan.
 
 ### Changed

package/core/generator.js

@@ -244,9 +244,23 @@ export async function* generateUIStream({ intent, executionId, llmAdapter, model
   executionId = engine.start({ intent, mode: 'stream', previousExecId });
 
   // ── Stage 1: Interpret ──
+  // Include confidence + matched signals in the status message so a reader can
+  // distinguish a strong domain match from a 3% tie-breaker. The bare label
+  // "Domain: data" is indistinguishable between "build a data dashboard" (high
+  // confidence, many signals) and "tier pricing page" (0.03 confidence, one
+  // weak signal) — same text, very different reliability.
   const domain = lookupDomain(intent);
   engine.submitStage(executionId, 'interpret', { domain, intent, confidence: domain.confidence });
-  yield { type: 'status', stage: 'interpret', message: `Domain: ${domain.domain}` };
+  const conf = domain.confidence != null ? Math.round(domain.confidence * 100) : null;
+  const signals = Array.isArray(domain.matchedSignals) && domain.matchedSignals.length
+    ? domain.matchedSignals.slice(0, 4)
+    : null;
+  yield {
+    type: 'status',
+    stage: 'interpret',
+    message: `Domain: ${domain.domain}${conf != null ? ` (${conf}% confidence)` : ''}`,
+    outcomes: signals ? [`Matched signals: ${signals.join(', ')}`] : [],
+  };
 
   // ── Clarity gate: yield clarify event if intent is vague ──
   // Only for fresh intents (not multi-turn iterations which have prior context)
@@ -267,12 +281,34 @@ export async function* generateUIStream({ intent, executionId, llmAdapter, model
   }
 
   // ── Stage 2: Analyze ──
+  // Surface the actual top-N retrieval candidates with scores. Two reasons the
+  // previous `${...patterns.length} patterns` line was misleading:
+  //   (a) `getContext(intent, 2)` runs at tier=2, but the context-assembler
+  //       only populates `result.patterns` at tier≥3 — so `context.patterns`
+  //       was STRUCTURALLY empty. "0 patterns" wasn't a retrieval result; it
+  //       was a tier mismatch. Fixed by running a fast keyword search here.
+  //   (b) The synthesizer composes from below-threshold patterns too; "0
+  //       patterns" reading as "nothing relevant" actively misleads the user.
   const context = await getContext(intent, 2);
+  const topPatternsRaw = searchBlocks(intent).slice(0, 5);
+  const candidateLines = topPatternsRaw.length
+    ? topPatternsRaw.map(p => {
+        const score = p.score != null ? ` · ${Number(p.score).toFixed(2)}` : '';
+        const domainTag = p.domain ? ` (${p.domain})` : '';
+        return `  • ${p.name}${domainTag}${score}`;
+      })
+    : ['  (no keyword match — synthesizer will compose from components)'];
   engine.submitStage(executionId, 'analyze', {
-    context, componentCount: context.components.length, patternCount: context.patterns.length,
+    context, componentCount: context.components.length, patternCount: topPatternsRaw.length,
+    topPatterns: topPatternsRaw.map(p => ({ name: p.name, score: p.score, domain: p.domain })),
     confidence: context.components.length > 0 ? 0.85 : 0.5,
   });
-  yield { type: 'status', stage: 'analyze', message: `${context.components.length} components, ${context.patterns.length} patterns` };
+  yield {
+    type: 'status',
+    stage: 'analyze',
+    message: `${context.components.length} components inspected · ${topPatternsRaw.length} pattern candidate${topPatternsRaw.length === 1 ? '' : 's'}`,
+    outcomes: ['Top retrievals:', ...candidateLines],
+  };
 
   // ── Research: web search enrichment (optional) ──
   let researchContext = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {

package/strategies/zettel/chunk-synthesizer.js

@@ -31,6 +31,12 @@ import { composeFromPlan, validatePlan } from './chunk-composer.js';
 const STRONG_RETRIEVAL_SCORE = 8;     // search-score threshold for fast path
 const PRE_SEARCH_LIMIT = 30;           // chunks shown to the LLM in the prompt
 const DEFAULT_MAX_ATTEMPTS = 2;
+// Scope-drift gate: composed HTML's component count vs. the sum of bound
+// chunks' component counts. A multiplier > SCOPE_DRIFT_RATIO trips a warning
+// + auto-fires a `scope-drift` issue. Floor prevents false positives on
+// small UIs where slot-wrapper noise dominates.
+const SCOPE_DRIFT_RATIO = 1.5;
+const SCOPE_DRIFT_MIN_ACTUAL = 20;
 
 const SYSTEM_PROMPT = `You compose web-app pages by binding training chunks into named slots.
 
@@ -141,17 +147,30 @@ function extractJSON(raw) {
 export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
   // Tier 1 — retrieval. Try semantic-blended hit first; fall back to keyword
   // when embeddings are unavailable (no chunk-embeddings.json or no API key).
-  const hits = await searchChunksAsync(intent, { limit: 5 });
+  //
+  // Restricted to kind=block: page/panel chunks are SKELETONS that need
+  // slot-binding composition (Tier 2 handles them). Returning a skeleton
+  // directly from Tier-1 would emit a near-empty page; we only want the
+  // fast-path for atomic block patterns.
+  const hits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
   if (hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE) {
     const top = getChunk(hits[0].name);
     const html = top.html || top.instances?.[0]?.html || '';
+    // Tier-1 fast path: sole bound chunk is the retrieved block. The gate
+    // is mostly a no-op here (ratio ≈ 1) but stays for symmetry — and to
+    // catch a corner case where retrieval returns a block that, post-render,
+    // expands far beyond its source (shouldn't happen, but worth detecting).
+    const scopeDrift = computeScopeDrift(html, [top]);
     return {
       html,
       plan: null,
       source: 'retrieval',
       score: hits[0].score,
       cosineScore: hits[0].cosineScore,
-      warnings: [],
+      warnings: scopeDrift.drift
+        ? [`scope drift: ${scopeDrift.actual} components in HTML vs ${scopeDrift.expected} in bound chunk (ratio ${scopeDrift.ratio.toFixed(2)}×)`]
+        : [],
+      scopeDrift,
     };
   }
 
@@ -189,6 +208,29 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   let lastError = null;
   const attempts = [];
 
+  // Trace: snapshot of the retrieval log for the issue-reporter to surface
+  // verbatim on bug tickets. Recorded once before the retry loop so it
+  // describes what the LLM actually saw.
+  const retrievalTrace = {
+    tier1Hits: hits.slice(0, 5).map((h) => ({
+      name: h.name,
+      score: Number(h.score.toFixed(3)),
+      kind: h.kind,
+      cosineScore: h.cosineScore != null ? Number(h.cosineScore.toFixed(3)) : null,
+    })),
+    tier1Threshold: STRONG_RETRIEVAL_SCORE,
+    tier1Pass: hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE,
+    catalogSize: filtered.length,
+    catalogPageNames: pageChunks.map((c) => c.name),
+    catalogPanelNames: panelChunks.map((c) => c.name),
+    catalogBlockTopN: blockHits.slice(0, 10).map((h) => ({
+      name: h.name,
+      score: Number(h.score.toFixed(3)),
+    })),
+    userPromptChars: userPrompt.length,
+    systemPromptChars: SYSTEM_PROMPT.length,
+  };
+
   for (let i = 0; i < maxAttempts; i++) {
     const retryNudge = lastError
       ? `\n\nPREVIOUS ATTEMPT FAILED: ${lastError}. Return ONLY a JSON object shaped as { "page": "...", "slot_bindings": { ... } }. No prose, no questions.`
@@ -216,12 +258,33 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
       continue;
     }
 
+    // Compute scope-drift signal: composed envelope vs sum of bound chunks.
+    // Bound chunks = page chunk + every block/panel resolved into a slot.
+    const boundNames = new Set([plan.page]);
+    for (const v of Object.values(plan.slot_bindings || {})) {
+      const arr = Array.isArray(v) ? v : [v];
+      for (const n of arr) boundNames.add(n);
+    }
+    const boundChunks = [...boundNames].map((n) => getChunk(n)).filter(Boolean);
+    const scopeDrift = computeScopeDrift(composed.html, boundChunks);
+    const driftWarnings = scopeDrift.drift
+      ? [`scope drift: ${scopeDrift.actual} components in composed HTML vs ${scopeDrift.expected} in bound chunks (ratio ${scopeDrift.ratio.toFixed(2)}× exceeds gate ${SCOPE_DRIFT_RATIO}×)`]
+      : [];
+
     return {
       html: composed.html,
       plan,
       source: 'synthesis',
-      warnings: composed.warnings,
-      synthesis: { attempts: i + 1, attemptsLog: attempts, validation },
+      warnings: [...composed.warnings, ...driftWarnings],
+      scopeDrift,
+      synthesis: {
+        attempts: i + 1,
+        attemptsLog: attempts,
+        validation,
+        retrievalTrace,
+        userPrompt,
+        systemPromptHash: hashString(SYSTEM_PROMPT),
+      },
     };
   }
 
@@ -230,6 +293,59 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
     plan: null,
     source: 'synthesis',
     warnings: [`synthesis failed after ${maxAttempts} attempts: ${lastError}`],
-    synthesis: { attempts: maxAttempts, attemptsLog: attempts },
+    synthesis: {
+      attempts: maxAttempts,
+      attemptsLog: attempts,
+      retrievalTrace,
+      userPrompt,
+      systemPromptHash: hashString(SYSTEM_PROMPT),
+    },
   };
 }
+
+// Cheap non-crypto hash for prompt-version fingerprinting in tickets.
+function hashString(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
+  return 'h' + h.toString(36);
+}
+
+/**
+ * Heuristic component count — number of opening tags in the HTML.
+ * Loose but stable proxy for A2UI envelope size; used by the scope-drift
+ * gate (above) and by issue-reporter's ticket-rendering counter.
+ */
+function countComponents(html) {
+  if (typeof html !== 'string') return 0;
+  return (html.match(/<[a-z][a-z0-9-]*/g) || []).length;
+}
+
+/**
+ * Compute the scope-drift signal for a composed result.
+ *
+ * Inputs: the final HTML string + the chunk records that fed into it
+ * (page chunk for Tier-2; the single block for Tier-1). Sums the bound
+ * chunks' component counts to get an "expected envelope," compares it to
+ * the actual composed count, and reports the ratio.
+ *
+ * Returns { actual, expected, ratio, drift } where `drift` is true when
+ * actual exceeds SCOPE_DRIFT_RATIO × expected AND actual ≥ SCOPE_DRIFT_MIN_ACTUAL.
+ */
+function computeScopeDrift(html, boundChunks) {
+  const actual = countComponents(html);
+  let expected = 0;
+  for (const c of boundChunks) {
+    if (!c) continue;
+    const chunkHtml = c.html || c.instances?.[0]?.html;
+    expected += countComponents(chunkHtml);
+  }
+  // Guard against zero-expected: when bound chunks have no HTML accounted for
+  // (rare; should only happen in malformed corpora), skip the gate rather
+  // than report infinite drift.
+  if (expected === 0) {
+    return { actual, expected, ratio: null, drift: false };
+  }
+  const ratio = actual / expected;
+  const drift = actual >= SCOPE_DRIFT_MIN_ACTUAL && ratio > SCOPE_DRIFT_RATIO;
+  return { actual, expected, ratio, drift };
+}

package/strategies/zettel/issue-reporter.js

@@ -75,6 +75,16 @@ export const AUTO_FIRE_POLICY = {
     suggested_owner: 'validator',
     titleFor: () => `refine_composition ops_failed list non-empty after apply`,
   },
+  'scope-drift': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'synthesis',
+    titleFor: (ctx) => {
+      const ratio = ctx?.scopeDrift?.ratio != null ? `${ctx.scopeDrift.ratio.toFixed(1)}×` : '';
+      const intent = ctx?.intent ? ` for "${truncate(ctx.intent, 40)}"` : '';
+      return `Scope drift${ratio ? ' ' + ratio : ''}: composed HTML exceeds bound-chunk envelope${intent}`;
+    },
+  },
 };
 
 function truncate(s, n = 60) {
@@ -167,9 +177,20 @@ export async function attachTrace(state_id, depth, cache) {
     };
   }
 
-  // 'full'
+  // 'full' — high-resolution session trace. Includes everything from
+  // summary plus the synthesis breadcrumbs (retrieval log, LLM prompts,
+  // raw responses per attempt, validation, plan, composed HTML preview)
+  // so a human reviewer or future agent can replay the full session.
   return {
     ...baseTrace,
+    intent: entry.intent ?? null,
+    source: entry.source ?? null,
+    score: entry.score ?? null,
+    plan: entry.plan ?? null,
+    synthesis: entry.synthesis ?? null, // retrievalTrace, attemptsLog, prompts
+    htmlPreview: entry.html ? truncateHtmlForTrace(entry.html) : null,
+    componentCount: entry.html ? countComponents(entry.html) : null,
+    scopeDrift: entry.scopeDrift ?? null,
     internal: entry.internal ?? null,
     output: entry.output ?? {
       ops: entry.ops_history || [],
@@ -177,9 +198,27 @@ export async function attachTrace(state_id, depth, cache) {
     },
     warnings: entry.warnings || [],
     duration_ms: entry.duration_ms ?? null,
+    parent_state_id: entry.parent_state_id ?? null,
+    created_at: entry.created_at ?? null,
   };
 }
 
+const HTML_PREVIEW_MAX_BYTES = 8 * 1024;
+
+function truncateHtmlForTrace(html) {
+  if (typeof html !== 'string') return null;
+  if (html.length <= HTML_PREVIEW_MAX_BYTES) return html;
+  return html.slice(0, HTML_PREVIEW_MAX_BYTES) + `\n<!-- ... ${html.length - HTML_PREVIEW_MAX_BYTES} bytes truncated -->`;
+}
+
+function countComponents(html) {
+  if (typeof html !== 'string') return 0;
+  // Count opening tags (excluding void/standalone HTML elements that
+  // don't contribute to A2UI component count). Loose heuristic; signals
+  // scope drift even if it's not a perfect protocol-level count.
+  return (html.match(/<[a-z][a-z0-9-]*/g) || []).length;
+}
+
 /**
  * Write an issue to disk.
  *
@@ -198,7 +237,11 @@ export async function reportIssue(input, ctx = {}) {
     ? ctx.reporter
     : 'user';
 
-  const traceDepth = input.trace ?? (input.state_id ? 'summary' : 'none');
+  // Default to 'full' when a state_id is provided — high-resolution session
+  // tickets are the design intent (the previous 'summary' default produced
+  // tickets too thin to debug from). Caller can opt down to 'summary' or
+  // 'none' explicitly.
+  const traceDepth = input.trace ?? (input.state_id ? 'full' : 'none');
   let trace = null;
   if (input.state_id && traceDepth !== 'none') {
     trace = await attachTrace(input.state_id, traceDepth, ctx.cache);
@@ -237,7 +280,181 @@ export async function reportIssue(input, ctx = {}) {
   const path = join(storageRoot, `${issue_id}.json`);
   await writeFile(path, JSON.stringify(issue, null, 2));
 
-  return { issue_id, path, ack: 'logged' };
+  // Write a sibling Markdown report for human review. The JSON ticket
+  // is the machine-readable source of truth; the .md is the readable
+  // surface a maintainer scans first to triage. Always written when
+  // we have a non-trivial trace (full or summary), so reviewers can
+  // see retrieval log, LLM prompts, attempts, plan, and composed HTML
+  // without reading the raw JSON.
+  let markdown_path = null;
+  if (trace) {
+    markdown_path = join(storageRoot, `${issue_id}.md`);
+    await writeFile(markdown_path, renderTicketMarkdown(issue, trace));
+  }
+
+  return {
+    issue_id,
+    path,                  // .json (machine-readable)
+    markdown_path,         // .md (human-readable; null when trace='none')
+    ack: 'logged',
+    severity: issue.severity,
+    suggested_owner: issue.suggested_owner,
+  };
+}
+
+/**
+ * Render the high-resolution session ticket as Markdown.
+ * Sections (each appears only if relevant data exists):
+ *   1. Header (id, severity, type, title, owner, tags)
+ *   2. Description (body)
+ *   3. Reproduction (intent, state_id, source, score)
+ *   4. Component-count drift (heuristic; flagged when > 50 components)
+ *   5. Retrieval log (Tier 1 hits + Tier 2 catalog summary)
+ *   6. LLM trace (each attempt's raw response)
+ *   7. Composer plan (slot bindings)
+ *   8. HTML preview (first 8KB of generated output)
+ *   9. Warnings + ops history
+ *  10. Environment (mcp/engine/model)
+ */
+function renderTicketMarkdown(issue, trace) {
+  const lines = [];
+  lines.push(`# ${issue.title}`);
+  lines.push('');
+  lines.push(`> **${issue.severity.toUpperCase()}** · ${issue.type} · owner: \`${issue.suggested_owner}\` · ${issue.created_at}`);
+  lines.push('> ');
+  lines.push(`> Issue ID: \`${issue.issue_id}\`${issue.tags?.length ? ' · tags: ' + issue.tags.map((t) => '`' + t + '`').join(' ') : ''}`);
+  lines.push('');
+
+  if (issue.body) {
+    lines.push('## Description');
+    lines.push('');
+    lines.push(issue.body);
+    lines.push('');
+  }
+
+  if (trace.intent || trace.state_id) {
+    lines.push('## Reproduction');
+    lines.push('');
+    if (trace.intent) lines.push(`- **Intent**: \`${trace.intent}\``);
+    if (trace.state_id) lines.push(`- **State ID**: \`${trace.state_id}\``);
+    if (trace.source) lines.push(`- **Source**: ${trace.source}${trace.score != null ? ` (score: ${trace.score.toFixed(3)})` : ''}`);
+    if (trace.parent_state_id) lines.push(`- **Parent state**: \`${trace.parent_state_id}\``);
+    if (trace.duration_ms != null) lines.push(`- **Duration**: ${trace.duration_ms}ms`);
+    lines.push('');
+  }
+
+  if (trace.componentCount != null) {
+    lines.push('## Component count');
+    lines.push('');
+    lines.push(`- **${trace.componentCount}** components in generated HTML`);
+    if (trace.scopeDrift) {
+      const sd = trace.scopeDrift;
+      const flag = sd.drift ? ' ⚠ **scope drift**' : '';
+      const ratio = sd.ratio != null ? `${sd.ratio.toFixed(2)}×` : 'n/a';
+      lines.push(`- Bound-chunk envelope: ${sd.expected} components`);
+      lines.push(`- Ratio (actual / expected): **${ratio}**${flag}`);
+      if (sd.drift) {
+        lines.push('');
+        lines.push(`> The composed HTML's component count exceeds the bound chunks' envelope by more than the drift gate. This is the canvas-drift regression class — the synthesizer materialized markup beyond what the retrieved chunks justify.`);
+      }
+    } else if (trace.componentCount > 50) {
+      lines.push('- ⚠ over-generation candidate (>50 components, no scope-drift signal available)');
+    }
+    lines.push('');
+  }
+
+  if (trace.synthesis?.retrievalTrace) {
+    const r = trace.synthesis.retrievalTrace;
+    lines.push('## Retrieval log');
+    lines.push('');
+    lines.push(`**Tier 1** (semantic-blended, threshold ${r.tier1Threshold}, ${r.tier1Pass ? '✓ pass' : '✗ fall through to Tier 2'})`);
+    lines.push('');
+    lines.push('| rank | score | kind | chunk |');
+    lines.push('|------|------:|------|-------|');
+    r.tier1Hits.forEach((h, i) => lines.push(`| ${i + 1} | ${h.score} | ${h.kind} | \`${h.name}\` |`));
+    lines.push('');
+    if (r.catalogSize) {
+      lines.push(`**Tier 2 catalog**: ${r.catalogSize} chunks (${r.catalogPageNames.length} page · ${r.catalogPanelNames.length} panel · ${r.catalogBlockTopN.length} top-block)`);
+      lines.push('');
+      if (r.catalogBlockTopN.length) {
+        lines.push('Top block candidates:');
+        for (const h of r.catalogBlockTopN) lines.push(`  - ${h.score} \`${h.name}\``);
+        lines.push('');
+      }
+    }
+  }
+
+  if (trace.synthesis?.attemptsLog?.length) {
+    lines.push('## LLM attempts');
+    lines.push('');
+    trace.synthesis.attemptsLog.forEach((att, i) => {
+      lines.push(`### Attempt ${att.attempt ?? i + 1}`);
+      lines.push('');
+      lines.push('```json');
+      lines.push(typeof att.raw === 'string' ? att.raw.slice(0, 2000) : JSON.stringify(att.raw, null, 2).slice(0, 2000));
+      lines.push('```');
+      lines.push('');
+    });
+    if (trace.synthesis.userPrompt) {
+      lines.push('### User prompt sent to LLM');
+      lines.push('');
+      lines.push('```');
+      lines.push(trace.synthesis.userPrompt.slice(0, 3000));
+      if (trace.synthesis.userPrompt.length > 3000) lines.push(`... (${trace.synthesis.userPrompt.length - 3000} more chars)`);
+      lines.push('```');
+      lines.push('');
+      if (trace.synthesis.systemPromptHash) lines.push(`System prompt hash: \`${trace.synthesis.systemPromptHash}\` (matches across attempts)`);
+      lines.push('');
+    }
+  }
+
+  if (trace.plan) {
+    lines.push('## Composer plan');
+    lines.push('');
+    lines.push('```json');
+    lines.push(JSON.stringify(trace.plan, null, 2));
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (trace.htmlPreview) {
+    lines.push('## Generated HTML (preview)');
+    lines.push('');
+    lines.push('```html');
+    lines.push(trace.htmlPreview);
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (trace.warnings?.length) {
+    lines.push('## Warnings');
+    lines.push('');
+    for (const w of trace.warnings) lines.push(`- ${w}`);
+    lines.push('');
+  }
+
+  if (trace.output?.ops?.length) {
+    lines.push('## Ops history (refinement chain)');
+    lines.push('');
+    lines.push(`${trace.output.ops.length} ops applied. ${trace.output.delta_summary ? 'Last delta: ' + trace.output.delta_summary : ''}`);
+    lines.push('');
+  }
+
+  if (issue.environment) {
+    lines.push('## Environment');
+    lines.push('');
+    for (const [k, v] of Object.entries(issue.environment)) lines.push(`- **${k}**: ${v}`);
+    lines.push('');
+  }
+
+  if (issue.related_issue_ids?.length) {
+    lines.push('## Related issues');
+    lines.push('');
+    for (const id of issue.related_issue_ids) lines.push(`- \`${id}\``);
+    lines.push('');
+  }
+
+  return lines.join('\n');
 }
 
 /**