nubos-pilot 0.1.0

package/bin/np-tools/new-project.cjs

@@ -0,0 +1,284 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const {
+  NubosPilotError,
+  atomicWriteFileSync,
+} = require('../../lib/core.cjs');
+const { addMilestone, addPhase } = require('../../lib/roadmap.cjs');
+const { createPhaseDir, phaseSlug } = require('../../lib/phase.cjs');
+const { writeState } = require('../../lib/state.cjs');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates');
+const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+
+function _render(raw, vars, templateName) {
+  return raw.replace(PLACEHOLDER_RE, (_match, key) => {
+    if (!(key in vars)) {
+      throw new NubosPilotError(
+        'template-unresolved-var',
+        `Undefined placeholder {{${key}}} in template "${templateName}"`,
+        { template: templateName, variable: key, available: Object.keys(vars) },
+      );
+    }
+    return String(vars[key]);
+  });
+}
+
+function _loadTemplate(name) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, name + '.md'), 'utf-8');
+}
+
+function _slugify(raw) {
+  return String(raw || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function _todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function _interviewPayload() {
+  return {
+    mode: 'interview',
+    questions: [
+      { key: 'project_name', type: 'input',
+        question: 'Project name?' },
+      { key: 'core_value', type: 'input',
+        question: 'Core value — one sentence that must stay true if everything else fails?' },
+      { key: 'primary_constraints', type: 'input',
+        question: 'Primary constraints (comma-separated, e.g. "Node 22; markdown-first")?' },
+      { key: 'first_milestone_name', type: 'input',
+        question: 'First milestone name (e.g. "v1.0")?' },
+      { key: 'first_phase_name', type: 'input',
+        question: 'First phase name (will be slugified for the directory)?' },
+    ],
+  };
+}
+
+function _validateAnswers(a) {
+  for (const key of [
+    'project_name',
+    'core_value',
+    'primary_constraints',
+    'first_milestone_name',
+    'first_phase_name',
+  ]) {
+    if (typeof a[key] !== 'string' || a[key].trim() === '') {
+      throw new NubosPilotError(
+        'answers-missing-field',
+        'answers JSON missing field: ' + key,
+        { field: key },
+      );
+    }
+  }
+}
+
+function _emit(stdout, payload) {
+  stdout.write(JSON.stringify(payload, null, 2));
+}
+
+function _apply(answersPath, cwd, stdout) {
+  let raw;
+  try {
+    raw = fs.readFileSync(answersPath, 'utf-8');
+  } catch (err) {
+    throw new NubosPilotError(
+      'answers-not-readable',
+      'answers file not readable: ' + answersPath,
+      { path: answersPath, cause: err && err.code },
+    );
+  }
+  let answers;
+  try {
+    answers = JSON.parse(raw);
+  } catch (err) {
+    throw new NubosPilotError(
+      'answers-parse-error',
+      'answers file is not valid JSON',
+      { path: answersPath, cause: err && err.message },
+    );
+  }
+  _validateAnswers(answers);
+
+  const root = path.resolve(cwd);
+  const stateDir = path.join(root, '.nubos-pilot');
+  const projectMd = path.join(stateDir, 'PROJECT.md');
+
+  if (fs.existsSync(projectMd)) {
+    throw new NubosPilotError(
+      'project-already-initialized',
+      'PROJECT.md already exists — refusing to overwrite',
+      { path: projectMd },
+    );
+  }
+
+  const milestoneId = _slugify(answers.first_milestone_name);
+  if (milestoneId === '') {
+    throw new NubosPilotError(
+      'invalid-slug',
+      'first_milestone_name slugifies to empty string',
+      { value: answers.first_milestone_name, field: 'first_milestone_name' },
+    );
+  }
+  const phaseSlugValue = phaseSlug(answers.first_phase_name);
+  if (phaseSlugValue === '') {
+    throw new NubosPilotError(
+      'invalid-slug',
+      'first_phase_name slugifies to empty string',
+      { value: answers.first_phase_name, field: 'first_phase_name' },
+    );
+  }
+
+  const createdDate = _todayIso();
+
+  
+
+  
+
+  fs.mkdirSync(stateDir, { recursive: true });
+  const roadmapYamlPath = path.join(stateDir, 'roadmap.yaml');
+  const emptyRoadmap = { schema_version: 1, milestones: [] };
+  atomicWriteFileSync(roadmapYamlPath, YAML.stringify(emptyRoadmap, { indent: 2 }));
+
+  
+
+  const projectVars = {
+    project_name: answers.project_name,
+    core_value: answers.core_value,
+    primary_constraints: answers.primary_constraints,
+    first_milestone_name: answers.first_milestone_name,
+    first_phase_name: answers.first_phase_name,
+    created_date: createdDate,
+  };
+  atomicWriteFileSync(projectMd, _render(_loadTemplate('PROJECT'), projectVars, 'PROJECT'));
+
+  
+
+  const reqVars = {
+    project_name: answers.project_name,
+    core_value: answers.core_value,
+    first_milestone_name: answers.first_milestone_name,
+    created_date: createdDate,
+  };
+  atomicWriteFileSync(
+    path.join(stateDir, 'REQUIREMENTS.md'),
+    _render(_loadTemplate('REQUIREMENTS'), reqVars, 'REQUIREMENTS'),
+  );
+
+  
+
+  
+  addMilestone({ id: milestoneId, name: answers.first_milestone_name, phases: [] }, root);
+  const phaseResult = addPhase(
+    milestoneId,
+    {
+      slug: phaseSlugValue,
+      name: answers.first_phase_name,
+      goal: '',
+      depends_on: [],
+      requirements: [],
+      success_criteria: [],
+      status: 'pending',
+      plans: [],
+    },
+    root,
+  );
+
+  
+
+  const phaseDir = createPhaseDir(phaseResult.number, phaseSlugValue, root);
+  const ctxVars = {
+    phase_number: String(phaseResult.number),
+    phase_name: answers.first_phase_name,
+    phase_padded: String(phaseResult.number).padStart(2, '0'),
+    phase_slug: phaseSlugValue,
+    created_date: createdDate,
+    domain_text: '<!-- TBD: phase boundary -->',
+    decisions_text: '<!-- TBD: decisions -->',
+    canonical_refs_text: '<!-- TBD: canonical references -->',
+    code_context_text: '<!-- TBD: existing code insights -->',
+    specifics_text: '<!-- TBD: specific ideas / references -->',
+    deferred_text: '<!-- TBD: deferred ideas -->',
+  };
+  const contextMdPath = path.join(
+    phaseDir,
+    String(phaseResult.number).padStart(2, '0') + '-CONTEXT.md',
+  );
+  atomicWriteFileSync(contextMdPath, _render(_loadTemplate('CONTEXT'), ctxVars, 'CONTEXT'));
+
+  
+
+  writeState(
+    {
+      frontmatter: {
+        schema_version: 2,
+        milestone: milestoneId,
+        milestone_name: answers.first_milestone_name,
+        current_phase: Number(phaseResult.number),
+        current_plan: null,
+        current_task: null,
+        last_updated: new Date().toISOString(),
+        progress: {
+          total_phases: 1,
+          completed_phases: 0,
+          total_plans: 0,
+          completed_plans: 0,
+          percent: 0,
+        },
+        session: {
+          stopped_at: null,
+          resume_file: null,
+          last_activity: createdDate + ' -- np:new-project scaffold',
+        },
+      },
+      body: '\n# Project State\n\nInitialized by np:new-project.\n',
+    },
+    root,
+  );
+
+  
+
+  _emit(stdout, {
+    mode: 'apply',
+    milestoneId,
+    firstPhaseNumber: phaseResult.number,
+    firstPhaseSlug: phaseSlugValue,
+    created: [
+      '.nubos-pilot/PROJECT.md',
+      '.nubos-pilot/REQUIREMENTS.md',
+      '.nubos-pilot/roadmap.yaml',
+      '.nubos-pilot/ROADMAP.md',
+      '.nubos-pilot/STATE.md',
+      path.relative(root, contextMdPath),
+    ],
+  });
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const argv = args || [];
+
+  const applyIdx = argv.indexOf('--apply');
+  if (applyIdx >= 0) {
+    const answersPath = argv[applyIdx + 1];
+    if (!answersPath) {
+      throw new NubosPilotError(
+        'missing-apply-path',
+        '--apply requires a path to the answers JSON file',
+        { args: argv.slice() },
+      );
+    }
+    _apply(answersPath, cwd, stdout);
+    return;
+  }
+
+  _emit(stdout, _interviewPayload());
+}
+
+module.exports = { run, _interviewPayload, _slugify };

package/bin/np-tools/new-project.test.cjs

@@ -0,0 +1,165 @@
+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 subcmd = require('./new-project.cjs');
+
+const _sandboxes = [];
+
+function makeEmptySandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-newproj-'));
+  _sandboxes.push(root);
+  return root;
+}
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    const p = _sandboxes.pop();
+    try { fs.rmSync(p, { recursive: true, force: true }); } catch {  }
+  }
+});
+
+function _captureStdout() {
+  let buf = '';
+  const stub = { write: (s) => { buf += s; return true; } };
+  return { stub, get: () => buf };
+}
+
+function _baseAnswers() {
+  return {
+    project_name: 'Demo Project',
+    core_value: 'Ship demos fast.',
+    primary_constraints: 'Node 22; markdown-first',
+    first_milestone_name: 'v1.0',
+    first_phase_name: 'Foundation Phase',
+  };
+}
+
+function _writeAnswers(root, answers) {
+  const p = path.join(root, 'answers.json');
+  fs.writeFileSync(p, JSON.stringify(answers), 'utf-8');
+  return p;
+}
+
+test('NP-1: run([]) emits interview JSON with all 5 questions', () => {
+  const sandbox = makeEmptySandbox();
+  const cap = _captureStdout();
+  subcmd.run([], { cwd: sandbox, stdout: cap.stub });
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.mode, 'interview');
+  assert.ok(Array.isArray(payload.questions));
+  const keys = payload.questions.map((q) => q.key);
+  for (const expected of [
+    'project_name',
+    'core_value',
+    'primary_constraints',
+    'first_milestone_name',
+    'first_phase_name',
+  ]) {
+    assert.ok(keys.includes(expected), 'interview missing ' + expected);
+  }
+  for (const q of payload.questions) {
+    assert.ok(typeof q.question === 'string' && q.question.length > 0);
+    assert.ok(typeof q.type === 'string');
+  }
+});
+
+test('NP-2: --apply creates all 5 files + scaffolds first phase dir', () => {
+  const sandbox = makeEmptySandbox();
+  const answersPath = _writeAnswers(sandbox, _baseAnswers());
+  const cap = _captureStdout();
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: cap.stub });
+
+  assert.ok(fs.existsSync(path.join(sandbox, '.nubos-pilot', 'PROJECT.md')), 'PROJECT.md missing');
+  assert.ok(fs.existsSync(path.join(sandbox, '.nubos-pilot', 'REQUIREMENTS.md')), 'REQUIREMENTS.md missing');
+  assert.ok(fs.existsSync(path.join(sandbox, '.nubos-pilot', 'roadmap.yaml')), 'roadmap.yaml missing');
+  assert.ok(fs.existsSync(path.join(sandbox, '.nubos-pilot', 'ROADMAP.md')), 'ROADMAP.md missing');
+  assert.ok(fs.existsSync(path.join(sandbox, '.nubos-pilot', 'STATE.md')), 'STATE.md missing');
+
+  const phasesRoot = path.join(sandbox, '.nubos-pilot', 'phases');
+  const entries = fs.readdirSync(phasesRoot);
+  const phaseDir = entries.find((e) => e.startsWith('01-'));
+  assert.ok(phaseDir, 'phases/01-<slug>/ not scaffolded');
+  assert.ok(
+    fs.existsSync(path.join(phasesRoot, phaseDir, '01-CONTEXT.md')),
+    '01-CONTEXT.md placeholder missing',
+  );
+});
+
+test('NP-3: PROJECT.md is rendered with user-supplied values', () => {
+  const sandbox = makeEmptySandbox();
+  const answersPath = _writeAnswers(sandbox, _baseAnswers());
+  const cap = _captureStdout();
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: cap.stub });
+  const raw = fs.readFileSync(path.join(sandbox, '.nubos-pilot', 'PROJECT.md'), 'utf-8');
+  assert.match(raw, /Demo Project/);
+  assert.match(raw, /Ship demos fast\./);
+  assert.match(raw, /Node 22/);
+
+  assert.doesNotMatch(raw, /\{\{[a-z_]+\}\}/);
+});
+
+test('NP-4: second invocation throws project-already-initialized', () => {
+  const sandbox = makeEmptySandbox();
+  const answersPath = _writeAnswers(sandbox, _baseAnswers());
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub });
+
+  const diffAnswers = Object.assign({}, _baseAnswers(), { project_name: 'Other' });
+  const diffPath = _writeAnswers(sandbox, diffAnswers);
+  assert.throws(
+    () => subcmd.run(['--apply', diffPath], { cwd: sandbox, stdout: _captureStdout().stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'project-already-initialized',
+  );
+});
+
+test('NP-5: shell-metachar project_name is stored literally, no files outside .nubos-pilot', () => {
+  const sandbox = makeEmptySandbox();
+  const evil = Object.assign({}, _baseAnswers(), {
+    project_name: '; rm -rf /tmp/definitely-not-there ; echo PWND',
+  });
+  const answersPath = _writeAnswers(sandbox, evil);
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub });
+  const raw = fs.readFileSync(path.join(sandbox, '.nubos-pilot', 'PROJECT.md'), 'utf-8');
+  assert.match(raw, /rm -rf/);
+
+  const entries = fs.readdirSync(sandbox).sort();
+  assert.deepEqual(entries, ['.nubos-pilot', 'answers.json']);
+});
+
+test('NP-6: slugifies first_phase_name; strips non [a-z0-9-]', () => {
+  const sandbox = makeEmptySandbox();
+  const answers = Object.assign({}, _baseAnswers(), {
+    first_phase_name: 'Foo Bar! 2',
+  });
+  const answersPath = _writeAnswers(sandbox, answers);
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub });
+  const phasesRoot = path.join(sandbox, '.nubos-pilot', 'phases');
+  const entries = fs.readdirSync(phasesRoot);
+  const phaseDir = entries.find((e) => e.startsWith('01-'));
+  assert.equal(phaseDir, '01-foo-bar-2');
+});
+
+test('NP-7: empty-after-slugify first_phase_name throws invalid-slug', () => {
+  const sandbox = makeEmptySandbox();
+  const answers = Object.assign({}, _baseAnswers(), {
+    first_phase_name: '!!!@@@###',
+  });
+  const answersPath = _writeAnswers(sandbox, answers);
+  assert.throws(
+    () => subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub }),
+    (err) => err.name === 'NubosPilotError' && err.code === 'invalid-slug',
+  );
+});
+
+test('NP-8: STATE.md seeded with milestone + current_phase:1 + status', () => {
+  const sandbox = makeEmptySandbox();
+  const answersPath = _writeAnswers(sandbox, _baseAnswers());
+  subcmd.run(['--apply', answersPath], { cwd: sandbox, stdout: _captureStdout().stub });
+  const { readState } = require('../../lib/state.cjs');
+  const st = readState(sandbox);
+  assert.ok(st.frontmatter.milestone, 'STATE.md missing milestone');
+  assert.equal(st.frontmatter.current_phase, 1);
+  assert.equal(st.frontmatter.current_plan, null);
+});

