nubos-pilot 0.1.0

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

@@ -0,0 +1,40 @@
+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 stateCmd = require('./state.cjs');
+
+const sandboxes = [];
+function mkTmp() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-state-cmd-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'));
+  sandboxes.push(root);
+  return root;
+}
+afterEach(() => {
+  while (sandboxes.length) {
+    const p = sandboxes.pop();
+    try { fs.rmSync(p, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('STATE-CMD-1: run returns full v2 frontmatter', () => {
+  const root = mkTmp();
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'),
+    '---\nschema_version: 2\nmilestone: v1.0\ncurrent_phase: 4\ncurrent_plan: 04-02\n' +
+    'current_task: null\nlast_updated: 2026-04-15\n---\n\n# s\n');
+  const payload = stateCmd.run([], root);
+  assert.equal(payload.schema_version, 2);
+  assert.equal(payload.current_phase, 4);
+  assert.equal(payload.current_plan, '04-02');
+});
+
+test('STATE-CMD-2: run on fresh sandbox returns error envelope payload (no STATE.md)', () => {
+  const root = mkTmp();
+
+  const payload = stateCmd.run([], root);
+  assert.ok(payload && payload.error);
+  assert.match(payload.error.code, /state-not-found|ENOENT/);
+});

package/bin/np-tools/stats.cjs

@@ -0,0 +1,151 @@
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { NubosPilotError, findProjectRoot } = require('../../lib/core.cjs');
+const { parseRoadmap } = require('../../lib/roadmap.cjs');
+const { readState } = require('../../lib/state.cjs');
+const { aggregatePhase } = require('../../lib/metrics-aggregate.cjs');
+
+const SCHEMA_VERSION = 1;
+
+function _usage() {
+  return 'Usage:\n  np-tools.cjs stats json';
+}
+
+function _emitError(err, stderr) {
+  const code = err && err.name === 'NubosPilotError' ? err.code : 'stats-internal-error';
+  const message = (err && err.message) || String(err);
+  const details = (err && err.details) || null;
+  stderr.write(JSON.stringify({ code, message, details }) + '\n');
+}
+
+function _safeExec(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (_err) {
+    return '';
+  }
+}
+
+function _gitStats(cwd) {
+  const log = _safeExec(['log', '--oneline', '--all'], cwd);
+  const commits = log ? log.split(/\r?\n/).filter((l) => l.length > 0).length : 0;
+  const first = _safeExec(['log', '--reverse', '--format=%aI', '--all'], cwd);
+  const firstFirst = first ? first.split(/\r?\n/)[0] : '';
+  return { commits, first_commit_at: firstFirst || null };
+}
+
+function _milestoneEntry(doc) {
+  if (!doc || !Array.isArray(doc.milestones) || doc.milestones.length === 0) return null;
+  const active = doc.milestones.find((m) => m && m.status === 'active' && m.id !== 'backlog');
+  const nonBacklog = doc.milestones.filter((m) => m && m.id !== 'backlog');
+  const pick = active || nonBacklog[0] || doc.milestones[0];
+  if (!pick) return null;
+  return { version: pick.id || '', name: pick.name || '' };
+}
+
+function _collectPhases(doc) {
+  const out = [];
+  if (!doc || !Array.isArray(doc.milestones)) return out;
+  for (const ms of doc.milestones) {
+    if (!ms || !Array.isArray(ms.phases)) continue;
+    if (ms.id === 'backlog') continue;
+    for (const ph of ms.phases) {
+      if (!ph || ph.number == null) continue;
+      const plans = Array.isArray(ph.plans) ? ph.plans : [];
+      const completePlans = plans.filter((p) => p && p.complete === true).length;
+      const status = ph.status === 'done' || ph.status === 'complete'
+        ? 'complete'
+        : ph.status === 'in-progress' ? 'in-progress' : 'pending';
+      out.push({
+        number: String(ph.number),
+        name: ph.name || '',
+        plans_total: plans.length,
+        plans_complete: completePlans,
+        status,
+        requirements: Array.isArray(ph.requirements) ? ph.requirements.slice() : [],
+      });
+    }
+  }
+  return out;
+}
+
+async function _buildStats(cwd) {
+  const useCwd = cwd || process.cwd();
+  const roadmap = parseRoadmap(useCwd);
+  const doc = roadmap && roadmap.doc ? roadmap.doc : null;
+  const milestone = _milestoneEntry(doc);
+  const phases = _collectPhases(doc);
+  let plansTotal = 0;
+  let plansComplete = 0;
+  for (const ph of phases) {
+    plansTotal += ph.plans_total;
+    plansComplete += ph.plans_complete;
+  }
+  const percent = plansTotal > 0 ? Math.round((plansComplete / plansTotal) * 100) : 0;
+  let lastActivity = null;
+  try {
+    const st = readState(useCwd);
+    if (st && st.frontmatter && st.frontmatter.last_activity) {
+      lastActivity = String(st.frontmatter.last_activity);
+    }
+  } catch (_err) {
+    lastActivity = null;
+  }
+  const git = _gitStats(useCwd);
+  const metrics_by_phase = {};
+  for (const ph of phases) {
+    try {
+      const agg = await aggregatePhase(ph.number, { cwd: useCwd });
+      metrics_by_phase[ph.number] = agg;
+    } catch (_err) {
+      metrics_by_phase[ph.number] = null;
+    }
+  }
+  return {
+    schema_version: SCHEMA_VERSION,
+    milestone,
+    phases,
+    plans_total: plansTotal,
+    plans_complete: plansComplete,
+    percent,
+    git,
+    last_activity: lastActivity,
+    metrics_by_phase,
+  };
+}
+
+async function run(argv, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const sub = args.shift();
+  if (sub !== 'json') {
+    stderr.write(_usage() + '\n');
+    return 1;
+  }
+  try {
+    findProjectRoot(cwd);
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+  try {
+    const out = await _buildStats(cwd);
+    stdout.write(JSON.stringify(out, null, 2) + '\n');
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, _buildStats, _collectPhases, _milestoneEntry };
+
+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/stats.test.cjs

@@ -0,0 +1,118 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Writable } = require('node:stream');
+
+const statsCli = require('./stats.cjs');
+
+const _sandboxes = [];
+
+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;
+}
+
+function makeSandbox(yaml, stateMd) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-stats-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'roadmap.yaml'), yaml);
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), stateMd);
+  execFileSync('git', ['init', '-q'], { cwd: root });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: root });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: root });
+  execFileSync('git', ['config', 'commit.gpgsign', 'false'], { cwd: root });
+  execFileSync('git', ['add', '.'], { cwd: root });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: root });
+  _sandboxes.push(root);
+  return root;
+}
+
+test.afterEach(() => {
+  while (_sandboxes.length) {
+    try { fs.rmSync(_sandboxes.pop(), { recursive: true, force: true }); } catch {  }
+  }
+});
+
+const DEMO_YAML = [
+  'milestones:',
+  '  - id: v1.0',
+  '    name: v1',
+  '    phases:',
+  '      - number: 1',
+  '        name: Foundation',
+  '        slug: foundation',
+  '        status: done',
+  '        plans:',
+  '          - id: 01-01',
+  '            title: First',
+  '            complete: true',
+  '      - number: 2',
+  '        name: Next',
+  '        slug: next',
+  '        status: in-progress',
+  '        plans:',
+  '          - id: 02-01',
+  '            title: Second',
+  '            complete: false',
+].join('\n') + '\n';
+
+const DEMO_STATE = [
+  '---',
+  'schema_version: 2',
+  'milestone: v1.0',
+  'milestone_name: v1',
+  'last_updated: "2026-04-17T10:00:00Z"',
+  'progress:',
+  '  total_phases: 2',
+  '  completed_phases: 1',
+  '  total_plans: 2',
+  '  completed_plans: 1',
+  '  percent: 50',
+  '---',
+  '',
+  '# STATE',
+].join('\n') + '\n';
+
+test('STATS-1: stats json emits schema_version + phases + git + metrics_by_phase', async () => {
+  const sb = makeSandbox(DEMO_YAML, DEMO_STATE);
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = await statsCli.run(['json'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 0, 'stderr=' + stderr.toString());
+  const parsed = JSON.parse(stdout.toString());
+  assert.equal(parsed.schema_version, 1);
+  assert.ok(parsed.milestone);
+  assert.equal(parsed.phases.length, 2);
+  assert.equal(parsed.plans_total, 2);
+  assert.equal(parsed.plans_complete, 1);
+  assert.equal(parsed.percent, 50);
+  assert.ok(parsed.git);
+  assert.ok(typeof parsed.git.commits === 'number');
+  assert.ok(parsed.metrics_by_phase);
+});
+
+test('STATS-2: unknown subcommand prints usage', async () => {
+  const sb = makeSandbox(DEMO_YAML, DEMO_STATE);
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = await statsCli.run(['yolo'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /Usage:/);
+});
+
+test('STATS-3: outside project emits NubosPilotError envelope', async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'np-stats-outside-'));
+  _sandboxes.push(tmp);
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = await statsCli.run(['json'], { cwd: tmp, stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /"code":\s*"not-in-project"/);
+});

