heyspex 0.1.0 → 0.2.0

package/vendor/heyspex-mcp/spec-id-lib.mjs

@@ -114,6 +114,26 @@ export function findReviewDocForSpec(vaultRoot, parentSpecId) {
  */
 export const FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
 
+/**
+ * `hs next CJV2` → `HS-CJV2` (owner ruling 2026-09-01): typing the bare file
+ * key is the natural gesture — the `HS-` prefix carries no information the
+ * CLI needs, so requiring it is friction. Accepts the long display form too
+ * (`CJV2-90JL`, `CJV2-90JL-EPIC`) by normalizing on the FIRST segment.
+ *
+ * Returns the `HS-`-prefixed uppercase id, or `null` when the token is not a
+ * spec-id shape at all (so the caller can keep its own "unexpected argument"
+ * error). A token that already starts with `HS-` comes back uppercased and
+ * otherwise untouched. Mirror: spex-console/src/lib/vault-id.ts
+ * `normalizeBareSpecIdToken`.
+ */
+export function normalizeBareSpecIdToken(input) {
+  const token = String(input ?? '').trim().toUpperCase();
+  if (!token) return null;
+  if (token.startsWith('HS-')) return token;
+  const head = token.split('-')[0];
+  return FILE_KEY_RE.test(head) ? `HS-${token}` : null;
+}
+
 /**
  * File key carried by a spec id/basename in EITHER ordering, or null for
  * legacy no-file-key names. The file key is the first title-tail token when it
@@ -202,14 +222,36 @@ export function allocateFileKey(occupied, options = {}) {
 }
 
 /**
- * One-call mint for filing modules: walk the vault for occupied keys, then
- * allocate. `randomUnit` is injectable for tests. Occupancy is the UNION of
- * file keys AND family keys: era-3 ids are bare file keys, so a file key that
- * equals any family key makes a bare `HS-XXXX` citation ambiguous between one
- * file and a whole family ([[HS-SJOT-AEP1-DIAG]]).
+ * Mint a FILE KEY against an ALREADY-RESOLVED occupancy set. `randomUnit` is
+ * injectable for tests. `occupied` must be the UNION of file keys AND family
+ * keys: era-3 ids are bare file keys, so a file key that equals any family key
+ * makes a bare `HS-XXXX` citation ambiguous between one file and a whole
+ * family ([[HS-SJOT-AEP1-DIAG]]).
+ *
+ * TAKES THE OCCUPANCY, NOT A VAULT ROOT ([[HS-FJWL]]). This used to be
+ * `mintFileKey(vaultRoot)` and resolved occupancy itself, by walking
+ * `specs/**` — correct on the disk tier, blind on the cloud tier, where a
+ * filed spec has a Neon row and no local `.md` and the stale local clone still
+ * answers with a large, plausible-looking set. File keys are the unique
+ * per-file identity under Naming V3, so a blind scan there re-issues a live
+ * id. Callers now resolve occupancy for THEIR tier —
+ * `collectOccupiedKeysEitherKindViaTier` (occupied-keys.mjs) on a tier-aware
+ * path, `collectOccupiedKeysEitherKind` below on a path that is disk-only by
+ * construction — and hand the set in.
+ *
+ * The `Set` check is the migration's fail-loud: a call site left passing a
+ * vaultRoot string would otherwise mint against `collectOccupiedKeysEitherKind`
+ * of nothing, i.e. against an empty set, i.e. duplicates. Refuse instead.
  */
-export function mintFileKey(vaultRoot, options = {}) {
-  return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
+export function mintFileKey(occupied, options = {}) {
+  if (!(occupied instanceof Set)) {
+    throw new TypeError(
+      'mintFileKey(occupied, options) takes a resolved occupancy Set, not a vaultRoot ' +
+        '([[HS-FJWL]]). Use collectOccupiedKeysEitherKindViaTier(vaultRoot, { tier, consoleUrl }) ' +
+        'on a tier-aware path, or collectOccupiedKeysEitherKind(vaultRoot) on a disk-only one.',
+    );
+  }
+  return allocateFileKey(occupied, options);
 }
 
 /**
@@ -267,6 +309,20 @@ export function collectOccupiedKeysEitherKind(vaultRoot) {
  * machinery as {@link allocateFileKey} (4 chars, at least one letter),
  * checked against {@link collectOccupiedFamilyKeysFromVault} so a fresh mint
  * doesn't accidentally collide with an existing unrelated family.
+ *
+ * DELIBERATELY STILL DISK-ONLY — do not "fix" this into a network call
+ * ([[HS-FJWL]]). {@link mintFileKey} was made tier-aware because a file key is
+ * the unique per-file identity: re-issuing one is a duplicate id. A FAMILY key
+ * is the opposite — any number of specs may legally share one (V3 shared-
+ * surname model, see {@link collectOccupiedFamilyKeysFromVault}), so this
+ * occupancy scan is a "pick something fresh" heuristic, NOT a uniqueness gate.
+ * Missing a cloud-only family key costs at most a family name reused by an
+ * unrelated spec, which the model already permits; paying a paged console walk
+ * per family mint would buy nothing. The cross-namespace half
+ * ([[HS-SJOT-AEP1-DIAG]] — a family key must not equal a FILE key) is carried
+ * by the union below on the disk tier and, in cloud reliance, by the console's
+ * own `createSpec` mint, which resolves occupancy through `loadAll()` and is
+ * tier-correct by construction.
  */
 export function mintFamilyKey(vaultRoot, options = {}) {
   return allocateFileKey(collectOccupiedKeysEitherKind(vaultRoot), options);
@@ -553,21 +609,41 @@ export function isBareFamilyToken(input) {
 }
 
 /**
- * Guard for mutating MCP/CLI ops: reject a `spec_id` that is a bare family token
- * (ambiguous — resolves to a family, not one spec). Returns an error object
- * `{ error, message }` to surface to the caller, or `null` when the id is
- * unambiguous enough to act on. Read-only resolvers do NOT call this — they fan
- * a family token out to a set or just miss.
+ * Guard for mutating MCP/CLI ops: reject a `spec_id` that is a bare `HS-XXXX`
+ * token the caller has not proven names exactly one spec. Returns an error
+ * object `{ error, message }` to surface to the caller, or `null` when the id
+ * is unambiguous enough to act on. Read-only resolvers do NOT call this — they
+ * fan a family token out to a set or just miss.
+ *
+ * WORDING ([[HS-05ZW-XHR4-DIAG-the-capture-dropped-it-warning-blamed]] follow-on):
+ * {@link isBareFamilyToken} is SHAPE-ONLY — `HS-05ZW` is exactly as likely to be
+ * an era-3 FILE key (the stored `id:` of every newly minted spec) as a family
+ * key, and nothing here can tell them apart without a lookup. So the default
+ * message states only what was actually established: the token could not be
+ * resolved to one spec from this machine, and it may be either. A caller that
+ * HAS verified the family reading (e.g. `classifyBareSpecId` found the token
+ * among the vault's occupied family keys) passes `confirmedFamily: true` to get
+ * the stronger, now-earned wording. The actionable hint is identical either way.
+ *
+ * @param {string|null|undefined} input
+ * @param {{ confirmedFamily?: boolean, detail?: string|null }} [opts]
  */
-export function requireResolvableSpecId(input) {
+export function requireResolvableSpecId(input, opts = {}) {
   if (isBareFamilyToken(input)) {
     const base = normalizeIdInput(input);
+    const hint =
+      `Pass a full basename that includes the type label ` +
+      `(e.g. ${base}-TASK-<slug> or HS-TASK-${base.replace(/^HS-/, '')}-<slug>; ` +
+      `the era-3 form is ${base}-<FAMILY>-<TYPE>-<slug>).`;
+    const claim = opts.confirmedFamily
+      ? `"${base}" is a bare family key, which names a whole shared-suffix family ` +
+        `rather than one spec.`
+      : `"${base}" is a bare token that could not be resolved to exactly one spec ` +
+        `from this machine — it may be the file key of a spec with no local copy, ` +
+        `or a family key naming a whole shared-suffix family.`;
     return {
       error: 'AMBIGUOUS_SPEC_ID',
-      message:
-        `"${base}" is a bare family key, which names a whole shared-suffix family ` +
-        `rather than one spec. Pass a full basename that includes the type label ` +
-        `(e.g. ${base}-TASK-<slug> or HS-TASK-${base.replace(/^HS-/, '')}-<slug>).`,
+      message: opts.detail ? `${claim} ${opts.detail} ${hint}` : `${claim} ${hint}`,
     };
   }
   return null;

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

@@ -42,8 +42,27 @@ import {
   mkdirSync,
   unlinkSync,
 } from 'node:fs';
-import { join } from 'node:path';
-import { deriveSlug } from './promotion-helpers.mjs';
+import { join, isAbsolute, resolve, sep } from 'node:path';
+import {
+  deriveSlug,
+  fetchSpecRecordViaConsole,
+  resolveWriteModeFromDeps,
+  splitRawSpecForConsole,
+  cloudWriteFailureResult,
+} from './promotion-helpers.mjs';
+// Cloud-mode vault WRITES + the cloud-tier read selector
+// ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]], HS-KR16).
+// Split has the same create-first, link-second shape as the other promotion
+// flows: each child's "Split-from" callout names its SIBLINGS, and the
+// original's `split_into:` names every child — basenames the console only
+// mints when the POST lands.
+import {
+  createSpecViaConsole,
+  updateSpecViaConsole,
+  stripServerMintedFields,
+} from './cloud-vault-writes.mjs';
+import { readViaSelector } from './read-path.mjs';
+
 import { yamlScalar } from './yaml-scalar.mjs';
 import {
   allocateFileKey,
@@ -60,6 +79,14 @@ import {
 // caller would only learn that reactively when heyspex_promote_research
 // later refuses a child with RESEARCH_STILL_STUB.
 import { findUnresolvedResearchPlaceholders } from './promote-research.mjs';
+import { assertPathUnderRoot } from '../../scripts/lib/shared-path-helpers.mjs';
+
+// Placeholders the CLOUD path feeds `buildChildResearchContent` in place of a
+// locally-minted id / file key / family key; `stripServerMintedFields` removes
+// them from the POST body (plus an explicit `delete` of an un-inheritable
+// `family:`), so the console never sees them.
+const CLOUD_PENDING_ID = 'HS-PENDING';
+const CLOUD_PENDING_KEY = 'PENDING';
 
 // Id validation/classification is via parseSpecId (dual-read: accepts type-first
 // HS-RES-<key> / HS-MIL-<key> / HS-CAP-<key> and the family-first orderings, plus
@@ -216,7 +243,7 @@ function appendChangeLogRow(body, dateStr, author, message) {
   return body.replace(/\s*$/, '') + `\n${row}\n`;
 }
 
-function commitWrites(writes) {
+function commitWrites(writes, vaultRoot) {
   const snapshots = new Map();
   const performed = [];
   try {
@@ -230,7 +257,10 @@ function commitWrites(writes) {
           0,
           Math.max(w.absPath.lastIndexOf('/'), w.absPath.lastIndexOf('\\')),
         );
-        if (dir) mkdirSync(dir, { recursive: true });
+        if (dir) {
+          if (vaultRoot) assertPathUnderRoot(vaultRoot, dir, 'split-research write');
+          mkdirSync(dir, { recursive: true });
+        }
         writeFileSync(w.absPath, w.content, 'utf8');
         performed.push(w);
       } else if (w.kind === 'update') {
@@ -396,6 +426,46 @@ function findCaptureByIdOrBasename(vaultRoot, ref) {
   return null;
 }
 
+// ── Cloud-tier siblings of the three lookups above (HS-KR16 pattern) ────────
+// `tier` is resolved ONCE per call by `executeSplitResearch` from `deps.tier`
+// and threaded down; absent it is `disk`, so every pre-existing caller reads
+// exactly as before. The neon branch reuses `fetchSpecRecordViaConsole` — the
+// same injected-`consoleFetch` reader promote-capture/promote-research use —
+// so a test drives the whole flow with a recorder and never opens a socket.
+// These exist because a cloud WRITE is pointless if the INPUTS cannot be
+// found: the writes below all derive from the original research doc and the
+// captures it names.
+
+async function findResearchByIdViaTier(vaultRoot, researchId, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => findResearchByIdLocal(vaultRoot, researchId),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, researchId),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+async function findMilestoneViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => findMilestoneByIdOrBasename(vaultRoot, ref),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
+async function findCaptureViaTier(vaultRoot, ref, { tier, consoleUrl, consoleFetch }) {
+  return readViaSelector({
+    tier,
+    diskRead: () => findCaptureByIdOrBasename(vaultRoot, ref),
+    neonRead: () => fetchSpecRecordViaConsole(consoleFetch, ref),
+    routeLabel: 'GET /api/specs/[id]',
+    consoleUrl,
+  });
+}
+
 function collectOccupiedResearchIds(vaultRoot) {
   const occupied = new Set();
   const dir = join(vaultRoot, 'specs', 'research');
@@ -601,7 +671,20 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   const validationError = validateInputShape(args);
   if (validationError) return validationError;
 
-  const research = findResearchByIdLocal(vaultRoot, args.research_id);
+  // Tier + write mode are resolved ONCE, here, by the caller and threaded down
+  // — never re-resolved inside a helper. Both default to the disk behaviour so
+  // every pre-existing caller/test is byte-identical
+  // ([[HS-BYU4-CWPX-TASK-promotion-writes-go-through-the-console]]).
+  const tierDeps = {
+    tier: deps?.tier ?? 'disk',
+    consoleUrl: deps?.consoleUrl,
+    consoleFetch: deps?.consoleFetch,
+  };
+  const writeMode = resolveWriteModeFromDeps(deps);
+  const cloudDeps = { consoleFetch: deps?.consoleFetch, consoleUrl: deps?.consoleUrl };
+  const cloudCompleted = [];
+
+  const research = await findResearchByIdViaTier(vaultRoot, args.research_id, tierDeps);
   if (!research) {
     return {
       error: 'RESEARCH_NOT_FOUND',
@@ -650,9 +733,16 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   // Resolve all splits up-front, before any writes.
   // One occupied set across the whole loop (owner ruling 2026-07-10) — children
   // are not on disk yet, so a fresh vault walk per split could repeat a key.
-  const occupiedFileKeys = collectOccupiedKeysEitherKind(vaultRoot); // union: file+family keys (HS-SJOT)
+  //
+  // In CLOUD mode nothing is minted here at all: `collectOccupiedKeysEitherKind`
+  // is a vault SCAN, and in a file-less vault it returns an EMPTY set — a key
+  // drawn against it can collide with one the cloud vault already holds. The
+  // console mints every child's file key, family and filename.
+  const occupiedFileKeys =
+    writeMode === 'cloud' ? new Set() : collectOccupiedKeysEitherKind(vaultRoot); // union: file+family keys (HS-SJOT)
   const childRecords = [];
   const captureChildMap = new Map();
+  const captureRecords = new Map(); // basename -> record (raw reused by the write phase)
 
   for (let i = 0; i < args.splits.length; i++) {
     const split = args.splits[i];
@@ -661,7 +751,7 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     if (split.target_milestone === 'NEW') {
       targetMilestone = { absent: true, newName: split.new_milestone_name.trim() };
     } else {
-      const ms = findMilestoneByIdOrBasename(vaultRoot, split.target_milestone);
+      const ms = await findMilestoneViaTier(vaultRoot, split.target_milestone, tierDeps);
       if (!ms) {
         return {
           error: 'MILESTONE_NOT_FOUND',
@@ -673,7 +763,8 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
 
     const childCaptureBasenames = [];
     for (const captureRef of split.sources_captures) {
-      const cap = findCaptureByIdOrBasename(vaultRoot, captureRef);
+      const cap = await findCaptureViaTier(vaultRoot, captureRef, tierDeps);
+      if (cap) captureRecords.set(cap.basename, cap);
       if (!cap) {
         return {
           error: 'CAPTURE_NOT_FOUND',
@@ -695,15 +786,18 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     // original itself has no derivable family (should not occur for a real
     // research doc).
     const childFamilyKey =
-      originalFamilyKey ?? mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit });
+      writeMode === 'cloud'
+        ? (originalFamilyKey ?? null)
+        : (originalFamilyKey ?? mintFamilyKey(vaultRoot, { randomUnit: deps?.randomUnit }));
     // Per-file FILE KEY (owner ruling 2026-07-10) — filename + `file_id:` SSOT,
     // and (V3) the anchor for `id:` itself
     // ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]]).
-    const childFileKey = allocateFileKey(occupiedFileKeys, { randomUnit: deps?.randomUnit });
-    occupiedFileKeys.add(childFileKey);
-    const childId = `HS-${childFileKey}`;
+    const childFileKey =
+      writeMode === 'cloud' ? null : allocateFileKey(occupiedFileKeys, { randomUnit: deps?.randomUnit });
+    if (childFileKey) occupiedFileKeys.add(childFileKey);
+    const childId = childFileKey ? `HS-${childFileKey}` : null;
     const slug = deriveSlug(split.name);
-    const basename = `${childId}-${childFamilyKey}-RES-${slug}`;
+    const basename = childFileKey ? `${childId}-${childFamilyKey}-RES-${slug}` : null;
 
     childRecords.push({
       id: childId,
@@ -716,9 +810,13 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       bodySlice: split.body_slice,
     });
 
+    // Hold the child RECORD, not its basename: in cloud mode the basename is
+    // still null here and only lands when that child's POST answers, so the
+    // capture→children map is read lazily at write time in both modes.
+    const childRecord = childRecords[childRecords.length - 1];
     for (const capBasename of childCaptureBasenames) {
       if (!captureChildMap.has(capBasename)) captureChildMap.set(capBasename, []);
-      captureChildMap.get(capBasename).push(basename);
+      captureChildMap.get(capBasename).push(childRecord);
     }
   }
 
@@ -727,17 +825,16 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
   const today = now.slice(0, 10);
   const author = 'split-research (agent)';
   const writes = [];
-  const childBasenames = childRecords.map((c) => c.basename);
-
-  for (const child of childRecords) {
-    const content = buildChildResearchContent({
-      id: child.id,
-      fileKey: child.fileKey,
-      familyKey: child.familyKey,
-      basename: child.basename,
+
+  const buildChildContent = (child, siblingBasenames) =>
+    buildChildResearchContent({
+      id: child.id ?? CLOUD_PENDING_ID,
+      fileKey: child.fileKey ?? CLOUD_PENDING_KEY,
+      familyKey: child.familyKey ?? CLOUD_PENDING_KEY,
+      basename: child.basename ?? '',
       name: child.name,
       originalBasename: research.basename,
-      siblingBasenames: childBasenames,
+      siblingBasenames,
       targetMilestone: child.targetMilestone,
       capturesBasenames: child.capturesBasenames,
       bodySlice: child.bodySlice,
@@ -745,42 +842,186 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       today,
       author,
     });
-    child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
-    writes.push({
-      kind: 'create',
-      absPath: join(vaultRoot, 'specs', 'research', `${child.basename}.md`),
-      content,
+
+  if (writeMode === 'cloud') {
+    // ── CREATE FIRST ────────────────────────────────────────────────────────
+    // Each child is POSTed with an EMPTY sibling list (a sibling's basename is
+    // minted by the console, so it cannot be known before that sibling's own
+    // POST answers), then re-PUT once every basename is in hand. The sibling
+    // cross-links live only in the "Split-from:" body callout, so the follow-up
+    // PUT replaces the BODY and keeps the frontmatter the console stored.
+    for (const child of childRecords) {
+      const content = buildChildContent(child, []);
+      child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
+      const { frontmatter, body } = splitRawSpecForConsole(content);
+      const cleaned = stripServerMintedFields(frontmatter);
+      if (!child.familyKey) delete cleaned.family;
+      let created;
+      try {
+        created = await createSpecViaConsole({
+          ...cloudDeps,
+          type: 'research',
+          name: child.name,
+          frontmatter: cleaned,
+          body,
+          actingAgent: deps?.actingAgent ?? null,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'create', type: 'research', name: child.name },
+          completed: cloudCompleted,
+        });
+      }
+      child.id = created.specId;
+      child.basename = created.basename;
+      child.relPath = created.relPath;
+      child.cloudFrontmatter = created.spec?.frontmatter ?? cleaned;
+      cloudCompleted.push({
+        kind: 'create',
+        type: 'research',
+        spec_id: created.specId,
+        basename: created.basename,
+        rel_path: created.relPath,
+      });
+    }
+
+    const cloudChildBasenames = childRecords.map((c) => c.basename);
+
+    // ── …LINK SECOND: sibling callouts, then the original, then the captures.
+    if (childRecords.length > 1) {
+      for (const child of childRecords) {
+        const rebuilt = buildChildContent(child, cloudChildBasenames);
+        const { body } = splitRawSpecForConsole(rebuilt);
+        try {
+          const res = await updateSpecViaConsole({
+            ...cloudDeps,
+            specId: child.id,
+            frontmatter: child.cloudFrontmatter,
+            body,
+          });
+          cloudCompleted.push({
+            kind: 'update',
+            type: 'research.siblings',
+            spec_id: res.specId,
+            basename: res.basename ?? child.basename,
+            rel_path: res.relPath,
+          });
+        } catch (err) {
+          return cloudWriteFailureResult(err, {
+            step: { kind: 'update', type: 'research.siblings', basename: child.basename },
+            completed: cloudCompleted,
+          });
+        }
+      }
+    }
+
+    const originalUpdatedCloud = buildUpdatedOriginalContent(research.raw, {
+      childBasenames: cloudChildBasenames,
+      now,
+      today,
+      author,
     });
-  }
+    {
+      const { frontmatter, body } = splitRawSpecForConsole(originalUpdatedCloud);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: originalId,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: 'research.original',
+          spec_id: res.specId,
+          basename: res.basename ?? research.basename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'research.original', basename: research.basename },
+          completed: cloudCompleted,
+        });
+      }
+    }
 
-  const originalUpdated = buildUpdatedOriginalContent(research.raw, {
-    childBasenames,
-    now,
-    today,
-    author,
-  });
-  writes.push({
-    kind: 'update',
-    absPath: research.absPath,
-    content: originalUpdated,
-  });
+    for (const [capBasename, childList] of captureChildMap.entries()) {
+      const capRecord = captureRecords.get(capBasename);
+      if (!capRecord) continue;
+      const capUpdated = buildUpdatedCaptureContent(
+        capRecord.raw,
+        childList.map((c) => c.basename),
+        now,
+      );
+      if (capUpdated === capRecord.raw) continue;
+      const { frontmatter, body } = splitRawSpecForConsole(capUpdated);
+      try {
+        const res = await updateSpecViaConsole({
+          ...cloudDeps,
+          specId: getScalarField(getFrontmatterBlock(capRecord.raw)?.block ?? '', 'id') ?? capBasename,
+          frontmatter,
+          body,
+        });
+        cloudCompleted.push({
+          kind: 'update',
+          type: 'capture',
+          spec_id: res.specId,
+          basename: res.basename ?? capBasename,
+          rel_path: res.relPath,
+        });
+      } catch (err) {
+        return cloudWriteFailureResult(err, {
+          step: { kind: 'update', type: 'capture', basename: capBasename },
+          completed: cloudCompleted,
+        });
+      }
+    }
+  } else {
+    const childBasenames = childRecords.map((c) => c.basename);
+
+    for (const child of childRecords) {
+      const content = buildChildContent(child, childBasenames);
+      child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
+      writes.push({
+        kind: 'create',
+        absPath: join(vaultRoot, 'specs', 'research', `${child.basename}.md`),
+        content,
+      });
+    }
 
-  for (const [capBasename, childList] of captureChildMap.entries()) {
-    const capAbs = join(vaultRoot, 'specs', 'captures', `${capBasename}.md`);
-    const capRaw = readFileSync(capAbs, 'utf8');
-    const capUpdated = buildUpdatedCaptureContent(capRaw, childList, now);
-    if (capUpdated !== capRaw) {
-      writes.push({ kind: 'update', absPath: capAbs, content: capUpdated });
+    const originalUpdated = buildUpdatedOriginalContent(research.raw, {
+      childBasenames,
+      now,
+      today,
+      author,
+    });
+    writes.push({
+      kind: 'update',
+      absPath: research.absPath,
+      content: originalUpdated,
+    });
+
+    for (const [capBasename, childList] of captureChildMap.entries()) {
+      const capAbs = join(vaultRoot, 'specs', 'captures', `${capBasename}.md`);
+      const capRaw = readFileSync(capAbs, 'utf8');
+      const capUpdated = buildUpdatedCaptureContent(
+        capRaw,
+        childList.map((c) => c.basename),
+        now,
+      );
+      if (capUpdated !== capRaw) {
+        writes.push({ kind: 'update', absPath: capAbs, content: capUpdated });
+      }
     }
-  }
 
-  const commitResult = commitWrites(writes);
-  if (!commitResult.ok) {
-    return {
-      error: 'WRITE_FAILED',
-      message: commitResult.error?.message ?? 'unknown write failure',
-      rollback_error: commitResult.error?.rollbackError,
-    };
+    const commitResult = commitWrites(writes, vaultRoot);
+    if (!commitResult.ok) {
+      return {
+        error: 'WRITE_FAILED',
+        message: commitResult.error?.message ?? 'unknown write failure',
+        rollback_error: commitResult.error?.rollbackError,
+      };
+    }
   }
 
   const anyChildStillStub = childRecords.some((c) => c.unresolvedPlaceholderCount > 0);
@@ -790,10 +1031,11 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
     archive_basename: research.basename,
     archive_path: research.relPath,
     archive_status_after: getScalarField(fm.block, 'status') ?? 'open',
+    ...(writeMode === 'cloud' ? { write_mode: 'cloud' } : {}),
     children: childRecords.map((c) => ({
       id: c.id,
       basename: c.basename,
-      path: join('specs', 'research', `${c.basename}.md`),
+      path: c.relPath ?? join('specs', 'research', `${c.basename}.md`),
       target_milestone: c.targetMilestone.absent ? 'NEW' : c.targetMilestone.basename,
       sources_captures: c.capturesBasenames,
       // Same placeholder count RESEARCH_STILL_STUB would later refuse
@@ -802,7 +1044,10 @@ export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
       research_still_stub: c.unresolvedPlaceholderCount > 0,
       unresolved_placeholder_count: c.unresolvedPlaceholderCount,
     })),
-    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+    writes:
+      writeMode === 'cloud'
+        ? cloudCompleted.map((w) => ({ kind: w.kind, path: w.rel_path ?? null, spec_id: w.spec_id }))
+        : writes.map((w) => ({ kind: w.kind, path: w.absPath })),
     // No fallback warning: every child unconditionally inherits the
     // original's family key (V3 shared-surname model — see the block comment
     // above inheritedFamilyKey).

package/vendor/heyspex-mcp/stdio-rpc.mjs

@@ -0,0 +1,22 @@
+// JSON-RPC writers for the stdio transport — the only place the MCP server
+// writes to stdout. Extracted from cli.mjs under
+// [[HS-BLNF-6W61-DIAG-cli-mjs-has-grown-into-a-13-665-line]] (no behavior change).
+
+export function sendResponse(id, result) {
+  const response = { jsonrpc: '2.0', id, result };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+export function sendError(id, code, message, data) {
+  const response = {
+    jsonrpc: '2.0',
+    id,
+    error: { code, message, ...(data && { data }) },
+  };
+  process.stdout.write(JSON.stringify(response) + '\n');
+}
+
+export function sendNotification(method, params) {
+  const notification = { jsonrpc: '2.0', method, params };
+  process.stdout.write(JSON.stringify(notification) + '\n');
+}