heyspex 0.2.5 → 0.2.7

package/vendor/heyspex-mcp/procedure-handlers.mjs

@@ -1,327 +1,327 @@
-// heyspex_list_procedures, get_procedure, preflight handlers (disk and tier-aware
-// variants; the procedure store itself is procedure-tools.mjs). Extracted from cli.mjs under
-// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
-
-import { executeGetProcedure, executeGetProcedureViaTier, executeListProcedures, executeListProceduresViaTier, executeRunPreflight, executeRunPreflightViaTier } from './procedure-tools.mjs';
-import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
-import { preflightMarkerNotice, writePreflightMarker } from './preflight-gate.mjs';
-
-/**
- * [[HS-K0ZP]]: reading research-capture-protocol directly is the same proof that
- * running heyspex_preflight({ intent: "research" }) gives, so a successful
- * heyspex_get_procedure on it writes the `research` marker too. Only a real body
- * counts -- a NOT_FOUND response taught the agent nothing. Never throws: the
- * marker write is fail-open by contract, and a read must never break on it.
- */
-export const RESEARCH_PROTOCOL_NAME = 'research-capture-protocol';
-export function recordResearchProtocolRead(vaultRoot, args, result) {
-  try {
-    if (String(args?.name ?? '').trim() !== RESEARCH_PROTOCOL_NAME) return false;
-    if (!result || result.error || !result.content) return false;
-    const identity = detectAgentIdentity(args.agent, args.session_id);
-    return writePreflightMarker(vaultRoot, 'research', {
-      sessionId: identity.sessionId,
-      agent: identity.agent,
-      procedures: [RESEARCH_PROTOCOL_NAME],
-      degradedSource: result.degraded ? 'disk' : undefined,
-    });
-  } catch {
-    return false;
-  }
-}
-import { matchingRecipes } from './recipe-tools.mjs';
-import { wrapDesignResult } from './tool-helpers.mjs';
-import { MEMORY_BASELINE_TAGS, MEMORY_DESCRIPTION_TRUNCATE, MEMORY_INJECTION_LIMIT, detectMemoryAmendment, scoreRelevantMemories } from './on-deck-brief.mjs';
-import { consoleReadErrorFrom, readViaSelector, resolveReadTier } from './read-path.mjs';
-import { consoleFetch } from './console-transport.mjs';
-import { extractSummary } from './memory-tools.mjs';
-
-export function handleListProcedures(vaultRoot, args) {
-  return wrapDesignResult(executeListProcedures(vaultRoot, args));
-}
-
-export function handleGetProcedure(vaultRoot, args) {
-  const result = executeGetProcedure(vaultRoot, args);
-  recordResearchProtocolRead(vaultRoot, args, result);
-  return wrapDesignResult(result);
-}
-
-export function handleRunPreflight(vaultRoot, args) {
-  const result = executeRunPreflight(vaultRoot, args);
-
-  // Proof-of-use ([[preflight-gate]]): record that the questions were actually
-  // asked, so the tools those questions govern can refuse when they were not.
-  // Only a real answer counts — an UNKNOWN_INTENT / CATALOG_NOT_FOUND response
-  // taught the agent nothing and must not clear a gate.
-  if (result && !result.error) {
-    const identity = detectAgentIdentity(args.agent, args.session_id);
-    const wrote = writePreflightMarker(vaultRoot, String(args.intent ?? '').trim(), {
-      sessionId: identity.sessionId,
-      agent: identity.agent,
-      threadType: args.thread_type ?? null,
-      procedures: Array.isArray(result.procedures)
-        ? result.procedures.map((p) => p?.procedure).filter(Boolean)
-        : [],
-    });
-    // A marker we could not write used to be swallowed silently, so preflight
-    // reported success while the gated tools refused forever and told the caller
-    // to "call preflight, then retry" — a loop no retry escaped
-    // ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]] item 3).
-    // Preflight still succeeds (fail-open); it just stops claiming it recorded
-    // something it did not.
-    const notice = preflightMarkerNotice(wrote);
-    if (notice) Object.assign(result, notice);
-  }
-  // Match workflow-recipes against the intent so recipes are discoverable the
-  // same way procedures are ([[HS-RQ9K-TASK]] / [[HS-5G0P-EPIC]]). Never throws.
-  let recipes = [];
-  try {
-    recipes = matchingRecipes(vaultRoot, args.intent);
-  } catch {
-    recipes = [];
-  }
-
-  // Recipe-only intent (e.g. "bug_fix"): a valid recipe signature that is NOT a
-  // procedure intent returns UNKNOWN_INTENT from the procedure map. Rather than
-  // hard-error, surface the matching recipes so the caller still gets a useful
-  // answer — recipe intents live in a different namespace than procedure intents.
-  if (result && result.error === 'UNKNOWN_INTENT' && recipes.length > 0) {
-    return wrapDesignResult({
-      intent: String(args.intent ?? '').trim(),
-      procedures: [],
-      recipes,
-      note:
-        'No procedure checklist for this intent, but it matches one or more workflow-recipes. Start one with heyspex_start_recipe, or call heyspex_preflight with a procedure intent (e.g. file_task, execute_spec).',
-    });
-  }
-
-  // Attach recalled_memories so high-stakes decision points carry the same
-  // memory load /hs-next does. Skipped on error responses ([[HS-TASK-IMMF]]).
-  if (result && !result.error) {
-    try {
-      const recalled = scoreRelevantMemories(vaultRoot, {
-        // Use the intent name as a primary signal so an intent like
-        // recommend_location surfaces template/saas/architecture memories
-        // strongly. The baseline pool still applies on top.
-        primaryTags: typeof args.intent === 'string' ? [args.intent] : [],
-      });
-      if (recalled.items.length > 0) {
-        result.recalled_memories = recalled;
-      }
-    } catch {
-      // Recall failure must never break preflight — surface the procedures
-      // without memories rather than 500ing the response.
-    }
-    if (recipes.length > 0) {
-      result.recipes = recipes;
-    }
-  }
-  return wrapDesignResult(result);
-}
-
-/**
- * Cloud-reliant sibling of `handleListProcedures` ([[HS-DJWP-MCPC-TASK]]
- * "Procedures" family, backing `heyspex_list_procedures`). `handleListProcedures`
- * stays untouched (its `diskRead` branch).
- */
-export async function handleListProceduresViaTier(vaultRoot, args) {
-  const tier = await resolveReadTier();
-  const result = await executeListProceduresViaTier({
-    vaultRoot,
-    args,
-    tier,
-    consoleFetch,
-    consoleUrl: effectiveConsoleUrl(),
-  });
-  return wrapDesignResult(result);
-}
-
-/**
- * Cloud-reliant sibling of `handleGetProcedure` ([[HS-DJWP-MCPC-TASK]]
- * "Procedures" family, backing `heyspex_get_procedure`). `handleGetProcedure`
- * stays untouched (its `diskRead` branch).
- */
-export async function handleGetProcedureViaTier(vaultRoot, args) {
-  const tier = await resolveReadTier();
-  const result = await executeGetProcedureViaTier({
-    vaultRoot,
-    args,
-    tier,
-    consoleFetch,
-    consoleUrl: effectiveConsoleUrl(),
-  });
-  recordResearchProtocolRead(vaultRoot, args, result);
-  return wrapDesignResult(result);
-}
-
-/**
- * Cloud-reliant sibling of `handleRunPreflight` ([[HS-DJWP-MCPC-TASK]]
- * "Procedures" + "Memories" families, backing `heyspex_preflight`).
- * `handleRunPreflight` is left completely untouched — it is imported and
- * called directly (synchronously) by `preflight-gate.test.mjs`, so it must
- * keep returning a plain object, never a Promise. This is a SEPARATE function,
- * used only by the live tool dispatch (`case 'heyspex_preflight'` below),
- * which duplicates the marker-write / recipe-match / memory-recall tail
- * (`writePreflightMarker`, `preflightMarkerNotice`, `matchingRecipes` are
- * reused unchanged — only the tier-aware catalog + memory fetch differ).
- */
-export async function handleRunPreflightViaTier(vaultRoot, args) {
-  const tier = await resolveReadTier();
-  const consoleUrl = effectiveConsoleUrl();
-  const result = await executeRunPreflightViaTier({ vaultRoot, args, tier, consoleFetch, consoleUrl });
-
-  if (result && !result.error) {
-    const identity = detectAgentIdentity(args.agent, args.session_id);
-    const wrote = writePreflightMarker(vaultRoot, String(args.intent ?? '').trim(), {
-      sessionId: identity.sessionId,
-      agent: identity.agent,
-      threadType: args.thread_type ?? null,
-      procedures: Array.isArray(result.procedures)
-        ? result.procedures.map((p) => p?.procedure).filter(Boolean)
-        : [],
-      degradedSource: result.degraded ? 'disk' : undefined,
-    });
-    const notice = preflightMarkerNotice(wrote);
-    if (notice) Object.assign(result, notice);
-  }
-
-  let recipes = [];
-  try {
-    recipes = matchingRecipes(vaultRoot, args.intent);
-  } catch {
-    recipes = [];
-  }
-
-  if (result && result.error === 'UNKNOWN_INTENT' && recipes.length > 0) {
-    return wrapDesignResult({
-      intent: String(args.intent ?? '').trim(),
-      procedures: [],
-      recipes,
-      note:
-        'No procedure checklist for this intent, but it matches one or more workflow-recipes. Start one with heyspex_start_recipe, or call heyspex_preflight with a procedure intent (e.g. file_task, execute_spec).',
-    });
-  }
-
-  if (result && !result.error) {
-    try {
-      const recalled = await scoreRelevantMemoriesViaTier(
-        vaultRoot,
-        { primaryTags: typeof args.intent === 'string' ? [args.intent] : [] },
-        { tier, consoleUrl },
-      );
-      if (recalled.items.length > 0) {
-        result.recalled_memories = recalled;
-      }
-    } catch {
-      // Recall failure must never break preflight.
-    }
-    if (recipes.length > 0) {
-      result.recipes = recipes;
-    }
-  }
-  return wrapDesignResult(result);
-}
-
-/**
- * Cloud-reliant sibling of `scoreRelevantMemories` ([[HS-DJWP-MCPC-TASK]]
- * "Memories" family, backing the preflight memory recall). `scoreRelevantMemories`
- * is left completely untouched (its callers — `handleRunPreflight`,
- * `enrichOnDeckWithRecalledMemories` — keep the exact disk-only behavior they
- * have today); this is a NEW, separate cloud path used only by
- * `handleRunPreflightViaTier` below. Scoring logic (tag-overlap, amendment
- * detection, truncation, sort) is duplicated rather than shared with
- * `scoreRelevantMemories` deliberately — the two operate on differently-shaped
- * inputs (disk: `{frontmatter, body}` per file; cloud: the console's flat
- * `MemoryDoc` rows) and duplicating ~25 lines is a smaller risk than
- * refactoring the already-tested disk function to share a helper.
- *
- * Unlike `handleRecallMemoriesViaTier`, no fidelity gap here — `MemoryDoc`
- * already carries everything this scorer reads (`tags`, `body`, `name`, `id`).
- *
- * Split into a tag-only ranking pass ({@link rankMemoryCandidatesByTags}) and a
- * per-item body-dependent builder ({@link buildScoredMemoryItem}) so the
- * caller ({@link scoreRelevantMemoriesViaTier}) can rank against a
- * summary-only listing (score is pure tag-overlap, never touches body) and
- * only fetch body text for the top `limit` survivors —
- * [[HS-LKV0-FUU4-DIAG-cloud-mode-recall-times-out-the]]: the console's
- * `GET /api/memories` used to always ship a body per doc, which is what made
- * a 896-doc vault blow the 30s fetch timeout on every one of these read paths.
- */
-export function rankMemoryCandidatesByTags(docs, options = {}) {
-  const primaryTags = Array.isArray(options.primaryTags) ? options.primaryTags : [];
-  const baselineTags = Array.isArray(options.baselineTags) ? options.baselineTags : MEMORY_BASELINE_TAGS;
-  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : MEMORY_INJECTION_LIMIT;
-
-  const querySet = new Set([...primaryTags, ...baselineTags].map((t) => String(t).toLowerCase()));
-  if (querySet.size === 0) return [];
-
-  const scored = [];
-  for (const doc of docs) {
-    const tags = Array.isArray(doc.tags) ? doc.tags : [];
-    if (tags.length === 0) continue;
-    const tagSet = new Set(tags.map((t) => String(t).toLowerCase()));
-    let score = 0;
-    for (const q of querySet) if (tagSet.has(q)) score += 1;
-    if (score === 0) continue;
-    scored.push({ doc, score });
-  }
-
-  scored.sort((a, b) => {
-    if (b.score !== a.score) return b.score - a.score;
-    const aName = a.doc.name || a.doc.id || '';
-    const bName = b.doc.name || b.doc.id || '';
-    return String(aName).localeCompare(String(bName));
-  });
-
-  return scored.slice(0, limit);
-}
-
-/** Builds one scored-memory item from a ranked candidate + its (separately fetched) body. */
-export function buildScoredMemoryItem(doc, score, body) {
-  const slug = doc.id;
-  const name = doc.name || doc.id || slug;
-  let description = extractSummary(body || '');
-  if (description.length > MEMORY_DESCRIPTION_TRUNCATE) {
-    description = description.slice(0, MEMORY_DESCRIPTION_TRUNCATE - 1) + '…';
-  }
-  const amended = detectMemoryAmendment(body || '', description);
-  if (amended) {
-    description = `${description} ⚠ ${amended} — this summary may not reflect the current ruling; READ THE FULL BODY before applying.`;
-  }
-  return { source: 'vault', name, link: `[[${slug}]]`, description, amended: amended || undefined, score };
-}
-
-export async function scoreRelevantMemoriesViaTier(vaultRoot, options, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    diskRead: () => scoreRelevantMemories(vaultRoot, options),
-    neonRead: async () => {
-      // Summary-only listing — scoring is pure tag-overlap and never needs body.
-      const res = await consoleFetch('/api/memories');
-      if (!res.ok) {
-        throw consoleReadErrorFrom(res, `GET /api/memories returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
-      }
-      const docs = Array.isArray(res.body?.memories) ? res.body.memories : [];
-      const ranked = rankMemoryCandidatesByTags(docs, options);
-      if (ranked.length === 0) return { header: null, items: [] };
-
-      // Fetch bodies ONLY for the survivors that ranking already narrowed to
-      // (`limit`, default 5) — never one fetch per candidate across the whole set.
-      const idsQs = new URLSearchParams({ ids: ranked.map(({ doc }) => doc.id).join(','), fields: 'body' });
-      const bodyPath = `/api/memories?${idsQs}`;
-      const bodyRes = await consoleFetch(bodyPath);
-      if (!bodyRes.ok) {
-        throw consoleReadErrorFrom(bodyRes, `GET ${bodyPath} returned ${bodyRes.status}: ${bodyRes.error || JSON.stringify(bodyRes.body ?? {})}`, null);
-      }
-      const bodyDocs = Array.isArray(bodyRes.body?.memories) ? bodyRes.body.memories : [];
-      const bodyById = new Map(bodyDocs.map((d) => [d.id, typeof d.body === 'string' ? d.body : '']));
-
-      return {
-        header: 'Retrieved from prior sessions. Apply at decision points; do not echo verbatim.',
-        items: ranked.map(({ doc, score }) => buildScoredMemoryItem(doc, score, bodyById.get(doc.id) || '')),
-      };
-    },
-    routeLabel: 'GET /api/memories',
-    consoleUrl,
-  });
-}
+// heyspex_list_procedures, get_procedure, preflight handlers (disk and tier-aware
+// variants; the procedure store itself is procedure-tools.mjs). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+import { executeGetProcedure, executeGetProcedureViaTier, executeListProcedures, executeListProceduresViaTier, executeRunPreflight, executeRunPreflightViaTier } from './procedure-tools.mjs';
+import { detectAgentIdentity, effectiveConsoleUrl } from './mcp-config.mjs';
+import { preflightMarkerNotice, writePreflightMarker } from './preflight-gate.mjs';
+
+/**
+ * [[HS-K0ZP]]: reading research-capture-protocol directly is the same proof that
+ * running heyspex_preflight({ intent: "research" }) gives, so a successful
+ * heyspex_get_procedure on it writes the `research` marker too. Only a real body
+ * counts -- a NOT_FOUND response taught the agent nothing. Never throws: the
+ * marker write is fail-open by contract, and a read must never break on it.
+ */
+export const RESEARCH_PROTOCOL_NAME = 'research-capture-protocol';
+export function recordResearchProtocolRead(vaultRoot, args, result) {
+  try {
+    if (String(args?.name ?? '').trim() !== RESEARCH_PROTOCOL_NAME) return false;
+    if (!result || result.error || !result.content) return false;
+    const identity = detectAgentIdentity(args.agent, args.session_id);
+    return writePreflightMarker(vaultRoot, 'research', {
+      sessionId: identity.sessionId,
+      agent: identity.agent,
+      procedures: [RESEARCH_PROTOCOL_NAME],
+      degradedSource: result.degraded ? 'disk' : undefined,
+    });
+  } catch {
+    return false;
+  }
+}
+import { matchingRecipes } from './recipe-tools.mjs';
+import { wrapDesignResult } from './tool-helpers.mjs';
+import { MEMORY_BASELINE_TAGS, MEMORY_DESCRIPTION_TRUNCATE, MEMORY_INJECTION_LIMIT, detectMemoryAmendment, scoreRelevantMemories } from './on-deck-brief.mjs';
+import { consoleReadErrorFrom, readViaSelector, resolveReadTier } from './read-path.mjs';
+import { consoleFetch } from './console-transport.mjs';
+import { extractSummary } from './memory-tools.mjs';
+
+export function handleListProcedures(vaultRoot, args) {
+  return wrapDesignResult(executeListProcedures(vaultRoot, args));
+}
+
+export function handleGetProcedure(vaultRoot, args) {
+  const result = executeGetProcedure(vaultRoot, args);
+  recordResearchProtocolRead(vaultRoot, args, result);
+  return wrapDesignResult(result);
+}
+
+export function handleRunPreflight(vaultRoot, args) {
+  const result = executeRunPreflight(vaultRoot, args);
+
+  // Proof-of-use ([[preflight-gate]]): record that the questions were actually
+  // asked, so the tools those questions govern can refuse when they were not.
+  // Only a real answer counts — an UNKNOWN_INTENT / CATALOG_NOT_FOUND response
+  // taught the agent nothing and must not clear a gate.
+  if (result && !result.error) {
+    const identity = detectAgentIdentity(args.agent, args.session_id);
+    const wrote = writePreflightMarker(vaultRoot, String(args.intent ?? '').trim(), {
+      sessionId: identity.sessionId,
+      agent: identity.agent,
+      threadType: args.thread_type ?? null,
+      procedures: Array.isArray(result.procedures)
+        ? result.procedures.map((p) => p?.procedure).filter(Boolean)
+        : [],
+    });
+    // A marker we could not write used to be swallowed silently, so preflight
+    // reported success while the gated tools refused forever and told the caller
+    // to "call preflight, then retry" — a loop no retry escaped
+    // ([[HS-N71O-P3XQ-DIAG-six-new-qc-gates-fail-cold-verification]] item 3).
+    // Preflight still succeeds (fail-open); it just stops claiming it recorded
+    // something it did not.
+    const notice = preflightMarkerNotice(wrote);
+    if (notice) Object.assign(result, notice);
+  }
+  // Match workflow-recipes against the intent so recipes are discoverable the
+  // same way procedures are ([[HS-RQ9K-TASK]] / [[HS-5G0P-EPIC]]). Never throws.
+  let recipes = [];
+  try {
+    recipes = matchingRecipes(vaultRoot, args.intent);
+  } catch {
+    recipes = [];
+  }
+
+  // Recipe-only intent (e.g. "bug_fix"): a valid recipe signature that is NOT a
+  // procedure intent returns UNKNOWN_INTENT from the procedure map. Rather than
+  // hard-error, surface the matching recipes so the caller still gets a useful
+  // answer — recipe intents live in a different namespace than procedure intents.
+  if (result && result.error === 'UNKNOWN_INTENT' && recipes.length > 0) {
+    return wrapDesignResult({
+      intent: String(args.intent ?? '').trim(),
+      procedures: [],
+      recipes,
+      note:
+        'No procedure checklist for this intent, but it matches one or more workflow-recipes. Start one with heyspex_start_recipe, or call heyspex_preflight with a procedure intent (e.g. file_task, execute_spec).',
+    });
+  }
+
+  // Attach recalled_memories so high-stakes decision points carry the same
+  // memory load /hs-next does. Skipped on error responses ([[HS-TASK-IMMF]]).
+  if (result && !result.error) {
+    try {
+      const recalled = scoreRelevantMemories(vaultRoot, {
+        // Use the intent name as a primary signal so an intent like
+        // recommend_location surfaces template/saas/architecture memories
+        // strongly. The baseline pool still applies on top.
+        primaryTags: typeof args.intent === 'string' ? [args.intent] : [],
+      });
+      if (recalled.items.length > 0) {
+        result.recalled_memories = recalled;
+      }
+    } catch {
+      // Recall failure must never break preflight — surface the procedures
+      // without memories rather than 500ing the response.
+    }
+    if (recipes.length > 0) {
+      result.recipes = recipes;
+    }
+  }
+  return wrapDesignResult(result);
+}
+
+/**
+ * Cloud-reliant sibling of `handleListProcedures` ([[HS-DJWP-MCPC-TASK]]
+ * "Procedures" family, backing `heyspex_list_procedures`). `handleListProcedures`
+ * stays untouched (its `diskRead` branch).
+ */
+export async function handleListProceduresViaTier(vaultRoot, args) {
+  const tier = await resolveReadTier();
+  const result = await executeListProceduresViaTier({
+    vaultRoot,
+    args,
+    tier,
+    consoleFetch,
+    consoleUrl: effectiveConsoleUrl(),
+  });
+  return wrapDesignResult(result);
+}
+
+/**
+ * Cloud-reliant sibling of `handleGetProcedure` ([[HS-DJWP-MCPC-TASK]]
+ * "Procedures" family, backing `heyspex_get_procedure`). `handleGetProcedure`
+ * stays untouched (its `diskRead` branch).
+ */
+export async function handleGetProcedureViaTier(vaultRoot, args) {
+  const tier = await resolveReadTier();
+  const result = await executeGetProcedureViaTier({
+    vaultRoot,
+    args,
+    tier,
+    consoleFetch,
+    consoleUrl: effectiveConsoleUrl(),
+  });
+  recordResearchProtocolRead(vaultRoot, args, result);
+  return wrapDesignResult(result);
+}
+
+/**
+ * Cloud-reliant sibling of `handleRunPreflight` ([[HS-DJWP-MCPC-TASK]]
+ * "Procedures" + "Memories" families, backing `heyspex_preflight`).
+ * `handleRunPreflight` is left completely untouched — it is imported and
+ * called directly (synchronously) by `preflight-gate.test.mjs`, so it must
+ * keep returning a plain object, never a Promise. This is a SEPARATE function,
+ * used only by the live tool dispatch (`case 'heyspex_preflight'` below),
+ * which duplicates the marker-write / recipe-match / memory-recall tail
+ * (`writePreflightMarker`, `preflightMarkerNotice`, `matchingRecipes` are
+ * reused unchanged — only the tier-aware catalog + memory fetch differ).
+ */
+export async function handleRunPreflightViaTier(vaultRoot, args) {
+  const tier = await resolveReadTier();
+  const consoleUrl = effectiveConsoleUrl();
+  const result = await executeRunPreflightViaTier({ vaultRoot, args, tier, consoleFetch, consoleUrl });
+
+  if (result && !result.error) {
+    const identity = detectAgentIdentity(args.agent, args.session_id);
+    const wrote = writePreflightMarker(vaultRoot, String(args.intent ?? '').trim(), {
+      sessionId: identity.sessionId,
+      agent: identity.agent,
+      threadType: args.thread_type ?? null,
+      procedures: Array.isArray(result.procedures)
+        ? result.procedures.map((p) => p?.procedure).filter(Boolean)
+        : [],
+      degradedSource: result.degraded ? 'disk' : undefined,
+    });
+    const notice = preflightMarkerNotice(wrote);
+    if (notice) Object.assign(result, notice);
+  }
+
+  let recipes = [];
+  try {
+    recipes = matchingRecipes(vaultRoot, args.intent);
+  } catch {
+    recipes = [];
+  }
+
+  if (result && result.error === 'UNKNOWN_INTENT' && recipes.length > 0) {
+    return wrapDesignResult({
+      intent: String(args.intent ?? '').trim(),
+      procedures: [],
+      recipes,
+      note:
+        'No procedure checklist for this intent, but it matches one or more workflow-recipes. Start one with heyspex_start_recipe, or call heyspex_preflight with a procedure intent (e.g. file_task, execute_spec).',
+    });
+  }
+
+  if (result && !result.error) {
+    try {
+      const recalled = await scoreRelevantMemoriesViaTier(
+        vaultRoot,
+        { primaryTags: typeof args.intent === 'string' ? [args.intent] : [] },
+        { tier, consoleUrl },
+      );
+      if (recalled.items.length > 0) {
+        result.recalled_memories = recalled;
+      }
+    } catch {
+      // Recall failure must never break preflight.
+    }
+    if (recipes.length > 0) {
+      result.recipes = recipes;
+    }
+  }
+  return wrapDesignResult(result);
+}
+
+/**
+ * Cloud-reliant sibling of `scoreRelevantMemories` ([[HS-DJWP-MCPC-TASK]]
+ * "Memories" family, backing the preflight memory recall). `scoreRelevantMemories`
+ * is left completely untouched (its callers — `handleRunPreflight`,
+ * `enrichOnDeckWithRecalledMemories` — keep the exact disk-only behavior they
+ * have today); this is a NEW, separate cloud path used only by
+ * `handleRunPreflightViaTier` below. Scoring logic (tag-overlap, amendment
+ * detection, truncation, sort) is duplicated rather than shared with
+ * `scoreRelevantMemories` deliberately — the two operate on differently-shaped
+ * inputs (disk: `{frontmatter, body}` per file; cloud: the console's flat
+ * `MemoryDoc` rows) and duplicating ~25 lines is a smaller risk than
+ * refactoring the already-tested disk function to share a helper.
+ *
+ * Unlike `handleRecallMemoriesViaTier`, no fidelity gap here — `MemoryDoc`
+ * already carries everything this scorer reads (`tags`, `body`, `name`, `id`).
+ *
+ * Split into a tag-only ranking pass ({@link rankMemoryCandidatesByTags}) and a
+ * per-item body-dependent builder ({@link buildScoredMemoryItem}) so the
+ * caller ({@link scoreRelevantMemoriesViaTier}) can rank against a
+ * summary-only listing (score is pure tag-overlap, never touches body) and
+ * only fetch body text for the top `limit` survivors —
+ * [[HS-LKV0-FUU4-DIAG-cloud-mode-recall-times-out-the]]: the console's
+ * `GET /api/memories` used to always ship a body per doc, which is what made
+ * a 896-doc vault blow the 30s fetch timeout on every one of these read paths.
+ */
+export function rankMemoryCandidatesByTags(docs, options = {}) {
+  const primaryTags = Array.isArray(options.primaryTags) ? options.primaryTags : [];
+  const baselineTags = Array.isArray(options.baselineTags) ? options.baselineTags : MEMORY_BASELINE_TAGS;
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : MEMORY_INJECTION_LIMIT;
+
+  const querySet = new Set([...primaryTags, ...baselineTags].map((t) => String(t).toLowerCase()));
+  if (querySet.size === 0) return [];
+
+  const scored = [];
+  for (const doc of docs) {
+    const tags = Array.isArray(doc.tags) ? doc.tags : [];
+    if (tags.length === 0) continue;
+    const tagSet = new Set(tags.map((t) => String(t).toLowerCase()));
+    let score = 0;
+    for (const q of querySet) if (tagSet.has(q)) score += 1;
+    if (score === 0) continue;
+    scored.push({ doc, score });
+  }
+
+  scored.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const aName = a.doc.name || a.doc.id || '';
+    const bName = b.doc.name || b.doc.id || '';
+    return String(aName).localeCompare(String(bName));
+  });
+
+  return scored.slice(0, limit);
+}
+
+/** Builds one scored-memory item from a ranked candidate + its (separately fetched) body. */
+export function buildScoredMemoryItem(doc, score, body) {
+  const slug = doc.id;
+  const name = doc.name || doc.id || slug;
+  let description = extractSummary(body || '');
+  if (description.length > MEMORY_DESCRIPTION_TRUNCATE) {
+    description = description.slice(0, MEMORY_DESCRIPTION_TRUNCATE - 1) + '…';
+  }
+  const amended = detectMemoryAmendment(body || '', description);
+  if (amended) {
+    description = `${description} ⚠ ${amended} — this summary may not reflect the current ruling; READ THE FULL BODY before applying.`;
+  }
+  return { source: 'vault', name, link: `[[${slug}]]`, description, amended: amended || undefined, score };
+}
+
+export async function scoreRelevantMemoriesViaTier(vaultRoot, options, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => scoreRelevantMemories(vaultRoot, options),
+    neonRead: async () => {
+      // Summary-only listing — scoring is pure tag-overlap and never needs body.
+      const res = await consoleFetch('/api/memories');
+      if (!res.ok) {
+        throw consoleReadErrorFrom(res, `GET /api/memories returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+      }
+      const docs = Array.isArray(res.body?.memories) ? res.body.memories : [];
+      const ranked = rankMemoryCandidatesByTags(docs, options);
+      if (ranked.length === 0) return { header: null, items: [] };
+
+      // Fetch bodies ONLY for the survivors that ranking already narrowed to
+      // (`limit`, default 5) — never one fetch per candidate across the whole set.
+      const idsQs = new URLSearchParams({ ids: ranked.map(({ doc }) => doc.id).join(','), fields: 'body' });
+      const bodyPath = `/api/memories?${idsQs}`;
+      const bodyRes = await consoleFetch(bodyPath);
+      if (!bodyRes.ok) {
+        throw consoleReadErrorFrom(bodyRes, `GET ${bodyPath} returned ${bodyRes.status}: ${bodyRes.error || JSON.stringify(bodyRes.body ?? {})}`, null);
+      }
+      const bodyDocs = Array.isArray(bodyRes.body?.memories) ? bodyRes.body.memories : [];
+      const bodyById = new Map(bodyDocs.map((d) => [d.id, typeof d.body === 'string' ? d.body : '']));
+
+      return {
+        header: 'Retrieved from prior sessions. Apply at decision points; do not echo verbatim.',
+        items: ranked.map(({ doc, score }) => buildScoredMemoryItem(doc, score, bodyById.get(doc.id) || '')),
+      };
+    },
+    routeLabel: 'GET /api/memories',
+    consoleUrl,
+  });
+}