package/bin/np-tools/triage.cjs

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, atomicWriteFileSync } = require('../../lib/core.cjs');
+const { askUser: defaultAskUser } = require('../../lib/askuser.cjs');
+const queueMod = require('./queue.cjs');
+
+const STATE_DIR_NAME = '.nubos-pilot';
+const TRIAGE_OPTIONS = ['promote-to-todo', 'promote-to-phase', 'keep', 'drop'];
+
+function _stateDir(cwd) {
+  return path.join(path.resolve(cwd), STATE_DIR_NAME);
+}
+
+function _sanitizeId(id) {
+  if (typeof id !== 'string' || id.length === 0) return 'item';
+  const cleaned = id.replace(/[^a-z0-9\-_.]/gi, '_').slice(0, 100);
+  return cleaned || 'item';
+}
+
+function _getQueueItems(cwd) {
+  const chunks = [];
+  const captureStdout = { write: (s) => { chunks.push(String(s)); return true; } };
+  queueMod.run([], { cwd, stdout: captureStdout });
+  try {
+    const parsed = JSON.parse(chunks.join(''));
+    return Array.isArray(parsed.items) ? parsed.items : [];
+  } catch {
+    return [];
+  }
+}
+
+function _applyPromoteToTodo(item, cwd, stderr) {
+  const stateDir = _stateDir(cwd);
+  const todosDir = path.join(stateDir, 'todos', 'pending');
+  try { fs.mkdirSync(todosDir, { recursive: true }); } catch {}
+  const safeName = _sanitizeId(item.id) + '.md';
+  const target = path.join(todosDir, safeName);
+  const body = `# ${item.title || item.id}\n\nSource: ${item.source}\n`;
+  try {
+    atomicWriteFileSync(target, body);
+    return { id: item.id, action: 'promote-to-todo', path: target };
+  } catch (err) {
+    try { stderr.write(`[triage] promote-to-todo failed for ${item.id}: ${err.message}\n`); } catch {}
+    return { id: item.id, action: 'promote-to-todo', error: err && err.message };
+  }
+}
+
+function _applyDrop(item, cwd, stderr) {
+  if (item.source !== 'todo') {
+    try { stderr.write(`[triage] drop: manual drop required for source=${item.source}, skipped ${item.id}\n`); } catch {}
+    return { id: item.id, action: 'drop', deferred: true };
+  }
+  const stateDir = _stateDir(cwd);
+  const todosDir = path.join(stateDir, 'todos', 'pending');
+  const explicit = item.path || path.join(todosDir, item.id);
+  const resolved = path.resolve(explicit);
+  const prefix = path.resolve(todosDir) + path.sep;
+  if (!(resolved === path.resolve(todosDir) || resolved.startsWith(prefix))) {
+    try { stderr.write(`[triage] drop refused: path outside todos/pending/ (${resolved})\n`); } catch {}
+    return { id: item.id, action: 'drop', refused: true };
+  }
+  try {
+    fs.unlinkSync(resolved);
+    return { id: item.id, action: 'drop', path: resolved };
+  } catch (err) {
+    try { stderr.write(`[triage] drop failed for ${item.id}: ${err.message}\n`); } catch {}
+    return { id: item.id, action: 'drop', error: err && err.message };
+  }
+}
+
+function _applyTriage(item, value, cwd, stderr) {
+  if (value === 'promote-to-todo') {
+    if (item.source === 'todo') {
+      try { stderr.write(`[triage] promote-to-todo is a no-op for existing todo ${item.id}\n`); } catch {}
+      return { id: item.id, action: 'keep', note: 'already-todo' };
+    }
+    return _applyPromoteToTodo(item, cwd, stderr);
+  }
+  if (value === 'promote-to-phase') {
+    try { stderr.write(`[triage] promote-to-phase requires manual step (Phase 10 UTIL-05) for ${item.id}\n`); } catch {}
+    return { id: item.id, action: 'promote-to-phase', deferred: true };
+  }
+  if (value === 'drop') {
+    return _applyDrop(item, cwd, stderr);
+  }
+
+  return { id: item.id, action: 'keep' };
+}
+
+async function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const askUser = typeof context.askUser === 'function' ? context.askUser : defaultAskUser;
+
+  const items = _getQueueItems(cwd);
+
+  if (items.length === 0) {
+    try { stderr.write('[triage] Queue leer — nichts zu triagen.\n'); } catch {}
+    const payload = { ok: true, decisions: [] };
+    stdout.write(JSON.stringify(payload));
+    return payload;
+  }
+
+  const decisions = [];
+  for (const item of items) {
+    const answer = await askUser({
+      type: 'select',
+      question: `Triage: ${item.title || item.id}`,
+      options: TRIAGE_OPTIONS.slice(),
+      default: 'keep',
+    });
+    const value = answer && typeof answer.value === 'string' ? answer.value : 'keep';
+    decisions.push(_applyTriage(item, value, cwd, stderr));
+  }
+
+  const payload = { ok: true, decisions };
+  try { stdout.write(JSON.stringify(payload)); } catch (err) {
+    throw new NubosPilotError('triage-emit-failed', err && err.message, {});
+  }
+  return payload;
+}
+
+module.exports = { run };

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