package/bin/np-tools/next.cjs

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

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

@@ -0,0 +1,30 @@
+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 nextCmd = require('./next.cjs');
+
+const sandboxes = [];
+function mkTmp() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-next-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('NEXT-CMD-1: run on fresh sandbox returns rule-1 JSON payload', () => {
+  const root = mkTmp();
+  const payload = nextCmd.run([], root);
+  assert.ok(payload.next_step);
+  assert.equal(payload.next_step.command, '/np:discuss-phase 1');
+  assert.equal(payload.task, null);
+  assert.equal(payload.phase, 1);
+});

package/bin/np-tools/park.cjs

@@ -0,0 +1,48 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError, projectStateDir } = require('../../lib/core.cjs');
+const { TASK_ID_RE, setTaskStatus } = require('../../lib/tasks.cjs');
+
+function _findPlanDirForTask(taskId, cwd) {
+  const phasesRoot = path.join(projectStateDir(cwd), 'phases');
+  let entries;
+  try {
+    entries = fs.readdirSync(phasesRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const padded = taskId.slice(0, 2);
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!(e.name === padded || e.name.startsWith(padded + '-'))) continue;
+    const candidate = path.join(phasesRoot, e.name, 'tasks', taskId + '.md');
+    if (fs.existsSync(candidate)) return path.join(phasesRoot, e.name);
+  }
+  return null;
+}
+
+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 taskId = list[0];
+  if (!taskId) {
+    throw new NubosPilotError('park-missing-task-id', 'park requires a task id', {});
+  }
+  if (!TASK_ID_RE.test(taskId)) {
+    throw new NubosPilotError('park-invalid-task-id', 'Invalid task id: ' + taskId, { taskId });
+  }
+  const planDir = _findPlanDirForTask(taskId, cwd);
+  if (!planDir) {
+    throw new NubosPilotError('task-not-found', 'No task file found for id ' + taskId, { taskId });
+  }
+  setTaskStatus(taskId, 'parked', planDir);
+  const payload = { ok: true, task_id: taskId, status: 'parked' };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

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

