heyspex 0.1.0

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

@@ -0,0 +1,2001 @@
+/**
+ * Pre-plan grounding for HeySpex MCP (/hs-ground).
+ * Holistic vault scan, north-star/pillar hooks, architecture placement,
+ * stress-test prompts, enhancement seeds — read-only.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, relative, basename } from 'node:path';
+import {
+  analyzeGroundingConflicts,
+  computeSafeContextSpecs,
+} from './plan-ground-conflicts.mjs';
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'for', 'to', 'in', 'on', 'at', 'of', 'with',
+  'is', 'are', 'was', 'were', 'be', 'this', 'that', 'it', 'as', 'from', 'by',
+  'add', 'new', 'use', 'using', 'via', 'into', 'when', 'how', 'what', 'which',
+]);
+
+const ANCHOR_SPECS = [
+  { basename: 'heyspex-north-star', why: 'L1 vision / constitution' },
+  { basename: 'architecture-pillars', why: 'L2 pillars and milestones (M2–M5)' },
+  { basename: 'entity-model', why: 'Entity schema and vault layout' },
+  { basename: 'plan-ingest-agent-workflow', why: 'Plan filing workflow before push', subdir: 'protocols' },
+  { basename: 'mcp-slash-surface-protocol', why: 'MCP + slash command parity', subdir: 'protocols' },
+  // next-session-handoff.md retired (HS-EPIC-HNDR) — current session resume state is the
+  // WIP ledger (.heyspex/wip-state.json, surfaced in the /hs-next brief), not a markdown anchor.
+];
+
+const SCAN_DIRS = [
+  { rel: 'specs/epics', bucket: 'epics' },
+  { rel: 'specs/tasks', bucket: 'tasks' },
+  { rel: 'specs/protocols', bucket: 'protocols' },
+  { rel: 'specs/adr', bucket: 'adrs' },
+  { rel: 'specs/use-cases', bucket: 'use_cases' },
+  { rel: 'specs/memory', bucket: 'memories' },
+  { rel: 'specs/research', bucket: 'research' },
+  // Captures hold the owner's not-yet-specced design vocabulary (e.g. named
+  // operating modes). Excluding them was the [[HS-RES-2QX6]] root cause: a
+  // pre-plan ground that could not surface [[HS-CAP-UIBF]] let an agent reinvent
+  // an already-designed concept. Milestones + diagnoses round out the in-flight
+  // surfaces a plan can collide with (mirrors plan-review.mjs OVERLAP_DIRS).
+  { rel: 'specs/captures', bucket: 'captures' },
+  { rel: 'specs/milestones', bucket: 'milestones' },
+  { rel: 'specs/diagnoses', bucket: 'diagnoses' },
+  { rel: 'specs/future-considerations', bucket: 'future_considerations' },
+];
+
+const AREA_BOOSTS = {
+  console: { paths: ['spex-console/'], tags: ['console', 'ui', 'cockpit'], surfaces: ['console'] }, // legacy-cockpit tag accepted
+  companion: { paths: ['companion/'], tags: ['companion', 'windows'], surfaces: ['companion'] },
+  mcp: { paths: ['vendor/heyspex-mcp/'], tags: ['mcp', 'slash'], surfaces: ['mcp'] },
+  vault: { paths: ['specs/'], tags: ['vault', 'specs'], surfaces: ['vault'] },
+  indexer: { paths: ['spex-console/src/lib/indexer/'], tags: ['indexer', 'm2'], surfaces: ['indexer'] },
+};
+
+const PILLAR_HINTS = [
+  { id: 'M2', label: 'Indexer MVP', keywords: ['indexer', 'postgres', 'sqlite', 'index', 'm2'] },
+  { id: 'M3', label: 'Console MVP', keywords: ['console', 'surface', 'm3'] },
+  { id: 'M4', label: 'hs CLI / MCP', keywords: ['cli', 'mcp', 'heyspex_', 'slash', 'm4'] },
+  { id: 'M5', label: 'Sync mesh', keywords: ['sync', 'phone', 'mesh', 'capture', 'm5'] },
+];
+
+const STRESS_TEST_PROMPTS = [
+  'Is this the best you can do? What would a stronger v2 include? What should be cut?',
+  'What acceptance criteria are missing or untestable?',
+  'What edge cases, non-goals, rollback, and operator docs are missing?',
+  'Does this duplicate open epics or tasks already in the vault?',
+  'Do behavioral claims conflict with linked protocol specs?',
+  'Which memory-lessons or decisions constrain this work?',
+  'Is this in-scope for current milestones, or should it be deferred to horizon?',
+];
+
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.heyspex',
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TF-IDF Search Index (BM25 + Backlinks + Recency)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// ## Algorithm Overview (HS-EPIC-74YP)
+//
+// This module implements a Google-like relevance ranking system for the HeySpex
+// spec vault, combining multiple signals into a weighted score:
+//
+// ### Signal 1: BM25 TF-IDF (primary signal, weight: 3.0)
+// - Industry-standard document retrieval algorithm (Okapi BM25)
+// - Rare terms score higher than common terms via IDF (inverse document frequency)
+// - Term frequency saturates to prevent keyword stuffing
+// - Document length normalization prevents long docs from dominating
+//
+// ### Signal 2: Title Match Boost (weight: 2.0)
+// - Full phrase match in title: 10 points
+// - All terms present (any order): 5 points
+// - Partial term matches: 2 points each
+//
+// ### Signal 3: Tag Matching (weight: 1.5)
+// - Explicit tag match: 5 points (user-specified tags in search)
+// - Query term in spec tag: 3 points (implicit matching)
+//
+// ### Signal 4: Area/Surface Match (weight: 1.0)
+// - Boosts specs in relevant code areas (console, companion, mcp, vault, indexer)
+// - Matches by file path or spec tags
+//
+// ### Signal 5: Status Boost (weight: 0.8)
+// - in_progress: 2.0 (actively worked on)
+// - open: 1.5 (actionable)
+// - in_review: 1.0 (pending completion)
+// - closed: 0 (completed, less relevant for planning)
+//
+// ### Signal 6: Backlink Importance (weight: 1.2)
+// - Specs with more inbound wikilinks are more "authoritative"
+// - Uses log scale: log1p(count), capped at 3
+// - Prevents heavily-linked specs from dominating while still boosting them
+//
+// ### Signal 7: Recency (weight: 0.6)
+// - Recently updated specs are more relevant for planning
+// - Decay tiers: <7d=2, <30d=1.5, <90d=1, <365d=0.5, older=0
+//
+// ### Formula
+//   Score = (BM25 × 3.0) + (title × 2.0) + (tag × 1.5) + (area × 1.0)
+//         + (status × 0.8) + (backlink × 1.2) + (recency × 0.6)
+//
+// ### Tuning
+// - Weights chosen empirically to balance precision vs recall
+// - tfidf is primary signal (3.0) because it captures semantic relevance
+// - title gets 2.0 because explicit matches are high confidence
+// - status/recency are lower (0.6-0.8) as tiebreakers, not primary filters
+//
+// See: [[hs-ground-search-algorithm]] for design decision documentation
+// Tests: vendor/heyspex-mcp/plan-ground.test.mjs (64 unit tests)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Lazy index singleton with cache invalidation */
+let cachedIndex = null;
+let cacheTimestamp = 0;
+let cachedVaultRoot = null;
+const CACHE_TTL_MS = 30_000; // 30 seconds
+
+/**
+ * Scoring weights for combining relevance signals.
+ *
+ * These weights were tuned empirically to balance:
+ * - tfidf (3.0): Primary signal for semantic relevance
+ * - title (2.0): High-confidence explicit matches
+ * - tag (1.5): User-defined categorization
+ * - area (1.0): Code area relevance
+ * - status (0.8): Prioritize actionable specs
+ * - backlink (1.2): Graph-based importance
+ * - recency (0.6): Time decay as tiebreaker
+ *
+ * @see [[hs-ground-search-algorithm]] for rationale
+ */
+const SCORE_WEIGHTS = {
+  tfidf: 3.0,      // BM25 contribution (primary signal)
+  title: 2.0,      // Title match boost
+  tag: 1.5,        // Tag match
+  area: 1.0,       // Area/surface match
+  status: 0.8,     // Status boost
+  backlink: 1.2,   // Graph importance
+  recency: 0.6,    // Time decay
+};
+
+/**
+ * BM25 algorithm parameters.
+ *
+ * k1 (1.5): Term frequency saturation parameter
+ * - Controls how quickly TF contribution saturates
+ * - Range: 1.2-2.0 typical; 1.5 is a balanced default
+ * - Higher = TF matters more; lower = saturates faster
+ *
+ * b (0.75): Document length normalization parameter
+ * - Controls how much long documents are penalized
+ * - Range: 0.0-1.0; 0.75 is the standard default
+ * - Higher = more normalization; 0 = no length penalty
+ *
+ * These are the Robertson/Walker defaults from the original BM25 paper.
+ */
+const BM25_K1 = 1.5;  // Term frequency saturation
+const BM25_B = 0.75;  // Document length normalization
+
+/**
+ * Build the in-memory search index over all specs.
+ * Computes: corpus stats, term frequencies, backlink graph, recency data.
+ */
+function buildVaultIndex(vaultRoot) {
+  const startMs = Date.now();
+  const specs = new Map();
+  const corpus = {
+    totalDocs: 0,
+    documentFrequency: new Map(),
+    avgDocLength: 0,
+  };
+  const backlinkGraph = new Map(); // target -> Set<source>
+
+  // Phase 1: Parse all specs, extract tokens and links
+  const specsRoot = join(vaultRoot, 'specs');
+  const allFiles = walkMdFiles(specsRoot);
+  let totalLength = 0;
+
+  for (const filePath of allFiles) {
+    try {
+      const content = readFileSync(filePath, 'utf8');
+      const { frontmatter, body } = parseFrontmatter(content);
+      const fileBase = basename(filePath, '.md');
+      const key = fileBase.toLowerCase();
+
+      const titleTokens = tokenize(frontmatter.name || fileBase);
+      const bodyTokens = tokenize(body);
+      const allTokens = [...titleTokens, ...bodyTokens];
+
+      // Build term frequency map
+      const termFrequency = new Map();
+      for (const token of allTokens) {
+        termFrequency.set(token, (termFrequency.get(token) || 0) + 1);
+      }
+
+      // Extract wikilinks for backlink graph
+      const outgoingLinks = extractWikilinks(body, frontmatter);
+      for (const target of outgoingLinks) {
+        const normalized = target.toLowerCase();
+        if (!backlinkGraph.has(normalized)) {
+          backlinkGraph.set(normalized, new Set());
+        }
+        backlinkGraph.get(normalized).add(key);
+      }
+
+      // Parse timestamps
+      const updatedAt = parseIsoDate(frontmatter.updated);
+      const createdAt = parseIsoDate(frontmatter.created);
+
+      specs.set(key, {
+        basename: fileBase,
+        id: frontmatter.id || fileBase,
+        name: frontmatter.name || fileBase,
+        type: frontmatter.type || 'unknown',
+        status: String(frontmatter.status || 'open').toLowerCase(),
+        tags: normalizeTags(frontmatter.tags),
+        // Authored frontmatter.summary, carried so candidate cards can prefer it
+        // over the body-derived extractSummaryLine() fallback (authored wins).
+        summary: typeof frontmatter.summary === 'string' ? frontmatter.summary : null,
+        relPath: relative(vaultRoot, filePath).replace(/\\/g, '/'),
+        titleTokens,
+        termFrequency,
+        docLength: allTokens.length,
+        backlinkCount: 0, // computed in phase 3
+        forwardRefCount: outgoingLinks.size,
+        updatedAt,
+        createdAt,
+      });
+
+      corpus.totalDocs++;
+      totalLength += allTokens.length;
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  corpus.avgDocLength = corpus.totalDocs > 0 ? totalLength / corpus.totalDocs : 0;
+
+  // Phase 2: Compute document frequency (IDF denominator)
+  for (const spec of specs.values()) {
+    const uniqueTerms = new Set(spec.termFrequency.keys());
+    for (const term of uniqueTerms) {
+      corpus.documentFrequency.set(
+        term,
+        (corpus.documentFrequency.get(term) || 0) + 1
+      );
+    }
+  }
+
+  // Phase 3: Compute backlink counts
+  for (const spec of specs.values()) {
+    const key = spec.basename.toLowerCase();
+    const sources = backlinkGraph.get(key);
+    spec.backlinkCount = sources ? sources.size : 0;
+  }
+
+  const buildTimeMs = Date.now() - startMs;
+
+  return {
+    corpus,
+    specs,
+    backlinkGraph,
+    lastBuilt: Date.now(),
+    buildTimeMs,
+  };
+}
+
+/**
+ * Get or rebuild the cached index.
+ */
+function getOrBuildIndex(vaultRoot) {
+  const now = Date.now();
+  // Invalidate on vaultRoot change as well as TTL: a single process is normally
+  // one vault, but the cache must not hand back a different root's index (would
+  // silently mis-resolve, and makes the substrate untestable across vaults).
+  if (cachedIndex && cachedVaultRoot === vaultRoot && (now - cacheTimestamp) < CACHE_TTL_MS) {
+    return cachedIndex;
+  }
+  cachedIndex = buildVaultIndex(vaultRoot);
+  cacheTimestamp = now;
+  cachedVaultRoot = vaultRoot;
+  return cachedIndex;
+}
+
+/**
+ * Extract wikilinks from body text and frontmatter.
+ */
+function extractWikilinks(body, frontmatter) {
+  const links = new Set();
+
+  // Body wikilinks: [[target]] or [[target|display]]
+  const regex = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+  let match;
+  while ((match = regex.exec(body)) !== null) {
+    const target = match[1].trim().toLowerCase().replace(/\.md$/, '');
+    if (target) links.add(target);
+  }
+
+  // Frontmatter links: parent, children, related, blocks, etc.
+  // `milestone` (epic → parent milestone) and `epics` (milestone → child epics)
+  // are the bidirectional milestone↔epic edge ([[HS-EPIC-MILE]]); including them
+  // makes those edges visible to the backlink graph and broken-`HS-MIL-*`-link
+  // detection, the same way parent/children cover the epic↔task edge.
+  const linkFields = ['parent', 'children', 'related', 'blocks', 'blocked_by', 'discovered_from', 'milestone', 'epics'];
+  for (const field of linkFields) {
+    const val = frontmatter[field];
+    if (Array.isArray(val)) {
+      for (const v of val) {
+        const normalized = normalizeWikilinkTarget(v);
+        if (normalized) links.add(normalized);
+      }
+    } else if (typeof val === 'string') {
+      const normalized = normalizeWikilinkTarget(val);
+      if (normalized) links.add(normalized);
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Normalize a wikilink target string.
+ */
+function normalizeWikilinkTarget(link) {
+  if (!link) return null;
+  return link
+    .replace(/^\[\[|\]\]$/g, '')
+    .split('|')[0]
+    .trim()
+    .toLowerCase()
+    .replace(/\.md$/, '');
+}
+
+/**
+ * Parse ISO date string to timestamp.
+ */
+function parseIsoDate(dateStr) {
+  if (!dateStr) return 0;
+  const d = new Date(dateStr);
+  return isNaN(d.getTime()) ? 0 : d.getTime();
+}
+
+/**
+ * BM25 scoring - industry standard for document retrieval.
+ * k1 controls term frequency saturation (1.2-2.0 typical)
+ * b controls document length normalization (0.75 typical)
+ */
+function computeBM25(queryTerms, spec, corpus) {
+  let score = 0;
+  const { avgDocLength, totalDocs, documentFrequency } = corpus;
+
+  for (const term of queryTerms) {
+    const tf = spec.termFrequency.get(term) || 0;
+    if (tf === 0) continue;
+
+    const df = documentFrequency.get(term) || 0;
+    // IDF with smoothing to handle rare terms
+    const idf = Math.log((totalDocs - df + 0.5) / (df + 0.5) + 1);
+
+    // Length-normalized term frequency
+    const lengthNorm = 1 - BM25_B + BM25_B * (spec.docLength / (avgDocLength || 1));
+    const tfNorm = (tf * (BM25_K1 + 1)) / (tf + BM25_K1 * lengthNorm);
+
+    score += idf * tfNorm;
+  }
+
+  return score;
+}
+
+/**
+ * Title match boost - phrase and term matching.
+ */
+function computeTitleBoost(queryTerms, spec) {
+  const titleLower = spec.name.toLowerCase();
+  const fullQuery = queryTerms.join(' ');
+
+  // Full phrase match (highest)
+  if (titleLower.includes(fullQuery) && fullQuery.length > 3) return 10;
+
+  // All terms present (any order)
+  const presentCount = queryTerms.filter((t) => titleLower.includes(t)).length;
+  if (presentCount === queryTerms.length && queryTerms.length > 0) return 5;
+
+  // Partial match
+  return presentCount * 2;
+}
+
+/**
+ * Backlink importance - specs linked by many others are more authoritative.
+ * Uses log scale to prevent runaway scores.
+ */
+function computeBacklinkScore(spec) {
+  const count = spec.backlinkCount;
+  if (count === 0) return 0;
+  // log1p handles 0 gracefully: 1 link ~= 0.69, 5 ~= 1.79, 10 ~= 2.40, 30 ~= 3.43
+  return Math.min(Math.log1p(count), 3);
+}
+
+/**
+ * Recency score - recently updated specs are more relevant.
+ * Decay function: full score for last 7 days, decays over 90 days.
+ */
+function computeRecencyScore(spec, now) {
+  if (!spec.updatedAt) return 0;
+  const ageMs = now - spec.updatedAt;
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+
+  if (ageDays < 7) return 2;      // Last week: full boost
+  if (ageDays < 30) return 1.5;   // Last month: high boost
+  if (ageDays < 90) return 1;     // Last quarter: moderate
+  if (ageDays < 365) return 0.5;  // Last year: low
+  return 0;                        // Older: no boost
+}
+
+/**
+ * Status boost - open/in_progress work is more relevant for planning.
+ */
+function computeStatusBoost(status) {
+  switch (status.toLowerCase()) {
+    case 'in_progress': return 2;
+    case 'open': return 1.5;
+    case 'in_review': return 1;
+    case 'closed': return 0;
+    default: return 0.5;
+  }
+}
+
+/**
+ * Tag matching - exact tag matches are high signal.
+ */
+function computeTagScore(queryTerms, explicitTags, spec) {
+  let score = 0;
+
+  // Explicit tag matches (highest weight)
+  for (const tag of explicitTags) {
+    if (spec.tags.includes(tag.toLowerCase())) {
+      score += 5;
+    }
+  }
+
+  // Query term matches tag
+  for (const term of queryTerms) {
+    if (spec.tags.some((t) => t.includes(term))) {
+      score += 3;
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Area/surface matching.
+ */
+function computeAreaScore(areas, spec) {
+  let score = 0;
+  const pathLower = spec.relPath.toLowerCase();
+
+  for (const area of areas) {
+    const boost = AREA_BOOSTS[area];
+    if (!boost) continue;
+    if (boost.paths.some((p) => pathLower.includes(p)) || boost.tags.some((t) => spec.tags.includes(t))) {
+      score += 2;
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Enhanced scoreSpec using TF-IDF index.
+ * Returns combined score with all factors.
+ */
+function scoreSpecWithIndex(queryTokens, explicitTags, areas, spec, corpus) {
+  const now = Date.now();
+  const reasons = [];
+
+  // Component scores
+  const bm25 = computeBM25(queryTokens, spec, corpus);
+  const titleBoost = computeTitleBoost(queryTokens, spec);
+  const tagScore = computeTagScore(queryTokens, explicitTags, spec);
+  const areaScore = computeAreaScore(areas, spec);
+  const statusBoost = computeStatusBoost(spec.status);
+  const backlinkScore = computeBacklinkScore(spec);
+  const recencyScore = computeRecencyScore(spec, now);
+
+  // Build reasons for debugging/display
+  if (bm25 > 0.5) reasons.push(`tfidf:${bm25.toFixed(1)}`);
+  if (titleBoost >= 5) reasons.push(`title:${titleBoost}`);
+  if (tagScore > 0) reasons.push(`tag:${tagScore}`);
+  if (backlinkScore > 1) reasons.push(`links:${spec.backlinkCount}`);
+  if (recencyScore > 1) reasons.push('recent');
+  if (areaScore > 0) reasons.push(`area`);
+
+  // Weighted combination
+  const score =
+    (bm25 * SCORE_WEIGHTS.tfidf) +
+    (titleBoost * SCORE_WEIGHTS.title) +
+    (tagScore * SCORE_WEIGHTS.tag) +
+    (areaScore * SCORE_WEIGHTS.area) +
+    (statusBoost * SCORE_WEIGHTS.status) +
+    (backlinkScore * SCORE_WEIGHTS.backlink) +
+    (recencyScore * SCORE_WEIGHTS.recency);
+
+  return {
+    score,
+    reasons,
+    bm25,
+    titleBoost,
+    tagScore,
+    areaScore,
+    statusBoost,
+    backlinkScore,
+    recencyScore,
+  };
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { frontmatter: {}, body: content };
+  const yamlBlock = match[1];
+  const body = content.slice(match[0].length).trim();
+  return { frontmatter: parseSimpleYaml(yamlBlock), body };
+}
+
+function parseSimpleYaml(yaml) {
+  const result = {};
+  const lines = yaml.split(/\r?\n/);
+  let currentArray = null;
+  // Block-scalar collection state (`key: |` / `key: >`). The vast majority of
+  // authored `summary:` values in this vault are literal block scalars, so the
+  // brief consumer must read them as strings — not drop them — to agree with the
+  // index consumer (which uses a real YAML parser). [[HS-TASK-ECOI]]
+  let blockKey = null;
+  let blockLines = null;
+  let blockFold = false;
+
+  const flushBlock = () => {
+    if (blockKey === null) return;
+    // Strip the common leading indentation of the block's content lines, then
+    // join: literal (`|`) keeps line breaks; folded (`>`) joins with spaces.
+    const contentful = blockLines.filter((l) => l.trim() !== '');
+    const minIndent = contentful.length
+      ? Math.min(...contentful.map((l) => l.match(/^(\s*)/)[1].length))
+      : 0;
+    const stripped = blockLines.map((l) => l.slice(minIndent));
+    result[blockKey] = blockFold
+      ? stripped.map((l) => l.trim()).filter(Boolean).join(' ')
+      : stripped.join('\n').replace(/\n+$/, '');
+    blockKey = null;
+    blockLines = null;
+    blockFold = false;
+  };
+
+  for (const line of lines) {
+    if (blockKey !== null) {
+      // Blank or indented lines belong to the active block scalar; a line at the
+      // key column (non-indented, non-blank) ends it and is parsed normally.
+      if (line.trim() === '' || /^\s/.test(line)) {
+        blockLines.push(line);
+        continue;
+      }
+      flushBlock();
+    }
+
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const arrayItemMatch = line.match(/^(\s+)-\s*(.*)$/);
+    if (arrayItemMatch && currentArray) {
+      const value = arrayItemMatch[2].trim().replace(/^["']|["']$/g, '');
+      currentArray.push(value);
+      continue;
+    }
+
+    const keyMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
+    if (keyMatch) {
+      const key = keyMatch[1];
+      const value = keyMatch[2].trim();
+      currentArray = null;
+
+      if (/^[|>][-+\d]*$/.test(value)) {
+        // Block scalar: `|`, `>`, or a header variant (`|-`, `>+`, `|2`, …).
+        blockKey = key;
+        blockLines = [];
+        blockFold = value.startsWith('>');
+        result[key] = '';
+      } else if (value === '') {
+        result[key] = [];
+        currentArray = result[key];
+      } else if (value.startsWith('[') && value.endsWith(']')) {
+        result[key] = value.slice(1, -1).split(',').map((s) => s.trim().replace(/^["']|["']$/g, ''));
+      } else {
+        result[key] = value.replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+  flushBlock();
+  return result;
+}
+
+function tokenize(text) {
+  if (!text) return [];
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .split(/\s+/)
+    .filter((t) => t.length > 2 && !STOPWORDS.has(t));
+}
+
+function walkMdFiles(dir, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkMdFiles(full, out);
+    else if (entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+function resolveSpecPath(vaultRoot, anchor) {
+  const specsRoot = join(vaultRoot, 'specs');
+  const candidates = [
+    join(specsRoot, `${anchor.basename}.md`),
+    anchor.subdir ? join(specsRoot, anchor.subdir, `${anchor.basename}.md`) : null,
+  ].filter(Boolean);
+
+  for (const p of candidates) {
+    if (existsSync(p)) return relative(vaultRoot, p).replace(/\\/g, '/');
+  }
+
+  const all = walkMdFiles(specsRoot);
+  const found = all.find((f) => basename(f, '.md') === anchor.basename);
+  return found ? relative(vaultRoot, found).replace(/\\/g, '/') : null;
+}
+
+function normalizeTags(tags) {
+  if (!tags) return [];
+  if (Array.isArray(tags)) return tags.map((t) => String(t).toLowerCase());
+  return [String(tags).toLowerCase()];
+}
+
+/**
+ * Score a spec using the TF-IDF index if available, otherwise fall back to simple scoring.
+ * This function bridges the old API (file-based) with the new index-based scoring.
+ */
+function scoreSpec(filePath, content, tokens, explicitTags, areas, index = null) {
+  const fileBase = basename(filePath, '.md');
+  const key = fileBase.toLowerCase();
+
+  // If we have an index, use enhanced TF-IDF scoring
+  if (index && index.specs.has(key)) {
+    const spec = index.specs.get(key);
+    const result = scoreSpecWithIndex(tokens, explicitTags, areas, spec, index.corpus);
+
+    return {
+      score: result.score,
+      reason: result.reasons.slice(0, 4).join(', ') || 'low relevance',
+      frontmatter: {
+        id: spec.id,
+        name: spec.name,
+        type: spec.type,
+        status: spec.status,
+        tags: spec.tags,
+        summary: spec.summary ?? null,
+      },
+      basename: spec.basename,
+      status: spec.status,
+      // Extra debug info for index-based scoring
+      _indexed: true,
+      _backlinkCount: spec.backlinkCount,
+      _bm25: result.bm25,
+    };
+  }
+
+  // Fallback: simple scoring for unindexed files (should be rare)
+  const { frontmatter, body } = parseFrontmatter(content);
+  const name = String(frontmatter.name || frontmatter.title || fileBase).toLowerCase();
+  const specTags = normalizeTags(frontmatter.tags);
+  const status = String(frontmatter.status || 'open').toLowerCase();
+
+  let score = 0;
+  const reasons = [];
+
+  for (const tok of tokens) {
+    if (name.includes(tok)) {
+      score += 2;
+      reasons.push(`title:${tok}`);
+    }
+    const bodyHits = (body.toLowerCase().match(new RegExp(`\\b${tok}\\b`, 'g')) || []).length;
+    if (bodyHits > 0) {
+      score += Math.min(bodyHits, 3);
+      reasons.push(`body:${tok}`);
+    }
+  }
+
+  for (const tag of explicitTags) {
+    if (specTags.includes(tag.toLowerCase())) {
+      score += 3;
+      reasons.push(`tag:${tag}`);
+    }
+  }
+
+  for (const area of areas) {
+    const boost = AREA_BOOSTS[area];
+    if (!boost) continue;
+    const pathLower = filePath.replace(/\\/g, '/').toLowerCase();
+    if (boost.paths.some((p) => pathLower.includes(p)) || boost.tags.some((t) => specTags.includes(t))) {
+      score += 2;
+      reasons.push(`area:${area}`);
+    }
+  }
+
+  if (status === 'open' || status === 'in_progress') {
+    score += 1;
+  }
+
+  return {
+    score,
+    reason: reasons.slice(0, 4).join(', ') || 'low relevance',
+    frontmatter,
+    basename: fileBase,
+    status,
+    _indexed: false,
+  };
+}
+
+function detectPillars(text) {
+  const lower = text.toLowerCase();
+  return PILLAR_HINTS.filter((p) => p.keywords.some((k) => lower.includes(k))).map((p) => p.id);
+}
+
+function detectSurfaces(text, areas) {
+  const surfaces = new Set();
+  for (const area of areas) {
+    const b = AREA_BOOSTS[area];
+    if (b) b.surfaces.forEach((s) => surfaces.add(s));
+  }
+  const lower = text.toLowerCase();
+  if (lower.includes('console')) surfaces.add('console');
+  if (lower.includes('companion')) surfaces.add('companion');
+  if (lower.includes('mcp') || lower.includes('slash')) surfaces.add('mcp');
+  if (lower.includes('vault') || lower.includes('spec')) surfaces.add('vault');
+  if (lower.includes('indexer')) surfaces.add('indexer');
+  return [...surfaces];
+}
+
+function findLargeMarkdownFiles(vaultRoot, limit = 8) {
+  const roots = [vaultRoot];
+  const large = [];
+
+  for (const root of roots) {
+    if (!existsSync(root)) continue;
+    const files = walkMdFiles(root);
+    for (const f of files) {
+      if (f.includes('node_modules')) continue;
+      try {
+        const content = readFileSync(f, 'utf8');
+        const lines = content.split(/\r?\n/).length;
+        if (lines >= 500) {
+          large.push({
+            path: relative(vaultRoot, f).replace(/\\/g, '/'),
+            lines,
+          });
+        }
+      } catch {
+        /* skip */
+      }
+    }
+  }
+
+  return large.sort((a, b) => b.lines - a.lines).slice(0, limit);
+}
+
+function buildCodebaseHints(topic, summary, areas, tokens) {
+  const queries = [...new Set([...tokens.slice(0, 6), topic].filter(Boolean))];
+  const globs = new Set();
+
+  for (const area of areas) {
+    const b = AREA_BOOSTS[area];
+    if (b) b.paths.forEach((p) => globs.add(`${p}**`));
+  }
+
+  if (queries.length === 0) queries.push('heyspex');
+
+  return {
+    grep_queries: queries.slice(0, 8),
+    path_globs: [...globs].length ? [...globs] : ['specs/**', 'spex-console/src/**', 'vendor/heyspex-mcp/**'],
+  };
+}
+
+function guessManifestPhase(vaultRoot, tokens) {
+  const roadmapPath = join(vaultRoot, 'specs/roadmaps/HS-ROADMAP-product-master.md');
+  if (!existsSync(roadmapPath) || tokens.length === 0) return null;
+
+  try {
+    const content = readFileSync(roadmapPath, 'utf8').toLowerCase();
+    const phases = content.match(/phase[_\s-]*id[:\s]+["']?(P\d+)/gi) || [];
+    if (phases.length === 0) return 'See [[HS-ROADMAP-product-master]] — agent should read manifest';
+    for (const tok of tokens) {
+      if (content.includes(tok)) return 'Match found in product roadmap — read manifest for phase';
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function buildPlanContextSection(topic, landscape, hooks, placement, suggestedRelated, conflictAnalysis) {
+  const lines = [
+    '## Grounding',
+    '',
+    '### Landscape',
+    '',
+  ];
+
+  if (landscape.open_work.length) {
+    lines.push('**Open work:**');
+    for (const item of landscape.open_work.slice(0, 8)) {
+      lines.push(`- [[${item.basename}]] — ${item.reason}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('### North-star and pillars', '');
+  lines.push(`- Review [[heyspex-north-star]] for L1 alignment on: **${topic}**`);
+  if (hooks.pillar_ids.length) {
+    lines.push(`- Pillars touched: ${hooks.pillar_ids.join(', ')} — read [[architecture-foundations]]`);
+  }
+  if (hooks.alignment_risks.length) {
+    for (const r of hooks.alignment_risks) lines.push(`- ⚠ ${r}`);
+  }
+  lines.push('');
+
+  lines.push('### Architecture placement', '');
+  if (placement.surfaces.length) {
+    lines.push(`- Surfaces: ${placement.surfaces.join(', ')}`);
+  }
+  if (placement.dependency_specs.length) {
+    lines.push('- Dependencies:');
+    for (const d of placement.dependency_specs.slice(0, 6)) {
+      lines.push(`  - [[${d}]]`);
+    }
+  }
+  if (placement.manifest_phase_hint) {
+    lines.push(`- Roadmap: ${placement.manifest_phase_hint}`);
+  }
+  lines.push('');
+
+  lines.push('### Conflicts and source of truth', '');
+  if (conflictAnalysis?.conflict_count > 0) {
+    lines.push(`- **${conflictAnalysis.conflict_count} conflict(s)/drift** — resolve before treating specs as authoritative.`);
+    for (const c of conflictAnalysis.conflicts.slice(0, 5)) {
+      lines.push(`- [[${c.spec_b}]] vs ${c.spec_a}: ${c.epic_claim} ⟂ ${c.spec_claim}`);
+      lines.push(`  - Recommended authority: **${c.recommended_source_of_truth}** — ${c.rationale}`);
+    }
+    if (conflictAnalysis.conflicts.length > 5) {
+      lines.push(`- …and ${conflictAnalysis.conflicts.length - 5} more (see tool \`conflict_analysis\`)`);
+    }
+    lines.push(`- Resolve: ${conflictAnalysis.resolve_commands.join(' · ')}`);
+  } else {
+    lines.push('- No behavioral conflicts detected among draft, focused epic, and top protocols.');
+  }
+  lines.push('');
+
+  lines.push('### Stress-test notes', '');
+  lines.push('- Complete adversarial review before push (see `/hs-ground` Phase 4).');
+  lines.push('');
+
+  lines.push('### Related (safe for context)', '');
+  const safe = conflictAnalysis?.safe_context_specs || suggestedRelated;
+  for (const r of safe.slice(0, 15)) {
+    lines.push(`- [[${r}]]`);
+  }
+  if (conflictAnalysis?.conflicted_spec_basenames?.length) {
+    lines.push('');
+    lines.push('**Do not cite as authoritative until resolved:**');
+    for (const b of conflictAnalysis.conflicted_spec_basenames.slice(0, 10)) {
+      lines.push(`- [[${b}]]`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function buildOptimizedOutline(topic) {
+  return [
+    `## Goal`,
+    '',
+    `${topic} — (refine after grounding)`,
+    '',
+    '## Phases',
+    '',
+    '1. **Discovery / design** — (from landscape scan)',
+    '2. **Implementation** — (code touch map from grounding)',
+    '3. **Validation** — tests, validate:vault-ids, linkage',
+    '',
+    '## Acceptance criteria',
+    '',
+    '- [ ] Aligns with [[heyspex-north-star]] and relevant pillar milestone',
+    '- [ ] Linked protocols and epics in `related:`',
+    '- [ ] (add measurable criteria from stress-test)',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Extract a one-line summary from a spec's markdown: the first meaningful prose
+ * line after the frontmatter block, with heading/callout/link syntax stripped
+ * and capped at `maxLen` chars. Used to build body-free candidate cards — the
+ * LLM triages on these, then deep-reads only the shortlist it selects
+ * ([[retrieval-intake-architecture]] §How the LLM-as-reranker works).
+ * @param {string} content
+ * @param {number} [maxLen]
+ * @returns {string}
+ */
+function extractSummaryLine(content, maxLen = 140) {
+  let body = String(content || '');
+  // Drop a leading YAML frontmatter block.
+  if (body.startsWith('---')) {
+    const close = body.indexOf('\n---', 3);
+    if (close !== -1) {
+      const nl = body.indexOf('\n', close + 1);
+      body = nl !== -1 ? body.slice(nl + 1) : '';
+    }
+  }
+  const cap = (s) => (s.length > maxLen ? `${s.slice(0, maxLen - 1).trimEnd()}…` : s);
+  let firstHeading = ''; // fallback if the doc is heading-only (title echoes anyway)
+  for (let raw of body.split('\n')) {
+    let line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith('|') || line.startsWith('<!--') || line.startsWith('---') || line.startsWith('```')) continue;
+    const isHeading = /^#{1,6}\s/.test(line);
+    line = line.replace(/^#{1,6}\s+/, ''); // de-head
+    line = line.replace(/^>+\s?/, '').replace(/^\[!\w+\][-+]?\s*/, ''); // de-callout
+    line = line.replace(/\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g, '$1'); // [[wikilink]] → text
+    line = line.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); // [md](link) → text
+    line = line.replace(/[*_`]/g, '').trim(); // strip emphasis
+    if (!line) continue;
+    // Prefer the first prose/callout line; the leading H1 usually just echoes
+    // the title, so skip headings unless that is all the doc has.
+    if (isHeading) {
+      if (!firstHeading) firstHeading = line;
+      continue;
+    }
+    return cap(line);
+  }
+  return cap(firstHeading);
+}
+
+/**
+ * @param {string} vaultRoot
+ * @param {object} args
+ */
+/**
+ * Bounded grounding report (G7R2/G7R4 contract): one capped markdown report with six
+ * sections — NOT a shopping list that tells the agent to read the vault. Reuses the
+ * already-computed lexical wide-recall + conflict data; applies hard caps and a
+ * token budget so the slash trigger ([[HS-TASK-G7R6-hs-ground-mcp-slash-thin-trigger]])
+ * can paste it verbatim. Substrate is production-lexical only — see
+ * [[retrieval-substrate-lexical-not-embeddings-gate-b-no]].
+ */
+function buildGroundReport(ctx) {
+  const SPEC_CAP = 12, CODE_CAP = 8, CONFLICT_CAP = 5, GRAPH_CAP = 8, GAP_CAP = 6;
+  const estTokens = (s) => Math.ceil(s.length / 4);
+  const {
+    topic, summary, vaultRoot, groundedAt, candidateCards, openWork, protocols,
+    decisionsToHeed, conflictAnalysis, surfaces, pillarIds, codebaseHints,
+    gapsAndQuestions, maxTokens,
+  } = ctx;
+
+  const render = (nSpecs) => {
+    const L = [];
+    L.push(`# Grounding report — ${topic}`);
+    if (summary) L.push(`> ${summary.slice(0, 200)}`);
+
+    L.push('', '## 1. Scope');
+    L.push(`- Workspace: \`${basename(vaultRoot)}\` · surfaces: ${surfaces.join(', ') || '—'} · pillars: ${pillarIds.join(', ') || '—'}`);
+    L.push(`- Index: in-memory lexical (BM25 + signals), built per call · grounded ${groundedAt}`);
+
+    L.push('', '## 2. Relevant specs');
+    L.push('_Lexical wide-recall — YOU are the reranker. Open only the shortlist you judge relevant; do not read them all._');
+    const specs = candidateCards.slice(0, nSpecs);
+    if (!specs.length) L.push('- (none matched)');
+    for (const c of specs) {
+      const why = (c.why_matched && c.why_matched[0]) || (c.summary ? c.summary.slice(0, 90) : '');
+      L.push(`- [[${c.basename}]] (${c.type}/${c.status})${why ? ` — ${why}` : ''}`);
+    }
+
+    L.push('', '## 3. Relevant code');
+    L.push('_Bounded pointers — open only what the task needs (code chunk store lands in G7R3)._');
+    const globs = (codebaseHints?.path_globs || []).slice(0, CODE_CAP);
+    if (!globs.length) L.push('- (no path hints)');
+    else for (const g of globs) L.push(`- \`${g}\``);
+
+    L.push('', '## 4. Graph hints');
+    const graph = [
+      ...protocols.slice(0, 4).map((p) => `protocol: [[${p.basename}]]`),
+      ...decisionsToHeed.slice(0, 3).map((d) => `decision/lesson: [[${d.basename}]]`),
+      ...openWork.slice(0, 3).map((e) => `open: [[${e.basename}]]`),
+    ].slice(0, GRAPH_CAP);
+    if (!graph.length) L.push('- (no graph neighbors)');
+    else for (const g of graph) L.push(`- ${g}`);
+
+    L.push('', '## 5. Conflicts');
+    if (conflictAnalysis.has_blocking_conflicts) {
+      L.push(`- ⚠ ${conflictAnalysis.conflict_count} blocking — resolve via ${conflictAnalysis.resolve_commands?.[0] || '/hs-resolve'} before using conflicted specs.`);
+      for (const c of (conflictAnalysis.conflicts || []).slice(0, CONFLICT_CAP)) {
+        const desc = c.summary || c.reason || c.message || c.kind || 'conflict';
+        L.push(`  - ${String(desc).slice(0, 140)}`);
+      }
+    } else {
+      L.push('- No blocking claim-level conflicts. NOTE: this detector is blind to design-supersession & identifier drift ([[drift-is-two-axes-as-built-and-design-supersession]]) — verify the design-vs-decision axis manually.');
+    }
+
+    L.push('', '## 6. Gaps');
+    const gaps = (gapsAndQuestions || []).slice(0, GAP_CAP);
+    if (!gaps.length) L.push('- (none flagged)');
+    else for (const g of gaps) L.push(`- ${g}`);
+
+    return L.join('\n');
+  };
+
+  // Greedy fit to the token budget: drop the least-relevant specs first (they are the
+  // longest, most expendable section) until the report fits.
+  let nSpecs = SPEC_CAP;
+  let report = render(nSpecs);
+  let truncated = false;
+  while (estTokens(report) > maxTokens && nSpecs > 3) {
+    nSpecs -= 1;
+    report = render(nSpecs);
+    truncated = true;
+  }
+  return { report_markdown: report, token_estimate: estTokens(report), truncated };
+}
+
+export function executeGroundPlan(vaultRoot, args = {}) {
+  const topic = String(args.topic || '').trim();
+  if (!topic) {
+    return { error: 'MISSING_TOPIC', message: 'topic is required (short title of feature/request)' };
+  }
+
+  const summary = String(args.summary || '').trim();
+  const explicitTags = normalizeTags(args.tags || []);
+  const areas = Array.isArray(args.areas)
+    ? args.areas.map((a) => {
+        const v = String(a).toLowerCase();
+        return v === 'cockpit' ? 'console' : v; // legacy-cockpit area alias
+      })
+    : [];
+  // Wide-recall window: the user's own LLM is the reranker, so HeySpex retrieves
+  // WIDE (Recall@N is the metric, not nDCG@10 ordering). Default 30, max 50 — per
+  // [[HS-RES-RTLR-retrieval-ab-layer1-results-and-signoff]] §4h (top-30–50 puts
+  // 70–80% of the gold in front of the LLM vs ~53–58% at top-10) and
+  // [[llm-as-reranker-lexical-recall-companion-architecture]].
+  const limit = Math.min(Math.max(Number(args.limit) || 30, 3), 50);
+  const includeCodebaseHints = args.include_codebase_hints !== false;
+  const checkConflicts = args.check_conflicts !== false;
+  // Compact mode is default — reduces response from ~17k to ~4k tokens
+  const compact = args.compact !== false;
+
+  const combinedText = `${topic} ${summary}`;
+  const tokens = [...new Set([...tokenize(topic), ...tokenize(summary)])];
+
+  // Build or retrieve cached TF-IDF index for enhanced scoring
+  const index = getOrBuildIndex(vaultRoot);
+
+  const anchors = ANCHOR_SPECS.map((a) => {
+    const path = resolveSpecPath(vaultRoot, a);
+    return {
+      basename: a.basename,
+      path: path || `specs/${a.subdir ? `${a.subdir}/` : ''}${a.basename}.md`,
+      why: a.why,
+      tier: 'anchor',
+      found: Boolean(path),
+    };
+  });
+
+  const discovered = {
+    epics: [],
+    tasks: [],
+    protocols: [],
+    adrs: [],
+    use_cases: [],
+    memories: [],
+    research: [],
+    captures: [],
+    milestones: [],
+    diagnoses: [],
+    future_considerations: [],
+  };
+
+  const scored = [];
+
+  for (const { rel, bucket } of SCAN_DIRS) {
+    const dir = join(vaultRoot, rel);
+    const files = walkMdFiles(dir);
+    for (const filePath of files) {
+      try {
+        const content = readFileSync(filePath, 'utf8');
+        const { score, reason, frontmatter, basename: fileBase, status } = scoreSpec(
+          filePath,
+          content,
+          tokens,
+          explicitTags,
+          areas,
+          index, // Pass index for TF-IDF scoring
+        );
+        if (score <= 0 && bucket !== 'memories') continue;
+
+        const entry = {
+          basename: fileBase,
+          id: frontmatter.id || fileBase,
+          name: frontmatter.name || fileBase,
+          path: relative(vaultRoot, filePath).replace(/\\/g, '/'),
+          status,
+          relevance: score,
+          reason,
+          type: frontmatter.type || bucket,
+          // Authored frontmatter.summary, carried so the candidate card can
+          // prefer it over the body-derived extractSummaryLine() fallback
+          // (same precedence as the index/brief consumers: authored wins).
+          summary: typeof frontmatter.summary === 'string' ? frontmatter.summary : null,
+        };
+
+        scored.push({ bucket, entry });
+
+        if (discovered[bucket]) {
+          discovered[bucket].push(entry);
+        }
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  }
+
+  scored.sort((a, b) => b.entry.relevance - a.entry.relevance);
+
+  for (const key of Object.keys(discovered)) {
+    discovered[key].sort((a, b) => b.relevance - a.relevance);
+    discovered[key] = discovered[key].slice(0, limit);
+  }
+
+  const topEntries = scored
+    .filter((s) => s.bucket !== 'future_considerations')
+    .slice(0, limit)
+    .map((s) => s.entry);
+
+  const anchorBasenames = anchors.filter((a) => a.found).map((a) => a.basename);
+  const suggestedRelated = [
+    ...new Set([
+      ...anchorBasenames.filter((b) => !['plan-ingest-agent-workflow'].includes(b)),
+      ...topEntries.map((e) => e.basename),
+    ]),
+  ].slice(0, 20);
+
+  // Wide-recall candidate CARDS — body-free triage rows for the LLM-as-reranker.
+  // The whole top-`limit` (30–50) window, each card carrying just enough to
+  // triage on: id/basename (to Read or [[link]]), title, type, status, a
+  // one-line summary, and the why-matched lexical signals. Bodies are NOT
+  // included — the agent deep-reads only the shortlist it selects (two-stage).
+  const candidateCards = topEntries.map((e) => {
+    // Precedence: authored frontmatter.summary wins over the body-derived
+    // extractSummaryLine() fallback, matching the index (U2) and /hs-next brief
+    // consumers so the same spec reads identically across surfaces. The body
+    // fallback is preserved byte-for-byte for specs with no authored summary.
+    let summary = e.summary && String(e.summary).trim() ? String(e.summary).trim() : '';
+    if (!summary) {
+      try {
+        summary = extractSummaryLine(readFileSync(join(vaultRoot, e.path), 'utf8'));
+      } catch {
+        /* unreadable — leave summary blank */
+      }
+    }
+    return {
+      id: e.id,
+      basename: e.basename,
+      title: e.name,
+      type: e.type,
+      status: e.status,
+      summary,
+      why_matched: e.reason ? e.reason.split(', ').filter(Boolean) : [],
+      relevance: Math.round(e.relevance * 100) / 100,
+    };
+  });
+
+  // The explicit "you are the reranker" contract that rides with the cards.
+  const candidateRerank = {
+    metric: 'Recall@N',
+    window_size: candidateCards.length,
+    you_are_the_reranker: true,
+    instruction:
+      `These ${candidateCards.length} candidate_cards are a WIDE lexical-recall window, not a ranked answer. ` +
+      'HeySpex retrieves wide and YOUR judgment is the reranker — there is no hosted reranker, vector search, or embedding model. ' +
+      'Two stages: (1) triage cheaply on the cards (id / title / summary / why_matched) and pick the shortlist that is genuinely relevant; ' +
+      '(2) deep-read ONLY that shortlist (Read those files), then act — write related:/parent links, flag duplicates, or confirm conflicts. ' +
+      'The order is lexical, not authoritative: do not assume the first card is the answer; judge each on the task in context.',
+  };
+
+  const openWork = [
+    ...discovered.epics,
+    ...discovered.tasks,
+  ]
+    .filter((e) => ['open', 'in_progress'].includes(e.status))
+    .sort((a, b) => b.relevance - a.relevance)
+    .slice(0, 10);
+
+  const possibleDuplicates = openWork.filter((e) => e.relevance >= 4).slice(0, 5);
+
+  const protocols = discovered.protocols.slice(0, 8);
+  const decisionsToHeed = discovered.memories
+    .filter((m) => m.path.includes('/decisions/') || m.path.includes('/lessons/'))
+    .slice(0, 8);
+
+  const horizonItems = discovered.future_considerations.slice(0, 5);
+
+  const pillarIds = detectPillars(combinedText);
+  const alignmentRisks = [];
+  if (possibleDuplicates.length > 0) {
+    alignmentRisks.push(
+      `Possible duplicate work: ${possibleDuplicates.map((d) => `[[${d.basename}]]`).join(', ')}`,
+    );
+  }
+  if (horizonItems.length > 0) {
+    alignmentRisks.push(
+      `Related horizon items exist — confirm in-scope vs defer: ${horizonItems.map((h) => h.basename).join(', ')}`,
+    );
+  }
+  if (pillarIds.length === 0) {
+    alignmentRisks.push('No obvious M2–M5 pillar match — confirm milestone placement in [[architecture-foundations]].');
+  }
+
+  const surfaces = detectSurfaces(combinedText, areas);
+  const dependencySpecs = [
+    ...protocols.map((p) => p.basename),
+    ...discovered.adrs.slice(0, 3).map((a) => a.basename),
+  ].slice(0, 10);
+
+  const architecturePlacement = {
+    surfaces,
+    dependency_specs: dependencySpecs,
+    manifest_phase_hint: guessManifestPhase(vaultRoot, tokens),
+  };
+
+  const northStarPillarHooks = {
+    north_star_sections: [
+      'Read [[heyspex-north-star]] — identify which L1 goals/themes this request serves or conflicts with.',
+    ],
+    pillar_ids: pillarIds,
+    alignment_risks: alignmentRisks,
+  };
+
+  const topSpecsForDrift = topEntries.map((e) => ({
+    basename: e.basename,
+    relevance: e.relevance,
+    type: e.type,
+  }));
+
+  const conflictAnalysis = checkConflicts
+    ? analyzeGroundingConflicts(vaultRoot, {
+        topic,
+        summary,
+        protocolBasenames: protocols.map((p) => p.basename),
+        topSpecs: topSpecsForDrift,
+        check_focus_epic: true,
+        // Neon layer-2 focus selection, injected at the async handler boundary
+        // ([[HS-TASK-FSEL]] residual); precedence over the dormant focus.yaml.
+        focusSpecPath: args.neon_selection_spec_path || null,
+      })
+    : {
+        has_blocking_conflicts: false,
+        conflict_count: 0,
+        conflicts: [],
+        linked_specs_checked: [],
+        focused_epic: null,
+        source_of_truth_rules: [],
+        conflicted_spec_basenames: [],
+        recommendations: [],
+        resolve_commands: ['/hs-resolve'],
+        safe_context_specs: suggestedRelated,
+      };
+
+  conflictAnalysis.safe_context_specs = computeSafeContextSpecs(
+    suggestedRelated,
+    conflictAnalysis.conflicted_spec_basenames,
+  );
+
+  const gapsAndQuestions = [
+    ...alignmentRisks,
+    ...(possibleDuplicates.length
+      ? [`Review overlapping specs: ${possibleDuplicates.map((d) => d.id || d.basename).join(', ')}`]
+      : []),
+    ...(conflictAnalysis.has_blocking_conflicts
+      ? [
+          `BLOCKER: ${conflictAnalysis.conflict_count} spec conflict(s)/drift — resolve via ${conflictAnalysis.resolve_commands[0]} before using conflicting specs as plan context.`,
+        ]
+      : []),
+    'Confirm parent epic and manifest phase before /hs-push.',
+    'Run heyspex_validate_linkage after filing (when tool available).',
+  ];
+
+  const enhancementSuggestions = [];
+  if (protocols.length === 0) {
+    enhancementSuggestions.push('Search for governing protocol specs to add to related:');
+  } else {
+    enhancementSuggestions.push(`Link protocols: ${protocols.map((p) => `[[${p.basename}]]`).join(', ')}`);
+  }
+  if (possibleDuplicates.length > 0) {
+    enhancementSuggestions.push('Merge or explicitly defer duplicate epics before filing new work.');
+  }
+  if (decisionsToHeed.length > 0) {
+    enhancementSuggestions.push(
+      `Heed memories: ${decisionsToHeed.map((d) => `[[${d.basename}]]`).join(', ')}`,
+    );
+  }
+  if (conflictAnalysis.has_blocking_conflicts) {
+    enhancementSuggestions.push(
+      'Resolve all conflicts in conflict_analysis before enhancing the plan — use safe_context_specs only until resolved.',
+    );
+  }
+  enhancementSuggestions.push('Add child tasks for each implementation phase after stress-test.');
+
+  const codebaseHints = includeCodebaseHints
+    ? {
+        ...buildCodebaseHints(topic, summary, areas, tokens),
+        large_markdown_files: findLargeMarkdownFiles(vaultRoot),
+      }
+    : { grep_queries: [], path_globs: [], large_markdown_files: [] };
+
+  const landscapeSummary = {
+    open_work: openWork.map((e) => ({ basename: e.basename, id: e.id, reason: e.reason })),
+    protocols: protocols.map((p) => ({ basename: p.basename, reason: p.reason })),
+    decisions_to_heed: decisionsToHeed.map((d) => ({ basename: d.basename, reason: d.reason })),
+    possible_duplicates: possibleDuplicates.map((d) => ({ basename: d.basename, id: d.id, reason: d.reason })),
+    horizon_items: horizonItems.map((h) => ({ basename: h.basename, reason: h.reason })),
+  };
+
+  const planContextSectionMarkdown = buildPlanContextSection(
+    topic,
+    landscapeSummary,
+    northStarPillarHooks,
+    architecturePlacement,
+    suggestedRelated,
+    conflictAnalysis,
+  );
+
+  const recallTags = [
+    ...new Set([...explicitTags, ...areas.flatMap((a) => AREA_BOOSTS[a]?.tags || [])]),
+  ].slice(0, 8);
+
+  // Bounded report mode (G7R2/G7R4/G7R6): one capped ≤max_tokens report, no read-everything
+  // scaffold. This is what /hs-ground should call. Substrate is production-lexical only.
+  if (args.report === true) {
+    const maxTokens = Math.min(Math.max(Number(args.max_tokens) || 2000, 500), 4000);
+    const groundedAt = new Date().toISOString();
+    const { report_markdown, token_estimate, truncated } = buildGroundReport({
+      topic,
+      summary,
+      vaultRoot,
+      groundedAt,
+      candidateCards,
+      openWork,
+      protocols,
+      decisionsToHeed,
+      conflictAnalysis,
+      surfaces,
+      pillarIds,
+      codebaseHints,
+      gapsAndQuestions,
+      maxTokens,
+    });
+    return {
+      topic,
+      report_markdown,
+      token_estimate,
+      max_tokens: maxTokens,
+      truncated,
+      has_blocking_conflicts: conflictAnalysis.has_blocking_conflicts,
+      conflict_count: conflictAnalysis.conflict_count,
+      safe_context_specs: (conflictAnalysis.safe_context_specs || []).slice(0, 12),
+      recall_memories_hint: { limit: 10, tags: recallTags.length ? recallTags : undefined },
+      grounded_at: groundedAt,
+      _report: true,
+    };
+  }
+
+  // Build compact or full response based on mode
+  const nextSteps = conflictAnalysis.has_blocking_conflicts
+    ? [
+        `Resolve ${conflictAnalysis.conflict_count} conflict(s) first: ${conflictAnalysis.resolve_commands.join(' · ')}`,
+        'Re-run heyspex_ground_plan after resolution.',
+        'Then complete hs-ground phases 2–6 using safe_context_specs only.',
+        'Hand off to /hs-push with aligned plan and related: (conflicts should be empty).',
+      ]
+    : [
+        'Complete all six /hs-ground phases in chat (scan → align → place → stress-test → enhance → optimize).',
+        'Call heyspex_recall_memories with suggested tags.',
+        'Triage candidate_cards (id/title/summary/why_matched) and deep-read ONLY the shortlist you select — do NOT read every discovered spec or whole large files.',
+        'Use safe_context_specs from conflict_analysis for authoritative wikilinks.',
+        'Hand off to /hs-push or /hs-push-next with optimized plan and suggested_related.',
+      ];
+
+  // Compact mode: reduce response size while preserving workflow-critical fields
+  // Main savings: discovered arrays → counts + basenames only (biggest bloat source)
+  if (compact) {
+    // Conflicts: keep full conflicts array (needed for Phase 1b resolution)
+    // but limit to top 5 to prevent explosion
+    const compactConflicts = {
+      has_blocking_conflicts: conflictAnalysis.has_blocking_conflicts,
+      conflict_count: conflictAnalysis.conflict_count,
+      conflicts: (conflictAnalysis.conflicts || []).slice(0, 5),
+      conflicted_spec_basenames: conflictAnalysis.conflicted_spec_basenames?.slice(0, 8) || [],
+      safe_context_specs: conflictAnalysis.safe_context_specs?.slice(0, 12) || [],
+      resolve_commands: conflictAnalysis.resolve_commands,
+      source_of_truth_rules: conflictAnalysis.source_of_truth_rules || [
+        'protocol > epic for behavioral claims',
+        'north-star > all for vision/constitution',
+        'epic supersedes only when explicitly noted',
+      ],
+    };
+
+    return {
+      topic,
+      summary: summary || null,
+
+      // ANCHORS: kept (small static list, workflow Phase 1 requires "read all anchors")
+      anchors: anchors.map((a) => ({ basename: a.basename, why: a.why, found: a.found })),
+
+      // DISCOVERED: counts + basenames only (main token savings)
+      discovered_counts: {
+        epics: discovered.epics.length,
+        tasks: discovered.tasks.length,
+        protocols: discovered.protocols.length,
+        memories: discovered.memories.length,
+        research: discovered.research.length,
+        adrs: discovered.adrs.length,
+        captures: discovered.captures.length,
+        milestones: discovered.milestones.length,
+        diagnoses: discovered.diagnoses.length,
+        total: Object.values(discovered).flat().length,
+      },
+
+      // Wide-recall candidate cards (Recall@N) — the agent is the reranker.
+      candidate_rerank: candidateRerank,
+      candidate_cards: candidateCards,
+
+      // Top items as wikilink basenames (agent can Read these). Now the full
+      // wide window, not a top-10 slice — the LLM does the narrowing.
+      top_specs_to_read: candidateCards.map((c) => c.basename),
+      open_work: openWork.slice(0, 6).map((e) => e.basename),
+      protocols_to_heed: protocols.slice(0, 5).map((p) => p.basename),
+      decisions_to_heed: decisionsToHeed.slice(0, 5).map((d) => d.basename),
+      possible_duplicates: possibleDuplicates.slice(0, 4).map((d) => d.basename),
+
+      // NORTH-STAR/PILLARS: kept for Phase 2
+      north_star_pillar_hooks: {
+        pillar_ids: pillarIds,
+        alignment_risks: alignmentRisks,
+        north_star_sections: ['Read [[heyspex-north-star]] for L1 alignment'],
+      },
+
+      // ARCHITECTURE PLACEMENT: kept for Phase 3
+      architecture_placement: {
+        surfaces,
+        dependency_specs: dependencySpecs.slice(0, 6),
+        manifest_phase_hint: architecturePlacement.manifest_phase_hint,
+      },
+
+      // CONFLICTS: compact but actionable for Phase 1b
+      conflict_analysis: compactConflicts,
+
+      // CODEBASE HINTS: kept for Phase 1 exploration
+      codebase_hints: includeCodebaseHints
+        ? {
+            grep_queries: codebaseHints.grep_queries?.slice(0, 5) || [],
+            path_globs: codebaseHints.path_globs?.slice(0, 4) || [],
+            large_markdown_files: (codebaseHints.large_markdown_files || []).slice(0, 5),
+          }
+        : null,
+
+      // STRESS-TEST PROMPTS: kept for Phase 4 (static list, small)
+      stress_test_prompts: STRESS_TEST_PROMPTS,
+
+      // ENHANCEMENT SUGGESTIONS: kept for Phase 5
+      enhancement_suggestions: enhancementSuggestions.slice(0, 6),
+
+      // GAPS: kept for completeness
+      gaps_and_questions: gapsAndQuestions.slice(0, 5),
+
+      // PLAN CONTEXT MARKDOWN: kept (essential for workflow)
+      plan_context_section_markdown: planContextSectionMarkdown,
+
+      // OPTIMIZED OUTLINE: kept for Phase 6
+      optimized_plan_outline: buildOptimizedOutline(topic),
+
+      // Hints for follow-up
+      recall_memories_hint: {
+        limit: 10,
+        tags: recallTags.length ? recallTags : undefined,
+      },
+      next_steps: nextSteps,
+      grounded_at: new Date().toISOString(),
+      _compact: true,
+      _note:
+        'Compact mode: discovered arrays reduced to counts+basenames. candidate_cards is the wide ' +
+        'lexical-recall window (top-30–50) for you to rerank — triage on cards, deep-read only your ' +
+        'shortlist. Set compact:false for full objects.',
+    };
+  }
+
+  // Full mode: original verbose response
+  return {
+    topic,
+    summary: summary || null,
+    anchors,
+    landscape_summary: landscapeSummary,
+    discovered,
+    north_star_pillar_hooks: northStarPillarHooks,
+    architecture_placement: architecturePlacement,
+    candidate_rerank: candidateRerank,
+    candidate_cards: candidateCards,
+    suggested_related: suggestedRelated,
+    codebase_hints: codebaseHints,
+    stress_test_prompts: STRESS_TEST_PROMPTS,
+    gaps_and_questions: gapsAndQuestions,
+    enhancement_suggestions: enhancementSuggestions,
+    conflict_analysis: conflictAnalysis,
+    plan_context_section_markdown: planContextSectionMarkdown,
+    optimized_plan_outline: buildOptimizedOutline(topic),
+    recall_memories_hint: {
+      limit: 10,
+      tags: recallTags.length ? recallTags : undefined,
+    },
+    next_steps: nextSteps,
+    grounded_at: new Date().toISOString(),
+    _compact: false,
+  };
+}
+
+/**
+ * `heyspex_resolve_focus_intent` lexical resolver — [[HS-TASK-JZEJ]] /
+ * [[HS-EPIC-OOPW]] Phase B. Given a free-text focus utterance, run lexical
+ * wide-recall over the vault (titles/bodies/tags) and return a WIDE candidate
+ * window for the calling agent's LLM to rerank. HeySpex hosts no reranker — the
+ * metric is Recall@N, not nDCG@10 ordering
+ * ([[llm-as-reranker-lexical-recall-companion-architecture]]). No embeddings /
+ * vector store (Gate B = NO,
+ * [[retrieval-substrate-lexical-not-embeddings-gate-b-no]]); consumes the same
+ * scoring substrate as hs-ground ([[HS-EPIC-G7R2-hs-ground-three-tier-grounding-report]]).
+ *
+ * The utterance need not contain a spec's exact tag word: utterance tokens match
+ * tags via computeTagScore's substring pass and match titles/bodies via BM25, so
+ * tag-relevant specs still surface — the core Phase-B behavior.
+ *
+ * Returns an empty window (NOT an error) for an empty/stopword-only utterance,
+ * an empty vault, or no matches — the caller's documented fallback is
+ * heyspex_list_known_tags + exact-tag NLU.
+ *
+ * Each candidate carries a `match_kind` — `strict-tag` when the user named one
+ * of the spec's tags exactly, `lexical` when it only surfaced on title/body or a
+ * substring tag hit. The top-level `justification` rolls those into the two
+ * counts (plus a ready-to-read `beat`) the confirmation copy reads back
+ * ([[HS-TASK-5DB2]] / focus-intent-routing §5–6).
+ *
+ * @param {string} vaultRoot - Root of the vault (contains specs/).
+ * @param {{ utterance?: string, top_k?: number }} args
+ * @returns {{ utterance: string, candidates: Array<{ spec: string, tags: string[], match_kind: 'strict-tag' | 'lexical', why: string }>, total: number, justification: { strict_tag_matches: number, lexically_adjacent: number, beat: string } }}
+ */
+export function resolveFocusIntentLexical(vaultRoot, args = {}) {
+  const utterance = String(args.utterance || '').trim();
+  // Wide-recall window: default 30, capped at 50 — same Recall@N bounds as
+  // executeGroundPlan's limit. top_k narrows the window when the caller asks.
+  const topK = Math.min(Math.max(Number(args.top_k) || 30, 1), 50);
+
+  const tokens = [...new Set(tokenize(utterance))];
+  if (tokens.length === 0) {
+    return { utterance, candidates: [], total: 0, justification: buildFocusJustification(0, 0) };
+  }
+
+  // Graceful degradation ([[HS-TASK-09I3]] / focus-intent-routing §6). The
+  // lexical recall primitive can be unreachable in a constrained environment —
+  // no vault index, an IO error while walking specs/, a corpus that fails to
+  // load. When the index build or scoring throws, the resolver must NOT raise:
+  // it degrades to an empty window flagged `degraded`, routing the caller to the
+  // Phase-A exact-tag NLU floor (heyspex_list_known_tags + closed-vocab mapping)
+  // instead of erroring out. An empty *result* (no matches, empty vault) is a
+  // success and is handled by the normal path below — only a thrown primitive
+  // trips degradation.
+  let index;
+  try {
+    index = getOrBuildIndex(vaultRoot);
+  } catch (err) {
+    return buildDegradedFocusResult(utterance, err);
+  }
+
+  // A candidate is a STRICT-TAG match when the user named one of its tags
+  // exactly — every token of some tag is present in the utterance (so multi-word
+  // tags like `focus-areas` match "focus areas"). Everything else that still
+  // surfaced matched on title/body/substring only — "lexically adjacent". The
+  // split feeds the confirmation copy ([[HS-TASK-5DB2]]).
+  const utteranceSet = new Set(tokens);
+  const isStrictTagHit = (specTags) =>
+    (specTags || []).some((tag) => {
+      const t = String(tag).toLowerCase();
+      if (utteranceSet.has(t)) return true;
+      const parts = tokenize(t);
+      return parts.length > 0 && parts.every((p) => utteranceSet.has(p));
+    });
+
+  let candidates;
+  try {
+    const scored = [];
+    for (const spec of index.specs.values()) {
+      // No explicit tags / areas from a free-text utterance — the utterance
+      // tokens carry the tag matching (computeTagScore substring pass) and the
+      // lexical hit.
+      const result = scoreSpecWithIndex(tokens, [], [], spec, index.corpus);
+      // Gate on the LEXICAL signal (BM25 + title + tag), not the full weighted
+      // score: status/backlink/recency boosts are unconditional, so the full
+      // score is > 0 for every open spec even with no term match. A candidate
+      // must actually match the utterance; the boosts only tie-break among
+      // matches.
+      const lexical = result.bm25 + result.titleBoost + result.tagScore;
+      if (lexical <= 0) continue;
+      scored.push({ spec, result });
+    }
+
+    // Deterministic order: score desc, basename asc as a stable tiebreak.
+    scored.sort(
+      (a, b) => b.result.score - a.result.score || a.spec.basename.localeCompare(b.spec.basename),
+    );
+
+    candidates = scored.slice(0, topK).map(({ spec, result }) => ({
+      spec: spec.id,
+      tags: spec.tags,
+      match_kind: isStrictTagHit(spec.tags) ? 'strict-tag' : 'lexical',
+      why: result.reasons.slice(0, 4).join(', ') || 'low relevance',
+    }));
+  } catch (err) {
+    return buildDegradedFocusResult(utterance, err);
+  }
+
+  const strict = candidates.filter((c) => c.match_kind === 'strict-tag').length;
+  const adjacent = candidates.length - strict;
+
+  return {
+    utterance,
+    candidates,
+    total: candidates.length,
+    justification: buildFocusJustification(strict, adjacent),
+  };
+}
+
+/**
+ * The graceful-degradation marker the focus resolver returns when its lexical
+ * recall primitive is unreachable or throws ([[HS-TASK-09I3]]). The shape is a
+ * SUPERSET of the success shape — a caller that ignores `degraded` still reads a
+ * valid empty window (`candidates: []`, `total: 0`) — plus a typed `degraded`
+ * flag and a `fallback` block routing to the Phase-A exact-tag NLU floor
+ * (`heyspex_list_known_tags` + closed-vocab mapping, focus-intent-routing §6).
+ * Never thrown; always returned.
+ *
+ * @param {string} utterance - The original (trimmed) utterance.
+ * @param {unknown} reason - The caught error or a reason string.
+ * @returns {{ utterance: string, candidates: [], total: 0, degraded: true, fallback: { mode: 'exact-tag-nlu', tool: 'heyspex_list_known_tags', reason: string }, justification: { strict_tag_matches: number, lexically_adjacent: number, beat: string } }}
+ */
+export function buildDegradedFocusResult(utterance, reason) {
+  const message =
+    reason && typeof reason === 'object' && 'message' in reason
+      ? String(reason.message)
+      : String(reason || 'lexical resolver unavailable');
+  return {
+    utterance: String(utterance || '').trim(),
+    candidates: [],
+    total: 0,
+    degraded: true,
+    fallback: {
+      mode: 'exact-tag-nlu',
+      tool: 'heyspex_list_known_tags',
+      reason: message,
+    },
+    justification: buildFocusJustification(0, 0),
+  };
+}
+
+/**
+ * Build the strict-tag vs lexically-adjacent split for the focus-intent
+ * confirmation copy ([[HS-TASK-5DB2]]). `beat` is a ready-to-read clause the
+ * calling agent drops into the §5 confirmation beat of focus-intent-routing,
+ * e.g. "3 strict-tag-match specs plus 5 lexically-adjacent specs".
+ */
+function buildFocusJustification(strictTagMatches, lexicallyAdjacent) {
+  const noun = (n) => (n === 1 ? 'spec' : 'specs');
+  const beat =
+    strictTagMatches === 0 && lexicallyAdjacent === 0
+      ? 'no matching specs'
+      : `${strictTagMatches} strict-tag-match ${noun(strictTagMatches)} plus ` +
+        `${lexicallyAdjacent} lexically-adjacent ${noun(lexicallyAdjacent)}`;
+  return { strict_tag_matches: strictTagMatches, lexically_adjacent: lexicallyAdjacent, beat };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tag-drift detection — [[HS-TASK-H0SI]] / [[HS-EPIC-OOPW]].
+// Flag near-duplicate tag pairs in the closed vocabulary (e.g. `chrome-ext` vs
+// `chrome-extension`) so the calling agent — or eventually the console — can
+// propose a merge and the tag set stays clean. Pure LEXICAL string-similarity
+// only (shared stem, edit distance, token overlap); explicitly NOT embedding
+// similarity ([[retrieval-substrate-lexical-not-embeddings-gate-b-no]]). The
+// threshold favors precision over recall: genuinely distinct tags (`mcp` vs
+// `cli`) must not be flagged, even at the cost of missing a subtle pair.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Levenshtein edit distance between two strings (iterative, two-row). */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length];
+}
+
+/** Length of the shared leading prefix of two strings. */
+function commonPrefixLen(a, b) {
+  const max = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max && a[i] === b[i]) i++;
+  return i;
+}
+
+/**
+ * Score one ordered tag pair for drift. Returns the strongest matching signal as
+ * `{ similarity, reason }`, or `null` when the pair looks like two distinct tags.
+ * Each rule has its own conservative internal gate; we take the highest-scoring
+ * rule that fires. `minSimilarity` is the flag threshold for the edit-distance /
+ * token-overlap rules (the categorical rules always clear it).
+ */
+function scoreTagPair(a, b, minSimilarity) {
+  if (a === b) return null;
+  const bare = (s) => s.replace(/[-_]/g, '');
+  const ba = bare(a);
+  const bb = bare(b);
+  const candidates = [];
+
+  // Rule A — same letters, different punctuation. `multi-agent` vs `multiagent`,
+  // `chrome-ext` vs `chrome_ext`. Strongest signal: identical once hyphens and
+  // underscores are removed.
+  if (ba === bb && ba.length > 0) {
+    candidates.push({ similarity: 1, reason: 'same letters, different hyphenation' });
+  }
+
+  // Rule B — plural/singular variant on the de-punctuated form. `task`/`tasks`,
+  // `area`/`areas`. Require the shorter base to be ≥ 3 chars so 1–2 char tags
+  // don't collide.
+  const [shortBare, longBare] = ba.length <= bb.length ? [ba, bb] : [bb, ba];
+  if (
+    shortBare.length >= 3 &&
+    (longBare === `${shortBare}s` || longBare === `${shortBare}es`)
+  ) {
+    candidates.push({ similarity: 0.95, reason: 'plural/singular variant' });
+  }
+
+  // Rule C — abbreviated form: same hyphen-separated tokens except exactly one
+  // position where one token is a prefix of the other (≥ 3 chars). Reuses
+  // tokenize for token-overlap scoring. `chrome-ext` vs `chrome-extension`.
+  const tokA = tokenize(a);
+  const tokB = tokenize(b);
+  if (tokA.length > 0 && tokA.length === tokB.length) {
+    let mismatches = 0;
+    let prefixMatch = false;
+    for (let i = 0; i < tokA.length; i++) {
+      if (tokA[i] === tokB[i]) continue;
+      mismatches++;
+      const [shortTok, longTok] =
+        tokA[i].length <= tokB[i].length ? [tokA[i], tokB[i]] : [tokB[i], tokA[i]];
+      if (shortTok.length >= 3 && longTok.startsWith(shortTok)) prefixMatch = true;
+      else { prefixMatch = false; break; }
+    }
+    if (mismatches === 1 && prefixMatch) {
+      candidates.push({ similarity: 0.9, reason: 'abbreviated form of the same tag' });
+    }
+  }
+
+  // Rule D — shared stem / near-identical spelling via edit distance. Gated on a
+  // long shared prefix and a small edit distance relative to length so distinct
+  // short tags (`mcp` vs `cli`) never qualify. `schedule` vs `scheduler`.
+  const longLen = Math.max(ba.length, bb.length);
+  const shortLen = Math.min(ba.length, bb.length);
+  if (longLen >= 5) {
+    const dist = levenshtein(ba, bb);
+    const prefix = commonPrefixLen(ba, bb);
+    const sim = 1 - dist / longLen;
+    if (dist <= 2 && prefix >= Math.ceil(0.6 * shortLen) && sim >= minSimilarity) {
+      candidates.push({ similarity: Number(sim.toFixed(2)), reason: `shared stem (edit distance ${dist})` });
+    }
+  }
+
+  // Rule E — strong multi-word overlap. Jaccard over the tokenized tags catches
+  // reordered/extra-word near-dupes the position-sensitive Rule C misses. Gated
+  // high (≥ minSimilarity, ≥ 2 tokens each) to stay precise.
+  if (tokA.length >= 2 && tokB.length >= 2) {
+    const setA = new Set(tokA);
+    const setB = new Set(tokB);
+    let shared = 0;
+    for (const t of setA) if (setB.has(t)) shared++;
+    const union = setA.size + setB.size - shared;
+    const jaccard = union > 0 ? shared / union : 0;
+    if (jaccard >= minSimilarity && jaccard < 1) {
+      candidates.push({ similarity: Number(jaccard.toFixed(2)), reason: 'overlapping words' });
+    }
+  }
+
+  if (candidates.length === 0) return null;
+  return candidates.reduce((best, c) => (c.similarity > best.similarity ? c : best));
+}
+
+/**
+ * Detect near-duplicate tag pairs in a vocabulary. `tags` may be an array of tag
+ * strings or of `{ name, count }` objects (the shape `heyspex_list_known_tags`
+ * returns). Returns drift pairs `{ a, b, reason, similarity }` sorted by
+ * similarity desc, then alphabetically — deterministic, no network, no
+ * embeddings. `minSimilarity` (default 0.8) is the precision/recall knob.
+ */
+function detectTagDrift(tags, options = {}) {
+  const minSimilarity = typeof options.minSimilarity === 'number' ? options.minSimilarity : 0.8;
+  const names = [
+    ...new Set(
+      (Array.isArray(tags) ? tags : [])
+        .map((t) => (typeof t === 'string' ? t : t && t.name))
+        .filter((t) => typeof t === 'string' && t.trim().length > 0)
+        .map((t) => t.trim().toLowerCase()),
+    ),
+  ].sort();
+
+  const drift = [];
+  for (let i = 0; i < names.length; i++) {
+    for (let j = i + 1; j < names.length; j++) {
+      const hit = scoreTagPair(names[i], names[j], minSimilarity);
+      if (hit) drift.push({ a: names[i], b: names[j], reason: hit.reason, similarity: hit.similarity });
+    }
+  }
+
+  drift.sort((x, y) => y.similarity - x.similarity || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+  return drift;
+}
+
+// Export scoring functions for unit testing (HS-TASK-9HIW)
+export {
+  computeBM25,
+  computeTitleBoost,
+  computeBacklinkScore,
+  computeRecencyScore,
+  computeStatusBoost,
+  computeTagScore,
+  computeAreaScore,
+  scoreSpecWithIndex,
+  tokenize,
+  detectTagDrift,
+  extractWikilinks,
+  normalizeWikilinkTarget,
+  parseIsoDate,
+  SCORE_WEIGHTS,
+  BM25_K1,
+  BM25_B,
+  STOPWORDS,
+  AREA_BOOSTS,
+};
+
+export function buildGroundWorkflowMarkdown(options = {}) {
+  const lines = [
+    '# HeySpex hs-ground — holistic pre-plan grounding',
+    '',
+    '> Holistic scan, north-star alignment, architecture placement, plan stress-test, then enhance and optimize before push.',
+    '',
+    '**Plan-quality optimization only — not code performance tuning.**',
+    '',
+    '---',
+    '',
+    '## Six mandatory phases (complete all)',
+    '',
+    '### Phase 1 — Holistic scan of the landscape',
+    '',
+    '1. Call MCP tool **`heyspex_ground_plan`** with `topic`, `summary`, `tags`, `areas`.',
+    '2. Call **`heyspex_recall_memories`** (`limit: 10`, tags from tool `recall_memories_hint`).',
+    '3. Read **all anchors** + top 5–8 discovered specs; any `.md` ≥500 lines in `large_markdown_files` → read fully.',
+    '4. Explore codebase via `codebase_hints` (`rg`, Glob) — not README-only ([[audit-read-plan-files-not-just-readmes]]).',
+    '5. **Deliverable:** `## Landscape scan` — table of specs/code with relevance; duplicates and surprises.',
+    '',
+    '### Phase 1b — Conflict gate (required when `conflict_analysis.conflict_count` > 0)',
+    '',
+    'Uses the **same detector** as Console On Deck (`GET /api/specs/:id/conflicts`) and `/hs-resolve`.',
+    '',
+    '1. Review `conflict_analysis.conflicts` — sources: `focused_epic`, `draft_plan`, `cross_spec_drift`.',
+    '2. Apply `source_of_truth_rules` — default **protocol** for behavior; **north-star** for vision; epic only when superseding.',
+    '3. **Do not** treat `conflicted_spec_basenames` as authoritative context until resolved.',
+    '4. Run **`/hs-resolve`** (or Console On Deck → Spec Conflicts) for focused-epic conflicts.',
+    '5. Re-run **`heyspex_ground_plan`** after fixes; confirm `has_blocking_conflicts` is false.',
+    '6. **Deliverable:** `## Conflict resolution` — conflict → chosen source of truth → action taken.',
+    '',
+    'If `conflict_count` is 0, note “no conflicts” and proceed.',
+    '',
+    '### Phase 2 — Tie work to north-star / pillars',
+    '',
+    '1. Quote specific **north-star** goals/themes served or conflicted.',
+    '2. Name **architecture pillar(s)** and milestones (M2–M5) from `north_star_pillar_hooks`.',
+    '3. State **in-scope vs horizon** — defer future-considerations explicitly.',
+    '4. **Deliverable:** `## North-star and pillar alignment` — pass/fail + risks.',
+    '',
+    '### Phase 3 — Place in the architecture',
+    '',
+    '1. **System map** — surfaces, packages, integration points.',
+    '2. **Spec graph** — parent epic candidate, siblings, governing protocols, ADRs.',
+    '3. **Roadmap placement** — manifest phase ([[HS-ROADMAP-product-master]]).',
+    '4. **Deliverable:** `## Architecture placement`.',
+    '',
+    '### Phase 4 — Stress-test the plan',
+    '',
+    'Work through every `stress_test_prompts` item from the tool output:',
+    '',
+    '- “Is this the best you can do?” — stronger v2 vs cuts',
+    '- Gaps: acceptance criteria, edge cases, non-goals, tests, ops docs',
+    '- Conflicts vs protocols; duplicates; memory constraints',
+    '- Confirm `conflict_analysis` is clear (Phase 1b complete if conflicts existed)',
+    '',
+    '**Deliverable:** `## Stress-test` — findings by severity (blocker / should-fix / nice-to-have).',
+    '',
+    '### Phase 5 — Enhance the plan',
+    '',
+    'Produce revised goal, scope, phases, child tasks, acceptance criteria, final `related:` wikilinks, code touch map.',
+    'Merge `enhancement_suggestions` from the tool.',
+    '',
+    '**Deliverable:** `## Enhanced plan` — markdown ready for `/hs-push`.',
+    '',
+    '### Phase 6 — Optimize as a result of analysis',
+    '',
+    'Tighten scope, reorder phases, sharpen `/hs-push-next` handoff. **Not** code perf.',
+    '',
+    '**Deliverable:** `## Optimized plan` — diff from pre-ground draft + `optimized_plan_outline` from tool.',
+    '',
+    '---',
+    '',
+    '## Output modes',
+    '',
+    '| Mode | Action |',
+    '|------|--------|',
+    '| Chat | Deliver Phases 1–6 in chat; no vault writes |',
+    '| Plan section | Paste `plan_context_section_markdown` + optimized plan into epic body |',
+    '| Research | If `save_research: true` or >8 novel findings → `heyspex_save_research` |',
+    '',
+    '**Handoff:** Grounding complete. Run `/hs-push` or `/hs-push-next` with the optimized plan and `related:` from Phase 6.',
+    '',
+    '## Linkage (after push)',
+    '',
+    '- `npm run validate:vault-ids`',
+    '- `heyspex_validate_linkage` + `heyspex_register_spec` when available',
+    '',
+  ];
+
+  if (options.topic) {
+    lines.push('## Topic', '', options.topic, '');
+  }
+  if (options.summary) {
+    lines.push('## Summary', '', options.summary, '');
+  }
+  if (options.save_research) {
+    lines.push('## save_research', '', 'true — offer heyspex_save_research after landscape scan.', '');
+  }
+
+  return lines.join('\n');
+}