heyspex 0.1.0 → 0.2.1

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

@@ -42,7 +42,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join } from 'node:path';
+import { join, isAbsolute, resolve, sep } from 'node:path';
 import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
 import { yamlScalar } from './yaml-scalar.mjs';
 import {
@@ -72,7 +72,36 @@ import {
   bumpUpdated,
   appendChangeLogRow,
   commitWrites,
+  fetchSpecRecordViaConsole,
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+  cloudModeUnsupportedWrite,
 } from './promotion-helpers.mjs';
+// Cloud-mode vault WRITES ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+// See the block comment at the head of `runExecutePhase` for the create-first,
+// link-second reorder these three verbs make possible.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  listSpecsViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+// Cloud-tier read selector ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]) —
+// reused verbatim, never copied. See the module doc above `fetchSpecRecordViaConsole`
+// in promotion-helpers.mjs for why the neon branch goes through an injected
+// consoleFetch instead of read-path.mjs's own transport.
+import { readViaSelector } from './read-path.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// Placeholders the CLOUD path feeds the shared content builders in place of a
+// locally-minted id / file key / family key — stripped from the request by
+// `stripServerMintedFields` (plus an explicit `delete` of an un-inheritable
+// `family:`) before it ever reaches the console. Their only job is to keep the
+// builders' templates well-formed so the BODY stored in the cloud vault is the
+// same markdown the disk path writes.
+const CLOUD_PENDING_ID = 'HS-PENDING';
+const CLOUD_PENDING_KEY = 'PENDING';
 
 /** Milestone statuses that allow attaching spawned epics without an override. */
 export const MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES = ['open'];
@@ -177,6 +206,45 @@ function findResearchByIdLocal(vaultRoot, researchId) {
   }
 }
 
