nubos-pilot 0.1.0

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

@@ -0,0 +1,350 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const {
+  NubosPilotError,
+  projectStateDir,
+  findProjectRoot,
+  atomicWriteFileSync,
+  withFileLock,
+} = require('../../lib/core.cjs');
+const { getPhase } = require('../../lib/roadmap.cjs');
+const { paddedPhase, phaseSlug, findPhaseDir } = require('../../lib/phase.cjs');
+const { listPlans, parsePlan, shouldPromoteToTasks } = require('../../lib/plan.cjs');
+const { getAgentSkills } = require('../../lib/agents.cjs');
+const { gitShowSafe } = require('../../lib/git.cjs');
+
+const INLINE_THRESHOLD_BYTES = 16 * 1024;
+
+function _validatePhaseArg(raw) {
+  if (raw == null || raw === '') {
+    throw new NubosPilotError(
+      'plan-phase-invalid-phase-arg',
+      'plan-phase requires a phase number (integer or decimal)',
+      { value: raw == null ? '' : String(raw) },
+    );
+  }
+  const s = String(raw);
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new NubosPilotError(
+      'plan-phase-invalid-phase-arg',
+      'Invalid phase number: ' + s,
+      { value: s },
+    );
+  }
+  return s;
+}
+
+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 { stateDir = path.join(path.resolve(cwd), '.nubos-pilot'); }
+  return path.join(stateDir, 'phases', padded + '-' + slug);
+}
+
+function _safeSkills(name, cwd) {
+  try { return getAgentSkills(name, cwd); } catch { return []; }
+}
+
+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 { tmpDir = os.tmpdir(); }
+  const suffix = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const tmpPath = path.join(tmpDir, 'init-plan-phase-' + suffix + '.json');
+  fs.writeFileSync(tmpPath, json, 'utf-8');
+  stdout.write('@file:' + tmpPath);
+}
+
+function _initPayload(phaseArg, cwd) {
+  let phase;
+  try {
+    phase = getPhase(phaseArg, cwd);
+  } catch (err) {
+    if (err && err.code === 'phase-not-found') {
+      throw new NubosPilotError(
+        'plan-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 researchPath = path.join(phase_dir, padded + '-RESEARCH.md');
+  const plan_review_path = path.join(phase_dir, padded + '-PLAN-REVIEW.md');
+
+  let has_plan = false;
+  try { has_plan = listPlans(phase_dir).length > 0; } catch { has_plan = false; }
+
+  const { plan_diff_required, plan_diff_plan_path } = _probePlanDiff(phase_dir, padded, cwd);
+
+  return {
+    _workflow: 'plan-phase',
+    phase: phaseArg,
+    padded,
+    phase_dir,
+    phase_slug: slug,
+    phase_name: phase.name,
+    goal: phase.goal || '',
+    requirements: Array.isArray(phase.requirements) ? phase.requirements : [],
+    success_criteria: Array.isArray(phase.success_criteria) ? phase.success_criteria : [],
+    has_context: fs.existsSync(contextPath),
+    has_research: fs.existsSync(researchPath),
+    has_plan,
+    context_path: fs.existsSync(contextPath) ? contextPath : null,
+    research_path: fs.existsSync(researchPath) ? researchPath : null,
+    plan_review_path,
+    planner_tier: 'opus',
+    checker_tier: 'opus',
+    plan_diff_required,
+    plan_diff_plan_path,
+    agent_skills: {
+      'np-planner': _safeSkills('np-planner', cwd),
+      'np-plan-checker': _safeSkills('np-plan-checker', cwd),
+    },
+  };
+}
+
+function _probePlanDiff(phaseDir, padded, cwd) {
+  const firstPlanAbs = path.join(phaseDir, padded + '-01-PLAN.md');
+  let root;
+  try { root = findProjectRoot(cwd); } catch { root = path.resolve(cwd); }
+  const rel = path.relative(root, firstPlanAbs);
+  const prev = process.cwd();
+  process.chdir(root);
+  let prior = null;
+  try {
+    prior = gitShowSafe('HEAD', rel);
+  } catch {
+    prior = null;
+  } finally {
+    process.chdir(prev);
+  }
+  return {
+    plan_diff_required: prior !== null,
+    plan_diff_plan_path: rel,
+  };
+}
+
+function _readVerdict(verdictPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(verdictPath, 'utf-8');
+  } catch (err) {
+    throw new NubosPilotError(
+      'plan-phase-verdict-unreadable',
+      'Verdict file not readable: ' + verdictPath,
+      { path: verdictPath, cause: err && err.code },
+    );
+  }
+  try { return JSON.parse(raw); } catch (err) {
+    throw new NubosPilotError(
+      'plan-phase-verdict-invalid',
+      'Verdict file is not valid JSON',
+      { path: verdictPath, cause: err && err.message },
+    );
+  }
+}
+
+function _renderVerdictYaml(verdict) {
+  const status = verdict.status || 'unknown';
+  const findings = Array.isArray(verdict.findings) ? verdict.findings : [];
+  const lines = ['status: ' + status, 'findings:'];
+  if (findings.length === 0) {
+    lines[1] = 'findings: []';
+  } else {
+    for (const f of findings) {
+      lines.push('  - category: ' + (f.category || 'unknown'));
+      lines.push('    severity: ' + (f.severity || 'minor'));
+      if (f.target) lines.push('    target: ' + JSON.stringify(String(f.target)));
+      if (f.message) lines.push('    message: ' + JSON.stringify(String(f.message)));
+    }
+  }
+  return lines.join('\n');
+}
+
+function _renderIterationSection(iter, verdict) {
+  const ts = new Date().toISOString();
+  const status = verdict.status || 'unknown';
+  const parts = [
+    '',
+    '## Iteration ' + iter + ' - ' + ts,
+    '',
+    '**Planner output:** PLAN.md committed at pending',
+    '**Checker verdict:** ' + status,
+    '**Findings:**',
+    '',
+    '```yaml',
+    _renderVerdictYaml(verdict),
+    '```',
+    '',
+    '**Planner response:** ' + (status === 'passed' ? 'done' : 'revision'),
+    '',
+  ];
+  return parts.join('\n');
+}
+
+function _planReviewAppend(phaseArg, iter, verdictPath, cwd) {
+  const padded = paddedPhase(phaseArg);
+  const phase = getPhase(phaseArg, cwd);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  fs.mkdirSync(phase_dir, { recursive: true });
+  const reviewPath = path.join(phase_dir, padded + '-PLAN-REVIEW.md');
+  const verdict = _readVerdict(verdictPath);
+
+  return withFileLock(reviewPath, () => {
+    let existing = '';
+    try { existing = fs.readFileSync(reviewPath, 'utf-8'); } catch { existing = ''; }
+    if (existing === '') {
+      existing = '# PLAN-REVIEW.md — Phase ' + phaseArg + ' (' + phase.name + ')\n'
+        + '\nAppend-only audit trail of plan-checker iterations. Never truncate.\n';
+    }
+    const section = _renderIterationSection(iter, verdict);
+    const next = existing + section;
+    atomicWriteFileSync(reviewPath, next);
+    return { appended: true, path: reviewPath, iteration: Number(iter) };
+  });
+}
+
+function _rmRecursive(target) {
+  try { fs.rmSync(target, { recursive: true, force: true }); } catch {  }
+}
+
+function _planPhaseAbort(phaseArg, cwd) {
+  const padded = paddedPhase(phaseArg);
+  const phase = getPhase(phaseArg, cwd);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const removed = [];
+
+  let entries = [];
+  try { entries = fs.readdirSync(phase_dir); } catch { entries = []; }
+  for (const name of entries) {
+    if (name === 'PLAN.md' || /^\d{2}(\.\d+)?-\d{2}-PLAN\.md$/.test(name)) {
+      const p = path.join(phase_dir, name);
+      _rmRecursive(p);
+      removed.push(p);
+    }
+  }
+  const tasksDir = path.join(phase_dir, 'tasks');
+  if (fs.existsSync(tasksDir)) {
+    _rmRecursive(tasksDir);
+    removed.push(tasksDir);
+  }
+
+  const preserved = path.join(phase_dir, padded + '-PLAN-REVIEW.md');
+  return { aborted: true, removed, preserved: fs.existsSync(preserved) ? preserved : null };
+}
+
+function _extractTasksFromPlan(planPath) {
+
+  
+  const raw = fs.readFileSync(planPath, 'utf-8');
+  const tagRe = /<task\s+([^>]+?)(?:\/>|>[\s\S]*?<\/task>)/g;
+  const attrRe = /([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*"([^"]*)"/g;
+  const out = [];
+  let m;
+  while ((m = tagRe.exec(raw)) !== null) {
+    const attrs = {};
+    let a;
+    while ((a = attrRe.exec(m[1])) !== null) attrs[a[1]] = a[2];
+    const depsRaw = attrs.depends_on || '';
+    const deps = depsRaw
+      .replace(/^\[|\]$/g, '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    out.push({
+      id: attrs.id || '',
+      frontmatter: {
+        depends_on: deps,
+        wave: attrs.wave ? Number(attrs.wave) : undefined,
+        tier: attrs.tier || undefined,
+      },
+    });
+  }
+  return out;
+}
+
+function _planPhasePromoteCheck(phaseArg, cwd) {
+  const phase = getPhase(phaseArg, cwd);
+  const slug = phase.slug || phaseSlug(phase.name);
+  const phase_dir = _resolvePhaseDir(phaseArg, cwd, slug);
+  const plans = listPlans(phase_dir);
+  if (plans.length === 0) return { promote: false, triggers: [] };
+
+  
+  const planPath = plans[0];
+
+  parsePlan(planPath);
+  const tasks = _extractTasksFromPlan(planPath);
+  return shouldPromoteToTasks({ tasks });
+}
+
+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];
+
+  switch (verb) {
+    case 'init': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const payload = _initPayload(phaseArg, cwd);
+      _emit(payload, stdout, cwd);
+      return payload;
+    }
+    case 'plan-review-append': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const iter = list[2];
+      const verdictPath = list[3];
+      if (!iter || !verdictPath) {
+        throw new NubosPilotError(
+          'plan-phase-missing-args',
+          'plan-review-append requires <phase> <iter> <verdictJsonPath>',
+          { got: list.slice(1) },
+        );
+      }
+      const result = _planReviewAppend(phaseArg, iter, verdictPath, cwd);
+      _emit(result, stdout, cwd);
+      return result;
+    }
+    case 'plan-phase-abort': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const result = _planPhaseAbort(phaseArg, cwd);
+      _emit(result, stdout, cwd);
+      return result;
+    }
+    case 'plan-phase-promote-check': {
+      const phaseArg = _validatePhaseArg(list[1]);
+      const result = _planPhasePromoteCheck(phaseArg, cwd);
+      _emit(result, stdout, cwd);
+      return result;
+    }
+    default:
+      throw new NubosPilotError(
+        'plan-phase-unknown-verb',
+        'plan-phase: unknown verb: ' + String(verb),
+        { verb: verb },
+      );
+  }
+}
+
+module.exports = { run, INLINE_THRESHOLD_BYTES };

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