@@ -0,0 +1,50 @@
+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('./park.cjs');
+
+const _roots = [];
+
+function makeRoot(taskId) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-park-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  const tasksDir = path.join(root, '.nubos-pilot', 'phases', '06-demo', 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+  fs.writeFileSync(path.join(tasksDir, taskId + '.md'), [
+    '---', `id: ${taskId}`, 'phase: 6', 'plan: "06-01"', 'type: auto',
+    'status: pending', 'tier: sonnet', 'owner: np-executor', 'wave: 1',
+    'depends_on: []', 'files_modified: []', 'autonomous: true',
+    'must_haves:', '  truths: []', '---', '', '# T',
+  ].join('\n'), 'utf-8');
+  _roots.push(root);
+  return root;
+}
+
+function _capture() { let b = ''; return { stub: { write: (s) => { b += s; } }, get: () => b }; }
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('PK-1: park missing id', () => {
+  assert.throws(
+    () => subcmd.run([], { cwd: process.cwd(), stdout: _capture().stub }),
+    (err) => err && err.code === 'park-missing-task-id',
+  );
+});
+
+test('PK-2: park flips status to parked', () => {
+  const root = makeRoot('06-01-T02');
+  const cap = _capture();
+  subcmd.run(['06-01-T02'], { cwd: root, stdout: cap.stub });
+  const payload = JSON.parse(cap.get());
+  assert.equal(payload.status, 'parked');
+  const tf = path.join(root, '.nubos-pilot', 'phases', '06-demo', 'tasks', '06-01-T02.md');
+  assert.match(fs.readFileSync(tf, 'utf-8'), /^status: parked$/m);
+});