+/**
+ * Cloud-tier sibling of {@link findResearchByIdLocal} (HS-KR16). Same
+ * `{ record }` / error-shaped contract; the neon branch fetches the by-id
+ * spec route directly and re-derives the same `RESEARCH_NOT_FOUND` /
+ * `RESEARCH_TYPE_MISMATCH` shapes the disk branch's `resolveBreakdownSource`
+ * call produces, since that shared resolver stays disk-only and untouched.
+ * `tier`/`consoleUrl`/`consoleFetch` are resolved ONCE per handler call
+ * (`handlePromoteResearch` in research-handlers.mjs) and threaded down here.
+ */
+async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
+    neonRead: async () => {
+      const record = await fetchSpecRecordViaConsole(consoleFetch, researchId);
+      if (!record) {
+        return {
+          error: 'RESEARCH_NOT_FOUND',
+          message: `research ${researchId} not found under specs/research/ (tried exact basename, frontmatter id:, and id-prefix match)`,
+        };
+      }
+      const fm = getFrontmatterBlock(record.raw);
+      const type = fm ? getScalarField(fm.block, 'type') : null;
+      if (type && type !== 'research') {
+        return {
+          error: 'RESEARCH_TYPE_MISMATCH',
+          message: `research_id ${researchId} resolved to ${record.relPath ?? 'a file'}, which is \`type: ${type}\` — not a research doc`,
+          resolved_basename: record.basename,
+          resolved_type: type,
+        };
+      }
+      return { record };
+    },
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 function findMilestoneByBasename(vaultRoot, basename) {
   const absPath = join(vaultRoot, 'specs', 'milestones', `${basename}.md`);
   if (!existsSync(absPath)) return null;
@@ -201,6 +269,36 @@ function findMilestoneById(vaultRoot, milestoneId) {
   return null;
 }
 
+/**
+ * Cloud-tier sibling of {@link findMilestoneByBasename} (HS-KR16). Same
+ * bare-record-or-null contract as the disk loader.
+ */
+async function findMilestoneByBasenameViaTier(vaultRoot, basename, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findMilestoneByBasename(vaultRoot, basename),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, basename),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+/**
+ * Cloud-tier sibling of {@link findMilestoneById} (HS-KR16). Same
+ * bare-record-or-null contract as the disk loader.
+ */
+async function findMilestoneByIdViaTier(vaultRoot, milestoneId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findMilestoneById(vaultRoot, milestoneId),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, milestoneId),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 function findEpicByIdOrBasename(vaultRoot, idOrBasename) {
   const dir = join(vaultRoot, 'specs', 'epics');
   if (!existsSync(dir)) return null;
@@ -232,6 +330,22 @@ function findEpicByIdOrBasename(vaultRoot, idOrBasename) {
   return null;
 }
 
+/**
+ * Cloud-tier sibling of {@link findEpicByIdOrBasename} (HS-KR16) — the
+ * console's by-id route accepts either an id or a basename, matching the
+ * disk loader's own two-shape contract. Same bare-record-or-null return.
+ */
+async function findEpicByIdOrBasenameViaTier(vaultRoot, idOrBasename, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => findEpicByIdOrBasename(vaultRoot, idOrBasename),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, idOrBasename),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Pillar resolution (epic→pillar hard requirement, [[pillar-assignment-protocol]])
 // ─────────────────────────────────────────────────────────────────────────────
@@ -295,6 +409,51 @@ export function resolvePillar(vaultRoot, raw) {
   return { ok: true, basename, frontmatterValue: `'[[${basename}]]'` };
 }
 
+/**
+ * Cloud sibling of {@link listVaultPillars} ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]] AC3).
+ *
+ * The disk version is a `readdirSync(specs/pillars)` scan, which in a file-less
+ * vault returns `[]` — so a `pillar_required` refusal would list NO valid
+ * options and read as "there are no pillars" rather than "this machine holds
+ * no copy of them". `GET /api/specs?type=pillar` (`listSpecsViaConsole`, which
+ * follows the keyset cursor) is the route that answers the same question in
+ * cloud mode. Fails SOFT to `[]`, exactly like the disk version: this list only
+ * enriches an error message that is being returned either way, and turning a
+ * refusal into an unreachable-console error would hide the real cause.
+ */
+export async function listVaultPillarsViaWriteMode(vaultRoot, { writeMode, consoleFetch, consoleUrl }) {
+  if (writeMode !== 'cloud') return listVaultPillars(vaultRoot);
+  try {
+    const rows = await listSpecsViaConsole({ consoleFetch, consoleUrl, type: 'pillar' });
+    return rows.map((row) => ({
+      id: row.basename ?? row.id ?? null,
+      name: row.name ?? row.basename ?? row.id ?? null,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Cloud-tier sibling of {@link resolvePillar} (HS-KR16).
+ */
+async function resolvePillarViaTier(vaultRoot, raw, { tier, consoleUrl, consoleFetch }) {
+  const basename = normalizePillarRef(raw);
+  if (!basename) return { ok: false };
+  return readViaSelector({
+    allowDiskFallback: false,
+    tier,
+    diskRead: () => resolvePillar(vaultRoot, raw),
+    neonRead: async () => {
+      const record = await fetchSpecRecordViaConsole(consoleFetch, basename);
+      if (!record) return { ok: false };
+      return { ok: true, basename, frontmatterValue: `'[[${basename}]]'` };
+    },
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AI proposer wiring
 // ─────────────────────────────────────────────────────────────────────────────
@@ -495,21 +654,32 @@ function validateResearchState(research) {
   // validateBidirectionalEnhances (RESEARCH_ALREADY_PROMOTED).
   const status = getScalarField(fm.block, 'status');
   const enhances = getScalarField(fm.block, 'enhances');
-  return { fm, status, enhances };
+  // [[HS-8XJA-KOGH-DIAG-passing-enhances-to-heyspex-promote]]: `enhances` is
+  // ALSO a heyspex_promote_capture argument that writes this same field one
+  // stage earlier, before any epic has actually been spawned — forging the
+  // "already promoted" signal ahead of the event it's supposed to record. A
+  // GENUINE promote-research execution always writes `spawned_epics` and/or
+  // `enhances_epics` in the SAME commit as `enhances` (buildUpdatedResearchContent
+  // below) — so `enhances` set with BOTH of those empty can only mean it was
+  // pre-set at capture-promote time, never backed by a real promotion.
+  const spawnedEpics = parseListFieldBasenames(fm.block, 'spawned_epics') ?? [];
+  const enhancesEpics = parseListFieldBasenames(fm.block, 'enhances_epics') ?? [];
+  const enhancesBacked = spawnedEpics.length > 0 || enhancesEpics.length > 0;
+  return { fm, status, enhances, enhancesBacked };
 }
 
-function resolveTargetMilestone(vaultRoot, args, occupiedMilestoneIds) {
+async function resolveTargetMilestone(vaultRoot, args, { tier, consoleUrl, consoleFetch }) {
   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);
+    const ms = await findMilestoneByBasenameViaTier(vaultRoot, basenameCandidate, { tier, consoleUrl, consoleFetch });
     if (ms) return { mode: 'existing', milestone: ms };
   }
   if (parseSpecId(args.target_milestone)?.typeLabel === 'MIL') {
-    const ms = findMilestoneById(vaultRoot, args.target_milestone);
+    const ms = await findMilestoneByIdViaTier(vaultRoot, args.target_milestone, { tier, consoleUrl, consoleFetch });
     if (ms) return { mode: 'existing', milestone: ms };
   }
   return {
@@ -652,6 +822,7 @@ async function runProposalPhase(args, ctx, deps) {
 /** 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
@@ -672,6 +843,7 @@ function normalizeStubName(name) {
 export function writeStubReviewMarker(vaultRoot, researchId, proposal = {}) {
   try {
     const file = stubReviewMarkerPath(vaultRoot, researchId);
+    assertPathUnderRoot(vaultRoot, join(file, '..'), 'promote-research write');
     mkdirSync(join(file, '..'), { recursive: true });
     writeFileSync(
       file,
@@ -815,6 +987,62 @@ function resolveOwnerIntent(vaultRoot, researchRaw) {
   }
 }
 
+/**
+ * Cloud-tier sibling of {@link resolveOwnerIntent} (HS-KR16) — same
+ * best-effort, never-throws contract (a missing/unreachable source capture
+ * just means no owner-intent enrichment, not a hard failure). Only the
+ * per-basename capture read moves through the tier selector; the
+ * sources_captures/related parsing stays identical to the disk version.
+ */
+async function resolveOwnerIntentViaTier(vaultRoot, researchRaw, { tier, consoleUrl, consoleFetch }) {
+  try {
+    const fm = getFrontmatterBlock(researchRaw);
+    if (!fm) return null;
+    let basenames = parseListFieldBasenames(fm.block, 'sources_captures') ?? [];
+    if (basenames.length === 0) {
+      basenames = (parseListFieldBasenames(fm.block, 'related') ?? []).filter((b) =>
+        /(^|-)CAP(-|$)/i.test(b),
+      );
+    }
+    if (basenames.length === 0) return null;
+    for (const basename of basenames) {
+      let raw;
+      try {
+        raw = await readViaSelector({
+    allowDiskFallback: false,
+          tier,
+          diskRead: () => {
+            const capturesDir = join(vaultRoot, 'specs', 'captures');
+            let abs = join(capturesDir, `${basename}.md`);
+            if (!existsSync(abs)) {
+              const byPrefix = findFileByPrefix(capturesDir, basename);
+              if (!byPrefix) return null;
+              abs = join(capturesDir, byPrefix);
+            }
+            return readFileSync(abs, 'utf8');
+          },
+          neonRead: async () => {
+            const record = await fetchSpecRecordViaConsole(consoleFetch, basename);
+            return record ? record.raw : null;
+          },
+          routeLabel: 'GET /api/specs/[id]',
+          consoleUrl,
+        });
+      } catch {
+        continue; // a genuine console failure here is soft — skip, try the next basename.
+      }
+      if (!raw) continue;
+      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
@@ -1018,6 +1246,38 @@ async function runExecutePhase(args, ctx, deps) {
   const now = (deps?.clock ?? isoNow)();
   const today = now.slice(0, 10);
   const author = 'promote-research (agent)';
+  // Same already-resolved tier this call's executePromoteResearch entry point
+  // read from deps.tier ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]])
+  // — read again here, never re-resolved via resolveReadTier().
+  const tierDeps = { tier: deps?.tier ?? 'disk', consoleUrl: deps?.consoleUrl, consoleFetch: deps?.consoleFetch };
+  // ── Vault WRITE mode ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]) ──
+  //
+  // Resolved ONCE by the caller (`resolveVaultWriteMode()`) and threaded in on
+  // `deps`; absent — every pre-existing caller and test — it is `local`, so the
+  // disk plan-then-`commitWrites` path below is byte-identical to before.
+  //
+  // CREATE FIRST, LINK SECOND. On disk this flow mints every filename itself,
+  // so it can stage all four write groups and commit them as one transaction.
+  // In cloud mode the console mints the id, the family and the filename, and
+  // the dependencies run strictly one way:
+  //
+  //   milestone  ← links to: research basename            (known up front)
+  //   epic       ← links to: MILESTONE basename           (only after its POST)
+  //   epic       ← links to: SIBLING epic basenames       (only after their POSTs)
+  //   milestone  ← links to: EPIC basenames (`epics:`)    (only after their POSTs)
+  //   research   ← links to: MILESTONE + EPIC basenames   (only after their POSTs)
+  //
+  // so the cloud order is: POST milestone → POST every epic (with only the
+  // deps already resolvable) → PUT epics that depend on a sibling → PUT the
+  // milestone's `epics:` mirror → PUT the research doc. Every wikilink written
+  // in a PUT body therefore names a basename a POST actually returned.
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  const cloudCompleted = [];
+  const recordCloud = (entry) => {
+    cloudCompleted.push(entry);
+    return entry;
+  };
 
   // Family inheritance ([[HS-GZM9-DIAG-G419]], mirrors promote-capture.mjs /
   // split-research.mjs): the spawned milestone AND every spawned epic inherit
@@ -1041,23 +1301,39 @@ async function runExecutePhase(args, ctx, deps) {
   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`);
+    if (writeMode === 'cloud') {
+      // NOTHING is minted locally in cloud mode (AC3): `allocateFileKey`,
+      // `collectOccupiedKeysEitherKind` and `allocateMilestoneId` all derive
+      // their answer from a vault SCAN, and in a file-less vault that scan is
+      // empty — a key drawn against an empty occupied set can collide with one
+      // the cloud vault already holds. `createSpec` mints the file key, the
+      // family and the filename server-side. An INHERITED family is still
+      // passed through: it is read off the source research doc, not minted.
+      milestoneFileKey = null;
+      milestoneFamilyKey = inheritedFamilyKey ?? null;
+      milestoneId = null;
+      milestoneBasename = null;
+      milestoneAbsPath = null;
+      milestoneRelPath = null;
+    } else {
+      // 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;
@@ -1076,7 +1352,7 @@ async function runExecutePhase(args, ctx, deps) {
   const augmentEpics = [];
   if (args.intent === 'augment' || args.intent === 'both') {
     for (const epicRef of args.augment_epic_ids) {
-      const found = findEpicByIdOrBasename(ctx.vaultRoot, epicRef);
+      const found = await findEpicByIdOrBasenameViaTier(ctx.vaultRoot, epicRef, tierDeps);
       if (!found) {
         return {
           error: 'AUGMENT_EPIC_NOT_FOUND',
@@ -1106,10 +1382,14 @@ async function runExecutePhase(args, ctx, deps) {
 
   const spawnedEpicSpecs = [];
   if (acceptedStubs.length > 0) {
-    const { epics: occupiedEpics } = collectOccupiedVaultIds(ctx.vaultRoot);
+    // Both occupied sets are DISK SCANS — skipped entirely in cloud mode,
+    // where no key is minted client-side (AC3).
+    const { epics: occupiedEpics } =
+      writeMode === 'cloud' ? { epics: new Set() } : 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)
+    const occupiedFileKeys =
+      writeMode === 'cloud' ? new Set() : collectOccupiedKeysEitherKind(ctx.vaultRoot); // union: file+family keys (HS-SJOT)
     for (const stub of acceptedStubs) {
       if (!stub?.name?.trim()) {
         return {
@@ -1117,23 +1397,32 @@ async function runExecutePhase(args, ctx, deps) {
           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 fileKey = null;
       let epicFamilyKey = inheritedFamilyKey;
-      if (!epicFamilyKey) {
-        const allocatedEpicFamilyId = allocateRandomVaultId('epic', occupiedEpics, {
-          randomUnit: deps?.randomUnit,
-        });
-        occupiedEpics.add(allocatedEpicFamilyId);
-        epicFamilyKey = parseSpecId(allocatedEpicFamilyId)?.familyKey ?? fileKey;
+      let epicId = null;
+      let basename = null;
+      if (writeMode === 'cloud') {
+        // Basename/id stay null until this stub's own POST answers; the
+        // inherited family (read off the research doc, never minted) is the
+        // only naming input that survives into the request.
+        epicFamilyKey = inheritedFamilyKey ?? null;
+      } else {
+        // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
+        // and (V3) the anchor for `id:` itself.
+        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.
+        if (!epicFamilyKey) {
+          const allocatedEpicFamilyId = allocateRandomVaultId('epic', occupiedEpics, {
+            randomUnit: deps?.randomUnit,
+          });
+          occupiedEpics.add(allocatedEpicFamilyId);
+          epicFamilyKey = parseSpecId(allocatedEpicFamilyId)?.familyKey ?? fileKey;
+        }
+        epicId = `HS-${fileKey}`;
+        basename = `${epicId}-${epicFamilyKey}-EPIC-${deriveSlug(stub.name)}`;
       }
-      const epicId = `HS-${fileKey}`;
-      const slug = deriveSlug(stub.name);
-      const basename = `${epicId}-${epicFamilyKey}-EPIC-${slug}`;
       spawnedEpicSpecs.push({
         id: epicId,
         fileKey,
@@ -1147,8 +1436,8 @@ async function runExecutePhase(args, ctx, deps) {
         // 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`),
+        relPath: basename ? join('specs', 'epics', `${basename}.md`) : null,
+        absPath: basename ? join(ctx.vaultRoot, 'specs', 'epics', `${basename}.md`) : null,
       });
     }
   }
@@ -1161,20 +1450,32 @@ async function runExecutePhase(args, ctx, deps) {
   //    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.
+  //
+  //    In CLOUD mode a sibling's basename does not exist yet either (the
+  //    console mints it at POST time), so the sibling half of this resolution
+  //    is DEFERRED: the entry is parked on `spec.pendingSiblingDeps` and folded
+  //    in by a follow-up PUT once every sibling POST has answered. The
+  //    externally-resolved half is identical in both modes.
   const depWarnings = [];
   if (spawnedEpicSpecs.length > 0) {
+    const siblingNames = new Set(spawnedEpicSpecs.map((s) => s.name.trim().toLowerCase()));
     const siblingNameToBasename = new Map();
     for (const s of spawnedEpicSpecs) {
       siblingNameToBasename.set(s.name.trim().toLowerCase(), s.basename);
     }
     for (const spec of spawnedEpicSpecs) {
       const resolved = [];
+      const pendingSiblings = [];
       for (const raw of spec.depends_on) {
         const d = typeof raw === 'string' ? raw.trim() : '';
         if (!d) continue;
+        if (writeMode === 'cloud' && siblingNames.has(d.toLowerCase())) {
+          pendingSiblings.push(d.toLowerCase());
+          continue;
+        }
         let target = siblingNameToBasename.get(d.toLowerCase());
         if (!target) {
-          const found = findEpicByIdOrBasename(ctx.vaultRoot, d);
+          const found = await findEpicByIdOrBasenameViaTier(ctx.vaultRoot, d, tierDeps);
           if (found) target = found.basename;
         }
         if (target) {
@@ -1184,6 +1485,7 @@ async function runExecutePhase(args, ctx, deps) {
         }
       }
       spec.depends_on = resolved;
+      spec.pendingSiblingDeps = pendingSiblings;
     }
   }
 
@@ -1195,14 +1497,19 @@ async function runExecutePhase(args, ctx, deps) {
   if (spawnedEpicSpecs.length > 0) {
     for (const spec of spawnedEpicSpecs) {
       const pillarRef = spec.pillar ?? args.pillar;
-      const resolved = resolvePillar(ctx.vaultRoot, pillarRef);
+      const resolved = await resolvePillarViaTier(ctx.vaultRoot, pillarRef, tierDeps);
       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),
+          // AC3: in cloud mode this list comes from `GET /api/specs?type=pillar`,
+          // not from a `readdirSync(specs/pillars)` that would be empty here.
+          existing_pillars: await listVaultPillarsViaWriteMode(ctx.vaultRoot, {
+            writeMode,
+            ...cloudDeps,
+          }),
           create_pillar: {
             tool: 'heyspex_file_spec',
             call: { type: 'pillar', name: '<theme name>' },
@@ -1220,11 +1527,295 @@ async function runExecutePhase(args, ctx, deps) {
   // 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);
+  const ownerIntent = await resolveOwnerIntentViaTier(ctx.vaultRoot, ctx.research.raw, tierDeps);
   // HS-M1MW: seed spawned stubs' JTBD sections from the research doc's own
   // JTBD section, when present.
   const researchJtbd = extractResearchJtbd(ctx.research.raw);
 
+  // ── CLOUD PATH ────────────────────────────────────────────────────────────
+  // Returns early; everything below this block is the untouched disk
+  // plan-then-`commitWrites` path.
+  if (writeMode === 'cloud') {
+    /** Frontmatter/body the console actually stored, falling back to ours. */
+    const storedOf = (created, fallbackRaw) => {
+      const fallback = splitRawSpecForConsole(fallbackRaw);
+      return {
+        frontmatter: created?.spec?.frontmatter ?? fallback.frontmatter,
+        body: typeof created?.spec?.body === 'string' ? created.spec.body : fallback.body,
+      };
+    };
+
+    // ── 1. POST the milestone FIRST — every epic's `parent:`/`milestone:` and
+    //       the research's `enhances:` name the basename it returns.
+    let milestoneStored = null;
+    if (milestoneCreated) {
+      const newContent = buildMilestoneStubContent(
+        CLOUD_PENDING_ID,
+        CLOUD_PENDING_KEY,
+        milestoneFamilyKey ?? CLOUD_PENDING_KEY,
+        ctx.targetResolution.name,
+        ctx.research.basename,
+        now,
+        ownerIntent,
+        researchJtbd,
+      );
+      const { frontmatter, body } = splitRawSpecForConsole(newContent);
+      const cleaned = stripServerMintedFields(frontmatter);
+      if (!milestoneFamilyKey) delete cleaned.family;
+      let created;
+      try {
+        created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: 'milestone',
+          name: ctx.targetResolution.name,
+          frontmatter: cleaned,
+          body,
+          actingAgent: deps?.actingAgent ?? null,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'create', type: 'milestone', name: ctx.targetResolution.name },
+          completed: cloudCompleted,
+        });
+      }
+      milestoneId = created.specId;
+      milestoneBasename = created.basename;
+      milestoneRelPath = created.relPath;
+      milestoneStored = storedOf(created, newContent);
+      recordCloud({
+        kind: 'create',
+        type: 'milestone',
+        spec_id: created.specId,
+        basename: created.basename,
+        rel_path: created.relPath,
+      });
+    }
+
+    // ── 2. POST every epic, now that the milestone basename is real.
+    for (const spec of spawnedEpicSpecs) {
+      const content = buildEpicContent(
+        {
+          ...spec,
+          id: CLOUD_PENDING_ID,
+          fileKey: CLOUD_PENDING_KEY,
+          familyKey: spec.familyKey ?? CLOUD_PENDING_KEY,
+        },
+        milestoneBasename,
+        ctx.research.basename,
+        now,
+        ownerIntent,
+        researchJtbd,
+      );
+      const { frontmatter, body } = splitRawSpecForConsole(content);
+      const cleaned = stripServerMintedFields(frontmatter);
+      if (!spec.familyKey) delete cleaned.family;
+      let created;
+      try {
+        created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: 'epic',
+          name: spec.name,
+          frontmatter: cleaned,
+          body,
+          actingAgent: deps?.actingAgent ?? null,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'create', type: 'epic', name: spec.name },
+          completed: cloudCompleted,
+        });
+      }
+      spec.id = created.specId;
+      spec.basename = created.basename;
+      spec.relPath = created.relPath;
+      spec.cloudStored = storedOf(created, content);
+      recordCloud({
+        kind: 'create',
+        type: 'epic',
+        spec_id: created.specId,
+        basename: created.basename,
+        rel_path: created.relPath,
+      });
+    }
+
+    // ── 3. PUT the epics whose `depends_on` names a SIBLING: that basename
+    //       only became knowable in step 2.
+    const siblingBasenameByName = new Map(
+      spawnedEpicSpecs.map((s) => [s.name.trim().toLowerCase(), s.basename]),
+    );
+    for (const spec of spawnedEpicSpecs) {
+      if (!spec.pendingSiblingDeps?.length) continue;
+      const siblingBasenames = [];
+      for (const name of spec.pendingSiblingDeps) {
+        const b = siblingBasenameByName.get(name);
+        if (b) siblingBasenames.push(b);
+        else depWarnings.push({ epic: spec.name, unresolved: name });
+      }
+      if (siblingBasenames.length === 0) continue;
+      spec.depends_on = [...spec.depends_on, ...siblingBasenames];
+      const fm = { ...spec.cloudStored.frontmatter };
+      fm.depends_on = spec.depends_on.map((d) => `[[${d}]]`);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: spec.id,
+          frontmatter: fm,
+          body: spec.cloudStored.body,
+        });
+        recordCloud({
+          kind: 'update',
+          type: 'epic.depends_on',
+          spec_id: res.specId,
+          basename: res.basename ?? spec.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'epic.depends_on', basename: spec.basename },
+          completed: cloudCompleted,
+        });
+      }
+    }
+
+    // ── 4. PUT the milestone's `epics:` mirror (the cloud twin of the
+    //       post-commit `appendEpicToMilestone` line surgery) + `informed_by:`
+    //       on an EXISTING milestone. Both reference basenames from step 2.
+    const spawnedBasenames = spawnedEpicSpecs.map((s) => s.basename);
+    if (milestoneCreated) {
+      if (spawnedBasenames.length > 0) {
+        const fm = { ...milestoneStored.frontmatter };
+        fm.epics = spawnedBasenames.map((b) => `[[${b}]]`);
+        try {
+          const res = await updateSpecViaConsole({
+            ...cloudDeps,
+            specId: milestoneId,
+            frontmatter: fm,
+            body: milestoneStored.body,
+          });
+          recordCloud({
+            kind: 'update',
+            type: 'milestone.epics',
+            spec_id: res.specId,
+            basename: res.basename ?? milestoneBasename,
+            rel_path: res.relPath,
+          });
+        } catch (err) {
+          return cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'milestone.epics', basename: milestoneBasename },
+            completed: cloudCompleted,
+          });
+        }
+      }
+    } else {
+      const msRaw = ctx.targetResolution.milestone.raw;
+      let updatedRaw = buildUpdatedMilestoneContent(msRaw, {
+        researchBasename: ctx.research.basename,
+        now,
+      });
+      const fmBlock = getFrontmatterBlock(updatedRaw);
+      if (fmBlock && spawnedBasenames.length > 0) {
+        let block = fmBlock.block;
+        for (const b of spawnedBasenames) block = appendToListField(block, 'epics', b).block;
+        updatedRaw = `${fmBlock.open}${block}${fmBlock.close}${fmBlock.body}`;
+      }
+      if (updatedRaw !== msRaw) {
+        const { frontmatter, body } = splitRawSpecForConsole(updatedRaw);
+        try {
+          const res = await updateSpecViaConsole({
+            ...cloudDeps,
+            specId: milestoneId,
+            frontmatter,
+            body,
+          });
+          recordCloud({
+            kind: 'update',
+            type: 'milestone',
+            spec_id: res.specId,
+            basename: res.basename ?? milestoneBasename,
+            rel_path: res.relPath,
+          });
+        } catch (err) {
+          return cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'milestone', basename: milestoneBasename },
+            completed: cloudCompleted,
+          });
+        }
+      }
+    }
+
+    // ── 5. PUT the research doc LAST: `enhances:` + `spawned_epics:` +
+    //       `enhances_epics:` all name basenames a POST returned above.
+    const researchContentCloud = buildUpdatedResearchContent(ctx.research.raw, {
+      milestoneBasename,
+      spawnedEpicBasenames: spawnedBasenames,
+      augmentedEpicBasenames: augmentEpics.map((e) => e.basename),
+      now,
+      today,
+      author,
+    });
+    {
+      const { frontmatter, body } = splitRawSpecForConsole(researchContentCloud);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: ctx.research.frontmatter?.id ?? args.research_id,
+          frontmatter,
+          body,
+        });
+        recordCloud({
+          kind: 'update',
+          type: 'research',
+          spec_id: res.specId,
+          basename: res.basename ?? ctx.research.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'research', basename: ctx.research.basename },
+          completed: cloudCompleted,
+        });
+      }
+    }
+
+    // ── 6. Roadmap manifest append — EXPLICIT DEGRADE. `registerSpec` edits
+    //       `roadmap_manifest.milestones` inside a roadmap doc, and `roadmap`
+    //       is not one of the console's creatable/updatable spec types (its
+    //       TYPE_TO_FOLDER has no entry for it), so there is no route to make
+    //       this write through. Reported, never silently skipped.
+    const roadmapRegistrationCloud = milestoneCreated
+      ? {
+          ok: false,
+          ...cloudModeUnsupportedWrite(
+            `${args.roadmap_id || 'HS-ROADMAP-PRODUCT'} (roadmap_manifest.milestones)`,
+            'a roadmap doc is not one of the spec types the console can create or update (no TYPE_TO_FOLDER entry for "roadmap"), so there is no POST/PUT route for the manifest append',
+            { milestone_basename: milestoneBasename },
+          ),
+        }
+      : undefined;
+
+    return {
+      phase: 'executed',
+      write_mode: 'cloud',
+      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: cloudCompleted.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id })),
+      human_review_required: false,
+      ...(depWarnings.length > 0 ? { depends_on_warnings: depWarnings } : {}),
+      ...(roadmapRegistrationCloud ? { roadmap_registration: roadmapRegistrationCloud } : {}),
+    };
+  }
+
   // 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.
