nubos-pilot 0.1.0

package/bin/np-tools/ai-integration-phase.test.cjs

@@ -0,0 +1,123 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, seedRoadmapYaml, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./ai-integration-phase.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          {
+            number: 9,
+            name: 'Feature Set',
+            slug: 'feature-set',
+            goal: 'Ship advanced workflows',
+            depends_on: [],
+            requirements: ['R-01'],
+            success_criteria: ['AI-SPEC produced'],
+            status: 'pending',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _capture() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('AIP-1: run(["init", "9"]) returns payload with expected shape', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const dir = seedPhaseDir(sandbox, 9, 'feature-set', {});
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.phase, '9');
+  assert.equal(payload.padded, '09');
+  assert.equal(payload.phase_dir, dir);
+  assert.equal(
+    payload.ai_spec_path,
+    path.join(dir, '09-AI-SPEC.md'),
+  );
+  assert.equal(payload.has_ai_spec, false);
+  assert.match(payload.template_path, /templates\/AI-SPEC\.md$/);
+});
+
+test('AIP-2: agents.* declares the 4 AI-integration subagents', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {});
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.deepEqual(payload.agents, {
+    framework_selector: 'np-framework-selector',
+    ai_researcher: 'np-ai-researcher',
+    domain_researcher: 'np-domain-researcher',
+    eval_planner: 'np-eval-planner',
+  });
+});
+
+test('AIP-3: has_ai_spec=true when {padded}-AI-SPEC.md exists', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {
+    '09-AI-SPEC.md': '# AI Spec\n',
+  });
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.has_ai_spec, true);
+});
+
+test('AIP-4: runtime field populated from lib/runtime detect()', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {});
+  fs.writeFileSync(
+    path.join(sandbox, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ runtime: 'claude' }),
+    'utf-8',
+  );
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.runtime, 'claude');
+});
+
+test('AIP-5: missing phase arg exits with usage error', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _capture();
+  let errBuf = '';
+  const errStub = { write: (s) => { errBuf += s; return true; } };
+  const code = subcmd.run([], { cwd: sandbox, stdout: cap.stub, stderr: errStub });
+  assert.equal(code, 1);
+  assert.match(errBuf, /Usage/);
+});
+
+test('AIP-6: phase not in roadmap produces NubosPilotError JSON on stderr', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _capture();
+  let errBuf = '';
+  const errStub = { write: (s) => { errBuf += s; return true; } };
+  const code = subcmd.run(['99'], { cwd: sandbox, stdout: cap.stub, stderr: errStub });
+  assert.equal(code, 1);
+  const parsed = JSON.parse(errBuf.trim());
+  assert.equal(parsed.code, 'ai-integration-phase-not-found');
+});

package/bin/np-tools/askuser.cjs