@@ -0,0 +1,108 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { detect } = require('../../lib/runtime/index.cjs');
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'ui-phase-invalid-arg',
+      'ui-phase requires a phase number argument',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const s = String(raw);
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new NubosPilotError(
+      'ui-phase-invalid-arg',
+      'Invalid phase number: ' + s,
+      { value: s },
+    );
+  }
+  return s;
+}
+
+function _resolvePhaseDir(phaseArg, cwd, slug) {
+  const hit = findPhaseDir(phaseArg, cwd);
+  if (hit) return hit;
+  const padded = paddedPhase(phaseArg);
+  return path.join(path.resolve(cwd), '.nubos-pilot', 'phases', padded + '-' + slug);
+}
+
+function _buildPayload(phaseArg, cwd) {
+  let phase;
+  try {
+    phase = getPhase(phaseArg, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'ui-phase-not-found',
+        'Phase ' + phaseArg + ' not found in roadmap',
+        { number: phaseArg },
+      );
+    }
+    throw err;
+  }
+
+  const padded = paddedPhase(phaseArg);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const ui_spec_path = path.join(phase_dir, padded + '-UI-SPEC.md');
+  const has_ui_spec = fs.existsSync(ui_spec_path);
+  const template_path = path.join(path.resolve(cwd), 'templates', 'UI-SPEC.md');
+  const { runtime } = detect({ cwd });
+
+  return {
+    _workflow: 'ui-phase',
+    phase: phaseArg,
+    padded,
+    phase_dir,
+    ui_spec_path,
+    has_ui_spec,
+    template_path,
+    agents: {
+      ui_researcher: 'np-ui-researcher',
+      ui_checker: 'np-ui-checker',
+    },
+    max_iterations: 2,
+    runtime,
+  };
+}
+
+function _emitError(err, stderr) {
+  if (err && err.name === 'NubosPilotError') {
+    stderr.write(
+      JSON.stringify({ code: err.code, message: err.message, details: err.details }) + '\n',
+    );
+  } else {
+    stderr.write(String((err && err.stack) || err) + '\n');
+  }
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const list = Array.isArray(args) ? args : [];
+
+  if (list[0] == null || list[0] === '') {
+    stderr.write('Usage: np-tools.cjs init ui-phase <phase>\n');
+    return 1;
+  }
+
+  try {
+    const phaseArg = _validatePhaseArg(list[0]);
+    const payload = _buildPayload(phaseArg, cwd);
+    stdout.write(JSON.stringify(payload, null, 2));
+    return 0;
+  } catch (err) {
+    _emitError(err, stderr);
+    return 1;
+  }
+}
+
+module.exports = { run, _buildPayload };

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

