context-planning 0.7.0

package/bin/commands/codebase-status.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const codebaseMapper = require('../../lib/codebase-mapper');
+
+function run(args = []) {
+  const root = repoRoot();
+  let json = false;
+  for (const a of args) {
+    if (a === '--json') json = true;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+  const r = codebaseMapper.codebaseStatus(root);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+  if (!r.dirExists) {
+    console.log(`.planning/codebase/ not present — run \`cp scaffold-codebase\` first.`);
+    process.exit(1);
+  }
+  console.log(`Codebase dir: ${path.relative(root, r.codebaseDir)}`);
+  console.log('');
+  console.log('  status  focus     file              lines   bytes');
+  console.log('  ------  --------  ----------------  ------  ------');
+  for (const row of r.rows) {
+    let status;
+    if (!row.exists) status = 'missing';
+    else if (row.looksStub) status = 'stub   ';
+    else status = 'filled ';
+    const lines = row.exists ? String(row.lines).padStart(5) : '    -';
+    const bytes = row.exists ? String(row.bytes).padStart(5) : '    -';
+    console.log(`  ${status} ${row.focus.padEnd(8)}  ${row.file.padEnd(16)} ${lines}  ${bytes}`);
+  }
+  console.log('');
+  console.log(`All present:  ${r.allExist ? '✓' : '✗'}`);
+  console.log(`All filled:   ${r.allFilled ? '✓' : '✗ (run /cp-map-codebase)'}`);
+}
+
+module.exports = { name: 'codebase-status', run };

package/bin/commands/complete-milestone.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+
+function run(args = []) {
+  const root = repoRoot();
+  let name = null;
+  let dryRun = false;
+  let noCommit = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry-run') dryRun = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a === '--json') json = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else if (!name) name = a;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+
+  const r = lifecycle.completeMilestone(root, { name, dryRun, noCommit });
+
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    process.exit(r.ok ? 0 : 1);
+    return;
+  }
+
+  if (!r.ok) {
+    console.error(`complete-milestone: ${r.reason}`);
+    if (r.reason === 'incomplete') {
+      console.error(`\nMilestone "${r.milestone}" still has work to do:`);
+      for (const rep of r.verify.reports.filter(x => !x.ok)) {
+        console.error(`  Phase ${rep.phaseNum} ${rep.name}: plans ${rep.plansDone}/${rep.plansTotal} done; missing SUMMARY: ${rep.summariesMissing.join(', ') || '—'}`);
+      }
+    } else if (r.hint) {
+      console.error(r.hint);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Milestone:   ${r.milestone}`);
+  console.log(`Phases:      ${r.phases.join(', ')}`);
+  console.log(`Subsystems:  ${r.agg.subsystems.join(', ') || '—'}`);
+  console.log(`Files:       ${r.agg.filesCreated.length} created, ${r.agg.filesModified.length} modified`);
+  console.log(`\nActions${dryRun ? ' (dry-run)' : ''}:`);
+  for (const a of r.actions) {
+    const rel = path.relative(root, a.path);
+    const mark = a.kind === 'write' ? '✓' : a.kind === 'delete' ? '✗' : '·';
+    console.log(`  ${mark} ${a.kind.padEnd(6)} ${rel}${a.reason ? '  (' + a.reason + ')' : ''}`);
+  }
+  if (!dryRun && r.commit) console.log(`\nCommitted:   ${r.commit}`);
+}
+
+module.exports = { name: 'complete-milestone', run };

package/bin/commands/config.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('fs');
+const { repoRoot } = require('../../lib/paths');
+const provider = require('../../lib/provider');
+
+function run(args = []) {
+  const root = repoRoot();
+  const sub = args[0];
+
+  // refresh reads raw config directly — must NOT go through loadConfig's auto-heal
+  if (sub === 'refresh') {
+    const dryRun = args.includes('--dry-run');
+    const p = provider.configPath(root);
+    if (!fs.existsSync(p)) {
+      console.error('cp: no .planning/config.json found — run `cp init` first');
+      process.exit(1);
+    }
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const defaults = provider.loadDefaults();
+    const { mergeCpDefaults } = require('../../lib/merge');
+    const merged = mergeCpDefaults(raw, defaults);
+    if (!merged.changed) {
+      console.log('cp: config is already up to date with upstream defaults.');
+      return;
+    }
+    for (const c of merged.plannedChanges) {
+      console.log(`cp: ${dryRun ? 'would' : 'will'} add: ${c}`);
+    }
+    if (dryRun) {
+      console.log('(no changes written — use without --dry-run to apply)');
+      return;
+    }
+    fs.writeFileSync(p, JSON.stringify(merged.cfg, null, 2) + '\n');
+    console.log(`cp: refreshed .planning/config.json with ${merged.summary}`);
+    return;
+  }
+
+  // All other subcommands need loaded config
+  const cfg = provider.loadConfig(root);
+  if (sub === 'get') {
+    const key = args[1];
+    if (!key) {
+      console.log(JSON.stringify(cfg.cp || {}, null, 2));
+      return;
+    }
+    const v = provider.cpGet(cfg, key);
+    console.log(v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v, null, 2) : v);
+    return;
+  }
+  if (sub === 'set') {
+    const key = args[1];
+    let val = args[2];
+    if (!key) {
+      console.error('Usage: cp config set <key> <value>');
+      process.exit(2);
+    }
+    if (val === 'true') val = true;
+    else if (val === 'false') val = false;
+    else if (val !== '' && !isNaN(Number(val))) val = Number(val);
+    provider.cpSet(cfg, key, val);
+    provider.saveConfig(cfg, root);
+    console.log(`set cp.${key} = ${JSON.stringify(val)}`);
+    return;
+  }
+  console.error('Usage: cp config get [<key>] | set <key> <value> | refresh [--dry-run]');
+  process.exit(2);
+}
+
+module.exports = { name: 'config', run };

package/bin/commands/doctor.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const pkg = require('../../package.json');
+const { repoRoot, planningDir } = require('../../lib/paths');
+const provider = require('../../lib/provider');
+const compat = require('../../lib/gsd-compat');
+
+function run(args = []) {
+  const jsonMode = args.includes('--json');
+  const quiet = args.includes('--quiet');
+  const root = repoRoot();
+  const cfg = provider.loadConfig(root);
+  const cpBlock = cfg.cp || {};
+  const configured = cpBlock.workflow_provider || 'superpowers';
+  const detect = require('../../lib/detect');
+  const report = detect.detectAllInstalled(cfg);
+
+  // --json: machine-parsable full report
+  if (jsonMode) {
+    const roles = [
+      'brainstorm', 'plan', 'execute', 'review',
+      'finish', 'worktree', 'tdd', 'debug', 'verify',
+    ];
+    const resolvedRoles = {};
+    for (const role of roles) {
+      const rr = provider.resolveSkill(role, root);
+      resolvedRoles[role] = {
+        provider: rr.name,
+        skill: rr.skill,
+        installed: rr.installed,
+        fallback: !!rr.fallback,
+      };
+    }
+    const json = {
+      version: pkg.version,
+      root,
+      configured,
+      harnesses: report.harnesses,
+      providers: report.providers,
+      roles: resolvedRoles,
+    };
+    console.log(JSON.stringify(json, null, 2));
+    return;
+  }
+
+  // --quiet: minimal output (configured + roles only)
+  if (quiet) {
+    console.log(`Configured: ${configured}`);
+    const roles = [
+      'brainstorm', 'plan', 'execute', 'review',
+      'finish', 'worktree', 'tdd', 'debug', 'verify',
+    ];
+    for (const role of roles) {
+      const rr = provider.resolveSkill(role, root);
+      const tag = rr.fallback ? ` [fallback]` : '';
+      const skill = rr.skill || '(none)';
+      const mark = rr.installed ? '✓' : '✗';
+      console.log(`  ${mark} ${role.padEnd(10)} -> ${rr.name}/${skill}${tag}`);
+    }
+    return;
+  }
+
+  // Full sectioned output
+  const planningPresent = fs.existsSync(planningDir(root));
+  const schemaVersion = cpBlock.version || 1;
+
+  console.log(`cp v${pkg.version}  (invocable as \`cplan\` or \`cp\`)`);
+  console.log(`Repo root:    ${root}`);
+  console.log(
+    `.planning/:   ${planningPresent ? 'present' : 'missing (run `cp init`)'}`
+  );
+  console.log(`Config:       ${provider.configPath(root)}  (schema v${schemaVersion})`);
+
+  // Section 1: Harnesses
+  console.log(`\nHarnesses detected:`);
+  for (const h of report.harnesses) {
+    if (!h.scannedRoots.length || h.scannedRoots.every((r) => !r.root)) {
+      console.log(`  — ${h.name.padEnd(10)} (file-based — no plugin slot)`);
+    } else {
+      const rootSummaries = h.scannedRoots.map((r) => {
+        const shortRoot = r.root.replace(/^~\//, '~/');
+        return `${shortRoot} (${r.expanded.length} plugins)`;
+      }).join(', ');
+      const mark = h.pluginCount > 0 ? '✓' : '✗';
+      if (h.pluginCount > 0) {
+        console.log(`  ${mark} ${h.name.padEnd(10)} ${rootSummaries}`);
+      } else {
+        console.log(`  ${mark} ${h.name.padEnd(10)} (no plugins found at ${h.scannedRoots.map((r) => r.root).join(', ')})`);
+      }
+    }
+  }
+
+  // Section 2: Providers
+  console.log(`\nProviders detected:`);
+  for (const p of report.providers) {
+    if (p.installed) {
+      const hitDescs = p.hits.map((hit) => {
+        if (hit.source === 'always') return '(always available)';
+        return `via ${hit.via} @ ${hit.evidence ? path.basename(path.dirname(hit.evidence)) + '/' + path.basename(hit.evidence) : '?'}`;
+      });
+      console.log(`  ✓ ${p.name.padEnd(18)} ${hitDescs.join(', ')}`);
+    } else {
+      console.log(`  ✗ ${p.name.padEnd(18)} (not detected)`);
+    }
+  }
+
+  // Section 3: Configured
+  console.log(`\nConfigured workflow_provider:  ${configured}       [\`cp config set workflow_provider <name>\` to switch]`);
+
+  // Section 4: Roles
+  const roles = [
+    'brainstorm', 'plan', 'execute', 'review',
+    'finish', 'worktree', 'tdd', 'debug', 'verify',
+  ];
+  console.log(`\nRoles → resolved skill:`);
+  for (const role of roles) {
+    const rr = provider.resolveSkill(role, root);
+    const tag = rr.fallback ? ` [fallback from missing ${rr.primaryMissing}]` : '';
+    const skill = rr.skill || '(no mapping)';
+    const mark = rr.installed ? '✓' : '✗';
+    console.log(`  ${mark} ${role.padEnd(10)} -> ${rr.name}/${skill}${tag}`);
+  }
+
+  // Section 5: GSD compat
+  const r = compat.report(root);
+  console.log(`\nGSD compatibility:`);
+  console.log(`  cp-aware config:    ${r.cpAware ? '✓' : '✗'}`);
+  console.log(`  GSD sentinels:      ${r.gsdProject ? '✓ detected' : '— none'}`);
+  console.log(`  shared files:       ${r.sharedFiles.length ? r.sharedFiles.join(', ') : '— none'}`);
+  console.log(`  phase dirs:         ${r.phases.length}`);
+  if (r.warnings.length) {
+    console.log(`  warnings:`);
+    for (const w of r.warnings) console.log(`    - ${w}`);
+  }
+}
+
+module.exports = { name: 'doctor', run };

package/bin/commands/gsd-import.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const importer = require('../../lib/import');
+const init = require('./init');
+
+function resolveAuditRoot(rootArg) {
+  if (!rootArg) return repoRoot();
+  const abs = path.resolve(rootArg);
+  if (!fs.existsSync(abs)) {
+    console.error(`--root path does not exist: ${abs}`);
+    process.exit(2);
+  }
+  // Walk up from abs looking for .git or .planning, like repoRoot() does.
+  let dir = abs;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.planning'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return abs;
+}
+
+function run(args = []) {
+  let rootArg = null;
+  let json = false;
+  let apply = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--root') rootArg = args[++i];
+    else if (a === '--json') json = true;
+    else if (a === '--apply') apply = true;
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: cp gsd-import [--root <dir>] [--json] [--apply]
+
+Read-only audit of a planning project (defaults to the current repo). Reports
+GSD/cp compatibility, sentinel files, phase inventory, frontmatter health, and
+what \`cp init\` would change. Never modifies anything unless --apply.
+
+Options:
+  --root <dir>   Audit <dir> instead of the current repo (still searches up
+                 from <dir> for a .git or .planning marker)
+  --json         Emit the raw report as JSON instead of human-readable text
+  --apply        After printing the audit, run \`cp init\` against the target
+                 root (additive only — GSD files are never rewritten)
+
+Exit codes:
+  0   clean / nothing to do
+  1   errors found (parse failures or required files missing)
+  2   changes pending (run with --apply or \`cp init\` to apply)
+`);
+      return;
+    } else {
+      console.error(`unknown gsd-import option: ${a}`);
+      process.exit(2);
+    }
+  }
+
+  const target = resolveAuditRoot(rootArg);
+  const report = importer.audit(target);
+
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    process.stdout.write(importer.render(report));
+  }
+
+  if (apply) {
+    console.log('');
+    console.log(`--apply: running \`cp init\` against ${target} ...`);
+    console.log('');
+    const prevCwd = process.cwd();
+    process.chdir(target);
+    try {
+      init.run();
+    } finally {
+      process.chdir(prevCwd);
+    }
+    return;
+  }
+
+  process.exit(importer.exitCode(report));
+}
+
+module.exports = { name: 'gsd-import', run };