package/bin/np-tools/pause-work.cjs

@@ -0,0 +1,24 @@
+const { mutateState } = require('../../lib/state.cjs');
+
+function run(_args, ctx) {
+  const context = ctx || {};
+  const cwd = context.cwd || process.cwd();
+  const stdout = context.stdout || process.stdout;
+  const next = mutateState((s) => {
+    s.frontmatter.session = s.frontmatter.session || {};
+    s.frontmatter.session.stopped_at = new Date().toISOString();
+    s.frontmatter.session.resume_file = s.frontmatter.current_task
+      ? '.nubos-pilot/checkpoints/' + s.frontmatter.current_task + '.json'
+      : null;
+    return s;
+  }, cwd);
+  const payload = {
+    ok: true,
+    stopped_at: next.frontmatter.session.stopped_at,
+    resume_file: next.frontmatter.session.resume_file,
+  };
+  stdout.write(JSON.stringify(payload));
+  return payload;
+}
+
+module.exports = { run };

package/bin/np-tools/pause-work.test.cjs

@@ -0,0 +1,74 @@
+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('./pause-work.cjs');
+
+const _roots = [];
+
+function makeRoot(currentTask) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'np-pw-'));
+  fs.mkdirSync(path.join(root, '.nubos-pilot'), { recursive: true });
+  const ct = currentTask == null ? 'null' : currentTask;
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), `---
+schema_version: 2
+milestone: m1
+milestone_name: m1
+current_phase: 6
+current_plan: "06-01"
+current_task: ${ct}
+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 b = ''; return { stub: { write: (s) => { b += s; return true; } }, get: () => b }; }
+
+after(() => {
+  while (_roots.length) {
+    const r = _roots.pop();
+    try { fs.rmSync(r, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('PW-1: pause-work sets stopped_at and resume_file when current_task set', () => {
+  const root = makeRoot('06-01-T01');
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.ok, true);
+  assert.ok(/^\d{4}-\d{2}-\d{2}T/.test(p.stopped_at));
+  assert.equal(p.resume_file, '.nubos-pilot/checkpoints/06-01-T01.json');
+});
+
+test('PW-2: pause-work resume_file=null when no current_task', () => {
+  const root = makeRoot(null);
+  const cap = _capture();
+  const p = subcmd.run([], { cwd: root, stdout: cap.stub });
+  assert.equal(p.resume_file, null);
+  assert.ok(p.stopped_at);
+});
+
+test('PW-3: STATE.md on disk reflects the mutation', () => {
+  const root = makeRoot('06-01-T02');
+  const cap = _capture();
+  subcmd.run([], { cwd: root, stdout: cap.stub });
+  const body = fs.readFileSync(path.join(root, '.nubos-pilot', 'STATE.md'), 'utf-8');
+  assert.ok(/stopped_at: "?\d{4}-\d{2}-\d{2}T/.test(body), body);
+  assert.ok(body.includes('resume_file: .nubos-pilot/checkpoints/06-01-T02.json'), body);
+});