nubos-pilot 0.1.0

package/lib/next.cjs

@@ -0,0 +1,236 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { readState } = require('./state.cjs');
+const { parseRoadmap } = require('./roadmap.cjs');
+const { findPhaseDir, paddedPhase } = require('./phase.cjs');
+const { listPlans } = require('./plan.cjs');
+const { loadTaskGraph } = require('./tasks.cjs');
+const { NubosPilotError } = require('./core.cjs');
+
+function _safeReadState(cwd) {
+  try {
+    return readState(cwd);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+
+    if (err && typeof err === 'object' && err.code === 'schema-version-mismatch') throw err;
+
+    if (err && err.code && String(err.code).startsWith('ENOENT')) return null;
+
+    if (err && err.message && /ENOENT/.test(err.message)) return null;
+    throw err;
+  }
+}
+
+function _safeParseRoadmap(cwd) {
+  try {
+    return parseRoadmap(cwd);
+  } catch (err) {
+    if (err && err.code === 'roadmap-parse-error') return null;
+    throw err;
+  }
+}
+
+function _firstPendingPhase(roadmap) {
+  if (!roadmap || !Array.isArray(roadmap.phases) || roadmap.phases.length === 0) return null;
+  for (const p of roadmap.phases) {
+    if (!p.complete) return Number(p.number);
+  }
+  return null;
+}
+
+function _phaseDirFor(n, cwd) {
+  try {
+    return findPhaseDir(n, cwd);
+  } catch (err) {
+    if (err && err.code === 'not-in-project') return null;
+
+    return null;
+  }
+}
+
+function _hasContext(phaseDir, n) {
+  if (!phaseDir) return false;
+  const padded = paddedPhase(n);
+  return fs.existsSync(path.join(phaseDir, padded + '-CONTEXT.md'));
+}
+
+function _hasVerification(phaseDir, n) {
+  if (!phaseDir) return false;
+  const padded = paddedPhase(n);
+  return fs.existsSync(path.join(phaseDir, padded + '-VERIFICATION.md'));
+}
+
+function _phasePlanPaths(phaseDir) {
+  if (!phaseDir) return [];
+  return listPlans(phaseDir);
+}
+
+function _firstPendingTaskPointer(phaseDir) {
+  const plans = _phasePlanPaths(phaseDir);
+  if (plans.length === 0) return null;
+
+  const planDir = path.dirname(plans[0]);
+  let tg;
+  try {
+    tg = loadTaskGraph(planDir);
+  } catch (err) {
+
+    
+    return null;
+  }
+  if (!tg.tasks || tg.tasks.length === 0) return null;
+  if (!tg.waves || tg.waves.length === 0) return null;
+  const firstWaveIds = tg.waves[0];
+  const pendingInWave = firstWaveIds
+    .map((id) => tg.tasks.find((t) => t.id === id))
+    .filter((t) => t && t.frontmatter && t.frontmatter.status !== 'done')
+    .sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id));
+  if (pendingInWave.length === 0) return null;
+  const pick = pendingInWave[0];
+  return {
+    id: pick.frontmatter.id,
+    owner: pick.frontmatter.owner,
+    tier: pick.frontmatter.tier,
+    wave: typeof pick.frontmatter.wave === 'number' ? pick.frontmatter.wave : 1,
+  };
+}
+
+function _allTasksDone(phaseDir) {
+  const plans = _phasePlanPaths(phaseDir);
+  if (plans.length === 0) return false;
+  for (const planPath of plans) {
+    const planDir = path.dirname(planPath);
+    let tg;
+    try { tg = loadTaskGraph(planDir); }
+    catch { return false; }
+    if (!tg.tasks || tg.tasks.length === 0) return false;
+    for (const t of tg.tasks) {
+      if (!t.frontmatter || t.frontmatter.status !== 'done') return false;
+    }
+  }
+  return true;
+}
+
+function resolveGate(phaseN, cwd) {
+  const phaseDir = _phaseDirFor(phaseN, cwd);
+  if (!_hasContext(phaseDir, phaseN)) return { rule: 1 };
+  const plans = _phasePlanPaths(phaseDir);
+  if (plans.length === 0) return { rule: 2 };
+  if (!_allTasksDone(phaseDir)) {
+    const task = _firstPendingTaskPointer(phaseDir);
+    return { rule: 3, task };
+  }
+  if (!_hasVerification(phaseDir, phaseN)) return { rule: 4 };
+  return { rule: 5 };
+}
+
+function _shapeForRule(gate, n) {
+  switch (gate.rule) {
+    case 1:
+      return {
+        next_step: { command: `/np:discuss-phase ${n}`, reason: `Phase ${n} has no CONTEXT.md` },
+        task: null,
+        phase: n,
+        plan: null,
+      };
+    case 2:
+      return {
+        next_step: { command: `/np:plan-phase ${n}`, reason: `Phase ${n} has CONTEXT.md but no PLAN.md yet` },
+        task: null,
+        phase: n,
+        plan: null,
+      };
+    case 3: {
+      const task = gate.task || null;
+      const planFromTask = task && task.id ? task.id.slice(0, 5) : null;
+      return {
+        next_step: { command: `/np:execute-phase ${n}`, reason: `Phase ${n} has pending tasks` },
+        task,
+        phase: n,
+        plan: planFromTask,
+      };
+    }
+    case 4:
+      return {
+        next_step: { command: `/np:verify-work ${n}`, reason: `Phase ${n} tasks all done — awaiting verification` },
+        task: null,
+        phase: n,
+        plan: null,
+      };
+    default:
+      return null;
+  }
+}
+
+function computeNextStep(cwd = process.cwd()) {
+  try {
+    const roadmap = _safeParseRoadmap(cwd);
+
+    if (!roadmap) {
+      return _shapeForRule({ rule: 1 }, 1);
+    }
+
+    
+    let phaseN;
+    const state = _safeReadState(cwd);
+    const cur = state && state.frontmatter ? state.frontmatter.current_phase : null;
+    if (cur != null && Number.isFinite(Number(cur))) {
+      phaseN = Number(cur);
+    } else {
+      const first = _firstPendingPhase(roadmap);
+      if (first == null) {
+
+        return {
+          next_step: { command: '/np:complete-milestone', reason: 'All phases complete' },
+          task: null,
+          phase: null,
+          plan: null,
+        };
+      }
+      phaseN = first;
+    }
+
+    const gate = resolveGate(phaseN, cwd);
+    if (gate.rule !== 5) {
+      return _shapeForRule(gate, phaseN);
+    }
+
+    const idx = roadmap.phases.findIndex((p) => Number(p.number) === phaseN);
+    let nextPending = null;
+    for (let i = idx + 1; i < roadmap.phases.length; i++) {
+      if (!roadmap.phases[i].complete) {
+        nextPending = Number(roadmap.phases[i].number);
+        break;
+      }
+    }
+    if (nextPending == null) {
+      return {
+        next_step: { command: '/np:complete-milestone', reason: 'All phases complete' },
+        task: null,
+        phase: null,
+        plan: null,
+      };
+    }
+
+    const gate2 = resolveGate(nextPending, cwd);
+    if (gate2.rule === 5) {
+
+      
+      return {
+        next_step: { command: `/np:plan-phase ${nextPending}`, reason: 'Next phase ready for planning' },
+        task: null, phase: nextPending, plan: null,
+      };
+    }
+    return _shapeForRule(gate2, nextPending);
+  } catch (err) {
+    if (err && err.code) throw err;
+    throw new NubosPilotError(
+      'next-internal-error',
+      `computeNextStep failed: ${err && err.message}`,
+      { cause: err && err.message },
+    );
+  }
+}
+
+module.exports = { computeNextStep, resolveGate };

