heyspex 0.1.0 → 0.2.1

package/vendor/heyspex-mcp/plan-review.mjs

@@ -18,7 +18,9 @@
  *      [[closed-trackable-specs-are-historical-record-not-living-docs]]) and
  *      classify each hit SUPERSEDED | SUBSUMED | SIBLING | UPSTREAM | PARENT.
  *   3. Code audit — resolve the literal files/symbols the plan names against
- *      the codebase: unresolved → BLOCKER, resolved → INFO.
+ *      the CODE checkout first and the vault checkout second
+ *      ({@link resolveCodeAuditRoots}): unresolved in both → BLOCKER,
+ *      resolved → INFO.
  *   4. Canonical + supersession — borrow the SRP test from
  *      [[doc-canonicalization-protocol]] and the relationship language from
  *      [[supersession-protocol]].
@@ -31,7 +33,10 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+import { PACKAGE_ROOT } from './package-root.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+import { resolveCodeAndVaultRoots } from '../../scripts/lib/shared-path-helpers.mjs';
 
 // In-flight statuses only. Terminal-status specs (closed / superseded /
 // cancelled / duplicate / archived) are frozen historical records, filtered
@@ -56,11 +61,17 @@ const OVERLAP_DIRS = [
 // Memory buckets scanned only for the Axis-B design-supersession pass (Pass 6).
 const MEMORY_AXIS_DIRS = ['specs/memory/decisions', 'specs/memory/lessons'];
 
-// Code roots scanned by the code-audit pass for symbol resolution. Only those
-// that exist under vaultRoot are read; missing roots are skipped silently.
-// (specs/ is intentionally excluded — it holds markdown, not code; symbols
-// mentioned only in prose specs must not count as "resolved" in code.)
+// Code roots scanned by the code-audit pass for symbol resolution, relative to
+// each checkout in {@link resolveCodeAuditRoots}. Only those that exist are
+// read; missing roots are skipped silently. (specs/ is intentionally excluded —
+// it holds markdown, not code; symbols mentioned only in prose specs must not
+// count as "resolved" in code.)
 const CODE_ROOTS = ['vendor/heyspex-mcp', 'spex-console/src', 'scripts'];
+
+// THIS PACKAGE's own root — `vendor/heyspex-mcp/plan-review.mjs` -> two levels
+// up: the code repo root in the monorepo, `node_modules/heyspex` in a packed
+// install. Same derivation `read-path.mjs` (PACKAGE_ROOT) and `dev-tools.mjs`
+// (CHECKOUT_ROOT) already use for this package's own sibling code.
 const CODE_EXTS = new Set(['.mjs', '.ts', '.tsx', '.js', '.jsx', '.cjs', '.mts', '.cts']);
 const SKIP_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo', 'coverage']);
 const MAX_CODE_FILES = 4000; // backstop so the audit can't walk an unbounded tree
@@ -541,9 +552,52 @@ function runOverlapPass(planBody, scope, candidates) {
   return { in_flight_overlap: overlaps, supersedes, canonical_doc: canonicalDoc };
 }
 
-/** Recursively collect code files under a root, bounded by MAX_CODE_FILES. */
-function collectCodeFiles(vaultRoot, root, acc) {
-  const full = join(vaultRoot, root);
+/**
+ * The ordered checkouts the code audit resolves a plan's `files`/`symbols`
+ * against ([[HS-8BHX-OUJ0-DIAG-breakdown-plan-review-resolves-code]]).
+ *
+ * Since the repo split the vault (`specs/`) and the code (`package.json`,
+ * `scripts/`, `spex-console/src`, …) can be two separate checkouts, and the
+ * vault holds NO code — so resolving a plan's code paths against the vault root
+ * reported every real file as a `BLOCKER`, the highest severity the audit has.
+ * The CODE root therefore goes first (a plan's paths are almost always code),
+ * and the VAULT root is carried ALONGSIDE it rather than replacing it, so a plan
+ * that legitimately names vault content (`specs/…`, `heyspex.yaml`) still
+ * resolves. A path present in NEITHER checkout is still a real BLOCKER.
+ *
+ * Code-root precedence mirrors the two already-fixed sites of this bug family
+ * (`spex-console/bin/hs-check.ts`, `spex-console/bin/hs-revalidate.ts`): an
+ * explicit caller override, then the `HS_PKG_ROOT` env the `bin/hs.mjs`
+ * dispatcher forwards, then this package's own install location. The MCP server
+ * is spawned by the editor, not by that dispatcher, so `PACKAGE_ROOT` is the
+ * one that normally answers — the same derivation `read-path.mjs` and
+ * `dev-tools.mjs` use for this package's sibling code. Single-checkout installs
+ * collapse the two roots back to one entry, so nothing changes there.
+ *
+ * @param {string} vaultRoot resolved vault root (holds `specs/`)
+ * @param {string} [codeRootOverride] explicit code root (tests / future callers)
+ * @returns {{ label: string, root: string }[]}
+ */
+export function resolveCodeAuditRoots(vaultRoot, codeRootOverride) {
+  return resolveCodeAndVaultRoots({
+    vaultRoot,
+    explicit: codeRootOverride,
+    packageRoot: PACKAGE_ROOT,
+  });
+}
+
+/** "the code root (C:\a) or the vault root (C:\b)" — AC3: say where we looked. */
+function describeRoots(roots) {
+  return roots.map((r) => `the ${r.label} (${r.root})`).join(' or ');
+}
+
+/**
+ * Recursively collect code files under `root` inside one checkout, bounded by
+ * MAX_CODE_FILES. Each entry keeps the checkout it came from so the reader can
+ * be told which root resolved a symbol.
+ */
+function collectCodeFiles(base, root, acc) {
+  const full = join(base.root, root);
   if (!existsSync(full)) return;
   let entries;
   try {
@@ -555,45 +609,56 @@ function collectCodeFiles(vaultRoot, root, acc) {
     if (acc.length >= MAX_CODE_FILES) return;
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name)) continue;
-      collectCodeFiles(vaultRoot, `${root}/${entry.name}`, acc);
+      collectCodeFiles(base, `${root}/${entry.name}`, acc);
     } else if (entry.isFile()) {
       const dot = entry.name.lastIndexOf('.');
       const ext = dot === -1 ? '' : entry.name.slice(dot);
       if (!CODE_EXTS.has(ext)) continue;
-      acc.push(`${root}/${entry.name}`);
+      acc.push({ base, rel: `${root}/${entry.name}` });
     }
   }
 }
 
 /**
  * Pass 3 — code audit. Resolve each file path and symbol the plan names against
- * the codebase. Unresolved → BLOCKER; resolved → INFO.
+ * the code checkout first and the vault checkout second
+ * ({@link resolveCodeAuditRoots}). Unresolved in BOTH → BLOCKER; resolved → INFO.
+ *
+ * @returns {{ findings: object[], roots: { label: string, root: string }[] }}
  */