@@ -0,0 +1,53 @@
+const { askUser } = require('../../lib/askuser.cjs');
+
+function _usage() {
+  return 'Usage:\n  np-tools.cjs askuser --json \'{...spec...}\'';
+}
+
+function _emitError(err, stderr) {
+  const code = err && err.name === 'NubosPilotError' ? err.code : 'askuser-internal-error';
+  const message = (err && err.message) || String(err);
+  const details = (err && err.details) || null;
+  stderr.write(JSON.stringify({ code, message, details }) + '\n');
+}
+
+async function run(argv, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const idx = args.indexOf('--json');
+  if (idx < 0 || idx + 1 >= args.length) {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  let spec;
+  try {
+    spec = JSON.parse(args[idx + 1]);
+  } catch (err) {
+    stderr.write(JSON.stringify({ code: 'askuser-invalid-json', message: err.message, details: null }) + '\n');
+    return 1;
+  }
+  try {
+    const result = await askUser(spec);
+    const value = result && typeof result === 'object' && 'value' in result ? result.value : result;
+    let out;
+    if (value == null) out = '';
+    else if (typeof value === 'string') out = value;
+    else out = JSON.stringify(value);
+    stdout.write(out + '\n');
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  run(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
+    process.stderr.write(String((err && err.stack) || err) + '\n');
+    process.exit(1);
+  });
+}

package/bin/np-tools/askuser.test.cjs

@@ -0,0 +1,49 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Writable } = require('node:stream');
+
+const askuserCli = require('./askuser.cjs');
+const askuserLib = require('../../lib/askuser.cjs');
+
+function makeSink() {
+  const chunks = [];
+  const w = new Writable({
+    write(chunk, _enc, cb) { chunks.push(chunk); cb(); },
+  });
+  w.toString = () => Buffer.concat(chunks.map((c) => Buffer.isBuffer(c) ? c : Buffer.from(String(c)))).toString('utf-8');
+  return w;
+}
+
+test('ASKUSER-1: happy path returns chosen label via readline test-hook', async (t) => {
+  askuserLib._setReadlineImplForTests(() => '2');
+  t.after(() => askuserLib._setReadlineImplForTests(null));
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const spec = { type: 'select', question: 'Choose', options: ['alpha', 'beta', 'gamma'] };
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = () => true;
+  let code;
+  try {
+    code = await askuserCli.run(['--json', JSON.stringify(spec)], { stdout, stderr });
+  } finally {
+    process.stdout.write = origStdoutWrite;
+  }
+  assert.equal(code, 0);
+  assert.match(stdout.toString(), /beta/);
+});
+
+test('ASKUSER-2: invalid JSON emits askuser-invalid-json on stderr', async () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = await askuserCli.run(['--json', '{not json'], { stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /"code":\s*"askuser-invalid-json"/);
+});
+
+test('ASKUSER-3: missing --json prints usage to stderr', async () => {
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = await askuserCli.run([], { stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /Usage:/);
+});

package/bin/np-tools/autonomous.cjs

@@ -0,0 +1,69 @@
+const path = require('node:path');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { resolveGate } = require('../../lib/next.cjs');
+const { findPhaseDir } = require('../../lib/phase.cjs');
+const { listPlans } = require('../../lib/plan.cjs');
+const { loadTaskGraph } = require('../../lib/tasks.cjs');
+
+function _firstWaveAllSkippedOrParked(phaseN, cwd) {
+  let phaseDir;
+  try { phaseDir = findPhaseDir(phaseN, cwd); } catch { return false; }
+  if (!phaseDir) return false;
+  const plans = listPlans(phaseDir);
+  if (plans.length === 0) return false;
+  const planDir = path.dirname(plans[0]);
+  let tg;
+  try { tg = loadTaskGraph(planDir); } catch { return false; }
+  if (!tg.waves || tg.waves.length === 0) return false;
+  const firstWave = tg.waves[0];
+  const pending = firstWave
+    .map((id) => tg.tasks.find((t) => t.id === id))
+    .filter((t) => t && t.frontmatter && t.frontmatter.status !== 'done');
+  if (pending.length === 0) return false;
+  return pending.every((t) => t.frontmatter.status === 'skipped' || t.frontmatter.status === 'parked');
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+
+  
+  const verb = list[0];
+  const phaseArg = verb === 'init' ? list[1] : verb;
+  if (phaseArg == null || phaseArg === '' || !/^\d+(\.\d+)?$/.test(String(phaseArg))) {
+    throw new NubosPilotError(
+      'autonomous-invalid-phase',
+      'autonomous requires a numeric phase argument',
+      { value: phaseArg == null ? '' : String(phaseArg) },
+    );
+  }
+  const phaseN = Number(phaseArg);
+  const gate = resolveGate(phaseN, cwd);
+  let payload;
+  const blockedNullTask = gate.rule === 3 && !gate.task;
+  const blockedSkippedOnly = gate.rule === 3 && _firstWaveAllSkippedOrParked(phaseN, cwd);
+  if (blockedNullTask || blockedSkippedOnly) {
+
+    
+    payload = {
+      _workflow: 'autonomous',
+      status: 'advancement-blocked',
+      phase: phaseN,
+      reason: 'rule-3-null-task',
+      gate,
+    };
+  } else {
+    payload = {
+      _workflow: 'autonomous',
+      status: 'ok',
+      phase: phaseN,
+      gate,
+    };
+  }
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/autonomous.test.cjs

@@ -0,0 +1,74 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, seedRoadmapYaml, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./autonomous.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [{ id: 'v1.0', name: 'm1', phases: [
+      { number: 6, name: 'Execution', slug: 'execution', goal: '', depends_on: [],
+        requirements: [], success_criteria: [], status: 'planned', plans: [] },
+    ]}],
+  };
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; return true; } }, get: () => b }; }
+
+afterEach(cleanupAll);
+
+test('AU-1: advancement-blocked when rule 3 + skipped-only wave (Pitfall 6 Guard)', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const phaseDir = seedPhaseDir(sandbox, 6, 'execution', {
+    '06-CONTEXT.md': '# ctx',
+    '06-01-PLAN.md': '---\nphase: 6\nplan: 01\n---\n# p\n',
+  });
+
+  fs.mkdirSync(path.join(phaseDir, 'tasks'), { recursive: true });
+  const taskMd = [
+    '---', 'id: 06-01-T01', 'phase: 6', 'plan: "06-01"', 'type: auto',
+    'status: skipped', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified: []', 'autonomous: true',
+    'must_haves:', '  truths: []', '---', '',
+  ].join('\n');
+  fs.writeFileSync(path.join(phaseDir, 'tasks', '06-01-T01.md'), taskMd, 'utf-8');
+
+  const cap = _capture();
+  const p = subcmd.run(['6'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(p.status, 'advancement-blocked');
+  assert.equal(p.reason, 'rule-3-null-task');
+});
+
+test('AU-2: ok status when gate is not rule-3-null-task', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+
+  seedPhaseDir(sandbox, 6, 'execution', {});
+  const cap = _capture();
+  const p = subcmd.run(['6'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(p.status, 'ok');
+  assert.equal(p.gate.rule, 1);
+});
+
+test('AU-3: accepts `init <phase>` verb form', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 6, 'execution', {});
+  const cap = _capture();
+  const p = subcmd.run(['init', '6'], { cwd: sandbox, stdout: cap.stub });
+  assert.equal(p.status, 'ok');
+});
+
+test('AU-4: missing phase arg → autonomous-invalid-phase', () => {
+  const sandbox = makeSandbox();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run([], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.code === 'autonomous-invalid-phase',
+  );
+});