package/lib/next.test.cjs

@@ -0,0 +1,194 @@
+const { test, afterEach } = 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 next = require('./next.cjs');
+
+const sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-next-test-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'));
+  sandboxes.push(root);
+  return root;
+}
+
+function writeState(root, fm) {
+  const lines = ['---'];
+  for (const k of Object.keys(fm)) {
+    const v = fm[k];
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      lines.push(`${k}:`);
+      for (const nk of Object.keys(v)) lines.push(`  ${nk}: ${v[nk] == null ? 'null' : v[nk]}`);
+    } else {
+      lines.push(`${k}: ${v == null ? 'null' : v}`);
+    }
+  }
+  lines.push('---', '', '');
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), lines.join('\n'));
+}
+
+function writeRoadmap(root, phases) {
+  const ms = {
+    schema_version: 1,
+    milestones: [{ id: 'v1.0', name: 'milestone', phases }],
+  };
+  const YAML = require('yaml');
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'roadmap.yaml'), YAML.stringify(ms, { indent: 2 }));
+}
+
+function mkPhase(root, n, slug, { context = false, plan = false, tasks = null, verification = false } = {}) {
+  const padded = String(n).padStart(2, '0');
+  const dir = path.join(root, '.nubos-pilot', 'phases', padded + '-' + slug);
+  fs.mkdirSync(dir, { recursive: true });
+  if (context) fs.writeFileSync(path.join(dir, padded + '-CONTEXT.md'), '# ctx\n');
+  if (plan) fs.writeFileSync(path.join(dir, padded + '-01-PLAN.md'), '---\nphase: ' + n + '\nplan: "' + padded + '-01"\n---\nbody\n');
+  if (verification) fs.writeFileSync(path.join(dir, padded + '-VERIFICATION.md'), '# verify\n');
+  if (tasks) {
+    const tdir = path.join(dir, 'tasks');
+    fs.mkdirSync(tdir, { recursive: true });
+    for (const t of tasks) {
+      const body =
+        '---\n' +
+        `id: ${padded}-01-T${String(t.num).padStart(2, '0')}\n` +
+        `status: ${t.status || 'pending'}\n` +
+        'tier: sonnet\n' +
+        'owner: np-executor\n' +
+        `phase: ${n}\n` +
+        `plan: ${padded}-01\n` +
+        'type: execute\n' +
+        `wave: ${t.wave || 1}\n` +
+        `depends_on: ${t.depends_on ? JSON.stringify(t.depends_on) : '[]'}\n` +
+        'files_modified: []\n' +
+        'autonomous: true\n' +
+        'must_haves:\n  truths: []\n  artifacts: []\n  key_links: []\n' +
+        '---\nbody\n';
+      fs.writeFileSync(path.join(tdir, `T-${String(t.num).padStart(2, '0')}.md`), body);
+    }
+  }
+  return dir;
+}
+
+afterEach(() => {
+  while (sandboxes.length) {
+    const p = sandboxes.pop();
+    try { fs.rmSync(p, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('N1 (rule 1): phase missing CONTEXT.md → discuss-phase', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [{ number: 1, name: 'Foundation', slug: 'foundation', status: 'pending' }]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:discuss-phase 1');
+  assert.equal(out.task, null);
+  assert.equal(out.phase, 1);
+});
+
+test('N2 (rule 2): CONTEXT.md exists but no PLAN.md → plan-phase', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [{ number: 1, name: 'Foundation', slug: 'foundation', status: 'pending' }]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', { context: true });
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:plan-phase 1');
+  assert.equal(out.task, null);
+  assert.equal(out.phase, 1);
+});
+
+test('N3 (rule 3): PLAN.md exists + pending tasks → execute-phase + task pointer', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [{ number: 1, name: 'Foundation', slug: 'foundation', status: 'pending' }]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', {
+    context: true,
+    plan: true,
+    tasks: [
+      { num: 1, status: 'pending', wave: 1 },
+      { num: 2, status: 'pending', wave: 1, depends_on: ['T-01'] },
+    ],
+  });
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:execute-phase 1');
+  assert.ok(out.task);
+  assert.equal(out.task.id, '01-01-T01', 'task.id comes from frontmatter.id');
+  assert.equal(out.task.owner, 'np-executor');
+  assert.equal(out.task.tier, 'sonnet');
+  assert.equal(out.task.wave, 1);
+});
+
+test('N4 (rule 4): all tasks done but no VERIFICATION.md → verify-work', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [{ number: 1, name: 'Foundation', slug: 'foundation', status: 'pending' }]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', {
+    context: true,
+    plan: true,
+    tasks: [{ num: 1, status: 'done', wave: 1 }],
+  });
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:verify-work 1');
+  assert.equal(out.task, null);
+});
+
+test('N5 (rule 5): phase done+verified → next phase rules recursed', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [
+    { number: 1, name: 'Foundation', slug: 'foundation', status: 'done' },
+    { number: 2, name: 'Second', slug: 'second', status: 'pending' },
+  ]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', {
+    context: true, plan: true, verification: true,
+    tasks: [{ num: 1, status: 'done', wave: 1 }],
+  });
+
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:discuss-phase 2');
+  assert.equal(out.phase, 2);
+});
+
+test('N6 (rule 6): all phases done → complete-milestone', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [
+    { number: 1, name: 'Foundation', slug: 'foundation', status: 'done' },
+  ]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', {
+    context: true, plan: true, verification: true,
+    tasks: [{ num: 1, status: 'done', wave: 1 }],
+  });
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:complete-milestone');
+  assert.equal(out.task, null);
+  assert.equal(out.phase, null);
+  assert.equal(out.plan, null);
+});
+
+test('N7: fresh project (no STATE.md, no roadmap.yaml) → rule 1 for phase 1 (Pattern S-7)', () => {
+  const root = makeSandbox();
+
+  const out = next.computeNextStep(root);
+  assert.equal(out.next_step.command, '/np:discuss-phase 1');
+  assert.equal(out.phase, 1);
+});
+
+test('N8: rule 3 deterministic task pointer = lexicographically-first pending in waves[0]', () => {
+  const root = makeSandbox();
+  writeRoadmap(root, [{ number: 1, name: 'Foundation', slug: 'foundation', status: 'pending' }]);
+  writeState(root, { schema_version: 2, current_phase: 1, current_plan: null, current_task: null });
+  mkPhase(root, 1, 'foundation', {
+    context: true, plan: true,
+    tasks: [
+      { num: 2, status: 'pending', wave: 1 },
+      { num: 1, status: 'pending', wave: 1 },
+      { num: 3, status: 'pending', wave: 1, depends_on: ['T-01'] },
+    ],
+  });
+  const out = next.computeNextStep(root);
+  assert.equal(out.task.id, '01-01-T01');
+});