@@ -0,0 +1,121 @@
+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('./ui-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-02'],
+            success_criteria: ['UI-SPEC produced'],
+            status: 'pending',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _capture() {
+  let buf = '';
+  return { stub: { write: (s) => { buf += s; return true; } }, get: () => buf };
+}
+
+afterEach(cleanupAll);
+
+test('UIP-1: run(["init", "9"]) returns expected payload 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.ui_spec_path, path.join(dir, '09-UI-SPEC.md'));
+  assert.equal(payload.has_ui_spec, false);
+  assert.match(payload.template_path, /templates\/UI-SPEC\.md$/);
+  assert.equal(payload.max_iterations, 2);
+});
+
+test('UIP-2: agents declares ui_researcher + ui_checker', () => {
+  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, {
+    ui_researcher: 'np-ui-researcher',
+    ui_checker: 'np-ui-checker',
+  });
+});
+
+test('UIP-3: has_ui_spec=true when {padded}-UI-SPEC.md exists', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', { '09-UI-SPEC.md': '# UI\n' });
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.has_ui_spec, true);
+});
+
+test('UIP-4: runtime populated via detect() and config override', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  seedPhaseDir(sandbox, 9, 'feature-set', {});
+  fs.writeFileSync(
+    path.join(sandbox, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ runtime: 'opencode' }),
+    'utf-8',
+  );
+  const cap = _capture();
+  subcmd.run(['9'], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.runtime, 'opencode');
+});
+
+test('UIP-5: missing phase arg returns usage error', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _capture();
+  let errBuf = '';
+  const code = subcmd.run([], {
+    cwd: sandbox, stdout: cap.stub,
+    stderr: { write: (s) => { errBuf += s; return true; } },
+  });
+  assert.equal(code, 1);
+  assert.match(errBuf, /Usage/);
+});
+
+test('UIP-6: unknown phase produces ui-phase-not-found error', () => {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const cap = _capture();
+  let errBuf = '';
+  const code = subcmd.run(['99'], {
+    cwd: sandbox, stdout: cap.stub,
+    stderr: { write: (s) => { errBuf += s; return true; } },
+  });
+  assert.equal(code, 1);
+  const parsed = JSON.parse(errBuf.trim());
+  assert.equal(parsed.code, 'ui-phase-not-found');
+});