heyspex 0.1.0 → 0.2.1

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

@@ -6,10 +6,12 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { prepareVaultPlanContent } from './plan-ingest.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
+import { resolveDefaultRoadmap } from './roadmap-default.mjs';
 import {
   allocateFileKey,
   collectOccupiedFileKeysFromVault,
@@ -22,6 +24,36 @@ import {
   formatSummaryFrontmatterField,
   resolveAuthoredSummaryValue,
 } from './summary-contract.mjs';
+// The cloud (console) write path. Transport-free and side-effect-free, so it
+// is safe to import statically; the actual transport (console-transport.mjs)
+// and the mode resolver (read-path.mjs) are DYNAMIC-imported at call time in
+// {@link resolveCloudDeps} / {@link resolveWriteModeForPlanPush} so a local-mode
+// run — and every existing local-mode test — keeps exactly the module graph it
+// had before cloud mode existed.
+import { cloudWriteFailure, createSpecViaConsole } from './cloud-vault-writes.mjs';
+
+// scripts/validate-vault-ids.mjs is a CODE-repo artifact that ships with this
+// package — since the repo split (2026-08-31) the vault root no longer holds
+// it, so resolve it relative to THIS file's checkout first and fall back to
+// the vault root only for pre-split layouts where they were the same repo.
+// `HS_PKG_ROOT` wins when set (same precedence as dev-tools.mjs's
+// CHECKOUT_ROOT / plan-review.mjs's resolveCodeAuditRoots).
+const CHECKOUT_ROOT = resolveCodeRoot({
+  packageRoot: dirname(dirname(dirname(fileURLToPath(import.meta.url)))),
+});
+
+/**
+ * Resolve scripts/validate-vault-ids.mjs against the code checkout first,
+ * falling back to `vaultRoot` for pre-split layouts where the vault and the
+ * code repo were the same checkout. Returns `null` when it exists in neither
+ * (the pre-existing "skipped" behavior).
+ */
+function resolveValidateVaultIdsScript(vaultRoot) {
+  const local = join(CHECKOUT_ROOT, 'scripts', 'validate-vault-ids.mjs');
+  if (existsSync(local)) return local;
+  const legacy = join(vaultRoot, 'scripts', 'validate-vault-ids.mjs');
+  return existsSync(legacy) ? legacy : null;
+}
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Milestone-parent resolution + bidirectional mirror-update (HS-TASK-T5PX)
@@ -218,20 +250,19 @@ const DESIGN_DECISIONS = {
 };
 
 /**
- * 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).
+ * Detect if plan content mentions web-app file paths (`spex-console/` and
+ * component-shaped sources).
  * @param {string} content - Plan markdown or epic body
  * @returns {boolean}
  */
 function detectConsolePaths(content) {
-  // Look for spex-console (and legacy-cockpit) file path patterns
+  // Look for spex-console 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
+    /spex-console\/src\//i,
+    /spex-console\/components\//i,
+    /spex-console\/app\//i,
+    /spex-console.*\.tsx/i,
+    /spex-console.*\.ts/i,
     /\bsurface\b.*\b(tsx?|component)\b/i,
   ];
 
@@ -843,6 +874,7 @@ const VAULT_ID_MIN_SUFFIX_LENGTH = 4;
 const KIND_TYPE_LABEL = { task: 'TASK', epic: 'EPIC' };
 
 import { deriveSlug } from './promotion-helpers.mjs';
+import { resolveCodeRoot } from '../../scripts/lib/shared-path-helpers.mjs';
 export { deriveSlug };
 
 function randomSuffix(length, charset = VAULT_ID_CHARSET) {
@@ -1181,7 +1213,22 @@ function buildOnDeckBanner(reason) {
 // / `focus-history.jsonl` writer here anymore ([[no-fallbacks-by-default]]; the
 // focus.yaml-fallback incident).
 
-export function executePushPlan(vaultRoot, args) {
+/**
+ * `heyspex_push_plan`.
+ *
+ * WRITE MODE ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]):
+ * `options.vaultWriteMode` selects where the epic lands and defaults to
+ * `'local'`, so every pre-existing two-argument caller keeps the byte-identical
+ * synchronous disk path below. `'cloud'` delegates to
+ * {@link pushPlanViaConsole} and therefore returns a PROMISE — resolve the mode
+ * once at the handler entry ({@link executePushPlanCloudAware}) and `await` the
+ * result, which is correct for both modes (awaiting the sync local object is a
+ * no-op).
+ */
+export function executePushPlan(vaultRoot, args, options = {}) {
+  if ((options.vaultWriteMode ?? 'local') === 'cloud') {
+    return pushPlanViaConsole(vaultRoot, args, options);
+  }
   const {
     epic_name: epicName,
     summary: epicSummaryArg,
@@ -1377,13 +1424,14 @@ ${epicBody}
 
   let validateOk = null;
   let validateMessage = null;
-  const validateScript = join(vaultRoot, 'scripts', 'validate-vault-ids.mjs');
-  if (existsSync(validateScript)) {
+  const validateScript = resolveValidateVaultIdsScript(vaultRoot);
+  if (validateScript) {
     try {
       execFileSync(process.execPath, [validateScript], {
-        cwd: vaultRoot,
+        cwd: dirname(validateScript),
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, HEYSPEX_VALIDATE_ROOT: vaultRoot },
       });
       validateOk = true;
     } catch (e) {
@@ -1392,7 +1440,7 @@ ${epicBody}
     }
   } else {
     validateOk = null;
-    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not in vault root)';
+    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not found in the code root or vault root)';
   }
 
   // Reuse the pre-flight conflict detection result computed before file writes
@@ -1415,7 +1463,13 @@ ${epicBody}
       spec_path: epicRelPath,
     },
     children: [],
-    focus_written: onDeck,
+    // NOT a claim that the pin landed — this function is sync and cannot write to
+    // Neon (see the note above). It reports the REQUEST (`on_deck`), and the async
+    // caller (`handlePushPlan`) overwrites this with the measured result of
+    // `writeFocusSelectionVendor`. `null` = "not attempted here / unknown", so a
+    // path that somehow skips the caller cannot read as a successful pin
+    // ([[HS-IOJW-5YDH-DIAG]] sweep idiom: report the result, never the request).
+    focus_written: onDeck ? null : false,
     focus_reason: computedFocusReason,
     validate_vault_ids: validateOk,
     validate_message: validateMessage,
@@ -1459,8 +1513,15 @@ ${epicBody}
 /**
  * Retroactively create an epic + child tasks for completed work.
  * All specs are created with status: in_review and a review doc is auto-generated.
+ *
+ * Same write-mode contract as {@link executePushPlan}: `options.vaultWriteMode`
+ * defaults to `'local'` (byte-identical synchronous disk path), `'cloud'`
+ * delegates to {@link shipEpicViaConsole} and returns a Promise.
  */
-export function executeShipEpic(vaultRoot, args) {
+export function executeShipEpic(vaultRoot, args, options = {}) {
+  if ((options.vaultWriteMode ?? 'local') === 'cloud') {
+    return shipEpicViaConsole(vaultRoot, args, options);
+  }
   const {
     epic_name: epicName,
     summary = '',
@@ -1471,7 +1532,7 @@ export function executeShipEpic(vaultRoot, args) {
     effort = 3,
     tags = [],
     related = [],
-    roadmap_id: roadmapId = 'HS-ROADMAP-PRODUCT',
+    roadmap_id: roadmapId = resolveDefaultRoadmap(vaultRoot).id,
     roadmap_phase: roadmapPhase = 'P0',
     skip_roadmap_registration: skipRoadmapRegistration = false,
     milestone,
@@ -1718,13 +1779,14 @@ _Space for reviewer comments._
   // Validate vault IDs
   let validateOk = null;
   let validateMessage = null;
-  const validateScript = join(vaultRoot, 'scripts', 'validate-vault-ids.mjs');
-  if (existsSync(validateScript)) {
+  const validateScript = resolveValidateVaultIdsScript(vaultRoot);
+  if (validateScript) {
     try {
       execFileSync(process.execPath, [validateScript], {
-        cwd: vaultRoot,
+        cwd: dirname(validateScript),
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, HEYSPEX_VALIDATE_ROOT: vaultRoot },
       });
       validateOk = true;
     } catch (e) {
@@ -1733,7 +1795,7 @@ _Space for reviewer comments._
     }
   } else {
     validateOk = null;
-    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not in vault root)';
+    validateMessage = 'skipped (scripts/validate-vault-ids.mjs not found in the code root or vault root)';
   }
 
   return {
@@ -1824,3 +1886,827 @@ export function buildShipWorkflowMarkdown(options = {}) {
 
   return lines.join('\n');
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLOUD WRITE MODE — `resolveVaultWriteMode() === 'cloud'`
+// [[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]
+//
+// In cloud reliance the vault is NOT on this machine's disk: a `writeFileSync`
+// here is a split brain — a markdown file the console's index has never heard
+// of, possibly on a machine with no clone of the vault at all. So every write
+// `push_plan` / `backfill_epic` makes goes through the console instead
+// (`POST /api/specs`, via cloud-vault-writes.mjs), and every id/file-key mint
+// that used to SCAN THE VAULT ON DISK is skipped — the console mints the id,
+// the family and the filename server-side.
+//
+// The structural consequence is CREATE-FIRST / LINK-SECOND. On disk the epic
+// basename was computable before any write, so children could be named in the
+// epic's own frontmatter. In cloud mode the basename only exists once
+// `POST /api/specs` has answered, so the order is: create the epic -> read back
+// its basename -> create each task with `parent: "[[<epic basename>]]"` ->
+// create the review doc, which cites both. Nothing is hand-linked in the
+// reverse direction: `createSpec` back-links `children:` (task->epic) and
+// `epics:` (epic->milestone) itself at create time (KIND_LINKAGE in
+// spex-console's vault.ts), which is exactly what `appendEpicToMilestone` did
+// on disk.
+//
+// There is NO rollback (the console has no un-create), so each entry point
+// stops at the first failure and reports which step failed and which documents
+// already landed — never an implied clean abort.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The one document these tools write that has NO console route, described once
+ * so the degrade message and any report of it can never drift apart.
+ *
+ * The console's create route accepts only the types in its `TYPE_TO_FOLDER`
+ * map (task, epic, milestone, diagnose, capture, planning-flow, memory-*,
+ * protocol, workflow-recipe, research, review, pillar, agent, golden-case,
+ * adr, draft, daily). A roadmap manifest is none of those, and its update is
+ * not a spec create at all: `addEpicToRoadmapPhase` scans `specs/roadmaps/`
+ * for the file whose frontmatter carries `id: <roadmapId>` and then performs
+ * line-surgical YAML editing inside a `roadmap_manifest` phase block. Borrowing
+ * some other `type` would mint a NEW document in the wrong folder rather than
+ * amend the existing manifest, so in cloud mode the write is skipped and said
+ * out loud.
+ */
+const CLOUD_UNSUPPORTED_ROADMAP_WRITE = Object.freeze({
+  error: 'CLOUD_MODE_UNSUPPORTED_WRITE',
+  document: 'specs/roadmaps/<manifest>.md',
+  write: 'addEpicToRoadmapPhase — append the epic basename to a roadmap_manifest phase',
+  why:
+    'There is no console route for a roadmap manifest: POST /api/specs only accepts the types in TYPE_TO_FOLDER '
+    + '(roadmap is not one of them), and this is an in-place edit of an existing YAML phase block, not a spec create. '
+    + 'Writing it to local disk in cloud mode would be a split brain, and minting it under a borrowed type would '
+    + 'create a new document instead of amending the manifest.',
+});
+
+/**
+ * Resolve the console transport + URL for a cloud-mode run.
+ *
+ * Both are DEPENDENCIES with real defaults: a test injects a recorder and never
+ * opens a socket, while production gets `consoleFetch` from
+ * ./console-transport.mjs and `getConsoleUrl()` from ./mcp-config.mjs. The
+ * imports are dynamic so a local-mode run never loads the transport at all and
+ * the pre-existing local tests keep exactly the module graph they had.
+ */
+async function resolveCloudDeps(options = {}) {
+  let consoleFetch = options.consoleFetch;
+  if (typeof consoleFetch !== 'function') {
+    ({ consoleFetch } = await import('./console-transport.mjs'));
+  }
+  let consoleUrl = options.consoleUrl ?? null;
+  if (!consoleUrl) {
+    try {
+      const { getConsoleUrl } = await import('./mcp-config.mjs');
+      consoleUrl = getConsoleUrl();
+    } catch {
+      consoleUrl = null;
+    }
+  }
+  return { consoleFetch, consoleUrl, actingAgent: options.actingAgent ?? null };
+}
+
+/** `resolveVaultWriteMode()` with the same injectable seam the handlers use. */
+async function resolveWriteModeForPlanPush(options = {}) {
+  if (options.vaultWriteMode === 'local' || options.vaultWriteMode === 'cloud') {
+    return options.vaultWriteMode;
+  }
+  if (typeof options.resolveVaultWriteMode === 'function') {
+    return (await options.resolveVaultWriteMode()) ?? 'local';
+  }
+  const { resolveVaultWriteMode } = await import('./read-path.mjs');
+  return (await resolveVaultWriteMode()) ?? 'local';
+}
+
+/**
+ * `heyspex_push_plan` HANDLER ENTRY: resolve the write mode ONCE, then run.
+ * `deps` is the same object threaded down to {@link executePushPlan} — pass
+ * `{ consoleFetch }` in tests, nothing in production.
+ */
+export async function executePushPlanCloudAware(vaultRoot, args, deps = {}) {
+  const vaultWriteMode = await resolveWriteModeForPlanPush(deps);
+  return executePushPlan(vaultRoot, args, { ...deps, vaultWriteMode });
+}
+
+/** `heyspex_backfill_epic` HANDLER ENTRY — see {@link executePushPlanCloudAware}. */
+export async function executeShipEpicCloudAware(vaultRoot, args, deps = {}) {
+  const vaultWriteMode = await resolveWriteModeForPlanPush(deps);
+  return executeShipEpic(vaultRoot, args, { ...deps, vaultWriteMode });
+}
+
+/**
+ * `GET /api/specs/:id` — the cloud twin of reading a vault file off disk. The
+ * route resolves an `id` OR a wikilink basename, which is exactly the two
+ * shapes the disk readers here resolve. Returns `null` for a genuine 404 (the
+ * spec is not in this caller's vault — the same "skip it" answer
+ * `resolveWikilink` gives); every other failure throws the canonical
+ * `CONSOLE_UNREACHABLE_CLOUD_MODE` error.
+ */
+async function readSpecViaConsole({ consoleFetch, consoleUrl, ref }) {
+  const routeLabel = `GET /api/specs/${ref}`;
+  if (typeof consoleFetch !== 'function') {
+    throw cloudWriteFailure(routeLabel, consoleUrl, 'no consoleFetch dependency was injected');
+  }
+  let result;
+  try {
+    result = await consoleFetch(`/api/specs/${encodeURIComponent(ref)}`);
+  } catch (err) {
+    throw cloudWriteFailure(routeLabel, consoleUrl, String(err?.message ?? err));
+  }
+  if (result?.status === 404) return null;
+  if (!result?.ok) {
+    throw cloudWriteFailure(
+      routeLabel,
+      result?.url ?? consoleUrl,
+      `${result?.status ?? '?'}${result?.error ? ` ${result.error}` : ''}`,
+      { status: result?.status ?? null, console_response: result?.body ?? null },
+    );
+  }
+  return result.body?.spec ?? null;
+}
+
+/**
+ * Cloud twin of {@link resolveMilestoneArg}. The shape checks (missing /
+ * not-an-HS-MIL) are pure and stay identical; only the EXISTENCE check moves
+ * from `existsSync(specs/milestones/<b>.md)` to the console. Also returns the
+ * milestone's `pillar:` so the epic can inherit it (the disk path reads the
+ * same field via {@link resolveMilestonePillar}).
+ *
+ * `family:` is deliberately NOT returned: in cloud mode `createSpec` inherits
+ * the family from the resolved structural parent itself, so minting or echoing
+ * one here would only give the server a chance to disagree with itself.
+ */
+async function resolveMilestoneArgViaConsole(raw, { consoleFetch, consoleUrl }) {
+  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 spec = await readSpecViaConsole({ consoleFetch, consoleUrl, ref: basename });
+  if (!spec) {
+    return {
+      error: 'MILESTONE_NOT_FOUND',
+      message: `milestone does not exist in the console vault: ${basename} (cloud write mode — checked via GET /api/specs/${basename}, not local disk)`,
+    };
+  }
+  const resolvedBasename =
+    typeof spec.basename === 'string' && spec.basename ? spec.basename : basename;
+  return {
+    basename: resolvedBasename,
+    wikilink: `[[${resolvedBasename}]]`,
+    pillar: normalizePillarRef(spec.frontmatter?.pillar),
+  };
+}
+
+/**
+ * Cloud twin of {@link detectSpecConflicts}. Same claim extraction and the same
+ * comparison — only the per-link body read moves from `resolveWikilink` +
+ * `readFileSync` to `GET /api/specs/:id`. A link the console cannot serve is
+ * SKIPPED and named in `unreachable`, mirroring the disk path's "skip files
+ * that can't be read" rather than failing a pre-flight advisory.
+ */
+async function detectSpecConflictsViaConsole(epicContent, relatedBasenames, deps) {
+  const epicClaims = extractBehavioralClaims(extractConflictCheckContent(epicContent), 'epic');
+  if (epicClaims.length === 0) {
+    return { conflicts: [], linked_specs_checked: [], unreachable: [] };
+  }
+  const conflicts = [];
+  const linkedSpecsChecked = [];
+  const unreachable = [];
+  for (const basename of relatedBasenames) {
+    let spec;
+    try {
+      spec = await readSpecViaConsole({ ...deps, ref: basename });
+    } catch (err) {
+      unreachable.push({ basename, message: String(err?.message ?? err) });
+      continue;
+    }
+    if (!spec) continue;
+    linkedSpecsChecked.push(basename);
+    conflicts.push(
+      ...findConflicts(epicClaims, extractBehavioralClaims(String(spec.body ?? ''), basename)),
+    );
+  }
+  return { conflicts, linked_specs_checked: linkedSpecsChecked, unreachable };
+}
+
+/** The `related:` wikilink array both cloud writers build (user links + defaults). */
+function normalizeRelatedWikilinks(related, defaults = []) {
+  const list = (Array.isArray(related) ? related : []).map(
+    (r) => `[[${String(r).replace(/^\[\[|\]\]$/g, '')}]]`,
+  );
+  return [...new Set([...list, ...defaults])];
+}
+
+/** The `landed` block every cloud result carries — the twin of research-handlers'. */
+function cloudLandedBlock({ consoleUrl, relPath, consoleWrite = null, vaultRoot = null }) {
+  return {
+    tier: 'cloud',
+    reported_by: consoleWrite ? 'console' : 'inferred_from_console_url',
+    console_url: consoleUrl ?? null,
+    rel_path: relPath ?? null,
+    abs_path: null,
+    on_disk: false,
+    in_local_vault: false,
+    vault_root: vaultRoot ?? null,
+    console_write: consoleWrite,
+  };
+}
+
+/**
+ * The one failure envelope both cloud entry points return. Names the step that
+ * failed AND everything that already landed — there is no rollback, so a caller
+ * must be able to say what state the vault is actually in.
+ */
+function cloudWriteFailureResult(err, { step, landed = [], extra = {} }) {
+  return {
+    error: 'CONSOLE_UNREACHABLE_CLOUD_MODE',
+    success: false,
+    write_mode: 'cloud',
+    failed_step: step,
+    message: String(err?.message ?? err),
+    console_url: err?.console_url ?? null,
+    ...(err?.status != null ? { status: err.status } : {}),
+    ...(err?.console_response ? { console_response: err.console_response } : {}),
+    ...(err?.hint ? { hint: err.hint } : {}),
+    already_landed: landed,
+    rollback:
+      'none — the console has no un-create; the documents in `already_landed` are real and must not be re-created on a retry',
+    ...extra,
+  };
+}
+
+/** In cloud mode the vault is not on this machine, so the id validator cannot run. */
+const CLOUD_VALIDATE_SKIPPED =
+  'skipped (cloud write mode — scripts/validate-vault-ids.mjs scans the vault on disk and this machine may hold no clone; the console validates ids server-side at create time)';
+
+/**
+ * `push_plan` in cloud write mode. Mirrors {@link executePushPlan}'s result
+ * shape so callers read ONE shape in both modes, minus everything that only
+ * exists on disk (the `file_id`/`family` mints, the milestone mirror-update,
+ * the id-validator subprocess).
+ */
+async function pushPlanViaConsole(vaultRoot, args, options = {}) {
+  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,
+    // Cloud-only: POST /api/specs HARD-REQUIRES `pillar:` on an epic (route.ts
+    // `pillar_required`), which the disk path never emitted because nothing on
+    // disk enforced it. Honoured only here, so the local branch stays
+    // byte-identical.
+    pillar,
+  } = 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 { consoleFetch, consoleUrl, actingAgent } = await resolveCloudDeps(options);
+
+  let milestoneResolved;
+  try {
+    milestoneResolved = await resolveMilestoneArgViaConsole(milestone, {
+      consoleFetch,
+      consoleUrl,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, { step: 'resolve_milestone' });
+  }
+  if (milestoneResolved.error) return milestoneResolved;
+
+  const resolvedPillar = normalizePillarRef(pillar) ?? milestoneResolved.pillar ?? 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. ` +
+        'Cloud write mode files the epic through POST /api/specs, which hard-blocks an epic with no resolvable `pillar:`. ' +
+        '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]]).',
+    };
+  }
+
+  // Reads LOCAL plan source files (Cursor `*.plan.md` etc.) into the epic body.
+  // Those are this machine's own files, not vault content, and this makes no
+  // vault write — so it is unchanged in cloud mode.
+  const prepared = prepareVaultPlanContent(vaultRoot, {
+    plan_markdown: planMarkdown,
+    implementation_prompt: implementationPrompt,
+    source_plan_paths: sourcePlanPaths,
+  });
+
+  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}`;
+    if (preparedPrompt?.trim()) {
+      epicBody += buildNextStepSection(preparedPrompt);
+    }
+  }
+
+  const userRelatedLinks = Array.isArray(related) ? related : [];
+  const uniqueRelated = normalizeRelatedWikilinks(userRelatedLinks, [
+    '[[plan-ingest-agent-workflow]]',
+    '[[vault-id-assignment-protocol]]',
+  ]);
+
+  // Pre-flight conflict detection, BEFORE anything is created — same blocking
+  // contract as the disk path (an on_deck push with conflicts writes nothing).
+  let preflightConflicts = [];
+  let preflightLinkedSpecs = [];
+  let preflightUnreachable = [];
+  if (!skipConflictCheck && userRelatedLinks.length > 0) {
+    const fullEpicContent = [epicBody, preparedPrompt || ''].join('\n');
+    const relatedBasenames = userRelatedLinks.map((r) => String(r).replace(/^\[\[|\]\]$/g, ''));
+    const conflictResult = await detectSpecConflictsViaConsole(fullEpicContent, relatedBasenames, {
+      consoleFetch,
+      consoleUrl,
+    });
+    preflightConflicts = conflictResult.conflicts;
+    preflightLinkedSpecs = conflictResult.linked_specs_checked;
+    preflightUnreachable = conflictResult.unreachable;
+
+    if (onDeck && preflightConflicts.length > 0) {
+      return {
+        error: 'CONFLICTS_DETECTED',
+        success: false,
+        on_deck: true,
+        blocked: true,
+        write_mode: 'cloud',
+        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).',
+        ],
+      };
+    }
+  }
+
+  // No `id`/`file_id`/`family`/`created`/`updated`: every one of those is
+  // server-minted (cloud-vault-writes.mjs SERVER_MINTED_FIELDS), and `family`
+  // is inherited from the milestone by `createSpec` itself.
+  const epicFrontmatter = {
+    kind,
+    effort,
+    requires_user_testing: false,
+    status: onDeck ? 'in_progress' : 'open',
+    milestone: milestoneResolved.wikilink,
+    pillar: `[[${resolvedPillar}]]`,
+    tags: tags.length > 0 ? [...tags] : ['epic'],
+    // Left empty ON PURPOSE — push_plan never files children, and the console
+    // back-links any later task into this array at THAT task's create time.
+    children: [],
+    related: uniqueRelated,
+  };
+  const epicMarkdown = `${epicBody}
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_push_plan) | Epic created via hs-push${onDeck ? '-next' : ''}. |
+`;
+
+  let createdEpic;
+  try {
+    createdEpic = await createSpecViaConsole({
+      consoleFetch,
+      consoleUrl,
+      type: 'epic',
+      name: epicName,
+      summary: epicSummary,
+      frontmatter: epicFrontmatter,
+      body: epicMarkdown,
+      actingAgent,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, { step: 'create_epic' });
+  }
+
+  const computedFocusReason = onDeck ? focusReason || `On deck: ${epicName} (hs-push-next)` : null;
+  const designDecisions = getApplicableDesignDecisions(
+    [epicBody, preparedPrompt || ''].join('\n'),
+  );
+
+  const result = {
+    success: true,
+    write_mode: 'cloud',
+    on_deck: onDeck,
+    epic: {
+      id: createdEpic.specId,
+      basename: createdEpic.basename,
+      spec_path: createdEpic.relPath,
+    },
+    children: [],
+    landed: cloudLandedBlock({
+      consoleUrl: createdEpic.consoleUrl ?? consoleUrl,
+      relPath: createdEpic.relPath,
+      consoleWrite: createdEpic.consoleWrite,
+      vaultRoot,
+    }),
+    // The console back-links `epics:` on the milestone at create time
+    // (KIND_LINKAGE.epic.parentArray), which is what appendEpicToMilestone did
+    // on disk — so this tool does NOT hand-write the parent array in cloud mode.
+    milestone_backlink: {
+      milestone: milestoneResolved.basename,
+      by: 'console (createSpec KIND_LINKAGE.epic.parentArray = "epics")',
+    },
+    focus_written: onDeck ? null : false,
+    focus_reason: computedFocusReason,
+    validate_vault_ids: null,
+    validate_message: CLOUD_VALIDATE_SKIPPED,
+    conflicts: preflightConflicts,
+    linked_specs_checked: preflightLinkedSpecs,
+    has_conflicts: preflightConflicts.length > 0,
+    design_decisions: designDecisions,
+    has_design_decisions: designDecisions.length > 0,
+    plans_ingested: prepared.plans_ingested,
+    ingested_plans: prepared.ingested_plans,
+    missing_plans: prepared.missing_plans,
+    ...(Array.isArray(createdEpic.warnings) && createdEpic.warnings.length > 0
+      ? { console_warnings: createdEpic.warnings }
+      : {}),
+    ...(preflightUnreachable.length > 0
+      ? { conflict_check_unreachable: preflightUnreachable }
+      : {}),
+    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)',
+    ],
+  };
+
+  if (result.conflicts.length > 0) {
+    result.next_steps.unshift(
+      `⚠️ ${result.conflicts.length} spec conflict(s) detected — review before implementation`,
+    );
+  }
+  if (designDecisions.length > 0) {
+    result.next_steps.unshift(
+      `📐 ${designDecisions.length} design decision(s) apply — review before implementation`,
+    );
+  }
+  return result;
+}
+
+/**
+ * `backfill_epic` in cloud write mode — the CREATE-FIRST / LINK-SECOND flow.
+ *
+ * Order is load-bearing: the epic must exist before a task can name it as
+ * `parent:`, and the review doc must come last because it cites both the epic
+ * and every task by basename — and in cloud mode a basename is only knowable
+ * once the console has answered.
+ *
+ * The `children:` array is NOT hand-written: `createSpec` back-links each task
+ * into its epic at the task's own create time. The roadmap manifest has no
+ * console route at all and degrades explicitly (see
+ * {@link CLOUD_UNSUPPORTED_ROADMAP_WRITE}).
+ */
+async function shipEpicViaConsole(vaultRoot, args, options = {}) {
+  const {
+    epic_name: epicName,
+    summary = '',
+    plan_markdown: planMarkdown = '',
+    children = [],
+    files_changed: filesChanged = [],
+    kind = 'feature',
+    effort = 3,
+    tags = [],
+    related = [],
+    roadmap_id: roadmapId = resolveDefaultRoadmap(vaultRoot).id,
+    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 { consoleFetch, consoleUrl, actingAgent } = await resolveCloudDeps(options);
+
+  let milestoneResolved;
+  try {
+    milestoneResolved = await resolveMilestoneArgViaConsole(milestone, {
+      consoleFetch,
+      consoleUrl,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, { step: 'resolve_milestone' });
+  }
+  if (milestoneResolved.error) return milestoneResolved;
+
+  const resolvedPillar = normalizePillarRef(pillar) ?? milestoneResolved.pillar ?? 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]]).',
+    };
+  }
+
+  // Validate EVERY child before creating anything: a summary-less child must
+  // not surface after half the vault has already been written.
+  const plannedChildren = [];
+  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.`,
+      };
+    }
+    plannedChildren.push({ name: child.name, summary: childSummary });
+  }
+
+  const relatedWikilinks = normalizeRelatedWikilinks(related);
+  const epicBody = planMarkdown.trim() || `# ${epicName}\n\n${epicSummary}\n`;
+  const epicFrontmatter = {
+    kind,
+    effort,
+    requires_user_testing: false,
+    status: 'in_review',
+    milestone: milestoneResolved.wikilink,
+    pillar: `[[${resolvedPillar}]]`,
+    tags: tags.length > 0 ? [...tags] : ['epic'],
+    // Empty at create time BY CONSTRUCTION — the task basenames do not exist
+    // yet. Each task back-links itself into this array when the console creates
+    // it (KIND_LINKAGE.task.parentArray = "children").
+    children: [],
+    related: relatedWikilinks,
+  };
+
+  const landed = [];
+
+  // ── Step 1: the epic (create-first) ────────────────────────────────────────
+  let createdEpic;
+  try {
+    createdEpic = await createSpecViaConsole({
+      consoleFetch,
+      consoleUrl,
+      type: 'epic',
+      name: epicName,
+      summary: epicSummary,
+      frontmatter: epicFrontmatter,
+      body: `${epicBody}
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_backfill_epic) | Epic created retroactively, backfilled to review. |
+`,
+      actingAgent,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, { step: 'create_epic', landed });
+  }
+  const epicBasename = createdEpic.basename;
+  landed.push({
+    step: 'create_epic',
+    type: 'epic',
+    id: createdEpic.specId,
+    basename: epicBasename,
+    rel_path: createdEpic.relPath,
+  });
+
+  // ── Step 2: the child tasks (link-second — the parent is now knowable) ─────
+  const childSpecs = [];
+  const childWikilinks = [];
+  for (const child of plannedChildren) {
+    let createdTask;
+    try {
+      createdTask = await createSpecViaConsole({
+        consoleFetch,
+        consoleUrl,
+        type: 'task',
+        name: child.name,
+        summary: child.summary,
+        frontmatter: {
+          kind,
+          effort,
+          requires_user_testing: false,
+          status: 'in_review',
+          tags: ['shipped'],
+          parent: `[[${epicBasename}]]`,
+        },
+        body: `# ${child.name}
+
+_Completed as part of [[${epicBasename}]]._
+
+## Change log
+
+| Date | Author | Change |
+|------|--------|--------|
+| ${todayDate()} | pwher (with agent via heyspex_backfill_epic) | Task backfilled to review as part of [[${epicBasename}]]. |
+`,
+        actingAgent,
+      });
+    } catch (err) {
+      return cloudWriteFailureResult(err, {
+        step: 'create_task',
+        landed,
+        extra: { failed_task: child.name },
+      });
+    }
+    landed.push({
+      step: 'create_task',
+      type: 'task',
+      id: createdTask.specId,
+      basename: createdTask.basename,
+      rel_path: createdTask.relPath,
+    });
+    childWikilinks.push(`[[${createdTask.basename}]]`);
+    childSpecs.push({
+      id: createdTask.specId,
+      basename: createdTask.basename,
+      relPath: createdTask.relPath,
+      name: child.name,
+      summary: child.summary,
+    });
+  }
+
+  // ── Step 3: the review doc (cites the epic AND every task — so, last) ─────
+  const filesTable =
+    filesChanged.length > 0
+      ? filesChanged.map((f) => `| ${f} | Modified |`).join('\n')
+      : '| _No files listed_ | - |';
+  const reviewBody = `# 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._
+`;
+  let createdReview;
+  try {
+    createdReview = await createSpecViaConsole({
+      consoleFetch,
+      consoleUrl,
+      type: 'review',
+      name: `Review: ${epicName}`,
+      summary: epicSummary,
+      frontmatter: {
+        // `parent:` is REQUIRED for a review by the console's linkage rules
+        // (KIND_LINKAGE.review.parentRequired); `for:` preserves the field the
+        // on-disk `<epic>.review.md` carried so existing readers still resolve.
+        parent: `[[${epicBasename}]]`,
+        for: `[[${epicBasename}]]`,
+      },
+      body: reviewBody,
+      actingAgent,
+    });
+  } catch (err) {
+    return cloudWriteFailureResult(err, { step: 'create_review_doc', landed });
+  }
+  landed.push({
+    step: 'create_review_doc',
+    type: 'review',
+    id: createdReview.specId,
+    basename: createdReview.basename,
+    rel_path: createdReview.relPath,
+  });
+
+  // ── Step 4: the roadmap manifest — NO CLOUD PATH, degrade out loud ────────
+  const roadmapRegistration = skipRoadmapRegistration
+    ? { success: true, message: 'Skipped (skip_roadmap_registration: true)' }
+    : {
+        success: false,
+        ...CLOUD_UNSUPPORTED_ROADMAP_WRITE,
+        roadmap_id: roadmapId,
+        roadmap_phase: roadmapPhase,
+        epic_basename: epicBasename,
+        message:
+          `Roadmap registration was SKIPPED in cloud write mode: ${CLOUD_UNSUPPORTED_ROADMAP_WRITE.why} `
+          + 'Nothing was written to local disk and no substitute document was minted. '
+          + `To land it, add "${epicBasename}" to phase ${roadmapPhase} of ${roadmapId} by hand, or run this backfill in local write mode.`,
+      };
+
+  return {
+    success: true,
+    write_mode: 'cloud',
+    shipped_to_review: true,
+    epic: {
+      id: createdEpic.specId,
+      basename: epicBasename,
+      spec_path: createdEpic.relPath,
+    },
+    children: childSpecs,
+    review_doc: createdReview.relPath,
+    landed: cloudLandedBlock({
+      consoleUrl: createdEpic.consoleUrl ?? consoleUrl,
+      relPath: createdEpic.relPath,
+      consoleWrite: createdEpic.consoleWrite,
+      vaultRoot,
+    }),
+    console_writes: landed,
+    children_backlink: {
+      by: 'console (createSpec KIND_LINKAGE.task.parentArray = "children")',
+      note: 'each task back-links itself into the epic `children:` array at its own create time — this tool does not hand-write the array in cloud mode',
+    },
+    milestone_backlink: {
+      milestone: milestoneResolved.basename,
+      by: 'console (createSpec KIND_LINKAGE.epic.parentArray = "epics")',
+    },
+    roadmap_registration: roadmapRegistration,
+    ...(skipRoadmapRegistration
+      ? {}
+      : { cloud_mode_unsupported_writes: [CLOUD_UNSUPPORTED_ROADMAP_WRITE] }),
+    validate_vault_ids: null,
+    validate_message: CLOUD_VALIDATE_SKIPPED,
+    next_steps: [
+      roadmapRegistration.success
+        ? `Roadmap registration: ${roadmapRegistration.message}`
+        : `⚠️ Roadmap registration has NO cloud path — add "${epicBasename}" to ${roadmapPhase} of ${roadmapId} by hand, or the epic will not appear in the kanban Review column`,
+      '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)',
+    ],
+  };
+}
+
+/** Internals exposed for tests only. */
+export const __testables = {
+  CLOUD_UNSUPPORTED_ROADMAP_WRITE,
+  CLOUD_VALIDATE_SKIPPED,
+  detectSpecConflictsViaConsole,
+  normalizeRelatedWikilinks,
+  pushPlanViaConsole,
+  readSpecViaConsole,
+  resolveCloudDeps,
+  resolveMilestoneArgViaConsole,
+  resolveWriteModeForPlanPush,
+  shipEpicViaConsole,
+};