package/lib/phase.cjs

@@ -0,0 +1,95 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { projectStateDir, withFileLock, NubosPilotError } = require('./core.cjs');
+
+function paddedPhase(n) {
+  const s = String(n);
+  const m = s.match(/^(\d+)(\.\d+)?$/);
+  if (!m) {
+    throw new NubosPilotError(
+      'phase-not-found',
+      'Invalid phase number: ' + s,
+      { got: n }
+    );
+  }
+  return m[1].padStart(2, '0') + (m[2] || '');
+}
+
+function phaseSlug(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function _listPhaseEntries(phasesRoot) {
+  try {
+    return fs.readdirSync(phasesRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function findPhaseDir(n, cwd = process.cwd()) {
+  const padded = paddedPhase(n);
+  const phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  const entries = _listPhaseEntries(phasesRoot);
+  if (entries === null) return null;
+
+  const matches = entries
+    .filter((e) => e.isDirectory())
+    .filter((e) => e.name === padded || e.name.startsWith(padded + '-'))
+    .map((e) => e.name)
+    .sort((a, b) => b.length - a.length);
+
+  if (matches.length === 0) return null;
+  return path.join(phasesRoot, matches[0]);
+}
+
+function _extractSlugTail(name, padded) {
+  if (name === padded) return '';
+  if (name.startsWith(padded + '-')) return name.slice(padded.length + 1);
+  return null;
+}
+
+function createPhaseDir(n, slug, cwd = process.cwd()) {
+  const padded = paddedPhase(n);
+  const cleanSlug = phaseSlug(slug);
+  if (cleanSlug === '') {
+    throw new NubosPilotError(
+      'phase-not-found',
+      'Invalid slug: ' + slug,
+      { slug }
+    );
+  }
+
+  const phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  fs.mkdirSync(phasesRoot, { recursive: true });
+
+  return withFileLock(path.join(phasesRoot, '.phase-create'), () => {
+    const entries = _listPhaseEntries(phasesRoot) || [];
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const tail = _extractSlugTail(e.name, padded);
+      if (tail === null) continue;
+      const existingPath = path.join(phasesRoot, e.name);
+      if (tail === cleanSlug) return existingPath;
+      throw new NubosPilotError(
+        'phase-slug-mismatch',
+        `Phase ${padded} already exists with different slug`,
+        {
+          padded,
+          expected_slug: cleanSlug,
+          existing_slug: tail,
+          existing_path: existingPath,
+        }
+      );
+    }
+    const target = path.join(phasesRoot, padded + '-' + cleanSlug);
+    fs.mkdirSync(target, { recursive: true });
+    return target;
+  });
+}
+
+module.exports = { findPhaseDir, createPhaseDir, phaseSlug, paddedPhase };