heyspex 0.1.0

package/vendor/heyspex-mcp/defer-spec.mjs

@@ -0,0 +1,527 @@
+/**
+ * Delegation defer — split a claimed task's remainder into a child spec with a
+ * handoff envelope. Spec: [[HS-TASK-1U0Z-hs-defer-mcp-tool-and-slash-command]]
+ * / [[HS-EPIC-YQ5A-delegation-defer-work-from-one-agent-to]].
+ *
+ * Transactional writes (child create + parent update + epic children back-link)
+ * via `commitWrites` from [[./promotion-helpers.mjs]]. Post-write orchestration
+ * (pin on-deck, release claim, WIP ledger) lives in the console route wrapper.
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { allocateRandomVaultId } from '../../scripts/vault-id-lib.mjs';
+import { familyOf, mintFamilyKey, mintFileKey, parseSpecId } from './spec-id-lib.mjs';
+import { yamlScalar } from './yaml-scalar.mjs';
+import {
+  isoNow,
+  deriveSlug,
+  findFileByPrefix,
+  getFrontmatterBlock,
+  getScalarField,
+  parseWikilinkBasename,
+  parseListFieldBasenames,
+  appendToListField,
+  setScalarField,
+  bumpUpdated,
+  appendChangeLogRow,
+  commitWrites,
+} from './promotion-helpers.mjs';
+import {
+  validateHandoffEnvelopeFields,
+} from '../../spex-console/src/lib/indexer/handoff-envelope.mjs';
+
+const VALID_PARENT_STATUSES = new Set(['in_review', 'in_progress']);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Discovery
+// ─────────────────────────────────────────────────────────────────────────────
+
+function findTaskByIdLocal(vaultRoot, taskId) {
+  const dir = join(vaultRoot, 'specs', 'tasks');
+  if (!existsSync(dir)) return null;
+  const direct = findFileByPrefix(dir, taskId);
+  const tryFile = (file) => {
+    const basename = file.replace(/\.md$/, '');
+    const absPath = join(dir, file);
+    return {
+      basename,
+      absPath,
+      relPath: join('specs', 'tasks', file),
+      raw: readFileSync(absPath, 'utf8'),
+    };
+  };
+  if (direct) return tryFile(direct);
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const raw = readFileSync(join(dir, file), 'utf8');
+    const idMatch = raw.match(/^id:\s*(\S+)/m);
+    if (idMatch) {
+      const id = idMatch[1].replace(/^['"]|['"]$/g, '');
+      if (id === taskId) {
+        return tryFile(file);
+      }
+    }
+  }
+  return null;
+}
+
+function findEpicByBasenameLocal(vaultRoot, basename) {
+  const dir = join(vaultRoot, 'specs', 'epics');
+  if (!existsSync(dir)) return null;
+  const file = `${basename}.md`;
+  const absPath = join(dir, file);
+  if (!existsSync(absPath)) {
+    const prefixed = findFileByPrefix(dir, basename.split('-').slice(0, 2).join('-'));
+    if (!prefixed) return null;
+    return {
+      basename: prefixed.replace(/\.md$/, ''),
+      absPath: join(dir, prefixed),
+      raw: readFileSync(join(dir, prefixed), 'utf8'),
+    };
+  }
+  return {
+    basename,
+    absPath,
+    raw: readFileSync(absPath, 'utf8'),
+  };
+}
+
+function collectOccupiedTaskIds(vaultRoot) {
+  const occupied = new Set();
+  const dir = join(vaultRoot, 'specs', 'tasks');
+  if (!existsSync(dir)) return occupied;
+  // Normalize task ids of EITHER ordering to the canonical family-first form so
+  // suffix-collision detection works mid-migration ([[HS-EPIC-DLE3]]).
+  const addTask = (value) => {
+    const p = parseSpecId(value);
+    if (p && p.typeLabel === 'TASK') occupied.add(`HS-${p.familyKey}-TASK`);
+  };
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    addTask(file.replace(/\.md$/i, ''));
+    try {
+      const raw = readFileSync(join(dir, file), 'utf8');
+      const idMatch = raw.match(/^id:\s*(\S+)/m);
+      if (idMatch) addTask(idMatch[1].replace(/^['"]|['"]$/g, ''));
+    } catch {
+      /* skip */
+    }
+  }
+  return occupied;
+}
+
+/**
+ * Idempotent defer lookup — same parent + `handoff_id` returns the existing split child
+ * ([[HS-TASK-W146-defer-idempotency-handoff-id-and-cross-a]]).
+ */
+function findExistingChildByHandoffId(vaultRoot, parentBasename, handoffId) {
+  const needle = String(handoffId ?? '').trim();
+  if (!needle) return null;
+  const dir = join(vaultRoot, 'specs', 'tasks');
+  if (!existsSync(dir)) return null;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const raw = readFileSync(join(dir, file), 'utf8');
+    const fm = getFrontmatterBlock(raw);
+    if (!fm) continue;
+    const splitOf = getScalarField(fm.block, 'split_of');
+    const existingHandoff = getScalarField(fm.block, 'handoff_id');
+    if (!splitOf || !existingHandoff) continue;
+    if (parseWikilinkBasename(splitOf) !== parentBasename) continue;
+    if (String(existingHandoff).trim() !== needle) continue;
+    const idMatch = fm.block.match(/^id:\s*(\S+)/m);
+    const childId = idMatch ? idMatch[1].replace(/^['"]|['"]$/g, '') : null;
+    return {
+      basename: file.replace(/\.md$/, ''),
+      absPath: join(dir, file),
+      relPath: join('specs', 'tasks', file),
+      childId,
+      raw,
+    };
+  }
+  return null;
+}
+
+function nextSplitIndex(vaultRoot, parentBasename) {
+  const dir = join(vaultRoot, 'specs', 'tasks');
+  if (!existsSync(dir)) return 1;
+  let max = 0;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const raw = readFileSync(join(dir, file), 'utf8');
+    const fm = getFrontmatterBlock(raw);
+    if (!fm) continue;
+    const splitOf = getScalarField(fm.block, 'split_of');
+    const splitIndexRaw = getScalarField(fm.block, 'split_index');
+    if (!splitOf || !splitIndexRaw) continue;
+    const target = parseWikilinkBasename(splitOf);
+    if (target !== parentBasename) continue;
+    const idx = Number.parseInt(splitIndexRaw, 10);
+    if (Number.isFinite(idx) && idx > max) max = idx;
+  }
+  return max + 1;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Envelope + content builders
+// ─────────────────────────────────────────────────────────────────────────────
+
+function yamlList(key, items) {
+  if (!items.length) return `${key}: []`;
+  return `${key}:\n${items.map((item) => `  - ${yamlScalar(item)}`).join('\n')}`;
+}
+
+function buildHandoffEnvelopeSection(envelope) {
+  const yamlBlock = [
+    `reason: ${yamlScalar(envelope.reason)}`,
+    yamlList('summary_done', envelope.summary_done),
+    yamlList('remaining', envelope.remaining),
+    yamlList('success_criteria', envelope.success_criteria),
+  ].join('\n');
+  return `## Handoff envelope
+
+\`\`\`yaml
+${yamlBlock}
+\`\`\``;
+}
+
+function buildChildTaskContent({
+  childId,
+  childFileKey,
+  childFamilyKey,
+  childName,
+  parentTask,
+  parentFm,
+  splitIndex,
+  envelope,
+  effort,
+  handoffId,
+  now,
+}) {
+  const slug = deriveSlug(childName);
+  const parentBasename = parentTask.basename;
+  const parentEpicLink = getScalarField(parentFm.block, 'parent') ?? '';
+  const parentMilestoneLink = getScalarField(parentFm.block, 'milestone') ?? '';
+  const kind = getScalarField(parentFm.block, 'kind') ?? 'feature';
+  const requiresUserTesting = getScalarField(parentFm.block, 'requires_user_testing') ?? 'false';
+  const tags = parseListFieldBasenames(parentFm.block, 'tags') ?? ['near-term'];
+  const tagsYaml =
+    tags.length === 0
+      ? 'tags: []'
+      : `tags:\n${tags.map((t) => `  - ${yamlScalar(t)}`).join('\n')}`;
+
+  const summaryLines = [
+    `Continuation of ${getScalarField(parentFm.block, 'name') ?? parentTask.basename} (split ${splitIndex}).`,
+    envelope.reason,
+  ].filter(Boolean);
+
+  const fm = `---
+id: ${childId}
+file_id: ${childFileKey}
+family: ${childFamilyKey}
+name: ${yamlScalar(childName)}
+type: task
+status: open
+kind: ${yamlScalar(kind)}
+effort: ${effort}
+owner: ${yamlScalar(getScalarField(parentFm.block, 'owner') ?? 'pwher')}
+parent: '${parentEpicLink}'
+milestone: '${parentMilestoneLink}'
+requires_user_testing: ${requiresUserTesting}
+summary: |-
+  ${summaryLines.map((l) => `  ${l}`).join('\n')}
+${tagsYaml}
+split_of: '[[${parentBasename}]]'
+split_index: ${splitIndex}${handoffId ? `\nhandoff_id: ${yamlScalar(handoffId)}` : ''}
+created: '${now}'
+updated: '${now}'
+---
+`;
+
+  const scopeItems = envelope.remaining.map((line) => `- ${line}`).join('\n');
+  const body = `## Scope
+
+Deferred remainder from [[${parentBasename}]]:
+
+${scopeItems}
+
+${buildHandoffEnvelopeSection(envelope)}
+
+## Acceptance criteria
+
+${envelope.success_criteria.map((c, i) => `${i + 1}. ${c}`).join('\n')}
+`;
+
+  return fm + body;
+}
+
+function ensureSplitSection(body, childBasename, splitIndex, reason) {
+  const heading = '## Split';
+  const line = `- Split ${splitIndex}: [[${childBasename}]] — ${reason}`;
+  if (!body.match(/^## Split\s*$/im)) {
+    return `${body.replace(/\s*$/, '')}\n\n${heading}\n\n${line}\n`;
+  }
+  if (body.includes(`[[${childBasename}]]`)) return body;
+  const idx = body.search(/^## Split\s*$/im);
+  const afterHeading = body.indexOf('\n', idx) + 1;
+  return `${body.slice(0, afterHeading)}${line}\n${body.slice(afterHeading)}`;
+}
+
+function buildUpdatedParentContent(parentRaw, { childBasename, splitIndex, parentStatus, reason, now, author }) {
+  const fm = getFrontmatterBlock(parentRaw);
+  if (!fm) return { changed: false, content: parentRaw };
+
+  let block = fm.block;
+  if (parentStatus && getScalarField(block, 'status') !== parentStatus) {
+    block = setScalarField(block, 'status', parentStatus);
+  }
+  block = bumpUpdated(block, now);
+
+  let body = fm.body;
+  body = ensureSplitSection(body, childBasename, splitIndex, reason);
+  body = appendChangeLogRow(body, now.slice(0, 10), author, `Deferred remainder → [[${childBasename}]] (split ${splitIndex})`);
+
+  return {
+    changed: true,
+    content: `${fm.open}${block}${fm.close}${body}`,
+  };
+}
+
+function buildUpdatedEpicContent(epicRaw, childBasename) {
+  const fm = getFrontmatterBlock(epicRaw);
+  if (!fm) return { changed: false, content: epicRaw };
+  const appended = appendToListField(fm.block, 'children', childBasename);
+  if (!appended.changed) return { changed: false, content: epicRaw };
+  return {
+    changed: true,
+    content: `${fm.open}${appended.block}${fm.close}${fm.body}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function validateInputShape(args) {
+  if (!args || typeof args !== 'object') {
+    return { error: 'INVALID_ARGS', message: 'args must be an object' };
+  }
+  const parsedSpecId = typeof args.spec_id === 'string' ? parseSpecId(args.spec_id) : null;
+  if (!parsedSpecId || parsedSpecId.typeLabel !== 'TASK') {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'spec_id must be a task id (HS-<key>-TASK or legacy HS-TASK-<key>)',
+    };
+  }
+  const envelope = {
+    reason: typeof args.reason === 'string' ? args.reason.trim() : '',
+    summary_done: Array.isArray(args.summary_done) ? args.summary_done.map(String).filter((s) => s.trim()) : [],
+    remaining: Array.isArray(args.remaining) ? args.remaining.map(String).filter((s) => s.trim()) : [],
+    success_criteria: Array.isArray(args.success_criteria)
+      ? args.success_criteria.map(String).filter((s) => s.trim())
+      : [],
+  };
+  const findings = validateHandoffEnvelopeFields(envelope);
+  if (findings.length > 0) {
+    return {
+      error: 'INVALID_ENVELOPE',
+      message: findings.map((f) => f.message).join('; '),
+      findings,
+    };
+  }
+  if (
+    args.parent_status !== undefined &&
+    args.parent_status !== null &&
+    !VALID_PARENT_STATUSES.has(String(args.parent_status))
+  ) {
+    return {
+      error: 'INVALID_ARGS',
+      message: 'parent_status must be "in_review" or "in_progress" when provided',
+    };
+  }
+  if (args.effort !== undefined && args.effort !== null) {
+    const effort = Number(args.effort);
+    if (!Number.isFinite(effort) || effort < 1) {
+      return { error: 'INVALID_ARGS', message: 'effort must be a positive number when provided' };
+    }
+  }
+  const handoffId =
+    typeof args.handoff_id === 'string' && args.handoff_id.trim() ? args.handoff_id.trim() : null;
+  if (handoffId !== null && handoffId.length === 0) {
+    return { error: 'INVALID_ARGS', message: 'handoff_id must be a non-empty string when provided' };
+  }
+  return { envelope, handoffId };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Execute
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * @param {string} vaultRoot repo root (parent of specs/)
+ * @param {object} args
+ * @param {object} [deps]
+ */
+export async function executeDeferSpec(vaultRoot, args = {}, deps = {}) {
+  const shape = validateInputShape(args);
+  if (shape.error) return shape;
+  const envelope = shape.envelope;
+  const handoffId = shape.handoffId ?? null;
+
+  const parent = findTaskByIdLocal(vaultRoot, args.spec_id);
+  if (!parent) {
+    return { error: 'TASK_NOT_FOUND', message: `task ${args.spec_id} not found under specs/tasks/` };
+  }
+
+  if (handoffId) {
+    const existing = findExistingChildByHandoffId(vaultRoot, parent.basename, handoffId);
+    if (existing) {
+      const existingFm = getFrontmatterBlock(existing.raw);
+      const existingId =
+        existing.childId ??
+        (existingFm ? getScalarField(existingFm.block, 'id')?.replace(/^['"]|['"]$/g, '') : null);
+      return {
+        ok: true,
+        idempotent: true,
+        parent_id: args.spec_id,
+        parent_basename: parent.basename,
+        parent_status: getScalarField(getFrontmatterBlock(parent.raw)?.block ?? '', 'status') ?? 'open',
+        child_id: existingId ?? existing.basename,
+        child_basename: existing.basename,
+        child_path: existing.relPath,
+        split_index: existingFm ? Number.parseInt(getScalarField(existingFm.block, 'split_index') ?? '1', 10) : 1,
+        epic_id: null,
+        envelope,
+        handoff_id: handoffId,
+      };
+    }
+  }
+
+  const parentFm = getFrontmatterBlock(parent.raw);
+  if (!parentFm) {
+    return { error: 'INVALID_PARENT', message: 'parent task has no frontmatter block' };
+  }
+
+  const parentStatus = args.parent_status ?? 'in_review';
+  const effort =
+    args.effort !== undefined && args.effort !== null
+      ? Number(args.effort)
+      : Number.parseInt(getScalarField(parentFm.block, 'effort') ?? '3', 10) || 3;
+
+  const parentName = getScalarField(parentFm.block, 'name') ?? parent.basename;
+  const childName =
+    typeof args.child_name === 'string' && args.child_name.trim()
+      ? args.child_name.trim()
+      : `${parentName.replace(/^['"]|['"]$/g, '')} (continued)`;
+
+  const splitIndex = nextSplitIndex(vaultRoot, parent.basename);
+  const now = (deps?.clock ?? isoNow)();
+  const author = typeof args.author === 'string' && args.author.trim() ? args.author.trim() : 'defer-spec (agent)';
+
+  // Era-3 family inheritance ([[naming-v3-7-rulings-hs-namespace-kept]]): the
+  // split child inherits the PARENT task's family (familyOf: explicit
+  // `family:` frontmatter wins, else positional from id/basename). The legacy
+  // allocator's `HS-<family>-TASK` draw is only the defensive fallback family
+  // source; `id:` keys onto the file key alone.
+  const parentIdValue = getScalarField(parentFm.block, 'id')?.replace(/^['"]|['"]$/g, '') ?? null;
+  const parentFamilyValue = getScalarField(parentFm.block, 'family')?.replace(/^['"]|['"]$/g, '') ?? null;
+  const childFamilyKey =
+    familyOf({
+      id: parentIdValue,
+      basename: parent.basename,
+      frontmatter: { family: parentFamilyValue },
+    }) ??
+    parseSpecId(
+      allocateRandomVaultId('task', collectOccupiedTaskIds(vaultRoot), { randomUnit: deps?.randomUnit }),
+    )?.familyKey ??
+    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.
+  const childFileKey = mintFileKey(vaultRoot, { randomUnit: deps?.randomUnit });
+  const childId = `HS-${childFileKey}`;
+  const childSlug = deriveSlug(childName);
+  const childBasename = `${childId}-${childFamilyKey}-TASK-${childSlug}`;
+  const childAbsPath = join(vaultRoot, 'specs', 'tasks', `${childBasename}.md`);
+
+  const writes = [];
+  writes.push({
+    kind: 'create',
+    absPath: childAbsPath,
+    content: buildChildTaskContent({
+      childId,
+      childFileKey,
+      childFamilyKey,
+      childName,
+      parentTask: parent,
+      parentFm,
+      splitIndex,
+      envelope,
+      effort,
+      handoffId,
+      now,
+    }),
+  });
+
+  const parentUpdate = buildUpdatedParentContent(parent.raw, {
+    childBasename,
+    splitIndex,
+    parentStatus,
+    reason: envelope.reason,
+    now,
+    author,
+  });
+  if (parentUpdate.changed) {
+    writes.push({ kind: 'update', absPath: parent.absPath, content: parentUpdate.content });
+  }
+
+  const epicLink = getScalarField(parentFm.block, 'parent');
+  const epicBasename = epicLink ? parseWikilinkBasename(epicLink) : null;
+  let epicBasenameResolved = epicBasename;
+  if (epicBasename) {
+    const epic = findEpicByBasenameLocal(vaultRoot, epicBasename);
+    if (epic) {
+      epicBasenameResolved = epic.basename;
+      const epicUpdate = buildUpdatedEpicContent(epic.raw, childBasename);
+      if (epicUpdate.changed) {
+        writes.push({ kind: 'update', absPath: epic.absPath, content: epicUpdate.content });
+      }
+    }
+  }
+
+  const commitResult = commitWrites(writes);
+  if (!commitResult.ok) {
+    return {
+      error: 'WRITE_FAILED',
+      message: commitResult.error?.message ?? 'unknown write failure',
+      rollback_error: commitResult.error?.rollbackError,
+    };
+  }
+
+  return {
+    ok: true,
+    parent_id: args.spec_id,
+    parent_basename: parent.basename,
+    parent_status: parentStatus,
+    child_id: childId,
+    child_basename: childBasename,
+    child_path: join('specs', 'tasks', `${childBasename}.md`),
+    split_index: splitIndex,
+    epic_id: epicBasenameResolved,
+    envelope,
+    handoff_id: handoffId,
+    writes: writes.map((w) => ({ kind: w.kind, path: w.absPath })),
+  };
+}
+
+export const __testables = {
+  validateInputShape,
+  findTaskByIdLocal,
+  findExistingChildByHandoffId,
+  nextSplitIndex,
+  buildHandoffEnvelopeSection,
+  buildChildTaskContent,
+  buildUpdatedParentContent,
+  ensureSplitSection,
+};