nubos-pilot 0.1.0

package/bin/np-tools/discuss-phase-power.test.cjs

@@ -0,0 +1,242 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { makeSandbox, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+
+const subcmd = require('./discuss-phase-power.cjs');
+
+const SAMPLE_TEMPLATE =
+  '# Phase {{phase}} Context (padded={{padded}})\n\n' +
+  '## Domain\n{{domain_text}}\n\n' +
+  '## Decisions\n{{decisions_text}}\n\n' +
+  '## Canonical References\n{{canonical_refs_text}}\n\n' +
+  '## Code Context\n{{code_context_text}}\n\n' +
+  '## Specifics\n{{specifics_text}}\n\n' +
+  '## Deferred\n{{deferred_text}}\n';
+
+function _seedTemplate(sandbox) {
+  const dir = path.join(sandbox, '.nubos-pilot', 'templates');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'CONTEXT.md'), SAMPLE_TEMPLATE, 'utf-8');
+}
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('P1: init without prior QUESTIONS.json creates file with schema', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+  assert.ok(fs.existsSync(qpath), 'QUESTIONS.json created');
+  const doc = JSON.parse(fs.readFileSync(qpath, 'utf-8'));
+  assert.equal(doc.phase, 5);
+  assert.equal(doc.padded, '05');
+  assert.equal(doc.mode, 'power');
+  assert.equal(typeof doc.created, 'string');
+  assert.ok(Array.isArray(doc.questions));
+  assert.equal(doc.answers_status, 'pending');
+
+  const areas = new Set(doc.questions.map((q) => q.area));
+  for (const a of ['domain', 'decisions', 'canonical_refs', 'code_context', 'specifics', 'deferred']) {
+    assert.ok(areas.has(a), 'area covered: ' + a);
+  }
+});
+
+test('P2: init when QUESTIONS.json already exists throws power-questions-exist', () => {
+  const sandbox = makeSandbox();
+  const phaseDir = seedPhaseDir(sandbox, 5, 'planning-workflows-agents', {
+    '05-QUESTIONS.json': '{}',
+  });
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'power-questions-exist'
+      && err.details && err.details.path && err.details.path.includes(phaseDir),
+  );
+});
+
+test('P3: refresh emits stats JSON with totals per area', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap0 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap0.stub });
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+
+  const doc = JSON.parse(fs.readFileSync(qpath, 'utf-8'));
+  const dq = doc.questions.find((q) => q.area === 'domain');
+  dq.answer = 'scoped';
+  fs.writeFileSync(qpath, JSON.stringify(doc, null, 2), 'utf-8');
+
+  const cap = _capture();
+  subcmd.run(['refresh', '5'], { cwd: sandbox, stdout: cap.stub });
+  const stats = JSON.parse(cap.get().trim());
+  assert.equal(typeof stats.total_questions, 'number');
+  assert.ok(stats.answered >= 1);
+  assert.ok(stats.pending >= 0);
+  assert.ok(stats.areas && typeof stats.areas === 'object');
+  assert.ok(stats.areas.domain && typeof stats.areas.domain.total === 'number');
+  assert.ok(typeof stats.areas.domain.answered === 'number');
+
+  const ctxPath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-CONTEXT.md'
+  );
+  assert.ok(!fs.existsSync(ctxPath), 'refresh does not touch CONTEXT.md');
+});
+
+test('P4: finalize with all answers renders CONTEXT.md and marks finalized', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+  const fixture = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'tests', 'fixtures', 'discuss', 'power-questions-sample.json'),
+    'utf-8'
+  );
+  fs.writeFileSync(qpath, fixture, 'utf-8');
+
+  const cap = _capture();
+  subcmd.run(['finalize', '5'], { cwd: sandbox, stdout: cap.stub });
+
+  const ctxPath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-CONTEXT.md'
+  );
+  assert.ok(fs.existsSync(ctxPath), 'CONTEXT.md rendered');
+  const ctx = fs.readFileSync(ctxPath, 'utf-8');
+  assert.ok(ctx.includes('Phase 5'), 'phase header present');
+  assert.ok(ctx.includes('power-mode file-UI'), 'domain answer substring');
+  assert.ok(ctx.includes('No HTML companion'), 'decisions answer substring');
+
+  const doc = JSON.parse(fs.readFileSync(qpath, 'utf-8'));
+  assert.equal(doc.answers_status, 'finalized');
+});
+
+test('P5: finalize with pending answers throws power-finalize-incomplete', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap0 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap0.stub });
+  assert.throws(
+    () => subcmd.run(['finalize', '5'], { cwd: sandbox, stdout: _capture().stub }),
+    (err) => err.name === 'NubosPilotError'
+      && err.code === 'power-finalize-incomplete'
+      && err.details && Array.isArray(err.details.pending_ids)
+      && err.details.pending_ids.length > 0,
+  );
+});
+
+test('P6: explain returns question object with explain field populated', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap0 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap0.stub });
+
+  const cap = _capture();
+  subcmd.run(['explain', '5', 'Q-01'], { cwd: sandbox, stdout: cap.stub });
+  const body = JSON.parse(cap.get().trim());
+  assert.equal(body.id, 'Q-01');
+  assert.ok(typeof body.explain === 'string' && body.explain.length > 0);
+});
+
+test('P7: exit emits status JSON; does NOT delete QUESTIONS.json', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap0 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap0.stub });
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+
+  const cap = _capture();
+  subcmd.run(['exit', '5'], { cwd: sandbox, stdout: cap.stub });
+  const body = JSON.parse(cap.get().trim());
+  assert.equal(body.status, 'exited');
+  assert.ok(fs.existsSync(qpath), 'QUESTIONS.json preserved after exit');
+});
+
+test('P8: HTML-ban regression — no HTML markers in source file', () => {
+  const src = fs.readFileSync(path.join(__dirname, 'discuss-phase-power.cjs'), 'utf-8');
+  const banned = [/<html/, /<!DOCTYPE/i, /showOpenFilePicker/, /FileSystemFileHandle/, /document\./];
+  for (const re of banned) {
+    assert.ok(!re.test(src), 'banned HTML marker found: ' + re);
+  }
+});
+
+test('P9: writes use atomicWriteFileSync', () => {
+  const src = fs.readFileSync(path.join(__dirname, 'discuss-phase-power.cjs'), 'utf-8');
+  const occurrences = (src.match(/atomicWriteFileSync/g) || []).length;
+  assert.ok(occurrences >= 2, 'atomicWriteFileSync used in ≥2 places, got ' + occurrences);
+});
+
+test('P10: concurrent refresh+finalize does not corrupt QUESTIONS.json', async () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+  const fixture = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'tests', 'fixtures', 'discuss', 'power-questions-sample.json'),
+    'utf-8'
+  );
+  fs.writeFileSync(qpath, fixture, 'utf-8');
+
+  const results = await Promise.allSettled([
+    Promise.resolve().then(() => subcmd.run(['refresh', '5'], { cwd: sandbox, stdout: _capture().stub })),
+    Promise.resolve().then(() => subcmd.run(['finalize', '5'], { cwd: sandbox, stdout: _capture().stub })),
+  ]);
+
+  const fulfilled = results.filter((r) => r.status === 'fulfilled').length;
+  assert.ok(fulfilled >= 1);
+  const doc = JSON.parse(fs.readFileSync(qpath, 'utf-8'));
+  assert.equal(doc.phase, 5);
+  assert.ok(Array.isArray(doc.questions));
+});
+
+test('P11: init + explain full round-trip preserves question set', () => {
+  const sandbox = makeSandbox();
+  seedPhaseDir(sandbox, 5, 'planning-workflows-agents');
+  _seedTemplate(sandbox);
+  const cap0 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap0.stub });
+  const qpath = path.join(
+    sandbox, '.nubos-pilot', 'phases', '05-planning-workflows-agents',
+    '05-QUESTIONS.json'
+  );
+  const before = JSON.parse(fs.readFileSync(qpath, 'utf-8')).questions.length;
+
+  const cap = _capture();
+  subcmd.run(['explain', '5', 'Q-01'], { cwd: sandbox, stdout: cap.stub });
+
+  const after = JSON.parse(fs.readFileSync(qpath, 'utf-8')).questions.length;
+  assert.equal(before, after, 'explain does not add/remove questions');
+});