@@ -0,0 +1,263 @@
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const { makeSandbox, seedRoadmapYaml, seedPhaseDir, cleanupAll } =
+  require('../../tests/helpers/fixture.cjs');
+const subcmd = require('./plan-phase.cjs');
+
+function _baseRoadmap() {
+  return {
+    schema_version: 1,
+    milestones: [
+      {
+        id: 'v1.0',
+        name: 'first',
+        phases: [
+          {
+            number: 5,
+            name: 'Planning Workflows',
+            slug: 'planning-workflows',
+            goal: 'Ship the plan-phase orchestrator',
+            depends_on: [],
+            requirements: ['PLAN-04'],
+            success_criteria: ['plan-phase workflow exists'],
+            status: 'planned',
+            plans: [],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function _capture() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+function _seed(phaseFiles) {
+  const sandbox = makeSandbox();
+  seedRoadmapYaml(sandbox, _baseRoadmap());
+  const dir = seedPhaseDir(sandbox, 5, 'planning-workflows', phaseFiles || {});
+  return { sandbox, phaseDir: dir };
+}
+
+afterEach(cleanupAll);
+
+test('PP-1: run(["init", "5"]) returns payload with expected shape', () => {
+  const { sandbox, phaseDir } = _seed({
+    '05-CONTEXT.md': '# ctx',
+    '05-RESEARCH.md': '# res',
+  });
+  const cap = _capture();
+  const payload = subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const raw = cap.get().trim();
+  assert.ok(!raw.startsWith('@file:'));
+  const parsed = JSON.parse(raw);
+  assert.equal(parsed.phase, '5');
+  assert.equal(parsed.padded, '05');
+  assert.equal(parsed.phase_dir, phaseDir);
+  assert.equal(parsed.phase_name, 'Planning Workflows');
+  assert.equal(parsed.goal, 'Ship the plan-phase orchestrator');
+  assert.deepEqual(parsed.requirements, ['PLAN-04']);
+  assert.equal(parsed.has_context, true);
+  assert.equal(parsed.has_research, true);
+  assert.equal(parsed.has_plan, false);
+  assert.equal(parsed.planner_tier, 'opus');
+  assert.equal(parsed.checker_tier, 'opus');
+  assert.ok(parsed.plan_review_path.endsWith('05-PLAN-REVIEW.md'));
+  assert.ok(parsed.agent_skills && 'np-planner' in parsed.agent_skills);
+  assert.ok(parsed.agent_skills && 'np-plan-checker' in parsed.agent_skills);
+
+  assert.equal(payload.phase, '5');
+});
+
+test('PP-2: init payload has_context/has_research/has_plan reflect actual disk state', () => {
+  const { sandbox } = _seed({});
+  const cap = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const parsed = JSON.parse(cap.get().trim());
+  assert.equal(parsed.has_context, false);
+  assert.equal(parsed.has_research, false);
+  assert.equal(parsed.has_plan, false);
+
+  fs.writeFileSync(path.join(parsed.phase_dir, '05-01-PLAN.md'), '---\nphase: "5"\n---\n');
+  const cap2 = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap2.stub });
+  const p2 = JSON.parse(cap2.get().trim());
+  assert.equal(p2.has_plan, true);
+});
+
+test('PP-3: plan-review-append creates PLAN-REVIEW.md with dated iteration section', () => {
+  const { sandbox, phaseDir } = _seed({});
+  const verdict = { status: 'issues_found', findings: [
+    { category: 'missing-success-criterion', severity: 'critical',
+      target: 'PLAN.md §SC-3', message: 'No task addresses SC-3.' },
+  ]};
+  const verdictPath = path.join(sandbox, 'verdict-1.json');
+  fs.writeFileSync(verdictPath, JSON.stringify(verdict), 'utf-8');
+
+  const cap = _capture();
+  subcmd.run(['plan-review-append', '5', '1', verdictPath], { cwd: sandbox, stdout: cap.stub });
+
+  const reviewPath = path.join(phaseDir, '05-PLAN-REVIEW.md');
+  assert.ok(fs.existsSync(reviewPath));
+  const body = fs.readFileSync(reviewPath, 'utf-8');
+  assert.match(body, /## Iteration 1 - \d{4}-\d{2}-\d{2}T/);
+  assert.match(body, /\*\*Checker verdict:\*\* issues_found/);
+  assert.match(body, /```yaml[\s\S]*missing-success-criterion[\s\S]*```/);
+});
+
+test('PP-4: plan-review-append is append-only (iteration 1 bytes preserved in iter 2)', () => {
+  const { sandbox, phaseDir } = _seed({});
+  const reviewPath = path.join(phaseDir, '05-PLAN-REVIEW.md');
+
+  const v1 = { status: 'issues_found', findings: [
+    { category: 'non-atomic-task', severity: 'major', target: 'T02', message: 'T02 bundles concerns' },
+  ]};
+  const v2 = { status: 'passed', findings: [] };
+  const v1Path = path.join(sandbox, 'v1.json');
+  const v2Path = path.join(sandbox, 'v2.json');
+  fs.writeFileSync(v1Path, JSON.stringify(v1), 'utf-8');
+  fs.writeFileSync(v2Path, JSON.stringify(v2), 'utf-8');
+
+  subcmd.run(['plan-review-append', '5', '1', v1Path], { cwd: sandbox, stdout: _capture().stub });
+  const afterIter1 = fs.readFileSync(reviewPath, 'utf-8');
+  const iter1Sha = crypto.createHash('sha256').update(afterIter1).digest('hex');
+
+  subcmd.run(['plan-review-append', '5', '2', v2Path], { cwd: sandbox, stdout: _capture().stub });
+  const afterIter2 = fs.readFileSync(reviewPath, 'utf-8');
+
+  assert.ok(afterIter2.startsWith(afterIter1),
+    'iter 1 bytes must be a prefix of iter 2 contents (append-only invariant)');
+
+  const iter1Sha2 = crypto.createHash('sha256').update(afterIter2.slice(0, afterIter1.length)).digest('hex');
+  assert.equal(iter1Sha, iter1Sha2);
+  assert.match(afterIter2, /## Iteration 2 - /);
+});
+
+test('PP-5: plan-phase-abort deletes PLAN.md + tasks/ but preserves PLAN-REVIEW.md', () => {
+  const { sandbox, phaseDir } = _seed({
+    '05-01-PLAN.md': '---\nphase: "5"\n---\n',
+    '05-PLAN-REVIEW.md': '## Iteration 1 - 2026-01-01T00:00:00Z\npreserve me\n',
+  });
+  const tasksDir = path.join(phaseDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, 'T01.md'), 'x', 'utf-8');
+
+  const cap = _capture();
+  subcmd.run(['plan-phase-abort', '5'], { cwd: sandbox, stdout: cap.stub });
+
+  assert.ok(!fs.existsSync(path.join(phaseDir, '05-01-PLAN.md')));
+  assert.ok(!fs.existsSync(tasksDir));
+  assert.ok(fs.existsSync(path.join(phaseDir, '05-PLAN-REVIEW.md')));
+  const body = fs.readFileSync(path.join(phaseDir, '05-PLAN-REVIEW.md'), 'utf-8');
+  assert.match(body, /preserve me/);
+});
+
+test('PP-6: plan-phase-promote-check returns {promote:false} on linear same-tier plan', () => {
+  const plan = [
+    '---',
+    'phase: "5"',
+    'plan: "05-01"',
+    '---',
+    '',
+    '<tasks>',
+    '<task id="T01" wave="1" tier="sonnet" depends_on="[]">one</task>',
+    '<task id="T02" wave="2" tier="sonnet" depends_on="[T01]">two</task>',
+    '</tasks>',
+  ].join('\n');
+  const { sandbox, phaseDir } = _seed({ '05-01-PLAN.md': plan });
+  const cap = _capture();
+  subcmd.run(['plan-phase-promote-check', '5'], { cwd: sandbox, stdout: cap.stub });
+  const out = JSON.parse(cap.get().trim());
+  assert.equal(out.promote, false);
+  assert.deepEqual(out.triggers, []);
+
+  void phaseDir;
+});
+
+test('PP-7: plan-phase-promote-check flags parallelism on parallel-tier plan', () => {
+  const plan = [
+    '---',
+    'phase: "5"',
+    'plan: "05-01"',
+    '---',
+    '',
+    '<tasks>',
+    '<task id="T01" wave="1" tier="sonnet" depends_on="[]">one</task>',
+    '<task id="T02" wave="1" tier="sonnet" depends_on="[]">two</task>',
+    '<task id="T03" wave="2" tier="opus" depends_on="[T01, T02]">three</task>',
+    '</tasks>',
+  ].join('\n');
+  const { sandbox } = _seed({ '05-01-PLAN.md': plan });
+  const cap = _capture();
+  subcmd.run(['plan-phase-promote-check', '5'], { cwd: sandbox, stdout: cap.stub });
+  const out = JSON.parse(cap.get().trim());
+  assert.equal(out.promote, true);
+  assert.ok(out.triggers.includes('parallelism'));
+});
+
+test('PP-8: unknown verb throws NubosPilotError("plan-phase-unknown-verb")', () => {
+  const { sandbox } = _seed({});
+  const cap = _capture();
+  assert.throws(
+    () => subcmd.run(['bad', '5'], { cwd: sandbox, stdout: cap.stub }),
+    (err) => err && err.name === 'NubosPilotError' && err.code === 'plan-phase-unknown-verb'
+      && err.details && err.details.verb === 'bad',
+  );
+});
+
+test('PP-9: oversized payload emits @file: pointer', () => {
+  const { sandbox } = _seed({});
+
+  const cfgDir = path.join(sandbox, '.nubos-pilot');
+  const big = [];
+  for (let i = 0; i < 3000; i++) big.push('skill-' + i);
+  fs.writeFileSync(
+    path.join(cfgDir, 'config.json'),
+    JSON.stringify({ agent_skills: { planner: big, 'np-plan-checker': big } }),
+    'utf-8',
+  );
+  const cap = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const raw = cap.get().trim();
+  assert.ok(raw.startsWith('@file:'), 'expected @file: pointer for oversized payload');
+});
+
+const { execFileSync } = require('node:child_process');
+
+function _initGitRepo(root) {
+  execFileSync('git', ['-C', root, 'init', '-q', '-b', 'main'], { stdio: 'pipe' });
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'test@nubos-pilot.local']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'nubos-test']);
+  execFileSync('git', ['-C', root, 'commit', '--allow-empty', '-q', '-m', 'chore: init'], { stdio: 'pipe' });
+}
+
+test('PP-PD-1: init payload has plan_diff_required=true when HEAD has 05-01-PLAN.md committed', () => {
+  const { sandbox, phaseDir } = _seed({});
+  _initGitRepo(sandbox);
+  const rel = path.relative(sandbox, path.join(phaseDir, '05-01-PLAN.md'));
+  fs.writeFileSync(path.join(sandbox, rel), '---\nphase: "5"\n---\n', 'utf-8');
+  execFileSync('git', ['-C', sandbox, 'add', '--', rel], { stdio: 'pipe' });
+  execFileSync('git', ['-C', sandbox, 'commit', '-q', '-m', 'seed PLAN.md'], { stdio: 'pipe' });
+  const cap = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const parsed = JSON.parse(cap.get().trim());
+  assert.equal(parsed.plan_diff_required, true);
+  assert.equal(parsed.plan_diff_plan_path, rel);
+});
+
+test('PP-PD-2: init payload has plan_diff_required=false for first-time planning', () => {
+  const { sandbox } = _seed({});
+  _initGitRepo(sandbox);
+  const cap = _capture();
+  subcmd.run(['init', '5'], { cwd: sandbox, stdout: cap.stub });
+  const parsed = JSON.parse(cap.get().trim());
+  assert.equal(parsed.plan_diff_required, false);
+  assert.match(parsed.plan_diff_plan_path, /05-01-PLAN\.md$/);
+});

package/bin/np-tools/progress.cjs

@@ -0,0 +1,7 @@
+const { readProgress } = require('../../lib/progress.cjs');
+
+function run(_args, cwd) {
+  return readProgress(cwd || process.cwd());
+}
+
+module.exports = { run };

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

@@ -0,0 +1,44 @@
+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 progressCmd = require('./progress.cjs');
+
+const sandboxes = [];
+function mkTmp() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-progress-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('PROG-CMD-1: run returns persisted progress block from STATE.md', () => {
+  const root = mkTmp();
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'),
+    '---\nschema_version: 2\ncurrent_phase: 1\ncurrent_plan: null\ncurrent_task: null\n' +
+    'last_updated: 2026-04-15\n' +
+    'progress:\n' +
+    '  total_phases: 5\n  completed_phases: 2\n  total_plans: 11\n  completed_plans: 4\n  percent: 36\n' +
+    '---\n\n# S\n');
+  const payload = progressCmd.run([], root);
+  assert.equal(payload.total_phases, 5);
+  assert.equal(payload.completed_phases, 2);
+  assert.equal(payload.total_plans, 11);
+  assert.equal(payload.completed_plans, 4);
+  assert.equal(payload.percent, 36);
+});
+
+test('PROG-CMD-2: run on fresh sandbox (no STATE.md) returns zero-block', () => {
+  const root = mkTmp();
+  const payload = progressCmd.run([], root);
+  assert.equal(payload.total_phases, 0);
+  assert.equal(payload.percent, 0);
+});