heyspex 0.1.0

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

@@ -0,0 +1,1419 @@
+/**
+ * HeySpex plan-review executor — the brain of the plan V1 → quality+canonical
+ * check → V2 gate ([[HS-EPIC-PLRV-plan-v1-quality-canonical-check-v2-gate]]).
+ *
+ * Pure-logic module backing the `heyspex_plan_review` MCP tool mounted in
+ * cli.mjs. Takes a plan file (path or inline content), runs four passes, and
+ * returns structured findings + V2 patch hints. Also writes a marker file at
+ * `.heyspex/plan-reviews/<sha256-of-plan-content>.json` that the per-editor
+ * gates read to decide whether ExitPlanMode is allowed.
+ *
+ * Four passes:
+ *   1. Scope-term extraction — spec ids, wikilinks, file paths, symbols,
+ *      content keywords (mirrors the tag-overlap heuristic in
+ *      scoreRelevantMemories at cli.mjs).
+ *   2. Overlap grep — scan specs/{tasks,epics,research,captures,protocols,
+ *      milestones,diagnoses} filtered to in-flight status only (closed /
+ *      superseded specs are frozen records, not competitors — see
+ *      [[closed-trackable-specs-are-historical-record-not-living-docs]]) and
+ *      classify each hit SUPERSEDED | SUBSUMED | SIBLING | UPSTREAM | PARENT.
+ *   3. Code audit — resolve the literal files/symbols the plan names against
+ *      the codebase: unresolved → BLOCKER, resolved → INFO.
+ *   4. Canonical + supersession — borrow the SRP test from
+ *      [[doc-canonicalization-protocol]] and the relationship language from
+ *      [[supersession-protocol]].
+ *
+ * Spec: [[HS-TASK-PRVT-plan-review-mcp-tool-overlap-and-audit]]
+ * Pattern source: vendor/heyspex-mcp/procedure-tools.mjs (the pure-executor
+ * shape this module mirrors).
+ * Run tests with: node --test vendor/heyspex-mcp/plan-review.test.mjs
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// In-flight statuses only. Terminal-status specs (closed / superseded /
+// cancelled / duplicate / archived) are frozen historical records, filtered
+// out of overlap matches per the closed-spec immutability principle.
+const IN_FLIGHT_STATUSES = new Set(['open', 'in_progress', 'in_review']);
+
+// Spec buckets scanned for overlap. Mirrors loadVaultSpecsForScheduler but
+// widened to the doc/research/capture surfaces a plan can collide with.
+const OVERLAP_DIRS = [
+  'specs/tasks',
+  'specs/epics',
+  'specs/milestones',
+  'specs/research',
+  'specs/captures',
+  'specs/protocols',
+  'specs/diagnoses',
+  // Axis-B drift: governing memory specs are not deliverables but constrain plans.
+  'specs/memory/decisions',
+  'specs/memory/lessons',
+];
+
+// Memory buckets scanned only for the Axis-B design-supersession pass (Pass 6).
+const MEMORY_AXIS_DIRS = ['specs/memory/decisions', 'specs/memory/lessons'];
+
+// Code roots scanned by the code-audit pass for symbol resolution. Only those
+// that exist under vaultRoot are read; missing roots are skipped silently.
+// (specs/ is intentionally excluded — it holds markdown, not code; symbols
+// mentioned only in prose specs must not count as "resolved" in code.)
+const CODE_ROOTS = ['vendor/heyspex-mcp', 'spex-console/src', 'scripts'];
+const CODE_EXTS = new Set(['.mjs', '.ts', '.tsx', '.js', '.jsx', '.cjs', '.mts', '.cts']);
+const SKIP_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo', 'coverage']);
+const MAX_CODE_FILES = 4000; // backstop so the audit can't walk an unbounded tree
+
+// Relationship-language cues used to classify an in-flight overlap. Borrowed
+// from supersession-protocol (supersede words) and the dependency vocabulary.
+const SUPERSEDE_WORDS = ['supersede', 'supersedes', 'superseded', 'replace', 'replaces', 'deprecate', 'deprecates', 'retire', 'retires', 'obsolete', 'obsoletes', 'discontinue', 'discontinues'];
+const SUBSUME_WORDS = ['subsume', 'subsumes', 'absorb', 'absorbs', 'fold in', 'folds in', 'roll up', 'rolls up', 'rolls into', 'rolled into', 'merge into', 'merges into'];
+const UPSTREAM_WORDS = ['depends on', 'depend on', 'depends_on', 'builds on', 'built on', 'requires', 'required by', 'prerequisite', 'upstream', 'blocked by', 'after landing', 'once .* lands', 'builds upon'];
+const PARENT_WORDS = ['parent', 'under the', 'child of', 'belongs under', 'milestone', 'epic for'];
+
+// Minimal English stopword set for content-keyword extraction. Not exhaustive —
+// just enough to keep overlap scoring from being dominated by glue words.
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'any', 'can', 'her', 'was', 'one', 'our', 'out', 'has', 'have', 'had', 'his', 'how', 'man', 'new', 'now', 'old', 'see', 'two', 'way', 'who', 'its', 'this', 'that', 'with', 'from', 'they', 'will', 'what', 'when', 'they', 'them', 'then', 'than', 'into', 'over', 'such', 'each', 'their', 'there', 'these', 'those', 'which', 'would', 'should', 'could', 'about', 'after', 'before', 'where', 'while', 'being', 'been', 'were', 'also', 'only', 'some', 'more', 'most', 'other', 'must', 'does', 'done', 'made', 'make', 'just', 'like', 'plan', 'spec', 'task', 'epic', 'work', 'use', 'used', 'using', 'via', 'per', 'add', 'adds', 'added', 'new',
+]);
+
+/**
+ * Parse YAML frontmatter from a markdown string. Self-contained (does not
+ * import cli.mjs internals) so the executor stays independently testable.
+ * Returns { frontmatter, body }. Only the shallow scalars / simple lists that
+ * spec frontmatter uses are parsed.
+ */
+export function parsePlanFrontmatter(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();
+  const frontmatter = {};
+  let currentListKey = null;
+  for (const rawLine of yamlBlock.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line.trim()) continue;
+    const listItem = line.match(/^\s*-\s+(.*)$/);
+    if (listItem && currentListKey) {
+      frontmatter[currentListKey].push(stripScalar(listItem[1]));
+      continue;
+    }
+    const kv = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const value = kv[2];
+    if (value === '' || value === '|' || value === '>') {
+      // Begin a list (or a block scalar we treat as empty); next indented
+      // `- ` lines attach to this key.
+      frontmatter[key] = [];
+      currentListKey = key;
+    } else {
+      frontmatter[key] = stripScalar(value);
+      currentListKey = null;
+    }
+  }
+  return { frontmatter, body };
+}
+
+function stripScalar(raw) {
+  let v = raw.trim();
+  if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) {
+    v = v.slice(1, -1);
+  }
+  return v;
+}
+
+/** Normalize a spec id / wikilink basename to its bare HS-XXX-YYYY id form. */
+function toSpecId(ref) {
+  const m = String(ref).match(/HS-[A-Z]+-[A-Za-z0-9]{3,}/);
+  return m ? m[0].toUpperCase() : null;
+}
+
+/**
+ * Pass 1 — extract the terms a plan touches.
+ *   spec_ids  — HS-XXX-YYYY ids referenced anywhere
+ *   wikilinks — [[basename]] targets
+ *   files     — path-like tokens ending in a known code/doc extension
+ *   symbols   — identifiers that look like function/class names
+ *   keywords  — deduped lowercase content words (stopwords removed)
+ */
+export function extractScopeTerms(planBody) {
+  const text = String(planBody || '');
+
+  const specIds = new Set();
+  for (const m of text.matchAll(/HS-[A-Z]+-[A-Za-z0-9]{3,}/g)) {
+    specIds.add(m[0].toUpperCase());
+  }
+
+  const wikilinks = new Set();
+  for (const m of text.matchAll(/\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g)) {
+    wikilinks.add(m[1].trim());
+  }
+
+  const files = new Set();
+  for (const m of text.matchAll(/[\w./@-]+\.(?:mjs|cjs|mts|cts|ts|tsx|js|jsx|json|md|yaml|yml)\b/g)) {
+    // Skip bare extensions captured without a path segment.
+    const f = m[0];
+    if (f.includes('/') || f.includes('.')) files.add(f.replace(/^[`'"]+|[`'"]+$/g, ''));
+  }
+
+  const symbols = new Set();
+  // Backtick-quoted identifiers: `someFunction`, `ClassName`, `runPlanReview()`
+  for (const m of text.matchAll(/`([A-Za-z_$][A-Za-z0-9_$]*)\(?\)?`/g)) {
+    const s = m[1];
+    if (s.length >= 3 && /[a-z]/.test(s) && /[A-Z_]/.test(s)) symbols.add(s);
+  }
+  // Call-shaped identifiers in prose: someFunction(
+  for (const m of text.matchAll(/\b([a-z][A-Za-z0-9_$]*[A-Z][A-Za-z0-9_$]*|[a-z_][A-Za-z0-9_$]+)\s*\(/g)) {
+    const s = m[1];
+    if (s.length >= 4 && /[A-Z_]/.test(s) && !STOPWORDS.has(s.toLowerCase())) symbols.add(s);
+  }
+
+  const keywords = new Set();
+  for (const m of text.toLowerCase().matchAll(/[a-z][a-z0-9-]{2,}/g)) {
+    const w = m[0];
+    if (w.length < 4 || w.length > 32) continue;
+    if (STOPWORDS.has(w)) continue;
+    keywords.add(w);
+  }
+
+  return {
+    spec_ids: [...specIds],
+    wikilinks: [...wikilinks],
+    files: [...files],
+    symbols: [...symbols],
+    keywords: [...keywords],
+  };
+}
+
+/** Load one in-flight spec descriptor, or null if absent / terminal-status. */
+function loadOverlapCandidates(vaultRoot) {
+  const out = [];
+  for (const dir of OVERLAP_DIRS) {
+    const full = join(vaultRoot, dir);
+    if (!existsSync(full)) continue;
+    let files;
+    try {
+      files = readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of files) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      if (entry.name.endsWith('.review.md')) continue;
+      const relPath = `${dir}/${entry.name}`;
+      let content;
+      try {
+        content = readFileSync(join(vaultRoot, relPath), 'utf8');
+      } catch {
+        continue;
+      }
+      const { frontmatter, body } = parsePlanFrontmatter(content);
+      const basename = entry.name.replace(/\.md$/i, '');
+      const id = (typeof frontmatter.id === 'string' && frontmatter.id) ? frontmatter.id : basename;
+      const status = String(frontmatter.status || 'open').toLowerCase();
+      if (!IN_FLIGHT_STATUSES.has(status)) continue; // frozen record — skip
+      const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+      out.push({
+        // `id` is the raw frontmatter id for display; `matchId` is the bare
+        // HS-XXX-YYYY form used to compare against plan references (protocol /
+        // research ids carry a hyphenated slug toSpecId would truncate, so we
+        // never overwrite the display id with the truncated form).
+        id: id,
+        matchId: toSpecId(id),
+        basename,
+        relPath,
+        type: String(frontmatter.type || dir.split('/')[1] || 'spec'),
+        status,
+        canonical: frontmatter.canonical !== 'false' && frontmatter.canonical !== false,
+        canonicalExplicit: frontmatter.canonical === 'true' || frontmatter.canonical === true,
+        title: String(frontmatter.name || frontmatter.id || basename),
+        tags: tags.map((t) => String(t).toLowerCase()),
+        body,
+      });
+    }
+  }
+  return out;
+}
+
+/** Load open memory decisions/lessons for the Axis-B design-supersession pass. */
+function loadMemoryAxisSpecs(vaultRoot) {
+  const out = [];
+  for (const dir of MEMORY_AXIS_DIRS) {
+    const full = join(vaultRoot, dir);
+    if (!existsSync(full)) continue;
+    let files;
+    try {
+      files = readdirSync(full, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of files) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const relPath = `${dir}/${entry.name}`;
+      let content;
+      try {
+        content = readFileSync(join(vaultRoot, relPath), 'utf8');
+      } catch {
+        continue;
+      }
+      const { frontmatter, body } = parsePlanFrontmatter(content);
+      const basename = entry.name.replace(/\.md$/i, '');
+      const id = typeof frontmatter.id === 'string' && frontmatter.id ? frontmatter.id : basename;
+      const status = String(frontmatter.status || 'open').toLowerCase();
+      if (!IN_FLIGHT_STATUSES.has(status)) continue;
+      out.push({
+        id,
+        matchId: toSpecId(id),
+        basename,
+        relPath,
+        type: String(frontmatter.type || 'memory-decision'),
+        status,
+        title: String(frontmatter.name || frontmatter.id || basename),
+        body,
+      });
+    }
+  }
+  return out;
+}
+
+// Cues in memory decisions that mark design constraints (Axis B).
+const OFF_DIRECTION_CUES = [
+  'off-direction',
+  'does not implement',
+  'does not run',
+  'never calls',
+  'never sit in',
+  'do not revive',
+  'do not rebuild',
+  'push back before building',
+  'superseded by',
+  'replaced by',
+  'is dead',
+  'are dead',
+  'deprecated.',
+];
+
+function constraintTokens(text) {
+  const set = new Set();
+  for (const m of String(text).toLowerCase().matchAll(/[a-z][a-z0-9-]{2,}/g)) {
+    const w = m[0];
+    if (w.length >= 4 && !STOPWORDS.has(w)) set.add(w);
+  }
+  return set;
+}
+
+/**
+ * Extract "dead" and off-direction constraint lines from a memory spec body.
+ * Exported for unit tests ([[drift-is-two-axes-as-built-and-design-supersession]]).
+ */
+export function extractDesignConstraints(body) {
+  const text = String(body || '');
+  const constraints = [];
+
+  // **Dead ...:** section header with following bullets (some older docs).
+  const deadSection = text.match(/\*\*Dead[^*]*\*\*[^\n]*\n([\s\S]*?)(?=\n\*\*[^*]|\n## |\n---|$)/i);
+  if (deadSection) {
+    for (const line of deadSection[1].split('\n')) {
+      const bullet = line.match(/^\s*[-*]\s+(.*)/);
+      if (bullet && bullet[1].trim().length > 8) {
+        constraints.push({ kind: 'dead', text: bullet[1].trim() });
+      }
+    }
+  }
+
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length < 12) continue;
+
+    // Inline bullet: `- **Dead (in-app inference):** BYOK getApiKey + Settings key UI`
+    const deadInline = trimmed.match(/^[-*]\s+\*\*Dead[^*]*:\*\*\s*(.+)/i);
+    if (deadInline && deadInline[1].trim().length > 8) {
+      constraints.push({ kind: 'dead', text: deadInline[1].trim() });
+      continue;
+    }
+
+    const lower = trimmed.toLowerCase();
+    if (OFF_DIRECTION_CUES.some((cue) => lower.includes(cue))) {
+      constraints.push({ kind: 'off_direction', text: trimmed.replace(/^[-*#>\s]+/, '') });
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * Pass 6 — Axis B design-supersession drift. Detects when a plan proposes work
+ * that governing memory decisions mark dead or off-direction (see
+ * [[drift-is-two-axes-as-built-and-design-supersession]]). The overlap grep's
+ * conflict detector is blind to this axis.
+ */
+export function runAxisBDriftPass(planBody, scope, memorySpecs) {
+  const planLower = String(planBody).toLowerCase();
+  const planKw = new Set(scope.keywords);
+  const conflicts = [];
+  const checked = [];
+
+  for (const spec of memorySpecs) {
+    const constraints = extractDesignConstraints(spec.body);
+    if (!constraints.length) continue;
+    checked.push(spec.id);
+
+    for (const { kind, text } of constraints) {
+      const cTok = constraintTokens(text);
+      let shared = 0;
+      const sharedTerms = [];
+      for (const t of cTok) {
+        if (planKw.has(t) || planLower.includes(t)) {
+          shared += 1;
+          sharedTerms.push(t);
+        }
+      }
+      const phrase = text.replace(/`/g, '').toLowerCase();
+      const phraseHit =
+        phrase.length >= 18 &&
+        planLower.includes(phrase.slice(0, Math.min(phrase.length, 48)).trim());
+
+      if (shared >= 2 || phraseHit) {
+        conflicts.push({
+          decision_id: spec.id,
+          decision_basename: spec.basename,
+          constraint_kind: kind,
+          constraint: text.slice(0, 240),
+          shared_terms: sharedTerms.slice(0, 8),
+          note:
+            'Plan scope overlaps a governing memory constraint (Axis B — design supersession). ' +
+            'The plan may re-implement work a newer decision marked dead or off-direction. ' +
+            'Remove/re-scope per the decision, or file an explicit supersession if intentional.',
+        });
+      }
+    }
+  }
+
+  return {
+    axis_b_drift: conflicts,
+    axis_b_decisions_checked: checked.length,
+    axis_b_memory_specs_loaded: memorySpecs.length,
+  };
+}
+
+/** Tokenize a spec's title + tags into a keyword set for overlap scoring. */
+function specKeywords(spec) {
+  const set = new Set(spec.tags);
+  for (const m of String(spec.title).toLowerCase().matchAll(/[a-z][a-z0-9-]{2,}/g)) {
+    const w = m[0];
+    if (w.length >= 4 && !STOPWORDS.has(w)) set.add(w);
+  }
+  return set;
+}
+
+/**
+ * Find the relationship cue (if any) in the window of plan text surrounding a
+ * reference to a spec. Returns the classification override or null.
+ */
+function classifyByProximity(planBody, refTokens, specType) {
+  const lower = String(planBody).toLowerCase();
+  // Find the earliest occurrence of any ref token, then look at a ±220 char window.
+  let idx = -1;
+  for (const tok of refTokens) {
+    const at = lower.indexOf(String(tok).toLowerCase());
+    if (at !== -1 && (idx === -1 || at < idx)) idx = at;
+  }
+  const window = idx === -1 ? lower : lower.slice(Math.max(0, idx - 220), idx + 220);
+
+  const has = (words) => words.some((w) => (w.includes('.*') ? new RegExp(w).test(window) : window.includes(w)));
+
+  if (has(SUPERSEDE_WORDS)) return 'SUPERSEDED';
+  if (has(SUBSUME_WORDS)) return 'SUBSUMED';
+  if (has(UPSTREAM_WORDS)) return 'UPSTREAM';
+  if ((specType === 'epic' || specType === 'milestone') && has(PARENT_WORDS)) return 'PARENT';
+  return null;
+}
+
+/** Extract a short evidence snippet around the first ref occurrence. */
+function evidenceSnippet(planBody, refTokens) {
+  const lower = String(planBody).toLowerCase();
+  let idx = -1;
+  for (const tok of refTokens) {
+    const at = lower.indexOf(String(tok).toLowerCase());
+    if (at !== -1 && (idx === -1 || at < idx)) idx = at;
+  }
+  if (idx === -1) return '';
+  const start = Math.max(0, idx - 80);
+  const snippet = String(planBody).slice(start, idx + 140).replace(/\s+/g, ' ').trim();
+  return (start > 0 ? '…' : '') + snippet + '…';
+}
+
+/**
+ * Pass 2 — overlap grep + classification. Returns
+ * { in_flight_overlap, supersedes, canonical_doc }.
+ */
+function runOverlapPass(planBody, scope, candidates) {
+  const planKeywords = new Set(scope.keywords);
+  const refIds = new Set(scope.spec_ids);
+  const refLinks = new Set(scope.wikilinks);
+
+  const overlaps = [];
+  const supersedes = [];
+
+  for (const spec of candidates) {
+    const directRef =
+      (spec.matchId && refIds.has(spec.matchId)) ||
+      refLinks.has(spec.basename) ||
+      scope.spec_ids.some((rid) => spec.basename.toUpperCase().includes(rid));
+
+    const sk = specKeywords(spec);
+    let shared = 0;
+    for (const k of sk) if (planKeywords.has(k)) shared += 1;
+    const overlapRatio = sk.size ? shared / sk.size : 0;
+
+    // Threshold: a direct reference always qualifies; otherwise require a
+    // meaningful keyword overlap so unrelated specs don't flood the report.
+    if (!directRef && (shared < 3 || overlapRatio < 0.34)) continue;
+
+    const refTokens = [spec.id, spec.matchId, spec.basename].filter(Boolean);
+    let classification = classifyByProximity(planBody, refTokens, spec.type);
+    if (!classification) {
+      // No relationship cue. A plan whose keywords clearly contain the spec's
+      // scope subsumes it; otherwise it's a sibling working the same area.
+      classification = overlapRatio >= 0.8 && shared >= 4 && !directRef ? 'SUBSUMED' : 'SIBLING';
+    }
+
+    const matchedTerms = [...sk].filter((k) => planKeywords.has(k)).slice(0, 8);
+    const why = directRef
+      ? `Plan directly references ${spec.id}; in-flight (${spec.status}). Relationship read as ${classification}.`
+      : `Keyword overlap with ${spec.id} (${shared} shared terms${matchedTerms.length ? ': ' + matchedTerms.join(', ') : ''}); both in-flight.`;
+
+    overlaps.push({
+      id: spec.id,
+      basename: spec.basename,
+      type: spec.type,
+      status: spec.status,
+      classification,
+      score: Number((overlapRatio || (directRef ? 1 : 0)).toFixed(2)),
+      direct_reference: directRef,
+      matched_terms: matchedTerms,
+      why,
+    });
+
+    if (classification === 'SUPERSEDED') {
+      supersedes.push({
+        id: spec.id,
+        basename: spec.basename,
+        evidence: evidenceSnippet(planBody, refTokens),
+        note: 'Plan text reads as deprecating this spec. If intended, follow [[supersession-protocol]] (status: superseded + superseded_by + banner) rather than deleting it.',
+      });
+    }
+  }
+
+  // Stable ordering: direct references first, then by score desc, then id.
+  overlaps.sort((a, b) => {
+    if (a.direct_reference !== b.direct_reference) return a.direct_reference ? -1 : 1;
+    if (b.score !== a.score) return b.score - a.score;
+    return a.id.localeCompare(b.id);
+  });
+
+  // Canonical detection — borrow the SRP test from doc-canonicalization-protocol.
+  // Among the matched specs, the canonical authority on the shared scope is the
+  // one carrying canonical:true, or (failing that) the highest-overlap evergreen
+  // doc / protocol / decision. Plan-side tasks/epics are deliverables, not the
+  // canonical home of a rule, so they don't win the canonical slot.
+  const EVERGREEN = new Set(['protocol', 'memory-decision', 'memory-lesson', 'adr', 'decision', 'reference']);
+  let canonicalDoc = null;
+  const canonCandidates = overlaps
+    .map((o) => ({ o, spec: candidates.find((c) => c.id === o.id && c.basename === o.basename) }))
+    .filter((x) => x.spec);
+  // Prefer an explicit canonical:true match.
+  let pick = canonCandidates.find((x) => x.spec.canonicalExplicit);
+  if (!pick) pick = canonCandidates.find((x) => EVERGREEN.has(x.spec.type) && x.o.classification !== 'SUPERSEDED');
+  if (pick) {
+    canonicalDoc = {
+      id: pick.spec.id,
+      basename: pick.spec.basename,
+      type: pick.spec.type,
+      why: pick.spec.canonicalExplicit
+        ? `${pick.spec.id} carries canonical:true and overlaps this plan's scope — defer to it as the authority; cite it, don't re-derive its rule.`
+        : `${pick.spec.id} is an evergreen ${pick.spec.type} on the shared scope — treat it as the canonical authority and align the plan to it.`,
+    };
+  }
+
+  return { in_flight_overlap: overlaps, supersedes, canonical_doc: canonicalDoc };
+}
+
+/** Recursively collect code files under a root, bounded by MAX_CODE_FILES. */
+function collectCodeFiles(vaultRoot, root, acc) {
+  const full = join(vaultRoot, root);
+  if (!existsSync(full)) return;
+  let entries;
+  try {
+    entries = readdirSync(full, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (acc.length >= MAX_CODE_FILES) return;
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      collectCodeFiles(vaultRoot, `${root}/${entry.name}`, acc);
+    } else if (entry.isFile()) {
+      const dot = entry.name.lastIndexOf('.');
+      const ext = dot === -1 ? '' : entry.name.slice(dot);
+      if (!CODE_EXTS.has(ext)) continue;
+      acc.push(`${root}/${entry.name}`);
+    }
+  }
+}
+
+/**
+ * Pass 3 — code audit. Resolve each file path and symbol the plan names against
+ * the codebase. Unresolved → BLOCKER; resolved → INFO.
+ */
+function runCodeAudit(vaultRoot, scope, planContent) {
+  const findings = [];
+
+  // File-path resolution — cheap existence check.
+  for (const f of scope.files) {
+    const clean = f.replace(/^\.\//, '');
+    const resolved = existsSync(join(vaultRoot, clean));
+    findings.push({
+      kind: 'file',
+      ref: f,
+      severity: resolved ? 'INFO' : 'BLOCKER',
+      note: resolved
+        ? `File exists at ${clean}.`
+        : `Plan references ${f} but no such file exists under the vault root — fix the path or add it to scope.`,
+    });
+  }
+
+  // Symbol resolution — build the code corpus once, then test each symbol.
+  if (scope.symbols.length) {
+    const files = [];
+    for (const root of CODE_ROOTS) collectCodeFiles(vaultRoot, root, files);
+    const corpus = [];
+    for (const rel of files) {
+      try {
+        corpus.push({ rel, content: readFileSync(join(vaultRoot, rel), 'utf8') });
+      } catch {
+        /* skip unreadable */
+      }
+    }
+    for (const sym of scope.symbols) {
+      const re = new RegExp(`\\b${sym.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+      const where = [];
+      for (const file of corpus) {
+        if (re.test(file.content)) {
+          where.push(file.rel);
+          if (where.length >= 5) break;
+        }
+      }
+      findings.push({
+        kind: 'symbol',
+        ref: sym,
+        severity: where.length ? 'INFO' : 'BLOCKER',
+        where,
+        note: where.length
+          ? `Symbol resolves in ${where.length === 5 ? '5+' : where.length} file(s).`
+          : `Plan references \`${sym}\` but it is not defined anywhere in the scanned code roots (${CODE_ROOTS.join(', ')}) — verify the name or add the missing implementation to scope.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/** Pass 4 — turn findings into actionable V2 patch hints. */
+function buildPatchHints({
+  in_flight_overlap,
+  supersedes,
+  canonical_doc,
+  code_audit,
+  vocabulary_reconciliation,
+  axis_b_drift,
+}) {
+  const hints = [];
+
+  for (const o of in_flight_overlap) {
+    switch (o.classification) {
+      case 'SUPERSEDED':
+        hints.push(`Plan appears to supersede ${o.id} — add an explicit supersession note and follow [[supersession-protocol]] (don't silently replace it).`);
+        break;
+      case 'SUBSUMED':
+        hints.push(`Plan's scope subsumes ${o.id} — fold its acceptance criteria in or mark it superseded; don't leave two specs owning the same scope.`);
+        break;
+      case 'UPSTREAM':
+        hints.push(`${o.id} is an upstream dependency — add it to depends_on and sequence this work after it lands.`);
+        break;
+      case 'PARENT':
+        hints.push(`${o.id} reads as the parent — set parent/milestone frontmatter to it rather than restating its scope.`);
+        break;
+      default:
+        hints.push(`Sibling in-flight work ${o.id} overlaps this scope — coordinate (link it in related:, note the boundary) so you don't stomp each other's WIP.`);
+    }
+  }
+
+  for (const s of supersedes) {
+    hints.push(`Supersession candidate ${s.id}: if intended, apply the [[supersession-protocol]] frontmatter (status, superseded_by, banner) as part of this work.`);
+  }
+
+  if (canonical_doc) {
+    hints.push(`Defer to canonical authority ${canonical_doc.id} on the shared scope — cite it in the plan and align to it instead of re-deriving its rule.`);
+  }
+
+  const blockers = code_audit.filter((c) => c.severity === 'BLOCKER');
+  for (const b of blockers) {
+    hints.push(`Resolve code-audit BLOCKER: ${b.ref} — ${b.note}`);
+  }
+
+  for (const v of (vocabulary_reconciliation || [])) {
+    hints.push(`Vocabulary: plan says "${v.plan_term}" but ${v.spec} uses "${v.vault_term}" — use the established term instead of forking the project's vocabulary.`);
+  }
+
+  for (const d of axis_b_drift || []) {
+    hints.push(
+      `Axis B drift vs ${d.decision_id}: plan overlaps a "${d.constraint_kind}" constraint — ` +
+        `"${d.constraint.slice(0, 100)}${d.constraint.length > 100 ? '…' : ''}". ` +
+        `Remove/re-scope this work per the decision, or supersede the decision explicitly.`,
+    );
+  }
+
+  if (!hints.length) {
+    hints.push('No in-flight overlap, canonical conflict, or unresolved code reference detected. Plan looks clean — proceed to V2 with a one-line "canonical pass: no competing in-flight work" note.');
+  }
+
+  return hints;
+}
+
+// ── Pass 5 — vocabulary reconciliation ──────────────────────────────────────
+// Flags when the plan introduces a term that is a NEAR-but-not-exact variant of
+// a term used by a strongly-overlapping in-flight spec — the morphological /
+// identifier-drift class of "reinventing the project's words" (e.g. plan says
+// "grains" while [[HS-EPIC-7CWZ]] says "grain", or "review-grain" vs
+// "review_grain"). Scoped to specs the overlap pass already flagged as related
+// (high precision per [[HS-RES-2QX6]] F12 — a noisy reconciliation nudge is
+// worse than none). Pure string variance; it does NOT catch synonyms (grain vs
+// mode) — those are surfaced by the overlap pass itself. Non-blocking (INFO).
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  if (!m) return n;
+  if (!n) return m;
+  let prev = Array.from({ length: n + 1 }, (_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+function isTermVariant(a, b) {
+  if (a === b) return false;
+  const na = a.replace(/[-_]/g, ''), nb = b.replace(/[-_]/g, '');
+  if (na === nb) return true; // hyphen/underscore/spacing variant
+  if (na + 's' === nb || nb + 's' === na) return true; // plural
+  const sa = na.replace(/s$/, ''), sb = nb.replace(/s$/, '');
+  if (sa === sb && na !== nb) return true; // shared singular stem
+  // Single-edit typo/morph variant — long words only, to keep precision high.
+  if (Math.min(na.length, nb.length) >= 5 && levenshtein(na, nb) === 1) return true;
+  return false;
+}
+
+function runVocabularyPass(scope, in_flight_overlap, candidatesById) {
+  const planTerms = [...new Set((scope.keywords || []).filter((w) => w.length >= 4))];
+  const seen = new Set();
+  const findings = [];
+  for (const o of in_flight_overlap) {
+    const spec = candidatesById.get(o.id) || candidatesById.get(o.matchId) || candidatesById.get(o.basename);
+    if (!spec) continue;
+    const vocab = specKeywords(spec);
+    for (const p of planTerms) {
+      if (vocab.has(p)) continue; // exact match — already aligned
+      for (const v of vocab) {
+        if (!isTermVariant(p, v)) continue;
+        const key = `${p}|${v}|${o.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        findings.push({
+          kind: 'vocabulary',
+          severity: 'INFO',
+          plan_term: p,
+          vault_term: v,
+          spec: o.id,
+          note: `Plan uses "${p}"; related in-flight ${o.id} uses "${v}". Reconcile to the established term rather than introducing a variant.`,
+        });
+      }
+    }
+  }
+  return findings.slice(0, 8);
+}
+
+/**
+ * Serialize a proposed epic→task breakdown into plan-review-shaped markdown so
+ * the overlap + code-audit passes can run without a separate tool (breakdown
+ * filing review — `scope: "breakdown"` on `heyspex_plan_review`).
+ */
+export function formatBreakdownPlanContent({ epicId, epicName, proposedTasks = [] } = {}) {
+  const tasks = Array.isArray(proposedTasks) ? proposedTasks : [];
+  const lines = [
+    `# Breakdown — proposed ${tasks.length} task(s) under ${epicId || '(no epic)'}`,
+    '',
+  ];
+  if (epicName) lines.push(`Epic title: ${epicName}`, '');
+  if (epicId) lines.push(`Parent epic: [[${epicId}]]`, '');
+  lines.push('## Proposed tasks', '');
+  tasks.forEach((raw, i) => {
+    const t = raw && typeof raw === 'object' ? raw : { title: String(raw || '') };
+    const title = t.title || t.name || `Task ${i + 1}`;
+    lines.push(`### ${i + 1}. ${title}`);
+    const scopeText = t.scope || t.body || t.description;
+    if (scopeText) lines.push(String(scopeText).trim(), '');
+    const files = t.files || t.paths;
+    if (Array.isArray(files) && files.length) {
+      lines.push(`Touches \`${files.join('`, `')}\`.`, '');
+    }
+    if (Array.isArray(t.symbols) && t.symbols.length) {
+      lines.push(`Uses \`${t.symbols.join('`, `')}\`.`, '');
+    }
+    const deps = t.depends_on || t.dependsOn;
+    if (Array.isArray(deps) && deps.length) {
+      lines.push(`Depends on: ${deps.join(', ')}.`, '');
+    }
+  });
+  return lines.join('\n');
+}
+
+/** Closed vocabulary for Pass 7 quality findings ([[HS-TASK-CH6Y]]). */
+export const QUALITY_FINDING_KINDS = new Set(['mece_gap', 'oversize', 'missing_depends_on']);
+
+/** Scope text longer than this is flagged oversize (one-context-window heuristic). */
+const OVERSIZE_SCOPE_CHARS = 1500;
+const OVERSIZE_FILE_COUNT = 8;
+const OVERSIZE_SYMBOL_COUNT = 10;
+
+const ORDERING_CUE_RE =
+  /\b(after|once|blocked by|depends on|requires|prerequisite|must land|before filing)\b/i;
+
+function taskTitle(raw, i) {
+  const t = raw && typeof raw === 'object' ? raw : { title: String(raw || '') };
+  return String(t.title || t.name || `Task ${i + 1}`).trim();
+}
+
+function normalizeTitleKey(title) {
+  return String(title).toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function taskFiles(raw) {
+  const t = raw && typeof raw === 'object' ? raw : {};
+  const files = t.files || t.paths;
+  return Array.isArray(files) ? files.map((f) => String(f).trim()).filter(Boolean) : [];
+}
+
+function taskDependsOn(raw) {
+  const t = raw && typeof raw === 'object' ? raw : {};
+  const deps = t.depends_on || t.dependsOn;
+  return Array.isArray(deps) ? deps.map((d) => String(d).trim()).filter(Boolean) : [];
+}
+
+function taskScopeText(raw) {
+  const t = raw && typeof raw === 'object' ? raw : {};
+  return String(t.scope || t.body || t.description || '').trim();
+}
+
+/**
+ * Validate and normalize agent-supplied quality findings. HeySpex never calls
+ * an LLM here — the session agent judges externally and passes findings back
+ * ([[HS-DEC-heyspex-runs-no-in-app-ai-inference-it-m]]).
+ */
+export function normalizeAgentQualityFindings(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== 'object') continue;
+    const kind = String(item.kind || '').trim();
+    const title = String(item.title || '').trim();
+    const note = String(item.note || '').trim();
+    if (!QUALITY_FINDING_KINDS.has(kind) || !title || !note) continue;
+    out.push({ kind, title, note });
+  }
+  return out;
+}
+
+/**
+ * Pass 7 — breakdown quality pass (MECE, sizing, ordering). Runs deterministic
+ * heuristics locally; optionally merges agent-supplied LLM findings. No in-app
+ * inference ([[HS-TASK-CH6Y]] / [[HS-EPIC-RCJK]]).
+ */
+export function runBreakdownQualityPass(proposedTasks = [], { agentQualityFindings } = {}) {
+  const tasks = Array.isArray(proposedTasks) ? proposedTasks : [];
+  const findings = [];
+  const titleIndex = new Map();
+
+  for (let i = 0; i < tasks.length; i++) {
+    const title = taskTitle(tasks[i], i);
+    const key = normalizeTitleKey(title);
+    if (key && titleIndex.has(key)) {
+      findings.push({
+        kind: 'mece_gap',
+        title: `Duplicate task titles: "${title}"`,
+        note:
+          `Tasks ${titleIndex.get(key) + 1} and ${i + 1} share the same title — ` +
+          'split scope or rename so each task is mutually exclusive.',
+      });
+    } else if (key) {
+      titleIndex.set(key, i);
+    }
+  }
+
+  const fileOwners = new Map();
+  for (let i = 0; i < tasks.length; i++) {
+    for (const f of taskFiles(tasks[i])) {
+      if (!fileOwners.has(f)) fileOwners.set(f, []);
+      fileOwners.get(f).push(i);
+    }
+  }
+  for (const [file, owners] of fileOwners) {
+    if (owners.length < 2) continue;
+    const labels = owners.map((idx) => `"${taskTitle(tasks[idx], idx)}"`).join(', ');
+    findings.push({
+      kind: 'mece_gap',
+      title: `Overlapping file ownership: ${file}`,
+      note:
+        `${owners.length} tasks (${labels}) all touch \`${file}\` — ` +
+        'merge into one task or split file scope so work is MECE.',
+    });
+  }
+
+  for (let i = 0; i < tasks.length; i++) {
+    const scope = taskScopeText(tasks[i]);
+    const files = taskFiles(tasks[i]);
+    const t = tasks[i] && typeof tasks[i] === 'object' ? tasks[i] : {};
+    const symbols = Array.isArray(t.symbols) ? t.symbols : [];
+    const title = taskTitle(tasks[i], i);
+
+    if (
+      scope.length > OVERSIZE_SCOPE_CHARS ||
+      files.length > OVERSIZE_FILE_COUNT ||
+      symbols.length > OVERSIZE_SYMBOL_COUNT
+    ) {
+      findings.push({
+        kind: 'oversize',
+        title: `Task may be oversized: "${title}"`,
+        note:
+          `Scope is ${scope.length} chars / ${files.length} files / ${symbols.length} symbols — ` +
+          'consider splitting into smaller tasks that fit one agent context window.',
+      });
+    }
+
+    const deps = taskDependsOn(tasks[i]);
+    if (ORDERING_CUE_RE.test(scope) && deps.length === 0) {
+      findings.push({
+        kind: 'missing_depends_on',
+        title: `Ordering cue without depends_on: "${title}"`,
+        note:
+          'Scope mentions sequencing ("after", "depends on", "blocked by", …) but `depends_on` is empty — ' +
+          'add explicit dependencies so filing order matches execution order.',
+      });
+    }
+
+    for (const dep of deps) {
+      const depKey = normalizeTitleKey(dep);
+      let depIdx = -1;
+      for (let j = 0; j < tasks.length; j++) {
+        if (normalizeTitleKey(taskTitle(tasks[j], j)) === depKey) {
+          depIdx = j;
+          break;
+        }
+      }
+      if (depIdx === -1) continue;
+      if (depIdx >= i) {
+        findings.push({
+          kind: 'missing_depends_on',
+          title: `Incoherent depends_on: "${title}"`,
+          note:
+            `Depends on "${dep}" which is task ${depIdx + 1} (same or later than task ${i + 1}) — ` +
+            'reorder tasks or fix depends_on so prerequisites come first.',
+        });
+      }
+    }
+  }
+
+  const agentFindings = normalizeAgentQualityFindings(agentQualityFindings);
+  const seen = new Set();
+  const merged = [];
+  for (const f of [...findings, ...agentFindings]) {
+    const key = `${f.kind}|${f.title}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(f);
+  }
+  return merged;
+}
+
+/**
+ * Brief for the session agent when quality_pass is enabled — the agent runs
+ * MECE/sizing/ordering judgment on its own model and may pass findings back
+ * via quality_findings on a follow-up call ([[HS-DEC-heyspex-runs-no-in-app-ai-inference-it-m]]).
+ */
+export function buildQualityJudgeBrief(proposedTasks = []) {
+  const tasks = Array.isArray(proposedTasks) ? proposedTasks : [];
+  const lines = [
+    'Pass 7 quality judge (agent-as-judge — use your own model, not HeySpex inference):',
+    'Check whether proposed tasks are MECE, appropriately sized, and correctly sequenced.',
+    'Return findings as quality_findings: [{ kind: "mece_gap"|"oversize"|"missing_depends_on", title, note }].',
+    '',
+    `Proposed task set (${tasks.length}):`,
+  ];
+  tasks.forEach((raw, i) => {
+    lines.push(`- ${i + 1}. ${taskTitle(raw, i)}`);
+    const scope = taskScopeText(raw);
+    if (scope) lines.push(`  scope: ${scope.slice(0, 200)}${scope.length > 200 ? '…' : ''}`);
+    const deps = taskDependsOn(raw);
+    if (deps.length) lines.push(`  depends_on: ${deps.join(', ')}`);
+  });
+  return lines.join('\n');
+}
+
+/**
+ * Run the full plan review. Accepts either a `planPath` (read from disk,
+ * relative to vaultRoot or absolute) or inline `planContent`. When
+ * `scope === "breakdown"`, also accepts `epicId` + `proposedTasks` to
+ * synthesize review input from a draft task set. Writes a marker file keyed
+ * by the sha256 of the plan content and returns the findings.
+ *
+ * @returns { scope_terms, in_flight_overlap, canonical_doc, supersedes,
+ *            code_audit, vocabulary_reconciliation, v2_patch_hints,
+ *            review_marker_path, review_scope, quality_findings? } | { error, message }
+ */
+export function runPlanReview({
+  vaultRoot,
+  planPath,
+  planContent,
+  scope = 'plan',
+  epicId,
+  epicName,
+  proposedTasks,
+  qualityPass,
+  agentQualityFindings,
+} = {}) {
+  if (!vaultRoot) {
+    return { error: 'MISSING_VAULT_ROOT', message: 'vaultRoot is required.' };
+  }
+
+  const reviewScope = scope === 'breakdown' ? 'breakdown' : 'plan';
+
+  let content = planContent;
+  let resolvedPlanPath = null;
+  if (typeof content !== 'string') {
+    if (
+      reviewScope === 'breakdown' &&
+      typeof epicId === 'string' &&
+      epicId.trim() &&
+      Array.isArray(proposedTasks) &&
+      proposedTasks.length > 0
+    ) {
+      content = formatBreakdownPlanContent({
+        epicId: epicId.trim(),
+        epicName: typeof epicName === 'string' ? epicName.trim() : undefined,
+        proposedTasks,
+      });
+    } else if (!planPath) {
+      if (reviewScope === 'breakdown') {
+        return {
+          error: 'MISSING_BREAKDOWN_INPUT',
+          message:
+            'For scope "breakdown", provide plan_path/plan_content OR epic_id + proposed_tasks (non-empty array).',
+        };
+      }
+      return { error: 'MISSING_PLAN', message: 'Provide either plan_path or plan_content.' };
+    }
+  }
+  if (typeof content !== 'string') {
+    if (!planPath) {
+      return { error: 'MISSING_PLAN', message: 'Provide either plan_path or plan_content.' };
+    }
+    resolvedPlanPath = planPath;
+    const abs = planPath.match(/^([A-Za-z]:[\\/]|\/)/) ? planPath : join(vaultRoot, planPath);
+    if (!existsSync(abs)) {
+      return { error: 'PLAN_NOT_FOUND', message: `Plan file not found: ${planPath}` };
+    }
+    try {
+      content = readFileSync(abs, 'utf8');
+    } catch (err) {
+      return { error: 'PLAN_UNREADABLE', message: `Could not read plan file: ${err.message}` };
+    }
+  }
+
+  if (!content.trim()) {
+    return { error: 'EMPTY_PLAN', message: 'Plan content is empty.' };
+  }
+
+  // The plan body for analysis strips its own frontmatter (if any) so a spec
+  // file's frontmatter doesn't pollute scope extraction.
+  const { body: planBody } = parsePlanFrontmatter(content);
+  const analysisText = planBody && planBody.trim() ? planBody : content;
+
+  const scopeTerms = extractScopeTerms(analysisText);
+  const candidates = loadOverlapCandidates(vaultRoot);
+  const { in_flight_overlap, supersedes, canonical_doc } = runOverlapPass(analysisText, scopeTerms, candidates);
+  const code_audit = runCodeAudit(vaultRoot, scopeTerms, content);
+
+  // Pass 5 — vocabulary reconciliation, scoped to the specs the overlap pass
+  // already flagged (high precision). Index candidates by every id form so the
+  // overlap entries resolve back to their full descriptor.
+  const candidatesById = new Map();
+  for (const c of candidates) {
+    candidatesById.set(c.id, c);
+    candidatesById.set(c.matchId, c);
+    candidatesById.set(c.basename, c);
+  }
+  const vocabulary_reconciliation = runVocabularyPass(scopeTerms, in_flight_overlap, candidatesById);
+  const memoryAxisSpecs = loadMemoryAxisSpecs(vaultRoot);
+  const axis_b = runAxisBDriftPass(analysisText, scopeTerms, memoryAxisSpecs);
+
+  const v2_patch_hints = buildPatchHints({
+    in_flight_overlap,
+    supersedes,
+    canonical_doc,
+    code_audit,
+    vocabulary_reconciliation,
+    axis_b_drift: axis_b.axis_b_drift,
+  });
+
+  const result = {
+    scope_terms: scopeTerms,
+    in_flight_overlap,
+    canonical_doc,
+    supersedes,
+    code_audit,
+    vocabulary_reconciliation,
+    axis_b_drift: axis_b.axis_b_drift,
+    axis_b_decisions_checked: axis_b.axis_b_decisions_checked,
+    v2_patch_hints,
+    plan_path: resolvedPlanPath,
+    review_scope: reviewScope,
+  };
+  if (reviewScope === 'breakdown' && typeof epicId === 'string' && epicId.trim()) {
+    result.epic_id = epicId.trim();
+  }
+
+  const tasksForQuality =
+    Array.isArray(proposedTasks) && proposedTasks.length > 0 ? proposedTasks : null;
+
+  if (qualityPass === true) {
+    if (reviewScope !== 'breakdown' || !tasksForQuality) {
+      return {
+        error: 'QUALITY_PASS_REQUIRES_BREAKDOWN',
+        message:
+          'quality_pass is only supported for scope "breakdown" with epic_id + proposed_tasks.',
+      };
+    }
+    result.quality_findings = runBreakdownQualityPass(tasksForQuality, { agentQualityFindings });
+    if (!agentQualityFindings || !agentQualityFindings.length) {
+      result.quality_judge_brief = buildQualityJudgeBrief(tasksForQuality);
+    }
+  }
+
+  // Side effect: write the marker file keyed by sha256(plan content). A re-review
+  // after a V2 rewrite hashes to a different filename, so each plan version gets
+  // its own marker — the gate reads the marker for the current plan-content hash.
+  const hash = createHash('sha256').update(content).digest('hex');
+  const reviewsDirRel = join('.heyspex', 'plan-reviews');
+  const reviewsDirAbs = join(vaultRoot, reviewsDirRel);
+  const markerRel = join(reviewsDirRel, `${hash}.json`);
+  try {
+    if (!existsSync(reviewsDirAbs)) mkdirSync(reviewsDirAbs, { recursive: true });
+    const marker = { ...result, plan_content_sha256: hash, reviewed_marker: true };
+    writeFileSync(join(vaultRoot, markerRel), JSON.stringify(marker, null, 2), 'utf8');
+    result.review_marker_path = markerRel.replace(/\\/g, '/');
+  } catch (err) {
+    // Marker write failure is surfaced but doesn't drop the findings — the
+    // analysis is still useful even if the gate marker couldn't be persisted.
+    result.review_marker_path = null;
+    result.marker_write_error = err.message;
+  }
+
+  result.plan_content_sha256 = hash;
+  return result;
+}
+
+/**
+ * Newest breakdown-scoped plan-review marker for an epic (by file mtime).
+ * Returns `{ markerRelPath, marker }` or `null`. [[HS-TASK-MEN2]]
+ */
+export function findLatestBreakdownReviewMarker(vaultRoot, epicId) {
+  const reviewsDir = join(vaultRoot, '.heyspex', 'plan-reviews');
+  if (!existsSync(reviewsDir)) return null;
+  const targetEpic = String(epicId || '').trim().toUpperCase();
+  if (!targetEpic) return null;
+
+  let best = null;
+  for (const name of readdirSync(reviewsDir)) {
+    if (!name.endsWith('.json')) continue;
+    const rel = join('.heyspex', 'plan-reviews', name).replace(/\\/g, '/');
+    const abs = join(vaultRoot, rel);
+    let marker;
+    try {
+      marker = JSON.parse(readFileSync(abs, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (marker.review_scope !== 'breakdown') continue;
+    const mid = String(marker.epic_id || '').trim().toUpperCase();
+    if (mid !== targetEpic) continue;
+    let mtime = 0;
+    try {
+      mtime = statSync(abs).mtimeMs;
+    } catch {
+      mtime = 0;
+    }
+    if (!best || mtime > best.mtime) {
+      best = { markerRelPath: rel, marker, mtime };
+    }
+  }
+  return best ? { markerRelPath: best.markerRelPath, marker: best.marker } : null;
+}
+
+/**
+ * Stamp `skipped_despite_findings` on a breakdown plan-review marker at
+ * `heyspex_record_alignment` time — skip-rate telemetry ([[HS-TASK-MEN2]]).
+ * Does not block alignment; hard enforcement is deferred.
+ *
+ * @returns {{ ok, review_marker_path, skipped_despite_findings, epic_id }}
+ *          | {{ error, message }}
+ */
+export function stampSkippedDespiteFindingsOnBreakdownMarker({
+  vaultRoot,
+  epicId,
+  skippedDespiteFindings,
+  markerRelPath,
+} = {}) {
+  if (!vaultRoot) {
+    return { error: 'MISSING_VAULT_ROOT', message: 'vaultRoot is required.' };
+  }
+  if (typeof skippedDespiteFindings !== 'boolean') {
+    return {
+      error: 'INVALID_SKIPPED_DESPITE_FINDINGS',
+      message: 'skipped_despite_findings must be a boolean (true or false).',
+    };
+  }
+
+  let rel = typeof markerRelPath === 'string' && markerRelPath.trim() ? markerRelPath.trim() : null;
+  if (!rel) {
+    const found = findLatestBreakdownReviewMarker(vaultRoot, epicId);
+    if (!found) {
+      return {
+        error: 'MARKER_NOT_FOUND',
+        message:
+          `No breakdown plan-review marker found for epic ${epicId || '(missing)'}. ` +
+          'Run heyspex_plan_review({ scope: "breakdown", epic_id, proposed_tasks }) first.',
+      };
+    }
+    rel = found.markerRelPath;
+  }
+
+  const abs = join(vaultRoot, rel);
+  let marker;
+  try {
+    marker = JSON.parse(readFileSync(abs, 'utf8'));
+  } catch (err) {
+    return { error: 'MARKER_UNREADABLE', message: err.message, review_marker_path: rel.replace(/\\/g, '/') };
+  }
+
+  marker.skipped_despite_findings = skippedDespiteFindings;
+  try {
+    writeFileSync(abs, JSON.stringify(marker, null, 2), 'utf8');
+  } catch (err) {
+    return { error: 'MARKER_WRITE_FAILED', message: err.message, review_marker_path: rel.replace(/\\/g, '/') };
+  }
+
+  return {
+    ok: true,
+    review_marker_path: rel.replace(/\\/g, '/'),
+    skipped_despite_findings: skippedDespiteFindings,
+    epic_id: marker.epic_id || epicId || null,
+  };
+}
+
+// Minimum auditable length for a QC findings summary. Proof-of-Use guard
+// ([[HS-RES-2QX6]] F13 / arXiv 2510.10931): a bare "tool fired" marker is
+// gameable ("decorative tool calls"), so the QC gate requires the agent to
+// record what it actually checked. Kept modest — this resists placeholders, it
+// is not a quality bar on the prose.
+const QC_SUMMARY_MIN_CHARS = 80;
+const QC_AXIS_B_CONFIRM_NOTE_MIN_CHARS = 40;
+
+// NOTE: the explicit axis_b_user_confirmed override is handled entirely by
+// the caller (runPlanQc), *after* this filter runs — it clears whatever this
+// function still reports as unresolved, unconditionally, once a sufficiently
+// long axis_b_confirmation_note is present. This function only recognizes
+// the *organic* resolution path (the agent's own findings_summary prose
+// naming the decision and stating how it was resolved/re-scoped), with no
+// override flag involved. Earlier versions of this function also tried to
+// detect a confirmed override by matching hard-coded phrases ("user
+// confirmed", "confirmed override", …) and requiring the decision id/basename
+// to appear verbatim in the summary or note — that undocumented, brittle
+// contract is what let real overrides fall through and keep refusing
+// ([[HS-EP8E-C1L2-DIAG-heyspex-plan-qc-override-path-ignores-ax]]).
+function axisBDriftUnresolved(axisDrift, summary) {
+  if (!axisDrift.length) return [];
+
+  const summaryLower = summary.toLowerCase();
+
+  return axisDrift.filter((c) => {
+    const mentionsDecision =
+      summaryLower.includes(String(c.decision_id).toLowerCase()) ||
+      summaryLower.includes(String(c.decision_basename).slice(0, 28).toLowerCase());
+
+    const mentionsResolution =
+      /\b(resolved|removed|dropped|re-scoped|superseded|defer|deferred|narrowed|cancelled|canceled|out of scope|not in scope)\b/i.test(
+        summary,
+      );
+
+    return !(mentionsResolution && mentionsDecision);
+  });
+}
+
+/**
+ * Record that the QC gut-check ([[plan-quality-canonical-check]] / `/hs-qc`)
+ * ran for a specific plan, with Proof-of-Use. Mirrors runPlanReview's marker
+ * mechanics but writes `.heyspex/plan-qc/<sha256(plan)>.json` carrying the
+ * agent's findings summary. The ExitPlanMode gate ([[HS-EPIC-PLRV]]) requires
+ * this marker AND the plan-review marker before it allows the exit.
+ *
+ * @returns { qc_marker_path, plan_content_sha256, findings_summary_chars }
+ *          | { error, message }
+ */
+export function runPlanQc({
+  vaultRoot,
+  planPath,
+  planContent,
+  findingsSummary,
+  axisBUserConfirmed,
+  axisBConfirmationNote,
+} = {}) {
+  if (!vaultRoot) {
+    return { error: 'MISSING_VAULT_ROOT', message: 'vaultRoot is required.' };
+  }
+
+  let content = planContent;
+  let resolvedPlanPath = null;
+  if (typeof content !== 'string') {
+    if (!planPath) {
+      return { error: 'MISSING_PLAN', message: 'Provide either plan_path or plan_content.' };
+    }
+    resolvedPlanPath = planPath;
+    const abs = planPath.match(/^([A-Za-z]:[\\/]|\/)/) ? planPath : join(vaultRoot, planPath);
+    if (!existsSync(abs)) {
+      return { error: 'PLAN_NOT_FOUND', message: `Plan file not found: ${planPath}` };
+    }
+    try {
+      content = readFileSync(abs, 'utf8');
+    } catch (err) {
+      return { error: 'PLAN_UNREADABLE', message: `Could not read plan file: ${err.message}` };
+    }
+  }
+
+  if (!content || !content.trim()) {
+    return { error: 'EMPTY_PLAN', message: 'Plan content is empty.' };
+  }
+
+  const summary = String(findingsSummary || '').trim();
+  if (summary.length < QC_SUMMARY_MIN_CHARS) {
+    return {
+      error: 'QC_SUMMARY_TOO_THIN',
+      message:
+        `findings_summary must be a real Proof-of-Use record of the QC gut-check ` +
+        `(>= ${QC_SUMMARY_MIN_CHARS} chars; got ${summary.length}). Summarize what you ` +
+        `actually checked — where the plan could be wrong, risks, breakages now/left-over, ` +
+        `missing items, integrations, JTBD — not a placeholder.`,
+    };
+  }
+
+  const { body: qcPlanBody } = parsePlanFrontmatter(content);
+  const qcAnalysisText = qcPlanBody && qcPlanBody.trim() ? qcPlanBody : content;
+  const qcScope = extractScopeTerms(qcAnalysisText);
+  const axisB = runAxisBDriftPass(qcAnalysisText, qcScope, loadMemoryAxisSpecs(vaultRoot));
+  const userConfirmed = axisBUserConfirmed === true;
+  const confirmationNote = String(axisBConfirmationNote || '').trim();
+
+  if (!/\baxis\s*b\s*:/i.test(summary)) {
+    return {
+      error: 'QC_AXIS_B_MISSING',
+      message:
+        'findings_summary must include an "Axis B:" line documenting the design-supersession ' +
+        'drift pass ([[drift-is-two-axes-as-built-and-design-supersession]]). List governing ' +
+        'memory decisions checked and any conflicts removed/re-scoped.',
+      axis_b_drift: axisB.axis_b_drift,
+      axis_b_decisions_checked: axisB.axis_b_decisions_checked,
+      requires_user_confirmation: axisB.axis_b_drift.length > 0,
+    };
+  }
+
+  const unresolved = axisBDriftUnresolved(axisB.axis_b_drift, summary);
+
+  if (unresolved.length > 0) {
+    if (userConfirmed) {
+      // Explicit override path: axis_b_user_confirmed: true clears whatever
+      // is still unresolved, as documented, provided the confirmation note
+      // meets the minimum audit-trail length. No magic phrasing or verbatim
+      // decision-id mention in findings_summary/note is required — the
+      // override is honored on its own terms, not ignored
+      // ([[HS-EP8E-C1L2-DIAG-heyspex-plan-qc-override-path-ignores-ax]]).
+      if (confirmationNote.length < QC_AXIS_B_CONFIRM_NOTE_MIN_CHARS) {
+        return {
+          error: 'QC_AXIS_B_CONFIRM_NOTE_TOO_THIN',
+          message:
+            `axis_b_user_confirmed requires axis_b_confirmation_note (>= ${QC_AXIS_B_CONFIRM_NOTE_MIN_CHARS} ` +
+            'chars) naming the governing decision and what the user confirmed.',
+          axis_b_drift: unresolved,
+          requires_user_confirmation: true,
+        };
+      }
+      // Override accepted — fall through; axis_b_user_confirmed and
+      // axis_b_confirmation_note get stamped into the QC marker below.
+    } else {
+      return {
+        error: 'QC_AXIS_B_DRIFT',
+        message:
+          `Plan overlaps ${unresolved.length} governing memory constraint(s) (Axis B drift). ` +
+          'STOP — present each conflict to the user before recording QC: (1) default recommendation is ' +
+          're-scope/remove the dead work from the plan, OR (2) if the user explicitly confirms they ' +
+          'want to proceed anyway, re-call with axis_b_user_confirmed: true, axis_b_confirmation_note ' +
+          '(audit trail), and findings_summary noting "user confirmed override". Do not silently ' +
+          'schedule work a memory decision marked dead/off-direction.',
+        axis_b_drift: unresolved,
+        axis_b_decisions_checked: axisB.axis_b_decisions_checked,
+        requires_user_confirmation: true,
+      };
+    }
+  }
+
+  const hash = createHash('sha256').update(content).digest('hex');
+  const qcDirRel = join('.heyspex', 'plan-qc');
+  const qcDirAbs = join(vaultRoot, qcDirRel);
+  const markerRel = join(qcDirRel, `${hash}.json`);
+  const marker = {
+    plan_content_sha256: hash,
+    qc_marker: true,
+    findings_summary: summary,
+    plan_path: resolvedPlanPath,
+    axis_b_drift: axisB.axis_b_drift,
+    axis_b_decisions_checked: axisB.axis_b_decisions_checked,
+    axis_b_user_confirmed: userConfirmed && axisB.axis_b_drift.length > 0,
+    axis_b_confirmation_note: userConfirmed && confirmationNote ? confirmationNote : undefined,
+  };
+  try {
+    if (!existsSync(qcDirAbs)) mkdirSync(qcDirAbs, { recursive: true });
+    writeFileSync(join(vaultRoot, markerRel), JSON.stringify(marker, null, 2), 'utf8');
+    return {
+      qc_marker_path: markerRel.replace(/\\/g, '/'),
+      plan_content_sha256: hash,
+      findings_summary_chars: summary.length,
+    };
+  } catch (err) {
+    return { error: 'QC_MARKER_WRITE_FAILED', message: err.message, plan_content_sha256: hash };
+  }
+}