package/bin/commands/inbox.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+const inbox = require('../../lib/inbox');
+
+function run(args = []) {
+  let json = false;
+  let showAll = false;
+  let tickIdx = null;
+  let note = null;
+  let noCommit = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') json = true;
+    else if (a === '--all') showAll = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a === '--tick') {
+      tickIdx = args[++i];
+      if (tickIdx == null) { console.error('--tick requires <N>'); process.exit(2); }
+    } else if (a === '--note') {
+      note = args[++i];
+      if (note == null) { console.error('--note requires <destination>'); process.exit(2); }
+    } else { console.error(`unknown option: ${a}`); process.exit(2); }
+  }
+  const root = repoRoot();
+
+  if (tickIdx !== null) {
+    let r;
+    try { r = inbox.markTriaged(root, tickIdx, note); }
+    catch (e) { console.error(`inbox: ${e.message}`); process.exit(1); }
+    lifecycle.writeBatch(r.actions);
+    const destPart = r.item.destination ? ` → ${r.item.destination}` : '';
+    console.log(`✓ triaged${destPart}  [${r.item.ts}]  ${r.item.text}`);
+    if (!noCommit) {
+      const commit = lifecycle.gitCommit(root, `cp: triage inbox item${destPart}`, {
+        paths: lifecycle.pathsFromActions(r.actions),
+      });
+      if (commit) console.log(`committed ${commit}`);
+    }
+    return;
+  }
+
+  const state = inbox.listInbox(root);
+  if (json) {
+    console.log(JSON.stringify(state, null, 2));
+    return;
+  }
+
+  if (!state.exists) {
+    console.log(`Inbox is empty (no ${path.relative(root, state.path)} yet).`);
+    console.log(`Add an item:  cp capture "your idea here"`);
+    return;
+  }
+
+  console.log(`Inbox: ${path.relative(root, state.path)}`);
+  console.log(`Open: ${state.open.length}  Triaged: ${state.triaged.length}`);
+  console.log('');
+  if (state.open.length === 0) {
+    console.log('  (no open items — capture a new one with `cp capture "..."`)');
+  } else {
+    console.log('## Open');
+    for (const it of state.open) {
+      console.log(`  ${String(it.idx).padStart(3)}  [${it.ts}]  ${it.text}`);
+    }
+  }
+  if (showAll && state.triaged.length > 0) {
+    console.log('');
+    console.log('## Triaged');
+    for (const it of state.triaged) {
+      const dest = it.destination ? `→ ${it.destination}` : '→';
+      console.log(`  ${String(it.idx).padStart(3)}  [${it.ts}]  ${dest}  ${it.text}`);
+    }
+  } else if (!showAll && state.triaged.length > 0) {
+    console.log('');
+    console.log(`(${state.triaged.length} triaged item(s) hidden — use \`cp inbox --all\`)`);
+  }
+}
+
+module.exports = { name: 'inbox', run };