package/bin/np-tools/discuss-phase.cjs

@@ -0,0 +1,132 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+
+function _parseArgs(args) {
+  const rest = [];
+  const flags = { assumptions: false };
+  for (const a of args || []) {
+    if (a === '--assumptions') flags.assumptions = true;
+    else rest.push(a);
+  }
+  return { positional: rest, flags };
+}
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'discuss-invalid-phase-arg',
+      'discuss-phase requires a phase number (integer or decimal like 7.1)',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const s = String(raw);
+  const integerOk = /^\d+$/.test(s);
+  const decimalOk = /^\d+\.\d+$/.test(s);
+  if (!integerOk && !decimalOk) {
+    throw new NubosPilotError(
+      'discuss-invalid-phase-arg',
+      'Invalid phase number: ' + s,
+      { value: s },
+    );
+  }
+  return s;
+}
+
+function _agentSkills() {
+  try {
+    const agents = require('../../lib/agents.cjs');
+    if (typeof agents.getAgentSkills === 'function') {
+      return { planner: agents.getAgentSkills('np-planner') };
+    }
+  } catch (_err) {  }
+  return { planner: null };
+}
+
+function _resolvePhaseDir(n, cwd, slug) {
+  const hit = findPhaseDir(n, cwd);
+  if (hit) return hit;
+
+  
+
+  const padded = paddedPhase(n);
+  let stateDir;
+  try { stateDir = projectStateDir(cwd); } catch (_err) {
+    stateDir = path.join(path.resolve(cwd), '.nubos-pilot');
+  }
+  return path.join(stateDir, 'phases', padded + '-' + slug);
+}
+
+function _emit(payload, stdout, cwd) {
+  const json = JSON.stringify(payload, null, 2);
+  if (Buffer.byteLength(json, 'utf-8') <= INLINE_THRESHOLD_BYTES) {
+    stdout.write(json);
+    return;
+  }
+  let tmpDir;
+  try {
+    tmpDir = path.join(projectStateDir(cwd), '.tmp');
+    fs.mkdirSync(tmpDir, { recursive: true });
+  } catch (_err) {
+    tmpDir = os.tmpdir();
+  }
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'init-discuss-phase-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const { positional, flags } = _parseArgs(args);
+  const phaseArg = _validatePhaseArg(positional[0]);
+
+  let phase;
+  try {
+    phase = getPhase(phaseArg, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'discuss-phase-not-found',
+        'Phase ' + phaseArg + ' not found in roadmap.yaml',
+        { number: phaseArg },
+      );
+    }
+    throw err;
+  }
+
+  const padded = paddedPhase(phaseArg);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const contextPath = path.join(phase_dir, padded + '-CONTEXT.md');
+  const has_context = fs.existsSync(contextPath);
+
+  const payload = {
+    _workflow: 'discuss-phase',
+    phase_number: phaseArg,
+    padded,
+    phase_dir,
+    phase_name: phase.name,
+    phase_slug: slug,
+    has_context,
+    goal: phase.goal || '',
+    requirements: Array.isArray(phase.requirements) ? phase.requirements : [],
+    success_criteria: Array.isArray(phase.success_criteria) ? phase.success_criteria : [],
+    mode: flags.assumptions ? 'assumptions' : 'adaptive',
+    agent_skills: _agentSkills(),
+  };
+
+  _emit(payload, stdout, cwd);
+  return payload;
+}
+
+module.exports = { run, _parseArgs, _validatePhaseArg, INLINE_THRESHOLD_BYTES };

