heyspex 0.1.0

package/vendor/heyspex-mcp/research-focus.mjs

@@ -0,0 +1,476 @@
+/**
+ * Research-on-deck — pin file (`.heyspex/research-focus.yaml`) and `/hs-res` flow.
+ * [[idea-capture-guardrails]] · [[HS-TASK-HRS5-hs-res-skill-ship-from-stub]] · [[HS-EPIC-IDFV-unified-idea-workflow-v2]]
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { parseSimpleFocusYaml } from './capture-focus.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+
+export function researchFocusPath(vaultRoot) {
+  return join(vaultRoot, '.heyspex', 'research-focus.yaml');
+}
+
+const VALID_SCOPES = new Set(['internal', 'codebase', 'external', 'all']);
+
+export function loadResearchFocus(vaultRoot) {
+  const p = researchFocusPath(vaultRoot);
+  if (!existsSync(p)) return null;
+  try {
+    const focus = parseSimpleFocusYaml(readFileSync(p, 'utf-8'));
+    if (focus.expires) {
+      const expiry = new Date(focus.expires);
+      if (expiry < new Date()) return null;
+    }
+    return focus;
+  } catch {
+    return null;
+  }
+}
+
+export function writeResearchFocus(vaultRoot, { specPath, sourceIdeaId, scope, reason }) {
+  if (!VALID_SCOPES.has(scope)) {
+    return { error: 'INVALID_SCOPE', message: `scope must be one of ${[...VALID_SCOPES].join('|')}` };
+  }
+  const dir = join(vaultRoot, '.heyspex');
+  mkdirSync(dir, { recursive: true });
+  const lines = [
+    '# HeySpex research-on-deck — MCP /hs-res ([[idea-capture-guardrails]])',
+    'kind: research',
+    `spec_path: ${specPath}`,
+    `source_idea_id: ${sourceIdeaId}`,
+    `pinned_at: ${new Date().toISOString()}`,
+    `scope: ${scope}`,
+  ];
+  if (reason) lines.push(`reason: ${JSON.stringify(reason)}`);
+  writeFileSync(researchFocusPath(vaultRoot), `${lines.join('\n')}\n`, 'utf8');
+  return { success: true };
+}
+
+export function clearResearchFocus(vaultRoot) {
+  const p = researchFocusPath(vaultRoot);
+  if (!existsSync(p)) return { existed: false };
+  rmSync(p);
+  return { existed: true };
+}
+
+function slugify(title) {
+  return String(title || 'research')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'research';
+}
+
+function stringifyResearchSpec(frontmatter, body) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(frontmatter)) {
+    if (v === null || v === undefined) continue;
+    if (Array.isArray(v)) {
+      lines.push(`${k}:`);
+      for (const item of v) lines.push(`  - ${JSON.stringify(item)}`);
+    } else if (typeof v === 'string') {
+      lines.push(`${k}: ${yamlScalar(v)}`);
+    } else {
+      lines.push(`${k}: ${v}`);
+    }
+  }
+  lines.push('---', '', body.trim(), '');
+  return lines.join('\n');
+}
+
+/**
+ * Build a research-doc body from sections supplied by the agent.
+ * Required: executive_summary, content. Optional: sources [{ title, url, description }].
+ */
+function buildResearchBody(args, { sourceIdeaId, scope }) {
+  const lines = [];
+  const title = args.title?.trim() || 'Research';
+  lines.push(`# ${title}`, '');
+  if (args.summary?.trim()) {
+    lines.push(args.summary.trim(), '');
+  }
+  lines.push('## Executive Summary', '');
+  lines.push(
+    args.executive_summary?.trim() ||
+      args.summary?.trim() ||
+      `_From idea [[${sourceIdeaId}]] (scope: ${scope})._`,
+    '',
+  );
+  if (args.findings?.trim() || args.content?.trim()) {
+    lines.push('## Findings', '');
+    lines.push((args.findings?.trim() || args.content?.trim() || ''), '');
+  }
+  if (Array.isArray(args.sources) && args.sources.length > 0) {
+    lines.push('## Sources', '');
+    for (const s of args.sources) {
+      if (!s) continue;
+      const titlePart = s.title || s.url || 'source';
+      if (s.url && s.title) {
+        lines.push(`- [${s.title}](${s.url})${s.description ? ` — ${s.description}` : ''}`);
+      } else if (s.url) {
+        lines.push(`- ${s.url}${s.description ? ` — ${s.description}` : ''}`);
+      } else {
+        lines.push(`- ${titlePart}${s.description ? ` — ${s.description}` : ''}`);
+      }
+    }
+    lines.push('');
+  }
+  lines.push('## Provenance', '');
+  lines.push(`- Source idea: [[${sourceIdeaId}]]`);
+  lines.push(`- Scope: ${scope}`);
+  lines.push(`- Captured via \`/hs-res\` on ${new Date().toISOString().slice(0, 10)}`);
+  return lines.join('\n');
+}
+
+/** Update a vault file's frontmatter by merging a patch; preserves body verbatim. */
+function patchSpecFrontmatter(absPath, patch) {
+  const content = readFileSync(absPath, 'utf-8');
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!m) {
+    throw new Error(`No frontmatter in ${absPath}`);
+  }
+  const yamlBlock = m[1];
+  const body = m[2];
+
+  // Parse existing keys naively so we can re-emit deterministically.
+  // For HS-IDEA frontmatter (small / flat), we update or append `promoted_to`
+  // and `updated`. Untouched keys stay byte-for-byte stable.
+  const lines = yamlBlock.split(/\r?\n/);
+  const updates = { ...patch };
+  const out = [];
+  for (const line of lines) {
+    const km = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):/);
+    if (km && Object.prototype.hasOwnProperty.call(updates, km[1])) {
+      const key = km[1];
+      const val = updates[key];
+      delete updates[key];
+      out.push(emitYamlLine(key, val));
+    } else {
+      out.push(line);
+    }
+  }
+  for (const [k, v] of Object.entries(updates)) {
+    out.push(emitYamlLine(k, v));
+  }
+  const newContent = `---\n${out.join('\n').replace(/\n+$/, '')}\n---\n${body.replace(/^\r?\n/, '')}`;
+  writeFileSync(absPath, newContent, 'utf8');
+}
+
+function emitYamlLine(key, value) {
+  if (value === null || value === undefined) return `${key}: null`;
+  if (typeof value === 'string') {
+    return `${key}: ${JSON.stringify(value)}`;
+  }
+  return `${key}: ${value}`;
+}
+
+function collectOccupiedResearchIds(vaultRoot) {
+  const dir = join(vaultRoot, 'specs', 'research');
+  const occupied = new Set();
+  if (!existsSync(dir)) return occupied;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md') || file.endsWith('.review.md')) continue;
+    // Dual-read: accept HS-RES-<key> and HS-<key>-RES, and key the occupied set
+    // on the canonical family-first id so it matches what allocateRandomVaultId
+    // generates/compares ([[HS-EPIC-DLE3]]).
+    const p = parseSpecId(file.replace(/\.md$/i, ''));
+    if (p && p.typeLabel === 'RES') occupied.add(`HS-${p.familyKey}-RES`);
+  }
+  return occupied;
+}
+
+/**
+ * Atomically write the research file, update the source idea's `promoted_to`,
+ * and clear the research-focus pin. Returns the new research id + path.
+ *
+ * deps: { allocateRandomVaultId, findSpecFile }
+ */
+export function executeCompleteResearch(vaultRoot, args = {}, deps = {}) {
+  const focus = loadResearchFocus(vaultRoot);
+  // Source idea + scope can come from the pin or from explicit args (ad-hoc mode).
+  const sourceIdeaId = args.source_idea_id || focus?.source_idea_id;
+  const scope = args.scope || focus?.scope || 'internal';
+  if (!sourceIdeaId) {
+    return {
+      error: 'NO_SOURCE_IDEA',
+      message:
+        'No source idea. Pin via console Promote (writes .heyspex/research-focus.yaml) or pass source_idea_id explicitly.',
+    };
+  }
+  if (!VALID_SCOPES.has(scope)) {
+    return { error: 'INVALID_SCOPE', message: `scope must be ${[...VALID_SCOPES].join('|')}` };
+  }
+  if (!args.title?.trim()) {
+    return { error: 'MISSING_TITLE', message: 'title is required' };
+  }
+  if (!args.executive_summary?.trim() && !args.summary?.trim()) {
+    return { error: 'MISSING_SUMMARY', message: 'executive_summary or summary is required' };
+  }
+  if (!args.content?.trim() && !args.findings?.trim()) {
+    return { error: 'MISSING_CONTENT', message: 'content or findings is required' };
+  }
+  // Completion source gate (HS-7HR9): external/all-scope research is a web-validated
+  // claim — refuse to finalize it with no cited source. Closes the "made-up research"
+  // gap where heyspex_complete_research accepted an empty sources array. `codebase`
+  // and `internal` scope are exempt (they cite code/vault, not URLs).
+  if (scope === 'external' || scope === 'all') {
+    const hasCitedUrl =
+      Array.isArray(args.sources) &&
+      args.sources.some((s) => s && typeof s.url === 'string' && /^https?:\/\//i.test(s.url.trim()));
+    if (!hasCitedUrl) {
+      return {
+        error: 'MISSING_SOURCES',
+        message:
+          `Scope "${scope}" is web-validated research — at least one cited source with a URL is required ` +
+          `to complete it (the ## Sources section cannot be empty). Add sources: [{ title, url, description }] ` +
+          `with a real http(s) URL, or complete this as scope "codebase"/"internal" if it cites code/vault instead of the web.`,
+      };
+    }
+  }
+  if (!deps.allocateRandomVaultId) {
+    return { error: 'MISSING_DEPS', message: 'allocateRandomVaultId is required' };
+  }
+  const ideaPath = deps.findSpecFile?.(vaultRoot, sourceIdeaId);
+  if (!ideaPath) {
+    // HS-CAP-* ids are minted by the console capture-workshop the moment the
+    // modal opens, but the markdown file is written lazily on first content
+    // (see spex-console/src/lib/capture-sessions/materialize.ts). The most common
+    // way to hit this branch is closing the modal without pressing Enter /
+    // Send on a note — the capture_sessions row stays `pending`, no file
+    // lands, and any /hs-res ad-hoc call against the visible id fails here.
+    const isCaptureId = parseSpecId(sourceIdeaId)?.typeLabel === 'CAP';
+    const message = isCaptureId
+      ? `Source capture ${sourceIdeaId} has no markdown file in specs/captures/. ` +
+        `The capture workshop assigns the id when the modal opens, but the file ` +
+        `is only written after you press Enter / Send on a note (lazy materialization). ` +
+        `Reopen the capture, send at least one note, watch for the "saved to ` +
+        `specs/captures/…" toast, then retry /hs-res.`
+      : `Source idea ${sourceIdeaId} not found in vault`;
+    return { error: 'IDEA_NOT_FOUND', message };
+  }
+
+  // Era-3 family inheritance ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // research doc inherits the SOURCE IDEA/CAPTURE's family (familyOf: explicit
+  // `family:` frontmatter wins, else positional from id/basename). The legacy
+  // allocator's `HS-<family>-RES` draw is only the defensive fallback family
+  // source; `id:` keys onto the file key alone.
+  const ideaBasename = String(ideaPath).replace(/\\/g, '/').split('/').pop().replace(/\.md$/i, '');
+  let ideaFmId = null;
+  let ideaFamilyValue = null;
+  try {
+    const ideaRaw = readFileSync(join(vaultRoot, ideaPath), 'utf-8');
+    ideaFmId = ideaRaw.match(/^id:\s*(\S+)/m)?.[1]?.replace(/^['"]|['"]$/g, '') ?? null;
+    ideaFamilyValue = ideaRaw.match(/^family:\s*(\S+)/m)?.[1]?.replace(/^['"]|['"]$/g, '') ?? null;
+  } catch {
+    /* unreadable idea file — fall through to positional/allocator derivation */
+  }
+  const familyKey =
+    familyOf({
+      id: ideaFmId ?? sourceIdeaId,
+      basename: ideaBasename,
+      frontmatter: { family: ideaFamilyValue },
+    }) ??
+    parseSpecId(deps.allocateRandomVaultId('research', collectOccupiedResearchIds(vaultRoot)))?.familyKey ??
+    mintFamilyKey(vaultRoot);
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  const fileKey = mintFileKey(vaultRoot);
+  const newId = `HS-${fileKey}`;
+  const slug = slugify(args.title);
+  const filename = `${newId}-${familyKey}-RES-${slug}.md`;
+  const researchDir = join(vaultRoot, 'specs', 'research');
+  mkdirSync(researchDir, { recursive: true });
+  const absResearchPath = join(researchDir, filename);
+
+  const today = new Date().toISOString().slice(0, 10);
+  const tags = Array.isArray(args.tags) ? args.tags : ['research'];
+  const related = Array.isArray(args.related) ? [...args.related] : [];
+  const sourceLink = `[[${sourceIdeaId}]]`;
+  if (!related.some((r) => String(r).includes(sourceIdeaId))) {
+    related.unshift(sourceLink);
+  }
+
+  const fm = {
+    id: newId,
+    file_id: fileKey,
+    family: familyKey,
+    name: args.title,
+    type: 'research',
+    status: 'open',
+    owner: args.owner || 'pwher',
+    created: today,
+    updated: today,
+    tags,
+    related,
+    source_idea: sourceLink,
+    scope,
+  };
+  const body = buildResearchBody(args, { sourceIdeaId, scope });
+  writeFileSync(absResearchPath, stringifyResearchSpec(fm, body), 'utf8');
+
+  // Update the source idea's promoted_to + updated date.
+  try {
+    patchSpecFrontmatter(join(vaultRoot, ideaPath), {
+      promoted_to: `[[${newId}]]`,
+      updated: today,
+    });
+  } catch (e) {
+    return {
+      error: 'IDEA_UPDATE_FAILED',
+      message: `Research file written to ${filename}, but updating ${sourceIdeaId} failed: ${e.message}`,
+      research_id: newId,
+      research_path: `specs/research/${filename}`,
+    };
+  }
+
+  const pinResult = clearResearchFocus(vaultRoot);
+
+  return {
+    success: true,
+    research_id: newId,
+    research_path: `specs/research/${filename}`,
+    source_idea_id: sourceIdeaId,
+    source_idea_path: ideaPath,
+    scope,
+    pin_cleared: pinResult.existed,
+    next_steps: [
+      `Open ${newId} in console to review the draft research`,
+      'Add wikilinks back to related specs',
+      // Research is evergreen ([[research-is-evergreen]]): it never closes.
+      // Lineage is recorded via relational fields, not a status flip.
+      'Add `enhances:` to bind this research to a milestone, or `bound_epic:` when an epic is filed from it',
+    ],
+  };
+}
+
+export function buildHsResPromptMarkdown(focus, options = {}) {
+  if (!focus?.spec_path || !focus?.source_idea_id) {
+    return `# /hs-res — no research pinned
+
+No \`.heyspex/research-focus.yaml\` is set. To run \`/hs-res\`:
+
+1. Open the source idea in console Docs.
+2. Click **Promote** on the doc toolbar.
+3. Confirm a scope (internal / codebase / external / all).
+4. Return here and rerun \`/hs-res\`.
+
+Or capture research ad-hoc by calling \`heyspex_complete_research\` with explicit \`source_idea_id\`, \`scope\`, \`title\`, \`executive_summary\`, \`content\`.
+`;
+  }
+  const { source_idea_id, scope, spec_path, pinned_at } = focus;
+
+  // Stale-pin detection. The console Promote button validates via the
+  // disk-backed vault index, so a freshly-written pin always points at a
+  // real file — but ad-hoc YAML edits, an in-flight capture-session that
+  // was discarded after pinning, or a moved/renamed file can leave the
+  // pin pointing at nothing. The MCP findSpecFile scans disk only, so a
+  // stale pin would fail late inside heyspex_complete_research with the
+  // generic IDEA_NOT_FOUND. Catch it here so the agent doesn't waste a
+  // research session on a pin that can never resolve.
+  if (options.vaultRoot) {
+    const abs = join(options.vaultRoot, spec_path);
+    if (!existsSync(abs)) {
+      const isCaptureId = parseSpecId(source_idea_id)?.typeLabel === 'CAP';
+      const captureHint = isCaptureId
+        ? `\n\nThe pinned id looks like a capture-workshop session (\`HS-CAP-*\`). ` +
+          `The console assigns the id when the modal opens but only writes the ` +
+          `markdown file after you press Enter / Send on a note. If you closed ` +
+          `the modal without sending anything, the pin is referencing a row that ` +
+          `never materialized — clear the pin and re-Promote after the capture ` +
+          `is actually saved to \`specs/captures/\`.`
+        : '';
+      return `# /hs-res — stale pin
+
+The pinned source idea \`${source_idea_id}\` points at \`${spec_path}\`, but that file does not exist on disk.${captureHint}
+
+To recover:
+
+1. Call \`heyspex_active_research\` to confirm the pin state.
+2. Either re-create the source idea/capture so the file exists, or clear the pin via the console doc-toolbar (Un-pin) before retrying \`/hs-res\`.
+`;
+    }
+  }
+  return `# /hs-res — research capture for ${source_idea_id}
+
+**Source idea:** [[${source_idea_id}]] · \`${spec_path}\`
+**Scope:** \`${scope || 'internal'}\` · **Pinned at:** \`${pinned_at || 'unknown'}\`
+
+---
+
+## Your job — research capture (NOT idea capture)
+
+Run the deep dive at the confirmed scope, then call \`heyspex_complete_research\` once. The tool atomically writes \`specs/research/HS-RES-*\`, sets the idea's \`promoted_to\`, and clears this pin.
+
+## Beat 1 — Confirm scope with the user
+
+Read the pinned scope above and confirm with the user before starting:
+
+- **internal** — search \`specs/\`, memories, ADRs only. Use \`heyspex_recall_memories\` + vault grep.
+- **codebase** — grep the repo (\`spex-console/\`, \`vendor/\`, \`scripts/\`, etc.).
+- **external** — web-validated research via the **deep-research harness** (below), not an ad-hoc dive.
+- **all** — vault + codebase + web (the web half runs through the deep-research harness).
+
+If the user wants a different scope, suggest re-pinning via console Promote rather than overriding silently.
+
+## Beat 2 — Deep dive at the confirmed scope
+
+Read **the source idea first** (\`specs/captures/...\` — load by id \`${source_idea_id}\`):
+
+- **Core Idea** and **Concept** sections are your prompt
+- Notes are user phrasing — useful for context, not for rewriting
+- Don't write research sections back into the idea file
+
+Then explore per scope. Capture findings as you go.
+
+**For \`external\` / \`all\` scope, run the \`hs-res\` skill's confidence-ladder method — do NOT hand-roll a web dive and do NOT spawn a Sonnet-based research path.** Self-hosted Firecrawl (search/scrape) + DeepSeek (synthesis + adversarial critique) is the default and required first choice for every rung (owner ruling, [[research-routing-hard-rule-sonnet]], amended 2026-07-13: *"Sonnet is fallback. And fallback must be initiated after specific user permission, not silent fallback."*):
+
+\`\`\`
+Skill({ skill: 'hs-res', args: '<the residual research question>' })
+\`\`\`
+
+**Never** \`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })\`, the built-in \`deep-research\` skill, or native \`WebSearch\`/\`WebFetch\` for this — those are the forbidden Sonnet-spawning paths the owner ruling exists to prevent. If Firecrawl or DeepSeek report unavailable (\`FIRECRAWL_UNAVAILABLE\` / \`SYNTHESIZE_UNAVAILABLE\`), stop and ask the user for explicit one-time permission before falling back to a Sonnet-based path — never silently. Ground first (the grounding gate blocks a launch that re-derives already-built/already-decided work — the question must be the residual delta). The skill's saved doc seeds the \`## Executive Summary\` + \`## Sources\` you pass to \`heyspex_complete_research\`.
+
+## Beat 3 — Write the research file
+
+Call \`heyspex_complete_research\` with:
+
+\`\`\`json
+{
+  "title": "<descriptive research title>",
+  "executive_summary": "<3–5 sentence summary>",
+  "content": "<full markdown findings — tables, code refs, comparisons>",
+  "sources": [
+    { "title": "Source 1", "url": "https://…", "description": "what it provided" }
+  ],
+  "tags": ["research", "<topic>"],
+  "related": ["[[<related-spec>]]"]
+}
+\`\`\`
+
+**For \`external\` / \`all\` scope, \`## Executive Summary\` and a non-empty \`## Sources\` (≥1 cited \`http(s)\` URL) are REQUIRED** — \`heyspex_complete_research\` rejects an empty \`sources\` array for these scopes (\`MISSING_SOURCES\`). Web-validated research must cite its web sources.
+
+The MCP tool fills in \`source_idea_id\` and \`scope\` from the pin. It also:
+
+- Allocates a fresh \`HS-RES-<suffix>\` id
+- Writes \`specs/research/HS-RES-<id>-<slug>.md\` with \`type: research\`, \`status: open\`, the \`Executive Summary\`, \`Findings\`, \`Sources\`, and \`Provenance\` sections
+- Sets the source idea's \`promoted_to: "[[HS-RES-<id>]]"\` and \`updated\`
+- Deletes \`.heyspex/research-focus.yaml\`
+
+## Hard prohibitions
+
+- **Never** write \`Executive Summary\` / \`Findings\` / \`Sources\` onto the idea file
+- **Never** flip the idea's \`status\` to \`closed\` — \`promoted_to\` is the signal
+- **Never** delete the idea file
+- **Never** call \`heyspex_complete_research\` until the user confirms scope (beat 1)
+`;
+}

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

@@ -0,0 +1,109 @@
+/**
+ * HeySpex research-resolution MCP tools — the agent face over the research policy knobs
+ * (agent_behaviors.research in .heyspex/config.yaml) and the interactive Firecrawl bridge,
+ * mounted in cli.mjs as:
+ *   - heyspex_resolve_research_plan  (read — open)  — Part A's authoritative resolver
+ *   - heyspex_firecrawl_research     (read/network)  — Part B's reachability bridge
+ *
+ * Fixes [[HS-LFUH-DIAG-W1YE]] (interactive research path silently downgrades
+ * `default_source: firecrawl-self-hosted` to web-native — never injected, no Firecrawl tool):
+ *   - `heyspex_resolve_research_plan` is the CAN'T-GO-STALE-MID-SESSION source of truth for
+ *     "which research method/backend applies right now" — the hook injection in
+ *     scripts/claude-hooks/_intent-classifier-router.mjs is only a best-effort snapshot hint;
+ *     this tool is what an agent calls to actually confirm it. It ONLY reads the configured
+ *     plan (research doc's full profile/fallback/capability-gating resolution is explicitly
+ *     out of scope — that is [[HS-X5GJ-RES-EU6J]], a separate feature built on top of this fix).
+ *   - `heyspex_firecrawl_research` is the on-demand execution surface that makes the configured
+ *     Firecrawl backend REACHABLE from an interactive turn — it is a thin MCP wrapper around
+ *     dev-factory/dream-research/interactive-firecrawl-tool.mjs, which itself wraps the
+ *     existing, self-tested default-backends.mjs/firecrawl-adapter.mjs implementation (no
+ *     search/scrape logic is reimplemented here).
+ *
+ * Pattern source: settings-tools.mjs (pure-logic execute* functions; cli.mjs wraps).
+ */
+
+import { listConfigLeaves } from './config-settings.mjs';
+// The deep-research backend is loaded LAZILY through the bridge, never imported
+// statically — a static import here pulls 25 SpexFleet / dream-research files into
+// the MCP server's package closure. See dev-factory-bridge.mjs for the full
+// rationale ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]]).
+import { loadDreamResearch } from './dev-factory-bridge.mjs';
+
+const RESEARCH_PREFIX = 'agent_behaviors.research.';
+
+/**
+ * Resolve the CONFIGURED research plan from .heyspex/config.yaml — the authoritative,
+ * live-read source of truth (never a stale hook-injection snapshot). Read-only; scope is
+ * deliberately limited to reading the three existing knobs
+ * (default_method/default_agent/default_source) plus the resolved endpoint for a Firecrawl
+ * source — NOT the resource-profile/fallback-chain/capability-gating resolution the research
+ * doc's separate feature will add later.
+ */
+export async function executeResolveResearchPlan(vaultRoot) {
+  const leaves = listConfigLeaves(vaultRoot).filter((s) => s.key.startsWith(RESEARCH_PREFIX));
+  const cfg = Object.fromEntries(leaves.map((s) => [s.key.slice(RESEARCH_PREFIX.length), s.value]));
+
+  const method = cfg.default_method ?? 'ladder';
+  const defaultAgent = cfg.default_agent ?? 'deepseek';
+  const defaultSource = cfg.default_source ?? 'web-native';
+
+  let endpoint = null;
+  if (defaultSource === 'firecrawl-self-hosted' || defaultSource === 'firecrawl-hosted') {
+    try {
+      const backend = await loadDreamResearch();
+      endpoint = backend.available ? backend.getBaseUrl() : null;
+    } catch {
+      endpoint = null; // fail-safe — an unreadable env/adapter must never break this read
+    }
+  }
+
+  const note =
+    defaultSource === 'firecrawl-self-hosted' || defaultSource === 'firecrawl-hosted'
+      ? 'For RUNG 0 `sequential`, call heyspex_firecrawl_research({ mode: "search"|"scrape", query|url }) ' +
+        'to honor this backend instead of native WebSearch/WebFetch. It respects the existing availability ' +
+        'gates (Ollama-XOR-Firecrawl lease for self-hosted / the attended-daytime credit gate for hosted) and ' +
+        'reports an explicit { downgraded: true, reason } if the backend is unavailable — never substitute ' +
+        'web-native silently. IMPORTANT (research-routing-hard-rule-sonnet, "Sonnet is the fallback, ' +
+        'Firecrawl is the default"): once the fetch succeeds, hand the gathered text to DeepSeek for ' +
+        'synthesis (dev-factory/dream-research/synthesize-cli.mjs, or the `hs-res` skill for anything ' +
+        'beyond a single lookup) — do NOT reason over/summarize the results yourself. Sonnet doing its ' +
+        'own synthesis is the fallback branch only, used after an explicit unreachability report and ' +
+        'never silently.'
+      : 'default_source is web-native — native WebSearch/WebFetch already honors the configured default; no ' +
+        'Firecrawl bridge call is needed.';
+
+  return {
+    ok: true,
+    method,
+    default_agent: defaultAgent,
+    default_source: defaultSource,
+    resource: { source: defaultSource, endpoint },
+    note,
+  };
+}
+
+/**
+ * Run one Firecrawl search or scrape for an interactive agent turn (rung 0 `sequential`) —
+ * the on-demand execution surface for whatever heyspex_resolve_research_plan resolved.
+ * Delegates entirely to dev-factory/dream-research/interactive-firecrawl-tool.mjs; this
+ * function only maps the MCP snake_case args onto that module's contract.
+ */
+export async function executeFirecrawlResearch(args = {}) {
+  const backend = await loadDreamResearch();
+  if (!backend.available) {
+    // Explicit downgrade, never a silent substitution — same contract the
+    // underlying tool uses when a backend is gated off.
+    return {
+      ok: false,
+      error: 'backend_unavailable',
+      downgraded: true,
+      reason: backend.reason,
+    };
+  }
+  return backend.runFirecrawlResearchTool({
+    mode: args.mode,
+    query: args.query,
+    url: args.url,
+    spec_id: args.spec_id,
+  });
+}