package/bin/commands/index.js

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Command registry — single source of truth for `cp <name>` lookup.
+ *
+ * Each module exports `{ name, run(args) }`.
+ *
+ * To add a new command:
+ *   1. Drop a file in this directory exporting `{ name, run }`.
+ *   2. Add an entry below.
+ *   3. Update `bin/commands/_usage.js` if it should appear in `cp help`.
+ */
+
+module.exports = {
+  version: require('./version'),
+  init: require('./init'),
+  doctor: require('./doctor'),
+  status: require('./status'),
+  tick: require('./tick'),
+  config: require('./config'),
+  'gsd-import': require('./gsd-import'),
+  install: require('./install'),
+  'write-summary': require('./write-summary'),
+  'scaffold-milestone': require('./scaffold-milestone'),
+  'scaffold-phase': require('./scaffold-phase'),
+  'scaffold-codebase': require('./scaffold-codebase'),
+  'codebase-status': require('./codebase-status'),
+  'complete-milestone': require('./complete-milestone'),
+  capture: require('./capture'),
+  inbox: require('./inbox'),
+  statusline: require('./statusline'),
+  worktree: require('./worktree'),
+};

package/bin/commands/init.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot, planningDir, ensureDir, readTemplate } = require('../../lib/paths');
+const provider = require('../../lib/provider');
+const compat = require('../../lib/gsd-compat');
+const { today, renderTemplate } = require('./_helpers');
+
+function run() {
+  const root = repoRoot();
+  const dir = planningDir(root);
+  ensureDir(dir);
+  ensureDir(path.join(dir, 'phases'));
+  ensureDir(path.join(dir, 'quick'));
+
+  const wasGsdProject = compat.isGsdProject(root);
+  const sharedPresent = compat.presentSharedFiles(root);
+
+  const files = [
+    ['PROJECT.md', 'PROJECT.md'],
+    ['ROADMAP.md', 'ROADMAP.md'],
+    ['STATE.md', 'STATE.md'],
+    ['MILESTONES.md', 'MILESTONES.md'],
+  ];
+
+  let created = 0;
+  for (const [target, tpl] of files) {
+    const dest = path.join(dir, target);
+    if (!fs.existsSync(dest)) {
+      const content = renderTemplate(readTemplate(tpl), {
+        PROJECT_NAME: path.basename(root),
+        DATE: today(),
+        TRIGGER: 'cp init',
+        CORE_VALUE: '(not set yet — fill PROJECT.md)',
+        CURRENT_PHASE_NAME: 'pre-planning',
+        PHASE_NUM: '0',
+        TOTAL_PHASES: '0',
+        PLAN_NUM: '0',
+        TOTAL_PLANS_IN_PHASE: '0',
+        STATUS: 'Ready to plan',
+        LAST_ACTIVITY: 'init',
+        CONTINUE_HERE_PATH_OR_NONE: 'None',
+        MILESTONE_NAME: 'v0.1 — first milestone',
+        PHASE_RANGE: '1',
+      });
+      fs.writeFileSync(dest, content);
+      created++;
+      console.log(`  + ${path.relative(root, dest)}`);
+    } else {
+      console.log(`  = ${path.relative(root, dest)} (exists, kept)`);
+    }
+  }
+
+  // config.json: merge-or-create.
+  const cfgPath = provider.configPath(root);
+  if (!fs.existsSync(cfgPath)) {
+    provider.saveConfig(provider.loadDefaults(), root);
+    console.log(`  + ${path.relative(root, cfgPath)}`);
+    created++;
+  } else {
+    // Merge cp.* if missing — loadConfig() does this automatically.
+    provider.loadConfig(root);
+    console.log(`  = ${path.relative(root, cfgPath)} (kept; cp block ensured)`);
+  }
+
+  console.log(`\n${created} new file(s).`);
+  if (wasGsdProject) {
+    console.log(
+      `\nDetected a GSD project (research/ / todos/ / seeds/ / REQUIREMENTS.md).`
+    );
+    console.log(
+      `cp wrote a 'cp' block into config.json but did not modify any GSD files.`
+    );
+    console.log(
+      `You can switch back to GSD any time; cp is additive only.`
+    );
+  } else if (sharedPresent.length > 0 && !wasGsdProject) {
+    console.log(
+      `\n${sharedPresent.length} shared file(s) detected — cp will treat this`
+    );
+    console.log(`as a GSD-compatible project.`);
+  }
+  console.log(`\nNext: edit .planning/PROJECT.md, then run /cp-new-milestone or /cp-plan-phase.`);
+}
+
+module.exports = { name: 'init', run };

