nubos-pilot 0.5.8 → 0.6.0

package/bin/install.js

@@ -17,6 +17,7 @@ const backupMod = require('../lib/install/backup.cjs');
 const registryMod = require('../lib/install/runtimes-registry.cjs');
 const runtimeAssetsMod = require('../lib/install/runtime-assets.cjs');
 const languageMod = require('../lib/language.cjs');
+const configDefaults = require('../lib/config-defaults.cjs');
 
 const cyan = '\x1b[36m', green = '\x1b[32m', yellow = '\x1b[33m',
       red = '\x1b[31m', blue = '\x1b[38;5;33m',
@@ -248,16 +249,11 @@ async function _runInitQuestions(detectedRuntime, askUser, flags) {
   const model_profile = (await askUser({ type: 'select', question: 'Model-Profile?',
     options: ['frontier', 'quality', 'balanced', 'budget', 'inherit'], default: 'frontier' })).value;
   const response_language = (await askUser({ type: 'input', question: 'Response language (ISO-639 code)?', default: 'en' })).value;
-  return {
+  return configDefaults.buildInstallConfig({
     runtime, runtimes, scope, mcp: !!f.mcp,
     model_profile,
     response_language,
-    commit_docs: true,
-    parallelization: true,
-    research: true,
-    plan_checker: true,
-    verifier: true,
-  };
+  });
 }
 
 function _repairCodexConfig() {

package/bin/np-tools/_commands.cjs

@@ -9,6 +9,7 @@ const COMMANDS = [
   { name: 'plan-milestone',      category: 'Planning', description: 'Plan a milestone: scaffolds slices + tasks' },
   { name: 'new-project',         category: 'Planning', description: 'Greenfield project init (PROJECT.md + REQUIREMENTS.md + M001 milestone)' },
   { name: 'new-milestone',       category: 'Planning', description: 'Append a new milestone (M<NNN>) to an existing project' },
+  { name: 'propose-milestones',  category: 'Planning', description: 'Re-plan all not-yet-done milestones: AI proposes add/update/remove from PROJECT.md + REQUIREMENTS.md' },
   { name: 'agent-skills',        category: 'Planning', description: 'Print agent_skills config for a given subagent' },
 
   { name: 'execute-milestone',   category: 'Execution', description: 'Wave-based milestone execution — slice by slice, tasks parallel within a slice' },
@@ -48,6 +49,7 @@ const COMMANDS = [
   { name: 'generate-slug',   category: 'Utility', description: 'Slugify text via lib/layout.cjs.slugify' },
   { name: 'stats',           category: 'Utility', description: 'Aggregated project stats (roadmap + STATE + git + metrics JSON shape)' },
   { name: 'detect-runtime',  category: 'Utility', description: 'Print detected runtime id (claude, codex, gemini, …) — reads config.json ∨ env ∨ default' },
+  { name: 'template-path',   category: 'Utility', description: 'Print absolute path to a package-shipped template by name (e.g. VALIDATION, milestone/CONTEXT)' },
 
   { name: 'thread',           category: 'Utility', description: 'Cross-session thread CRUD (create/resume under .nubos-pilot/threads/)' },
   { name: 'session-report',   category: 'Utility', description: 'Generate session report from metrics since .last-session pointer' },

package/bin/np-tools/commit.cjs

@@ -1,6 +1,7 @@
 const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
-const { NubosPilotError } = require('../../lib/core.cjs');
+const { NubosPilotError, findProjectRoot } = require('../../lib/core.cjs');
 const { assertCommittablePaths } = require('../../lib/git.cjs');
 const { resolveCommitArtifacts } = require('../../lib/commit-policy.cjs');
 
@@ -47,19 +48,34 @@ function _parseArgs(argv) {
   return { msg, files };
 }
 
-function _validateFiles(files) {
-  for (const f of files) {
+function _realpathOrResolve(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+
+function _normalizeFiles(files, cwd, root) {
+  const realRoot = _realpathOrResolve(root);
+  return files.map((f) => {
     if (typeof f !== 'string' || f.length === 0) {
       throw new NubosPilotError('commit-invalid-path', 'commit path must be non-empty string', { path: f });
     }
-    const segments = String(f).split(/[/\\]/);
-    for (const seg of segments) {
-      if (seg === '..') {
-        throw new NubosPilotError('commit-path-traversal', 'commit path must not contain ".." segments', { path: f });
-      }
+    const abs = path.isAbsolute(f) ? path.resolve(f) : path.resolve(cwd, f);
+    const realAbs = _realpathOrResolve(abs);
+    const rel = path.relative(realRoot, realAbs);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new NubosPilotError(
+        'commit-path-outside-project',
+        'commit path must resolve inside project root',
+        { path: f, root },
+      );
     }
-    if (path.isAbsolute(f)) {
-      throw new NubosPilotError('commit-path-absolute', 'commit path must be relative', { path: f });
+    return rel;
+  });
+}
+
+function _validateFiles(files) {
+  for (const f of files) {
+    if (typeof f !== 'string' || f.length === 0) {
+      throw new NubosPilotError('commit-invalid-path', 'commit path must be non-empty string', { path: f });
     }
   }
 }
@@ -87,13 +103,15 @@ function run(argv, ctx) {
       stdout.write(JSON.stringify({ committed: false, reason: 'commit_artifacts=false', files }) + '\n');
       return 0;
     }
-    const committable = assertCommittablePaths(files);
+    const root = findProjectRoot(cwd);
+    const normalized = _normalizeFiles(files, cwd, root);
+    const committable = assertCommittablePaths(normalized, { cwd: root });
     if (committable.length === 0) {
       throw new NubosPilotError('commit-no-paths', 'commit invoked with no committable paths', { files });
     }
-    execFileSync('git', ['add', '--', ...committable], { stdio: 'pipe' });
-    execFileSync('git', ['commit', '-m', msg, '--', ...committable], { stdio: 'pipe' });
-    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' }).trim();
+    execFileSync('git', ['add', '--', ...committable], { cwd: root, stdio: 'pipe' });
+    execFileSync('git', ['commit', '-m', msg, '--', ...committable], { cwd: root, stdio: 'pipe' });
+    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, encoding: 'utf-8' }).trim();
     stdout.write(JSON.stringify({ committed: true, sha, files: committable }) + '\n');
     return 0;
   } catch (err) {

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

@@ -57,12 +57,39 @@ test('COMMIT-1: happy path commits a single file and prints sha JSON', () => {
   assert.match(stdout.toString(), /"committed":\s*true/);
 });
 
-test('COMMIT-2: path with ".." segment rejected with commit-path-traversal', () => {
+test('COMMIT-2: path resolving outside project root rejected with commit-path-outside-project', () => {
+  const sb = makeSandbox();
+  initGit(sb);
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = commitCli.run(['feat: x', '--files', '../outside.txt'], { cwd: sb, stdout, stderr });
+  assert.equal(code, 1);
+  assert.match(stderr.toString(), /"code":\s*"commit-path-outside-project"/);
+});
+
+test('COMMIT-2b: absolute path inside project root is accepted and normalized', () => {
+  const sb = makeSandbox();
+  initGit(sb);
+  const absFile = path.join(sb, 'note.md');
+  fs.writeFileSync(absFile, 'hi\n');
+  const stdout = makeSink();
+  const stderr = makeSink();
+  const code = commitCli.run(['docs: note', '--files', absFile], { cwd: sb, stdout, stderr });
+  assert.equal(code, 0, 'stderr=' + stderr.toString());
+  assert.match(stdout.toString(), /"committed":\s*true/);
+});
+
+test('COMMIT-2c: absolute path outside project root rejected', () => {
+  const sb = makeSandbox();
+  initGit(sb);
+  const outside = path.join(os.tmpdir(), 'np-commit-outside-' + Date.now() + '.txt');
+  fs.writeFileSync(outside, 'x');
   const stdout = makeSink();
   const stderr = makeSink();
-  const code = commitCli.run(['feat: x', '--files', '../outside.txt'], { stdout, stderr });
+  const code = commitCli.run(['docs: x', '--files', outside], { cwd: sb, stdout, stderr });
+  try { fs.unlinkSync(outside); } catch {}
   assert.equal(code, 1);
-  assert.match(stderr.toString(), /"code":\s*"commit-path-traversal"/);
+  assert.match(stderr.toString(), /"code":\s*"commit-path-outside-project"/);
 });
 
 test('COMMIT-3: empty message prints usage and exits 1', () => {

package/bin/np-tools/propose-milestones.cjs

@@ -0,0 +1,461 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const YAML = require('yaml');
+
+const {
+  NubosPilotError,
+  atomicWriteFileSync,
+  withFileLock,
+} = require('../../lib/core.cjs');
+const layout = require('../../lib/layout.cjs');
+const { readState } = require('../../lib/state.cjs');
+const textMode = require('../../lib/text-mode.cjs');
+
+const TBD_RE = /<!--\s*TBD[^>]*-->/gi;
+const DONE_STATUSES = new Set(['done', 'complete', 'completed']);
+
+function _emit(stdout, payload) {
+  stdout.write(JSON.stringify(payload, null, 2));
+}
+
+function _guardInitialized(root) {
+  const projectMd = path.join(root, '.nubos-pilot', 'PROJECT.md');
+  if (!fs.existsSync(projectMd)) {
+    throw new NubosPilotError(
+      'project-not-initialized',
+      'PROJECT.md not found — run np:new-project first',
+      { hint: 'Run np:new-project first', path: projectMd },
+    );
+  }
+}
+
+function _readRoadmap(root) {
+  const p = path.join(root, '.nubos-pilot', 'roadmap.yaml');
+  if (!fs.existsSync(p)) {
+    throw new NubosPilotError(
+      'roadmap-missing',
+      'roadmap.yaml not found',
+      { path: p },
+    );
+  }
+  const raw = fs.readFileSync(p, 'utf-8');
+  let doc;
+  try { doc = YAML.parse(raw); } catch (err) {
+    throw new NubosPilotError(
+      'roadmap-parse-error',
+      'roadmap.yaml invalid YAML',
+      { path: p, cause: err && err.message },
+    );
+  }
+  if (!doc || !Array.isArray(doc.milestones)) {
+    throw new NubosPilotError(
+      'roadmap-parse-error',
+      'roadmap.yaml missing milestones array',
+      { path: p },
+    );
+  }
+  return { doc, path: p };
+}
+
+function _classifyMilestone(m, root, stateMilestoneId) {
+  if (!m || m.id === 'backlog') return null;
+  const status = typeof m.status === 'string' ? m.status : 'pending';
+  const isDone = DONE_STATUSES.has(status);
+  const slices = Array.isArray(m.slices) ? m.slices : [];
+  const hasSlices = slices.length > 0;
+
+  const mNumMatch = typeof m.id === 'string' ? m.id.match(/^M(\d+)$/) : null;
+  const mNum = mNumMatch ? Number(mNumMatch[1]) : (typeof m.number === 'number' ? m.number : null);
+
+  let contextSummary = null;
+  let contextHasContent = false;
+  if (mNum != null) {
+    const ctxPath = layout.milestoneContextPath(mNum, root);
+    if (fs.existsSync(ctxPath)) {
+      const raw = fs.readFileSync(ctxPath, 'utf-8');
+      const tbdSections = (raw.match(TBD_RE) || []).length;
+      const contentSections = (raw.match(/^<[a-z_]+>$/gm) || []).length;
+      contextHasContent = contentSections > 0 && tbdSections === 0;
+      contextSummary = {
+        path: ctxPath,
+        byte_size: raw.length,
+        tbd_sections: tbdSections,
+        content_sections: contentSections,
+        has_content: contextHasContent,
+      };
+    }
+  }
+
+  const isActive = stateMilestoneId && m.id === stateMilestoneId;
+
+  let classification;
+  if (isDone) classification = 'completed';
+  else if (hasSlices || isActive) classification = 'active';
+  else if (contextHasContent) classification = 'discussed';
+  else classification = 'empty';
+
+  return {
+    id: m.id,
+    number: mNum,
+    name: m.name || '',
+    goal: typeof m.goal === 'string' ? m.goal : '',
+    status,
+    classification,
+    slice_count: slices.length,
+    context: contextSummary,
+    touchable: classification === 'empty',
+    modification_requires_confirm: classification === 'active' || classification === 'discussed',
+  };
+}
+
+function _nextMilestoneNumber(doc) {
+  let maxNum = 0;
+  for (const m of doc.milestones || []) {
+    if (!m) continue;
+    if (m.id === 'backlog') continue;
+    if (typeof m.number === 'number' && Number.isInteger(m.number) && m.number > maxNum) {
+      maxNum = m.number;
+    }
+    if (typeof m.id === 'string') {
+      const mm = m.id.match(/^M(\d+)$/);
+      if (mm) {
+        const n = Number(mm[1]);
+        if (Number.isInteger(n) && n > maxNum) maxNum = n;
+      }
+    }
+  }
+  return maxNum + 1;
+}
+
+function _interviewPayload(cwd) {
+  const root = path.resolve(cwd);
+  _guardInitialized(root);
+  const { doc } = _readRoadmap(root);
+
+  let stateMilestoneId = null;
+  try {
+    const st = readState(root);
+    stateMilestoneId = st && st.frontmatter && st.frontmatter.milestone || null;
+  } catch {
+    stateMilestoneId = null;
+  }
+
+  const classified = [];
+  for (const m of doc.milestones) {
+    const row = _classifyMilestone(m, root, stateMilestoneId);
+    if (row) classified.push(row);
+  }
+
+  const projectMd = fs.readFileSync(path.join(root, '.nubos-pilot', 'PROJECT.md'), 'utf-8');
+  const reqPath = path.join(root, '.nubos-pilot', 'REQUIREMENTS.md');
+  const reqMd = fs.existsSync(reqPath) ? fs.readFileSync(reqPath, 'utf-8') : '';
+
+  const projectHasTbd = /_TBD — filled by \/np:discuss-project\._/.test(projectMd);
+
+  const tmDetail = textMode.resolveTextModeDetail(cwd);
+
+  return {
+    _workflow: 'propose-milestones',
+    mode: 'interview',
+    text_mode: tmDetail.enabled,
+    text_mode_source: tmDetail.source,
+    project_md_path: path.join(root, '.nubos-pilot', 'PROJECT.md'),
+    requirements_md_path: reqPath,
+    project_md: projectMd,
+    requirements_md: reqMd,
+    project_has_tbd: projectHasTbd,
+    current_state_milestone: stateMilestoneId,
+    milestones: classified,
+    next_milestone_number: _nextMilestoneNumber(doc),
+    guidance: {
+      completed: 'Untouchable — never modify or remove; displayed for context only.',
+      active: 'Has slices or is the current state pointer — modifications require explicit per-item confirm.',
+      discussed: 'Has non-TBD CONTEXT.md content — modifications require explicit per-item confirm.',
+      empty: 'No slices, CONTEXT.md still TBD — freely modifiable or removable.',
+    },
+  };
+}
+
+function _validateOperation(op, idx) {
+  if (!op || typeof op !== 'object') {
+    throw new NubosPilotError(
+      'invalid-operation',
+      'operation ' + idx + ' is not an object',
+      { index: idx },
+    );
+  }
+  const type = op.type;
+  if (!['add', 'update', 'remove'].includes(type)) {
+    throw new NubosPilotError(
+      'invalid-operation-type',
+      'operation ' + idx + ' has unknown type: ' + String(type),
+      { index: idx, type },
+    );
+  }
+  if (type === 'add') {
+    if (typeof op.milestone_name !== 'string' || op.milestone_name.trim() === '') {
+      throw new NubosPilotError('answers-missing-field', 'op[' + idx + '].milestone_name required', { index: idx });
+    }
+    if (typeof op.milestone_goal !== 'string' || op.milestone_goal.trim() === '') {
+      throw new NubosPilotError('answers-missing-field', 'op[' + idx + '].milestone_goal required', { index: idx });
+    }
+  } else {
+    if (typeof op.milestone_id !== 'string' || !/^M\d+$/.test(op.milestone_id)) {
+      throw new NubosPilotError('answers-missing-field', 'op[' + idx + '].milestone_id required (format M<NNN>)', { index: idx });
+    }
+    if (type === 'update') {
+      const hasName = typeof op.new_name === 'string' && op.new_name.trim() !== '';
+      const hasGoal = typeof op.new_goal === 'string' && op.new_goal.trim() !== '';
+      if (!hasName && !hasGoal) {
+        throw new NubosPilotError('answers-missing-field', 'op[' + idx + '] update needs new_name or new_goal', { index: idx });
+      }
+    }
+  }
+}
+
+function _findMilestone(doc, id) {
+  return doc.milestones.find((m) => m && m.id === id);
+}
+
+function _assertTouchable(m, opType, confirmForceModify) {
+  const status = typeof m.status === 'string' ? m.status : 'pending';
+  if (DONE_STATUSES.has(status)) {
+    throw new NubosPilotError(
+      'milestone-completed-untouchable',
+      'Milestone ' + m.id + ' is completed (status=' + status + ') — cannot ' + opType,
+      { id: m.id, status },
+    );
+  }
+  const slices = Array.isArray(m.slices) ? m.slices : [];
+  if (slices.length > 0 && !confirmForceModify) {
+    throw new NubosPilotError(
+      'milestone-has-slices',
+      'Milestone ' + m.id + ' has ' + slices.length + ' slice(s); ' + opType + ' requires confirm_force_modify=true',
+      { id: m.id, slice_count: slices.length },
+    );
+  }
+}
+
+function _applyAdd(doc, op) {
+  const mNum = _nextMilestoneNumber(doc);
+  const id = layout.mId(mNum);
+  doc.milestones.push({
+    id,
+    number: mNum,
+    name: op.milestone_name,
+    goal: op.milestone_goal,
+    status: 'pending',
+    requirements: [],
+    success_criteria: [],
+    slices: [],
+  });
+  return { type: 'add', id, number: mNum, name: op.milestone_name };
+}
+
+function _applyUpdate(doc, op) {
+  const m = _findMilestone(doc, op.milestone_id);
+  if (!m) {
+    throw new NubosPilotError('milestone-not-found', 'milestone ' + op.milestone_id + ' not found', { id: op.milestone_id });
+  }
+  _assertTouchable(m, 'update', op.confirm_force_modify === true);
+  const changed = {};
+  if (typeof op.new_name === 'string' && op.new_name.trim() !== '') {
+    changed.from_name = m.name;
+    m.name = op.new_name;
+    changed.to_name = m.name;
+  }
+  if (typeof op.new_goal === 'string' && op.new_goal.trim() !== '') {
+    changed.from_goal = m.goal;
+    m.goal = op.new_goal;
+    changed.to_goal = m.goal;
+  }
+  return { type: 'update', id: m.id, changed };
+}
+
+function _applyRemove(doc, op, root) {
+  const idx = doc.milestones.findIndex((m) => m && m.id === op.milestone_id);
+  if (idx < 0) {
+    throw new NubosPilotError('milestone-not-found', 'milestone ' + op.milestone_id + ' not found', { id: op.milestone_id });
+  }
+  const m = doc.milestones[idx];
+  _assertTouchable(m, 'remove', op.confirm_force_modify === true);
+  doc.milestones.splice(idx, 1);
+
+  let archivedTo = null;
+  const mNumMatch = m.id.match(/^M(\d+)$/);
+  if (mNumMatch) {
+    const mNum = Number(mNumMatch[1]);
+    const srcDir = layout.milestoneDir(mNum, root);
+    if (fs.existsSync(srcDir)) {
+      const archRoot = path.join(root, '.nubos-pilot', 'archive', 'milestones');
+      fs.mkdirSync(archRoot, { recursive: true });
+      const stamp = new Date().toISOString().slice(0, 10);
+      const target = path.join(archRoot, m.id + '-' + stamp);
+      fs.renameSync(srcDir, target);
+      archivedTo = target;
+    }
+  }
+  return { type: 'remove', id: m.id, archived_to: archivedTo };
+}
+
+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 },
+    );
+  }
+  if (!answers || !Array.isArray(answers.operations)) {
+    throw new NubosPilotError(
+      'answers-missing-field',
+      'answers.operations must be an array',
+      {},
+    );
+  }
+  answers.operations.forEach(_validateOperation);
+
+  const root = path.resolve(cwd);
+  _guardInitialized(root);
+
+  const roadmapPath = path.join(root, '.nubos-pilot', 'roadmap.yaml');
+  const results = withFileLock(roadmapPath, () => {
+    const rawYaml = fs.readFileSync(roadmapPath, 'utf-8');
+    let doc;
+    try { doc = YAML.parse(rawYaml); } catch (err) {
+      throw new NubosPilotError('roadmap-parse-error', 'roadmap.yaml invalid YAML', { path: roadmapPath, cause: err && err.message });
+    }
+    if (!doc || !Array.isArray(doc.milestones)) {
+      throw new NubosPilotError('roadmap-parse-error', 'roadmap.yaml missing milestones array', { path: roadmapPath });
+    }
+
+    const out = [];
+    for (const op of answers.operations) {
+      if (op.type === 'add') out.push(_applyAdd(doc, op));
+      else if (op.type === 'update') out.push(_applyUpdate(doc, op));
+      else if (op.type === 'remove') out.push(_applyRemove(doc, op, root));
+    }
+
+    atomicWriteFileSync(roadmapPath, YAML.stringify(doc, { indent: 2 }));
+
+    for (const result of out) {
+      if (result.type === 'add') {
+        _writeMilestoneArtefacts(root, result.number, result.name, doc);
+      }
+    }
+
+    return out;
+  });
+
+  _emit(stdout, {
+    mode: 'apply',
+    results,
+  });
+}
+
+function _writeMilestoneArtefacts(root, mNum, name, doc) {
+  const { _render, _loadTemplate } = _lazyRenderer();
+  const m = doc.milestones.find((x) => x && x.id === layout.mId(mNum));
+  const goal = m && m.goal || '';
+  layout.createMilestoneDir(mNum, root);
+  const mIdStr = layout.mId(mNum);
+  const createdDate = new Date().toISOString().slice(0, 10);
+  const ctxVars = {
+    milestone_id: mIdStr,
+    milestone_name: name,
+    created_date: createdDate,
+    goal_text: goal,
+    decisions_text: '<!-- TBD: locked decisions from /np:discuss-phase -->',
+    deferred_text: '<!-- TBD: deferred ideas -->',
+    domain_text: '<!-- TBD: domain boundary -->',
+    canonical_refs_text: '<!-- TBD: canonical references -->',
+  };
+  const roadmapVars = {
+    milestone_id: mIdStr,
+    milestone_name: name,
+    created_date: createdDate,
+    slices_text: '<!-- TBD: slices will be appended by /np:plan-phase ' + mNum + ' -->',
+  };
+  const metaVars = {
+    milestone_id: mIdStr,
+    milestone_name: JSON.stringify(name).slice(1, -1),
+    status: 'pending',
+    created_date: createdDate,
+    goal_text_escaped: JSON.stringify(goal).slice(1, -1),
+    requirements_json: '[]',
+    success_criteria_json: '[]',
+    slice_count: 0,
+    task_count: 0,
+  };
+  _writeFile(layout.milestoneContextPath(mNum, root), _render(_loadTemplate('CONTEXT.md'), ctxVars, 'milestone/CONTEXT.md'));
+  _writeFile(layout.milestoneRoadmapPath(mNum, root), _render(_loadTemplate('ROADMAP.md'), roadmapVars, 'milestone/ROADMAP.md'));
+  _writeFile(layout.milestoneMetaPath(mNum, root), _render(_loadTemplate('META.json'), metaVars, 'milestone/META.json'));
+}
+
+function _writeFile(target, content) {
+  if (path.basename(target) === 'PROJECT.md') {
+    throw new NubosPilotError(
+      'propose-milestones-forbidden-write',
+      'propose-milestones is never allowed to write PROJECT.md (D-29)',
+      { path: target },
+    );
+  }
+  atomicWriteFileSync(target, content);
+}
+
+function _lazyRenderer() {
+  const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'milestone');
+  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), 'utf-8');
+  }
+  return { _render, _loadTemplate };
+}
+
+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(cwd));
+}
+
+module.exports = { run, _interviewPayload };