heyspex 0.2.5 → 0.2.7

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

@@ -1,523 +1,523 @@
-// heyspex_recall_memories and the memory-scoring helpers that the preflight,
-// on-deck brief and claim tools also use (tag ranking, amendment detection,
-// design-decision memories). Extracted from cli.mjs under
-// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
-//
-// ─────────────────────────────────────────────────────────────────────────────
-// Memory scorer for runtime injection ([[HS-TASK-IMMF]]).
-// Shared by enrichOnDeckWithRecalledMemories + handleRunPreflight so /hs-next
-// and heyspex_preflight surface the same top-K memories. Tag-overlap scoring
-// with a baseline pool ensures rule-placement-class memories (the kind missed
-// in the IMMF incident) always rank as candidates.
-// ─────────────────────────────────────────────────────────────────────────────
-
-import { consoleReadErrorFrom, readViaSelector, resolveReadTier } from './read-path.mjs';
-import { consoleFetch } from './console-transport.mjs';
-import { join, relative } from 'node:path';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { parseFrontmatter } from './vault-io.mjs';
-import { effectiveConsoleUrl } from './mcp-config.mjs';
-import { InvalidListCursorError, LIST_SPEC_TOOLS, finishPagedListToolResult, pageListToolResult, paginateRowsKeyset, resolvePageLimit } from './list-tools.mjs';
-
-/**
- * Page + byte-budget the recall result ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).
- * Sort key is the memory's `name` with `id` as the tie-breaker — the same
- * name order recall has always used, now as a keyset cursor. Never a total
- * count: the response says what it returned and where the next page starts.
- */
-function finishRecallPage(memories, args, filtersApplied) {
-  const paged = pageListToolResult('heyspex_recall_memories', memories, args, {
-    keyOf: (m) => m.name,
-    idOf: (m) => m.id,
-    extra: { filters_applied: filtersApplied },
-  });
-  if (paged.error) {
-    return { isError: true, content: [{ type: 'text', text: JSON.stringify(paged.error, null, 2) }] };
-  }
-  return { content: [{ type: 'text', text: paged.text }] };
-}
-
-// UI-related tags that trigger design context injection
-export const UI_TAGS = new Set(['ui', 'console', 'companion', 'design-system']);
-
-// Key design decisions to enforce (spec basename → requirements)
-export const DESIGN_DECISIONS = {
-  'scrollbar-transparent-track': {
-    summary: 'Use <ScrollArea> for ALL scrollable areas, not native overflow',
-    checklist: [
-      'Search for overflow, overflowY, maxHeight — each needs ScrollArea',
-      'Import ScrollArea from @/components/scroll-area',
-    ],
-  },
-  'supabase-design-system-reference': {
-    summary: 'Use CSS variables from globals.css, not hardcoded colors',
-    checklist: [
-      'Use --bg-canvas, --text-primary, etc. from globals.css',
-      'No #fff, #000, or other hex colors in TSX files',
-    ],
-  },
-  'quick-panel-visual-language-windows11-alignment': {
-    summary: 'Square corners, 2px borders, mint accents for overlays',
-    checklist: [
-      'No borderRadius or rounded-* classes',
-      'Use 2px solid borders, not 1px',
-    ],
-  },
-  'console-agent-quick-start-box-styling': {
-    summary: 'Blue/green callout variants with documented tokens',
-    checklist: [
-      'Use #60a5fa (blue-400) or emerald variants for callouts',
-      'Apply color-mix for background tints',
-    ],
-  },
-};
-
-/**
- * Check if a spec has UI-related tags that should trigger design context.
- * @param {Object} frontmatter - Parsed frontmatter
- * @returns {string[]} - Array of matched UI tags
- */
-export function detectUITags(frontmatter) {
-  const tags = frontmatter.tags || [];
-  return tags.filter(tag => UI_TAGS.has(tag.toLowerCase()));
-}
-
-/**
- * Load design-related memories from the vault based on tags.
- *
- * Untouched — see {@link loadDesignMemoriesViaTier} below for the cloud-tier
- * sibling ([[HS-DJWP-MCPC-TASK]] round 2, best-effort wiring).
- *
- * @param {string} vaultRoot - Root of the vault
- * @param {string[]} triggerTags - UI tags that triggered this lookup
- * @returns {Array<{id: string, summary: string, checklist: string[]}>}
- */
-export function loadDesignMemories(vaultRoot, triggerTags) {
-  const memories = [];
-  const scanDirs = [
-    join(vaultRoot, 'specs', 'memory', 'decisions'),
-    join(vaultRoot, 'specs', 'memory', 'ui-patterns'),
-  ];
-
-  for (const memoryDir of scanDirs) {
-    if (!existsSync(memoryDir)) continue;
-
-    try {
-      const files = readdirSync(memoryDir).filter(f => f.endsWith('.md'));
-
-      for (const file of files) {
-        const basename = file.replace('.md', '');
-
-        // Check if this is a known design decision
-        if (DESIGN_DECISIONS[basename]) {
-          memories.push({
-            id: basename,
-            ...DESIGN_DECISIONS[basename],
-          });
-          continue;
-        }
-
-        // Or check file tags for ui/design-system
-        const filepath = join(memoryDir, file);
-        try {
-          const content = readFileSync(filepath, 'utf8');
-          const { frontmatter } = parseFrontmatter(content);
-          const fileTags = (frontmatter.tags || []).map(t => t.toLowerCase());
-
-          // Include if file has any of our trigger tags
-          const hasUITag = fileTags.some(t => UI_TAGS.has(t));
-          if (hasUITag) {
-            // Extract summary from body
-            const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
-            const summary = lines[0]?.slice(0, 200) || frontmatter.name || basename;
-
-            memories.push({
-              id: basename,
-              summary,
-              checklist: [],
-            });
-          }
-        } catch {
-          // Skip files that can't be parsed
-        }
-      }
-    } catch {
-      // Skip if directory can't be read
-    }
-  }
-
-  return memories;
-}
-
-/**
- * Recover the slug `DESIGN_DECISIONS` is keyed by from a `MemoryDoc.id`
- * ([[HS-DJWP-MCPC-TASK]] round 2 best-effort wiring). `GET /api/memories`
- * has no basename field, but the modern memory-doc id convention is
- * `HS-<TYPE>-<slug>` (e.g. `HS-DEC-scrollbar-transparent-track`, `TYPE` being
- * the 2-4 letter memory-kind code) — the slug is byte-identical to the
- * file's basename in every checked case. Stripping that prefix recovers the
- * DESIGN_DECISIONS key. A handful of legacy memory docs predate this
- * convention (their `id:` is a bare slug with no `HS-` prefix, sometimes
- * drifted from the current filename/dict key entirely) — those simply miss
- * the exact-key lookup and fall through to the tag-overlap branch below,
- * same as disk tier's own fallback for anything not in DESIGN_DECISIONS.
- */
-/** The tool-error code for a console page that was a permission verdict, not a memory set. */
-export const VAULT_SCOPE_UNAUTHORIZED = 'VAULT_SCOPE_UNAUTHORIZED';
-
-/**
- * The denial reason carried by a `GET /api/memories` page the console could
- * NOT authorize — `{ memories: [], vaultScope: { authorized: false, reason } }`
- * — or `null` for a normal page ([[HS-FIA6-WW9R-TASK-reads-never-answer-empty-from-an]]
- * for [[HS-W3JF-PEGM-DIAG-one-account-wide-active-vault-pointer]] fix 4).
- * That page is a verdict about the CALLER's vault scope, not about the vault's
- * contents: during the 2026-10-10 incident `heyspex_recall_memories` rendered
- * it as "no memories" for an hour while the console was answering from the
- * wrong vault. Pure; `body` may be anything the transport parsed.
- * @param {unknown} body
- * @returns {string | null}
- */
-export function unauthorizedVaultScopeReason(body) {
-  const vaultScope = body && typeof body === 'object' ? body.vaultScope : null;
-  if (!vaultScope || typeof vaultScope !== 'object' || vaultScope.authorized !== false) return null;
-  return typeof vaultScope.reason === 'string' && vaultScope.reason ? vaultScope.reason : 'unknown';
-}
-
-/**
- * The `isError` tool result for an unauthorized page, or `null` when the page
- * is a real memory set (same shape `search-specs.mjs` answers for its empty
- * unauthorized page). Pure.
- * @param {unknown} body
- * @param {string} tool the MCP tool name, for the agent's error text
- */
-export function unauthorizedVaultScopeResult(body, tool) {
-  const reason = unauthorizedVaultScopeReason(body);
-  if (reason === null) return null;
-  return {
-    isError: true,
-    content: [{
-      type: 'text',
-      text: JSON.stringify({
-        error: VAULT_SCOPE_UNAUTHORIZED,
-        tool,
-        reason,
-        message:
-          `The console could not authorize a vault for this caller (${reason}), so the empty page it `
-          + 'returned says nothing about the vault\'s memories. Do NOT read this as "no memories". '
-          + 'Check that this repo\'s vault is registered and that the request named it '
-          + '(`x-heyspex-vault-id`); `hs connect --check` shows the binding.',
-      }, null, 2),
-    }],
-  };
-}
-
-export function designDecisionKeyFromMemoryDocId(id) {
-  const trimmed = typeof id === 'string' ? id.trim() : '';
-  return trimmed.replace(/^HS-[A-Z0-9]+-/, '') || trimmed;
-}
-
-/**
- * Cloud-reliant sibling of `loadDesignMemories`
- * ([[HS-DJWP-MCPC-TASK]] round 2, best-effort per the coordinator's
- * instruction to check whether `id`/`name` can serve as the DESIGN_DECISIONS
- * key). `loadDesignMemories` stays untouched (the `diskRead` branch).
- *
- * In `neon` tier: `GET /api/memories?category=decisions` +
- * `?category=ui-patterns` (the same two dirs the disk scan walks), then per
- * doc — exact DESIGN_DECISIONS hit via {@link designDecisionKeyFromMemoryDocId},
- * else the same UI_TAGS tag-overlap fallback the disk path uses (using the
- * console's own `summary` — already body-derived — rather than replicating
- * disk tier's frontmatter-adjacent `content.split('\n')[0]` heuristic, which
- * this task does not attempt to reproduce byte-for-byte since nothing tests
- * its exact text).
- */
-export async function loadDesignMemoriesViaTier(vaultRoot, triggerTags, { tier, consoleUrl }) {
-  return readViaSelector({
-    tier,
-    diskRead: () => loadDesignMemories(vaultRoot, triggerTags),
-    neonRead: async () => {
-      const [decisionsRes, patternsRes] = await Promise.all([
-        consoleFetch('/api/memories?category=decisions'),
-        consoleFetch('/api/memories?category=ui-patterns'),
-      ]);
-      if (!decisionsRes.ok) {
-        throw consoleReadErrorFrom(decisionsRes, `GET /api/memories?category=decisions returned ${decisionsRes.status}: ${decisionsRes.error || ''}`, null);
-      }
-      if (!patternsRes.ok) {
-        throw consoleReadErrorFrom(patternsRes, `GET /api/memories?category=ui-patterns returned ${patternsRes.status}: ${patternsRes.error || ''}`, null);
-      }
-      // An unauthorized empty page is a scope verdict, not "no design
-      // memories" — fail the same way a non-OK status does ([[HS-FIA6]]).
-      for (const [label, res] of [['decisions', decisionsRes], ['ui-patterns', patternsRes]]) {
-        const reason = unauthorizedVaultScopeReason(res.body);
-        if (reason !== null) {
-          throw new Error(`GET /api/memories?category=${label} answered an unauthorized empty page (${VAULT_SCOPE_UNAUTHORIZED}: ${reason})`);
-        }
-      }
-      const docs = [
-        ...(Array.isArray(decisionsRes.body?.memories) ? decisionsRes.body.memories : []),
-        ...(Array.isArray(patternsRes.body?.memories) ? patternsRes.body.memories : []),
-      ];
-
-      const memories = [];
-      for (const doc of docs) {
-        const key = designDecisionKeyFromMemoryDocId(doc.id);
-        if (DESIGN_DECISIONS[key]) {
-          memories.push({ id: key, ...DESIGN_DECISIONS[key] });
-          continue;
-        }
-        const tags = (Array.isArray(doc.tags) ? doc.tags : []).map((t) => String(t).toLowerCase());
-        if (tags.some((t) => UI_TAGS.has(t))) {
-          const summary =
-            (typeof doc.summary === 'string' && doc.summary) || doc.name || doc.id;
-          memories.push({ id: doc.id, summary, checklist: [] });
-        }
-      }
-      return memories;
-    },
-    routeLabel: 'GET /api/memories',
-    consoleUrl,
-  });
-}
-
-export function handleRecallMemories(vaultRoot, args) {
-  const { category = 'all', related_to, tags = [], compact = true } = args;
-
-  const memoryDir = join(vaultRoot, 'specs', 'memory');
-  if (!existsSync(memoryDir)) {
-    return {
-      content: [{
-        type: 'text',
-        text: JSON.stringify({
-          memories: [],
-          next_cursor: null,
-          message: 'No memories found (specs/memory/ does not exist)',
-        }, null, 2),
-      }],
-    };
-  }
-
-  // Determine which subdirectories to scan
-  const categories = category === 'all'
-    ? ['lessons', 'decisions', 'references', 'ui-patterns']
-    : [category];
-
-  const memories = [];
-
-  for (const cat of categories) {
-    const catDir = join(memoryDir, cat);
-    if (!existsSync(catDir)) continue;
-
-    const files = readdirSync(catDir).filter(f => f.endsWith('.md'));
-
-    for (const file of files) {
-      const filepath = join(catDir, file);
-      try {
-        const content = readFileSync(filepath, 'utf8');
-        const { frontmatter, body } = parseFrontmatter(content);
-
-        // Build memory entry — compact mode omits body_preview
-        const memory = {
-          id: frontmatter.id || file.replace('.md', ''),
-          name: frontmatter.name || file.replace('.md', ''),
-          type: frontmatter.type || (cat === 'ui-patterns' ? 'memory-ui-pattern' : `memory-${cat.replace(/s$/, '')}`),
-          category: cat,
-          tags: frontmatter.tags || [],
-          summary: extractSummary(body),
-        };
-
-        // Include extra fields only in non-compact mode
-        if (!compact) {
-          memory.status = frontmatter.status || 'open';
-          memory.related = frontmatter.related || [];
-          memory.filepath = relative(vaultRoot, filepath);
-          memory.body_preview = body.slice(0, 500) + (body.length > 500 ? '...' : '');
-        }
-
-        // Apply filters
-        if (related_to) {
-          const relatedIds = (frontmatter.related || []).map(r =>
-            String(r).replace(/^\[\[|\]\]$/g, '').toLowerCase()
-          );
-          if (!relatedIds.some(r => r.includes(related_to.toLowerCase()))) {
-            continue;
-          }
-        }
-
-        if (tags.length > 0) {
-          const memoryTags = (memory.tags || []).map(t => t.toLowerCase());
-          if (!tags.some(t => memoryTags.includes(t.toLowerCase()))) {
-            continue;
-          }
-        }
-
-        memories.push(memory);
-      } catch (e) {
-        // Skip files that can't be parsed
-      }
-    }
-  }
-
-  // One page (name, id keyset) under the byte budget — never the whole set.
-  return finishRecallPage(memories, args, {
-    category,
-    related_to: related_to || null,
-    tags: tags.length > 0 ? tags : null,
-    compact,
-  });
-}
-
-/**
- * Cloud-reliant sibling of `handleRecallMemories` ([[HS-DJWP-MCPC-TASK]]
- * "Memories" family, backing `heyspex_recall_memories`). `handleRecallMemories`
- * itself is left completely untouched (it is the `diskRead` branch, byte for
- * byte); in `neon` tier this answers from `GET /api/memories` instead of
- * scanning `specs/memory/**`.
- *
- * Known fidelity gap (documented, not silently dropped): the console's
- * `MemoryDoc` shape carries `{id, name, type, category, tags, summary, body}` —
- * it does not project `status` / `related` / a filesystem `filepath`, so
- * `compact: false` in `neon` tier returns those three fields as `null`/`[]`
- * instead of the real frontmatter values. `related_to` filtering is therefore
- * also unavailable over HTTP today (degrades to "no match" rather than
- * silently ignoring the filter) — extending `MemoryDoc` to carry `related`
- * would need a spex-console edit, out of scope for this task.
- *
- * Two-fetch shape ([[HS-LKV0-FUU4-DIAG-cloud-mode-recall-times-out-the]]): the
- * first `GET /api/memories` call gets the DEFAULT summary-only listing (no
- * `body`) — filtering + sorting run on tags/name, which never need body text.
- * Only AFTER slicing to the handful actually being returned (`effectiveLimit`,
- * capped at 30) does a second call fetch bodies, narrowed to exactly those ids
- * via `?ids=...&fields=body`. This is what keeps recall off the console's full
- * 896-doc body scan while still returning full fidelity (real `summary`
- * fallback + `body_preview`) for every doc it hands back — never a degraded
- * body on a returned doc.
- */
-export async function handleRecallMemoriesViaTier(vaultRoot, args) {
-  const tier = await resolveReadTier();
-  return readViaSelector({
-    tier,
-    diskRead: () => handleRecallMemories(vaultRoot, args),
-    neonRead: async () => {
-      const { category = 'all', related_to, tags = [], compact = true } = args;
-
-      const qs = new URLSearchParams();
-      if (category && category !== 'all') qs.set('category', category);
-      const path = `/api/memories${qs.toString() ? `?${qs}` : ''}`;
-      const res = await consoleFetch(path);
-      if (!res.ok) {
-        throw consoleReadErrorFrom(res, `GET ${path} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
-      }
-      // A 200 whose `vaultScope.authorized` is false is a permission verdict,
-      // never an empty memory set ([[HS-FIA6-WW9R-TASK-reads-never-answer-empty-from-an]]).
-      const unauthorized = unauthorizedVaultScopeResult(res.body, 'heyspex_recall_memories');
-      if (unauthorized) return unauthorized;
-      let docs = Array.isArray(res.body?.memories) ? res.body.memories : [];
-
-      // `related_to` cannot be honored over HTTP (MemoryDoc carries no
-      // `related` field) — documented gap above; a caller relying on it in
-      // cloud reliance gets zero results rather than a silently-ignored filter.
-      if (related_to) docs = [];
-
-      if (tags.length > 0) {
-        const wanted = tags.map((t) => String(t).toLowerCase());
-        docs = docs.filter((d) => {
-          const memoryTags = (Array.isArray(d.tags) ? d.tags : []).map((t) => String(t).toLowerCase());
-          return wanted.some((t) => memoryTags.includes(t));
-        });
-      }
-
-      // Page on tags/name ONLY — no body needed yet — so the body fetch below
-      // touches exactly the docs being returned. Same `(name, id)` keyset
-      // cursor as the disk path ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]);
-      // the byte-budget fit runs once bodies are attached, below.
-      const pageLimit = resolvePageLimit(args.limit, LIST_SPEC_TOOLS.heyspex_recall_memories);
-      let firstPage;
-      try {
-        firstPage = paginateRowsKeyset(docs, {
-          limit: pageLimit,
-          after: args.after,
-          keyOf: (d) => String(d.name ?? ''),
-          idOf: (d) => String(d.id ?? ''),
-        });
-      } catch (err) {
-        if (err instanceof InvalidListCursorError) {
-          return {
-            isError: true,
-            content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_CURSOR', message: err.message, tool: 'heyspex_recall_memories' }, null, 2) }],
-          };
-        }
-        throw err;
-      }
-      const limitedDocs = firstPage.rows;
-
-      const bodyById = new Map();
-      if (limitedDocs.length > 0) {
-        const idsQs = new URLSearchParams({
-          ids: limitedDocs.map((d) => d.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 : [];
-        for (const bd of bodyDocs) bodyById.set(bd.id, typeof bd.body === 'string' ? bd.body : '');
-      }
-
-      const memories = limitedDocs.map((d) => {
-        const body = bodyById.get(d.id) || '';
-        const memory = {
-          id: d.id,
-          name: d.name,
-          type: d.type,
-          category: d.category,
-          tags: Array.isArray(d.tags) ? d.tags : [],
-          summary: typeof d.summary === 'string' && d.summary ? d.summary : extractSummary(body),
-        };
-        if (!compact) {
-          memory.status = null; // not carried by GET /api/memories — see doc comment above.
-          memory.related = [];
-          memory.filepath = null;
-          memory.body_preview = body.slice(0, 500) + (body.length > 500 ? '...' : '');
-        }
-        return memory;
-      });
-
-      // Already paged above (before the body fetch) — attach the page envelope
-      // and fit to the byte budget without re-paging, which would report
-      // `next_cursor: null` for a set that now fits in one page.
-      const paged = finishPagedListToolResult(
-        'heyspex_recall_memories',
-        { rows: memories, next_cursor: firstPage.next_cursor, limit: pageLimit },
-        {
-          keyOf: (m) => m.name,
-          idOf: (m) => m.id,
-          extra: {
-            filters_applied: {
-              category,
-              related_to: related_to || null,
-              tags: tags.length > 0 ? tags : null,
-              compact,
-            },
-          },
-        },
-      );
-      return { content: [{ type: 'text', text: paged.text }] };
-    },
-    routeLabel: 'GET /api/memories',
-    consoleUrl: effectiveConsoleUrl(),
-  });
-}
-
-export function extractSummary(body) {
-  // Try to extract first paragraph or first few sentences
-  const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
-  if (lines.length === 0) return '';
-
-  // Get first non-empty, non-heading line
-  const firstPara = lines[0].trim();
-  if (firstPara.length <= 200) return firstPara;
-  return firstPara.slice(0, 200) + '...';
-}
+// heyspex_recall_memories and the memory-scoring helpers that the preflight,
+// on-deck brief and claim tools also use (tag ranking, amendment detection,
+// design-decision memories). Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Memory scorer for runtime injection ([[HS-TASK-IMMF]]).
+// Shared by enrichOnDeckWithRecalledMemories + handleRunPreflight so /hs-next
+// and heyspex_preflight surface the same top-K memories. Tag-overlap scoring
+// with a baseline pool ensures rule-placement-class memories (the kind missed
+// in the IMMF incident) always rank as candidates.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { consoleReadErrorFrom, readViaSelector, resolveReadTier } from './read-path.mjs';
+import { consoleFetch } from './console-transport.mjs';
+import { join, relative } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { parseFrontmatter } from './vault-io.mjs';
+import { effectiveConsoleUrl } from './mcp-config.mjs';
+import { InvalidListCursorError, LIST_SPEC_TOOLS, finishPagedListToolResult, pageListToolResult, paginateRowsKeyset, resolvePageLimit } from './list-tools.mjs';
+
+/**
+ * Page + byte-budget the recall result ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]).
+ * Sort key is the memory's `name` with `id` as the tie-breaker — the same
+ * name order recall has always used, now as a keyset cursor. Never a total
+ * count: the response says what it returned and where the next page starts.
+ */
+function finishRecallPage(memories, args, filtersApplied) {
+  const paged = pageListToolResult('heyspex_recall_memories', memories, args, {
+    keyOf: (m) => m.name,
+    idOf: (m) => m.id,
+    extra: { filters_applied: filtersApplied },
+  });
+  if (paged.error) {
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(paged.error, null, 2) }] };
+  }
+  return { content: [{ type: 'text', text: paged.text }] };
+}
+
+// UI-related tags that trigger design context injection
+export const UI_TAGS = new Set(['ui', 'console', 'companion', 'design-system']);
+
+// Key design decisions to enforce (spec basename → requirements)
+export const DESIGN_DECISIONS = {
+  'scrollbar-transparent-track': {
+    summary: 'Use <ScrollArea> for ALL scrollable areas, not native overflow',
+    checklist: [
+      'Search for overflow, overflowY, maxHeight — each needs ScrollArea',
+      'Import ScrollArea from @/components/scroll-area',
+    ],
+  },
+  'supabase-design-system-reference': {
+    summary: 'Use CSS variables from globals.css, not hardcoded colors',
+    checklist: [
+      'Use --bg-canvas, --text-primary, etc. from globals.css',
+      'No #fff, #000, or other hex colors in TSX files',
+    ],
+  },
+  'quick-panel-visual-language-windows11-alignment': {
+    summary: 'Square corners, 2px borders, mint accents for overlays',
+    checklist: [
+      'No borderRadius or rounded-* classes',
+      'Use 2px solid borders, not 1px',
+    ],
+  },
+  'console-agent-quick-start-box-styling': {
+    summary: 'Blue/green callout variants with documented tokens',
+    checklist: [
+      'Use #60a5fa (blue-400) or emerald variants for callouts',
+      'Apply color-mix for background tints',
+    ],
+  },
+};
+
+/**
+ * Check if a spec has UI-related tags that should trigger design context.
+ * @param {Object} frontmatter - Parsed frontmatter
+ * @returns {string[]} - Array of matched UI tags
+ */
+export function detectUITags(frontmatter) {
+  const tags = frontmatter.tags || [];
+  return tags.filter(tag => UI_TAGS.has(tag.toLowerCase()));
+}
+
+/**
+ * Load design-related memories from the vault based on tags.
+ *
+ * Untouched — see {@link loadDesignMemoriesViaTier} below for the cloud-tier
+ * sibling ([[HS-DJWP-MCPC-TASK]] round 2, best-effort wiring).
+ *
+ * @param {string} vaultRoot - Root of the vault
+ * @param {string[]} triggerTags - UI tags that triggered this lookup
+ * @returns {Array<{id: string, summary: string, checklist: string[]}>}
+ */
+export function loadDesignMemories(vaultRoot, triggerTags) {
+  const memories = [];
+  const scanDirs = [
+    join(vaultRoot, 'specs', 'memory', 'decisions'),
+    join(vaultRoot, 'specs', 'memory', 'ui-patterns'),
+  ];
+
+  for (const memoryDir of scanDirs) {
+    if (!existsSync(memoryDir)) continue;
+
+    try {
+      const files = readdirSync(memoryDir).filter(f => f.endsWith('.md'));
+
+      for (const file of files) {
+        const basename = file.replace('.md', '');
+
+        // Check if this is a known design decision
+        if (DESIGN_DECISIONS[basename]) {
+          memories.push({
+            id: basename,
+            ...DESIGN_DECISIONS[basename],
+          });
+          continue;
+        }
+
+        // Or check file tags for ui/design-system
+        const filepath = join(memoryDir, file);
+        try {
+          const content = readFileSync(filepath, 'utf8');
+          const { frontmatter } = parseFrontmatter(content);
+          const fileTags = (frontmatter.tags || []).map(t => t.toLowerCase());
+
+          // Include if file has any of our trigger tags
+          const hasUITag = fileTags.some(t => UI_TAGS.has(t));
+          if (hasUITag) {
+            // Extract summary from body
+            const lines = content.split('\n').filter(l => l.trim() && !l.startsWith('#') && !l.startsWith('---'));
+            const summary = lines[0]?.slice(0, 200) || frontmatter.name || basename;
+
+            memories.push({
+              id: basename,
+              summary,
+              checklist: [],
+            });
+          }
+        } catch {
+          // Skip files that can't be parsed
+        }
+      }
+    } catch {
+      // Skip if directory can't be read
+    }
+  }
+
+  return memories;
+}
+
+/**
+ * Recover the slug `DESIGN_DECISIONS` is keyed by from a `MemoryDoc.id`
+ * ([[HS-DJWP-MCPC-TASK]] round 2 best-effort wiring). `GET /api/memories`
+ * has no basename field, but the modern memory-doc id convention is
+ * `HS-<TYPE>-<slug>` (e.g. `HS-DEC-scrollbar-transparent-track`, `TYPE` being
+ * the 2-4 letter memory-kind code) — the slug is byte-identical to the
+ * file's basename in every checked case. Stripping that prefix recovers the
+ * DESIGN_DECISIONS key. A handful of legacy memory docs predate this
+ * convention (their `id:` is a bare slug with no `HS-` prefix, sometimes
+ * drifted from the current filename/dict key entirely) — those simply miss
+ * the exact-key lookup and fall through to the tag-overlap branch below,
+ * same as disk tier's own fallback for anything not in DESIGN_DECISIONS.
+ */
+/** The tool-error code for a console page that was a permission verdict, not a memory set. */
+export const VAULT_SCOPE_UNAUTHORIZED = 'VAULT_SCOPE_UNAUTHORIZED';
+
+/**
+ * The denial reason carried by a `GET /api/memories` page the console could
+ * NOT authorize — `{ memories: [], vaultScope: { authorized: false, reason } }`
+ * — or `null` for a normal page ([[HS-FIA6-WW9R-TASK-reads-never-answer-empty-from-an]]
+ * for [[HS-W3JF-PEGM-DIAG-one-account-wide-active-vault-pointer]] fix 4).
+ * That page is a verdict about the CALLER's vault scope, not about the vault's
+ * contents: during the 2026-10-10 incident `heyspex_recall_memories` rendered
+ * it as "no memories" for an hour while the console was answering from the
+ * wrong vault. Pure; `body` may be anything the transport parsed.
+ * @param {unknown} body
+ * @returns {string | null}
+ */
+export function unauthorizedVaultScopeReason(body) {
+  const vaultScope = body && typeof body === 'object' ? body.vaultScope : null;
+  if (!vaultScope || typeof vaultScope !== 'object' || vaultScope.authorized !== false) return null;
+  return typeof vaultScope.reason === 'string' && vaultScope.reason ? vaultScope.reason : 'unknown';
+}
+
+/**
+ * The `isError` tool result for an unauthorized page, or `null` when the page
+ * is a real memory set (same shape `search-specs.mjs` answers for its empty
+ * unauthorized page). Pure.
+ * @param {unknown} body
+ * @param {string} tool the MCP tool name, for the agent's error text
+ */
+export function unauthorizedVaultScopeResult(body, tool) {
+  const reason = unauthorizedVaultScopeReason(body);
+  if (reason === null) return null;
+  return {
+    isError: true,
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        error: VAULT_SCOPE_UNAUTHORIZED,
+        tool,
+        reason,
+        message:
+          `The console could not authorize a vault for this caller (${reason}), so the empty page it `
+          + 'returned says nothing about the vault\'s memories. Do NOT read this as "no memories". '
+          + 'Check that this repo\'s vault is registered and that the request named it '
+          + '(`x-heyspex-vault-id`); `hs connect --check` shows the binding.',
+      }, null, 2),
+    }],
+  };
+}
+
+export function designDecisionKeyFromMemoryDocId(id) {
+  const trimmed = typeof id === 'string' ? id.trim() : '';
+  return trimmed.replace(/^HS-[A-Z0-9]+-/, '') || trimmed;
+}
+
+/**
+ * Cloud-reliant sibling of `loadDesignMemories`
+ * ([[HS-DJWP-MCPC-TASK]] round 2, best-effort per the coordinator's
+ * instruction to check whether `id`/`name` can serve as the DESIGN_DECISIONS
+ * key). `loadDesignMemories` stays untouched (the `diskRead` branch).
+ *
+ * In `neon` tier: `GET /api/memories?category=decisions` +
+ * `?category=ui-patterns` (the same two dirs the disk scan walks), then per
+ * doc — exact DESIGN_DECISIONS hit via {@link designDecisionKeyFromMemoryDocId},
+ * else the same UI_TAGS tag-overlap fallback the disk path uses (using the
+ * console's own `summary` — already body-derived — rather than replicating
+ * disk tier's frontmatter-adjacent `content.split('\n')[0]` heuristic, which
+ * this task does not attempt to reproduce byte-for-byte since nothing tests
+ * its exact text).
+ */
+export async function loadDesignMemoriesViaTier(vaultRoot, triggerTags, { tier, consoleUrl }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => loadDesignMemories(vaultRoot, triggerTags),
+    neonRead: async () => {
+      const [decisionsRes, patternsRes] = await Promise.all([
+        consoleFetch('/api/memories?category=decisions'),
+        consoleFetch('/api/memories?category=ui-patterns'),
+      ]);
+      if (!decisionsRes.ok) {
+        throw consoleReadErrorFrom(decisionsRes, `GET /api/memories?category=decisions returned ${decisionsRes.status}: ${decisionsRes.error || ''}`, null);
+      }
+      if (!patternsRes.ok) {
+        throw consoleReadErrorFrom(patternsRes, `GET /api/memories?category=ui-patterns returned ${patternsRes.status}: ${patternsRes.error || ''}`, null);
+      }
+      // An unauthorized empty page is a scope verdict, not "no design
+      // memories" — fail the same way a non-OK status does ([[HS-FIA6]]).
+      for (const [label, res] of [['decisions', decisionsRes], ['ui-patterns', patternsRes]]) {
+        const reason = unauthorizedVaultScopeReason(res.body);
+        if (reason !== null) {
+          throw new Error(`GET /api/memories?category=${label} answered an unauthorized empty page (${VAULT_SCOPE_UNAUTHORIZED}: ${reason})`);
+        }
+      }
+      const docs = [
+        ...(Array.isArray(decisionsRes.body?.memories) ? decisionsRes.body.memories : []),
+        ...(Array.isArray(patternsRes.body?.memories) ? patternsRes.body.memories : []),
+      ];
+
+      const memories = [];
+      for (const doc of docs) {
+        const key = designDecisionKeyFromMemoryDocId(doc.id);
+        if (DESIGN_DECISIONS[key]) {
+          memories.push({ id: key, ...DESIGN_DECISIONS[key] });
+          continue;
+        }
+        const tags = (Array.isArray(doc.tags) ? doc.tags : []).map((t) => String(t).toLowerCase());
+        if (tags.some((t) => UI_TAGS.has(t))) {
+          const summary =
+            (typeof doc.summary === 'string' && doc.summary) || doc.name || doc.id;
+          memories.push({ id: doc.id, summary, checklist: [] });
+        }
+      }
+      return memories;
+    },
+    routeLabel: 'GET /api/memories',
+    consoleUrl,
+  });
+}
+
+export function handleRecallMemories(vaultRoot, args) {
+  const { category = 'all', related_to, tags = [], compact = true } = args;
+
+  const memoryDir = join(vaultRoot, 'specs', 'memory');
+  if (!existsSync(memoryDir)) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          memories: [],
+          next_cursor: null,
+          message: 'No memories found (specs/memory/ does not exist)',
+        }, null, 2),
+      }],
+    };
+  }
+
+  // Determine which subdirectories to scan
+  const categories = category === 'all'
+    ? ['lessons', 'decisions', 'references', 'ui-patterns']
+    : [category];
+
+  const memories = [];
+
+  for (const cat of categories) {
+    const catDir = join(memoryDir, cat);
+    if (!existsSync(catDir)) continue;
+
+    const files = readdirSync(catDir).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      const filepath = join(catDir, file);
+      try {
+        const content = readFileSync(filepath, 'utf8');
+        const { frontmatter, body } = parseFrontmatter(content);
+
+        // Build memory entry — compact mode omits body_preview
+        const memory = {
+          id: frontmatter.id || file.replace('.md', ''),
+          name: frontmatter.name || file.replace('.md', ''),
+          type: frontmatter.type || (cat === 'ui-patterns' ? 'memory-ui-pattern' : `memory-${cat.replace(/s$/, '')}`),
+          category: cat,
+          tags: frontmatter.tags || [],
+          summary: extractSummary(body),
+        };
+
+        // Include extra fields only in non-compact mode
+        if (!compact) {
+          memory.status = frontmatter.status || 'open';
+          memory.related = frontmatter.related || [];
+          memory.filepath = relative(vaultRoot, filepath);
+          memory.body_preview = body.slice(0, 500) + (body.length > 500 ? '...' : '');
+        }
+
+        // Apply filters
+        if (related_to) {
+          const relatedIds = (frontmatter.related || []).map(r =>
+            String(r).replace(/^\[\[|\]\]$/g, '').toLowerCase()
+          );
+          if (!relatedIds.some(r => r.includes(related_to.toLowerCase()))) {
+            continue;
+          }
+        }
+
+        if (tags.length > 0) {
+          const memoryTags = (memory.tags || []).map(t => t.toLowerCase());
+          if (!tags.some(t => memoryTags.includes(t.toLowerCase()))) {
+            continue;
+          }
+        }
+
+        memories.push(memory);
+      } catch (e) {
+        // Skip files that can't be parsed
+      }
+    }
+  }
+
+  // One page (name, id keyset) under the byte budget — never the whole set.
+  return finishRecallPage(memories, args, {
+    category,
+    related_to: related_to || null,
+    tags: tags.length > 0 ? tags : null,
+    compact,
+  });
+}
+
+/**
+ * Cloud-reliant sibling of `handleRecallMemories` ([[HS-DJWP-MCPC-TASK]]
+ * "Memories" family, backing `heyspex_recall_memories`). `handleRecallMemories`
+ * itself is left completely untouched (it is the `diskRead` branch, byte for
+ * byte); in `neon` tier this answers from `GET /api/memories` instead of
+ * scanning `specs/memory/**`.
+ *
+ * Known fidelity gap (documented, not silently dropped): the console's
+ * `MemoryDoc` shape carries `{id, name, type, category, tags, summary, body}` —
+ * it does not project `status` / `related` / a filesystem `filepath`, so
+ * `compact: false` in `neon` tier returns those three fields as `null`/`[]`
+ * instead of the real frontmatter values. `related_to` filtering is therefore
+ * also unavailable over HTTP today (degrades to "no match" rather than
+ * silently ignoring the filter) — extending `MemoryDoc` to carry `related`
+ * would need a spex-console edit, out of scope for this task.
+ *
+ * Two-fetch shape ([[HS-LKV0-FUU4-DIAG-cloud-mode-recall-times-out-the]]): the
+ * first `GET /api/memories` call gets the DEFAULT summary-only listing (no
+ * `body`) — filtering + sorting run on tags/name, which never need body text.
+ * Only AFTER slicing to the handful actually being returned (`effectiveLimit`,
+ * capped at 30) does a second call fetch bodies, narrowed to exactly those ids
+ * via `?ids=...&fields=body`. This is what keeps recall off the console's full
+ * 896-doc body scan while still returning full fidelity (real `summary`
+ * fallback + `body_preview`) for every doc it hands back — never a degraded
+ * body on a returned doc.
+ */
+export async function handleRecallMemoriesViaTier(vaultRoot, args) {
+  const tier = await resolveReadTier();
+  return readViaSelector({
+    tier,
+    diskRead: () => handleRecallMemories(vaultRoot, args),
+    neonRead: async () => {
+      const { category = 'all', related_to, tags = [], compact = true } = args;
+
+      const qs = new URLSearchParams();
+      if (category && category !== 'all') qs.set('category', category);
+      const path = `/api/memories${qs.toString() ? `?${qs}` : ''}`;
+      const res = await consoleFetch(path);
+      if (!res.ok) {
+        throw consoleReadErrorFrom(res, `GET ${path} returned ${res.status}: ${res.error || JSON.stringify(res.body ?? {})}`, null);
+      }
+      // A 200 whose `vaultScope.authorized` is false is a permission verdict,
+      // never an empty memory set ([[HS-FIA6-WW9R-TASK-reads-never-answer-empty-from-an]]).
+      const unauthorized = unauthorizedVaultScopeResult(res.body, 'heyspex_recall_memories');
+      if (unauthorized) return unauthorized;
+      let docs = Array.isArray(res.body?.memories) ? res.body.memories : [];
+
+      // `related_to` cannot be honored over HTTP (MemoryDoc carries no
+      // `related` field) — documented gap above; a caller relying on it in
+      // cloud reliance gets zero results rather than a silently-ignored filter.
+      if (related_to) docs = [];
+
+      if (tags.length > 0) {
+        const wanted = tags.map((t) => String(t).toLowerCase());
+        docs = docs.filter((d) => {
+          const memoryTags = (Array.isArray(d.tags) ? d.tags : []).map((t) => String(t).toLowerCase());
+          return wanted.some((t) => memoryTags.includes(t));
+        });
+      }
+
+      // Page on tags/name ONLY — no body needed yet — so the body fetch below
+      // touches exactly the docs being returned. Same `(name, id)` keyset
+      // cursor as the disk path ([[HS-E66W-8KK5-TASK-mcp-list-tools-page-with-a-cursor-and-a]]);
+      // the byte-budget fit runs once bodies are attached, below.
+      const pageLimit = resolvePageLimit(args.limit, LIST_SPEC_TOOLS.heyspex_recall_memories);
+      let firstPage;
+      try {
+        firstPage = paginateRowsKeyset(docs, {
+          limit: pageLimit,
+          after: args.after,
+          keyOf: (d) => String(d.name ?? ''),
+          idOf: (d) => String(d.id ?? ''),
+        });
+      } catch (err) {
+        if (err instanceof InvalidListCursorError) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_CURSOR', message: err.message, tool: 'heyspex_recall_memories' }, null, 2) }],
+          };
+        }
+        throw err;
+      }
+      const limitedDocs = firstPage.rows;
+
+      const bodyById = new Map();
+      if (limitedDocs.length > 0) {
+        const idsQs = new URLSearchParams({
+          ids: limitedDocs.map((d) => d.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 : [];
+        for (const bd of bodyDocs) bodyById.set(bd.id, typeof bd.body === 'string' ? bd.body : '');
+      }
+
+      const memories = limitedDocs.map((d) => {
+        const body = bodyById.get(d.id) || '';
+        const memory = {
+          id: d.id,
+          name: d.name,
+          type: d.type,
+          category: d.category,
+          tags: Array.isArray(d.tags) ? d.tags : [],
+          summary: typeof d.summary === 'string' && d.summary ? d.summary : extractSummary(body),
+        };
+        if (!compact) {
+          memory.status = null; // not carried by GET /api/memories — see doc comment above.
+          memory.related = [];
+          memory.filepath = null;
+          memory.body_preview = body.slice(0, 500) + (body.length > 500 ? '...' : '');
+        }
+        return memory;
+      });
+
+      // Already paged above (before the body fetch) — attach the page envelope
+      // and fit to the byte budget without re-paging, which would report
+      // `next_cursor: null` for a set that now fits in one page.
+      const paged = finishPagedListToolResult(
+        'heyspex_recall_memories',
+        { rows: memories, next_cursor: firstPage.next_cursor, limit: pageLimit },
+        {
+          keyOf: (m) => m.name,
+          idOf: (m) => m.id,
+          extra: {
+            filters_applied: {
+              category,
+              related_to: related_to || null,
+              tags: tags.length > 0 ? tags : null,
+              compact,
+            },
+          },
+        },
+      );
+      return { content: [{ type: 'text', text: paged.text }] };
+    },
+    routeLabel: 'GET /api/memories',
+    consoleUrl: effectiveConsoleUrl(),
+  });
+}
+
+export function extractSummary(body) {
+  // Try to extract first paragraph or first few sentences
+  const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
+  if (lines.length === 0) return '';
+
+  // Get first non-empty, non-heading line
+  const firstPara = lines[0].trim();
+  if (firstPara.length <= 200) return firstPara;
+  return firstPara.slice(0, 200) + '...';
+}