package/bin/commands/install.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot, pluginRoot } = require('../../lib/paths');
+const { available } = require('./_helpers');
+
+function run(args = []) {
+  const harness = args[0];
+  if (!harness) {
+    console.error('Usage: cp install <copilot|claude|cursor|aider|echo-provider> [--force]');
+    process.exit(2);
+  }
+  const force = args.includes('--force');
+
+  // Special case: echo-provider installs to .planning/providers/
+  if (harness === 'echo-provider') {
+    const echoInstaller = require(path.join(pluginRoot(), 'install', 'echo-provider.js'));
+    const result = echoInstaller.install();
+    for (const r of result.results) {
+      console.log(`✓ ${r.file} (${r.status})`);
+    }
+    console.log('\necho-provider installed. Switch with:');
+    console.log('  cp config set workflow_provider echo-provider');
+    return;
+  }
+
+  let installer;
+  try {
+    installer = require(path.join(pluginRoot(), 'install', `${harness}.js`));
+  } catch (e) {
+    console.error(`Unknown harness: ${harness}`);
+    console.error(`Available: copilot${available('claude') ? ', claude' : ''}${available('cursor') ? ', cursor' : ''}${available('aider') ? ', aider' : ''}`);
+    process.exit(2);
+  }
+  const result = installer.install({ pluginRoot: pluginRoot(), repoRoot: repoRoot(), force });
+  // Non-zero exit when there are user-modified files we refused to overwrite
+  // (signals the caller — e.g. CI — that the install was incomplete).
+  if (result && Array.isArray(result.userModified) && result.userModified.length > 0 && !force) {
+    process.exitCode = 3;
+  }
+}
+
+module.exports = { name: 'install', run };