package/bin/np-tools/discuss-phase.test.cjs

@@ -0,0 +1,148 @@
+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('./discuss-phase.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          {
+            number: 3,
+            name: 'Observability',
+            slug: 'observability',
+            goal: 'Ship structured logging + metrics',
+            depends_on: [],
+            requirements: ['OBS-01'],
+            success_criteria: ['Logs emit JSON'],
+            status: 'planned',
+            plans: [],
+          },
+          {
+            number: 7,
+            name: 'Seven',
+            slug: 'seven',
+            goal: 'Phase seven goal',
+            depends_on: [],
+            requirements: [],
+            success_criteria: [],
+            status: 'planned',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _captureStdout() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('DP-1: run(["3"]) on valid phase returns JSON payload with expected shape', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'observability', {});
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const raw = cap.get().trim();
+  assert.ok(!raw.startsWith('@file:'));
+  const payload = JSON.parse(raw);
+  assert.equal(payload.phase_number, '3');
+  assert.equal(payload.padded, '03');
+  assert.ok(payload.phase_dir.endsWith('03-observability'));
+  assert.equal(payload.phase_name, 'Observability');
+  assert.equal(payload.has_context, false);
+  assert.equal(payload.goal, 'Ship structured logging + metrics');
+  assert.deepEqual(payload.requirements, ['OBS-01']);
+  assert.ok('agent_skills' in payload);
+  assert.equal(payload.mode, 'adaptive');
+});
+
+test('DP-2: run(["nonexistent"]) throws discuss-invalid-phase-arg', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['nonexistent'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'discuss-invalid-phase-arg',
+  );
+});
+
+test('DP-3: run(["99"]) where phase not in roadmap throws discuss-phase-not-found', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+  assert.throws(
+    () => subcmd.run(['99'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'discuss-phase-not-found',
+  );
+});
+
+test('DP-4: existing CONTEXT.md flips has_context=true', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'observability', {
+    '03-CONTEXT.md': '# existing context\n',
+  });
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.has_context, true);
+});
+
+test('DP-5: --assumptions flag sets mode=assumptions', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 3, 'observability', {});
+  const cap = _captureStdout();
+  subcmd.run(['3', '--assumptions'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.mode, 'assumptions');
+});
+
+test('DP-6: decimal phase number 7.1 accepted; 7.1 not in roadmap falls through to phase-not-found', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _captureStdout();
+
+  
+  assert.throws(
+    () => subcmd.run(['7.1'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'discuss-phase-not-found',
+  );
+});
+
+test('DP-7: oversized payload emits @file:<tmp> pointer', () => {
+  const sandbox = makeSandbox();
+  const big = _baseRoadmap();
+
+  const filler = [];
+  for (let i = 0; i < 1200; i++) {
+    filler.push('REQ-' + i + '-with-additional-padding-to-grow-bytes-effectively');
+  }
+  big.milestones[0].phases[0].requirements = filler;
+  seedRoadmapYaml(sandbox, big);
+  seedPhaseDir(sandbox, 3, 'observability', {});
+  const cap = _captureStdout();
+  subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
+  const out = cap.get().trim();
+  assert.ok(out.startsWith('@file:'), 'large payload produced @file: pointer');
+  const tmpPath = out.slice('@file:'.length);
+  const body = fs.readFileSync(tmpPath, 'utf-8');
+  const payload = JSON.parse(body);
+  assert.equal(payload.phase_number, '3');
+  fs.unlinkSync(tmpPath);
+});

package/bin/np-tools/dispatch.cjs

@@ -0,0 +1,116 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { computeNextStep: realComputeNextStep } = require('../../lib/next.cjs');
+const { askUser: defaultAskUser } = require('../../lib/askuser.cjs');
+
+const VALID_ACTIONS = new Set(['discuss', 'plan', 'execute', 'verify']);
+
+function _parseArgs(args) {
+  const list = Array.isArray(args) ? args : [];
+  let phase = null;
+  let force = false;
+  let actionOverride = null;
+  for (const a of list) {
+    if (a === '--force') { force = true; continue; }
+    if (typeof a === 'string' && a.startsWith('--action=')) {
+      actionOverride = a.slice('--action='.length);
+      continue;
+    }
+    if (phase == null && typeof a === 'string' && !a.startsWith('--')) {
+      phase = a;
+    }
+  }
+  return { phase, force, actionOverride };
+}
+
+function _normalize(result) {
+  if (!result || typeof result !== 'object') {
+    return { nextAction: null, ambiguous: false, alternatives: [] };
+  }
+  if (typeof result.nextAction === 'string') {
+    return {
+      nextAction: result.nextAction,
+      ambiguous: Boolean(result.ambiguous),
+      alternatives: Array.isArray(result.alternatives) ? result.alternatives : [],
+      reasoning: result.reasoning,
+    };
+  }
+
+  const cmd = result.next_step && result.next_step.command;
+  let action = null;
+  if (typeof cmd === 'string') {
+    const m = cmd.match(/\/np:([a-z-]+)/);
+    if (m) {
+      const verb = m[1];
+      if (verb.startsWith('discuss')) action = 'discuss';
+      else if (verb.startsWith('plan')) action = 'plan';
+      else if (verb.startsWith('execute')) action = 'execute';
+      else if (verb.startsWith('verify')) action = 'verify';
+    }
+  }
+  return {
+    nextAction: action,
+    ambiguous: false,
+    alternatives: [],
+    reasoning: result.next_step && result.next_step.reason,
+  };
+}
+
+async function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const askUser = typeof context.askUser === 'function' ? context.askUser : defaultAskUser;
+  const computeNextStep = typeof context.computeNextStep === 'function'
+    ? context.computeNextStep
+    : realComputeNextStep;
+
+  const { phase, force, actionOverride } = _parseArgs(args);
+
+  if (actionOverride != null) {
+    if (!VALID_ACTIONS.has(actionOverride)) {
+      throw new NubosPilotError(
+        'dispatch-unknown-action',
+        'Unknown --action override: ' + actionOverride,
+        { action: actionOverride, valid: [...VALID_ACTIONS] },
+      );
+    }
+  }
+
+  const raw = await computeNextStep(cwd, { phase });
+  const resolved = _normalize(raw);
+
+  let action = actionOverride || resolved.nextAction;
+
+  if (!actionOverride && !force && resolved.ambiguous) {
+    const options = [resolved.nextAction, ...(resolved.alternatives || [])]
+      .filter((x) => x && VALID_ACTIONS.has(x));
+    if (options.length > 1) {
+      const answer = await askUser({
+        type: 'select',
+        question: `State ambiguous. Recommended: ${resolved.nextAction}. Override?`,
+        options,
+        default: resolved.nextAction,
+      });
+      if (answer && typeof answer.value === 'string') action = answer.value;
+    }
+  }
+
+  if (!action || !VALID_ACTIONS.has(action)) {
+    throw new NubosPilotError(
+      'dispatch-no-action',
+      'computeNextStep did not yield a routable action',
+      { resolved, phase },
+    );
+  }
+
+  const payload = {
+    skill: 'np-' + action,
+    args: { phase },
+  };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };