heyspex 0.1.0

package/vendor/heyspex-mcp/design-tools.mjs

@@ -0,0 +1,449 @@
+/**
+ * HeySpex Design System MCP tools
+ *
+ * Pure-logic module backing the five `heyspex_design_*` MCP tools mounted in
+ * cli.mjs. Reads from spex-console/public/design-system/ (registry.json + per-pattern
+ * r/<name>.json + tokens.dtcg.json) and spex-console/DESIGN.md.
+ *
+ * Spec: [[HS-TASK-DSMC-design-system-mcp-server]]
+ * Parent epic: [[HS-EPIC-06O0-design-system-v2-agentic-registry-hs-des]]
+ * Source of truth shape filed by [[HS-TASK-DSR1-design-system-registry-alignment]].
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const REGISTRY_DIR = ['spex-console', 'public', 'design-system'];
+const ITEMS_DIR = ['spex-console', 'public', 'design-system', 'r'];
+const TOKENS_FILE = ['spex-console', 'public', 'design-system', 'tokens.dtcg.json'];
+const DESIGN_DOC = ['spex-console', 'DESIGN.md'];
+const PROPOSALS_DIR = ['specs', 'design-proposals'];
+
+const VALID_LAYERS = new Set(['primitive', 'semantic', 'component', 'pattern']);
+const NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Filesystem readers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function loadRegistry(vaultRoot) {
+  const path = join(vaultRoot, ...REGISTRY_DIR, 'registry.json');
+  if (!existsSync(path)) return null;
+  return readJson(path);
+}
+
+export function loadRegistryItem(vaultRoot, name) {
+  const path = join(vaultRoot, ...ITEMS_DIR, `${name}.json`);
+  if (!existsSync(path)) return null;
+  return readJson(path);
+}
+
+export function listRegistryItemNames(vaultRoot) {
+  const registry = loadRegistry(vaultRoot);
+  if (!registry || !Array.isArray(registry.items)) return [];
+  return registry.items.map((it) => it.name).filter(Boolean);
+}
+
+export function loadAllRegistryItems(vaultRoot) {
+  const names = listRegistryItemNames(vaultRoot);
+  const items = [];
+  for (const name of names) {
+    const item = loadRegistryItem(vaultRoot, name);
+    if (item) items.push(item);
+  }
+  return items;
+}
+
+export function loadTokensDtcg(vaultRoot) {
+  const path = join(vaultRoot, ...TOKENS_FILE);
+  if (!existsSync(path)) return null;
+  return readJson(path);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// list_patterns
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalize(value) {
+  return String(value ?? '').toLowerCase();
+}
+
+function summarizeItem(item) {
+  const description = String(item.description ?? '').trim();
+  // First sentence (up to first period+space) or first 200 chars.
+  let summary = description;
+  const sentenceEnd = summary.search(/\.(\s|$)/);
+  if (sentenceEnd > 0 && sentenceEnd < 220) {
+    summary = summary.slice(0, sentenceEnd + 1);
+  } else if (summary.length > 200) {
+    summary = summary.slice(0, 200).trimEnd() + '…';
+  }
+  return {
+    name: item.name,
+    title: item.title ?? null,
+    layer: item.hsLayer ?? null,
+    tags: Array.isArray(item.hsTags) ? item.hsTags : [],
+    summary,
+  };
+}
+
+export function executeListPatterns(vaultRoot, args = {}) {
+  const registry = loadRegistry(vaultRoot);
+  if (!registry) {
+    return { error: 'REGISTRY_NOT_FOUND', message: 'spex-console/public/design-system/registry.json not found' };
+  }
+
+  const tagFilter = args.tag ? normalize(args.tag) : null;
+  const layerFilter = args.layer ? normalize(args.layer) : null;
+  const queryFilter = args.query ? normalize(args.query) : null;
+
+  if (layerFilter && !VALID_LAYERS.has(layerFilter)) {
+    return { error: 'INVALID_LAYER', message: `layer must be one of: ${[...VALID_LAYERS].join(', ')}` };
+  }
+
+  const items = loadAllRegistryItems(vaultRoot);
+  const matches = [];
+
+  for (const item of items) {
+    if (tagFilter) {
+      const tags = (item.hsTags ?? []).map(normalize);
+      if (!tags.includes(tagFilter)) continue;
+    }
+    if (layerFilter) {
+      if (normalize(item.hsLayer) !== layerFilter) continue;
+    }
+    if (queryFilter) {
+      const haystack = [item.name, item.title, item.description].map(normalize).join(' ');
+      if (!haystack.includes(queryFilter)) continue;
+    }
+    matches.push(summarizeItem(item));
+  }
+
+  matches.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    patterns: matches,
+    count: matches.length,
+    total: items.length,
+    filters_applied: {
+      tag: args.tag ?? null,
+      layer: args.layer ?? null,
+      query: args.query ?? null,
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// get_pattern
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function executeGetPattern(vaultRoot, args = {}) {
+  const name = String(args.name ?? '').trim();
+  if (!name) {
+    return { error: 'MISSING_NAME', message: 'name is required' };
+  }
+  const item = loadRegistryItem(vaultRoot, name);
+  if (!item) {
+    return { error: 'PATTERN_NOT_FOUND', message: `No registry item at spex-console/public/design-system/r/${name}.json` };
+  }
+  const includeCode = args.includeCode !== false; // default true
+  if (!includeCode && 'hsCodePreview' in item) {
+    const { hsCodePreview, ...rest } = item;
+    return { pattern: rest, source: `spex-console/public/design-system/r/${name}.json`, includeCode: false };
+  }
+  return { pattern: item, source: `spex-console/public/design-system/r/${name}.json`, includeCode: true };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// get_token
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeVarName(input) {
+  const trimmed = String(input ?? '').trim();
+  if (!trimmed) return null;
+  return trimmed.startsWith('--') ? trimmed : `--${trimmed.replace(/^-+/, '')}`;
+}
+
+function varNameToDtcgPath(varName) {
+  // --accent-green → ['accent', 'green']
+  // --bg-rail-highlight → ['bg', 'rail', 'highlight']
+  // --status-ready → ['status', 'ready']
+  return varName.replace(/^--/, '').split('-').filter(Boolean);
+}
+
+function lookupDtcg(tokens, path) {
+  let node = tokens;
+  for (const segment of path) {
+    if (!node || typeof node !== 'object' || !(segment in node)) return null;
+    node = node[segment];
+  }
+  return node;
+}
+
+function bestDtcgMatch(tokens, varName) {
+  // Try longest-prefix match: --bg-rail-highlight may live at bg.rail.highlight
+  // or, if "rail-highlight" is a leaf name, at bg["rail-highlight"]. Walk down
+  // greedily by segment, then if that misses, try joining trailing segments.
+  if (!tokens) return null;
+  const segments = varNameToDtcgPath(varName);
+  // exact path match
+  const direct = lookupDtcg(tokens, segments);
+  if (direct && (direct.$value !== undefined || direct.$type !== undefined)) {
+    return { path: segments, node: direct };
+  }
+  // try collapsing trailing segments into one kebab leaf
+  for (let split = segments.length - 1; split >= 1; split--) {
+    const head = segments.slice(0, split);
+    const tail = segments.slice(split).join('-');
+    const node = lookupDtcg(tokens, [...head, tail]);
+    if (node && (node.$value !== undefined || node.$type !== undefined)) {
+      return { path: [...head, tail], node };
+    }
+  }
+  return null;
+}
+
+export function executeGetToken(vaultRoot, args = {}) {
+  const varName = normalizeVarName(args.var);
+  if (!varName) {
+    return { error: 'MISSING_VAR', message: 'var is required (e.g. "--accent-green")' };
+  }
+
+  const items = loadAllRegistryItems(vaultRoot);
+  const darkValues = new Map(); // value → [pattern names]
+  const lightValues = new Map();
+  const usedBy = new Set();
+
+  for (const item of items) {
+    const cssVars = item.cssVars ?? {};
+    const darkVal = cssVars.dark?.[varName];
+    const lightVal = cssVars.light?.[varName];
+    if (darkVal !== undefined) {
+      if (!darkValues.has(darkVal)) darkValues.set(darkVal, []);
+      darkValues.get(darkVal).push(item.name);
+      usedBy.add(item.name);
+    }
+    if (lightVal !== undefined) {
+      if (!lightValues.has(lightVal)) lightValues.set(lightVal, []);
+      lightValues.get(lightVal).push(item.name);
+      usedBy.add(item.name);
+    }
+  }
+
+  // DTCG fallback / metadata
+  const tokens = loadTokensDtcg(vaultRoot);
+  let dtcgKind = null;
+  let dtcgGroups = null;
+  if (tokens) {
+    const darkMatch = bestDtcgMatch(tokens.dark, varName);
+    const lightMatch = bestDtcgMatch(tokens.light, varName);
+    if (darkMatch?.node?.$type) dtcgKind = darkMatch.node.$type;
+    else if (lightMatch?.node?.$type) dtcgKind = lightMatch.node.$type;
+    if (darkMatch) dtcgGroups = darkMatch.path.slice(0, -1);
+    else if (lightMatch) dtcgGroups = lightMatch.path.slice(0, -1);
+    if (darkMatch && !darkValues.size && darkMatch.node.$value !== undefined) {
+      darkValues.set(darkMatch.node.$value, ['(tokens.dtcg.json)']);
+    }
+    if (lightMatch && !lightValues.size && lightMatch.node.$value !== undefined) {
+      lightValues.set(lightMatch.node.$value, ['(tokens.dtcg.json)']);
+    }
+  }
+
+  if (darkValues.size === 0 && lightValues.size === 0) {
+    return { error: 'TOKEN_NOT_FOUND', message: `${varName} not found in any registry item or tokens.dtcg.json` };
+  }
+
+  return {
+    var: varName,
+    value: {
+      dark: [...darkValues.entries()].map(([value, patterns]) => ({ value, patterns })),
+      light: [...lightValues.entries()].map(([value, patterns]) => ({ value, patterns })),
+    },
+    kind: dtcgKind,
+    groups: dtcgGroups,
+    usedBy: [...usedBy].sort(),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// get_doc
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function executeGetDoc(vaultRoot, args = {}) {
+  const name = String(args.name ?? '').trim();
+  if (!name) {
+    return { error: 'MISSING_NAME', message: 'name is required' };
+  }
+  const docPath = join(vaultRoot, ...DESIGN_DOC);
+  if (!existsSync(docPath)) {
+    return { error: 'DESIGN_DOC_NOT_FOUND', message: 'spex-console/DESIGN.md not found' };
+  }
+  const content = readFileSync(docPath, 'utf8');
+  const lines = content.split(/\r?\n/);
+
+  // Anchor convention from DESIGN.md: a leading-line marker like
+  //   **`pattern-name`** (...)
+  // or sometimes just **pattern-name** (...).
+  const anchorWithBackticks = `**\`${name}\`**`;
+  const anchorPlain = `**${name}**`;
+
+  let startLine = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith(anchorWithBackticks) || line.startsWith(anchorPlain)) {
+      startLine = i;
+      break;
+    }
+  }
+
+  if (startLine === -1) {
+    return {
+      error: 'ANCHOR_NOT_FOUND',
+      message: `No "${anchorWithBackticks}" anchor in spex-console/DESIGN.md`,
+      hint: 'Anchors are leading-line markers like `**`pattern-name`**`. Check the registry item designDocAnchor field.',
+    };
+  }
+
+  // Excerpt ends at the next anchor / next heading / blank-then-anchor.
+  let endLine = lines.length;
+  for (let i = startLine + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.startsWith('## ') || line.startsWith('### ')) {
+      endLine = i;
+      break;
+    }
+    // Next `**` anchor at column 0
+    if ((line.startsWith('**`') && line.includes('`**')) || /^\*\*[a-z][a-z0-9-]+\*\*/.test(line)) {
+      endLine = i;
+      break;
+    }
+  }
+
+  const excerpt = lines.slice(startLine, endLine).join('\n').replace(/\s+$/g, '');
+
+  return {
+    name,
+    anchor: anchorWithBackticks,
+    line_start: startLine + 1,
+    line_end: endLine,
+    excerpt,
+    link: `spex-console/DESIGN.md#L${startLine + 1}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// propose_pattern
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function executeProposePattern(vaultRoot, args = {}) {
+  const name = String(args.name ?? '').trim();
+  if (!name) {
+    return { error: 'MISSING_NAME', message: 'name is required (kebab-case slug)' };
+  }
+  if (!NAME_PATTERN.test(name)) {
+    return {
+      error: 'INVALID_NAME',
+      message: 'name must be kebab-case (lowercase letters, digits, dashes) — e.g. "agent-handoff-callout"',
+    };
+  }
+
+  const title = String(args.title ?? '').trim();
+  const description = String(args.description ?? '').trim();
+  if (!title || !description) {
+    return { error: 'MISSING_FIELDS', message: 'title and description are required' };
+  }
+
+  const hsLayer = String(args.hsLayer ?? '').trim();
+  if (!VALID_LAYERS.has(hsLayer)) {
+    return {
+      error: 'INVALID_LAYER',
+      message: `hsLayer must be one of: ${[...VALID_LAYERS].join(', ')}`,
+    };
+  }
+
+  // Reject collisions with an already-shipped pattern.
+  const existingShipped = loadRegistryItem(vaultRoot, name);
+  if (existingShipped) {
+    return {
+      error: 'ALREADY_SHIPPED',
+      message: `A registry item already exists at spex-console/public/design-system/r/${name}.json — pick a different slug or update the shipped item directly.`,
+    };
+  }
+
+  const proposalsDir = join(vaultRoot, ...PROPOSALS_DIR);
+  const filename = `${name}.json`;
+  const filepath = join(proposalsDir, filename);
+
+  if (existsSync(filepath)) {
+    return {
+      error: 'PROPOSAL_EXISTS',
+      message: `Proposal already exists at specs/design-proposals/${filename} — edit the file directly or pick a different slug.`,
+      existing_path: relative(vaultRoot, filepath),
+    };
+  }
+
+  const now = new Date().toISOString();
+  const proposed_by = String(args.proposed_by ?? '').trim() || 'unknown agent';
+
+  const proposal = {
+    $schema: 'https://ui.shadcn.com/schema/registry-item.json',
+    name,
+    type: 'registry:ui',
+    title,
+    description,
+    hsLayer,
+    hsTags: Array.isArray(args.hsTags) ? args.hsTags : [],
+    hsDecisionRefs: Array.isArray(args.hsDecisionRefs) ? args.hsDecisionRefs : [],
+    designDocAnchor: String(args.designDocAnchor ?? name),
+    hsStatus: 'proposed',
+    hsProposedAt: now,
+    hsProposedBy: proposed_by,
+  };
+
+  if (args.cssVars && typeof args.cssVars === 'object') {
+    proposal.cssVars = args.cssVars;
+  }
+  if (typeof args.hsCodePreview === 'string' && args.hsCodePreview.length > 0) {
+    proposal.hsCodePreview = args.hsCodePreview;
+  }
+  proposal.files = [];
+  proposal.dependencies = [];
+  proposal.registryDependencies = [];
+
+  try {
+    if (!existsSync(proposalsDir)) {
+      mkdirSync(proposalsDir, { recursive: true });
+    }
+    writeFileSync(filepath, JSON.stringify(proposal, null, 2) + '\n', 'utf8');
+  } catch (err) {
+    return { error: 'WRITE_FAILED', message: err.message };
+  }
+
+  return {
+    success: true,
+    proposal_id: name,
+    filepath: relative(vaultRoot, filepath),
+    next_steps: [
+      `Open specs/design-proposals/${filename} and refine the cssVars + hsCodePreview blocks`,
+      `Once promoted, copy to spex-console/public/design-system/r/${filename} and add to registry.json items[]`,
+      `Add the matching prose anchor (**\`${name}\`**) to spex-console/DESIGN.md`,
+    ],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Discovery helper for slash prompts
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function listProposals(vaultRoot) {
+  const dir = join(vaultRoot, ...PROPOSALS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''))
+    .sort();
+}

package/vendor/heyspex-mcp/dev-factory-bridge.mjs

@@ -0,0 +1,66 @@
+/**
+ * dev-factory-bridge.mjs — the ONE lazy seam between the shippable MCP server and
+ * the SpexFleet / deep-research code that stays inside this repo.
+ *
+ * Why this file exists ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]]):
+ * `research-tools.mjs` used to `import` two modules from
+ * `../../dev-factory/dream-research/` at the top level. Those two static imports
+ * dragged **25 files** into the MCP server's static import closure —
+ * `dev-factory/router.mjs` (model routing), `dev-factory/cloud-clients.mjs`
+ * (provider clients + env loading), `dev-factory/cost-tracker.mjs`, and the whole
+ * `dev-factory/dream-research/` engine. Any npm package that ships a working MCP
+ * server therefore had to ship all of them, and `npm publish` is a one-way door.
+ *
+ * Loading them through `await import()` instead means:
+ *   - inside this repo, behavior is identical (the modules are right there);
+ *   - inside a published install they are simply absent, and the two research
+ *     tools degrade to an explicit `unavailable` result instead of crashing the
+ *     server at startup;
+ *   - the published file list is decided by the open-core boundary
+ *     ([[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]), not by an
+ *     accident of module graph shape.
+ *
+ * The resolution is memoized per process: one failed probe is enough, and a
+ * successful one is not re-paid on every tool call.
+ */
+
+/** @type {Promise<{ available: boolean, reason?: string, getBaseUrl?: Function, runFirecrawlResearchTool?: Function }>|undefined} */
+let dreamResearchPromise;
+
+/**
+ * Lazily resolve the deep-research surface the MCP research tools delegate to.
+ *
+ * Never throws. When the modules are not present (a published install, which
+ * ships the MCP server without SpexFleet), returns
+ * `{ available: false, reason }` so callers can report an honest downgrade
+ * rather than a stack trace.
+ */
+export function loadDreamResearch() {
+  if (dreamResearchPromise) return dreamResearchPromise;
+  dreamResearchPromise = (async () => {
+    try {
+      const [adapter, tool] = await Promise.all([
+        import('../../dev-factory/dream-research/firecrawl-adapter.mjs'),
+        import('../../dev-factory/dream-research/interactive-firecrawl-tool.mjs'),
+      ]);
+      return {
+        available: true,
+        getBaseUrl: adapter.getBaseUrl,
+        runFirecrawlResearchTool: tool.runFirecrawlResearchTool,
+      };
+    } catch (err) {
+      return {
+        available: false,
+        reason:
+          'the deep-research backend is not part of this install ' +
+          `(${err?.code ?? err?.message ?? String(err)})`,
+      };
+    }
+  })();
+  return dreamResearchPromise;
+}
+
+/** Test-only: forget the memoized probe so a test can exercise both branches. */
+export function resetDevFactoryBridgeCache() {
+  dreamResearchPromise = undefined;
+}

