heyspex 0.1.0

package/vendor/heyspex-mcp/promote-research.mjs

@@ -0,0 +1,1553 @@
+/**
+ * /hs-promote-research MCP tool — research → milestone promotion with
+ * AI-assisted epic stubs. Spec: [[HS-TASK-QQHP]] of [[HS-EPIC-M2J3]].
+ *
+ * Two-phase flow driven by presence/absence of `accepted_stubs`:
+ *
+ *   Phase 1 (review): caller invokes with `intent` ∈ {spawn, both} and no
+ *     `accepted_stubs`. Tool runs the AI proposer (console `/api/ai/
+ *     propose-epic-stubs`), returns the stubs to the agent for the human's
+ *     confirmation step. No file writes.
+ *
+ *   Phase 2 (execute): caller invokes again with `accepted_stubs` populated.
+ *     Tool performs the transactional write set (milestone create-or-update,
+ *     epic-stub files, research mutation, change-log rows) and rolls back
+ *     anything written if a later step fails.
+ *
+ * `intent: "augment"` is single-phase (no AI call — just appends the research
+ * to the chosen epics' `enhances_epics:` reverse pointer on the research
+ * side).
+ *
+ * Linkage written per [[HS-TASK-YJX6]]:
+ *   research.enhances        : "[[HS-MIL-…]]"   (single)
+ *   research.spawned_epics   : array of [[…]]   (new epics)
+ *   research.enhances_epics  : array of [[…]]   (augmented epics)
+ *   (research.status stays `open` — research is evergreen; [[research-is-evergreen]].
+ *    The `enhances` link, not a status flip, is the "already promoted" signal.)
+ *   milestone.informed_by    : appended with research wikilink
+ *   milestone.epics          : appended with each new epic wikilink
+ *   new epic.parent          : "[[HS-MIL-…]]"
+ *   new epic.milestone       : "[[HS-MIL-…]]"
+ *   new epic.derived_from    : "[[HS-RES-…]]"
+ *
+ * All writes are staged then committed; any failure rolls back the prior
+ * writes (created files deleted, mutated files restored from snapshot).
+ */
+
+import {
+  readFileSync,
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import {
+  matchCaseInsensitiveExact as sharedMatchCaseInsensitiveExact,
+  normalizeSourceRef,
+  resolveBreakdownSource,
+} from './breakdown-source.mjs';
+import { allocateFileKey, collectOccupiedKeysEitherKind, parseSpecId } from './spec-id-lib.mjs';
+import {
+  appendEpicToMilestone,
+  normalizeMilestoneBasename,
+  collectOccupiedVaultIds,
+} from './plan-push.mjs';
+import { registerSpec } from './register-spec.mjs';
+import {
+  isoNow,
+  todayDate,
+  deriveSlug,
+  randomSuffix,
+  findFileByPrefix,
+  getFrontmatterBlock,
+  getScalarField,
+  parseWikilinkBasename,
+  parseListFieldBasenames,
+  setScalarField,
+  appendToListField,
+  bumpUpdated,
+  appendChangeLogRow,
+  commitWrites,
+} from './promotion-helpers.mjs';
+
+/** Milestone statuses that allow attaching spawned epics without an override. */
+export const MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES = ['open'];
+
+/** In-progress attach is owner-gated — requires explicit override + reason. */
+export const MILESTONE_ATTACH_IN_PROGRESS_STATUS = 'in_progress';
+// Research-id validation is resolution-first: any string that resolves to a
+// file under specs/research/ is accepted, and the type gate then reads that
+// file's `type:` frontmatter. No id-shape pattern-match is applied to the
+// caller's string ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]).
+
+/**
+ * Allocate a fresh HS-MIL-XXXX id by scanning specs/milestones/ for the
+ * existing set. vault-id-lib doesn't currently support milestone (the only
+ * other site that allocates HS-MIL-* ids is by hand) so we keep this local
+ * to avoid widening the shared lib until a second caller appears.
+ */
+function allocateMilestoneId(vaultRoot, options = {}) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'milestones');
+  // Normalize milestone ids/basenames of EITHER ordering to canonical
+  // family-first so collision detection works mid-migration ([[HS-EPIC-DLE3]]).
+  const addMil = (value) => {
+    const p = parseSpecId(value);
+    if (p && p.typeLabel === 'MIL') occupied.add(`HS-${p.familyKey}-MIL`);
+  };
+  if (existsSync(dir)) {
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.md')) continue;
+      addMil(file.replace(/\.md$/i, ''));
+      try {
+        const raw = readFileSync(join(dir, file), 'utf8');
+        const idMatch = raw.match(/^id:\s*(\S+)/m);
+        if (idMatch) addMil(idMatch[1].replace(/^['"]|['"]$/g, ''));
+      } catch {
+        /* skip */
+      }
+    }
+  }
+  const randomUnit = options.randomUnit ?? Math.random;
+  let length = 4;
+  while (true) {
+    for (let attempt = 0; attempt < 10_000; attempt++) {
+      const id = `HS-${randomSuffix(length, randomUnit)}-MIL`; // family-first
+      if (!occupied.has(id)) return id;
+    }
+    length++;
+  }
+}
+
+/**
+ * Normalize a caller-supplied research reference to a bare id/basename.
+ *
+ * Thin alias over the shared breakdown-source normalizer ([[HS-K1TR]]) — kept as a
+ * named export because callers and tests reference it by this name.
+ */
+export function normalizeResearchRef(raw) {
+  return normalizeSourceRef(raw);
+}
+
+/**
+ * Pure matching logic for resolution step 2 (case-insensitive exact basename),
+ * re-exported from the shared resolver so the research path and the diagnose path
+ * cannot drift on it.
+ */
+function matchCaseInsensitiveExact(files, ref) {
+  return sharedMatchCaseInsensitiveExact(files, ref);
+}
+
+/**
+ * Resolve + type-check a RESEARCH reference.
+ *
+ * The four-step resolution ladder now lives in `breakdown-source.mjs` — one door
+ * for a research doc or a bug write-up ([[HS-ALBV]] §Scope "one stage, two inputs").
+ * This wrapper pins the search to `research` and maps the shared error codes back
+ * to the research-specific ones the promote-research contract already publishes.
+ */
+function findResearchByIdLocal(vaultRoot, researchId) {
+  const resolved = resolveBreakdownSource(vaultRoot, researchId, { kinds: ['research'] });
+  if (!resolved.error) return { record: resolved.record };
+  switch (resolved.error) {
+    case 'INVALID_ARGS':
+      return { error: 'INVALID_ARGS', message: 'research_id is required' };
+    case 'SOURCE_ID_AMBIGUOUS':
+      return {
+        error: 'RESEARCH_ID_AMBIGUOUS',
+        message: resolved.message.replace(String(researchId), `research_id ${researchId}`),
+        candidates: resolved.candidates,
+      };
+    case 'SOURCE_TYPE_MISMATCH':
+      return {
+        error: 'RESEARCH_TYPE_MISMATCH',
+        message: `research_id ${researchId} resolved to ${resolved.resolved_basename ? `specs/research/${resolved.resolved_basename}.md` : 'a file'}, which is \`type: ${resolved.resolved_type}\` — not a research doc`,
+        resolved_basename: resolved.resolved_basename,
+        resolved_type: resolved.resolved_type,
+      };
+    default:
+      return {
+        error: 'RESEARCH_NOT_FOUND',
+        message: `research ${researchId} not found under specs/research/ (tried exact basename, frontmatter id:, and id-prefix match)`,
+      };
+  }
+}
+
+function findMilestoneByBasename(vaultRoot, basename) {
+  const absPath = join(vaultRoot, 'specs', 'milestones', `${basename}.md`);
+  if (!existsSync(absPath)) return null;
+  return {
+    basename,
+    absPath,
+    relPath: join('specs', 'milestones', `${basename}.md`),
+    raw: readFileSync(absPath, 'utf8'),
+  };
+}
+
+function findMilestoneById(vaultRoot, milestoneId) {
+  const dir = join(vaultRoot, 'specs', 'milestones');
+  if (!existsSync(dir)) return null;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    if (file.startsWith(`${milestoneId}-`)) {
+      const basename = file.replace(/\.md$/, '');
+      return findMilestoneByBasename(vaultRoot, basename);
+    }
+  }
+  return null;
+}
+
+function findEpicByIdOrBasename(vaultRoot, idOrBasename) {
+  const dir = join(vaultRoot, 'specs', 'epics');
+  if (!existsSync(dir)) return null;
+  if (/\.md$/.test(idOrBasename)) idOrBasename = idOrBasename.replace(/\.md$/, '');
+  // Try as basename first (HS-EPIC-XXXX-slug)
+  const directAbs = join(dir, `${idOrBasename}.md`);
+  if (existsSync(directAbs)) {
+    return {
+      basename: idOrBasename,
+      absPath: directAbs,
+      relPath: join('specs', 'epics', `${idOrBasename}.md`),
+      raw: readFileSync(directAbs, 'utf8'),
+    };
+  }
+  // Try as id prefix (HS-EPIC-XXXX)
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    if (file.startsWith(`${idOrBasename}-`)) {
+      const basename = file.replace(/\.md$/, '');
+      const absPath = join(dir, file);
+      return {
+        basename,
+        absPath,
+        relPath: join('specs', 'epics', file),
+        raw: readFileSync(absPath, 'utf8'),
+      };
+    }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Pillar resolution (epic→pillar hard requirement, [[pillar-assignment-protocol]])
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// `POST /api/specs` / `heyspex_file_spec` hard-block a `type: epic` whose
+// `pillar:` is missing or does not resolve to an `HS-PILR-*` doc on disk
+// (`400 pillar_required`, listing existing pillars). Spawned epics here write
+// files directly and so bypass that filing-time gate — this mirrors the same
+// contract inside the execute phase, checked BEFORE any write (HS-TASK-QQHP
+// defect #2).
+
+/** Strip quotes/wikilink wrapping from a caller-supplied pillar reference. */
+function normalizePillarRef(raw) {
+  if (typeof raw !== 'string') return null;
+  let value = raw.trim();
+  if (!value) return null;
+  const wikilink = value.match(/^\[\[([^\]]+)\]\]$/);
+  if (wikilink) value = wikilink[1].trim();
+  value = value.replace(/^['"]|['"]$/g, '').trim();
+  // Strip a trailing `.md` (mirrors normalizeResearchRef) so "HS-PILR-x.md" /
+  // "[[HS-PILR-x.md]]" resolve against specs/pillars/HS-PILR-x.md instead of
+  // missing on a doubled ".md.md" join.
+  value = value.replace(/\.md$/i, '').trim();
+  return value || null;
+}
+
+/** Every pillar doc that exists under specs/pillars/ in the target vault. */
+export function listVaultPillars(vaultRoot) {
+  const dir = join(vaultRoot, 'specs', 'pillars');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const basename = file.replace(/\.md$/i, '');
+    let name = basename;
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const block = getFrontmatterBlock(raw)?.block ?? '';
+      name = getScalarField(block, 'name') ?? basename;
+    } catch {
+      /* keep basename as the display name */
+    }
+    out.push({ id: basename, name });
+  }
+  return out;
+}
+
+/**
+ * Resolve a caller-supplied pillar reference (bare `HS-PILR-<slug>` or a
+ * `[[wikilink]]`) to a pillar doc that exists on disk in the target vault.
+ * Returns `{ ok: true, basename, frontmatterValue }` — `frontmatterValue` is
+ * the normalized quoted-wikilink form (`'[[HS-PILR-<slug>]]'`) to write into
+ * the epic's frontmatter — or `{ ok: false }` when the reference is blank,
+ * malformed, or does not resolve.
+ */
+export function resolvePillar(vaultRoot, raw) {
+  const basename = normalizePillarRef(raw);
+  if (!basename) return { ok: false };
+  const absPath = join(vaultRoot, 'specs', 'pillars', `${basename}.md`);
+  if (!existsSync(absPath)) return { ok: false };
+  return { ok: true, basename, frontmatterValue: `'[[${basename}]]'` };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AI proposer wiring
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Default proposer — POSTs to console `/api/ai/propose-epic-stubs`. Tests
+ * inject their own proposer via `deps.proposeStubs` so no live network is
+ * needed.
+ */
+async function defaultProposeStubs(payload, deps) {
+  if (!deps?.consoleFetch) {
+    return {
+      ok: false,
+      reason: 'no_console_fetch',
+      message: 'console fetch dep not wired',
+    };
+  }
+  const result = await deps.consoleFetch('/api/ai/propose-epic-stubs', {
+    method: 'POST',
+    body: payload,
+  });
+  if (!result.ok) {
+    return {
+      ok: false,
+      reason: result.errorKind === 'timeout' ? 'console_timeout' : 'console_error',
+      message: `console /api/ai/propose-epic-stubs returned ${result.status}`,
+      console_response: result.body,
+    };
+  }
+  return result.body;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Argument validation + research/milestone loading
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateInputShape(args) {
+  if (!args || typeof args !== 'object') {
+    return { error: 'INVALID_ARGS', message: 'args must be an object' };
+  }
+  if (typeof args.research_id !== 'string' || !normalizeResearchRef(args.research_id)) {
+    return { error: 'INVALID_ARGS', message: 'research_id is required' };
+  }
+  // No type-label gate here on purpose. A real vault id may be a bare era-3
+  // file key (`HS-X5FH`) that carries no `RES` label at all — rejecting it
+  // shape-first made every research doc unpromotable
+  // ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]). The
+  // "is this a research doc?" question is answered by the resolved file's
+  // `type:` frontmatter in findResearchByIdLocal.
+  // Default policy ([[spec-hierarchy]] §Research → milestone/epic filing): NEW milestone
+  // unless the agent explicitly names an existing one.
+  if (args.target_milestone === undefined || args.target_milestone === null || args.target_milestone === '') {
+    args.target_milestone = 'NEW';
+  }
+  if (typeof args.target_milestone !== 'string' || !args.target_milestone.trim()) {
+    return { error: 'INVALID_ARGS', message: 'target_milestone must be a non-empty string or omitted (defaults to NEW)' };
+  }
+  args.target_milestone = args.target_milestone.trim();
+  if (args.target_milestone === 'NEW') {
+    if (
+      typeof args.new_milestone_name !== 'string' ||
+      !args.new_milestone_name.trim()
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: 'new_milestone_name is required when target_milestone === "NEW"',
+      };
+    }
+  }
+  if (!['spawn', 'augment', 'both'].includes(args.intent)) {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'intent must be one of: spawn | augment | both',
+    };
+  }
+  if (
+    args.intent !== 'spawn' &&
+    (!Array.isArray(args.augment_epic_ids) || args.augment_epic_ids.length === 0)
+  ) {
+    return {
+      error: 'INVALID_ARGS',
+      message:
+        'augment_epic_ids must be a non-empty array when intent includes "augment"',
+    };
+  }
+  if (
+    args.accepted_stubs !== undefined &&
+    !Array.isArray(args.accepted_stubs)
+  ) {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'accepted_stubs must be an array when provided',
+    };
+  }
+  if (args.attach_to_in_progress_milestone !== undefined && typeof args.attach_to_in_progress_milestone !== 'boolean') {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'attach_to_in_progress_milestone must be a boolean when provided',
+    };
+  }
+  if (args.attach_override_reason !== undefined && typeof args.attach_override_reason !== 'string') {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'attach_override_reason must be a string when provided',
+    };
+  }
+  // Batch-default pillar for spawned epics ([[pillar-assignment-protocol]]).
+  // Shape/resolvability against specs/pillars/ is checked in runExecutePhase
+  // (it needs vaultRoot); this is just the type gate.
+  if (args.pillar !== undefined && typeof args.pillar !== 'string') {
+    return { error: 'INVALID_ARGS', message: 'pillar must be a string when provided' };
+  }
+  return null;
+}
+
+/**
+ * Enforce research-promotion milestone attach policy ([[spec-hierarchy]]):
+ * default is NEW; existing milestones must be `open` unless the rare
+ * in_progress override is explicitly requested with an audit reason.
+ */
+export function validateExistingMilestoneAttachable(milestoneRaw, args = {}) {
+  const fm = getFrontmatterBlock(milestoneRaw);
+  if (!fm) {
+    return {
+      error: 'MILESTONE_FRONTMATTER_MISSING',
+      message: 'target milestone has no frontmatter — cannot verify attach policy',
+    };
+  }
+  const status = (getScalarField(fm.block, 'status') ?? 'open').trim().toLowerCase();
+  const basename = milestoneRaw.match(/^id:\s*(\S+)/m)?.[1] ?? 'milestone';
+
+  if (MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES.includes(status)) {
+    return { ok: true, status };
+  }
+
+  if (status === MILESTONE_ATTACH_IN_PROGRESS_STATUS) {
+    if (args.attach_to_in_progress_milestone === true) {
+      const reason = typeof args.attach_override_reason === 'string'
+        ? args.attach_override_reason.trim()
+        : '';
+      if (reason.length < 40) {
+        return {
+          error: 'ATTACH_OVERRIDE_REASON_REQUIRED',
+          message:
+            'Attaching spawned epics to an in_progress milestone requires attach_to_in_progress_milestone: true and attach_override_reason (≥40 chars) documenting the owner exception. Default is target_milestone: "NEW".',
+          milestone_status: status,
+        };
+      }
+      return { ok: true, status, override: 'in_progress' };
+    }
+    return {
+      error: 'MILESTONE_IN_PROGRESS_ATTACH_BLOCKED',
+      message:
+        `Target milestone is status: ${status}. Spawning epics into an in-progress milestone is blocked by default — use target_milestone: "NEW" (the default) unless the owner explicitly approves the rare exception (attach_to_in_progress_milestone: true + attach_override_reason).`,
+      milestone_status: status,
+      policy: 'default_new_milestone',
+    };
+  }
+
+  return {
+    error: 'MILESTONE_NOT_ATTACHABLE',
+    message:
+      `Target milestone is status: ${status}. Only status: open milestones accept spawned epics without creating a new milestone. Use target_milestone: "NEW" (the default) or pick an open milestone that clearly extends the same thesis.`,
+    milestone_status: status,
+    policy: 'default_new_milestone',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Unfinished-stub gate — refuse to spawn milestones/epics from a research doc
+// that is still just its promote-capture outline stub (owner correction
+// 2026-08-12): outline-confirm only fixes the SHAPE of the research (its
+// section headings); it is not the same as the research having been done.
+// A prior session treated "the outline was approved" as "the research is
+// complete" and immediately spawned a milestone + epics from a doc whose
+// sections were still the literal `_TBD — fill in this section._` placeholder
+// text buildResearchStubContent() in promote-capture.mjs writes for every
+// outline section. This mechanically catches that failure mode regardless of
+// whether the outline→epic-stub review gate is also respected.
+// ─────────────────────────────────────────────────────────────────────────────
+const TBD_PLACEHOLDER_RE = /_TBD\s*[—–-]\s*fill in this section\._/gi;
+
+/** Count of unresolved promote-capture stub placeholders left in a research body. */
+export function findUnresolvedResearchPlaceholders(raw) {
+  const body = getFrontmatterBlock(raw)?.body ?? raw;
+  const matches = body.match(TBD_PLACEHOLDER_RE);
+  return matches ? matches.length : 0;
+}
+
+function validateResearchState(research) {
+  const fm = getFrontmatterBlock(research.raw);
+  if (!fm) {
+    return { error: 'RESEARCH_FRONTMATTER_MISSING', message: 'research has no frontmatter' };
+  }
+  // Research is evergreen ([[research-is-evergreen]]): status stays `open` over
+  // the doc's whole life, so there is no `status: closed` re-promotion gate. The
+  // `enhances` link is the "already promoted" signal — see
+  // validateBidirectionalEnhances (RESEARCH_ALREADY_PROMOTED).
+  const status = getScalarField(fm.block, 'status');
+  const enhances = getScalarField(fm.block, 'enhances');
+  return { fm, status, enhances };
+}
+
+function resolveTargetMilestone(vaultRoot, args, occupiedMilestoneIds) {
+  if (args.target_milestone === 'NEW') {
+    return { mode: 'new', name: args.new_milestone_name.trim() };
+  }
+  // Accept either bare HS-MIL-XXXX, the full basename, or wikilink wrapping.
+  const basenameCandidate = normalizeMilestoneBasename(args.target_milestone);
+  if (basenameCandidate) {
+    const ms = findMilestoneByBasename(vaultRoot, basenameCandidate);
+    if (ms) return { mode: 'existing', milestone: ms };
+  }
+  if (parseSpecId(args.target_milestone)?.typeLabel === 'MIL') {
+    const ms = findMilestoneById(vaultRoot, args.target_milestone);
+    if (ms) return { mode: 'existing', milestone: ms };
+  }
+  return {
+    error: 'MILESTONE_NOT_FOUND',
+    message: `target_milestone ${args.target_milestone} did not resolve to a file under specs/milestones/ (looked for both basename and id)`,
+  };
+}
+
+function validateBidirectionalEnhances(researchEnhances, targetMilestoneBasename) {
+  if (!researchEnhances) return null;
+  const existingBasename = parseWikilinkBasename(researchEnhances);
+  if (!existingBasename) {
+    return {
+      error: 'RESEARCH_ENHANCES_MALFORMED',
+      message: `research \`enhances:\` is not a wikilink: ${researchEnhances}`,
+    };
+  }
+  if (existingBasename !== targetMilestoneBasename) {
+    return {
+      error: 'RESEARCH_ENHANCES_CONFLICT',
+      message: `research already has \`enhances: [[${existingBasename}]]\` but target_milestone resolves to ${targetMilestoneBasename}. Split or rewrite the research first ([[HS-TASK-GTH9-hs-split-research-mcp-tool]] / [[HS-TASK-YJX6]]).`,
+      existing: existingBasename,
+      target: targetMilestoneBasename,
+    };
+  }
+  // Same target: the research already enhances this milestone — i.e. it has
+  // already been promoted here. Under the evergreen rule the research stays
+  // `status: open`, so `enhances` (not status) is the "already promoted" signal.
+  // Block the re-run to avoid spawning duplicate epics. (A *failed* promote rolls
+  // back via commitWrites, leaving `enhances` unset, so legitimate retries are
+  // unaffected.)
+  return {
+    error: 'RESEARCH_ALREADY_PROMOTED',
+    message: `research already enhances [[${targetMilestoneBasename}]] — it has already been promoted to this milestone. Re-running would spawn duplicate epics; edit the milestone/epics directly, or split the research to target a different milestone.`,
+    existing: existingBasename,
+    target: targetMilestoneBasename,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 1: review (AI proposal)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runProposalPhase(args, ctx, deps) {
+  const proposer = deps?.proposeStubs ?? defaultProposeStubs;
+
+  // Build payload — body is the research markdown (sans frontmatter), bound
+  // to a soft excerpt cap so the console endpoint does not have to babysit
+  // an unbounded request body.
+  const researchBody = ctx.research.raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  const cappedBody = researchBody.length > 8000
+    ? researchBody.slice(0, 8000) + '\n\n…(truncated for AI proposal)'
+    : researchBody;
+
+  const milestoneTarget =
+    ctx.targetResolution.mode === 'new'
+      ? 'NEW'
+      : ctx.targetResolution.milestone.frontmatter?.id ??
+        ctx.targetResolution.milestone.basename;
+  const milestoneName =
+    ctx.targetResolution.mode === 'new'
+      ? ctx.targetResolution.name
+      : ctx.targetResolution.milestone.name ?? ctx.targetResolution.milestone.basename;
+  const existingEpicBasenames =
+    ctx.targetResolution.mode === 'existing'
+      ? ctx.targetResolution.milestone.epicsList ?? []
+      : [];
+
+  const payload = {
+    researchId: ctx.research.frontmatter?.id ?? args.research_id,
+    researchName: ctx.research.frontmatter?.name ?? '',
+    researchBody: cappedBody,
+    milestone: {
+      target: milestoneTarget,
+      name: milestoneName,
+      existingEpicBasenames,
+    },
+    spawnEpicCount: args.spawn_epic_count,
+  };
+
+  const proposalResult = await proposer(payload, deps);
+
+  // Record that this turn happened, and what the human is about to be shown.
+  // The execute turn refuses without this marker.
+  writeStubReviewMarker(ctx.vaultRoot, payload.researchId, {
+    stubs: proposalResult?.ok ? proposalResult.stubs : [],
+    proposerOk: proposalResult?.ok === true,
+    targetMilestone: milestoneTarget,
+  });
+
+  return {
+    phase: 'review',
+    research_id: payload.researchId,
+    research_title: payload.researchName,
+    research_status: ctx.researchStatus,
+    target_milestone: ctx.targetResolution.mode === 'new'
+      ? 'NEW'
+      : ctx.targetResolution.milestone.basename,
+    target_milestone_name: milestoneName,
+    new_milestone_name:
+      ctx.targetResolution.mode === 'new' ? ctx.targetResolution.name : undefined,
+    intent: args.intent,
+    augment_candidates:
+      ctx.targetResolution.mode === 'existing'
+        ? ctx.targetResolution.milestone.epicsList ?? []
+        : [],
+    proposed_stubs: proposalResult?.ok ? proposalResult.stubs : [],
+    ai_proposal: proposalResult?.ok
+      ? { ok: true, model: 'claude-haiku-4-5-20251001' }
+      : { ok: false, reason: proposalResult?.reason, message: proposalResult?.message },
+    milestone_attach_policy: {
+      default: 'NEW',
+      existing_milestone_requires_status: MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES,
+      in_progress_requires_override: true,
+    },
+    human_review_required: true,
+    next_call_hint:
+      'Default is target_milestone: "NEW". Show proposed_stubs to the user, let them edit/remove, then call heyspex_promote_research again with the same args plus `accepted_stubs: [...]` to execute the writes. Attach to an existing milestone only when it is status: open and clearly extends the same thesis.',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Two-turn review gate ([[HS-EPIC-PLRV]] pattern, copied from the plan gate).
+//
+// The two-phase flow was a CONVENTION: phase 1 proposes stubs, the human edits
+// them, phase 2 writes. Nothing enforced it. An agent could call phase 2
+// directly with stubs it invented, and a milestone plus a handful of epics
+// would land in the vault having never been shown to anyone. The two-turn rule
+// existed only as prose in the slash command.
+//
+// The plan gate is the one gate in this system that holds, and it holds because
+// of three things together: phase 1 writes a marker, phase 2 refuses without a
+// matching one, and a thin answer is rejected rather than accepted. Same three
+// here — the difference being that both phases live inside this one tool, so
+// the gate is not a hook and `.heyspex/mode.json` cannot disarm it.
+//
+// Break-glass: HEYSPEX_PROMOTE_REVIEW_GATE_OFF=1.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Minimum length for an explanation, matching attach_override_reason above. */
+const EDIT_NOTE_MIN_LENGTH = 40;
+
+/** Marker path for a research doc's proposal turn. Keyed on the research id — the
+ *  one value stable across both turns, since the human is expected to EDIT the
+ *  stubs in between (so hashing the stub content, as the plan gate does, would
+ *  refuse every legitimate edit). */
+export function stubReviewMarkerPath(vaultRoot, researchId) {
+  const hash = createHash('sha256').update(String(researchId ?? '')).digest('hex');
+  return join(vaultRoot, '.heyspex', 'promote-research', `${hash}.json`);
+}
+
+/** Normalize a stub name for comparison — case and punctuation are the human's
+ *  to change; what matters is whether the accepted set descends from the
+ *  proposed one at all. */
+function normalizeStubName(name) {
+  return String(name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+/** Record that the proposal turn happened, and what was put in front of the human. */
+export function writeStubReviewMarker(vaultRoot, researchId, proposal = {}) {
+  try {
+    const file = stubReviewMarkerPath(vaultRoot, researchId);
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(
+      file,
+      JSON.stringify(
+        {
+          research_id: researchId,
+          proposed_at: new Date().toISOString(),
+          proposed_stub_names: (proposal.stubs ?? []).map((s) => s?.name ?? ''),
+          proposer_ok: proposal.proposerOk === true,
+          target_milestone: proposal.targetMilestone ?? null,
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+    return true;
+  } catch {
+    // A marker we cannot write must not break the proposal turn — the execute
+    // turn will refuse for a missing marker, which is the safe direction.
+    return false;
+  }
+}
+
+function readStubReviewMarker(vaultRoot, researchId) {
+  try {
+    const file = stubReviewMarkerPath(vaultRoot, researchId);
+    if (!existsSync(file)) return null;
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refuse an execute turn that never had a proposal turn, or whose accepted
+ * stubs bear no relation to what was proposed. Returns an error object to
+ * return verbatim, or null to proceed.
+ *
+ * Pure decision logic apart from the marker read, so the drift rules are
+ * testable without a vault.
+ */
+export function checkStubReviewGate({ marker, acceptedStubs = [], args = {} }) {
+  if (!marker) {
+    return {
+      error: 'STUB_REVIEW_REQUIRED',
+      message:
+        'No proposal turn recorded for this research doc. Spawning a milestone and epics is a two-turn flow: call heyspex_promote_research WITHOUT accepted_stubs first, show the proposed stubs to the human and let them edit or remove them, then call again with accepted_stubs. Passing stubs straight through means nobody saw them. (Break-glass: HEYSPEX_PROMOTE_REVIEW_GATE_OFF=1.)',
+      remedy: 'run the proposal phase (omit accepted_stubs) and confirm with the human',
+    };
+  }
+
+  const proposedNames = (marker.proposed_stub_names ?? []).map(normalizeStubName).filter(Boolean);
+  // The proposer can legitimately return nothing (its endpoint was down, or the
+  // doc yielded no stubs). The human then authors from scratch, so there is no
+  // proposal to drift from — the marker alone proves the turn happened.
+  if (proposedNames.length === 0) return null;
+
+  const acceptedNames = acceptedStubs.map((s) => normalizeStubName(s?.name)).filter(Boolean);
+  const overlap = acceptedNames.filter((n) => proposedNames.includes(n)).length;
+  if (overlap > 0) return null;
+
+  const note = typeof args.stub_edit_note === 'string' ? args.stub_edit_note.trim() : '';
+  if (note.length >= EDIT_NOTE_MIN_LENGTH) return null;
+
+  return {
+    error: 'STUB_REVIEW_DRIFT',
+    message:
+      `None of the ${acceptedNames.length} accepted stub(s) match any of the ${proposedNames.length} that were proposed and reviewed. That is either a full rewrite by the human — which is fine — or stubs invented after the review, which is what this gate exists to catch. Pass stub_edit_note (≥${EDIT_NOTE_MIN_LENGTH} chars) saying what the human changed and why, or re-run the proposal turn.`,
+    proposed_stub_names: marker.proposed_stub_names ?? [],
+    accepted_stub_names: acceptedStubs.map((s) => s?.name ?? ''),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase 2: execute (transactional writes)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function loadMilestoneEpicsList(milestoneRecord) {
+  const fm = getFrontmatterBlock(milestoneRecord.raw);
+  if (!fm) return [];
+  const list = parseListFieldBasenames(fm.block, 'epics');
+  return list ?? [];
+}
+
+function loadFrontmatterScalar(raw, field) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) return null;
+  return getScalarField(fm.block, field);
+}
+
+/**
+ * Owner-intent carry-through — resolve the source capture behind a research doc.
+ *
+ * The capture holds the OWNER'S words; research is evidence *about* those words.
+ * Spawned milestones/epics used to carry only `informed_by` / `derived_from`
+ * pointers to the research, so downstream planning re-derived intent from the
+ * research alone. When a research recommendation contradicted the capture,
+ * nothing surfaced it — the 2026-08-11 SpexCrawl drift cost four owner
+ * corrections, every one of them answered by text already sitting in the capture
+ * ([[HS-GIXC-CAP-KPZT-heyspex-should-actively-detect-and-preve]]).
+ *
+ * The bug path already does this correctly — `buildDiagnoseContent` in
+ * promote-capture.mjs drops the capture's Core Idea into the diagnose Symptom.
+ * This brings the plan path to the same parity.
+ *
+ * Fail-open by construction: no resolvable capture returns null and the stubs
+ * render exactly as they did before.
+ */
+function resolveOwnerIntent(vaultRoot, researchRaw) {
+  try {
+    const fm = getFrontmatterBlock(researchRaw);
+    if (!fm) return null;
+    let basenames = parseListFieldBasenames(fm.block, 'sources_captures') ?? [];
+    if (basenames.length === 0) {
+      // Research saved via heyspex_save_research bypasses the stub scaffold and
+      // so has no sources_captures: — fall back to capture-typed related: entries.
+      basenames = (parseListFieldBasenames(fm.block, 'related') ?? []).filter((b) =>
+        /(^|-)CAP(-|$)/i.test(b),
+      );
+    }
+    if (basenames.length === 0) return null;
+    const capturesDir = join(vaultRoot, 'specs', 'captures');
+    for (const basename of basenames) {
+      // Wikilinks may be either the full file basename or bare id (`HS-VNK3-CAP`),
+      // so fall back to prefix resolution — the id-only form is the common case.
+      let abs = join(capturesDir, `${basename}.md`);
+      if (!existsSync(abs)) {
+        const byPrefix = findFileByPrefix(capturesDir, basename);
+        if (!byPrefix) continue;
+        abs = join(capturesDir, byPrefix);
+      }
+      const raw = readFileSync(abs, 'utf8');
+      const body = getFrontmatterBlock(raw)?.body ?? raw;
+      const m = body.match(/#\s*Core Idea\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)/i);
+      const coreIdea = m ? m[1].trim() : '';
+      if (coreIdea) return { basename, coreIdea };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull the research doc's own `## JTBD (job-to-be-done)` section body, so
+ * spawned milestone/epic stubs can re-derive their altitude's slice of the
+ * job instead of starting from a blank placeholder ([[research-capture-protocol]]
+ * §"JTBD (job-to-be-done) framing"). Returns '' when the research has no such
+ * section (older docs, or research not yet updated) — callers then render a
+ * plain placeholder prompt.
+ */
+function extractResearchJtbd(researchRaw) {
+  const fm = getFrontmatterBlock(researchRaw);
+  const body = fm ? fm.body : researchRaw;
+  const m = body.match(/##\s*JTBD\s*\(job-to-be-done\)\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)/i);
+  if (!m) return '';
+  return m[1].trim();
+}
+
+/**
+ * Render the `## JTBD (job-to-be-done)` section injected above
+ * `## Intended outcome` in spawned milestone/epic stubs — re-derived (not
+ * copied) to that altitude's slice of the job, same discipline as the
+ * existing Intended-outcome cascade ([[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]).
+ */
+function renderJtbdSection(researchJtbd, altitudeLabel) {
+  const seedBlock = researchJtbd
+    ? `**Job stated by research:**\n${researchJtbd}\n\n**This ${altitudeLabel}'s slice of the job:** _TBD — re-derive what part of that job this ${altitudeLabel} serves; do not copy the research text verbatim._`
+    : `**Job:** _TBD — the source research has no JTBD section yet; state the job this ${altitudeLabel} serves._`;
+  return `## JTBD (job-to-be-done)
+
+<!-- Re-derive to this ${altitudeLabel}'s slice of the job — do NOT copy verbatim (same discipline as Intended outcome, [[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]). -->
+${seedBlock}
+
+`;
+}
+
+/** Render the owner-intent block injected above `## Intended outcome`. */
+function renderOwnerIntentSection(ownerIntent) {
+  if (!ownerIntent) return '';
+  const quoted = ownerIntent.coreIdea
+    .split('\n')
+    .map((line) => `> ${line}`.trimEnd())
+    .join('\n');
+  return `## Owner intent — verbatim, from [[${ownerIntent.basename}]]
+
+${quoted}
+
+_This is the owner's own statement of what they asked for. Research is evidence **about** this intent, never a replacement for it. **Where the research and this text disagree, this text wins** — and the disagreement must be stated explicitly below rather than silently resolved in the research's favour._
+
+`;
+}
+
+/** Frontmatter line linking a spec back to the capture that originated it. */
+function renderSourceCaptureField(ownerIntent) {
+  return ownerIntent ? `source_capture: "[[${ownerIntent.basename}]]"\n` : '';
+}
+
+function buildMilestoneStubContent(
+  milestoneId,
+  fileKey,
+  familyKey,
+  milestoneName,
+  researchBasename,
+  now,
+  ownerIntent = null,
+  researchJtbd = '',
+) {
+  const today = now.slice(0, 10);
+  return `---
+id: ${milestoneId}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(milestoneName)}
+type: milestone
+status: open
+owner: pwher
+created: "${now}"
+updated: "${now}"
+target_date: ""
+tags:
+  - milestone
+epics: []
+informed_by:
+  - "[[${researchBasename}]]"
+${renderSourceCaptureField(ownerIntent)}related: []
+---
+
+# ${milestoneName}
+
+_Milestone stub created by /hs-promote-research from [[${researchBasename}]]. Replace this prose with the actual milestone framing — why these epics ship together as one coherent restructure or release._
+
+${renderOwnerIntentSection(ownerIntent)}${renderJtbdSection(researchJtbd, 'milestone')}## Intended outcome
+
+<!-- Re-derive from [[${researchBasename}]]'s intended outcome — do NOT copy it ([[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]).${ownerIntent ? ' Check it against the Owner intent above; where they disagree, the capture wins — say so here.' : ''} -->
+**Outcome at the milestone altitude:** _What outcome does this milestone deliver?_
+
+**Moves (↑ link):** _Which research outcome does it move — and by what mechanism of contribution? Name the mechanism; don't echo the parent's words._
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-research (agent) | Created from research [[${researchBasename}]]. |
+`;
+}
+
+function buildEpicContent(
+  { id, fileKey, familyKey, basename, name, kind, effort, depends_on, rationale, pillarFrontmatterValue },
+  milestoneBasename,
+  researchBasename,
+  now,
+  ownerIntent = null,
+  researchJtbd = '',
+) {
+  const today = now.slice(0, 10);
+  const dependsBlock =
+    Array.isArray(depends_on) && depends_on.length > 0
+      ? `depends_on:\n${depends_on.map((d) => `  - "[[${d}]]"`).join('\n')}`
+      : 'depends_on: []';
+  return `---
+id: ${id}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: epic
+kind: ${kind}
+effort: ${effort}
+requires_user_testing: false
+status: open
+owner: pwher
+created: "${now}"
+updated: "${now}"
+parent: "[[${milestoneBasename}]]"
+milestone: "[[${milestoneBasename}]]"
+pillar: ${pillarFrontmatterValue}
+derived_from: "[[${researchBasename}]]"
+${renderSourceCaptureField(ownerIntent)}${dependsBlock}
+tags:
+  - epic
+children: []
+related: []
+---
+
+# ${name}
+
+${rationale ? rationale.trim() : '_Epic stub spawned by /hs-promote-research; rationale and acceptance criteria pending._'}
+
+${renderOwnerIntentSection(ownerIntent)}${renderJtbdSection(researchJtbd, 'epic')}## Intended outcome
+
+<!-- Re-derive from [[${milestoneBasename}]]'s intended outcome — do NOT copy it ([[HS-K4D4-2I29-RES-outcome-cascade-through-a-requirements-h]]).${ownerIntent ? ' Check it against the Owner intent above; where they disagree, the capture wins — say so here.' : ''} -->
+**User-visible outcome of this epic:** _What changes for the user when this epic ships?_
+
+**Moves (↑ link):** _Which milestone outcome does it move — and by what mechanism of contribution?_
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | promote-research (agent) | Spawned by /hs-promote-research from research [[${researchBasename}]] under milestone [[${milestoneBasename}]]. |
+`;
+}
+
+/**
+ * Shape a valid family key must satisfy ([[HS-8O69-EPIC-LKF9-relational-family-graph-authoring]] /
+ * validator `FAMILY_FIELD_MALFORMED`) — mirrors spec-id-lib.mjs's (module-
+ * private) `FAMILY_KEY_SHAPE_RE` and validate-vault-ids.mjs's own copy of the
+ * same shape.
+ */
+const FAMILY_KEY_SHAPE_RE = /^[A-Z0-9]{4,}$/;
+
+/**
+ * The family key a spawned milestone/epic should inherit from its source
+ * research doc ([[HS-GZM9-DIAG-G419]]). Tries each candidate in order and
+ * returns the FIRST one that is well-formed — a malformed candidate
+ * (lowercase, <4 chars, punctuation) is skipped, never propagated, so it can
+ * never leak into every spawned file and trip the validator's
+ * `FAMILY_FIELD_MALFORMED`:
+ *
+ *   1. the research doc's explicit `family:` frontmatter field
+ *   2. the family key parsed positionally from the research doc's `id:`
+ *   3. the family key parsed positionally from the research doc's basename
+ *
+ * Returns null when no candidate is derivable/well-formed — callers fall
+ * back further to the freshly-minted key of the spec being created.
+ *
+ * @param {{ frontmatter?: { id?: string|null, family?: string|null }, basename?: string|null }} research
+ */
+function inheritedResearchFamilyKey(research) {
+  const candidates = [
+    research?.frontmatter?.family,
+    parseSpecId(research?.frontmatter?.id)?.familyKey,
+    parseSpecId(research?.basename)?.familyKey,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && FAMILY_KEY_SHAPE_RE.test(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function runExecutePhase(args, ctx, deps) {
+  const now = (deps?.clock ?? isoNow)();
+  const today = now.slice(0, 10);
+  const author = 'promote-research (agent)';
+
+  // Family inheritance ([[HS-GZM9-DIAG-G419]], mirrors promote-capture.mjs /
+  // split-research.mjs): the spawned milestone AND every spawned epic inherit
+  // the SOURCE RESEARCH DOC's family key — explicit `family:` frontmatter
+  // wins IF well-formed, else the family key parsed positionally from the
+  // research doc's id/basename (era-aware dual-read). Era-3 file-key-first
+  // ([[naming-v3-7-rulings-hs-namespace-kept]]): the inherited family lands in
+  // the basename (`HS-<fileKey>-<familyKey>-<TYPE>-<slug>`) and in `family:`;
+  // `id:` keys onto the file key alone.
+  const inheritedFamilyKey = inheritedResearchFamilyKey(ctx.research);
+
+  // ── Resolve / allocate target milestone basename + path ───────────────────
+  let milestoneBasename;
+  let milestoneAbsPath;
+  let milestoneRelPath;
+  let milestoneCreated = false;
+  let milestoneId;
+  let milestoneFileKey = null;
+  let milestoneFamilyKey = null;
+  let milestoneInformedByAlreadyHasResearch = false;
+  let existingMilestoneEpics = [];
+
+  if (ctx.targetResolution.mode === 'new') {
+    // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+    // and (V3) the anchor for `id:` itself.
+    milestoneFileKey = allocateFileKey(collectOccupiedKeysEitherKind(ctx.vaultRoot), {
+      randomUnit: deps?.randomUnit,
+    });
+    // Family: inherit from the research doc; the legacy allocator's
+    // `HS-<family>-MIL` draw is only the fallback family source (never blank —
+    // last resort is the fresh file key itself, matching the old chain).
+    milestoneFamilyKey =
+      inheritedFamilyKey ??
+      parseSpecId(allocateMilestoneId(ctx.vaultRoot, { randomUnit: deps?.randomUnit }))?.familyKey ??
+      milestoneFileKey;
+    milestoneId = `HS-${milestoneFileKey}`;
+    const slug = deriveSlug(ctx.targetResolution.name);
+    milestoneBasename = `${milestoneId}-${milestoneFamilyKey}-MIL-${slug}`;
+    milestoneAbsPath = join(ctx.vaultRoot, 'specs', 'milestones', `${milestoneBasename}.md`);
+    milestoneRelPath = join('specs', 'milestones', `${milestoneBasename}.md`);
+    milestoneCreated = true;
+  } else {
+    const ms = ctx.targetResolution.milestone;
+    milestoneBasename = ms.basename;
+    milestoneAbsPath = ms.absPath;
+    milestoneRelPath = ms.relPath;
+    milestoneId = loadFrontmatterScalar(ms.raw, 'id') ?? milestoneBasename;
+    existingMilestoneEpics = ms.epicsList ?? [];
+    const informedByList = parseListFieldBasenames(getFrontmatterBlock(ms.raw).block, 'informed_by') ?? [];
+    milestoneInformedByAlreadyHasResearch = informedByList.includes(
+      ctx.research.basename,
+    );
+  }
+
+  // ── Resolve augment epics + validate they live under the target milestone ─
+  const augmentEpics = [];
+  if (args.intent === 'augment' || args.intent === 'both') {
+    for (const epicRef of args.augment_epic_ids) {
+      const found = findEpicByIdOrBasename(ctx.vaultRoot, epicRef);
+      if (!found) {
+        return {
+          error: 'AUGMENT_EPIC_NOT_FOUND',
+          message: `augment_epic_ids entry ${epicRef} did not resolve to a file under specs/epics/`,
+        };
+      }
+      // If the milestone exists already, the epic must already belong to it.
+      if (ctx.targetResolution.mode === 'existing' && !existingMilestoneEpics.includes(found.basename)) {
+        return {
+          error: 'AUGMENT_EPIC_NOT_IN_MILESTONE',
+          message: `epic ${found.basename} is not listed in milestone ${milestoneBasename}'s \`epics:\` array`,
+        };
+      }
+      augmentEpics.push(found);
+    }
+  }
+
+  // ── Prepare spawned epic records (from accepted_stubs) ────────────────────
+  const acceptedStubs = Array.isArray(args.accepted_stubs) ? args.accepted_stubs : [];
+  if ((args.intent === 'spawn' || args.intent === 'both') && acceptedStubs.length === 0) {
+    return {
+      error: 'NO_ACCEPTED_STUBS',
+      message:
+        'intent includes "spawn" but no accepted_stubs provided. Run the proposal phase first (omit accepted_stubs) and confirm with the human.',
+    };
+  }
+
+  const spawnedEpicSpecs = [];
+  if (acceptedStubs.length > 0) {
+    const { epics: occupiedEpics } = collectOccupiedVaultIds(ctx.vaultRoot);
+    // One occupied set across the whole loop — files are not on disk yet, so a
+    // fresh vault walk per stub would let two stubs draw the same file key.
+    const occupiedFileKeys = collectOccupiedKeysEitherKind(ctx.vaultRoot); // union: file+family keys (HS-SJOT)
+    for (const stub of acceptedStubs) {
+      if (!stub?.name?.trim()) {
+        return {
+          error: 'INVALID_STUB',
+          message: 'every accepted stub must have a non-empty name',
+        };
+      }
+      // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+      // and (V3) the anchor for `id:` itself.
+      const fileKey = allocateFileKey(occupiedFileKeys, { randomUnit: deps?.randomUnit });
+      occupiedFileKeys.add(fileKey);
+      // Family: inherit from the research doc; the legacy allocator's
+      // `HS-<family>-EPIC` draw is only the fallback family source.
+      let epicFamilyKey = inheritedFamilyKey;
+      if (!epicFamilyKey) {
+        const allocatedEpicFamilyId = allocateRandomVaultId('epic', occupiedEpics, {
+          randomUnit: deps?.randomUnit,
+        });
+        occupiedEpics.add(allocatedEpicFamilyId);
+        epicFamilyKey = parseSpecId(allocatedEpicFamilyId)?.familyKey ?? fileKey;
+      }
+      const epicId = `HS-${fileKey}`;
+      const slug = deriveSlug(stub.name);
+      const basename = `${epicId}-${epicFamilyKey}-EPIC-${slug}`;
+      spawnedEpicSpecs.push({
+        id: epicId,
+        fileKey,
+        familyKey: epicFamilyKey,
+        basename,
+        name: stub.name.trim(),
+        kind: stub.kind ?? 'feature',
+        effort: typeof stub.effort === 'number' ? stub.effort : 3,
+        depends_on: Array.isArray(stub.depends_on) ? stub.depends_on : [],
+        rationale: typeof stub.rationale === 'string' ? stub.rationale : '',
+        // Per-stub pillar override; falls back to the batch-default `args.pillar`
+        // in the gate below (stub value wins — [[pillar-assignment-protocol]]).
+        pillar: typeof stub.pillar === 'string' ? stub.pillar : undefined,
+        relPath: join('specs', 'epics', `${basename}.md`),
+        absPath: join(ctx.vaultRoot, 'specs', 'epics', `${basename}.md`),
+      });
+    }
+  }
+
+  // ── Resolve depends_on against sibling stubs + existing vault specs ───────
+  //    ([[HS-UM2Z-TH36-DIAG]]). Phase-2 `accepted_stubs[].depends_on` carries
+  //    human-readable stub NAMES (the only sibling identifier available before
+  //    ids are minted, above) — writing them straight into frontmatter as
+  //    `[[<name>]]` produces a wikilink that resolves to nothing. Substitute
+  //    each entry that matches a sibling stub's `name` with that sibling's
+  //    freshly-minted basename; else resolve against an existing vault epic by
+  //    id/basename; else DROP it (warn) rather than write an unresolvable link.
+  const depWarnings = [];
+  if (spawnedEpicSpecs.length > 0) {
+    const siblingNameToBasename = new Map();
+    for (const s of spawnedEpicSpecs) {
+      siblingNameToBasename.set(s.name.trim().toLowerCase(), s.basename);
+    }
+    for (const spec of spawnedEpicSpecs) {
+      const resolved = [];
+      for (const raw of spec.depends_on) {
+        const d = typeof raw === 'string' ? raw.trim() : '';
+        if (!d) continue;
+        let target = siblingNameToBasename.get(d.toLowerCase());
+        if (!target) {
+          const found = findEpicByIdOrBasename(ctx.vaultRoot, d);
+          if (found) target = found.basename;
+        }
+        if (target) {
+          resolved.push(target);
+        } else {
+          depWarnings.push({ epic: spec.name, unresolved: d });
+        }
+      }
+      spec.depends_on = resolved;
+    }
+  }
+
+  // ── Pillar gate — every spawned epic must resolve to a pillar doc that
+  //    exists on disk BEFORE any file is written (no partial spawn), mirroring
+  //    POST /api/specs' `pillar_required` hard-block ([[pillar-assignment-
+  //    protocol]]). Per-stub `pillar` wins over the top-level `args.pillar`
+  //    batch default. HS-TASK-QQHP defect #2.
+  if (spawnedEpicSpecs.length > 0) {
+    for (const spec of spawnedEpicSpecs) {
+      const pillarRef = spec.pillar ?? args.pillar;
+      const resolved = resolvePillar(ctx.vaultRoot, pillarRef);
+      if (!resolved.ok) {
+        return {
+          error: 'pillar_required',
+          message: pillarRef
+            ? `epic "${spec.name}" pillar \`${pillarRef}\` does not resolve to a pillar under specs/pillars/ — pick an existing pillar or author a new one first`
+            : `epic "${spec.name}" requires a \`pillar:\` wikilink to an HS-PILR theme — pass a top-level \`pillar\` batch default or a per-stub \`pillar\`; pick an existing pillar or author a new one first`,
+          existing_pillars: listVaultPillars(ctx.vaultRoot),
+          create_pillar: {
+            tool: 'heyspex_file_spec',
+            call: { type: 'pillar', name: '<theme name>' },
+            note: 'When no existing theme fits, author a net-new pillar, then re-file with `pillar: [[<new HS-PILR id>]]` (top-level `pillar` batch default or a per-stub override).',
+          },
+        };
+      }
+      spec.pillarFrontmatterValue = resolved.frontmatterValue;
+    }
+  }
+
+  // ── Stage all writes ──────────────────────────────────────────────────────
+  const writes = [];
+
+  // The owner's own words from the originating capture, carried onto every spec
+  // this promotion creates so intent survives the hop into the plan graph.
+  // Null when no capture resolves — stubs then render exactly as before.
+  const ownerIntent = resolveOwnerIntent(ctx.vaultRoot, ctx.research.raw);
+  // HS-M1MW: seed spawned stubs' JTBD sections from the research doc's own
+  // JTBD section, when present.
+  const researchJtbd = extractResearchJtbd(ctx.research.raw);
+
+  // 1. Milestone (create-if-new, else update later via line-surgical helper).
+  //    Family inheritance (HS-TASK-QQHP defect #1) is resolved once, up top,
+  //    where the era-3 basenames/ids are composed.
+  if (milestoneCreated) {
+    const newContent = buildMilestoneStubContent(
+      milestoneId,
+      milestoneFileKey,
+      milestoneFamilyKey,
+      ctx.targetResolution.name,
+      ctx.research.basename,
+      now,
+      ownerIntent,
+      researchJtbd,
+    );
+    writes.push({ kind: 'create', absPath: milestoneAbsPath, content: newContent });
+  }
+
+  // 2. Spawned epic files (spec.familyKey was resolved at mint time above).
+  for (const spec of spawnedEpicSpecs) {
+    const content = buildEpicContent(
+      spec,
+      milestoneBasename,
+      ctx.research.basename,
+      now,
+      ownerIntent,
+      researchJtbd,
+    );
+    writes.push({ kind: 'create', absPath: spec.absPath, content });
+  }
+
+  // 3. Updated research file (set enhances + spawned_epics + enhances_epics;
+  //    status stays `open` — research is evergreen, [[research-is-evergreen]]).
+  const researchContent = buildUpdatedResearchContent(
+    ctx.research.raw,
+    {
+      milestoneBasename,
+      spawnedEpicBasenames: spawnedEpicSpecs.map((s) => s.basename),
+      augmentedEpicBasenames: augmentEpics.map((e) => e.basename),
+      now,
+      today,
+      author,
+    },
+  );
+  writes.push({ kind: 'update', absPath: ctx.research.absPath, content: researchContent });
+
+  // 4. Updated milestone file (only if not just-created and we need informed_by/epics updates).
+  if (!milestoneCreated) {
+    const updatedMilestoneContent = buildUpdatedMilestoneContent(
+      ctx.targetResolution.milestone.raw,
+      {
+        researchBasename: ctx.research.basename,
+        now,
+      },
+    );
+    if (updatedMilestoneContent !== ctx.targetResolution.milestone.raw) {
+      writes.push({ kind: 'update', absPath: milestoneAbsPath, content: updatedMilestoneContent });
+    }
+  }
+
+  // ── Commit ────────────────────────────────────────────────────────────────
+  const commitResult = commitWrites(writes);
+  if (!commitResult.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commitResult.error?.message ?? 'unknown write failure',
+      rollback_error: commitResult.error?.rollbackError,
+    };
+  }
+
+  // ── Post-commit: append each new epic basename to milestone.epics via the
+  //    shared line-surgical helper, so the bidirectional integrity rule from
+  //    [[HS-TASK-T5PX]] (milestone.epics ⇔ epic.milestone) is preserved.
+  for (const spec of spawnedEpicSpecs) {
+    try {
+      appendEpicToMilestone(ctx.vaultRoot, milestoneBasename, spec.basename);
+    } catch (err) {
+      return {
+        error: 'MILESTONE_EPICS_MIRROR_FAILED',
+        message: `epic files written but failed to append to milestone.epics: ${err.message}`,
+        partial: true,
+      };
+    }
+  }
+
+  // ── Post-commit: register a freshly-created milestone into the default
+  //    roadmap's `roadmap_manifest.milestones` ([[HS-6DL4-2OO7-DIAG]]) — the
+  //    same manifest-append `registerSpec` already performs for
+  //    `heyspex_file_spec`'s createSpec path, so a promote-research-spawned
+  //    milestone doesn't sit unreachable from the roadmap. Best-effort: a
+  //    missing/misconfigured roadmap doc is surfaced as a warning rather than
+  //    failing an otherwise-successful promote (the milestone/epic files are
+  //    already committed at this point).
+  let roadmapRegistration;
+  if (milestoneCreated) {
+    try {
+      const reg = registerSpec(ctx.vaultRoot, {
+        spec_id: milestoneBasename,
+        roadmap_id: args.roadmap_id || 'HS-ROADMAP-PRODUCT',
+        updateTimestamps: false,
+      });
+      roadmapRegistration = reg?.success === false
+        ? { ok: false, error: reg.error, message: reg.message }
+        : { ok: true, roadmap_id: reg?.roadmap_id, already_registered: !!reg?.already_registered };
+    } catch (err) {
+      roadmapRegistration = { ok: false, error: 'ROADMAP_REGISTER_THREW', message: err.message };
+    }
+  }
+
+  return {
+    phase: 'executed',
+    milestone_id: milestoneId,
+    milestone_basename: milestoneBasename,
+    milestone_path: milestoneRelPath,
+    milestone_created: milestoneCreated,
+    spawned_epics: spawnedEpicSpecs.map((s) => ({
+      id: s.id,
+      basename: s.basename,
+      path: s.relPath,
+    })),
+    augmented_epics: augmentEpics.map((e) => e.basename),
+    research_id: ctx.research.frontmatter?.id ?? args.research_id,
+    research_path: ctx.research.relPath,
+    research_status_after: ctx.researchStatus ?? 'open',
+    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    human_review_required: false,
+    ...(depWarnings.length > 0 ? { depends_on_warnings: depWarnings } : {}),
+    ...(roadmapRegistration ? { roadmap_registration: roadmapRegistration } : {}),
+  };
+}
+
+function buildUpdatedResearchContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('research has no frontmatter — cannot promote');
+  }
+  let block = fm.block;
+  // 1. enhances: single wikilink to target milestone.
+  block = setScalarField(block, 'enhances', `"[[${params.milestoneBasename}]]"`);
+  // 2. spawned_epics: append each new epic basename.
+  for (const basename of params.spawnedEpicBasenames) {
+    block = appendToListField(block, 'spawned_epics', basename).block;
+  }
+  // 3. enhances_epics: append each augmented epic basename.
+  for (const basename of params.augmentedEpicBasenames) {
+    block = appendToListField(block, 'enhances_epics', basename).block;
+  }
+  // 4. updated: now. (status is intentionally NOT touched — research is
+  //    evergreen and stays `status: open`; see [[research-is-evergreen]].)
+  block = bumpUpdated(block, params.now);
+
+  const change = `Promoted to milestone [[${params.milestoneBasename}]] via /hs-promote-research; spawned ${params.spawnedEpicBasenames.length} epic(s), augmented ${params.augmentedEpicBasenames.length} epic(s). Research stays evergreen (status: open).`;
+  const newBody = appendChangeLogRow(fm.body, params.today, params.author, change);
+  return `${fm.open}${block}${fm.close}${newBody}`;
+}
+
+function buildUpdatedMilestoneContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) {
+    throw new Error('milestone has no frontmatter — cannot update informed_by');
+  }
+  const informedByList = parseListFieldBasenames(fm.block, 'informed_by') ?? [];
+  if (informedByList.includes(params.researchBasename)) return raw;
+  let block = fm.block;
+  block = appendToListField(block, 'informed_by', params.researchBasename).block;
+  block = bumpUpdated(block, params.now);
+  return `${fm.open}${block}${fm.close}${fm.body}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function executePromoteResearch(vaultRoot, args = {}, deps = {}) {
+  const validationError = validateInputShape(args);
+  if (validationError) return validationError;
+
+  // 1. Load research file. Resolution happens FIRST (exact basename → .md /
+  // wikilink-stripped → frontmatter id: → unambiguous prefix); the "is this
+  // really research?" check reads the resolved file's `type:`.
+  const resolved = findResearchByIdLocal(vaultRoot, args.research_id);
+  if (!resolved || resolved.error) {
+    return (
+      resolved ?? {
+        error: 'RESEARCH_NOT_FOUND',
+        message: `research ${args.research_id} not found under specs/research/`,
+      }
+    );
+  }
+  const research = resolved.record;
+  research.frontmatter = {};
+  const researchFm = getFrontmatterBlock(research.raw);
+  if (researchFm) {
+    research.frontmatter.id = getScalarField(researchFm.block, 'id') ?? args.research_id;
+    research.frontmatter.name = getScalarField(researchFm.block, 'name') ?? '';
+    // Explicit family inheritance source (HS-TASK-QQHP defect #1) — see
+    // inheritedFamilyKey in runExecutePhase.
+    research.frontmatter.family = getScalarField(researchFm.block, 'family') ?? null;
+  }
+
+  const researchState = validateResearchState(research);
+  if (researchState.error) return researchState;
+
+  // 1b. Unfinished-stub gate — block promotion (both phases; a review call
+  // proposing epic stubs from an unresearched doc is no more useful than an
+  // execute call spawning them) until the research body has actually been
+  // written. See findUnresolvedResearchPlaceholders above.
+  const unresolvedPlaceholders = findUnresolvedResearchPlaceholders(research.raw);
+  if (unresolvedPlaceholders > 0) {
+    return {
+      error: 'RESEARCH_STILL_STUB',
+      message:
+        `research ${research.basename} still has ${unresolvedPlaceholders} unresolved ` +
+        '"_TBD — fill in this section._" placeholder(s) from its promote-capture outline ' +
+        'stub — the research findings must be authored before promoting it into a ' +
+        'milestone/epics. Fill it in by running the /hs-res method (SpexCrawl gather via ' +
+        'the Companion + DeepSeek synthesis); do NOT author the research yourself in the ' +
+        'main session — that skips the routed research seats. Approving the OUTLINE only ' +
+        'confirms its shape (section headings); it is not the same as the research having ' +
+        'been done, and spawning work items from an unresearched stub produces epics with ' +
+        'no real findings behind them.',
+      research_path: research.relPath,
+      unresolved_placeholder_count: unresolvedPlaceholders,
+    };
+  }
+
+  // 2. Resolve target milestone.
+  const targetResolution = resolveTargetMilestone(vaultRoot, args);
+  if (targetResolution.error) return targetResolution;
+
+  if (targetResolution.mode === 'existing') {
+    const fm = getFrontmatterBlock(targetResolution.milestone.raw);
+    targetResolution.milestone.epicsList = fm
+      ? parseListFieldBasenames(fm.block, 'epics') ?? []
+      : [];
+    targetResolution.milestone.frontmatter = fm
+      ? {
+          id: getScalarField(fm.block, 'id'),
+          name: getScalarField(fm.block, 'name'),
+        }
+      : {};
+    targetResolution.milestone.name = targetResolution.milestone.frontmatter.name ?? targetResolution.milestone.basename;
+  }
+
+  // 3. Bidirectional conflict check (AC #4) + milestone attach policy.
+  if (targetResolution.mode === 'existing') {
+    const attachPolicy = validateExistingMilestoneAttachable(
+      targetResolution.milestone.raw,
+      args,
+    );
+    if (attachPolicy.error) return attachPolicy;
+
+    const conflict = validateBidirectionalEnhances(
+      researchState.enhances,
+      targetResolution.milestone.basename,
+    );
+    if (conflict) return conflict;
+  } else if (researchState.enhances) {
+    // Already enhances a milestone but target is NEW — refuse, the human should
+    // either split the research or pick the existing milestone.
+    return {
+      error: 'RESEARCH_ENHANCES_CONFLICT',
+      message: `research already enhances ${researchState.enhances}; pass target_milestone matching that basename or split the research first.`,
+      existing: researchState.enhances,
+    };
+  }
+
+  const ctx = {
+    vaultRoot,
+    research,
+    researchStatus: researchState.status,
+    targetResolution,
+  };
+
+  // 4. Phase split.
+  const hasAcceptedStubs =
+    Array.isArray(args.accepted_stubs) && args.accepted_stubs.length > 0;
+  const wantsStubProposal =
+    (args.intent === 'spawn' || args.intent === 'both') && !hasAcceptedStubs;
+
+  if (wantsStubProposal) {
+    return runProposalPhase(args, ctx, deps);
+  }
+
+  // Two-turn review gate: an execute turn that spawns epics must descend from a
+  // proposal turn the human actually saw. `augment` writes no epic stubs, so it
+  // is single-phase by design and not gated here.
+  if (hasAcceptedStubs && process.env.HEYSPEX_PROMOTE_REVIEW_GATE_OFF !== '1') {
+    const gate = checkStubReviewGate({
+      marker: readStubReviewMarker(vaultRoot, research.frontmatter?.id ?? args.research_id),
+      acceptedStubs: args.accepted_stubs,
+      args,
+    });
+    if (gate) return gate;
+  }
+
+  return runExecutePhase(args, ctx, deps);
+}
+
+export const __testables = {
+  appendToListField,
+  setScalarField,
+  buildUpdatedResearchContent,
+  buildUpdatedMilestoneContent,
+  buildMilestoneStubContent,
+  buildEpicContent,
+  resolveOwnerIntent,
+  renderOwnerIntentSection,
+  parseListFieldBasenames,
+  getFrontmatterBlock,
+  allocateMilestoneId,
+  validateInputShape,
+  normalizeResearchRef,
+  findResearchByIdLocal,
+  validateExistingMilestoneAttachable,
+  MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES,
+  resolvePillar,
+  listVaultPillars,
+  normalizePillarRef,
+  inheritedResearchFamilyKey,
+  matchCaseInsensitiveExact,
+  findUnresolvedResearchPlaceholders,
+  checkStubReviewGate,
+  writeStubReviewMarker,
+  stubReviewMarkerPath,
+  EDIT_NOTE_MIN_LENGTH,
+};