-function runCodeAudit(vaultRoot, scope, planContent) {
+function runCodeAudit(vaultRoot, scope, planContent, codeRootOverride) {
   const findings = [];
+  const roots = resolveCodeAuditRoots(vaultRoot, codeRootOverride);
 
-  // File-path resolution — cheap existence check.
+  // File-path resolution — cheap existence check, per checkout in order.
   for (const f of scope.files) {
     const clean = f.replace(/^\.\//, '');
-    const resolved = existsSync(join(vaultRoot, clean));
+    const hit = roots.find((entry) => existsSync(join(entry.root, clean)));
     findings.push({
       kind: 'file',
       ref: f,
-      severity: resolved ? 'INFO' : 'BLOCKER',
-      note: resolved
-        ? `File exists at ${clean}.`
-        : `Plan references ${f} but no such file exists under the vault root — fix the path or add it to scope.`,
+      severity: hit ? 'INFO' : 'BLOCKER',
+      resolved_root: hit ? hit.label : null,
+      note: hit
+        ? `File exists at ${clean} under the ${hit.label} (${hit.root}).`
+        : `Plan references ${f} but no such file exists under ${describeRoots(roots)} — fix the path or add it to scope.`,
     });
   }
 
   // Symbol resolution — build the code corpus once, then test each symbol.
   if (scope.symbols.length) {
     const files = [];
-    for (const root of CODE_ROOTS) collectCodeFiles(vaultRoot, root, files);
+    for (const entry of roots) {
+      for (const root of CODE_ROOTS) collectCodeFiles(entry, root, files);
+    }
     const corpus = [];
-    for (const rel of files) {
+    for (const file of files) {
       try {
-        corpus.push({ rel, content: readFileSync(join(vaultRoot, rel), 'utf8') });
+        corpus.push({
+          rel: file.rel,
+          base: file.base,
+          content: readFileSync(join(file.base.root, file.rel), 'utf8'),
+        });
       } catch {
         /* skip unreadable */
       }
@@ -601,9 +666,11 @@ function runCodeAudit(vaultRoot, scope, planContent) {
     for (const sym of scope.symbols) {
       const re = new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
       const where = [];
+      const whereRoots = new Set();
       for (const file of corpus) {
         if (re.test(file.content)) {
           where.push(file.rel);
+          whereRoots.add(file.base.label);
           if (where.length >= 5) break;
         }
       }
@@ -612,14 +679,15 @@ function runCodeAudit(vaultRoot, scope, planContent) {
         ref: sym,
         severity: where.length ? 'INFO' : 'BLOCKER',
         where,
+        resolved_root: where.length ? [...whereRoots].join(', ') : null,
         note: where.length
-          ? `Symbol resolves in ${where.length === 5 ? '5+' : where.length} file(s).`
-          : `Plan references \`${sym}\` but it is not defined anywhere in the scanned code roots (${CODE_ROOTS.join(', ')}) — verify the name or add the missing implementation to scope.`,
+          ? `Symbol resolves in ${where.length === 5 ? '5+' : where.length} file(s) under the ${[...whereRoots].join(', ')}.`
+          : `Plan references \`${sym}\` but it is not defined anywhere in the scanned code roots (${CODE_ROOTS.join(', ')}) under ${describeRoots(roots)} — verify the name or add the missing implementation to scope.`,
       });
     }
   }
 
-  return findings;
+  return { findings, roots };
 }
 
 /** Pass 4 — turn findings into actionable V2 patch hints. */
@@ -976,6 +1044,7 @@ export function buildQualityJudgeBrief(proposedTasks = []) {
   return lines.join('\n');
 }
 
+
 /**
  * Run the full plan review. Accepts either a `planPath` (read from disk,
  * relative to vaultRoot or absolute) or inline `planContent`. When
@@ -983,12 +1052,20 @@ export function buildQualityJudgeBrief(proposedTasks = []) {
  * synthesize review input from a draft task set. Writes a marker file keyed
  * by the sha256 of the plan content and returns the findings.
  *
+ * `codeRoot` is an optional override for the CODE checkout the pass-3 audit
+ * resolves file paths and symbols against; it defaults to `HS_PKG_ROOT` / this
+ * package's own root, with the vault root carried alongside it
+ * ({@link resolveCodeAuditRoots} —
+ * [[HS-8BHX-OUJ0-DIAG-breakdown-plan-review-resolves-code]]).
+ *
  * @returns { scope_terms, in_flight_overlap, canonical_doc, supersedes,
- *            code_audit, vocabulary_reconciliation, v2_patch_hints,
- *            review_marker_path, review_scope, quality_findings? } | { error, message }
+ *            code_audit, code_audit_roots, vocabulary_reconciliation,
+ *            v2_patch_hints, review_marker_path, review_scope,
+ *            quality_findings? } | { error, message }
  */
 export function runPlanReview({
   vaultRoot,
+  codeRoot,
   planPath,
   planContent,
   scope = 'plan',
@@ -1058,7 +1135,12 @@ export function runPlanReview({
   const scopeTerms = extractScopeTerms(analysisText);
   const candidates = loadOverlapCandidates(vaultRoot);
   const { in_flight_overlap, supersedes, canonical_doc } = runOverlapPass(analysisText, scopeTerms, candidates);
-  const code_audit = runCodeAudit(vaultRoot, scopeTerms, content);
+  const { findings: code_audit, roots: codeAuditRoots } = runCodeAudit(
+    vaultRoot,
+    scopeTerms,
+    content,
+    codeRoot,
+  );
 
   // Pass 5 — vocabulary reconciliation, scoped to the specs the overlap pass
   // already flagged (high precision). Index candidates by every id form so the
@@ -1088,6 +1170,9 @@ export function runPlanReview({
     canonical_doc,
     supersedes,
     code_audit,
+    // AC3 — say which checkouts the code audit searched, so a future wrong-root
+    // failure is readable from the output instead of guessed at.
+    code_audit_roots: codeAuditRoots.map((entry) => ({ label: entry.label, root: entry.root })),
     vocabulary_reconciliation,
     axis_b_drift: axis_b.axis_b_drift,
     axis_b_decisions_checked: axis_b.axis_b_decisions_checked,
@@ -1123,10 +1208,14 @@ export function runPlanReview({
   const reviewsDirRel = join('.heyspex', 'plan-reviews');
   const reviewsDirAbs = join(vaultRoot, reviewsDirRel);
   const markerRel = join(reviewsDirRel, `${hash}.json`);
+  const markerAbs = join(vaultRoot, markerRel);
   try {
+    // Refuse BEFORE any mkdirSync/writeFileSync — a malformed vaultRoot must
+    // create nothing on disk, not create it somewhere wrong ([[HS-MMR6]]).
+    assertPathUnderRoot(vaultRoot, markerAbs, 'plan-review marker write');
     if (!existsSync(reviewsDirAbs)) mkdirSync(reviewsDirAbs, { recursive: true });
     const marker = { ...result, plan_content_sha256: hash, reviewed_marker: true };
-    writeFileSync(join(vaultRoot, markerRel), JSON.stringify(marker, null, 2), 'utf8');
+    writeFileSync(markerAbs, JSON.stringify(marker, null, 2), 'utf8');
     result.review_marker_path = markerRel.replace(/\\/g, '/');
   } catch (err) {
     // Marker write failure is surfaced but doesn't drop the findings — the
@@ -1405,9 +1494,14 @@ export function runPlanQc({
     axis_b_user_confirmed: userConfirmed && axisB.axis_b_drift.length > 0,
     axis_b_confirmation_note: userConfirmed && confirmationNote ? confirmationNote : undefined,
   };
+  const qcMarkerAbs = join(vaultRoot, markerRel);
   try {
+    // Refuse BEFORE any mkdirSync/writeFileSync -- same guard, same reason as
+    // the plan-review marker write above ([[HS-MMR6]]): a malformed vaultRoot
+    // must create nothing on disk, not create it somewhere wrong.
+    assertPathUnderRoot(vaultRoot, qcMarkerAbs, 'plan-review marker write');
     if (!existsSync(qcDirAbs)) mkdirSync(qcDirAbs, { recursive: true });
-    writeFileSync(join(vaultRoot, markerRel), JSON.stringify(marker, null, 2), 'utf8');
+    writeFileSync(qcMarkerAbs, JSON.stringify(marker, null, 2), 'utf8');
     return {
       qc_marker_path: markerRel.replace(/\\/g, '/'),
       plan_content_sha256: hash,

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

@@ -0,0 +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,
+  });
+}