nubos-pilot 0.1.0

package/lib/tasks.cjs

@@ -0,0 +1,327 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { NubosPilotError, withFileLock, atomicWriteFileSync } = require('./core.cjs');
+
+const TASK_REQUIRED_FIELDS = [
+  'id',
+  'phase',
+  'plan',
+  'type',
+  'status',
+  'tier',
+  'owner',
+  'wave',
+  'depends_on',
+  'files_modified',
+  'autonomous',
+  'must_haves',
+];
+
+const TASK_STATUS_ENUM = new Set(['pending', 'in-progress', 'done', 'skipped', 'parked']);
+const TASK_TIER_ENUM = new Set(['haiku', 'sonnet', 'opus']);
+const TASK_ID_RE = /^\d{2}-\d{2}-T\d{2}$/;
+
+function _isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function validateTaskFrontmatter(fm, taskId) {
+  if (!_isPlainObject(fm)) {
+    throw new NubosPilotError(
+      'tasks-invalid-frontmatter',
+      `Task ${taskId} frontmatter must be an object`,
+      { task: taskId, missing: TASK_REQUIRED_FIELDS.slice(), wrong_type: [] },
+    );
+  }
+  const missing = [];
+  const wrongType = [];
+  for (const field of TASK_REQUIRED_FIELDS) {
+    if (!(field in fm)) {
+      missing.push(field);
+    }
+  }
+  if ('depends_on' in fm && !Array.isArray(fm.depends_on)) wrongType.push('depends_on');
+  if ('files_modified' in fm && !Array.isArray(fm.files_modified)) wrongType.push('files_modified');
+  if ('autonomous' in fm && typeof fm.autonomous !== 'boolean') wrongType.push('autonomous');
+  if ('wave' in fm && fm.wave !== null && typeof fm.wave !== 'number') wrongType.push('wave');
+  if ('must_haves' in fm && !_isPlainObject(fm.must_haves)) wrongType.push('must_haves');
+
+  if (missing.length > 0 || wrongType.length > 0) {
+    throw new NubosPilotError(
+      'tasks-invalid-frontmatter',
+      `Task ${taskId} frontmatter invalid (missing: [${missing.join(', ')}], wrong_type: [${wrongType.join(', ')}])`,
+      { task: taskId, missing, wrong_type: wrongType },
+    );
+  }
+
+  if ('id' in fm && !TASK_ID_RE.test(String(fm.id))) {
+    throw new NubosPilotError(
+      'tasks-invalid-frontmatter',
+      `Task ${taskId} has invalid id format '${fm.id}' (expected <plan-id>-T<NN>, e.g. 04-01-T03)`,
+      { task: taskId, field: 'id', got: fm.id, expected: '<plan-id>-T<NN>' },
+    );
+  }
+  if ('status' in fm && !TASK_STATUS_ENUM.has(fm.status)) {
+    throw new NubosPilotError(
+      'tasks-invalid-status',
+      `Task ${taskId} has invalid status '${fm.status}'`,
+      { task: taskId, got: fm.status, allowed: [...TASK_STATUS_ENUM] },
+    );
+  }
+  if ('tier' in fm && !TASK_TIER_ENUM.has(fm.tier)) {
+    throw new NubosPilotError(
+      'tasks-invalid-tier',
+      `Task ${taskId} has invalid tier '${fm.tier}'`,
+      { task: taskId, got: fm.tier, allowed: [...TASK_TIER_ENUM] },
+    );
+  }
+  if ('owner' in fm && (typeof fm.owner !== 'string' || fm.owner.length === 0)) {
+    throw new NubosPilotError(
+      'tasks-invalid-owner',
+      `Task ${taskId} has invalid owner (must be non-empty string)`,
+      { task: taskId, got: fm.owner },
+    );
+  }
+}
+
+function _extractCycle(remaining, children) {
+  const remainingSet = remaining instanceof Set ? remaining : new Set(remaining);
+  if (remainingSet.size === 0) return [];
+  const start = [...remainingSet].sort()[0];
+  const path = [];
+  const onPath = new Set();
+
+  function visit(node) {
+    path.push(node);
+    onPath.add(node);
+    const kids = children.get(node) || [];
+    const sortedKids = [...kids].sort();
+    for (const k of sortedKids) {
+      if (!remainingSet.has(k)) continue;
+      if (onPath.has(k)) {
+        const idx = path.indexOf(k);
+        return path.slice(idx).concat(k);
+      }
+      const result = visit(k);
+      if (result) return result;
+    }
+    path.pop();
+    onPath.delete(node);
+    return null;
+  }
+
+  const result = visit(start);
+  if (result) return result;
+  return path.length > 0 ? path.slice() : [start];
+}
+
+function computeWaves(tasks) {
+  const idSet = new Set(tasks.map((t) => t.id));
+
+  for (const t of tasks) {
+    const deps = t.depends_on || [];
+    for (const dep of deps) {
+      if (!idSet.has(dep)) {
+        throw new NubosPilotError(
+          'tasks-unknown-dep',
+          `Task ${t.id} depends on unknown task ${dep}`,
+          { task: t.id, missing_dep: dep },
+        );
+      }
+    }
+  }
+
+  const indeg = new Map();
+  const children = new Map();
+  for (const t of tasks) {
+    indeg.set(t.id, (t.depends_on || []).length);
+    children.set(t.id, []);
+  }
+  for (const t of tasks) {
+    for (const dep of t.depends_on || []) {
+      children.get(dep).push(t.id);
+    }
+  }
+
+  const remaining = new Set(tasks.map((t) => t.id));
+  const wavesById = new Map();
+  const waves = [];
+  let waveNum = 1;
+
+  while (remaining.size > 0) {
+    const layer = [...remaining].filter((id) => indeg.get(id) === 0).sort();
+    if (layer.length === 0) {
+      const cycle = _extractCycle(remaining, children);
+      throw new NubosPilotError(
+        'tasks-cyclic',
+        `Cycle detected in task graph: ${cycle.join(' -> ')}`,
+        { cycle },
+      );
+    }
+    for (const id of layer) {
+      wavesById.set(id, waveNum);
+      for (const child of children.get(id) || []) {
+        indeg.set(child, indeg.get(child) - 1);
+      }
+      remaining.delete(id);
+    }
+    waves.push(layer);
+    waveNum += 1;
+  }
+
+  const warnings = [];
+  for (const t of tasks) {
+    if (t.wave != null && typeof t.wave === 'number') {
+      const computed = wavesById.get(t.id);
+      if (t.wave !== computed) {
+        warnings.push({
+          code: 'wave-override-conflict',
+          task: t.id,
+          user_wave: t.wave,
+          computed_wave: computed,
+        });
+      }
+    }
+  }
+
+  return { waves, wavesById, warnings };
+}
+
+function loadTaskGraph(planDir) {
+  const tasksDir = path.join(planDir, 'tasks');
+  let entries;
+  try {
+    entries = fs.readdirSync(tasksDir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        tasks: [],
+        graph: new Map(),
+        waves: [],
+        wavesById: new Map(),
+        warnings: [],
+        errors: [],
+      };
+    }
+    throw err;
+  }
+
+  const mdFiles = entries.filter((n) => n.endsWith('.md'));
+  mdFiles.sort();
+
+  const taskRecords = [];
+  for (const name of mdFiles) {
+    const absPath = path.join(tasksDir, name);
+    const id = name.slice(0, -3);
+    const raw = fs.readFileSync(absPath, 'utf-8');
+    const { frontmatter } = extractFrontmatter(raw);
+    validateTaskFrontmatter(frontmatter, id);
+    taskRecords.push({ id, frontmatter, path: absPath });
+  }
+
+  const computeInput = taskRecords.map((r) => ({
+    id: r.id,
+    depends_on: r.frontmatter.depends_on || [],
+    wave: r.frontmatter.wave,
+  }));
+
+  const { waves, wavesById, warnings } = computeWaves(computeInput);
+
+  const graph = new Map();
+  for (const r of taskRecords) graph.set(r.id, []);
+  for (const r of taskRecords) {
+    for (const dep of r.frontmatter.depends_on || []) {
+      graph.get(dep).push(r.id);
+    }
+  }
+
+  return {
+    tasks: taskRecords,
+    graph,
+    waves,
+    wavesById,
+    warnings,
+    errors: [],
+  };
+}
+
+function _findTaskFile(taskId, planDir) {
+  const candidate = path.join(planDir, 'tasks', `${taskId}.md`);
+  try {
+    fs.accessSync(candidate, fs.constants.F_OK);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+function _rewriteStatusLine(raw, newStatus) {
+  const fmMatch = raw.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/);
+  if (!fmMatch) {
+    throw new NubosPilotError(
+      'task-frontmatter-missing',
+      'Task file has no YAML frontmatter block',
+      {},
+    );
+  }
+  const [, openFence, fmBody, closeFence] = fmMatch;
+
+  const statusRe = /^status:\s*.*$/m;
+  if (!statusRe.test(fmBody)) {
+    throw new NubosPilotError(
+      'task-status-line-missing',
+      'Frontmatter does not contain a top-level status: field',
+      {},
+    );
+  }
+  const newFmBody = fmBody.replace(statusRe, `status: ${newStatus}`);
+  const rest = raw.slice(fmMatch[0].length);
+  return openFence + newFmBody + closeFence + rest;
+}
+
+function setTaskStatus(taskId, newStatus, planDir = process.cwd()) {
+  if (!TASK_STATUS_ENUM.has(newStatus)) {
+    throw new NubosPilotError(
+      'invalid-task-status',
+      `Status '${newStatus}' not in enum [${[...TASK_STATUS_ENUM].join(', ')}]`,
+      { taskId, newStatus, allowed: [...TASK_STATUS_ENUM] },
+    );
+  }
+  const filePath = _findTaskFile(taskId, planDir);
+  if (!filePath) {
+    throw new NubosPilotError(
+      'task-not-found',
+      `No task file for id ${taskId} under ${planDir}/tasks/`,
+      { taskId, planDir },
+    );
+  }
+  return withFileLock(filePath, () => {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+
+    
+
+    const { frontmatter } = extractFrontmatter(raw);
+    if (!('status' in frontmatter)) {
+      throw new NubosPilotError(
+        'task-status-line-missing',
+        `Task ${taskId} frontmatter has no status field`,
+        { taskId },
+      );
+    }
+    const next = _rewriteStatusLine(raw, newStatus);
+    atomicWriteFileSync(filePath, next);
+    return newStatus;
+  });
+}
+
+module.exports = {
+  loadTaskGraph,
+  validateTaskFrontmatter,
+  computeWaves,
+  setTaskStatus,
+  TASK_REQUIRED_FIELDS,
+  TASK_STATUS_ENUM,
+  TASK_TIER_ENUM,
+  TASK_ID_RE,
+};

package/lib/tasks.test.cjs

@@ -0,0 +1,389 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const tasks = require('./tasks.cjs');
+
+const FIXTURES = path.join(__dirname, 'fixtures', 'plans');
+
+function validFm(overrides) {
+  return Object.assign({
+    id: '99-01-T01',
+    phase: 99,
+    plan: '01',
+    type: 'execute',
+    status: 'pending',
+    tier: 'sonnet',
+    owner: 'np-executor',
+    wave: 1,
+    depends_on: [],
+    files_modified: [],
+    autonomous: true,
+    must_haves: { truths: ['stub'], artifacts: [], key_links: [] },
+  }, overrides || {});
+}
+
+test('TA-1: validateTaskFrontmatter on complete valid fm does not throw', () => {
+  assert.doesNotThrow(() => tasks.validateTaskFrontmatter(validFm(), 'T-01'));
+});
+
+test('TA-2: missing depends_on throws tasks-invalid-frontmatter with missing field', () => {
+  const fm = validFm();
+  delete fm.depends_on;
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      return err.name === 'NubosPilotError'
+        && err.code === 'tasks-invalid-frontmatter'
+        && Array.isArray(err.details.missing)
+        && err.details.missing.includes('depends_on');
+    },
+  );
+});
+
+test('TA-3: depends_on as string instead of array throws wrong_type', () => {
+  const fm = validFm({ depends_on: 'T-01' });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-02'),
+    (err) => {
+      return err.code === 'tasks-invalid-frontmatter'
+        && Array.isArray(err.details.wrong_type)
+        && err.details.wrong_type.includes('depends_on');
+    },
+  );
+});
+
+test('TA-4: autonomous as string throws tasks-invalid-frontmatter', () => {
+  const fm = validFm({ autonomous: 'true' });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      return err.code === 'tasks-invalid-frontmatter'
+        && Array.isArray(err.details.wrong_type)
+        && err.details.wrong_type.includes('autonomous');
+    },
+  );
+});
+
+test('TA-5: computeWaves linear chain produces three sequential waves', () => {
+  const result = tasks.computeWaves([
+    { id: 'T-01', depends_on: [] },
+    { id: 'T-02', depends_on: ['T-01'] },
+    { id: 'T-03', depends_on: ['T-02'] },
+  ]);
+  assert.deepEqual(result.waves, [['T-01'], ['T-02'], ['T-03']]);
+  assert.equal(result.wavesById.get('T-01'), 1);
+  assert.equal(result.wavesById.get('T-03'), 3);
+  assert.deepEqual(result.warnings, []);
+});
+
+test('TA-6: computeWaves parallel fanout yields two waves with sorted tie-break', () => {
+  const result = tasks.computeWaves([
+    { id: 'T-03', depends_on: ['T-01'] },
+    { id: 'T-01', depends_on: [] },
+    { id: 'T-02', depends_on: ['T-01'] },
+  ]);
+  assert.deepEqual(result.waves, [['T-01'], ['T-02', 'T-03']]);
+});
+
+test('TA-7: computeWaves cycle throws tasks-cyclic with concrete closed cycle', () => {
+  assert.throws(
+    () => tasks.computeWaves([
+      { id: 'T-01', depends_on: ['T-03'] },
+      { id: 'T-02', depends_on: ['T-01'] },
+      { id: 'T-03', depends_on: ['T-02'] },
+    ]),
+    (err) => {
+      return err.code === 'tasks-cyclic'
+        && Array.isArray(err.details.cycle)
+        && err.details.cycle.length >= 3
+        && err.details.cycle[0] === err.details.cycle[err.details.cycle.length - 1];
+    },
+  );
+});
+
+test('TA-8: computeWaves with unknown dep throws tasks-unknown-dep', () => {
+  assert.throws(
+    () => tasks.computeWaves([
+      { id: 'T-01', depends_on: ['T-99'] },
+    ]),
+    (err) => {
+      return err.code === 'tasks-unknown-dep'
+        && err.details.task === 'T-01'
+        && err.details.missing_dep === 'T-99';
+    },
+  );
+});
+
+test('TA-9: computeWaves wave-override-conflict warning emitted (computed wins)', () => {
+  const result = tasks.computeWaves([
+    { id: 'T-01', depends_on: [], wave: 1 },
+    { id: 'T-02', depends_on: ['T-01'], wave: 5 },
+  ]);
+  assert.deepEqual(result.waves, [['T-01'], ['T-02']]);
+  assert.equal(result.warnings.length, 1);
+  const w = result.warnings[0];
+  assert.equal(w.code, 'wave-override-conflict');
+  assert.equal(w.task, 'T-02');
+  assert.equal(w.user_wave, 5);
+  assert.equal(w.computed_wave, 2);
+});
+
+test('TA-10: loadTaskGraph linear fixture returns full graph + waves', () => {
+  const result = tasks.loadTaskGraph(path.join(FIXTURES, 'linear'));
+  assert.equal(result.tasks.length, 3);
+  assert.deepEqual(result.tasks.map((t) => t.id), ['T-01', 'T-02', 'T-03']);
+  assert.deepEqual(result.waves, [['T-01'], ['T-02'], ['T-03']]);
+  assert.deepEqual(result.warnings, []);
+  assert.deepEqual(result.errors, []);
+  assert.ok(result.wavesById instanceof Map);
+});
+
+test('TA-11: loadTaskGraph on plan with no tasks/ dir returns empty result', () => {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-tasks-'));
+  try {
+    const result = tasks.loadTaskGraph(root);
+    assert.deepEqual(result.tasks, []);
+    assert.deepEqual(result.waves, []);
+    assert.deepEqual(result.warnings, []);
+    assert.deepEqual(result.errors, []);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('TA-12: loadTaskGraph cycle fixture throws tasks-cyclic', () => {
+  assert.throws(
+    () => tasks.loadTaskGraph(path.join(FIXTURES, 'cycle')),
+    (err) => err.code === 'tasks-cyclic',
+  );
+});
+
+test('TA-13: loadTaskGraph wave-conflict fixture surfaces override warning', () => {
+  const result = tasks.loadTaskGraph(path.join(FIXTURES, 'wave-conflict'));
+  assert.equal(result.tasks.length, 2);
+  const conflict = result.warnings.find((w) => w.code === 'wave-override-conflict');
+  assert.ok(conflict, 'expected wave-override-conflict warning');
+  assert.equal(conflict.task, 'T-02');
+  assert.equal(conflict.user_wave, 5);
+  assert.equal(conflict.computed_wave, 2);
+});
+
+test('TA-14: task id derived from filename strips .md suffix', () => {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-tasks-'));
+  try {
+    fs.mkdirSync(path.join(root, 'tasks'));
+    const fmBlock =
+      '---\nid: 99-01-T01\nphase: 99\nplan: 01\ntype: execute\nstatus: pending\ntier: sonnet\nowner: executor\nwave: 1\ndepends_on: []\nfiles_modified: []\nautonomous: true\nmust_haves:\n  truths:\n    - "stub"\n  artifacts: []\n  key_links: []\n---\n\nbody\n';
+    fs.writeFileSync(path.join(root, 'tasks', 'T-01.md'), fmBlock);
+    fs.writeFileSync(path.join(root, 'tasks', '99-weird.md'), fmBlock);
+    const result = tasks.loadTaskGraph(root);
+    const ids = result.tasks.map((t) => t.id).sort();
+    assert.deepEqual(ids, ['99-weird', 'T-01']);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('TA-15: computeWaves output is deterministic across runs (sorted tie-break)', () => {
+  const input = [
+    { id: 'T-03', depends_on: ['T-01'] },
+    { id: 'T-02', depends_on: ['T-01'] },
+    { id: 'T-01', depends_on: [] },
+  ];
+  function serialize(r) {
+    return JSON.stringify({
+      waves: r.waves,
+      wavesById: [...r.wavesById.entries()].sort(),
+      warnings: r.warnings,
+    });
+  }
+  const a = serialize(tasks.computeWaves(input));
+  const b = serialize(tasks.computeWaves(input));
+  assert.equal(a, b);
+});
+
+test('TA-16: TASK_REQUIRED_FIELDS exports the D-12 list', () => {
+  assert.ok(Array.isArray(tasks.TASK_REQUIRED_FIELDS));
+  for (const f of ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves']) {
+    assert.ok(tasks.TASK_REQUIRED_FIELDS.includes(f), `missing ${f}`);
+  }
+});
+
+test('TA-17: invalid status throws tasks-invalid-status with allowed enum in details', () => {
+  const fm = validFm({ status: 'bogus' });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      return err.name === 'NubosPilotError'
+        && err.code === 'tasks-invalid-status'
+        && err.details.got === 'bogus'
+        && Array.isArray(err.details.allowed)
+        && err.details.allowed.includes('pending')
+        && err.details.allowed.includes('done');
+    },
+  );
+});
+
+test('TA-18: invalid tier throws tasks-invalid-tier with allowed enum in details', () => {
+  const fm = validFm({ tier: 'gpt' });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      return err.code === 'tasks-invalid-tier'
+        && err.details.got === 'gpt'
+        && Array.isArray(err.details.allowed)
+        && err.details.allowed.includes('sonnet');
+    },
+  );
+});
+
+test('TA-19: empty-string owner throws tasks-invalid-owner', () => {
+  const fm = validFm({ owner: '' });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => err.code === 'tasks-invalid-owner',
+  );
+});
+
+test('TA-20: non-string owner throws tasks-invalid-owner', () => {
+  const fm = validFm({ owner: 42 });
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => err.code === 'tasks-invalid-owner',
+  );
+});
+
+test('TA-21: malformed id throws tasks-invalid-frontmatter with field=id', () => {
+  const fm = validFm({ id: 'T-01' }); 
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      return err.code === 'tasks-invalid-frontmatter'
+        && err.details.field === 'id'
+        && err.details.expected === '<plan-id>-T<NN>';
+    },
+  );
+});
+
+test('TA-22: missing id / status / tier / owner reported as missing fields (tasks-invalid-frontmatter)', () => {
+  const fm = validFm();
+  delete fm.id;
+  delete fm.status;
+  delete fm.tier;
+  delete fm.owner;
+  assert.throws(
+    () => tasks.validateTaskFrontmatter(fm, 'T-01'),
+    (err) => {
+      if (err.code !== 'tasks-invalid-frontmatter') return false;
+      const m = err.details.missing;
+      return Array.isArray(m)
+        && m.includes('id') && m.includes('status')
+        && m.includes('tier') && m.includes('owner');
+    },
+  );
+});
+
+test('TA-23: 12-field round-trip — all fields preserved through validateTaskFrontmatter', () => {
+  const fm = validFm({ id: '04-01-T07', status: 'in-progress', tier: 'opus', owner: 'np-planner' });
+
+  const before = JSON.parse(JSON.stringify(fm));
+  tasks.validateTaskFrontmatter(fm, '04-01-T07'); 
+
+  assert.deepEqual(fm, before);
+
+  for (const f of tasks.TASK_REQUIRED_FIELDS) {
+    assert.ok(f in fm, `field ${f} missing after round-trip`);
+  }
+});
+
+test('TA-24: TASK_REQUIRED_FIELDS exports the full Phase-4 superset', () => {
+  for (const f of ['id', 'status', 'tier', 'owner']) {
+    assert.ok(tasks.TASK_REQUIRED_FIELDS.includes(f), `missing phase-4 field ${f}`);
+  }
+});
+
+const fs6 = require('node:fs');
+const os6 = require('node:os');
+
+function makeTaskFile(planDir, id, status) {
+  const dir = path.join(planDir, 'tasks');
+  fs6.mkdirSync(dir, { recursive: true });
+  const fm = [
+    '---',
+    `id: ${id}`,
+    'phase: 6',
+    "plan: '06-01'",
+    'type: execute',
+    `status: ${status}`,
+    'tier: sonnet',
+    'owner: np-executor',
+    'wave: 1',
+    'depends_on: []',
+    'files_modified: []',
+    'autonomous: true',
+    'must_haves:',
+    '  truths:',
+    '    - "stub"',
+    '  artifacts: []',
+    '  key_links: []',
+    '---',
+    '',
+    'task body',
+    '',
+  ].join('\n');
+  const file = path.join(dir, `${id}.md`);
+  fs6.writeFileSync(file, fm, 'utf-8');
+  return file;
+}
+
+function makePlanSandbox(id, status) {
+  const root = fs6.mkdtempSync(path.join(os6.tmpdir(), 'np-tasks-st-'));
+  makeTaskFile(root, id, status);
+  return root;
+}
+
+test('TA-25: setTaskStatus mutates frontmatter.status and persists round-trip', () => {
+  const planDir = makePlanSandbox('06-01-T01', 'pending');
+  try {
+    tasks.setTaskStatus('06-01-T01', 'done', planDir);
+    const reloaded = tasks.loadTaskGraph(planDir);
+    const t = reloaded.tasks.find((x) => x.id === '06-01-T01');
+    assert.ok(t, 'task must still be findable after status mutation');
+    assert.equal(t.frontmatter.status, 'done');
+  } finally {
+    fs6.rmSync(planDir, { recursive: true, force: true });
+  }
+});
+
+test('TA-26: setTaskStatus rejects out-of-enum status with NubosPilotError', () => {
+  const planDir = makePlanSandbox('06-01-T02', 'pending');
+  try {
+    assert.throws(
+      () => tasks.setTaskStatus('06-01-T02', 'bogus', planDir),
+      (err) => {
+        return err.name === 'NubosPilotError'
+          && err.code === 'invalid-task-status'
+          && err.details.newStatus === 'bogus';
+      },
+    );
+  } finally {
+    fs6.rmSync(planDir, { recursive: true, force: true });
+  }
+});
+
+test('TA-27: setTaskStatus on missing task throws task-not-found', () => {
+  const planDir = makePlanSandbox('06-01-T03', 'pending');
+  try {
+    assert.throws(
+      () => tasks.setTaskStatus('06-01-T99', 'done', planDir),
+      (err) => err.name === 'NubosPilotError' && err.code === 'task-not-found',
+    );
+  } finally {
+    fs6.rmSync(planDir, { recursive: true, force: true });
+  }
+});