@@ -1401,10 +1992,20 @@ export async function executePromoteResearch(vaultRoot, args = {}, deps = {}) {
   const validationError = validateInputShape(args);
   if (validationError) return validationError;
 
+  // Cloud-tier reads ([[HS-KR16-CWPX-TASK-promotion-reads-through-the-cloud-tier]]):
+  // `deps.tier` is resolved ONCE by the caller (`handlePromoteResearch` in
+  // research-handlers.mjs, via `resolveReadTier()`) and threaded down —
+  // never re-resolved here. Absent (every pre-existing caller/test) defaults
+  // to `disk`, so disk-tier behavior is byte-identical to before this task.
+  const tier = deps.tier ?? 'disk';
+  const consoleUrl = deps.consoleUrl;
+  const consoleFetchDep = deps.consoleFetch;
+  const tierDeps = { tier, consoleUrl, consoleFetch: consoleFetchDep };
+
   // 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);
+  const resolved = await findResearchByIdViaTier(vaultRoot, args.research_id, tierDeps);
   if (!resolved || resolved.error) {
     return (
       resolved ?? {
@@ -1451,7 +2052,7 @@ export async function executePromoteResearch(vaultRoot, args = {}, deps = {}) {
   }
 
   // 2. Resolve target milestone.
-  const targetResolution = resolveTargetMilestone(vaultRoot, args);
+  const targetResolution = await resolveTargetMilestone(vaultRoot, args, tierDeps);
   if (targetResolution.error) return targetResolution;
 
   if (targetResolution.mode === 'existing') {
@@ -1476,12 +2077,17 @@ export async function executePromoteResearch(vaultRoot, args = {}, deps = {}) {
     );
     if (attachPolicy.error) return attachPolicy;
 
-    const conflict = validateBidirectionalEnhances(
-      researchState.enhances,
-      targetResolution.milestone.basename,
-    );
+    // [[HS-8XJA-KOGH-DIAG]]: an `enhances` set with no spawned_epics/enhances_epics
+    // behind it was never actually promoted (see validateResearchState) — treat
+    // it as unset rather than blocking on a signal the capture-promote step
+    // forged one stage early. buildUpdatedResearchContent below overwrites
+    // `enhances` unconditionally on a successful run, so this self-heals the
+    // stray pointer instead of requiring a hand-edit to clear it.
+    const conflict = researchState.enhancesBacked
+      ? validateBidirectionalEnhances(researchState.enhances, targetResolution.milestone.basename)
+      : null;
     if (conflict) return conflict;
-  } else if (researchState.enhances) {
+  } else if (researchState.enhances && researchState.enhancesBacked) {
     // Already enhances a milestone but target is NEW — refuse, the human should
     // either split the research or pick the existing milestone.
     return {
@@ -1538,6 +2144,13 @@ export const __testables = {
   validateInputShape,
   normalizeResearchRef,
   findResearchByIdLocal,
+  findResearchByIdViaTier,
+  findMilestoneByBasenameViaTier,
+  findMilestoneByIdViaTier,
+  findEpicByIdOrBasenameViaTier,
+  resolvePillarViaTier,
+  resolveOwnerIntentViaTier,
+  resolveTargetMilestone,
   validateExistingMilestoneAttachable,
   MILESTONE_ATTACH_DEFAULT_ALLOWED_STATUSES,
   resolvePillar,