package/bin/np-tools/checkpoint.cjs

@@ -0,0 +1,101 @@
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { TASK_ID_RE } = require('../../lib/tasks.cjs');
+const {
+  startTask,
+  writeCheckpoint,
+  readCheckpoint,
+} = require('../../lib/checkpoint.cjs');
+
+const _VALID_STATUSES = new Set(['in-progress', 'verifying', 'pre-commit', 'done']);
+
+function _parseFlags(rest) {
+  const flags = {};
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--phase' || a === '--plan' || a === '--wave') {
+      flags[a.slice(2)] = rest[i + 1];
+      i += 1;
+    }
+  }
+  return flags;
+}
+
+function _assertTaskId(id) {
+  if (typeof id !== 'string' || !TASK_ID_RE.test(id)) {
+    throw new NubosPilotError(
+      'checkpoint-invalid-task-id',
+      'Invalid task-id format: ' + id + ' (expected <NN-NN-TNN>)',
+      { id },
+    );
+  }
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const list = Array.isArray(args) ? args : [];
+  const verb = list[0];
+  const taskId = list[1];
+
+  switch (verb) {
+    case 'start': {
+      _assertTaskId(taskId);
+      const flags = _parseFlags(list.slice(2));
+      const task = {
+        id: taskId,
+        phase: flags.phase != null ? Number(flags.phase) : null,
+        plan: flags.plan != null ? String(flags.plan) : null,
+        wave: flags.wave != null ? Number(flags.wave) : null,
+      };
+      const cp = startTask(task, cwd);
+      stdout.write(JSON.stringify(cp));
+      return cp;
+    }
+    case 'transition': {
+      _assertTaskId(taskId);
+      const status = list[2];
+      if (!_VALID_STATUSES.has(status)) {
+        throw new NubosPilotError(
+          'checkpoint-invalid-status',
+          'Invalid checkpoint status: ' + status + ' (allowed: ' + [..._VALID_STATUSES].join(', ') + ')',
+          { status, allowed: [..._VALID_STATUSES] },
+        );
+      }
+      const cp = writeCheckpoint(taskId, { status }, cwd);
+      stdout.write(JSON.stringify(cp));
+      return cp;
+    }
+    case 'touch': {
+      _assertTaskId(taskId);
+      const file = list[2];
+      if (!file) {
+        throw new NubosPilotError(
+          'checkpoint-missing-file',
+          'checkpoint touch requires <file>',
+          { taskId },
+        );
+      }
+      const existing = readCheckpoint(taskId, cwd) || { files_touched: [] };
+      const touched = Array.isArray(existing.files_touched) ? existing.files_touched.slice() : [];
+      if (!touched.includes(file)) touched.push(file);
+      const cp = writeCheckpoint(taskId, { files_touched: touched }, cwd);
+      stdout.write(JSON.stringify(cp));
+      return cp;
+    }
+    case 'show': {
+      _assertTaskId(taskId);
+      const cp = readCheckpoint(taskId, cwd);
+      stdout.write(JSON.stringify(cp));
+      return cp;
+    }
+    default:
+      throw new NubosPilotError(
+        'checkpoint-unknown-verb',
+        'checkpoint: unknown verb: ' + String(verb) + ' (allowed: start, transition, touch, show)',
+        { verb },
+      );
+  }
+}
+
+module.exports = { run };

