heyspex 0.1.0

package/vendor/heyspex-mcp/promotion-helpers.mjs

@@ -0,0 +1,280 @@
+/**
+ * Shared frontmatter + transactional-write helpers for the HeySpex promotion
+ * tools. Extracted from `promote-research.mjs` ([[HS-TASK-QQHP]]) so that
+ * `promote-capture.mjs` ([[HS-TASK-WQCE]]) and any future promotion tool can
+ * reuse the same parsing, mutation, and commit/rollback machinery — the
+ * bidirectional invariants from [[HS-TASK-YJX6]] live in one place.
+ *
+ * All helpers operate on the frontmatter *block* (the inner YAML body between
+ * `---` fences) or on the full file body. They are tolerant of CRLF line
+ * endings and of YAML blocks that sit flush against the closing fence with no
+ * trailing newline.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Date / string utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const VAULT_ID_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+export function isoNow() {
+  return new Date().toISOString();
+}
+
+export function todayDate() {
+  return isoNow().slice(0, 10);
+}
+
+export function deriveSlug(name, maxLen = 40) {
+  const slug = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  if (!slug) return 'untitled';
+  if (slug.length <= maxLen) return slug;
+  const cut = slug.slice(0, maxLen);
+  const lastDash = cut.lastIndexOf('-');
+  if (lastDash > 0) return cut.slice(0, lastDash);
+  return cut.replace(/-+$/, '') || 'untitled';
+}
+
+export function randomSuffix(length, randomUnit = Math.random) {
+  let out = '';
+  for (let i = 0; i < length; i++) {
+    const idx = Math.floor(randomUnit() * VAULT_ID_CHARSET.length);
+    out += VAULT_ID_CHARSET[Math.min(idx, VAULT_ID_CHARSET.length - 1)];
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// File discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a `.md` filename in `dir` from an id-or-basename prefix.
+ *
+ * An EXACT basename match always wins over a prefix match: passing the complete
+ * basename (`HS-X5FH-TN54-RES-voice-profile-for-the-companion`) used to resolve
+ * to nothing, because `<basename>-` is not a prefix of `<basename>.md`, which
+ * forced callers to guess a truncated prefix
+ * ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]). Exact-first
+ * is strictly additive for the other callers: it can only turn a previous null
+ * (or a wrong sibling hit) into the file the caller literally named.
+ */
+export function findFileByPrefix(dir, prefix) {
+  if (!existsSync(dir)) return null;
+  const exact = `${prefix}.md`;
+  let prefixHit = null;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    if (file === exact) return file;
+    if (prefixHit === null && file.startsWith(`${prefix}-`)) prefixHit = file;
+  }
+  return prefixHit;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontmatter parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function getFrontmatterBlock(raw) {
+  const m = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)/);
+  if (!m) return null;
+  return {
+    open: m[1],
+    block: m[2],
+    close: m[3],
+    body: raw.slice(m[0].length),
+    full: m[0],
+  };
+}
+
+export function getScalarField(block, field) {
+  const re = new RegExp(`^${field}:[ \\t]*(.*)$`, 'm');
+  const m = block.match(re);
+  if (!m) return null;
+  const raw = m[1].trim();
+  if (!raw) return null;
+  return raw.replace(/^['"]|['"]$/g, '');
+}
+
+export function parseWikilinkBasename(value) {
+  if (!value) return null;
+  const m = value.match(/^\[\[([^\]]+)\]\]$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * Parse a block-list frontmatter field into its list of wikilink basenames.
+ * Returns:
+ *   - `[]` if the field is an inline empty array (`field: []`)
+ *   - array of basenames if the field is a block list
+ *   - `null` if the field is absent
+ */
+export function parseListFieldBasenames(block, field) {
+  const emptyRe = new RegExp(`^${field}:[ \\t]*\\[[ \\t]*\\][ \\t]*$`, 'm');
+  if (emptyRe.test(block)) return [];
+  const headRe = new RegExp(`^${field}:[ \\t]*\\r?\\n`, 'm');
+  const headMatch = block.match(headRe);
+  if (!headMatch) return null;
+  const startIdx = headMatch.index + headMatch[0].length;
+  const lines = block.slice(startIdx).split(/\r?\n/);
+  const items = [];
+  for (const line of lines) {
+    if (/^[ \t]+-[^\n]*$/.test(line)) {
+      items.push(line);
+      continue;
+    }
+    break;
+  }
+  if (items.length === 0) return null;
+  const out = [];
+  for (const line of items) {
+    const wm = line.match(/-[ \t]*["']?\[\[([^\]]+)\]\]["']?/);
+    if (wm) out.push(wm[1]);
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Frontmatter mutation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Append a wikilink basename to a list-shaped frontmatter field, idempotent.
+ * Creates the field as a block list if it does not already exist. Operates on
+ * the *normalized* block (always re-trimmed to no trailing newline) so down-
+ * stream concatenation with fm.close stays clean.
+ */
+export function appendToListField(block, field, basename) {
+  const existing = parseListFieldBasenames(block, field);
+  if (existing && existing.includes(basename)) return { block, changed: false };
+
+  const emptyRe = new RegExp(`^${field}:[ \\t]*\\[[ \\t]*\\][ \\t]*$`, 'm');
+  if (emptyRe.test(block)) {
+    const replacement = `${field}:\n  - "[[${basename}]]"`;
+    return { block: block.replace(emptyRe, replacement), changed: true };
+  }
+
+  if (existing !== null) {
+    const headRe = new RegExp(`^${field}:[ \\t]*\\r?\\n`, 'm');
+    const headMatch = block.match(headRe);
+    if (headMatch) {
+      const before = block.slice(0, headMatch.index);
+      const startIdx = headMatch.index + headMatch[0].length;
+      let endIdx = startIdx;
+      const lines = block.slice(startIdx).split(/\r?\n/);
+      for (const line of lines) {
+        if (/^[ \t]+-[^\n]*$/.test(line)) {
+          endIdx += line.length + 1;
+          continue;
+        }
+        break;
+      }
+      const after = endIdx > block.length ? '' : block.slice(endIdx - 1);
+      const allItems = [...existing, basename]
+        .map((b) => `  - "[[${b}]]"`)
+        .join('\n');
+      const next = `${before}${field}:\n${allItems}${after.startsWith('\n') ? after : '\n' + after}`;
+      return { block: next.replace(/\n+$/, ''), changed: true };
+    }
+  }
+
+  const appended = `${block}\n${field}:\n  - "[[${basename}]]"`;
+  return { block: appended, changed: true };
+}
+
+export function setScalarField(block, field, value) {
+  const re = new RegExp(`^${field}:[ \\t]*(.*)$`, 'm');
+  if (re.test(block)) {
+    return block.replace(re, `${field}: ${value}`);
+  }
+  const trimmed = block.replace(/\r?\n$/, '');
+  return `${trimmed}\n${field}: ${value}`;
+}
+
+export function bumpUpdated(block, now) {
+  return setScalarField(block, 'updated', `"${now}"`);
+}
+
+export function appendChangeLogRow(body, dateStr, author, message) {
+  const row = `| ${dateStr} | ${author} | ${message} |`;
+  const headingMatch = body.match(/^## Change[ -]log\s*$/im);
+  if (!headingMatch) {
+    return (
+      body.replace(/\s*$/, '') +
+      `\n\n## Change log\n\n| Date | Author | Change |\n| --- | --- | --- |\n${row}\n`
+    );
+  }
+  return body.replace(/\s*$/, '') + `\n${row}\n`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Transactional writes
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Stage + commit a set of file writes with rollback. `writes` entries are
+ * `{ kind: 'create' | 'update', absPath, content }`. Rollback on any error:
+ * created files are removed, updated files restored from snapshot.
+ */
+export function commitWrites(writes) {
+  const snapshots = new Map();
+  const performed = [];
+  try {
+    for (const w of writes) {
+      if (w.kind === 'create') {
+        if (existsSync(w.absPath)) {
+          throw new Error(`refusing to overwrite existing file: ${w.absPath}`);
+        }
+        snapshots.set(w.absPath, { existed: false });
+        const dir = w.absPath.slice(
+          0,
+          Math.max(w.absPath.lastIndexOf('/'), w.absPath.lastIndexOf('\\')),
+        );
+        if (dir) mkdirSync(dir, { recursive: true });
+        writeFileSync(w.absPath, w.content, 'utf8');
+        performed.push(w);
+      } else if (w.kind === 'update') {
+        if (!existsSync(w.absPath)) {
+          throw new Error(`cannot update missing file: ${w.absPath}`);
+        }
+        if (!snapshots.has(w.absPath)) {
+          snapshots.set(w.absPath, {
+            existed: true,
+            original: readFileSync(w.absPath, 'utf8'),
+          });
+        }
+        writeFileSync(w.absPath, w.content, 'utf8');
+        performed.push(w);
+      }
+    }
+    return { ok: true };
+  } catch (err) {
+    for (const w of performed.reverse()) {
+      const snap = snapshots.get(w.absPath);
+      if (!snap) continue;
+      try {
+        if (snap.existed) {
+          writeFileSync(w.absPath, snap.original, 'utf8');
+        } else if (existsSync(w.absPath)) {
+          unlinkSync(w.absPath);
+        }
+      } catch (rollbackErr) {
+        err.rollbackError = rollbackErr.message;
+      }
+    }
+    return { ok: false, error: err };
+  }
+}

package/vendor/heyspex-mcp/read-path.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * read-path.mjs — the single decision point every vault read the MCP server
+ * makes goes through (epic HS-T6GS "MCP server reads the vault through the
+ * ...").  Decides `disk` vs `neon` from the already-shipped dev-mode
+ * resolver (`resolveDevMode().readTier` in `scripts/lib/dev-mode.mjs`), and
+ * runs the matching read function.
+ *
+ * Transport-free by design: this module never imports console-fetch.mjs or
+ * talks to a network itself — callers hand it `diskRead`/`neonRead`
+ * functions and this module only picks which one runs.
+ *
+ * Dynamic-imports scripts/lib/dev-mode.mjs at call time — same self-
+ * containment pattern cli.mjs uses for handleDevServerStatus / handleDevMode
+ * (`pathToFileURL(join(root, ...)).href` then `await import(coreUrl)`), so
+ * vendor/ stays dependency-free.
+ *
+ * `scripts/lib/dev-mode.mjs` is PACKAGE code (the shared dev/prod mode core
+ * — see its own module doc), not vault content: no vault, customer or
+ * platform, ever contains a `scripts/` folder (confirmed against the
+ * customer-vault scaffold templates). It therefore must always be resolved
+ * relative to THIS PACKAGE's own install location — `PACKAGE_ROOT` below
+ * (`vendor/heyspex-mcp/read-path.mjs` -> two levels up: the repo root in the
+ * monorepo, `node_modules/heyspex` in a packed install) — never the
+ * resolved VAULT root (wherever the customer's `specs/` happens to live,
+ * which is a SEPARATE directory in every packed install).
+ *
+ * The pre-fix code conflated the two under one misleadingly-named constant
+ * (`VAULT_ROOT = join(__dirname, '..', '..')`): it was actually always
+ * computing the PACKAGE root (harmless in the monorepo, where repo root
+ * doubles as both), so once `scripts/lib/dev-mode.mjs` is added to
+ * `package.json` `files` (this task, sibling fix), the exact same
+ * computation resolves correctly in a packed install too — confirmed by
+ * spawning the REAL packed tarball's server against a scaffolded vault in a
+ * different directory (`scripts/verify-packed-mcp-loop.test.mjs`; using the
+ * VAULT root here instead throws `Cannot find module
+ * '<vault>/scripts/lib/dev-mode.mjs'` — that file never exists there).
+ * `PACKAGE_ROOT` is kept as its own clearly-named constant (never
+ * `VAULT_ROOT`) so the two concepts can't be silently re-conflated, and
+ * {@link resolveVaultRoot} exposes the SAME shared vault resolver
+ * (`getActiveConfig()` in `./vault-resolve.mjs`) every other MCP read uses,
+ * for any future caller here that genuinely needs the vault (not this
+ * module's own sibling code) — [[HS-PO09-0JNK-TASK-packed-mcp-server-runs-the-agent-loop]] AC3.
+ *
+ * `loadDevMode` is an injectable loader (defaults to the real dynamic
+ * import) so tests can stub scripts/lib/dev-mode.mjs and prove the verdict
+ * comes from `resolveDevMode` itself, not from string-matching this file.
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { getActiveConfig } from './vault-resolve.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// THIS PACKAGE's own root (vendor/heyspex-mcp/read-path.mjs -> two levels
+// up) — repo root in the monorepo, `node_modules/heyspex` in a packed
+// install. Used to locate this package's OWN sibling code (dev-mode.mjs);
+// see the module doc above for why this is never the vault root.
+const PACKAGE_ROOT = join(__dirname, '..', '..');
+
+/**
+ * Resolve the VAULT root via the same shared 5-tier resolver every other MCP
+ * read uses (HEYSPEX_VAULT_ROOT / HEYSPEX_VAULT_DIR env, the cwd the server
+ * was started in/under, the offline registry pointer, cwd fallback). Not
+ * used by {@link loadRealDevMode} (see module doc — dev-mode.mjs is package
+ * code, not vault content); exposed for any future caller in this file that
+ * genuinely needs the vault. Never throws: falls back to {@link PACKAGE_ROOT}
+ * so a caller that somehow can't reach the resolver still gets SOME answer.
+ */
+export function resolveVaultRoot() {
+  try {
+    const { repoRootAbs } = getActiveConfig();
+    if (repoRootAbs) return repoRootAbs;
+  } catch {
+    // fall through to the package-root default below
+  }
+  return PACKAGE_ROOT;
+}
+
+/** Real loader: dynamic-imports the shared dev-mode core from THIS PACKAGE's own root. */
+export async function loadRealDevMode() {
+  const coreUrl = pathToFileURL(join(PACKAGE_ROOT, 'scripts', 'lib', 'dev-mode.mjs')).href;
+  return import(coreUrl);
+}
+
+/**
+ * Raised when a `neon`-tier read fails — names the console URL and the
+ * failing route so the caller sees exactly what was unreachable. The disk
+ * read is never attempted as a fallback (cloud-first tiers stay cloud-only).
+ */
+export class ConsoleUnreachableCloudModeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CONSOLE_UNREACHABLE_CLOUD_MODE';
+  }
+}
+
+/**
+ * resolveReadTier({ env, homeDir, loadDevMode? }) -> "disk" | "neon"
+ *
+ * The verdict is whatever `resolveDevMode(...).readTier` says: `disk` only
+ * for dev mode with local reliance, `neon` for prod and for dev with cloud
+ * reliance. `env`/`homeDir` are forwarded to `resolveDevMode` untouched
+ * (undefined lets it fall back to its own `process.env`/`homedir()`
+ * defaults). `loadDevMode` defaults to {@link loadRealDevMode}; tests
+ * override it with a stub module to prove this function never derives the
+ * verdict itself.
+ */
+export async function resolveReadTier({ env, homeDir, loadDevMode = loadRealDevMode } = {}) {
+  const mod = await loadDevMode();
+  const resolved = mod.resolveDevMode({ env, homeDir });
+  return resolved.readTier;
+}
+
+/**
+ * readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl })
+ *
+ * Runs the read matching `tier`:
+ *   - "disk": calls `diskRead()` (`neonRead` is never invoked).
+ *   - "neon": calls `neonRead()`. On failure, wraps the error into a plain
+ *     {@link ConsoleUnreachableCloudModeError} naming `consoleUrl` and
+ *     `routeLabel`; `diskRead` is never called (no silent local fallback
+ *     out of cloud reliance).
+ */
+export async function readViaSelector({ tier, diskRead, neonRead, routeLabel, consoleUrl }) {
+  if (tier === 'disk') {
+    return diskRead();
+  }
+  if (tier === 'neon') {
+    try {
+      return await neonRead();
+    } catch (err) {
+      throw new ConsoleUnreachableCloudModeError(
+        `CONSOLE_UNREACHABLE_CLOUD_MODE: route "${routeLabel}" failed against console ${consoleUrl} — ${String(err?.message ?? err)}`,
+      );
+    }
+  }
+  throw new Error(`readViaSelector: unknown tier "${tier}" (expected "disk" | "neon")`);
+}

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

@@ -0,0 +1,258 @@
+/**
+ * HeySpex workflow-recipe MCP tools (pure logic).
+ *
+ * Backs the `heyspex_list_recipes` and `heyspex_start_recipe` MCP tools and the
+ * recipe-matching arm of `heyspex_preflight`, all mounted in cli.mjs. Recipes are
+ * the four stock workflow templates authored under specs/recipes/ by
+ * scripts/init-stock-recipes.mjs ([[HS-C28M-TASK]]); the entity shape is the
+ * workflow-recipe branch of schemas/heyspex-frontmatter.schema.json
+ * ([[HS-GWMJ-TASK]]).
+ *
+ * v1 has no catalog build step (there are only four files): this module scans
+ * specs/recipes/*.md directly at call time and parses the frontmatter with
+ * js-yaml — the same parser scripts/init-stock-recipes.mjs uses to AUTHOR the
+ * files, so read/write are symmetric. Pattern source: procedure-tools.mjs.
+ *
+ * Spec: [[HS-RQ9K-TASK]] under [[HS-5G0P-EPIC-workflow-recipe-skills-catalog]].
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const RECIPES_DIR = ['specs', 'recipes'];
+
+function normalize(value) {
+  return String(value ?? '').toLowerCase().trim();
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+/** Parse the frontmatter block of a recipe markdown file. Returns null on miss. */
+function parseRecipeFrontmatter(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return null;
+  try {
+    const data = yaml.load(match[1]);
+    return data && typeof data === 'object' ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Shape a raw frontmatter object into the recipe record the tools return. */
+function toRecipe(data, relPath) {
+  return {
+    id: data.id ?? null,
+    name: data.name ?? null,
+    description: data.description ?? '',
+    status: data.status ?? null,
+    intent_signatures: asArray(data.intent_signatures),
+    procedures: asArray(data.procedures),
+    tool_scope: asArray(data.tool_scope),
+    spec_template:
+      data.spec_template && typeof data.spec_template === 'object'
+        ? data.spec_template
+        : {},
+    capture_sequence: asArray(data.capture_sequence),
+    path: relPath,
+  };
+}
+
+/**
+ * Load every recipe under specs/recipes/. Returns [] when the folder is absent
+ * (a vault with no recipes is valid — the tools degrade to an empty catalog).
+ * Files whose frontmatter is missing or is not a workflow-recipe are skipped.
+ */
+export function loadRecipes(vaultRoot) {
+  const dir = join(vaultRoot, ...RECIPES_DIR);
+  if (!existsSync(dir)) return [];
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+  } catch {
+    return [];
+  }
+  const recipes = [];
+  for (const file of files.sort()) {
+    let raw;
+    try {
+      raw = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    const data = parseRecipeFrontmatter(raw);
+    if (!data || data.type !== 'workflow-recipe') continue;
+    recipes.push(toRecipe(data, `specs/recipes/${file}`));
+  }
+  return recipes;
+}
+
+/**
+ * Score how strongly a recipe matches an intent string.
+ *   - 'high'   : an intent_signature equals the intent (token-exact).
+ *   - 'medium' : an intent_signature is a substring of the intent (or vice
+ *                versa), or the intent hits the recipe name/description.
+ *   - null     : no match.
+ * Comparison is case-insensitive and underscore/space/hyphen agnostic so
+ * "fix bug", "fix-bug", and "bug_fix" all reach the Bug fix flow.
+ */
+function canonicalToken(value) {
+  return normalize(value).replace(/[\s_-]+/g, ' ').trim();
+}
+
+export function matchStrength(recipe, intent) {
+  const needle = canonicalToken(intent);
+  if (!needle) return null;
+  const signatures = recipe.intent_signatures.map(canonicalToken).filter(Boolean);
+  if (signatures.some((s) => s === needle)) return 'high';
+  if (signatures.some((s) => s.includes(needle) || needle.includes(s))) return 'medium';
+  const haystack = canonicalToken(`${recipe.name} ${recipe.description}`);
+  if (haystack.includes(needle)) return 'medium';
+  return null;
+}
+
+function summarize(recipe) {
+  return {
+    id: recipe.id,
+    name: recipe.name,
+    description: recipe.description,
+    intent_signatures: recipe.intent_signatures,
+    tool_scope: recipe.tool_scope,
+    path: recipe.path,
+  };
+}
+
+/**
+ * heyspex_list_recipes({ intent? }) — return matching recipes.
+ * No intent → every recipe. With intent → only recipes whose intent_signatures
+ * (or name/description) match, each annotated with a match_strength and sorted
+ * strongest-first, then by name.
+ */
+export function executeListRecipes(vaultRoot, args = {}) {
+  const recipes = loadRecipes(vaultRoot);
+  const intent = typeof args.intent === 'string' ? args.intent.trim() : '';
+
+  let matches;
+  if (!intent) {
+    matches = recipes.map((r) => ({ ...summarize(r), match_strength: null }));
+  } else {
+    matches = [];
+    for (const r of recipes) {
+      const strength = matchStrength(r, intent);
+      if (strength) matches.push({ ...summarize(r), match_strength: strength });
+    }
+  }
+
+  const rank = { high: 0, medium: 1 };
+  matches.sort((a, b) => {
+    const ra = rank[a.match_strength] ?? 2;
+    const rb = rank[b.match_strength] ?? 2;
+    if (ra !== rb) return ra - rb;
+    return String(a.name ?? '').localeCompare(String(b.name ?? ''));
+  });
+
+  return {
+    recipes: matches,
+    count: matches.length,
+    total: recipes.length,
+    filters_applied: { intent: intent || null },
+  };
+}
+
+/**
+ * matchingRecipes(vaultRoot, intent) — the compact list attached to a preflight
+ * response. Same match rule as executeListRecipes but shaped for discovery
+ * (id/name/match_strength). Returns [] when nothing matches. Never throws.
+ */
+export function matchingRecipes(vaultRoot, intent) {
+  if (typeof intent !== 'string' || !intent.trim()) return [];
+  let recipes;
+  try {
+    recipes = loadRecipes(vaultRoot);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const r of recipes) {
+    const strength = matchStrength(r, intent);
+    if (strength) {
+      out.push({
+        id: r.id,
+        name: r.name,
+        description: r.description,
+        match_strength: strength,
+        start: { tool: 'heyspex_start_recipe', args: { recipe_id: r.id } },
+      });
+    }
+  }
+  const rank = { high: 0, medium: 1 };
+  out.sort((a, b) => (rank[a.match_strength] ?? 2) - (rank[b.match_strength] ?? 2));
+  return out;
+}
+
+/**
+ * Resolve a recipe by id or slug. Accepts the authored id ("HS-RECIPE-bug-fix"),
+ * the bare slug ("bug-fix"), or an underscore/space variant ("bug fix").
+ */
+export function resolveRecipe(vaultRoot, recipeId) {
+  const wanted = canonicalToken(recipeId);
+  if (!wanted) return null;
+  const recipes = loadRecipes(vaultRoot);
+  for (const r of recipes) {
+    const id = canonicalToken(r.id);
+    const slug = id.replace(/^hs recipe /, '');
+    if (id === wanted || slug === wanted) return r;
+  }
+  return null;
+}
+
+/**
+ * Build the "start context" a recipe hands off: everything a capture walk needs
+ * to structure the start of work (the capture_sequence to walk, the
+ * spec_template to pre-fill, the tool_scope + recipe_id to stamp for provenance
+ * — stamped through the capture→file path by [[HS-98G6-TASK]]).
+ */
+export function buildRecipeStartContext(recipe, args = {}) {
+  const captureText =
+    typeof args.capture_text === 'string' && args.capture_text.trim()
+      ? args.capture_text.trim()
+      : null;
+  return {
+    recipe_id: recipe.id,
+    name: recipe.name,
+    description: recipe.description,
+    capture_sequence: recipe.capture_sequence,
+    spec_template: recipe.spec_template,
+    tool_scope: recipe.tool_scope,
+    procedures: recipe.procedures,
+    ...(captureText ? { capture_text: captureText } : {}),
+  };
+}
+
+/**
+ * heyspex_start_recipe({ recipe_id, capture_text? }) — pure arm. Resolves the
+ * recipe and returns its start context, or an error the shell surfaces. The
+ * console capture create/pin (the "creates/pins a capture" side effect) lives in
+ * cli.mjs's thin shell so this stays synchronous and testable without a server.
+ */
+export function executeStartRecipe(vaultRoot, args = {}) {
+  const recipeId = typeof args.recipe_id === 'string' ? args.recipe_id.trim() : '';
+  if (!recipeId) {
+    return {
+      error: 'MISSING_RECIPE_ID',
+      message: 'recipe_id is required (e.g. "HS-RECIPE-bug-fix" or "bug-fix").',
+    };
+  }
+  const recipe = resolveRecipe(vaultRoot, recipeId);
+  if (!recipe) {
+    const known = loadRecipes(vaultRoot).map((r) => r.id).filter(Boolean);
+    return {
+      error: 'RECIPE_NOT_FOUND',
+      message: `No recipe matching "${recipeId}". Known recipes: ${known.join(', ') || '(none)'}. Call heyspex_list_recipes to browse.`,
+    };
+  }
+  return { recipe: buildRecipeStartContext(recipe, args) };
+}