@tekyzinc/gsd-t 3.16.12 → 3.18.12

package/bin/spawn-plan-derive.cjs

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * GSD-T Spawn Plan Derive (M44 D8 T4)
+ *
+ * Deterministic projection of `.gsd-t/partition.md` + `.gsd-t/domains/*\/tasks.md`
+ * into the current "incomplete tasks" slice. No LLM calls, no prompts, no
+ * heuristics — just parsing + slicing.
+ *
+ * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
+ *
+ * Consumed by: `bin/spawn-plan-writer.cjs` (when caller does NOT pass an
+ * explicit `tasks: [...]` array).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Derive a `{milestone, wave, domains, tasks}` slice from on-disk partition
+ * + tasks. The "current incomplete slice" is the next contiguous run of
+ * tasks whose checkboxes are still unchecked (`[ ]`) across all domains in
+ * the current wave.
+ *
+ * Gracefully returns an empty slice when partition.md is absent or no
+ * incomplete tasks remain. Never throws for missing files.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {string} [opts.milestone]       filter hint (e.g. 'M44'); defaults to parsed from partition
+ * @param {string|number} [opts.currentIter]   unused today; reserved for future iter-slicing
+ * @returns {{ milestone: string|null, wave: string|null, domains: string[], tasks: Array<{id:string,title:string,status:string}> }}
+ */
+function derivePlanFromPartition(opts) {
+  const projectDir = (opts && opts.projectDir) || '.';
+  const result = { milestone: null, wave: null, domains: [], tasks: [] };
+
+  const partitionPath = path.join(projectDir, '.gsd-t', 'partition.md');
+  if (!fs.existsSync(partitionPath)) {
+    return result;
+  }
+
+  let partitionText;
+  try {
+    partitionText = fs.readFileSync(partitionPath, 'utf8');
+  } catch (_) {
+    return result;
+  }
+
+  // Parse the milestone id (first `M\d+` in heading) and the wave we care
+  // about. For now we pick the first wave with any incomplete tasks.
+  const milestoneMatch = partitionText.match(/\b(M\d+)\b/);
+  if (milestoneMatch) result.milestone = milestoneMatch[1];
+  if (opts && opts.milestone) result.milestone = String(opts.milestone);
+
+  // Enumerate domain dirs under .gsd-t/domains/
+  const domainsRoot = path.join(projectDir, '.gsd-t', 'domains');
+  const domains = _listDomains(domainsRoot, result.milestone);
+  if (!domains.length) return result;
+
+  // Collect incomplete tasks from each domain's tasks.md, grouped by wave.
+  // If no explicit wave header is present, "unknown" groups them.
+  const byWave = new Map();
+  for (const d of domains) {
+    const tasks = _parseTasks(path.join(domainsRoot, d, 'tasks.md'));
+    for (const t of tasks) {
+      if (!byWave.has(t.wave)) byWave.set(t.wave, []);
+      byWave.get(t.wave).push({ ...t, domain: d });
+    }
+  }
+
+  // Pick the wave with the most incomplete tasks; ties: first seen.
+  let pickWave = null;
+  let pickCount = -1;
+  for (const [w, arr] of byWave) {
+    const incomplete = arr.filter((t) => t.status !== 'done').length;
+    if (incomplete > pickCount) {
+      pickCount = incomplete;
+      pickWave = w;
+    }
+  }
+  if (pickWave == null) return result;
+
+  const waveTasks = byWave.get(pickWave) || [];
+  result.wave = pickWave;
+  const seenDomains = new Set();
+  for (const t of waveTasks) {
+    if (t.domain) seenDomains.add(t.domain);
+    result.tasks.push({
+      id: t.id,
+      title: t.title,
+      status: t.status,
+    });
+  }
+  result.domains = [...seenDomains];
+  return result;
+}
+
+// ── internal parsers ──────────────────────────────────────────────────────
+
+function _listDomains(dir, milestone) {
+  if (!fs.existsSync(dir)) return [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return []; }
+  const names = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (milestone) {
+      // Normalize to lowercase m-prefix so we match `m44-d8-…`
+      const prefix = String(milestone).toLowerCase() + '-';
+      if (!e.name.toLowerCase().startsWith(prefix)) continue;
+    }
+    names.push(e.name);
+  }
+  return names.sort();
+}
+
+/**
+ * Parse a domain tasks.md into a list of `{id, title, status, wave}`.
+ * Recognizes:
+ *   `- [ ] **M44-D8-T1** — title…`
+ *   `- [x] **M44-D8-T1** — title…`
+ *   `- [x] done (2026-04-23 · commit abc123) **M44-D8-T1** — title…`
+ * Task-id pattern is `M\d+-D\d+-T\d+`. Wave comes from the nearest
+ * preceding `## Wave N` header.
+ */
+function _parseTasks(tasksPath) {
+  if (!fs.existsSync(tasksPath)) return [];
+  let text;
+  try { text = fs.readFileSync(tasksPath, 'utf8'); } catch (_) { return []; }
+
+  const out = [];
+  let currentWave = 'unknown';
+  const lines = text.split('\n');
+  for (const line of lines) {
+    const waveMatch = line.match(/^##\s+Wave\s+(\d+)\b/i);
+    if (waveMatch) {
+      currentWave = 'wave-' + waveMatch[1];
+      continue;
+    }
+    const m = line.match(/^-\s*\[([ xX])\][^\*]*\*\*(M\d+-D\d+-T\d+)\*\*\s*[—-]\s*(.+)$/);
+    if (!m) continue;
+    const checked = m[1].toLowerCase() === 'x';
+    const id = m[2];
+    let title = m[3].trim();
+    // Strip trailing " — sub-note" if present; keep only the primary title.
+    // The task title may contain em-dashes; safer to just use the first line.
+    title = title.split(/\s{2,}/)[0].trim();
+    out.push({
+      id,
+      title,
+      status: checked ? 'done' : 'pending',
+      wave: currentWave,
+    });
+  }
+  return out;
+}
+
+module.exports = {
+  derivePlanFromPartition,
+  _parseTasks,
+  _listDomains,
+};

package/bin/spawn-plan-status-updater.cjs

@@ -0,0 +1,292 @@
+'use strict';
+
+/**
+ * GSD-T Spawn Plan Status Updater (M44 D8 T2)
+ *
+ * Pure module — patches spawn-plan files written by spawn-plan-writer.cjs.
+ * Called by the post-commit git hook and by `captureSpawn` on completion.
+ *
+ * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
+ *
+ * Hard rules:
+ *   - Atomic rewrites only (temp file + rename)
+ *   - No-op on unknown spawnId or unknown taskId — observability is best-effort
+ *   - Never throw for missing files; callers rely on silent-fail behavior
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SPAWNS_SUBDIR = path.join('.gsd-t', 'spawns');
+
+/**
+ * Patch `{spawnId}.json`: find the task with the given id and flip its
+ * status to `done`, recording the commit SHA and (optional) token
+ * attribution. If the next pending task exists, promote it to
+ * `in_progress` so the single-active-task invariant is preserved.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} opts.taskId
+ * @param {string} [opts.commit]                         short or full SHA
+ * @param {object|null} [opts.tokens]                    `{in,out,cr,cc,cost_usd}` or null
+ * @param {string} [opts.projectDir='.']
+ * @returns {{ patched: boolean, path: string }}
+ */
+function markTaskDone(opts) {
+  if (!opts || typeof opts !== 'object') return { patched: false, path: null };
+  const { spawnId, taskId } = opts;
+  if (!spawnId || !taskId) return { patched: false, path: null };
+
+  const projectDir = opts.projectDir || '.';
+  const fp = _planPath(projectDir, spawnId);
+  const plan = _readPlan(fp);
+  if (!plan) return { patched: false, path: fp };
+
+  const tasks = Array.isArray(plan.tasks) ? plan.tasks : [];
+  const idx = tasks.findIndex((t) => t && t.id === taskId);
+  if (idx < 0) return { patched: false, path: fp };
+
+  const task = tasks[idx];
+  task.status = 'done';
+  if (typeof opts.commit === 'string' && opts.commit) task.commit = opts.commit;
+  // Token attribution is "null when absent" per constraints §Format rules.
+  // The caller passes `null` or an object; we never silently overwrite
+  // an already-populated tokens field with null.
+  if (Object.prototype.hasOwnProperty.call(opts, 'tokens')) {
+    if (opts.tokens && typeof opts.tokens === 'object') {
+      task.tokens = _normalizeTokens(opts.tokens);
+    } else if (task.tokens == null) {
+      task.tokens = null;
+    }
+  }
+
+  // Promote the next pending task to in_progress (single-active invariant).
+  const anyInProgress = tasks.some((t) => t && t.status === 'in_progress');
+  if (!anyInProgress) {
+    for (let j = idx + 1; j < tasks.length; j++) {
+      if (tasks[j] && tasks[j].status === 'pending') {
+        tasks[j].status = 'in_progress';
+        break;
+      }
+    }
+  }
+
+  _atomicWriteJson(fp, plan);
+  return { patched: true, path: fp };
+}
+
+/**
+ * Mark a spawn plan as ended. Sets `endedAt` to now-ISO and records
+ * `endedReason` ('success' | 'error' | caller-supplied). No-op on missing
+ * file. Atomic rewrite.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId
+ * @param {string} [opts.endedReason='success']
+ * @param {string} [opts.projectDir='.']
+ * @param {Date}   [opts.now]
+ * @returns {{ patched: boolean, path: string }}
+ */
+function markSpawnEnded(opts) {
+  if (!opts || typeof opts !== 'object') return { patched: false, path: null };
+  const { spawnId } = opts;
+  if (!spawnId) return { patched: false, path: null };
+
+  const projectDir = opts.projectDir || '.';
+  const fp = _planPath(projectDir, spawnId);
+  const plan = _readPlan(fp);
+  if (!plan) return { patched: false, path: fp };
+
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  plan.endedAt = now.toISOString();
+  plan.endedReason = opts.endedReason || 'success';
+  _atomicWriteJson(fp, plan);
+  return { patched: true, path: fp };
+}
+
+/**
+ * Enumerate active plan files (those where `endedAt === null`). Returns
+ * absolute file paths, sorted by startedAt descending.
+ *
+ * @param {string} [projectDir='.']
+ * @returns {string[]}
+ */
+function listActivePlans(projectDir) {
+  const dir = path.join(projectDir || '.', SPAWNS_SUBDIR);
+  if (!fs.existsSync(dir)) return [];
+  let files;
+  try { files = fs.readdirSync(dir); } catch (_) { return []; }
+  const results = [];
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    const fp = path.resolve(path.join(dir, f));
+    const plan = _readPlan(fp);
+    if (plan && plan.endedAt == null) results.push({ fp, plan });
+  }
+  results.sort((a, b) => {
+    const ta = Date.parse(a.plan && a.plan.startedAt || '') || 0;
+    const tb = Date.parse(b.plan && b.plan.startedAt || '') || 0;
+    return tb - ta;
+  });
+  return results.map((r) => r.fp);
+}
+
+// ── token-log attribution lookup ───────────────────────────────────────────
+
+/**
+ * Parse `.gsd-t/token-log.md` and return the sum of `{in,out,cr,cc,cost_usd}`
+ * across all rows whose `Task` column matches the given id and whose
+ * `Datetime-start` is >= the spawn's startedAt.
+ *
+ * Returns `null` when no matching rows exist (per the "zero is a
+ * measurement, dash is acknowledged gap" rule).
+ *
+ * @param {object} opts
+ * @param {string} opts.projectDir
+ * @param {string} opts.taskId
+ * @param {string} opts.spawnStartedAt   ISO-8601 (matches plan.startedAt)
+ * @param {string} [opts.tokenLogPath]   override for tests
+ * @returns {{in:number, out:number, cr:number, cc:number, cost_usd:number}|null}
+ */
+function sumTokensForTask(opts) {
+  if (!opts || typeof opts !== 'object') return null;
+  const { projectDir, taskId } = opts;
+  if (!projectDir || !taskId) return null;
+
+  const fp = opts.tokenLogPath || path.join(projectDir, '.gsd-t', 'token-log.md');
+  if (!fs.existsSync(fp)) return null;
+
+  const startMs = _parseDatetime(opts.spawnStartedAt);
+
+  let text;
+  try { text = fs.readFileSync(fp, 'utf8'); } catch (_) { return null; }
+
+  const lines = text.split('\n');
+  // Find header row to locate column indices.
+  const headerIdx = lines.findIndex((l) => /^\|\s*Datetime-start\s*\|/.test(l));
+  if (headerIdx < 0) return null;
+  const header = lines[headerIdx].split('|').map((s) => s.trim());
+  const iStart = header.indexOf('Datetime-start');
+  const iTokens = header.indexOf('Tokens');
+  const iTask = header.indexOf('Task');
+  if (iStart < 0 || iTask < 0) return null;
+
+  const sum = { in: 0, out: 0, cr: 0, cc: 0, cost_usd: 0 };
+  let matched = 0;
+  for (let i = headerIdx + 2; i < lines.length; i++) {
+    const row = lines[i];
+    if (!row || !row.startsWith('|')) continue;
+    const cells = row.split('|').map((s) => s.trim());
+    if (cells.length < header.length) continue;
+    const startedAt = cells[iStart] || '';
+    const task = cells[iTask] || '';
+    if (task !== taskId) continue;
+    // Only rows whose Datetime-start >= spawn.startedAt count.
+    if (startMs != null) {
+      const rowMs = _parseDatetime(startedAt);
+      if (rowMs != null && rowMs < startMs) continue;
+    }
+    const tokensCell = iTokens >= 0 ? (cells[iTokens] || '') : '';
+    const parsed = _parseTokensCell(tokensCell);
+    if (parsed) {
+      sum.in += parsed.in;
+      sum.out += parsed.out;
+      sum.cr += parsed.cr;
+      sum.cc += parsed.cc;
+      sum.cost_usd += parsed.cost_usd;
+      matched++;
+    } else {
+      // No token data in the row; still counts as a "match" for the task
+      // but contributes zero. Keep going.
+      matched++;
+    }
+  }
+  if (matched === 0) return null;
+  // Round cost to 2 decimals for determinism.
+  sum.cost_usd = Math.round(sum.cost_usd * 100) / 100;
+  return sum;
+}
+
+// ── internal helpers ───────────────────────────────────────────────────────
+
+function _planPath(projectDir, spawnId) {
+  return path.resolve(path.join(projectDir, SPAWNS_SUBDIR, spawnId + '.json'));
+}
+
+function _readPlan(fp) {
+  try {
+    const raw = fs.readFileSync(fp, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch (_) {
+    return null;
+  }
+}
+
+function _atomicWriteJson(targetPath, obj) {
+  const dir = path.dirname(targetPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const tmp = targetPath + '.tmp-' + process.pid + '-' + Date.now();
+  const json = JSON.stringify(obj, null, 2) + '\n';
+  fs.writeFileSync(tmp, json);
+  fs.renameSync(tmp, targetPath);
+}
+
+function _normalizeTokens(t) {
+  const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : Number(v) || 0);
+  return {
+    in: num(t.in != null ? t.in : t.input_tokens),
+    out: num(t.out != null ? t.out : t.output_tokens),
+    cr: num(t.cr != null ? t.cr : t.cache_read_input_tokens),
+    cc: num(t.cc != null ? t.cc : t.cache_creation_input_tokens),
+    cost_usd: num(
+      t.cost_usd != null
+        ? t.cost_usd
+        : (t.total_cost_usd != null ? t.total_cost_usd : 0)
+    ),
+  };
+}
+
+function _parseDatetime(s) {
+  if (!s) return null;
+  if (typeof s === 'string' && /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/.test(s)) {
+    const [d, t] = s.split(' ');
+    const ms = Date.parse(`${d}T${t}:00`);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  const ms = Date.parse(s);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Parse a tokens cell of the form `in=N out=N cr=N cc=N $X.XX` or `—`
+ * or a mixed form. Returns null when no numeric data is present.
+ */
+function _parseTokensCell(cell) {
+  if (!cell || cell === '—' || cell === '-') return null;
+  const num = (re) => {
+    const m = cell.match(re);
+    return m ? Number(m[1]) : 0;
+  };
+  const inp = num(/\bin=(\d+)/);
+  const out = num(/\bout=(\d+)/);
+  const cr = num(/\bcr=(\d+)/);
+  const cc = num(/\bcc=(\d+)/);
+  const costM = cell.match(/\$(\d+(?:\.\d+)?)/);
+  const cost_usd = costM ? Number(costM[1]) : 0;
+  if (!inp && !out && !cr && !cc && !cost_usd) return null;
+  return { in: inp, out, cr, cc, cost_usd };
+}
+
+module.exports = {
+  markTaskDone,
+  markSpawnEnded,
+  listActivePlans,
+  sumTokensForTask,
+  // test-only
+  _parseTokensCell,
+  _parseDatetime,
+  _normalizeTokens,
+};

package/bin/spawn-plan-writer.cjs

@@ -0,0 +1,204 @@
+'use strict';
+
+/**
+ * GSD-T Spawn Plan Writer (M44 D8 T1)
+ *
+ * Pure module — writes a spawn-plan JSON file under `.gsd-t/spawns/{spawnId}.json`
+ * at every spawn chokepoint (captureSpawn, autoSpawnHeadless, unattended-worker
+ * resume Step 0). The plan file answers exactly one question:
+ *
+ *   "Of the tasks that were supposed to happen in this spawn, which are done,
+ *    which are in flight, which are pending?"
+ *
+ * Hard rules (see .gsd-t/domains/m44-d8-spawn-plan-visibility/constraints.md):
+ *   1. Writer DERIVES, never decides — no LLM calls, no prompts, no heuristics
+ *      beyond reading partition.md + tasks.md.
+ *   2. Spawn must launch even if writer fails — callers wrap in try/catch.
+ *   3. Atomic writes only (temp file + rename).
+ *
+ * Contract: .gsd-t/contracts/spawn-plan-contract.md v1.0.0
+ *
+ * Zero external deps. `.cjs` so it loads in both ESM-default and CJS projects.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SPAWNS_SUBDIR = path.join('.gsd-t', 'spawns');
+const SPAWN_PLAN_SCHEMA_VERSION = 1;
+
+/**
+ * Write a spawn-plan file at `.gsd-t/spawns/{spawnId}.json` using an atomic
+ * temp-file + rename. Creates the `.gsd-t/spawns/` directory and its
+ * `.gitkeep` sentinel if missing.
+ *
+ * If `tasks` or `domains` are not explicitly supplied, the writer tries
+ * to derive them from `.gsd-t/partition.md` + `.gsd-t/domains/*\/tasks.md`
+ * via the companion `spawn-plan-derive.cjs` module. When derivation fails
+ * (no partition file, malformed tasks.md, ENOENT), the writer falls back to
+ * `{tasks: [], note: "no-partition"}` and STILL writes the file — the
+ * observability panel's job is to render whatever is present; never to block.
+ *
+ * @param {object} opts
+ * @param {string} opts.spawnId                       filesystem-safe id
+ * @param {'unattended-worker'|'headless-detached'|'in-session-subagent'} opts.kind
+ * @param {string} [opts.milestone]                   e.g. 'M44'
+ * @param {string} [opts.wave]                        e.g. 'wave-3'
+ * @param {string[]} [opts.domains]                   domain names involved
+ * @param {Array<{id: string, title: string, status?: string}>} [opts.tasks]
+ *                                                    explicit task list
+ *                                                    (bypasses derivation)
+ * @param {string} [opts.projectDir='.']
+ * @param {Date}   [opts.now]                         injection for tests
+ * @returns {string}                                  absolute path written
+ */
+function writeSpawnPlan(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('writeSpawnPlan: opts is required');
+  }
+  const spawnId = _sanitizeSpawnId(opts.spawnId);
+  if (!spawnId) {
+    throw new Error('writeSpawnPlan: spawnId is required and must be filesystem-safe');
+  }
+  const kind = opts.kind || 'in-session-subagent';
+  const projectDir = opts.projectDir || '.';
+  const now = opts.now instanceof Date ? opts.now : new Date();
+
+  const spawnsDir = path.join(projectDir, SPAWNS_SUBDIR);
+  _ensureDir(spawnsDir);
+  _ensureGitkeep(spawnsDir);
+
+  // Derive or accept explicit plan slice. Explicit wins.
+  let plan = _buildPlanSkeleton({ spawnId, kind, now });
+  plan.milestone = opts.milestone || null;
+  plan.wave = opts.wave || null;
+  plan.domains = Array.isArray(opts.domains) ? opts.domains.slice() : [];
+  plan.tasks = Array.isArray(opts.tasks)
+    ? opts.tasks.map(_normalizeTask)
+    : [];
+
+  // Only auto-derive when caller did NOT explicitly supply tasks. A caller
+  // can pass `tasks: []` to bypass derivation too.
+  if (!Array.isArray(opts.tasks)) {
+    try {
+      const derive = require('./spawn-plan-derive.cjs');
+      const derived = derive.derivePlanFromPartition({
+        projectDir,
+        milestone: opts.milestone,
+        currentIter: opts.currentIter,
+      });
+      if (derived && typeof derived === 'object') {
+        if (!plan.milestone && derived.milestone) plan.milestone = derived.milestone;
+        if (!plan.wave && derived.wave) plan.wave = derived.wave;
+        if (!plan.domains.length && Array.isArray(derived.domains)) plan.domains = derived.domains.slice();
+        if (Array.isArray(derived.tasks)) plan.tasks = derived.tasks.map(_normalizeTask);
+      }
+    } catch (err) {
+      // Derivation failures NEVER block the spawn. The plan file still
+      // gets written with `{tasks: [], note: "no-partition"}` shape.
+      plan.note = 'no-partition';
+      try { process.stderr.write(`[spawn-plan-writer] derive failed (continuing): ${err && err.message || err}\n`); } catch (_) { /* silent */ }
+    }
+  }
+
+  // Mark first incomplete task as in_progress if every predecessor is done.
+  // Only one task per spawn may be in_progress at a time (see constraints §Format rules).
+  _applyInProgressHint(plan.tasks);
+
+  const targetPath = path.join(spawnsDir, spawnId + '.json');
+  const absTarget = path.resolve(targetPath);
+  _atomicWriteJson(absTarget, plan);
+  return absTarget;
+}
+
+/**
+ * Return the `.gsd-t/spawns/` directory for the given project.
+ */
+function spawnsDirFor(projectDir) {
+  return path.join(projectDir || '.', SPAWNS_SUBDIR);
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+function _sanitizeSpawnId(id) {
+  if (id == null) return null;
+  const s = String(id);
+  // Filesystem-safe: alphanumerics, dash, underscore, dot. See constraints.md §Format rules.
+  if (!/^[A-Za-z0-9._-]{1,200}$/.test(s)) return null;
+  return s;
+}
+
+function _ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+function _ensureGitkeep(dir) {
+  const gk = path.join(dir, '.gitkeep');
+  if (!fs.existsSync(gk)) {
+    try { fs.writeFileSync(gk, ''); } catch (_) { /* best-effort */ }
+  }
+}
+
+function _buildPlanSkeleton({ spawnId, kind, now }) {
+  return {
+    schemaVersion: SPAWN_PLAN_SCHEMA_VERSION,
+    spawnId,
+    kind,
+    startedAt: now.toISOString(),
+    endedAt: null,
+    milestone: null,
+    wave: null,
+    domains: [],
+    tasks: [],
+    endedReason: null,
+  };
+}
+
+function _normalizeTask(t) {
+  if (!t || typeof t !== 'object') return null;
+  const id = typeof t.id === 'string' ? t.id : null;
+  const title = typeof t.title === 'string' ? t.title : '';
+  const statusIn = typeof t.status === 'string' ? t.status : 'pending';
+  const status = ['pending', 'in_progress', 'done'].includes(statusIn) ? statusIn : 'pending';
+  const normalized = {
+    id,
+    title,
+    status,
+  };
+  if (typeof t.commit === 'string' && t.commit) normalized.commit = t.commit;
+  if (t.tokens && typeof t.tokens === 'object') {
+    normalized.tokens = t.tokens;
+  } else {
+    normalized.tokens = null;
+  }
+  return normalized;
+}
+
+function _applyInProgressHint(tasks) {
+  if (!Array.isArray(tasks) || tasks.length === 0) return;
+  // Already an in_progress? Leave as-is.
+  if (tasks.some((t) => t && t.status === 'in_progress')) return;
+  for (const t of tasks) {
+    if (!t) continue;
+    if (t.status === 'pending') { t.status = 'in_progress'; return; }
+    // Skip already-done; continue to next.
+  }
+}
+
+function _atomicWriteJson(targetPath, obj) {
+  const tmp = targetPath + '.tmp-' + process.pid + '-' + Date.now();
+  const json = JSON.stringify(obj, null, 2) + '\n';
+  fs.writeFileSync(tmp, json);
+  fs.renameSync(tmp, targetPath);
+}
+
+module.exports = {
+  writeSpawnPlan,
+  spawnsDirFor,
+  SPAWN_PLAN_SCHEMA_VERSION,
+  // Exposed for unit-test reach-in only; not part of the public contract.
+  _sanitizeSpawnId,
+  _normalizeTask,
+  _applyInProgressHint,
+  _atomicWriteJson,
+};