heyspex 0.1.0

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

@@ -0,0 +1,1826 @@
+/**
+ * Epic plan push + on-deck pinning for HeySpex MCP.
+ * Protocol: [[plan-ingest-agent-workflow]], [[vault-id-assignment-protocol]]
+ * Conflict detection: [[HS-EPIC-6RKN-spec-conflict-detection-pre-flight-check]]
+ * Design enforcement: [[HS-EPIC-W9ZE-design-system-enforcement-auto-surface-u]]
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { prepareVaultPlanContent } from './plan-ingest.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import {
+  allocateFileKey,
+  collectOccupiedFileKeysFromVault,
+  mintFamilyKey,
+  parseSpecId,
+  familyOf,
+} from './spec-id-lib.mjs';
+import {
+  buildSummaryRequiredMcpError,
+  formatSummaryFrontmatterField,
+  resolveAuthoredSummaryValue,
+} from './summary-contract.mjs';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Milestone-parent resolution + bidirectional mirror-update (HS-TASK-T5PX)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a milestone arg from the MCP caller into a canonical basename.
+ * Accepts `[[HS-MIL-XXX-slug]]`, `"[[HS-MIL-XXX-slug]]"`, or bare `HS-MIL-XXX-slug`.
+ * Returns null if the input doesn't look like an HS-MIL reference.
+ */
+export function normalizeMilestoneBasename(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const v = raw.trim().replace(/^['"]|['"]$/g, '');
+  const m = v.match(/^\[\[([^\]]+)\]\]$/);
+  const basename = m ? m[1] : v;
+  // Dual-read: accept type-first HS-MIL-<key>… and family-first HS-<key>-MIL…
+  // ([[HS-EPIC-DLE3]]).
+  if (parseSpecId(basename)?.typeLabel !== 'MIL') return null;
+  return basename;
+}
+
+/**
+ * Mirror-update a milestone file's `epics:` array to include the new epic
+ * basename. Idempotent — no-op if the entry is already present. Line-surgical
+ * (does not re-serialize YAML, per [[HS-DEC-vault-frontmatter-warn-dont-repair-on-read]]).
+ *
+ * Returns { changed, added, totalAfter }.
+ * Throws if the milestone file has no recognizable `epics:` field.
+ */
+export function appendEpicToMilestone(vaultRoot, milestoneBasename, epicBasename) {
+  const milestonePath = join(vaultRoot, 'specs', 'milestones', `${milestoneBasename}.md`);
+  const raw = readFileSync(milestonePath, 'utf8');
+  const fmMatch = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)/);
+  if (!fmMatch) {
+    throw new Error(`Milestone ${milestoneBasename} missing frontmatter`);
+  }
+  const fmOpen = fmMatch[1];
+  let block = fmMatch[2];
+  const fmClose = fmMatch[3];
+  const body = raw.slice(fmMatch[0].length);
+
+  const blockListRe = /^epics:[ \t]*\r?\n((?:[ \t]+-[^\n]*\r?\n)+)/m;
+  const inlineEmptyRe = /^epics:[ \t]*\[[ \t]*\][ \t]*\r?\n/m;
+  const existing = new Set();
+
+  const blockListMatch = block.match(blockListRe);
+  if (blockListMatch) {
+    for (const line of blockListMatch[1].split(/\r?\n/)) {
+      const wm = line.match(/-[ \t]*["']?\[\[([^\]]+)\]\]["']?/);
+      if (wm) existing.add(wm[1]);
+    }
+  }
+
+  if (existing.has(epicBasename)) {
+    return { changed: false, added: null, totalAfter: existing.size };
+  }
+
+  const allBasenames = [...existing, epicBasename];
+  const newEpicsBlock =
+    'epics:\n' + allBasenames.map((b) => `  - "[[${b}]]"`).join('\n') + '\n';
+
+  let nextBlock;
+  if (blockListMatch) {
+    nextBlock = block.replace(blockListRe, newEpicsBlock);
+  } else if (inlineEmptyRe.test(block)) {
+    nextBlock = block.replace(inlineEmptyRe, newEpicsBlock);
+  } else {
+    throw new Error(
+      `Milestone ${milestoneBasename} has no recognizable \`epics:\` field (expected block list or inline empty)`,
+    );
+  }
+
+  const nowIso = new Date().toISOString();
+  const updatedRe = /^updated:[ \t]*["']?[^\n"']+["']?/m;
+  if (updatedRe.test(nextBlock)) {
+    nextBlock = nextBlock.replace(updatedRe, `updated: "${nowIso}"`);
+  }
+
+  writeFileSync(milestonePath, `${fmOpen}${nextBlock}${fmClose}${body}`, 'utf8');
+  return { changed: true, added: epicBasename, totalAfter: allBasenames.length };
+}
+
+/**
+ * Resolve + validate a milestone arg from MCP input. Returns either a
+ * `{ basename, wikilink }` pair or a `{ error, message }` for the caller to
+ * propagate to the tool response.
+ */
+export function resolveMilestoneArg(vaultRoot, raw) {
+  if (!raw?.trim?.()) {
+    return {
+      error: 'MISSING_MILESTONE',
+      message:
+        'milestone is required — wikilink to parent HS-MIL-* (e.g. "[[HS-MIL-HMNJ-status-and-roadmap-surface-refactor]]"). See [[HS-TASK-T5PX]].',
+    };
+  }
+  const basename = normalizeMilestoneBasename(raw);
+  if (!basename) {
+    return {
+      error: 'INVALID_MILESTONE',
+      message: `milestone is not a valid HS-MIL wikilink: ${raw}`,
+    };
+  }
+  const milestonePath = join(vaultRoot, 'specs', 'milestones', `${basename}.md`);
+  if (!existsSync(milestonePath)) {
+    return {
+      error: 'MILESTONE_NOT_FOUND',
+      message: `milestone file does not exist: specs/milestones/${basename}.md`,
+    };
+  }
+  return { basename, wikilink: `[[${basename}]]` };
+}
+
+/**
+ * The family key of an already-resolved milestone (V3 shared-surname model —
+ * [[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]): an epic filed
+ * under a milestone inherits the milestone's family — generalizing the
+ * epic→task pattern ([[vault-id-assignment-protocol]] §Family inheritance) —
+ * so a new epic's `family:` matches its parent milestone whenever one is
+ * derivable, else the caller mints a fresh key. Reads the milestone file's
+ * own frontmatter (explicit `family:` wins, else positional from `id:`), not
+ * just the basename, so a backfilled explicit field is honored.
+ */
+/**
+ * Normalize a caller-supplied pillar reference to a bare `HS-PILR-<slug>` id.
+ * Accepts `[[HS-PILR-x]]`, `'HS-PILR-x'`, or `HS-PILR-x`; returns null for anything
+ * that is not shaped like a pillar id, so the caller falls back to the milestone's.
+ */
+function normalizePillarRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const bare = ref.replace(/\[\[|\]\]/g, '').trim().replace(/^["']|["']$/g, '');
+  return /^HS-PILR-[A-Za-z0-9-]+$/.test(bare) ? bare : null;
+}
+
+/**
+ * The authored `pillar:` on a milestone, as a bare id. Milestones have carried one
+ * since 2026-08-13 ([[pillar-assignment-protocol]] §Milestones), which makes it a
+ * reliable default for epics filed underneath them.
+ */
+function resolveMilestonePillar(vaultRoot, milestoneBasename) {
+  try {
+    const raw = readFileSync(
+      join(vaultRoot, 'specs', 'milestones', `${milestoneBasename}.md`),
+      'utf8',
+    );
+    const { frontmatter } = parseYamlFrontmatter(raw);
+    return normalizePillarRef(frontmatter.pillar);
+  } catch {
+    return null;
+  }
+}
+
+function resolveMilestoneFamily(vaultRoot, milestoneBasename) {
+  try {
+    const raw = readFileSync(
+      join(vaultRoot, 'specs', 'milestones', `${milestoneBasename}.md`),
+      'utf8',
+    );
+    const { frontmatter } = parseYamlFrontmatter(raw);
+    return familyOf({
+      id: frontmatter.id,
+      basename: milestoneBasename,
+      frontmatter: { family: frontmatter.family },
+    });
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Design system decisions (HS-EPIC-W9ZE)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DESIGN_DECISIONS = {
+  'scrollbar-transparent-track': {
+    summary: 'Use <ScrollArea> for ALL scrollable areas, not native overflow',
+    key_requirement: 'Import ScrollArea from @/components/scroll-area; do not use overflow: auto/scroll',
+    applies_to: ['console'],
+  },
+  'supabase-design-system-reference': {
+    summary: 'Use CSS variables from globals.css, not hardcoded colors',
+    key_requirement: 'Reference --bg-canvas, --text-primary, etc. instead of hex colors',
+    applies_to: ['console'],
+  },
+  'quick-panel-visual-language-windows11-alignment': {
+    summary: 'Square corners, 2px borders, mint accents for overlays',
+    key_requirement: 'No borderRadius or rounded-* classes in console components',
+    applies_to: ['console', 'companion'],
+  },
+  'console-agent-quick-start-box-styling': {
+    summary: 'Blue/green callout variants with documented color tokens',
+    key_requirement: 'Use #60a5fa (blue-400) or emerald variants for callout boxes',
+    applies_to: ['console'],
+  },
+};
+
+/**
+ * Detect if plan content mentions web-app file paths. Matches the current
+ * `spex-console/` paths and the legacy `cockpit/` ones (legacy-cockpit; older plan text still
+ * uses the pre-rename paths).
+ * @param {string} content - Plan markdown or epic body
+ * @returns {boolean}
+ */
+function detectConsolePaths(content) {
+  // Look for spex-console (and legacy-cockpit) file path patterns
+  const patterns = [
+    /(spex-console|cockpit)\/src\//i, // legacy-cockpit
+    /(spex-console|cockpit)\/components\//i, // legacy-cockpit
+    /(spex-console|cockpit)\/app\//i, // legacy-cockpit
+    /(spex-console|cockpit).*\.tsx/i, // legacy-cockpit
+    /(spex-console|cockpit).*\.ts/i, // legacy-cockpit
+    /\bsurface\b.*\b(tsx?|component)\b/i,
+  ];
+
+  return patterns.some(p => p.test(content));
+}
+
+/**
+ * Detect if plan content mentions companion file paths.
+ * @param {string} content - Plan markdown or epic body
+ * @returns {boolean}
+ */
+function detectCompanionPaths(content) {
+  const patterns = [
+    /companion\/desktop\//i,
+    /companion\/extension\//i,
+    /HeySpex\.Companion/i,
+    /\borb\b.*\b(winforms?|cs|component)\b/i,
+  ];
+
+  return patterns.some(p => p.test(content));
+}
+
+/**
+ * Get applicable design decisions based on plan content.
+ * @param {string} content - Plan markdown or epic body
+ * @returns {Array<{decision: string, applies_because: string, key_requirement: string}>}
+ */
+function getApplicableDesignDecisions(content) {
+  const decisions = [];
+  const touchesConsole = detectConsolePaths(content);
+  const touchesCompanion = detectCompanionPaths(content);
+
+  for (const [id, decision] of Object.entries(DESIGN_DECISIONS)) {
+    const applies = [];
+    if (touchesConsole && decision.applies_to.includes('console')) {
+      applies.push('spex-console/src/');
+    }
+    if (touchesCompanion && decision.applies_to.includes('companion')) {
+      applies.push('companion/');
+    }
+
+    if (applies.length > 0) {
+      decisions.push({
+        decision: id,
+        applies_because: `Plan touches ${applies.join(', ')}`,
+        key_requirement: decision.key_requirement,
+        summary: decision.summary,
+      });
+    }
+  }
+
+  return decisions;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Behavioral claim extraction and conflict detection (Phase 1)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts behavioral claims (action → outcome patterns) from markdown content.
+ * Looks for patterns in:
+ * - Tables with "Action/Gesture → Result/Outcome" columns
+ * - Bullet points with "X → Y" or "X: Y" patterns
+ * - NEXT STEP blocks with action descriptions
+ * @param {string} content - Markdown content
+ * @param {string} source - Source identifier for the claim
+ * @returns {Array<{action: string, outcome: string, source: string, section: string}>}
+ */
+export function extractBehavioralClaims(content, source) {
+  const claims = [];
+
+  // Normalize action strings for comparison
+  // Key insight: "click orb", "click (no drag)", "left-click", "orb click" should all normalize similarly
+  const normalizeAction = (action) => {
+    let normalized = action
+      .toLowerCase()
+      .replace(/\bleft-click\b/g, 'click')
+      .replace(/\bright-click\b/g, 'right-click')
+      .replace(/\bdouble-click\b/g, 'double-click')
+      .replace(/\bpress\b/g, 'click')
+      .replace(/\btap\b/g, 'click')
+      // Remove parenthetical qualifiers like "(no drag)" for comparison
+      .replace(/\s*\([^)]*\)\s*/g, ' ')
+      // Remove markdown formatting
+      .replace(/\*\*/g, '')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    // Normalize "X click" to "click X" for consistent matching
+    const swapMatch = normalized.match(/^(\w+)\s+(click|right-click|double-click)$/);
+    if (swapMatch) {
+      normalized = `${swapMatch[2]} ${swapMatch[1]}`;
+    }
+
+    return normalized;
+  };
+
+  // Extract current section name from content position
+  const getSectionAt = (text, position) => {
+    const beforePos = text.slice(0, position);
+    const sectionMatches = [...beforePos.matchAll(/^#+\s+(.+)$/gm)];
+    if (sectionMatches.length > 0) {
+      return sectionMatches[sectionMatches.length - 1][1].trim();
+    }
+    return 'Unknown section';
+  };
+
+  // Pattern 1: Multi-column tables with Action and Result/Outcome columns
+  // Find all markdown tables by splitting on lines and looking for table patterns
+  const lines = content.split(/\r?\n/);
+  let inTable = false;
+  let tableHeaders = [];
+  let actionColIdx = -1;
+  let resultColIdx = -1;
+  let tableStartLine = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Check if this is a table header row (starts and ends with |, contains column names)
+    if (line.startsWith('|') && line.endsWith('|') && !line.includes('---')) {
+      const cols = line.split('|').filter(c => c.trim() !== '');
+
+      // Check if next line is separator row
+      if (i + 1 < lines.length) {
+        const nextLine = lines[i + 1].trim();
+        if (nextLine.startsWith('|') && nextLine.includes('---')) {
+          // This is a header row followed by separator
+          tableHeaders = cols.map(h => h.trim().toLowerCase());
+
+          // Find action column index (Action, Gesture, etc.)
+          actionColIdx = tableHeaders.findIndex(h =>
+            h.includes('action') || h.includes('gesture') || h.includes('input')
+          );
+
+          // Find result column index (Result, Outcome, Effect, etc.)
+          resultColIdx = tableHeaders.findIndex(h =>
+            h.includes('result') || h.includes('outcome') || h.includes('effect') || h.includes('behavior')
+          );
+
+          if (actionColIdx !== -1 && resultColIdx !== -1) {
+            inTable = true;
+            tableStartLine = i;
+            i++; // Skip the separator line
+            continue;
+          }
+        }
+      }
+    }
+
+    // Process table body rows
+    if (inTable && line.startsWith('|') && line.endsWith('|')) {
+      // Check if we've reached end of table (empty line or non-table line)
+      if (line.includes('---') || !line.includes('|')) {
+        inTable = false;
+        continue;
+      }
+
+      const cols = line.split('|').filter(c => c !== '');
+
+      if (cols.length > Math.max(actionColIdx, resultColIdx)) {
+        const actionRaw = cols[actionColIdx].replace(/\*\*/g, '').trim();
+        const resultRaw = cols[resultColIdx].replace(/\*\*/g, '').trim();
+
+        // Skip if this looks like a header or separator
+        if (actionRaw.includes('---') || resultRaw.includes('---')) continue;
+        if (actionRaw.toLowerCase() === 'action' || actionRaw.toLowerCase() === 'gesture') continue;
+
+        // Check if this looks like an action
+        const actionKeywords = ['click', 'drag', 'press', 'tap', 'hold', 'hotkey', 'escape', 'enter', 'right-click', 'shell'];
+        const lowerAction = actionRaw.toLowerCase();
+        if (actionKeywords.some(kw => lowerAction.includes(kw))) {
+          // Calculate approximate position for section lookup
+          const textBeforeLine = lines.slice(0, i).join('\n');
+          claims.push({
+            action: normalizeAction(actionRaw),
+            outcome: resultRaw,
+            source,
+            section: getSectionAt(content, textBeforeLine.length),
+            raw_action: actionRaw,
+          });
+        }
+      }
+    } else if (inTable && !line.startsWith('|')) {
+      // End of table
+      inTable = false;
+    }
+  }
+
+  // Pattern 1b: Simple 2-column tables (fallback for tables without clear headers)
+  const simpleTablePattern = /^\|\s*\*?\*?([^|*]+)\*?\*?\s*\|\s*([^|]+)\s*\|$/gm;
+  let simpleMatch;
+  while ((simpleMatch = simpleTablePattern.exec(content)) !== null) {
+    const col1 = simpleMatch[1].trim();
+    const col2 = simpleMatch[2].trim();
+
+    // Skip if already captured by multi-column parser, or if header/separator
+    if (col1.toLowerCase().includes('action') ||
+        col1.toLowerCase().includes('gesture') ||
+        col1.includes('---') ||
+        col2.includes('---')) {
+      continue;
+    }
+
+    // Skip ASCII art / UI mockups (lines with box drawing characters or many special chars)
+    if (col2.includes('│') || col2.includes('─') || col2.includes('═') ||
+        col2.includes('┌') || col2.includes('└') || col2.includes('□') ||
+        col2.length > 100) {
+      continue;
+    }
+
+    // Check if this looks like an action (contains click, drag, press, tap, etc.)
+    const actionKeywords = ['click', 'drag', 'press', 'tap', 'hold', 'hotkey', 'escape', 'enter', 'right-click', 'shell'];
+    const lowerCol1 = col1.toLowerCase();
+    if (actionKeywords.some(kw => lowerCol1.includes(kw))) {
+      // Check if we already have this claim (from multi-column parser)
+      const normalized = normalizeAction(col1);
+      const exists = claims.some(c => c.action === normalized && c.section === getSectionAt(content, simpleMatch.index));
+      if (!exists) {
+        claims.push({
+          action: normalized,
+          outcome: col2.replace(/\*\*/g, '').trim(),
+          source,
+          section: getSectionAt(content, simpleMatch.index),
+          raw_action: col1,
+        });
+      }
+    }
+  }
+
+  // Pattern 2: Bullet points with "action → outcome" or "action: outcome"
+  const bulletPattern = /^[\s]*[-*]\s*\*?\*?([^:\n→]+)\*?\*?\s*[→:]\s*(.+)$/gm;
+  let bulletMatch;
+  while ((bulletMatch = bulletPattern.exec(content)) !== null) {
+    const action = bulletMatch[1].trim();
+    const outcome = bulletMatch[2].trim();
+
+    const actionKeywords = ['click', 'drag', 'press', 'tap', 'hold', 'hotkey', 'left-click', 'right-click'];
+    const lowerAction = action.toLowerCase();
+    if (actionKeywords.some(kw => lowerAction.includes(kw))) {
+      claims.push({
+        action: normalizeAction(action),
+        outcome: outcome.replace(/\*\*/g, '').trim(),
+        source,
+        section: getSectionAt(content, bulletMatch.index),
+        raw_action: action,
+      });
+    }
+  }
+
+  // Pattern 3: Prose descriptions like "Click X toggles Y" or "X click opens Y"
+  const prosePatterns = [
+    /\b(click(?:ing)?|left-click|right-click|drag(?:ging)?|press(?:ing)?|tap(?:ping)?)\s+(\w+(?:\s+\w+)?)\s+(toggles?|opens?|shows?|hides?|closes?|activates?|triggers?|repositions?)\s+([^.;,\n│─═┌└□]+)/gi,
+    /\b(\w+(?:\s+\w+)?)\s+(click|left-click|right-click)\s+(toggles?|opens?|shows?|hides?|closes?|activates?|triggers?)\s+([^.;,\n│─═┌└□]+)/gi,
+  ];
+
+  for (const pattern of prosePatterns) {
+    let proseMatch;
+    while ((proseMatch = pattern.exec(content)) !== null) {
+      // Skip if we're in ASCII art (check surrounding context)
+      const contextStart = Math.max(0, proseMatch.index - 100);
+      const contextEnd = Math.min(content.length, proseMatch.index + proseMatch[0].length + 100);
+      const context = content.slice(contextStart, contextEnd);
+      if (context.includes('│') || context.includes('─') || context.includes('═') ||
+          context.includes('┌') || context.includes('└') || context.includes('□')) {
+        continue;
+      }
+
+      // Determine action and outcome based on capture groups
+      let action, outcome;
+      if (proseMatch[1].toLowerCase().match(/^(click|left-click|right-click|drag|press|tap)/i)) {
+        // Pattern 1: "click orb toggles shell"
+        action = `${proseMatch[1]} ${proseMatch[2]}`;
+        outcome = `${proseMatch[3]} ${proseMatch[4]}`;
+      } else {
+        // Pattern 2: "orb click toggles shell"
+        action = `${proseMatch[2]} ${proseMatch[1]}`;
+        outcome = `${proseMatch[3]} ${proseMatch[4]}`;
+      }
+
+      // Skip if outcome is too long (likely extracted garbage)
+      if (outcome.length > 100) continue;
+
+      claims.push({
+        action: normalizeAction(action),
+        outcome: outcome.trim(),
+        source,
+        section: getSectionAt(content, proseMatch.index),
+        raw_action: action.trim(),
+      });
+    }
+  }
+
+  // Deduplicate claims by action + outcome (keep first occurrence)
+  const seen = new Set();
+  const dedupedClaims = [];
+  for (const claim of claims) {
+    const key = `${claim.action}|${claim.outcome.slice(0, 50).toLowerCase()}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      dedupedClaims.push(claim);
+    }
+  }
+
+  return dedupedClaims;
+}
+
+/**
+ * Compares claims from epic against claims from linked protocols.
+ * @param {Array} epicClaims - Claims extracted from the epic
+ * @param {Array} protocolClaims - Claims extracted from linked protocols
+ * @returns {Array<{epic_claim: string, spec_claim: string, spec: string, section: string, action: string}>}
+ */
+export function findConflicts(epicClaims, protocolClaims) {
+  const conflicts = [];
+
+  // Build a map of protocol claims by normalized action
+  const protocolByAction = new Map();
+  for (const claim of protocolClaims) {
+    const key = claim.action;
+    if (!protocolByAction.has(key)) {
+      protocolByAction.set(key, []);
+    }
+    protocolByAction.get(key).push(claim);
+  }
+
+  // Helper: check if two actions are semantically the same
+  const actionsMatch = (a1, a2) => {
+    if (a1 === a2) return true;
+
+    // Extract the core action (click, drag, etc.) and target (orb, shell, etc.)
+    const extractParts = (action) => {
+      const verb = action.match(/^(click|right-click|double-click|drag|press|tap|hold|hotkey)/)?.[1] || '';
+      const target = action.replace(/^(click|right-click|double-click|drag|press|tap|hold|hotkey)\s*/, '').trim();
+      return { verb, target };
+    };
+
+    const p1 = extractParts(a1);
+    const p2 = extractParts(a2);
+
+    // Same verb and overlapping target
+    if (p1.verb === p2.verb) {
+      // "click orb" matches "click" if one is more specific
+      if (!p1.target || !p2.target) return true;
+      // Both have targets - check for overlap
+      return p1.target.includes(p2.target) || p2.target.includes(p1.target);
+    }
+
+    return false;
+  };
+
+  // Compare each epic claim against protocol claims
+  for (const epicClaim of epicClaims) {
+    // Find matching protocol claims (by exact match or semantic similarity)
+    const matchingProtocolClaims = [];
+
+    for (const [protoAction, protoClaims] of protocolByAction.entries()) {
+      if (actionsMatch(epicClaim.action, protoAction)) {
+        matchingProtocolClaims.push(...protoClaims);
+      }
+    }
+
+    for (const protoClaim of matchingProtocolClaims) {
+      // Check if outcomes conflict (different verbs or targets)
+      const epicOutcome = epicClaim.outcome.toLowerCase();
+      const protoOutcome = protoClaim.outcome.toLowerCase();
+
+      // Define synonym groups for verbs
+      const verbSynonyms = {
+        'move': ['move', 'reposition', 'drag', 'relocate'],
+        'open': ['open', 'show', 'display', 'reveal'],
+        'close': ['close', 'hide', 'dismiss'],
+        'toggle': ['toggle'],
+        'activate': ['activate', 'trigger', 'start', 'enable'],
+      };
+
+      // Normalize verb to its canonical form
+      const normalizeVerb = (verb) => {
+        if (!verb) return null;
+        verb = verb.replace(/s$/, '').toLowerCase();
+        for (const [canonical, synonyms] of Object.entries(verbSynonyms)) {
+          if (synonyms.includes(verb)) return canonical;
+        }
+        return verb;
+      };
+
+      // Extract main verb from outcomes
+      const extractVerb = (outcome) => {
+        const verbMatch = outcome.match(/\b(toggles?|opens?|shows?|hides?|closes?|activates?|triggers?|repositions?|moves?|displays?|dismisses?)\b/i);
+        return verbMatch ? normalizeVerb(verbMatch[1]) : null;
+      };
+
+      // Extract main target from outcomes (what is being opened/toggled/etc.)
+      const extractTarget = (outcome) => {
+        // Look for key UI elements
+        const targetMatch = outcome.match(/\b(shell|action panel|panel|window|menu|settings|inbox|form|orb)\b/i);
+        return targetMatch ? targetMatch[1].toLowerCase() : null;
+      };
+
+      const epicVerb = extractVerb(epicOutcome);
+      const protoVerb = extractVerb(protoOutcome);
+      const epicTarget = extractTarget(epicOutcome);
+      const protoTarget = extractTarget(protoOutcome);
+
+      // No conflict if verbs are in the same synonym group
+      if (epicVerb && protoVerb && epicVerb === protoVerb) {
+        // Same canonical verb - check if targets conflict
+        if (!epicTarget || !protoTarget) continue; // Can't determine target, no conflict
+        if (epicTarget === protoTarget) continue; // Same target, no conflict
+        if (epicTarget === 'orb' || protoTarget === 'orb') continue; // "orb" is the subject, not a target
+      }
+
+      // Conflict scenarios:
+      // 1. Different verbs for the same action (toggle vs open)
+      const verbConflict = epicVerb && protoVerb && epicVerb !== protoVerb;
+
+      // 2. Same verb but different targets (opens shell vs opens action panel)
+      const targetConflict = epicVerb && protoVerb && epicVerb === protoVerb &&
+                            epicTarget && protoTarget && epicTarget !== protoTarget &&
+                            epicTarget !== 'orb' && protoTarget !== 'orb';
+
+      // 3. One says toggle and the other says open (these are different behaviors)
+      const semanticConflict = (epicVerb === 'toggle' && protoVerb === 'open') ||
+                              (epicVerb === 'open' && protoVerb === 'toggle');
+
+      if (verbConflict || targetConflict || semanticConflict) {
+        // Avoid duplicate conflicts
+        const conflictKey = `${epicClaim.action}|${protoClaim.source}`;
+        const exists = conflicts.some(c =>
+          `${c.action}|${c.spec}` === conflictKey
+        );
+
+        if (!exists) {
+          conflicts.push({
+            action: epicClaim.raw_action || epicClaim.action,
+            epic_claim: `${epicClaim.raw_action || epicClaim.action} → ${epicClaim.outcome}`,
+            spec_claim: `${protoClaim.raw_action || protoClaim.action} → ${protoClaim.outcome}`,
+            spec: protoClaim.source,
+            section: `§${protoClaim.section}`,
+            epic_section: `§${epicClaim.section}`,
+            conflict_type: verbConflict ? 'verb_mismatch' : (targetConflict ? 'target_mismatch' : 'semantic'),
+          });
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+/**
+ * Extracts wikilinks from a related: frontmatter array or markdown content.
+ * @param {Array|string} related - The related field from frontmatter or markdown body
+ * @returns {string[]} - Array of basenames (without [[ ]])
+ */
+export function extractWikilinks(related) {
+  const links = [];
+
+  if (Array.isArray(related)) {
+    for (const item of related) {
+      const match = String(item).match(/\[\[([^\]]+)\]\]/);
+      if (match) {
+        links.push(match[1]);
+      }
+    }
+  } else if (typeof related === 'string') {
+    const matches = related.matchAll(/\[\[([^\]]+)\]\]/g);
+    for (const match of matches) {
+      links.push(match[1]);
+    }
+  }
+
+  return links;
+}
+
+/** Wikilinks under `## Related` in spec body markdown. */
+export function extractRelatedSectionWikilinks(body) {
+  const section = body.match(/## Related\s*\n([\s\S]*?)(?=\n## |\n---|\Z)/i);
+  if (!section?.[1]) return [];
+  const links = [];
+  const regex = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+  let match;
+  while ((match = regex.exec(section[1])) !== null) {
+    links.push(String(match[1]).trim().replace(/\.md$/i, ''));
+  }
+  return links;
+}
+
+/** Merge frontmatter `related:` with body `## Related` wikilinks (deduped). */
+export function collectEpicRelatedLinks(frontmatterRelated, body) {
+  const seen = new Set();
+  const out = [];
+  for (const link of [
+    ...extractWikilinks(frontmatterRelated),
+    ...extractRelatedSectionWikilinks(body || ''),
+  ]) {
+    const key = link.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(link);
+  }
+  return out;
+}
+
+/** NEXT STEP + acceptance criteria — scope for conflict checks (not problem narrative). */
+export function extractConflictCheckContent(body) {
+  const parts = [];
+  const nextStep = body.match(/```[^\n]*NEXT STEP[^\n]*\n([\s\S]*?)```/i);
+  if (nextStep?.[1]?.trim()) parts.push(nextStep[1].trim());
+  const acceptance = body.match(
+    /## Acceptance criteria\s*\n([\s\S]*?)(?=\n## |\n---|\Z)/i,
+  );
+  if (acceptance?.[1]?.trim()) parts.push(acceptance[1].trim());
+  return parts.join('\n\n');
+}
+
+/**
+ * Resolves a wikilink basename to a file path in the vault.
+ * @param {string} vaultRoot - Root of the vault
+ * @param {string} basename - The wikilink basename
+ * @returns {string|null} - Full path if found, null otherwise
+ */
+export function resolveWikilink(vaultRoot, basename) {
+  // Check common locations for protocols and specs
+  const locations = [
+    `specs/protocols/${basename}.md`,
+    `specs/tasks/${basename}.md`,
+    `specs/epics/${basename}.md`,
+    `specs/memory/decisions/${basename}.md`,
+    `specs/memory/lessons/${basename}.md`,
+    `specs/memory/references/${basename}.md`,
+    `specs/research/${basename}.md`,
+  ];
+
+  for (const loc of locations) {
+    const fullPath = join(vaultRoot, loc);
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+
+  // Search by prefix in specs directories
+  const specDirs = ['specs/protocols', 'specs/tasks', 'specs/epics'];
+  for (const dir of specDirs) {
+    const dirPath = join(vaultRoot, dir);
+    if (!existsSync(dirPath)) continue;
+
+    try {
+      const files = readdirSync(dirPath);
+      for (const file of files) {
+        if (file.startsWith(basename) && file.endsWith('.md')) {
+          return join(dirPath, file);
+        }
+      }
+    } catch {
+      // Directory doesn't exist or isn't readable
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Detects behavioral conflicts between an epic and its linked protocols.
+ * @param {string} vaultRoot - Root of the vault
+ * @param {string} epicContent - The full markdown content of the epic
+ * @param {Array} relatedLinks - Array of related wikilink basenames
+ * @returns {{conflicts: Array, linked_specs_checked: string[]}}
+ */
+export function detectSpecConflicts(vaultRoot, epicContent, relatedLinks) {
+  const conflicts = [];
+  const linkedSpecsChecked = [];
+
+  const epicClaims = extractBehavioralClaims(
+    extractConflictCheckContent(epicContent),
+    'epic',
+  );
+
+  if (epicClaims.length === 0) {
+    return { conflicts: [], linked_specs_checked: [] };
+  }
+
+  // Check each linked protocol/spec for conflicts
+  for (const basename of relatedLinks) {
+    const specPath = resolveWikilink(vaultRoot, basename);
+    if (!specPath) continue;
+
+    try {
+      const specContent = readFileSync(specPath, 'utf8');
+      linkedSpecsChecked.push(basename);
+
+      // Extract claims from the protocol
+      const protocolClaims = extractBehavioralClaims(specContent, basename);
+
+      // Find conflicts
+      const specConflicts = findConflicts(epicClaims, protocolClaims);
+      conflicts.push(...specConflicts);
+    } catch {
+      // Skip files that can't be read
+    }
+  }
+
+  return { conflicts, linked_specs_checked: linkedSpecsChecked };
+}
+
+const VAULT_ID_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+const VAULT_ID_MIN_SUFFIX_LENGTH = 4;
+// Family-first ([[HS-EPIC-DLE3]]): mint HS-<key>-<TYPE>; parse ids dual-read.
+const KIND_TYPE_LABEL = { task: 'TASK', epic: 'EPIC' };
+
+import { deriveSlug } from './promotion-helpers.mjs';
+export { deriveSlug };
+
+function randomSuffix(length, charset = VAULT_ID_CHARSET) {
+  let out = '';
+  for (let i = 0; i < length; i++) {
+    out += charset[Math.floor(Math.random() * charset.length)];
+  }
+  return out;
+}
+
+function capacity(charset, length) {
+  return charset.length ** length;
+}
+
+function suffixLengthForId(kind, id) {
+  const p = parseSpecId(id);
+  return p && p.typeLabel === KIND_TYPE_LABEL[kind] ? p.familyKey.length : null;
+}
+
+function countIdsAtSuffixLength(kind, occupied, length) {
+  let n = 0;
+  for (const id of occupied) {
+    if (suffixLengthForId(kind, id) === length) n++;
+  }
+  return n;
+}
+
+export function allocateRandomVaultId(kind, occupied) {
+  let length = VAULT_ID_MIN_SUFFIX_LENGTH;
+  const typeLabel = KIND_TYPE_LABEL[kind];
+
+  while (true) {
+    const usedAtLength = countIdsAtSuffixLength(kind, occupied, length);
+    if (usedAtLength >= capacity(VAULT_ID_CHARSET, length)) {
+      length++;
+      continue;
+    }
+    const maxAttempts = Math.min(capacity(VAULT_ID_CHARSET, length) - usedAtLength, 10_000);
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const suffix = randomSuffix(length);
+      const id = `HS-${suffix}-${typeLabel}`; // family-first
+      if (!occupied.has(id)) return id;
+    }
+    length++;
+  }
+}
+
+export function collectOccupiedVaultIds(vaultRoot) {
+  const tasks = new Set();
+  const epics = new Set();
+
+  // Normalize ids/basenames of EITHER ordering to the canonical family-first form
+  // so suffix-collision detection works mid-migration ([[HS-EPIC-DLE3]]).
+  const scanDir = (subdir, kind) => {
+    const dir = join(vaultRoot, 'specs', subdir);
+    if (!existsSync(dir)) return;
+    const target = kind === 'task' ? tasks : epics;
+    const add = (value) => {
+      const p = parseSpecId(value);
+      if (p && p.typeLabel === KIND_TYPE_LABEL[kind]) target.add(`HS-${p.familyKey}-${p.typeLabel}`);
+    };
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.md') || file.endsWith('.review.md')) continue;
+      add(file.replace(/\.md$/i, ''));
+      try {
+        const raw = readFileSync(join(dir, file), 'utf8');
+        const idMatch = raw.match(/^id:\s*(\S+)/m);
+        if (idMatch) add(idMatch[1].replace(/^['"]|['"]$/g, ''));
+      } catch {
+        // skip
+      }
+    }
+  };
+
+  scanDir('tasks', 'task');
+  scanDir('epics', 'epic');
+  return { tasks, epics };
+}
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+/**
+ * Parses YAML frontmatter from a markdown file.
+ * @param {string} content - Full markdown file content
+ * @returns {{frontmatter: object, body: string, raw: string}}
+ */
+function parseYamlFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content, raw: '' };
+
+  const rawFm = match[1];
+  const body = match[2];
+
+  // Simple YAML parser for our use case
+  const frontmatter = {};
+  const lines = rawFm.split(/\r?\n/);
+  let currentKey = null;
+  let currentArray = null;
+  let inNestedObject = false;
+  let nestedKey = null;
+  let nestedArray = null;
+
+  for (const line of lines) {
+    // Skip empty lines
+    if (!line.trim()) continue;
+
+    // Check indentation level
+    const indent = line.match(/^(\s*)/)[1].length;
+
+    if (indent === 0 && line.includes(':')) {
+      // Top-level key
+      const [key, ...valueParts] = line.split(':');
+      const value = valueParts.join(':').trim();
+      currentKey = key.trim();
+
+      if (value === '' || value === '[]') {
+        frontmatter[currentKey] = [];
+        currentArray = frontmatter[currentKey];
+      } else if (value.startsWith("'") || value.startsWith('"')) {
+        frontmatter[currentKey] = value.replace(/^['"]|['"]$/g, '');
+        currentArray = null;
+      } else {
+        frontmatter[currentKey] = value;
+        currentArray = null;
+      }
+      inNestedObject = false;
+    } else if (indent > 0 && line.trim().startsWith('- ')) {
+      // Array item
+      const itemValue = line.trim().slice(2).trim().replace(/^['"]|['"]$/g, '');
+      if (currentArray) {
+        currentArray.push(itemValue);
+      }
+    }
+  }
+
+  return { frontmatter, body, raw: rawFm };
+}
+
+/**
+ * Adds an epic ID to a phase in a roadmap manifest.
+ * @param {string} vaultRoot - Root of the vault
+ * @param {string} roadmapId - Roadmap ID (e.g., 'HS-ROADMAP-PRODUCT')
+ * @param {string} phaseId - Phase ID (e.g., 'P0')
+ * @param {string} epicBasename - Epic basename to add (e.g., 'HS-EPIC-W5X8-some-slug')
+ * @returns {{success: boolean, message: string}}
+ */
+export function addEpicToRoadmapPhase(vaultRoot, roadmapId, phaseId, epicBasename) {
+  // Find the roadmap file
+  const roadmapDir = join(vaultRoot, 'specs', 'roadmaps');
+  if (!existsSync(roadmapDir)) {
+    return { success: false, message: 'specs/roadmaps directory not found' };
+  }
+
+  const files = readdirSync(roadmapDir);
+  let roadmapFile = null;
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const filePath = join(roadmapDir, file);
+    const content = readFileSync(filePath, 'utf8');
+    if (content.includes(`id: ${roadmapId}`) || content.includes(`id: '${roadmapId}'`)) {
+      roadmapFile = filePath;
+      break;
+    }
+  }
+
+  if (!roadmapFile) {
+    return { success: false, message: `Roadmap ${roadmapId} not found` };
+  }
+
+  const content = readFileSync(roadmapFile, 'utf8');
+
+  // Find the phase in the roadmap_manifest
+  // Look for the pattern: - id: P0\n      name: ...\n      tasks:\n        - task1\n        - task2
+  const phasePattern = new RegExp(
+    `(- id: ${phaseId}\\s*\\n\\s*name:[^\\n]*\\n\\s*summary:[^\\n]*\\n\\s*tasks:\\s*\\n)((?:\\s*- [^\\n]+\\n)*)`,
+    'm'
+  );
+
+  const match = content.match(phasePattern);
+  if (!match) {
+    return { success: false, message: `Phase ${phaseId} not found in roadmap ${roadmapId}` };
+  }
+
+  // Check if epic is already in the phase
+  if (match[2].includes(epicBasename)) {
+    return { success: true, message: `Epic ${epicBasename} already in phase ${phaseId}` };
+  }
+
+  // Add the epic to the end of the tasks list
+  const existingTasks = match[2];
+  const indent = existingTasks.match(/^(\s*)-/m)?.[1] || '        ';
+  const newTasks = existingTasks + `${indent}- ${epicBasename}\n`;
+
+  const updatedContent = content.replace(phasePattern, `$1${newTasks}`);
+  writeFileSync(roadmapFile, updatedContent, 'utf8');
+
+  return { success: true, message: `Added ${epicBasename} to phase ${phaseId} in ${roadmapId}` };
+}
+
+function todayDate() {
+  return isoNow().slice(0, 10);
+}
+
+// YAML scalar quoting lives in the shared, dependency-free helper so every
+// frontmatter writer uses one correct rule ([[yaml-scalar]]). The old inline
+// regex only quoted when a value *contained* `:`/`"`, letting values that
+// START with a backtick or quote corrupt the frontmatter.
+const yamlQuote = yamlScalar;
+
+export function buildPushWorkflowMarkdown(options = {}) {
+  const onDeck = options.on_deck === true;
+  const title = onDeck ? 'hs-push-next' : 'hs-push';
+  const lines = [
+    `# HeySpex ${title} — push epic plan to the vault`,
+    '',
+    'Use the **implementation plan from this conversation** (or the user paste below) as source material.',
+    '',
+    '### Plan ingest (required)',
+    '',
+    'External plans (Cursor `~/.cursor/plans/*.plan.md`, repo `.cursor/plans/`, or `source_plan_paths`) are **read and copied into the vault spec** under `## Canonical implementation plan (HeySpex)`. Do not leave specs that only point at proprietary paths — Claude Code cannot read them.',
+    '',
+    'Pass `source_plan_paths` when the plan file path is known (e.g. from Cursor Plan mode). The tool also auto-detects `.plan.md` references inside `plan_markdown` / `implementation_prompt`.',
+    '',
+    '## Workflow',
+    '',
+    '### 1. Write specs ([[plan-ingest-agent-workflow]])',
+    '',
+    '**Preferred:** call MCP tool `heyspex_push_plan` with structured fields (epic_name, **summary**, plan_markdown, implementation_prompt, source_plan_paths[], on_deck). **Do not pass `children`** — tasks are filed just-in-time via `/hs-next` breakdown + `heyspex_file_spec` ([[spec-hierarchy]] §empty-state grain-split).',
+    '',
+    '**Or hand-author (plan ingest — epic/milestone only):**',
+    '',
+    '- Epic: `specs/epics/HS-EPIC-<id>-<slug>.md` — use `POST /api/specs` or random ID per [[vault-id-assignment-protocol]]; **`children: []`**',
+    '- Milestone: `specs/milestones/HS-MIL-<id>-<slug>.md` when filing a milestone in the same planning wave',
+    '- Do **not** hand-author task files here — tasks come from `/hs-next` breakdown + `heyspex_file_spec`',
+    '- Do **not** set duplicate numeric epic slots',
+    '',
+    '### 2. Validate IDs',
+    '',
+    '```bash',
+    'npm run validate:vault-ids',
+    '```',
+    '',
+    '### 3. Linkage + roadmap',
+    '',
+    '- `heyspex_validate_linkage` — fix orphans',
+    '- `heyspex_register_spec` — add epic (or milestone) to manifest phase when appropriate',
+    '',
+  ];
+
+  if (onDeck) {
+    lines.push(
+      '### 4. On deck ([[HS-TASK-HS0U-local-mcp-hs-next-on-deck-prompt]])',
+      '',
+      'When `on_deck: true` (hs-push-next), the push tool also:',
+      '',
+      '- Sets epic `status: in_progress`',
+      '- Writes `.heyspex/focus.yaml` (`kind: epic`, `spec_path`)',
+      '- Adds epic **NEXT STEP** fenced block (` ```NEXT STEP `) with `implementation_prompt`',
+      '- Adds On deck callout at top of epic body',
+      '',
+      'Then run `heyspex_next_on_deck` or `/hs-next` to pull the prompt.',
+      '',
+      'Record the WIP ledger (`heyspex_record_wip`) for the epic if this supersedes prior focus — the prose next-session-handoff.md is retired (HS-EPIC-HNDR).',
+      '',
+      '### 5. Conflict pre-flight ([[HS-EPIC-6RKN-spec-conflict-detection-pre-flight-check]])',
+      '',
+      'Before any files are written, the tool extracts behavioral claims (click/drag/hotkey patterns) from the NEXT STEP + acceptance criteria and compares them against the `related:` linked specs. If contradictions are found:',
+      '',
+      '- The push is **blocked** with `error: "CONFLICTS_DETECTED"` and a `conflicts[]` payload — **no files written, no focus pinned**.',
+      '- Resolution: edit the plan to match the linked spec, edit the linked spec to match the plan, or re-run with `skip_conflict_check: true` to force.',
+      '- After landing, dismissed conflicts can be recorded via the console `Dismiss with reason…` action (writes `conflict_override:` to epic frontmatter).',
+      '',
+    );
+  }
+
+  lines.push(
+    '## Rules',
+    '',
+    '- Vault is the only queue — track work in specs, not ad-hoc todos',
+    '- Do not commit unless the user asks',
+    '- After push, offer to run validate + linkage tools',
+    '',
+  );
+
+  if (options.epic_name) {
+    lines.push(`## Target epic name`, '', options.epic_name, '');
+  }
+  if (options.plan_hint) {
+    lines.push('## Plan hint', '', options.plan_hint, '');
+  }
+
+  return lines.join('\n');
+}
+
+function buildNextStepSection(implementationPrompt) {
+  const body = implementationPrompt?.trim() || [
+    '# Task: Implement this epic',
+    '',
+    'CONTEXT: (fill from epic)',
+    '',
+    'Read the epic body and [[CLAUDE.md]]. Break into tasks via `/hs-next` if `children: []`.',
+    '',
+    'VALIDATION: npm run validate:vault-ids; relevant tests',
+    '',
+    'OUTPUT: summary + spec updates. Do not commit unless asked.',
+  ].join('\n');
+
+  return [
+    '',
+    '## NEXT STEP: Ready-to-paste prompt',
+    '',
+    'Copy the fenced block below into a **new agent session**, or run `heyspex_next_on_deck` / `/hs-next` when focus is pinned.',
+    '',
+    '```NEXT STEP',
+    body,
+    '```',
+    '',
+  ].join('\n');
+}
+
+function buildOnDeckBanner(reason) {
+  return [
+    '> [!important] On deck',
+    `> **Status:** \`in_progress\` — console On Deck + MCP (\`heyspex_next_on_deck\`, \`/hs-next\`).`,
+    `> Pin: \`.heyspex/focus.yaml\`${reason ? ` — ${reason}` : ''}.`,
+    '',
+  ].join('\n');
+}
+
+// Focus is persisted to Neon `focus_selection` by the async caller
+// (cli.mjs `writeFocusSelectionVendor` → PUT /api/control/focus-selection),
+// which also records the focus-history event. There is no `.heyspex/focus.yaml`
+// / `focus-history.jsonl` writer here anymore ([[no-fallbacks-by-default]]; the
+// focus.yaml-fallback incident).
+
+export function executePushPlan(vaultRoot, args) {
+  const {
+    epic_name: epicName,
+    summary: epicSummaryArg,
+    plan_markdown: planMarkdown = '',
+    implementation_prompt: implementationPrompt,
+    source_plan_paths: sourcePlanPaths = [],
+    children = [],
+    on_deck: onDeck = false,
+    focus_reason: focusReason,
+    kind = 'feature',
+    effort = 3,
+    tags = [],
+    related = [],
+    skip_conflict_check: skipConflictCheck = false,
+    milestone,
+  } = args;
+
+  if (!epicName?.trim()) {
+    return { error: 'MISSING_EPIC_NAME', message: 'epic_name is required' };
+  }
+
+  const epicSummary = resolveAuthoredSummaryValue(epicSummaryArg);
+  if (!epicSummary) {
+    return buildSummaryRequiredMcpError('epic');
+  }
+
+  if (Array.isArray(children) && children.some((c) => c?.name?.trim())) {
+    return {
+      error: 'CHILDREN_NOT_SUPPORTED',
+      message:
+        'heyspex_push_plan files the epic only (`children: []`). File tasks just-in-time from the What\'s Next `/hs-next` breakdown via `heyspex_file_spec` with `summary` — not via push_plan ([[spec-hierarchy]] §empty-state grain-split).',
+      procedure: 'spec-hierarchy',
+    };
+  }
+
+  const milestoneResolved = resolveMilestoneArg(vaultRoot, milestone);
+  if (milestoneResolved.error) {
+    return milestoneResolved;
+  }
+
+  const prepared = prepareVaultPlanContent(vaultRoot, {
+    plan_markdown: planMarkdown,
+    implementation_prompt: implementationPrompt,
+    source_plan_paths: sourcePlanPaths,
+  });
+
+  // V3 file-key-first minting ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]):
+  // `id:` keys onto the file key alone; the epic inherits its milestone
+  // parent's family (falls back to a fresh mint if the milestone has none —
+  // defensive, should not occur for a real milestone).
+  const epicFamilyKey =
+    resolveMilestoneFamily(vaultRoot, milestoneResolved.basename) ?? mintFamilyKey(vaultRoot);
+  // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+  // and (V3) the anchor for `id:` itself.
+  const epicFileKey = allocateFileKey(collectOccupiedFileKeysFromVault(vaultRoot));
+  const epicId = `HS-${epicFileKey}`;
+
+  const epicSlug = deriveSlug(epicName);
+  const epicBasename = `${epicId}-${epicFamilyKey}-EPIC-${epicSlug}`;
+  const epicRelPath = `specs/epics/${epicBasename}.md`;
+  const now = isoNow();
+  const summaryYaml = formatSummaryFrontmatterField(epicSummary);
+  let epicBody =
+    prepared.plan_markdown.trim() || `# ${epicName}\n\n## Goal\n\n_Describe outcome._\n`;
+  const preparedPrompt = prepared.implementation_prompt;
+  if (onDeck) {
+    epicBody = `${buildOnDeckBanner(focusReason)}\n${epicBody}`;
+    // [[HS-TASK-G0HF]] the `## NEXT STEP` block is now an OPTIONAL authored
+    // override — only emit it when an implementation_prompt was actually
+    // supplied. Without one, `/hs-next` derives the brief from the epic's
+    // acceptance criteria (no required NEXT STEP block, no NO_NEXT_STEP error).
+    if (preparedPrompt?.trim()) {
+      epicBody += buildNextStepSection(preparedPrompt);
+    }
+  }
+
+  const childrenYaml = 'children: []';
+
+  const tagsYaml =
+    tags.length > 0 ? `tags:\n${tags.map((t) => `  - ${t}`).join('\n')}` : 'tags:\n  - epic';
+
+  // Build related links array (user-provided + defaults)
+  const userRelatedLinks = Array.isArray(related) ? related : [];
+  const allRelatedLinks = [
+    ...userRelatedLinks.map(r => {
+      // Normalize to wikilink format
+      const basename = String(r).replace(/^\[\[|\]\]$/g, '');
+      return `[[${basename}]]`;
+    }),
+    '[[plan-ingest-agent-workflow]]',
+    '[[vault-id-assignment-protocol]]',
+  ];
+  // Dedupe while preserving order
+  const uniqueRelated = [...new Set(allRelatedLinks)];
+  const relatedYaml = uniqueRelated.length > 0
+    ? `related:\n${uniqueRelated.map(r => `  - '${r}'`).join('\n')}`
+    : 'related: []';
+
+  // Pre-flight conflict detection (HS-EPIC-6RKN Phase 3).
+  // For on_deck pushes, block before writing files so the agent fixes the
+  // plan first. /hs-push (no on_deck) reports conflicts in next_steps but
+  // doesn't block — the spec is still useful as a draft.
+  let preflightConflicts = [];
+  let preflightLinkedSpecs = [];
+  if (!skipConflictCheck && userRelatedLinks.length > 0) {
+    const fullEpicContent = [epicBody, preparedPrompt || ''].join('\n');
+    const relatedBasenames = userRelatedLinks.map((r) =>
+      String(r).replace(/^\[\[|\]\]$/g, ''),
+    );
+    const conflictResult = detectSpecConflicts(
+      vaultRoot,
+      fullEpicContent,
+      relatedBasenames,
+    );
+    preflightConflicts = conflictResult.conflicts;
+    preflightLinkedSpecs = conflictResult.linked_specs_checked;
+
+    if (onDeck && preflightConflicts.length > 0) {
+      return {
+        error: 'CONFLICTS_DETECTED',
+        success: false,
+        on_deck: true,
+        blocked: true,
+        message: `${preflightConflicts.length} behavioral conflict(s) detected against linked spec(s). Resolve them or pass skip_conflict_check: true to force the push.`,
+        conflicts: preflightConflicts,
+        linked_specs_checked: preflightLinkedSpecs,
+        has_conflicts: true,
+        next_steps: [
+          'Review the conflicts below — each shows a behavioral claim in this plan that contradicts a linked spec.',
+          'Resolution options:',
+          '  • Edit the NEXT STEP / acceptance criteria in plan_markdown to match the linked spec, then re-run heyspex_push_plan.',
+          '  • Edit the linked spec (its Interaction model section) to match this plan, then re-run heyspex_push_plan.',
+          '  • Pass skip_conflict_check: true to force the push (a conflict_override row can be recorded later via the console Dismiss-with-reason action).',
+        ],
+      };
+    }
+  }
+
+  const epicContent = `---
+id: ${epicId}
+file_id: ${epicFileKey}
+family: ${epicFamilyKey}
+name: ${yamlQuote(epicName)}
+${summaryYaml}
+type: epic
+kind: ${kind}
+effort: ${effort}
+requires_user_testing: false
+status: ${onDeck ? 'in_progress' : 'open'}
+owner: pwher
+created: '${now}'
+updated: '${now}'
+milestone: "${milestoneResolved.wikilink}"
+${tagsYaml}
+${childrenYaml}
+${relatedYaml}
+---
+
+${epicBody}
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_push_plan) | Epic created via hs-push${onDeck ? '-next' : ''}. |
+`;
+
+  const epicDir = join(vaultRoot, 'specs', 'epics');
+  mkdirSync(epicDir, { recursive: true });
+  writeFileSync(join(vaultRoot, epicRelPath), epicContent, 'utf8');
+
+  // Mirror-update milestone's epics: array (bidirectional integrity per HS-TASK-T5PX).
+  try {
+    appendEpicToMilestone(vaultRoot, milestoneResolved.basename, epicBasename);
+  } catch (err) {
+    return {
+      error: 'MILESTONE_MIRROR_UPDATE_FAILED',
+      message: `epic file written but failed to mirror-update milestone: ${err.message}`,
+      epic_id: epicId,
+      epic_path: epicRelPath,
+    };
+  }
+
+  // Focus write is owned by the async caller (cli.mjs `handlePushPlan` →
+  // `writeFocusSelectionVendor`) so it can go to Neon `focus_selection` via the
+  // console endpoint. Neon is the only focus store — no file fallback
+  // ([[HS-TASK-FSEL]]; [[no-fallbacks-by-default]]). `executePushPlan` is sync
+  // and must not touch Neon, so it surfaces `on_deck` + `epic.spec_path` +
+  // `focus_reason` and lets the caller act.
+  const computedFocusReason = onDeck
+    ? focusReason || `On deck: ${epicName} (hs-push-next)`
+    : null;
+
+  let validateOk = null;
+  let validateMessage = null;
+  const validateScript = join(vaultRoot, 'scripts', 'validate-vault-ids.mjs');
+  if (existsSync(validateScript)) {
+    try {
+      execFileSync(process.execPath, [validateScript], {
+        cwd: vaultRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      validateOk = true;
+    } catch (e) {
+      validateOk = false;
+      validateMessage = e.stderr?.toString() || e.message;
+    }
+  } else {
+    validateOk = null;
+    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not in vault root)';
+  }
+
+  // Reuse the pre-flight conflict detection result computed before file writes
+  // (HS-EPIC-6RKN Phase 3). The on_deck path would have returned early above
+  // when conflicts existed; we still surface them in the response for /hs-push
+  // (no on_deck) and for the forced-push case.
+  const conflicts = preflightConflicts;
+  const linkedSpecsChecked = preflightLinkedSpecs;
+
+  // Design decision detection (HS-EPIC-W9ZE)
+  const fullContent = [epicBody, preparedPrompt || ''].join('\n');
+  const designDecisions = getApplicableDesignDecisions(fullContent);
+
+  const result = {
+    success: true,
+    on_deck: onDeck,
+    epic: {
+      id: epicId,
+      basename: epicBasename,
+      spec_path: epicRelPath,
+    },
+    children: [],
+    focus_written: onDeck,
+    focus_reason: computedFocusReason,
+    validate_vault_ids: validateOk,
+    validate_message: validateMessage,
+    // Conflict detection results (HS-EPIC-6RKN)
+    conflicts,
+    linked_specs_checked: linkedSpecsChecked,
+    has_conflicts: conflicts.length > 0,
+    // Design system decisions (HS-EPIC-W9ZE)
+    design_decisions: designDecisions,
+    has_design_decisions: designDecisions.length > 0,
+    plans_ingested: prepared.plans_ingested,
+    ingested_plans: prepared.ingested_plans,
+    missing_plans: prepared.missing_plans,
+    next_steps: [
+      'heyspex_validate_linkage',
+      onDeck
+        ? 'heyspex_next_on_deck or /hs-next — break into tasks via the breakdown brief (heyspex_file_spec with summary)'
+        : 'Optional: heyspex_push_plan on_deck after review',
+      'heyspex_register_spec if epic should appear in roadmap manifest',
+      'Record the WIP ledger (heyspex_record_wip) for the epic if this is the new focus (next-session-handoff.md retired — HS-EPIC-HNDR)',
+    ],
+  };
+
+  // Add conflict warning to next_steps if conflicts found
+  if (conflicts.length > 0) {
+    result.next_steps.unshift(
+      `⚠️ ${conflicts.length} spec conflict(s) detected — review before implementation`
+    );
+  }
+
+  // Add design decision reminder if applicable
+  if (designDecisions.length > 0) {
+    result.next_steps.unshift(
+      `📐 ${designDecisions.length} design decision(s) apply — review before implementation`
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Retroactively create an epic + child tasks for completed work.
+ * All specs are created with status: in_review and a review doc is auto-generated.
+ */
+export function executeShipEpic(vaultRoot, args) {
+  const {
+    epic_name: epicName,
+    summary = '',
+    plan_markdown: planMarkdown = '',
+    children = [],
+    files_changed: filesChanged = [],
+    kind = 'feature',
+    effort = 3,
+    tags = [],
+    related = [],
+    roadmap_id: roadmapId = 'HS-ROADMAP-PRODUCT',
+    roadmap_phase: roadmapPhase = 'P0',
+    skip_roadmap_registration: skipRoadmapRegistration = false,
+    milestone,
+    pillar,
+  } = args;
+
+  if (!epicName?.trim()) {
+    return { error: 'MISSING_EPIC_NAME', message: 'epic_name is required' };
+  }
+
+  const epicSummary = resolveAuthoredSummaryValue(summary);
+  if (!epicSummary) {
+    return buildSummaryRequiredMcpError('epic');
+  }
+
+  const milestoneResolved = resolveMilestoneArg(vaultRoot, milestone);
+  if (milestoneResolved.error) {
+    return milestoneResolved;
+  }
+
+  // Every epic must carry a resolvable `pillar:` ([[pillar-assignment-protocol]]) — the
+  // vault gate errors on one that does not, and before 2026-08-13 this tool emitted none
+  // at all, so every backfilled epic landed red (caught when backfilling the pillar work
+  // itself). Default to the parent milestone's authored pillar: milestones have carried
+  // one since the same date, and an epic sharing its milestone's theme is the overwhelming
+  // common case. An explicit `pillar` arg wins when the epic's own subject differs.
+  const resolvedPillar =
+    normalizePillarRef(pillar) ??
+    resolveMilestonePillar(vaultRoot, milestoneResolved.basename) ??
+    null;
+  if (!resolvedPillar) {
+    return {
+      error: 'PILLAR_REQUIRED',
+      message:
+        `Cannot resolve a pillar for this epic: parent milestone "${milestoneResolved.basename}" has no \`pillar:\` and none was passed. ` +
+        'Pass `pillar: "[[HS-PILR-<slug>]]"`, or assign the milestone a pillar first. ' +
+        'Use heyspex_suggest_pillar to pick one against each pillar\'s written charter — never by name ([[pillar-assignment-protocol]]).',
+    };
+  }
+
+  // V3 file-key-first minting ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]):
+  // the epic inherits its milestone parent's family; each backfilled child
+  // task then inherits the EPIC's family (the "original template" epic→task
+  // pattern — vault-id-assignment-protocol §Family inheritance).
+  const epicFamilyKey =
+    resolveMilestoneFamily(vaultRoot, milestoneResolved.basename) ?? mintFamilyKey(vaultRoot);
+  // Per-file FILE KEYS (owner ruling 2026-07-10) — one occupied set across the
+  // whole run (epic + backfilled children are not on disk yet), and (V3) the
+  // anchor for every minted `id:` here.
+  const occupiedFileKeys = collectOccupiedFileKeysFromVault(vaultRoot);
+  const epicFileKey = allocateFileKey(occupiedFileKeys);
+  occupiedFileKeys.add(epicFileKey);
+  const epicId = `HS-${epicFileKey}`;
+
+  const epicSlug = deriveSlug(epicName);
+  const epicBasename = `${epicId}-${epicFamilyKey}-EPIC-${epicSlug}`;
+  const epicRelPath = `specs/epics/${epicBasename}.md`;
+  const now = isoNow();
+  const childWikilinks = [];
+
+  const childSpecs = [];
+  for (const child of children) {
+    if (!child?.name?.trim()) continue;
+    const childSummary = resolveAuthoredSummaryValue(child.summary);
+    if (!childSummary) {
+      return {
+        ...buildSummaryRequiredMcpError('task'),
+        message: `Child task "${child.name}" requires a plain-language \`summary\` when backfilled — pass \`summary\` on each child per spec-summary-authoring.`,
+      };
+    }
+    const taskFileKey = allocateFileKey(occupiedFileKeys);
+    occupiedFileKeys.add(taskFileKey);
+    const taskId = `HS-${taskFileKey}`;
+    const taskSlug = deriveSlug(child.name);
+    // Inherits the epic's family — the epic→task pattern.
+    const taskBasename = `${taskId}-${epicFamilyKey}-TASK-${taskSlug}`;
+    const taskRelPath = `specs/tasks/${taskBasename}.md`;
+    childWikilinks.push(`[[${taskBasename}]]`);
+    childSpecs.push({
+      id: taskId,
+      fileKey: taskFileKey,
+      familyKey: epicFamilyKey,
+      basename: taskBasename,
+      relPath: taskRelPath,
+      name: child.name,
+      summary: childSummary,
+    });
+  }
+
+  // Build epic body
+  let epicBody = planMarkdown.trim() || `# ${epicName}\n\n${epicSummary}\n`;
+  const epicSummaryYaml = formatSummaryFrontmatterField(epicSummary);
+
+  const childrenYaml =
+    childWikilinks.length > 0
+      ? `children:\n${childWikilinks.map((c) => `  - '${c}'`).join('\n')}`
+      : 'children: []';
+
+  const allTags = tags.length > 0 ? tags : ['epic'];
+  const tagsYaml = `tags:\n${allTags.map((t) => `  - ${t}`).join('\n')}`;
+
+  const userRelatedLinks = Array.isArray(related) ? related : [];
+  const allRelatedLinks = userRelatedLinks.map(r => {
+    const basename = String(r).replace(/^\[\[|\]\]$/g, '');
+    return `[[${basename}]]`;
+  });
+  const relatedYaml = allRelatedLinks.length > 0
+    ? `related:\n${allRelatedLinks.map(r => `  - '${r}'`).join('\n')}`
+    : 'related: []';
+
+  const epicContent = `---
+id: ${epicId}
+file_id: ${epicFileKey}
+family: ${epicFamilyKey}
+name: ${yamlQuote(epicName)}
+${epicSummaryYaml}
+type: epic
+kind: ${kind}
+effort: ${effort}
+requires_user_testing: false
+status: in_review
+owner: pwher
+created: '${now}'
+updated: '${now}'
+milestone: "${milestoneResolved.wikilink}"
+pillar: '[[${resolvedPillar}]]'
+${tagsYaml}
+${childrenYaml}
+${relatedYaml}
+---
+
+${epicBody}
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_backfill_epic) | Epic created retroactively, backfilled to review. |
+`;
+
+  const epicDir = join(vaultRoot, 'specs', 'epics');
+  mkdirSync(epicDir, { recursive: true });
+  writeFileSync(join(vaultRoot, epicRelPath), epicContent, 'utf8');
+
+  // Mirror-update milestone's epics: array (bidirectional integrity per HS-TASK-T5PX).
+  try {
+    appendEpicToMilestone(vaultRoot, milestoneResolved.basename, epicBasename);
+  } catch (err) {
+    return {
+      error: 'MILESTONE_MIRROR_UPDATE_FAILED',
+      message: `epic file written but failed to mirror-update milestone: ${err.message}`,
+      epic_id: epicId,
+      epic_path: epicRelPath,
+    };
+  }
+
+  // Write child tasks with status: in_review
+  for (const child of childSpecs) {
+    const taskSummaryYaml = formatSummaryFrontmatterField(child.summary);
+    const taskBody =
+      `# ${child.name}\n\n_Completed as part of [[${epicBasename}]]._\n`;
+
+    const taskContent = `---
+id: ${child.id}
+file_id: ${child.fileKey}
+family: ${child.familyKey}
+name: ${yamlQuote(child.name)}
+${taskSummaryYaml}
+type: task
+kind: ${kind}
+effort: ${effort}
+requires_user_testing: false
+status: in_review
+owner: pwher
+created: '${now}'
+updated: '${now}'
+tags:
+  - shipped
+parent: '[[${epicBasename}]]'
+---
+
+${taskBody}
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_backfill_epic) | Task backfilled to review as part of [[${epicBasename}]]. |
+`;
+    mkdirSync(join(vaultRoot, 'specs', 'tasks'), { recursive: true });
+    writeFileSync(join(vaultRoot, child.relPath), taskContent, 'utf8');
+  }
+
+  // Generate review doc for the epic
+  const reviewRelPath = `specs/epics/${epicBasename}.review.md`;
+  const filesTable = filesChanged.length > 0
+    ? filesChanged.map(f => `| ${f} | Modified |`).join('\n')
+    : '| _No files listed_ | - |';
+
+  const reviewContent = `---
+type: review
+for: '[[${epicBasename}]]'
+created: '${now}'
+---
+
+# Review: ${epicName}
+
+## Pre-Review Checklist
+
+- [ ] Code changes reviewed
+- [ ] Tests passing (if applicable)
+- [ ] No regressions introduced
+- [ ] Documentation updated (if applicable)
+
+## Files Changed
+
+| File | Change Type |
+|------|-------------|
+${filesTable}
+
+## Summary
+
+${epicSummary}
+
+## Child Tasks
+
+${childWikilinks.length > 0 ? childWikilinks.map(c => `- ${c}`).join('\n') : '_No child tasks._'}
+
+## Notes
+
+_Space for reviewer comments._
+`;
+
+  writeFileSync(join(vaultRoot, reviewRelPath), reviewContent, 'utf8');
+
+  // Register epic in roadmap manifest (so it appears in kanban board)
+  let roadmapRegistration = null;
+  if (!skipRoadmapRegistration) {
+    roadmapRegistration = addEpicToRoadmapPhase(vaultRoot, roadmapId, roadmapPhase, epicBasename);
+  } else {
+    roadmapRegistration = { success: true, message: 'Skipped (skip_roadmap_registration: true)' };
+  }
+
+  // Validate vault IDs
+  let validateOk = null;
+  let validateMessage = null;
+  const validateScript = join(vaultRoot, 'scripts', 'validate-vault-ids.mjs');
+  if (existsSync(validateScript)) {
+    try {
+      execFileSync(process.execPath, [validateScript], {
+        cwd: vaultRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      validateOk = true;
+    } catch (e) {
+      validateOk = false;
+      validateMessage = e.stderr?.toString() || e.message;
+    }
+  } else {
+    validateOk = null;
+    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not in vault root)';
+  }
+
+  return {
+    success: true,
+    shipped_to_review: true,
+    epic: {
+      id: epicId,
+      basename: epicBasename,
+      spec_path: epicRelPath,
+    },
+    children: childSpecs,
+    review_doc: reviewRelPath,
+    roadmap_registration: roadmapRegistration,
+    validate_vault_ids: validateOk,
+    validate_message: validateMessage,
+    next_steps: [
+      roadmapRegistration?.success
+        ? `Epic added to ${roadmapPhase} in ${roadmapId} — visible in Review column`
+        : `⚠️ Roadmap registration failed: ${roadmapRegistration?.message}`,
+      'Human reviews the epic and child tasks',
+      'Move to status: closed after verification',
+      'Record the WIP ledger (heyspex_record_wip) for the epic if needed (next-session-handoff.md retired — HS-EPIC-HNDR)',
+    ],
+  };
+}
+
+/**
+ * Build markdown workflow instructions for /hs-backfill prompt.
+ */
+export function buildShipWorkflowMarkdown(options = {}) {
+  const lines = [
+    '# HeySpex hs-backfill — retroactively backfill completed work into Review',
+    '',
+    'Use this when you completed implementation work **without a pre-existing epic** and want to record it in the vault.',
+    '',
+    '## What it does',
+    '',
+    '1. Creates epic spec with `status: in_review`',
+    '2. Creates child task specs with `status: in_review`',
+    '3. Generates `{epic}.review.md` companion file',
+    '4. **Registers epic in roadmap manifest** (default: `P0` of `HS-ROADMAP-PRODUCT`)',
+    '',
+    '> **Roadmap registration** ensures the epic appears in the kanban Review column. Without this, epics are "orphans" and won\'t show up in the board view.',
+    '',
+    '## Workflow',
+    '',
+    '### 1. Gather information',
+    '',
+    'Collect from the conversation:',
+    '- Epic name (what was accomplished)',
+    '- Summary (brief description)',
+    '- Child tasks (breakdown of work done)',
+    '- Files changed (for review doc)',
+    '',
+    '### 2. Call MCP tool',
+    '',
+    '```json',
+    '{',
+    '  "tool": "heyspex_backfill_epic",',
+    '  "arguments": {',
+    '    "epic_name": "Feature Name",',
+    '    "summary": "Brief description of what was done",',
+    '    "plan_markdown": "## Goal\\n\\nDescription...\\n\\n## What was done\\n\\n- Item 1\\n- Item 2",',
+    '    "children": [',
+    '      { "name": "Task 1", "summary": "What was done" },',
+    '      { "name": "Task 2", "summary": "What was done" }',
+    '    ],',
+    '    "files_changed": [',
+    '      "path/to/file1.ts",',
+    '      "path/to/file2.tsx"',
+    '    ]',
+    '  }',
+    '}',
+    '```',
+    '',
+    '### 3. Commit and push',
+    '',
+    '```bash',
+    'git add specs/',
+    'git commit -m "feat(epic): {epic-name} - backfilled to review (hs-backfill)"',
+    'git push',
+    '```',
+    '',
+    '## Result',
+    '',
+    'After running, the human can review the epic in the console Review column.',
+  ];
+
+  return lines.join('\n');
+}