heyspex 0.1.0

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

@@ -0,0 +1,832 @@
+/**
+ * /hs-split-research MCP tool — split a single research doc into N child
+ * research docs (each targeting one milestone) before promotion. Spec:
+ * [[HS-TASK-GTH9]] of [[HS-EPIC-M2J3]].
+ *
+ * Single-phase flow (caller supplies body_slice + sources_captures partitions):
+ *
+ *   1. Load + validate the original research (must be type: research, not
+ *      already split, ≥2 split entries provided).
+ *   2. For each split entry: resolve target_milestone (existing HS-MIL-* or
+ *      "NEW" placeholder), verify sources_captures ⊆ original.sources_captures,
+ *      allocate HS-RES-<id>, build child basename.
+ *   3. Stage writes transactionally:
+ *      - Create N child research files (split_from, sources_captures,
+ *        body_slice, "Split-from:" callout prepended, change-log row).
+ *      - Update original: set split_into: [children], prepend "Split:" callout,
+ *        append change-log row. Status stays `open` — research is evergreen.
+ *      - For each capture in any child's sources_captures: append the child
+ *        research basename to capture.informs_research (bidirectional rule
+ *        per [[HS-TASK-YJX6]]).
+ *   4. Commit. On any single-step failure, roll back all writes.
+ *
+ * Children land as status: open — promotion to a milestone happens later via
+ * /hs-promote-research ([[HS-TASK-QQHP]]); split is content partitioning, not
+ * milestone binding. The "target_milestone" arg is recorded in each child's
+ * body callout (for human readability) but does NOT write to child.enhances
+ * (which is only required at promotion time, per [[HS-TASK-YJX6]]).
+ *
+ * The split archive stays `status: open` too (research is evergreen,
+ * [[research-is-evergreen]]) and sets `split_into:` to record its children. It
+ * carries no `enhances:` of its own (each child enhances its own milestone at
+ * promotion), which is fine under the "enhances REQUIRED when set" rule in
+ * [[entity-model]]. Re-split is guarded by the presence of `split_into:`, not by
+ * a status flip.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  readdirSync,
+  mkdirSync,
+  unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { deriveSlug } from './promotion-helpers.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import {
+  allocateFileKey,
+  collectOccupiedKeysEitherKind,
+  mintFamilyKey,
+  parseSpecId,
+  familyOf,
+} from './spec-id-lib.mjs';
+// Same sweep as heyspex_promote_capture's proactive stub warning
+// ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]): a caller can
+// split a research doc that is still its own promote-capture outline stub
+// (e.g. splitting before running /hs-res) — each child then inherits the
+// same `_TBD — fill in this section._` placeholders, and without this the
+// caller would only learn that reactively when heyspex_promote_research
+// later refuses a child with RESEARCH_STILL_STUB.
+import { findUnresolvedResearchPlaceholders } from './promote-research.mjs';
+
+// 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
+// legacy numeric keys), so no hand-rolled type-first regexes are kept here
+// ([[HS-EPIC-DLE3]]).
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Family inheritance (split children → parent research's family), owner
+// ruling 2026-07-12 ([[family-id-is-inherited-capture-research]] /
+// [[HS-3JUN-DIAG-HZ8T]]), rewritten for the V3 shared-surname model
+// ([[HS-ZU1Q-TASK-PNAS-flip-new-spec-minting-to-the-file-key]],
+// [[naming-v3-7-rulings-hs-namespace-kept]]). Same disambiguation rule as
+// promote-capture.mjs (duplicated per this file's own "independently
+// shippable" convention): under era-3 minting, `id:` keys onto the per-file
+// file key alone, not the family key, so any number of research docs — the
+// archived original AND every split child — can now legally share one
+// family key at once. Every child inherits the ORIGINAL research's family
+// key UNCONDITIONALLY; there is no collision to fall back from, so
+// `FAMILY_INHERITANCE_FALLBACK` is dead.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The family key `sourceId` carries: explicit `frontmatter.family` when
+ * present, else the positional family key parsed from `id` (dual-read,
+ * either ordering) — delegates to {@link familyOf}. Returns null when
+ * `sourceId` doesn't parse and no frontmatter was supplied.
+ */
+function inheritedFamilyKey(sourceId, sourceFrontmatter) {
+  return familyOf({ id: sourceId, frontmatter: sourceFrontmatter });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Generic helpers (mirrored from promote-research.mjs — duplicated rather
+// than imported to keep the two MCP tools independently shippable; if a third
+// caller emerges, extract into a shared research-frontmatter.mjs module).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+function getFrontmatterBlock(raw) {
+  const m = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---\r?\n?)/);
+  if (!m) return null;
+  return {
+    open: m[1],
+    block: m[2],
+    close: m[3],
+    body: raw.slice(m[0].length),
+    full: m[0],
+  };
+}
+
+function getScalarField(block, field) {
+  const re = new RegExp(`^${field}:[ \\t]*(.*)$`, 'm');
+  const m = block.match(re);
+  if (!m) return null;
+  const raw = m[1].trim();
+  if (!raw) return null;
+  return raw.replace(/^['"]|['"]$/g, '');
+}
+
+function parseWikilinkBasename(value) {
+  if (!value) return null;
+  const m = value.match(/^\[\[([^\]]+)\]\]$/);
+  return m ? m[1] : null;
+}
+
+function parseListFieldBasenames(block, field) {
+  const emptyRe = new RegExp(`^${field}:[ \\t]*\\[[ \\t]*\\][ \\t]*$`, 'm');
+  if (emptyRe.test(block)) return [];
+  const headRe = new RegExp(`^${field}:[ \\t]*\\r?\\n`, 'm');
+  const headMatch = block.match(headRe);
+  if (!headMatch) return null;
+  const startIdx = headMatch.index + headMatch[0].length;
+  const lines = block.slice(startIdx).split(/\r?\n/);
+  const items = [];
+  for (const line of lines) {
+    if (/^[ \t]+-[^\n]*$/.test(line)) {
+      items.push(line);
+      continue;
+    }
+    break;
+  }
+  if (items.length === 0) return null;
+  const out = [];
+  for (const line of items) {
+    const wm = line.match(/-[ \t]*["']?\[\[([^\]]+)\]\]["']?/);
+    if (wm) out.push(wm[1]);
+  }
+  return out;
+}
+
+function appendToListField(block, field, basename) {
+  const existing = parseListFieldBasenames(block, field);
+  if (existing && existing.includes(basename)) return { block, changed: false };
+
+  const emptyRe = new RegExp(`^${field}:[ \\t]*\\[[ \\t]*\\][ \\t]*$`, 'm');
+  if (emptyRe.test(block)) {
+    const replacement = `${field}:\n  - "[[${basename}]]"`;
+    return { block: block.replace(emptyRe, replacement), changed: true };
+  }
+
+  if (existing !== null) {
+    const headRe = new RegExp(`^${field}:[ \\t]*\\r?\\n`, 'm');
+    const headMatch = block.match(headRe);
+    if (headMatch) {
+      const before = block.slice(0, headMatch.index);
+      const startIdx = headMatch.index + headMatch[0].length;
+      let endIdx = startIdx;
+      const lines = block.slice(startIdx).split(/\r?\n/);
+      for (const line of lines) {
+        if (/^[ \t]+-[^\n]*$/.test(line)) {
+          endIdx += line.length + 1;
+          continue;
+        }
+        break;
+      }
+      const after = endIdx > block.length ? '' : block.slice(endIdx - 1);
+      const allItems = [...existing, basename]
+        .map((b) => `  - "[[${b}]]"`)
+        .join('\n');
+      const next = `${before}${field}:\n${allItems}${after.startsWith('\n') ? after : '\n' + after}`;
+      return { block: next.replace(/\n+$/, ''), changed: true };
+    }
+  }
+
+  const appended = `${block}\n${field}:\n  - "[[${basename}]]"`;
+  return { block: appended, changed: true };
+}
+
+function setScalarField(block, field, value) {
+  const re = new RegExp(`^${field}:[ \\t]*(.*)$`, 'm');
+  if (re.test(block)) {
+    return block.replace(re, `${field}: ${value}`);
+  }
+  const trimmed = block.replace(/\r?\n$/, '');
+  return `${trimmed}\n${field}: ${value}`;
+}
+
+function bumpUpdated(block, now) {
+  return setScalarField(block, 'updated', `"${now}"`);
+}
+
+function appendChangeLogRow(body, dateStr, author, message) {
+  const row = `| ${dateStr} | ${author} | ${message} |`;
+  const headingMatch = body.match(/^## Change[ -]log\s*$/im);
+  if (!headingMatch) {
+    return (
+      body.replace(/\s*$/, '') +
+      `\n\n## Change log\n\n| Date | Author | Change |\n| --- | --- | --- |\n${row}\n`
+    );
+  }
+  return body.replace(/\s*$/, '') + `\n${row}\n`;
+}
+
+function commitWrites(writes) {
+  const snapshots = new Map();
+  const performed = [];
+  try {
+    for (const w of writes) {
+      if (w.kind === 'create') {
+        if (existsSync(w.absPath)) {
+          throw new Error(`refusing to overwrite existing file: ${w.absPath}`);
+        }
+        snapshots.set(w.absPath, { existed: false });
+        const dir = w.absPath.slice(
+          0,
+          Math.max(w.absPath.lastIndexOf('/'), w.absPath.lastIndexOf('\\')),
+        );
+        if (dir) mkdirSync(dir, { recursive: true });
+        writeFileSync(w.absPath, w.content, 'utf8');
+        performed.push(w);
+      } else if (w.kind === 'update') {
+        if (!existsSync(w.absPath)) {
+          throw new Error(`cannot update missing file: ${w.absPath}`);
+        }
+        if (!snapshots.has(w.absPath)) {
+          snapshots.set(w.absPath, {
+            existed: true,
+            original: readFileSync(w.absPath, 'utf8'),
+          });
+        }
+        writeFileSync(w.absPath, w.content, 'utf8');
+        performed.push(w);
+      }
+    }
+    return { ok: true };
+  } catch (err) {
+    for (const w of performed.reverse()) {
+      const snap = snapshots.get(w.absPath);
+      if (!snap) continue;
+      try {
+        if (snap.existed) {
+          writeFileSync(w.absPath, snap.original, 'utf8');
+        } else if (existsSync(w.absPath)) {
+          unlinkSync(w.absPath);
+        }
+      } catch (rollbackErr) {
+        err.rollbackError = rollbackErr.message;
+      }
+    }
+    return { ok: false, error: err };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Vault lookups
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findFileByPrefix(dir, prefix) {
+  if (!existsSync(dir)) return null;
+  const exact = `${prefix}.md`;
+  let prefixHit = null;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    if (file === exact) return file;
+    if (prefixHit === null && file.startsWith(`${prefix}-`)) prefixHit = file;
+  }
+  return prefixHit;
+}
+
+/**
+ * Resolve a research reference to a file under specs/research/. Same
+ * resolution order as promote-research: exact basename (wikilink/`.md`
+ * tolerant) → frontmatter `id:`/`file_id:` → `<ref>-` prefix. Returns the
+ * record or null; the caller applies the `type: research` gate
+ * ([[HS-B1ZT-QCP2-DIAG-heyspex-promote-research-cannot-resolve]]).
+ */
+function findResearchByIdLocal(vaultRoot, researchId) {
+  const dir = join(vaultRoot, 'specs', 'research');
+  if (!existsSync(dir)) return null;
+  let ref = typeof researchId === 'string' ? researchId.trim().replace(/^['"]|['"]$/g, '').trim() : '';
+  ref = (parseWikilinkBasename(ref) ?? ref).replace(/\.md$/i, '').trim();
+  if (!ref) return null;
+
+  const tryFile = (file) => {
+    const basename = file.replace(/\.md$/i, '');
+    const absPath = join(dir, file);
+    const raw = readFileSync(absPath, 'utf8');
+    return { basename, absPath, relPath: join('specs', 'research', file), raw };
+  };
+
+  // 1. Exact basename (also covers the truncated-prefix form via step 3).
+  if (existsSync(join(dir, `${ref}.md`))) return tryFile(`${ref}.md`);
+
+  const files = readdirSync(dir).filter((f) => f.toLowerCase().endsWith('.md'));
+
+  // 2. Frontmatter id: / file_id: scan.
+  for (const file of files) {
+    let raw;
+    try {
+      raw = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    const block = getFrontmatterBlock(raw)?.block;
+    if (!block) continue;
+    if (getScalarField(block, 'id') === ref || getScalarField(block, 'file_id') === ref) {
+      return tryFile(file);
+    }
+  }
+
+  // 3. Prefix match (last resort).
+  const direct = findFileByPrefix(dir, ref);
+  return direct ? tryFile(direct) : null;
+}
+
+function findMilestoneByIdOrBasename(vaultRoot, ref) {
+  const dir = join(vaultRoot, 'specs', 'milestones');
+  if (!existsSync(dir)) return null;
+  let normalized = ref;
+  if (/\.md$/.test(normalized)) normalized = normalized.replace(/\.md$/, '');
+  const wikilink = parseWikilinkBasename(normalized);
+  if (wikilink) normalized = wikilink;
+
+  const directAbs = join(dir, `${normalized}.md`);
+  if (existsSync(directAbs)) {
+    return {
+      basename: normalized,
+      absPath: directAbs,
+      relPath: join('specs', 'milestones', `${normalized}.md`),
+      raw: readFileSync(directAbs, 'utf8'),
+    };
+  }
+  if (parseSpecId(normalized)?.typeLabel === 'MIL') {
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.md')) continue;
+      if (file.startsWith(`${normalized}-`)) {
+        const basename = file.replace(/\.md$/, '');
+        return {
+          basename,
+          absPath: join(dir, file),
+          relPath: join('specs', 'milestones', file),
+          raw: readFileSync(join(dir, file), 'utf8'),
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function findCaptureByIdOrBasename(vaultRoot, ref) {
+  const dir = join(vaultRoot, 'specs', 'captures');
+  if (!existsSync(dir)) return null;
+  let normalized = ref;
+  if (/\.md$/.test(normalized)) normalized = normalized.replace(/\.md$/, '');
+  const wikilink = parseWikilinkBasename(normalized);
+  if (wikilink) normalized = wikilink;
+
+  const directAbs = join(dir, `${normalized}.md`);
+  if (existsSync(directAbs)) {
+    return {
+      basename: normalized,
+      absPath: directAbs,
+      relPath: join('specs', 'captures', `${normalized}.md`),
+      raw: readFileSync(directAbs, 'utf8'),
+    };
+  }
+  if (parseSpecId(normalized)?.typeLabel === 'CAP') {
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith('.md')) continue;
+      if (file.startsWith(`${normalized}-`)) {
+        const basename = file.replace(/\.md$/, '');
+        return {
+          basename,
+          absPath: join(dir, file),
+          relPath: join('specs', 'captures', file),
+          raw: readFileSync(join(dir, file), 'utf8'),
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function collectOccupiedResearchIds(vaultRoot) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'research');
+  if (!existsSync(dir)) return occupied;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    // Key the occupied set on the canonical family-first id (dual-read on both
+    // the basename and the frontmatter id) so suffix-collision detection matches
+    // what allocateRandomVaultId generates/compares ([[HS-EPIC-DLE3]]).
+    const fromName = parseSpecId(file.replace(/\.md$/i, ''));
+    if (fromName && fromName.typeLabel === 'RES') {
+      occupied.add(`HS-${fromName.familyKey}-RES`);
+    }
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const idMatch = raw.match(/^id:\s*(\S+)/m);
+      if (idMatch) {
+        const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+        const fromId = parseSpecId(id);
+        if (fromId && fromId.typeLabel === 'RES') {
+          occupied.add(`HS-${fromId.familyKey}-RES`);
+        }
+      }
+    } catch {
+      /* skip */
+    }
+  }
+  return occupied;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Input validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateInputShape(args) {
+  if (!args || typeof args !== 'object') {
+    return { error: 'INVALID_ARGS', message: 'args must be an object' };
+  }
+  if (typeof args.research_id !== 'string' || !args.research_id.trim()) {
+    return { error: 'INVALID_ARGS', message: 'research_id is required' };
+  }
+  // No id-shape gate: a bare era-3 file id (`HS-X5FH`) carries no `RES` label,
+  // and rejecting it here fired before the resolver could find the file. The
+  // `type: research` check below (WRONG_TYPE) is the real gate.
+  if (!Array.isArray(args.splits) || args.splits.length < 2) {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'splits must be an array of at least 2 entries (splitting into 1 is a no-op)',
+    };
+  }
+  for (let i = 0; i < args.splits.length; i++) {
+    const s = args.splits[i];
+    if (!s || typeof s !== 'object') {
+      return { error: 'INVALID_ARGS', message: `splits[${i}] must be an object` };
+    }
+    if (typeof s.name !== 'string' || !s.name.trim()) {
+      return { error: 'INVALID_ARGS', message: `splits[${i}].name is required` };
+    }
+    if (typeof s.target_milestone !== 'string' || !s.target_milestone.trim()) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `splits[${i}].target_milestone is required (HS-MIL-* id, basename, or the literal "NEW")`,
+      };
+    }
+    if (
+      s.target_milestone === 'NEW' &&
+      (typeof s.new_milestone_name !== 'string' || !s.new_milestone_name.trim())
+    ) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `splits[${i}].new_milestone_name is required when target_milestone === "NEW"`,
+      };
+    }
+    if (typeof s.body_slice !== 'string' || !s.body_slice.trim()) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `splits[${i}].body_slice is required (non-empty string — caller-prepared partition of original body)`,
+      };
+    }
+    if (!Array.isArray(s.sources_captures)) {
+      return {
+        error: 'INVALID_ARGS',
+        message: `splits[${i}].sources_captures must be an array (may be empty)`,
+      };
+    }
+  }
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Child + original content builders
+// ─────────────────────────────────────────────────────────────────────────────
+
+function buildChildResearchContent({
+  id,
+  fileKey,
+  familyKey,
+  basename,
+  name,
+  originalBasename,
+  siblingBasenames,
+  targetMilestone,
+  capturesBasenames,
+  bodySlice,
+  now,
+  today,
+  author,
+}) {
+  const sourcesBlock =
+    capturesBasenames.length === 0
+      ? 'sources_captures: []'
+      : `sources_captures:\n${capturesBasenames.map((b) => `  - "[[${b}]]"`).join('\n')}`;
+
+  const siblings = siblingBasenames.filter((b) => b !== basename);
+  const siblingPhrase =
+    siblings.length === 0
+      ? ''
+      : siblings.length === 1
+        ? `; sibling slice lives at [[${siblings[0]}]]`
+        : `; sibling slices live at ${siblings.map((b) => `[[${b}]]`).join(', ')}`;
+
+  const milestonePhrase = targetMilestone.absent
+    ? 'targets a new milestone (to be created at promotion via /hs-promote-research)'
+    : `targets [[${targetMilestone.basename}]] specifically`;
+
+  const calloutLine = `> **Split-from:** [[${originalBasename}]]. This research ${milestonePhrase}${siblingPhrase}.`;
+
+  return `---
+id: ${id}
+file_id: ${fileKey}
+family: ${familyKey}
+name: ${yamlScalar(name)}
+type: research
+status: open
+owner: pwher
+created: "${now}"
+updated: "${now}"
+split_from: "[[${originalBasename}]]"
+${sourcesBlock}
+tags:
+  - research
+  - split-child
+related: []
+---
+
+${calloutLine}
+
+${bodySlice.trim()}
+
+## Change log
+
+| Date | Author | Change |
+| --- | --- | --- |
+| ${today} | ${author} | Created via /hs-split-research from [[${originalBasename}]]. |
+`;
+}
+
+function buildUpdatedOriginalContent(raw, params) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) throw new Error('original research has no frontmatter — cannot split');
+  let block = fm.block;
+  for (const childBasename of params.childBasenames) {
+    block = appendToListField(block, 'split_into', childBasename).block;
+  }
+  // status is intentionally NOT touched — the archive stays `status: open`
+  // (research is evergreen; see [[research-is-evergreen]]). `split_into:` records
+  // the children and guards against re-split.
+  block = bumpUpdated(block, params.now);
+
+  const childList =
+    params.childBasenames.length === 2
+      ? `${params.childBasenames.map((b) => `[[${b}]]`).join(' and ')}`
+      : params.childBasenames.map((b) => `[[${b}]]`).join(', ');
+  const callout = `> **Split:** This research was split into ${childList} on ${params.today} via /hs-split-research. Original content preserved below for audit.`;
+  const newBody = `\n${callout}\n${fm.body}`;
+  const changeMsg = `Split into ${params.childBasenames.length} child research doc(s) via /hs-split-research. Archive stays evergreen (status: open); split_into records the children.`;
+  const finalBody = appendChangeLogRow(newBody, params.today, params.author, changeMsg);
+  return `${fm.open}${block}${fm.close}${finalBody}`;
+}
+
+function buildUpdatedCaptureContent(raw, childBasenames, now) {
+  const fm = getFrontmatterBlock(raw);
+  if (!fm) throw new Error('capture has no frontmatter — cannot update informs_research');
+  let block = fm.block;
+  let changed = false;
+  for (const child of childBasenames) {
+    const next = appendToListField(block, 'informs_research', child);
+    if (next.changed) {
+      block = next.block;
+      changed = true;
+    }
+  }
+  if (!changed) return raw;
+  block = bumpUpdated(block, now);
+  return `${fm.open}${block}${fm.close}${fm.body}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+export async function executeSplitResearch(vaultRoot, args = {}, deps = {}) {
+  const validationError = validateInputShape(args);
+  if (validationError) return validationError;
+
+  const research = findResearchByIdLocal(vaultRoot, args.research_id);
+  if (!research) {
+    return {
+      error: 'RESEARCH_NOT_FOUND',
+      message: `research ${args.research_id} not found under specs/research/`,
+    };
+  }
+
+  const fm = getFrontmatterBlock(research.raw);
+  if (!fm) {
+    return {
+      error: 'RESEARCH_FRONTMATTER_MISSING',
+      message: `research ${research.basename} has no frontmatter`,
+    };
+  }
+
+  const type = getScalarField(fm.block, 'type');
+  if (type !== 'research') {
+    return {
+      error: 'WRONG_TYPE',
+      message: `${research.basename} is not type: research (got ${type ?? 'null'})`,
+    };
+  }
+
+  // Research is evergreen ([[research-is-evergreen]]) — a split archive stays
+  // `status: open`, so re-split is guarded by the presence of `split_into:`
+  // (set on the first split), not by a status flip.
+  const existingSplitInto = parseListFieldBasenames(fm.block, 'split_into');
+  if (existingSplitInto && existingSplitInto.length > 0) {
+    return {
+      error: 'RESEARCH_ALREADY_SPLIT',
+      message: `research ${research.basename} already has \`split_into:\` set (${existingSplitInto.join(', ')}) — /hs-split-research refuses to re-split an archive. File a new research doc if further partitioning is needed.`,
+    };
+  }
+
+  const originalCaptureBasenames = parseListFieldBasenames(fm.block, 'sources_captures') ?? [];
+  // Family inheritance source: the ORIGINAL research's own family (see block
+  // comment above inheritedFamilyKey) — every child inherits THIS family key
+  // UNCONDITIONALLY, per the owner ruling "split children stay in the parent
+  // research's family". V3 shared-surname model: any number of children AND
+  // the archived original may now legally share it at once.
+  const originalId = getScalarField(fm.block, 'id') ?? args.research_id;
+  const originalFamilyKey = inheritedFamilyKey(originalId, {
+    family: getScalarField(fm.block, 'family'),
+  });
+
+  // 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)
+  const childRecords = [];
+  const captureChildMap = new Map();
+
+  for (let i = 0; i < args.splits.length; i++) {
+    const split = args.splits[i];
+
+    let targetMilestone;
+    if (split.target_milestone === 'NEW') {
+      targetMilestone = { absent: true, newName: split.new_milestone_name.trim() };
+    } else {
+      const ms = findMilestoneByIdOrBasename(vaultRoot, split.target_milestone);
+      if (!ms) {
+        return {
+          error: 'MILESTONE_NOT_FOUND',
+          message: `splits[${i}].target_milestone ${split.target_milestone} did not resolve to a file under specs/milestones/ (pass HS-MIL-<id>, the full basename, or "NEW")`,
+        };
+      }
+      targetMilestone = { absent: false, basename: ms.basename };
+    }
+
+    const childCaptureBasenames = [];
+    for (const captureRef of split.sources_captures) {
+      const cap = findCaptureByIdOrBasename(vaultRoot, captureRef);
+      if (!cap) {
+        return {
+          error: 'CAPTURE_NOT_FOUND',
+          message: `splits[${i}].sources_captures entry ${captureRef} did not resolve to a file under specs/captures/`,
+        };
+      }
+      if (!originalCaptureBasenames.includes(cap.basename)) {
+        return {
+          error: 'CAPTURE_NOT_IN_ORIGINAL',
+          message: `splits[${i}].sources_captures entry ${cap.basename} is not present in the original research's sources_captures (subset requirement per /hs-split-research §4 — children inherit a subset of the original's captures)`,
+        };
+      }
+      childCaptureBasenames.push(cap.basename);
+    }
+
+    // Family inheritance (owner ruling 2026-07-12) — see block comment above
+    // inheritedFamilyKey. Every child inherits the ORIGINAL's family key
+    // unconditionally; a fresh mint only in the defensive edge case where the
+    // original itself has no derivable family (should not occur for a real
+    // research doc).
+    const childFamilyKey =
+      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 slug = deriveSlug(split.name);
+    const basename = `${childId}-${childFamilyKey}-RES-${slug}`;
+
+    childRecords.push({
+      id: childId,
+      fileKey: childFileKey,
+      familyKey: childFamilyKey,
+      basename,
+      name: split.name.trim(),
+      targetMilestone,
+      capturesBasenames: childCaptureBasenames,
+      bodySlice: split.body_slice,
+    });
+
+    for (const capBasename of childCaptureBasenames) {
+      if (!captureChildMap.has(capBasename)) captureChildMap.set(capBasename, []);
+      captureChildMap.get(capBasename).push(basename);
+    }
+  }
+
+  // Stage writes.
+  const now = (deps?.clock ?? isoNow)();
+  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,
+      name: child.name,
+      originalBasename: research.basename,
+      siblingBasenames: childBasenames,
+      targetMilestone: child.targetMilestone,
+      capturesBasenames: child.capturesBasenames,
+      bodySlice: child.bodySlice,
+      now,
+      today,
+      author,
+    });
+    child.unresolvedPlaceholderCount = findUnresolvedResearchPlaceholders(content);
+    writes.push({
+      kind: 'create',
+      absPath: join(vaultRoot, 'specs', 'research', `${child.basename}.md`),
+      content,
+    });
+  }
+
+  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, 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 anyChildStillStub = childRecords.some((c) => c.unresolvedPlaceholderCount > 0);
+
+  return {
+    archive_id: getScalarField(fm.block, 'id') ?? args.research_id,
+    archive_basename: research.basename,
+    archive_path: research.relPath,
+    archive_status_after: getScalarField(fm.block, 'status') ?? 'open',
+    children: childRecords.map((c) => ({
+      id: c.id,
+      basename: c.basename,
+      path: 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
+      // heyspex_promote_research on for this child — surfaced here proactively
+      // ([[HS-DSFO-49G3-DIAG-promote-capture-s-success-response]]).
+      research_still_stub: c.unresolvedPlaceholderCount > 0,
+      unresolved_placeholder_count: c.unresolvedPlaceholderCount,
+    })),
+    writes: 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).
+    warning: undefined,
+    next_step: anyChildStillStub
+      ? 'One or more split children still carry unresolved "_TBD — fill in this section._" ' +
+        'placeholders (inherited from the original research\'s outline) — they are outlines, ' +
+        'not authored findings. Run the /hs-res method against each still-stub child before ' +
+        'calling heyspex_promote_research on it; it will otherwise refuse with RESEARCH_STILL_STUB.'
+      : undefined,
+  };
+}
+
+export const __testables = {
+  validateInputShape,
+  appendToListField,
+  parseListFieldBasenames,
+  getFrontmatterBlock,
+  buildChildResearchContent,
+  buildUpdatedOriginalContent,
+  buildUpdatedCaptureContent,
+  collectOccupiedResearchIds,
+  findResearchByIdLocal,
+  findMilestoneByIdOrBasename,
+  findCaptureByIdOrBasename,
+  inheritedFamilyKey,
+};