package/bin/np-tools/checkpoint.test.cjs

@@ -0,0 +1,119 @@
+const { test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const subcmd = require('./checkpoint.cjs');
+
+const _roots = [];
+
+function makeRoot() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-cp-cli-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: null
+current_plan: null
+current_task: null
+last_updated: "2026-04-15T00:00:00Z"
+progress:
+  total_phases: 0
+  completed_phases: 0
+  total_plans: 0
+  completed_plans: 0
+  percent: 0
+session:
+  stopped_at: null
+  resume_file: null
+  last_activity: null
+---
+
+# State
+`, 'utf-8');
+  _roots.push(root);
+  return root;
+}
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('CPT-1: checkpoint start writes file and updates STATE.current_task', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  subcmd.run(['start', '06-01-T01', '--phase', '6', '--plan', '06-01', '--wave', '1'], { cwd: root, stdout: cap.stub });
+  const cp = JSON.parse(fs.readFileSync(path.join(root, '.nubos-pilot', 'checkpoints', '06-01-T01.json'), 'utf-8'));
+  assert.equal(cp.task_id, '06-01-T01');
+  assert.equal(cp.status, 'in-progress');
+  const state = fs.readFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), 'utf-8');
+  assert.ok(state.includes('current_task: 06-01-T01'), state);
+});
+
+test('CPT-2: checkpoint transition updates status', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  subcmd.run(['start', '06-01-T02', '--phase', '6', '--plan', '06-01', '--wave', '1'], { cwd: root, stdout: cap.stub });
+  subcmd.run(['transition', '06-01-T02', 'verifying'], { cwd: root, stdout: cap.stub });
+  const cp = JSON.parse(fs.readFileSync(path.join(root, '.nubos-pilot', 'checkpoints', '06-01-T02.json'), 'utf-8'));
+  assert.equal(cp.status, 'verifying');
+});
+
+test('CPT-3: checkpoint transition rejects unknown status', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  subcmd.run(['start', '06-01-T03', '--phase', '6', '--plan', '06-01', '--wave', '1'], { cwd: root, stdout: cap.stub });
+  assert.throws(
+    () => subcmd.run(['transition', '06-01-T03', 'weird'], { cwd: root, stdout: cap.stub }),
+    (err) => err && err.code === 'checkpoint-invalid-status',
+  );
+});
+
+test('CPT-4: checkpoint touch appends to files_touched', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  subcmd.run(['start', '06-01-T04', '--phase', '6', '--plan', '06-01', '--wave', '1'], { cwd: root, stdout: cap.stub });
+  subcmd.run(['touch', '06-01-T04', 'src/a.ts'], { cwd: root, stdout: cap.stub });
+  subcmd.run(['touch', '06-01-T04', 'src/b.ts'], { cwd: root, stdout: cap.stub });
+  const cp = JSON.parse(fs.readFileSync(path.join(root, '.nubos-pilot', 'checkpoints', '06-01-T04.json'), 'utf-8'));
+  assert.deepEqual(cp.files_touched, ['src/a.ts', 'src/b.ts']);
+});
+
+test('CPT-5: checkpoint show emits JSON', () => {
+  const root = makeRoot();
+  const cap1 = _capture();
+  subcmd.run(['start', '06-01-T05', '--phase', '6', '--plan', '06-01', '--wave', '1'], { cwd: root, stdout: cap1.stub });
+  const cap2 = _capture();
+  subcmd.run(['show', '06-01-T05'], { cwd: root, stdout: cap2.stub });
+  const json = JSON.parse(cap2.get());
+  assert.equal(json.task_id, '06-01-T05');
+});
+
+test('CPT-6: unknown verb throws', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['bogus', '06-01-T01'], { cwd: root, stdout: cap.stub }),
+    (err) => err && err.code === 'checkpoint-unknown-verb',
+  );
+});
+
+test('CPT-7: invalid task-id format rejected (defense-in-depth)', () => {
+  const root = makeRoot();
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['start', 'not-a-task-id'], { cwd: root, stdout: cap.stub }),
+    (err) => err && err.code === 'checkpoint-invalid-task-id',
+  );
+});