nubos-pilot 0.7.0 → 0.7.2

package/lib/handoff.cjs

@@ -0,0 +1,277 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { atomicWriteFileSync, NubosPilotError, projectStateDir } = require('./core.cjs');
+const { milestoneDir, parseMId } = require('./layout.cjs');
+
+const STATUS_ENUM = new Set(['open', 'read', 'acted', 'archived']);
+const AGENT_RE = /^[a-zA-Z0-9_\-\*]+$/;
+
+function _slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'note';
+}
+
+let _lastTs = 0;
+function _isoZ() {
+  const now = Date.now();
+  const adjusted = now > _lastTs ? now : _lastTs + 1;
+  _lastTs = adjusted;
+  return new Date(adjusted).toISOString();
+}
+
+function _genId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+function _handoffsRoot({ milestone, cwd }) {
+  const base = projectStateDir(cwd || process.cwd());
+  if (milestone) {
+    const mNum = typeof milestone === 'string' ? parseMId(milestone) : milestone;
+    return path.join(milestoneDir(mNum, cwd), 'handoffs');
+  }
+  return path.join(base, 'handoffs');
+}
+
+function _validateAgentName(field, value) {
+  if (typeof value !== 'string' || value.length === 0 || !AGENT_RE.test(value)) {
+    throw new NubosPilotError(
+      'handoff-invalid-agent',
+      `${field} must be a non-empty slug (alphanumerics, _, -, or *); got: ${JSON.stringify(value)}`,
+      { field, value },
+    );
+  }
+}
+
+function _buildFilename({ createdAt, from, to, topic, id }) {
+  const stamp = createdAt.replace(/[:.]/g, '-');
+  const slug = _slugify(topic);
+  return stamp + '__' + from + '-to-' + to + '__' + slug + '__' + id + '.md';
+}
+
+function _serialize({ id, from, to, topic, createdAt, milestone, slice, task, status, body }) {
+  const fmLines = [
+    '---',
+    'schema_version: 1',
+    'id: ' + JSON.stringify(id),
+    'from_agent: ' + JSON.stringify(from),
+    'to_agent: ' + JSON.stringify(to),
+    'topic: ' + JSON.stringify(topic),
+    'created_at: ' + JSON.stringify(createdAt),
+    'milestone: ' + (milestone ? JSON.stringify(milestone) : 'null'),
+    'slice: ' + (slice ? JSON.stringify(slice) : 'null'),
+    'task: ' + (task ? JSON.stringify(task) : 'null'),
+    'status: ' + JSON.stringify(status),
+    '---',
+  ];
+  const trimmed = (body || '').replace(/\s+$/, '');
+  return fmLines.join('\n') + '\n\n' + (trimmed.length ? trimmed + '\n' : '');
+}
+
+function writeHandoff(input, cwd) {
+  const o = input || {};
+  _validateAgentName('from', o.from);
+  _validateAgentName('to', o.to);
+  if (typeof o.topic !== 'string' || o.topic.length === 0) {
+    throw new NubosPilotError('handoff-missing-topic', 'topic required (non-empty string)', {});
+  }
+  const status = o.status || 'open';
+  if (!STATUS_ENUM.has(status)) {
+    throw new NubosPilotError(
+      'handoff-invalid-status',
+      `status '${status}' not in [${[...STATUS_ENUM].join(', ')}]`,
+      { status },
+    );
+  }
+
+  const id = _genId();
+  const createdAt = _isoZ();
+  const workingDir = cwd || process.cwd();
+  const dir = _handoffsRoot({ milestone: o.milestone || null, cwd: workingDir });
+  fs.mkdirSync(dir, { recursive: true });
+
+  const filename = _buildFilename({
+    createdAt,
+    from: o.from,
+    to: o.to,
+    topic: o.topic,
+    id,
+  });
+  const target = path.join(dir, filename);
+
+  const content = _serialize({
+    id,
+    from: o.from,
+    to: o.to,
+    topic: o.topic,
+    createdAt,
+    milestone: o.milestone || null,
+    slice: o.slice || null,
+    task: o.task || null,
+    status,
+    body: o.body || '',
+  });
+  atomicWriteFileSync(target, content);
+  return { id, path: target, filename, created_at: createdAt };
+}
+
+function _readHandoffFile(filePath) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf-8'); } catch { return null; }
+  let fm;
+  try { ({ frontmatter: fm } = extractFrontmatter(raw)); }
+  catch { return null; }
+  if (!fm || typeof fm.id !== 'string') return null;
+  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  return { frontmatter: fm, body, path: filePath };
+}
+
+function _listDirs({ milestone, cwd, global }) {
+  const dirs = [];
+  const working = cwd || process.cwd();
+  if (!global) {
+    if (milestone) {
+      dirs.push(_handoffsRoot({ milestone, cwd: working }));
+    } else {
+      const msRoot = path.join(projectStateDir(working), 'milestones');
+      try {
+        const entries = fs.readdirSync(msRoot, { withFileTypes: true });
+        for (const e of entries) {
+          if (!e.isDirectory()) continue;
+          const hDir = path.join(msRoot, e.name, 'handoffs');
+          dirs.push(hDir);
+        }
+      } catch {}
+    }
+  }
+  dirs.push(_handoffsRoot({ milestone: null, cwd: working }));
+  return dirs;
+}
+
+function listHandoffs(opts, cwd) {
+  const o = opts || {};
+  const forAgent = o.for || null;
+  const status = o.status || null;
+  const milestone = o.milestone || null;
+  const onlyGlobal = Boolean(o.global);
+
+  if (forAgent) _validateAgentName('for', forAgent);
+  if (status && !STATUS_ENUM.has(status)) {
+    throw new NubosPilotError(
+      'handoff-invalid-status',
+      `status '${status}' not in [${[...STATUS_ENUM].join(', ')}]`,
+      { status },
+    );
+  }
+
+  const out = [];
+  const seen = new Set();
+  const dirs = _listDirs({ milestone, cwd, global: onlyGlobal });
+  for (const dir of dirs) {
+    let entries;
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+    for (const name of entries) {
+      if (!name.endsWith('.md')) continue;
+      const filePath = path.join(dir, name);
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      const rec = _readHandoffFile(filePath);
+      if (!rec) continue;
+      const fm = rec.frontmatter;
+      if (forAgent && fm.to_agent !== forAgent && fm.to_agent !== '*') continue;
+      if (status && fm.status !== status) continue;
+      out.push({
+        id: String(fm.id),
+        from_agent: fm.from_agent,
+        to_agent: fm.to_agent,
+        topic: fm.topic,
+        created_at: fm.created_at,
+        milestone: fm.milestone === 'null' ? null : fm.milestone,
+        slice: fm.slice === 'null' ? null : fm.slice,
+        task: fm.task === 'null' ? null : fm.task,
+        status: fm.status,
+        path: filePath,
+      });
+    }
+  }
+  out.sort((a, b) => {
+    const ta = String(a.created_at);
+    const tb = String(b.created_at);
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    const ia = String(a.id);
+    const ib = String(b.id);
+    if (ia !== ib) return ia < ib ? -1 : 1;
+    const pa = String(a.path);
+    const pb = String(b.path);
+    if (pa !== pb) return pa < pb ? -1 : 1;
+    return 0;
+  });
+  return out;
+}
+
+function readHandoff(id, cwd) {
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new NubosPilotError('handoff-missing-id', 'id required', {});
+  }
+  const all = listHandoffs({}, cwd);
+  const match = all.find((h) => h.id === id);
+  if (!match) {
+    throw new NubosPilotError('handoff-not-found', `no handoff with id ${id}`, { id });
+  }
+  const rec = _readHandoffFile(match.path);
+  return {
+    id: match.id,
+    from_agent: match.from_agent,
+    to_agent: match.to_agent,
+    topic: match.topic,
+    created_at: match.created_at,
+    milestone: match.milestone,
+    slice: match.slice,
+    task: match.task,
+    status: match.status,
+    body: rec ? rec.body.replace(/^\s+/, '').replace(/\s+$/, '\n') : '',
+    path: match.path,
+  };
+}
+
+function setHandoffStatus(id, newStatus, cwd) {
+  if (!STATUS_ENUM.has(newStatus)) {
+    throw new NubosPilotError(
+      'handoff-invalid-status',
+      `status '${newStatus}' not in [${[...STATUS_ENUM].join(', ')}]`,
+      { newStatus },
+    );
+  }
+  const all = listHandoffs({}, cwd);
+  const match = all.find((h) => h.id === id);
+  if (!match) {
+    throw new NubosPilotError('handoff-not-found', `no handoff with id ${id}`, { id });
+  }
+  const raw = fs.readFileSync(match.path, 'utf-8');
+  const fmMatch = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/);
+  if (!fmMatch) {
+    throw new NubosPilotError('handoff-frontmatter-missing', 'handoff file has no YAML frontmatter', { id });
+  }
+  const [, openFence, fmBody, closeFence] = fmMatch;
+  if (!/^status:\s*.*$/m.test(fmBody)) {
+    throw new NubosPilotError('handoff-status-line-missing', 'frontmatter has no status field', { id });
+  }
+  const newFmBody = fmBody.replace(/^status:\s*.*$/m, 'status: ' + newStatus);
+  const rest = raw.slice(fmMatch[0].length);
+  atomicWriteFileSync(match.path, openFence + newFmBody + closeFence + rest);
+  return newStatus;
+}
+
+module.exports = {
+  writeHandoff,
+  listHandoffs,
+  readHandoff,
+  setHandoffStatus,
+  STATUS_ENUM,
+};