package/vendor/heyspex-mcp/diagnose-skeleton.mjs

@@ -0,0 +1,114 @@
+/**
+ * The ONE canonical diagnose body skeleton.
+ *
+ * Three writers inject a fill-in diagnose body — capture promotion
+ * (`promote-capture.mjs`), research promotion
+ * (`promote-research-to-diagnose.mjs`), and the deferred-work DLQ
+ * (`deferred-reclaim.mjs`). Until [[HS-I2SE-5UGW-DIAG-the-diagnose-skeleton-has-no-place-to]]
+ * each carried its own copy, so any change had to be made three times and the
+ * drift was invisible until someone diffed two filed diagnoses. The shared
+ * block below is the single definition; `diagnose-skeleton-drift.test.mjs`
+ * fails if any writer stops emitting it verbatim.
+ *
+ * Why these prompts and not just headings
+ * ([[resolution-diagnose-workflow]] §Step 2 / §Step 6):
+ *
+ * - **Root cause** asks the level check. An author who writes the first true
+ *   statement they find has satisfied an open prompt and stopped one level
+ *   above the cause. "If I fix exactly this, can the same class of failure
+ *   still happen?" is the question that catches that.
+ * - **Red herrings** gives the investigation's dead ends somewhere to live.
+ *   The fixer is often a sub-agent or a fleet builder who sees only this file;
+ *   whatever was ruled out gets re-litigated, and re-litigated wrong, because
+ *   the wrong fixes are the ones that look right.
+ * - **Sweep** is §Step 6's receipt. A skipped sweep and a clean sweep look
+ *   identical afterwards unless one of them writes something down.
+ * - **Acceptance criteria** asks for the reversal check. "The test passes now"
+ *   is also what a fix that merely moves the symptom produces; a check that
+ *   FAILS when the fix is reverted is a different claim.
+ *
+ * PROMPTED, NEVER ENFORCED. Nothing validates that these sections are filled
+ * in, and nothing should. A one-line typo bug that files with an empty Red
+ * herrings and a one-clause Sweep is the intended outcome — the point is that
+ * the author is asked, not that the answer is long. Making them required would
+ * buy ceremonial empty tables and train everyone to type filler.
+ */
+
+/** The level-check prompt for `## Root cause`. */
+export const DIAGNOSE_ROOT_CAUSE_PROMPT =
+  '_TBD — the mechanism, not the observation. Before writing this, ask: if I fix exactly this, can the same class of failure still happen? If yes, this is still a symptom — go one level down._';
+
+/** The prompt for `## Red herrings`. */
+export const DIAGNOSE_RED_HERRINGS_PROMPT =
+  '_The tempting fixes that are wrong, and why each one is wrong. Anything you ruled out during investigation belongs here — the fixer cannot see your reasoning, only this file. A two-column table (tempting fix ❘ why it is wrong) reads well. Leave it empty for a trivial bug; it is prompted, not required._';
+
+/** The prompt for `## Fix`. */
+export const DIAGNOSE_FIX_PROMPT = '_TBD — the change that resolves it._';
+
+/** The sibling-sweep receipt prompt for `## Sweep` ([[resolution-diagnose-workflow]] §Step 6). */
+export const DIAGNOSE_SWEEP_PROMPT =
+  '_What you searched for other occurrences of this same bug, what you found, and the diagnose ids filed for each sibling. "Searched the other four tests in this file, none share the shape" is a fine receipt — a claim someone else can re-run. Silence is not._';
+
+/** The reversal-check prompt for `## Acceptance criteria`. */
+export const DIAGNOSE_ACCEPTANCE_PROMPT =
+  '_TBD — how we know it is fixed. At least one criterion must be a check that FAILS when the fix is reverted, named so someone else can run it; "the test passes now" is also what a symptom-level fix produces. Freeze it as a checks manifest (`checks:` on heyspex_file_spec, [[checks-manifest-authoring]]) when the bug is worth a regression guard._';
+
+/**
+ * Every `##` heading a fully-injected diagnose skeleton carries, in order.
+ * `Symptom` / `Reproduction` / `Change log` are writer-seeded (each intake path
+ * has its own source material); the five in between are the shared block.
+ */
+export const DIAGNOSE_SECTION_ORDER = Object.freeze([
+  'Symptom',
+  'Reproduction',
+  'Root cause',
+  'Red herrings',
+  'Fix',
+  'Sweep',
+  'Acceptance criteria',
+  'Change log',
+]);
+
+/** The shared block's headings, in order — what the drift test compares. */
+export const DIAGNOSE_SHARED_SECTIONS = Object.freeze([
+  'Root cause',
+  'Red herrings',
+  'Fix',
+  'Sweep',
+  'Acceptance criteria',
+]);
+
+/**
+ * The shared `## Root cause` → `## Acceptance criteria` block, verbatim.
+ *
+ * `notes` lets an intake path add a path-specific hint under a section without
+ * forking the prompt — the DLQ writer knows the likely cause of a reclaimed
+ * deferred task, and that hint is worth keeping. Keys are section names; the
+ * value is appended as its own line after the canonical prompt.
+ *
+ * Returns text with no leading and no trailing newline; callers join it into
+ * their own body with blank lines on either side.
+ */
+export function buildDiagnoseSkeletonSections(notes = {}) {
+  const prompts = {
+    'Root cause': DIAGNOSE_ROOT_CAUSE_PROMPT,
+    'Red herrings': DIAGNOSE_RED_HERRINGS_PROMPT,
+    Fix: DIAGNOSE_FIX_PROMPT,
+    Sweep: DIAGNOSE_SWEEP_PROMPT,
+    'Acceptance criteria': DIAGNOSE_ACCEPTANCE_PROMPT,
+  };
+  return DIAGNOSE_SHARED_SECTIONS.map((section) => {
+    const note = typeof notes[section] === 'string' && notes[section].trim() ? notes[section].trim() : '';
+    const bodyLines = note ? `${prompts[section]}\n\n${note}` : prompts[section];
+    return `## ${section}\n\n${bodyLines}`;
+  }).join('\n\n');
+}
+
+/** The `##` headings of a markdown body, in document order. */
+export function diagnoseSectionHeadings(body) {
+  const out = [];
+  const re = /^##\s+(.+?)\s*$/gm;
+  let m;
+  while ((m = re.exec(String(body ?? ''))) !== null) out.push(m[1]);
+  return out;
+}