package/lib/handoff.test.cjs

@@ -0,0 +1,227 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const handoff = require('./handoff.cjs');
+
+function _sandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-handoff-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'milestones', 'M001'), { recursive: true });
+  return root;
+}
+
+test('HO-1: writeHandoff creates a file with correct frontmatter and returns id', () => {
+  const root = _sandbox();
+  try {
+    const res = handoff.writeHandoff({
+      from: 'np-executor',
+      to: 'np-verifier',
+      topic: 'Feature Flag X',
+      milestone: 'M001',
+      slice: 'M001-S002',
+      body: 'I hardcoded the flag for now.',
+    }, root);
+    assert.match(res.id, /^[a-f0-9]{8}$/);
+    assert.ok(fs.existsSync(res.path));
+    assert.match(res.path, /M001\/handoffs\//);
+    const raw = fs.readFileSync(res.path, 'utf-8');
+    assert.match(raw, /from_agent: "?np-executor"?/);
+    assert.match(raw, /to_agent: "?np-verifier"?/);
+    assert.match(raw, /status: "?open"?/);
+    assert.match(raw, /I hardcoded the flag/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-2: writeHandoff without milestone writes under global handoffs/', () => {
+  const root = _sandbox();
+  try {
+    const res = handoff.writeHandoff({
+      from: 'np-researcher',
+      to: '*',
+      topic: 'General finding',
+      body: 'x',
+    }, root);
+    assert.match(res.path, /\.nubos-pilot\/handoffs\//);
+    assert.doesNotMatch(res.path, /milestones\//);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-3: listHandoffs with for-filter returns addressed + broadcast', () => {
+  const root = _sandbox();
+  try {
+    handoff.writeHandoff({ from: 'a', to: 'verifier', topic: 'to-verifier', milestone: 'M001' }, root);
+    handoff.writeHandoff({ from: 'a', to: 'planner', topic: 'to-planner', milestone: 'M001' }, root);
+    handoff.writeHandoff({ from: 'a', to: '*', topic: 'broadcast', milestone: 'M001' }, root);
+    const list = handoff.listHandoffs({ for: 'verifier' }, root);
+    const topics = list.map((h) => h.topic);
+    assert.deepEqual(topics.sort(), ['broadcast', 'to-verifier'].sort());
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-4: listHandoffs with status filter', () => {
+  const root = _sandbox();
+  try {
+    const a = handoff.writeHandoff({ from: 'x', to: 'y', topic: 'one', milestone: 'M001' }, root);
+    handoff.writeHandoff({ from: 'x', to: 'y', topic: 'two', milestone: 'M001' }, root);
+    handoff.setHandoffStatus(a.id, 'acted', root);
+    const open = handoff.listHandoffs({ status: 'open' }, root);
+    const acted = handoff.listHandoffs({ status: 'acted' }, root);
+    assert.equal(open.length, 1);
+    assert.equal(acted.length, 1);
+    assert.equal(open[0].topic, 'two');
+    assert.equal(acted[0].topic, 'one');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-5: setHandoffStatus rewrites status field in place', () => {
+  const root = _sandbox();
+  try {
+    const { id, path: p } = handoff.writeHandoff({ from: 'a', to: 'b', topic: 't', milestone: 'M001' }, root);
+    handoff.setHandoffStatus(id, 'read', root);
+    const raw = fs.readFileSync(p, 'utf-8');
+    assert.match(raw, /status: read/);
+    assert.doesNotMatch(raw, /status: open/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-6: setHandoffStatus rejects invalid status', () => {
+  const root = _sandbox();
+  try {
+    const { id } = handoff.writeHandoff({ from: 'a', to: 'b', topic: 't', milestone: 'M001' }, root);
+    assert.throws(
+      () => handoff.setHandoffStatus(id, 'bogus', root),
+      (err) => err.name === 'NubosPilotError' && err.code === 'handoff-invalid-status',
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-7: setHandoffStatus on missing id throws handoff-not-found', () => {
+  const root = _sandbox();
+  try {
+    assert.throws(
+      () => handoff.setHandoffStatus('deadbeef', 'acted', root),
+      (err) => err.name === 'NubosPilotError' && err.code === 'handoff-not-found',
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-8: readHandoff returns body and metadata for an existing id', () => {
+  const root = _sandbox();
+  try {
+    const body = 'Line one.\nLine two.';
+    const { id } = handoff.writeHandoff({
+      from: 'a',
+      to: 'b',
+      topic: 'x',
+      milestone: 'M001',
+      body,
+    }, root);
+    const rec = handoff.readHandoff(id, root);
+    assert.equal(rec.id, id);
+    assert.equal(rec.topic, 'x');
+    assert.match(rec.body, /Line one\./);
+    assert.match(rec.body, /Line two\./);
+    assert.equal(rec.milestone, 'M001');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-9: writeHandoff validates agent-name format', () => {
+  const root = _sandbox();
+  try {
+    assert.throws(
+      () => handoff.writeHandoff({ from: '', to: 'b', topic: 't' }, root),
+      (err) => err.name === 'NubosPilotError' && err.code === 'handoff-invalid-agent',
+    );
+    assert.throws(
+      () => handoff.writeHandoff({ from: 'a', to: 'has space', topic: 't' }, root),
+      (err) => err.name === 'NubosPilotError' && err.code === 'handoff-invalid-agent',
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-10: writeHandoff requires topic', () => {
+  const root = _sandbox();
+  try {
+    assert.throws(
+      () => handoff.writeHandoff({ from: 'a', to: 'b', topic: '' }, root),
+      (err) => err.name === 'NubosPilotError' && err.code === 'handoff-missing-topic',
+    );
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-11: listHandoffs without milestone scans all milestones + global', () => {
+  const root = _sandbox();
+  try {
+    fs.mkdirSync(path.join(root, '.nubos-pilot', 'milestones', 'M002'), { recursive: true });
+    handoff.writeHandoff({ from: 'a', to: 'b', topic: 'in-m1', milestone: 'M001' }, root);
+    handoff.writeHandoff({ from: 'a', to: 'b', topic: 'in-m2', milestone: 'M002' }, root);
+    handoff.writeHandoff({ from: 'a', to: 'b', topic: 'global' }, root);
+    const all = handoff.listHandoffs({}, root);
+    const topics = all.map((h) => h.topic).sort();
+    assert.deepEqual(topics, ['global', 'in-m1', 'in-m2']);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-12: listHandoffs with global=true skips milestone scopes', () => {
+  const root = _sandbox();
+  try {
+    handoff.writeHandoff({ from: 'a', to: 'b', topic: 'in-m1', milestone: 'M001' }, root);
+    handoff.writeHandoff({ from: 'a', to: 'b', topic: 'global' }, root);
+    const globals = handoff.listHandoffs({ global: true }, root);
+    assert.equal(globals.length, 1);
+    assert.equal(globals[0].topic, 'global');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-13: listHandoffs sort order is chronological', () => {
+  const root = _sandbox();
+  try {
+    const a = handoff.writeHandoff({ from: 'a', to: 'b', topic: 'first', milestone: 'M001' }, root);
+    const b = handoff.writeHandoff({ from: 'a', to: 'b', topic: 'second', milestone: 'M001' }, root);
+    const list = handoff.listHandoffs({}, root);
+    const order = list.map((h) => h.topic);
+    const firstIdx = order.indexOf('first');
+    const secondIdx = order.indexOf('second');
+    assert.ok(firstIdx !== -1 && secondIdx !== -1);
+    assert.ok(firstIdx < secondIdx, 'first must come before second');
+    assert.ok(a.created_at <= b.created_at);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('HO-14: STATUS_ENUM covers open, read, acted, archived', () => {
+  assert.ok(handoff.STATUS_ENUM.has('open'));
+  assert.ok(handoff.STATUS_ENUM.has('read'));
+  assert.ok(handoff.STATUS_ENUM.has('acted'));
+  assert.ok(handoff.STATUS_ENUM.has('archived'));
+  assert.equal(handoff.STATUS_ENUM.size, 4);
+});

package/lib/tasks.cjs

@@ -305,8 +305,6 @@ function setTaskStatus(taskId, newStatus, cwd = process.cwd()) {
   return withFileLock(filePath, () => {
     const raw = fs.readFileSync(filePath, 'utf-8');
 
-    
-
     const { frontmatter } = extractFrontmatter(raw);
     if (!('status' in frontmatter)) {
       throw new NubosPilotError(
@@ -317,6 +315,19 @@ function setTaskStatus(taskId, newStatus, cwd = process.cwd()) {
     }
     const next = _rewriteStatusLine(raw, newStatus);
     atomicWriteFileSync(filePath, next);
+
+    const sliceFullId = typeof frontmatter.slice === 'string' ? frontmatter.slice : null;
+    if (sliceFullId) {
+      try {
+        const { renderTodoMd } = require('./todo.cjs');
+        renderTodoMd(sliceFullId, cwd);
+      } catch (err) {
+        process.stderr.write(
+          '[nubos-pilot warn] TODO.md render failed for ' + sliceFullId + ': ' + ((err && err.message) || err) + '\n',
+        );
+      }
+    }
+
     return newStatus;
   });
 }

package/lib/todo.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { atomicWriteFileSync, NubosPilotError } = require('./core.cjs');
+const { parseSliceFullId, sliceDir, listTasks, mId } = require('./layout.cjs');
+
+const STATUS_CHECKBOX = Object.freeze({
+  'pending':      '[ ]',
+  'in-progress':  '[~]',
+  'done':         '[x]',
+  'skipped':      '[-]',
+  'parked':       '[!]',
+});
+
+function _checkbox(status) {
+  return STATUS_CHECKBOX[status] || '[?]';
+}
+
+function _taskNameFromPlan(planPath) {
+  let raw;
+  try { raw = fs.readFileSync(planPath, 'utf-8'); } catch { return null; }
+  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  const lines = body.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(/^#\s+(.+?)\s*$/);
+    if (m) {
+      const header = m[1].trim();
+      const split = header.match(/^\S+\s+—\s+(.+)$/);
+      return split ? split[1].trim() : header;
+    }
+  }
+  return null;
+}
+
+function _nowIsoZ() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function _collectTasks(sliceFullId, cwd) {
+  const { milestone, slice } = parseSliceFullId(sliceFullId);
+  const entries = listTasks(milestone, slice, cwd);
+  const result = [];
+  for (const e of entries) {
+    let raw;
+    try { raw = fs.readFileSync(e.plan_path, 'utf-8'); } catch { continue; }
+    let fm;
+    try { ({ frontmatter: fm } = extractFrontmatter(raw)); }
+    catch { fm = {}; }
+    const status = typeof fm.status === 'string' ? fm.status : 'pending';
+    result.push({
+      id: e.full_id,
+      short_id: e.id,
+      status,
+      name: _taskNameFromPlan(e.plan_path),
+      plan_path: e.plan_path,
+    });
+  }
+  return result;
+}
+
+function _buildContent(sliceFullId, tasks) {
+  const counts = { total: 0, pending: 0, 'in-progress': 0, done: 0, skipped: 0, parked: 0 };
+  for (const t of tasks) {
+    counts.total += 1;
+    if (Object.prototype.hasOwnProperty.call(counts, t.status)) {
+      counts[t.status] += 1;
+    }
+  }
+  const { milestone } = parseSliceFullId(sliceFullId);
+  const fm = [
+    '---',
+    'schema_version: 1',
+    'milestone_id: ' + mId(milestone),
+    'slice_id: ' + sliceFullId,
+    'total: ' + counts.total,
+    'pending: ' + counts.pending,
+    'in_progress: ' + counts['in-progress'],
+    'done: ' + counts.done,
+    'skipped: ' + counts.skipped,
+    'parked: ' + counts.parked,
+    'updated_at: ' + _nowIsoZ(),
+    '---',
+  ].join('\n');
+
+  const heading = '# Slice ' + sliceFullId;
+  let body;
+  if (tasks.length === 0) {
+    body = '_No tasks yet._';
+  } else {
+    const rows = tasks.map((t) => {
+      const name = t.name || '(unnamed)';
+      return '- ' + _checkbox(t.status) + ' **' + t.id + '** — ' + name;
+    });
+    body = rows.join('\n');
+  }
+  return fm + '\n\n' + heading + '\n\n' + body + '\n';
+}
+
+function todoPath(sliceFullId, cwd) {
+  const { milestone, slice } = parseSliceFullId(sliceFullId);
+  return path.join(sliceDir(milestone, slice, cwd || process.cwd()), 'TODO.md');
+}
+
+function renderTodoMd(sliceFullId, cwd) {
+  if (!sliceFullId || typeof sliceFullId !== 'string') {
+    throw new NubosPilotError(
+      'todo-missing-slice-id',
+      'renderTodoMd requires sliceFullId (e.g. M001-S001)',
+      { got: sliceFullId },
+    );
+  }
+  parseSliceFullId(sliceFullId);
+  const workingDir = cwd || process.cwd();
+  const tasks = _collectTasks(sliceFullId, workingDir);
+  const content = _buildContent(sliceFullId, tasks);
+  const target = todoPath(sliceFullId, workingDir);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  atomicWriteFileSync(target, content);
+  return target;
+}
+
+module.exports = {
+  renderTodoMd,
+  todoPath,
+  STATUS_CHECKBOX,
+};