context-planning 0.7.0

package/bin/commands/scaffold-codebase.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+const codebaseMapper = require('../../lib/codebase-mapper');
+
+function run(args = []) {
+  const root = repoRoot();
+  let dryRun = false;
+  let force = false;
+  let noCommit = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry-run') dryRun = true;
+    else if (a === '--force') force = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+
+  let r;
+  try {
+    r = codebaseMapper.scaffoldCodebase(root, { dryRun, force });
+  } catch (e) {
+    console.error(`scaffold-codebase: ${e.message}`);
+    process.exit(1);
+  }
+
+  for (const a of r.actions) {
+    const rel = path.relative(root, a.path);
+    const mark = dryRun ? '·' : (a.kind === 'mkdir' ? '+' : '✓');
+    console.log(`${mark} ${a.kind.padEnd(5)} ${rel}`);
+  }
+  if (r.skipped.length) {
+    console.log(`\nSkipped ${r.skipped.length} existing file(s) — use --force to overwrite:`);
+    for (const s of r.skipped) console.log(`  = ${s}`);
+  }
+  console.log(`\nCodebase dir: ${path.relative(root, r.codebaseDir)}`);
+  console.log(`Created:      ${r.created.length} stub(s)`);
+  if (dryRun) return;
+  if (!noCommit && r.actions.some((a) => a.kind === 'write' || a.kind === 'mkdir')) {
+    const commit = lifecycle.gitCommit(root, `cp: scaffold-codebase (${r.created.length} stubs)`, {
+      paths: lifecycle.pathsFromActions(r.actions),
+    });
+    if (commit) console.log(`committed     ${commit}`);
+  }
+  if (r.created.length > 0) {
+    console.log(`\nNext: run /cp-map-codebase to fill the stubs with a real analysis.`);
+  }
+}
+
+module.exports = { name: 'scaffold-codebase', run };

package/bin/commands/scaffold-milestone.js

@@ -0,0 +1,58 @@
+'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 status = 'in-progress';
+  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 === '--planned') status = 'planned';
+    else if (a === '--status') status = args[++i];
+    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); }
+  }
+  if (!name) {
+    console.error('Usage: cp scaffold-milestone <name> [--planned] [--no-commit] [--dry-run]');
+    process.exit(2);
+  }
+
+  let r;
+  try {
+    r = lifecycle.scaffoldMilestone(root, name, { dryRun, status });
+  } catch (e) {
+    console.error(`scaffold-milestone: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (!r.ok) {
+    console.error(`scaffold-milestone: ${r.reason}`);
+    if (r.reason === 'milestone-exists') {
+      console.error(`  "${r.milestone}" already exists (status: ${r.status}).`);
+    }
+    process.exit(1);
+  }
+
+  for (const a of r.actions) {
+    const rel = path.relative(root, a.path);
+    console.log(`${dryRun ? '·' : '✓'} ${rel}`);
+  }
+  console.log(`Milestone:   ${r.milestone} [${r.status}]`);
+  if (dryRun) return;
+  if (!noCommit) {
+    const commit = lifecycle.gitCommit(root, `cp: scaffold-milestone ${r.milestone}`, {
+      paths: lifecycle.pathsFromActions(r.actions),
+    });
+    if (commit) console.log(`committed ${commit}`);
+  }
+}
+
+module.exports = { name: 'scaffold-milestone', run };

package/bin/commands/scaffold-phase.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+
+function run(args = []) {
+  const root = repoRoot();
+  let num = null;
+  let name = null;
+  let plans = 0;
+  let milestoneName = null;
+  let dryRun = false;
+  let noCommit = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--name') name = args[++i];
+    else if (a === '--plans') plans = parseInt(args[++i], 10) || 0;
+    else if (a === '--milestone') milestoneName = args[++i];
+    else if (a === '--dry-run') dryRun = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else if (!num) num = a;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+  if (!num || !name) {
+    console.error('Usage: cp scaffold-phase <N> --name <name> [--plans <count>] [--milestone <name>] [--no-commit] [--dry-run]');
+    process.exit(2);
+  }
+
+  let r;
+  try {
+    r = lifecycle.scaffoldPhase(root, num, { dryRun, name, plans, milestone: milestoneName });
+  } catch (e) {
+    console.error(`scaffold-phase: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (!r.ok) {
+    console.error(`scaffold-phase: ${r.reason}`);
+    if (r.reason === 'phase-exists') {
+      console.error(`  ${path.relative(root, r.phaseDir)} already exists.`);
+    } else if (r.reason === 'milestone-not-found') {
+      console.error(`  No milestone named "${milestoneName}" in ROADMAP.md.`);
+    } else if (r.reason === 'no-active-milestone') {
+      console.error(`  No in-progress milestone. Run \`cp scaffold-milestone <name>\` first or pass --milestone.`);
+    }
+    process.exit(1);
+  }
+
+  for (const a of r.actions) {
+    const rel = path.relative(root, a.path);
+    console.log(`${dryRun ? '·' : '✓'} ${rel}`);
+  }
+  console.log(`Phase ${r.phaseNum} added to milestone "${r.milestone}"${r.plans.length ? ` (${r.plans.length} plan${r.plans.length === 1 ? '' : 's'}: ${r.plans.join(', ')})` : ''}`);
+  if (dryRun) return;
+  if (!noCommit) {
+    const commit = lifecycle.gitCommit(root, `cp: scaffold-phase ${r.phaseNum} (${name})`, {
+      paths: lifecycle.pathsFromActions(r.actions),
+    });
+    if (commit) console.log(`committed ${commit}`);
+  }
+}
+
+module.exports = { name: 'scaffold-phase', run };

package/bin/commands/status.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const pkg = require('../../package.json');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+
+function run(args = []) {
+  const root = repoRoot();
+  const json = args.includes('--json');
+  const r = lifecycle.statusReport(root);
+  if (json) {
+    console.log(JSON.stringify(r, null, 2));
+    process.exit(r.ok ? 0 : 1);
+    return;
+  }
+  if (!r.ok) {
+    console.error(r.error);
+    process.exit(1);
+  }
+  console.log(`cp v${pkg.version}`);
+  console.log(`Repo:        ${root}`);
+  console.log(`Milestone:   ${r.milestone || '(none in-progress)'}${r.milestoneStatus ? ` [${r.milestoneStatus}]` : ''}`);
+  if (r.phases.length === 0) {
+    console.log('Phases:      (none yet — run `/cp-plan-phase 1`)');
+  } else {
+    console.log('Phases:');
+    for (const p of r.phases) {
+      const bar = p.total > 0 ? `${p.done}/${p.total}` : '0/0';
+      const mark = p.total > 0 && p.done === p.total ? '✓' : '·';
+      console.log(`  ${mark} Phase ${p.num} ${p.name}: ${bar} plans done`);
+    }
+  }
+  if (r.nextPlan) {
+    console.log(`\nNext plan:   ${r.nextPlan.planId} (Phase ${r.nextPlan.phaseNum}: ${r.nextPlan.phaseName})`);
+    console.log(`             ${r.nextPlan.desc}`);
+    console.log(`\nDo:          /cp-execute-phase ${r.nextPlan.phaseNum}`);
+  } else if (r.milestone) {
+    console.log(`\nAll plans done. Run \`cp complete-milestone\` (or \`/cp-complete-milestone\`).`);
+  }
+}
+
+module.exports = { name: 'status', run };

package/bin/commands/statusline.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot, planningDir } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+
+function run(args = []) {
+  let format = null;
+  let json = false;
+  let noColor = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') json = true;
+    else if (a === '--no-color') noColor = true;
+    else if (a === '--format') {
+      format = args[++i];
+      if (format == null) { console.error('--format requires a value'); process.exit(2); }
+    } else { console.error(`unknown option: ${a}`); process.exit(2); }
+  }
+
+  // Stay silent outside a cp/git project. Used in shell prompts — must never
+  // emit noise that breaks PS1.
+  let root;
+  try { root = repoRoot(); }
+  catch { process.exit(0); }
+  const planning = planningDir(root);
+  if (!fs.existsSync(path.join(planning, 'ROADMAP.md'))) process.exit(0);
+
+  let r;
+  try { r = lifecycle.statusReport(root); }
+  catch { process.exit(0); }
+  if (!r.ok) process.exit(0);
+
+  // Compute the active phase: first phase with done < total. Fall back to
+  // last phase if all done.
+  let activePhase = r.phases.find((p) => p.done < p.total);
+  if (!activePhase && r.phases.length > 0) activePhase = r.phases[r.phases.length - 1];
+
+  const phaseLabel = activePhase
+    ? `${String(activePhase.num).padStart(2, '0')}-${activePhase.name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')}`
+    : null;
+  const doneTotal = activePhase ? `${activePhase.done}/${activePhase.total}` : null;
+  const nextId = r.nextPlan ? r.nextPlan.planId : null;
+
+  // Try to grab the current git branch (best-effort, silent on failure).
+  let branch = '';
+  try {
+    branch = require('child_process')
+      .execSync('git rev-parse --abbrev-ref HEAD', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString().trim();
+  } catch { branch = ''; }
+
+  if (json) {
+    console.log(JSON.stringify({
+      milestone: r.milestone,
+      milestoneStatus: r.milestoneStatus,
+      phase: activePhase ? { num: activePhase.num, name: activePhase.name, label: phaseLabel, done: activePhase.done, total: activePhase.total } : null,
+      nextPlan: r.nextPlan,
+      branch,
+    }, null, 2));
+    return;
+  }
+
+  // Color helpers (ANSI). Detection is conservative: only emit when stdout
+  // is a TTY AND --no-color was NOT passed AND NO_COLOR env is unset.
+  const useColor = !noColor && process.stdout.isTTY && !process.env.NO_COLOR;
+  const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+  const dim = (s) => c('2', s);
+  const bold = (s) => c('1', s);
+  const cyan = (s) => c('36', s);
+  const green = (s) => c('32', s);
+  const yellow = (s) => c('33', s);
+
+  // Custom format support: %M %P %D %N %B tokens.
+  if (format) {
+    const out = format
+      .replace(/%M/g, r.milestone || '')
+      .replace(/%P/g, phaseLabel || '')
+      .replace(/%D/g, doneTotal || '')
+      .replace(/%N/g, nextId || '')
+      .replace(/%B/g, branch || '');
+    console.log(out);
+    return;
+  }
+
+  // Default format. Examples:
+  //   cp ▸ v0.4 ▸ 02-mvp 1/3 → 02-02
+  //   cp ▸ v0.4 ▸ ✓ done
+  //   cp ▸ (no milestone)
+  const arrow = dim('▸');
+  const prefix = bold(cyan('cp'));
+  if (!r.milestone) {
+    console.log(`${prefix} ${arrow} ${dim('(no milestone)')}`);
+    return;
+  }
+  const mPart = green(r.milestone);
+  if (!activePhase) {
+    console.log(`${prefix} ${arrow} ${mPart}`);
+    return;
+  }
+  const phasePart = activePhase.done >= activePhase.total
+    ? `${green('✓')} ${dim('done')}`
+    : `${yellow(phaseLabel)} ${dim(doneTotal)}${nextId ? ' ' + arrow + ' ' + cyan(nextId) : ''}`;
+  console.log(`${prefix} ${arrow} ${mPart} ${arrow} ${phasePart}`);
+}
+
+module.exports = { name: 'statusline', run };

package/bin/commands/tick.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const lifecycle = require('../../lib/lifecycle');
+
+function run(args = []) {
+  const root = repoRoot();
+  let planId = null;
+  let undo = false;
+  let noCommit = false;
+  let dryRun = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--undo') undo = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a === '--dry-run') dryRun = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else if (!planId) planId = a;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+  if (!planId) { console.error('Usage: cp tick <plan-id> [--undo] [--no-commit] [--dry-run]'); process.exit(2); }
+
+  let result;
+  try {
+    result = lifecycle.tickPlan(root, planId, { dryRun, done: !undo });
+  } catch (e) {
+    console.error(`tick: ${e.message}`);
+    process.exit(1);
+  }
+  for (const a of result.actions) {
+    const rel = path.relative(root, a.path);
+    console.log(`${dryRun ? '·' : '✓'} ${rel}`);
+  }
+  if (result.actions.length === 0) {
+    console.log(`(no change — plan ${planId} already ${undo ? 'unticked' : 'ticked'})`);
+    return;
+  }
+  if (dryRun) return;
+  if (!noCommit) {
+    const verb = undo ? 'untick' : 'tick';
+    const commit = lifecycle.gitCommit(root, `cp: ${verb} plan ${planId}`, {
+      paths: lifecycle.pathsFromActions(result.actions),
+    });
+    if (commit) console.log(`committed ${commit}`);
+  }
+}
+
+module.exports = { name: 'tick', run };

package/bin/commands/version.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const pkg = require('../../package.json');
+
+function run() {
+  console.log(pkg.version);
+}
+
+module.exports = { name: 'version', run };

package/bin/commands/worktree.js

@@ -0,0 +1,218 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const provider = require('../../lib/provider');
+const lifecycle = require('../../lib/lifecycle');
+const worktree = require('../../lib/worktree');
+
+// Best-effort canonical path: collapses Windows short names (FOO~1) and
+// resolves symlinks. Falls back to path.resolve() if the path doesn't
+// exist (which can happen for registry entries whose worktree was
+// removed externally).
+//
+// On Windows, the JS realpathSync historically preserves 8.3 short
+// names while realpathSync.native (GetFinalPathNameByHandle) expands
+// them. Try .native first.
+function canonical(p) {
+  const realNative = fs.realpathSync.native;
+  if (realNative) {
+    try { return realNative(p); } catch { /* fall through */ }
+  }
+  try { return fs.realpathSync(p); }
+  catch { return path.resolve(p); }
+}
+
+function samePath(a, b) {
+  const ca = canonical(a);
+  const cb = canonical(b);
+  if (process.platform === 'win32') {
+    return ca.toLowerCase() === cb.toLowerCase();
+  }
+  return ca === cb;
+}
+
+function runCreate(args, root) {
+  let name = null;
+  let branch = null;
+  let from = null;
+  let wpath = null;
+  let phase = null;
+  let noCreate = false;
+  let noCommit = false;
+  let dryRun = false;
+  let useProvider = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--branch') branch = args[++i];
+    else if (a === '--from') from = args[++i];
+    else if (a === '--path') wpath = args[++i];
+    else if (a === '--phase') phase = args[++i];
+    else if (a === '--no-create') noCreate = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a === '--dry-run') dryRun = true;
+    else if (a === '--use-provider') useProvider = 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); }
+  }
+  if (!name) { console.error('Usage: cp worktree create <name> [--branch <b>] [--from <base>] [--path <dir>] [--phase <N>]'); process.exit(2); }
+
+  const slug = worktree.slugify(name);
+  const finalPath = wpath ? path.resolve(wpath) : worktree.defaultWorktreePath(root, slug);
+  const finalBranch = branch || worktree.defaultBranchName(slug);
+
+  // Provider delegation: when --use-provider is set, resolve the worktree
+  // role and emit a hand-off line. The harness is responsible for
+  // invoking the named skill; cp still records the registry entry so
+  // future `cp worktree list` shows it.
+  if (useProvider) {
+    const skill = provider.resolveSkill('worktree', root);
+    if (skill.installed && skill.skill) {
+      console.log(`Provider hand-off:`);
+      console.log(`  provider: ${skill.name}${skill.fallback ? ' (fallback)' : ''}`);
+      console.log(`  skill:    ${skill.skill}`);
+      console.log(`  invoke:   load the "${skill.skill}" skill, then run:`);
+      console.log(`              git worktree add ${finalPath} -b ${finalBranch}${from ? ' ' + from : ''}`);
+      console.log(`  registry: cp will record .planning/WORKTREES.md when you re-run without --use-provider`);
+      console.log(`  (cp did NOT create the worktree itself — provider in charge)`);
+      process.exitCode = 0;
+      return;
+    }
+    console.error(`--use-provider: no worktree skill available (configured: ${skill.name}, installed: ${skill.installed}).`);
+    console.error(`Falling back to cp-native worktree creation. Re-run without --use-provider to silence this message.`);
+  }
+
+  // Native path: shell out via lib/worktree.runGitWorktreeAdd (v0.4.4).
+  const created = worktree.isoDay();
+  if (!noCreate && !dryRun) {
+    const r = worktree.runGitWorktreeAdd(root, { worktreePath: finalPath, branch: finalBranch, from });
+    if (r.status !== 0) {
+      const gitArgs = ['worktree', 'add', finalPath, '-b', finalBranch].concat(from ? [from] : []);
+      console.error(`git ${gitArgs.join(' ')} failed:`);
+      if (r.stdout) process.stderr.write(r.stdout);
+      if (r.stderr) process.stderr.write(r.stderr);
+      process.exit(1);
+    }
+    process.stdout.write(r.stdout || '');
+  } else if (noCreate) {
+    console.log(`(--no-create) skipping git worktree add ${finalPath} -b ${finalBranch}${from ? ' ' + from : ''}`);
+  } else {
+    console.log(`(dry-run) would run: git worktree add ${finalPath} -b ${finalBranch}${from ? ' ' + from : ''}`);
+  }
+
+  const entry = {
+    slug,
+    branch: finalBranch,
+    path: finalPath,
+    phase: phase || null,
+    created,
+    notes: '',
+  };
+
+  const r = worktree.addRegistryEntry(root, entry);
+  if (r.alreadyPresent) {
+    console.log(`(note: an entry for slug "${slug}" was already in WORKTREES.md — updated path/branch in place)`);
+  }
+  if (dryRun) {
+    console.log(`(dry-run) would update ${path.relative(root, worktree.worktreesPath(root))}`);
+    return;
+  }
+  lifecycle.writeBatch(r.actions);
+  console.log(`✓ worktree registered:  ${slug}  →  ${finalPath}  (branch ${finalBranch})`);
+
+  if (!noCommit) {
+    const commit = lifecycle.gitCommit(root, `cp: register worktree ${slug}`, {
+      paths: lifecycle.pathsFromActions(r.actions),
+    });
+    if (commit) console.log(`committed ${commit}`);
+  }
+}
+
+function runList(args, root) {
+  const json = args.includes('--json');
+  const entries = worktree.listRegistry(root);
+
+  // Cross-reference with git's view via lib/worktree.listGitWorktrees (v0.4.4).
+  const gitTrees = worktree.listGitWorktrees(root);
+
+  if (json) {
+    console.log(JSON.stringify({ registered: entries, git: gitTrees }, null, 2));
+    return;
+  }
+
+  if (entries.length === 0) {
+    console.log(`No cp-tracked worktrees yet.`);
+    console.log(`Create one with:  cp worktree create <name>`);
+    return;
+  }
+
+  console.log(`Registered worktrees (.planning/WORKTREES.md):`);
+  for (const e of entries) {
+    const onDisk = gitTrees.find((g) => samePath(g.path, e.path));
+    const status = onDisk ? '✓ on disk' : '✗ missing';
+    console.log(`  ${e.slug.padEnd(20)} ${e.branch.padEnd(28)} ${status}`);
+    console.log(`    ${e.path}${e.phase ? '  [phase ' + e.phase + ']' : ''}`);
+  }
+}
+
+function runRemove(args, root) {
+  let slug = null;
+  let force = false;
+  let noCommit = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--force') force = true;
+    else if (a === '--no-commit') noCommit = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else if (!slug) slug = a;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+  if (!slug) { console.error('Usage: cp worktree remove <slug> [--force]'); process.exit(2); }
+
+  const r = worktree.removeRegistryEntry(root, slug);
+  if (!r.removed) {
+    console.error(`No worktree registered under slug "${slug}". Run \`cp worktree list\` to see slugs.`);
+    process.exit(1);
+  }
+
+  // Shell out via lib/worktree.runGitWorktreeRemove (v0.4.4).
+  const gr = worktree.runGitWorktreeRemove(root, { worktreePath: r.removed.path, force });
+  if (gr.status !== 0) {
+    const gitArgs = ['worktree', 'remove'].concat(force ? ['--force'] : []).concat([r.removed.path]);
+    console.error(`git ${gitArgs.join(' ')} failed:`);
+    if (gr.stdout) process.stderr.write(gr.stdout);
+    if (gr.stderr) process.stderr.write(gr.stderr);
+    console.error(`\n(Registry entry NOT removed. Pass --force to remove anyway, or clean up the worktree first.)`);
+    process.exit(1);
+  }
+  if (gr.stdout) process.stdout.write(gr.stdout);
+
+  lifecycle.writeBatch(r.actions);
+  console.log(`✓ worktree removed:  ${slug}  (${r.removed.path})`);
+
+  if (!noCommit) {
+    const commit = lifecycle.gitCommit(root, `cp: remove worktree ${slug}`, {
+      paths: lifecycle.pathsFromActions(r.actions),
+    });
+    if (commit) console.log(`committed ${commit}`);
+  }
+}
+
+function run(args = []) {
+  const sub = args.shift();
+  if (!sub) {
+    console.error('Usage: cp worktree <create|list|remove> [...]');
+    process.exit(2);
+  }
+  const root = repoRoot();
+
+  if (sub === 'create') return runCreate(args, root);
+  if (sub === 'list')   return runList(args, root);
+  if (sub === 'remove' || sub === 'rm') return runRemove(args, root);
+  console.error(`Unknown worktree subcommand: ${sub}`);
+  process.exit(2);
+}
+
+module.exports = { name: 'worktree', run };

package/bin/commands/write-summary.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { repoRoot } = require('../../lib/paths');
+const milestone = require('../../lib/milestone');
+
+function run(args = []) {
+  const root = repoRoot();
+  let planId = null;
+  let fromPath = null;
+  let bodyPath = null;
+  let overwrite = false;
+  let dryRun = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--from') fromPath = args[++i];
+    else if (a === '--body') bodyPath = args[++i];
+    else if (a === '--overwrite') overwrite = true;
+    else if (a === '--dry-run') dryRun = true;
+    else if (a.startsWith('-')) { console.error(`unknown option: ${a}`); process.exit(2); }
+    else if (!planId) planId = a;
+    else { console.error(`unexpected arg: ${a}`); process.exit(2); }
+  }
+  if (!planId || !fromPath) {
+    console.error('Usage: cp write-summary <plan-id> --from <json> [--body <md>] [--overwrite] [--dry-run]');
+    process.exit(2);
+  }
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(fromPath, 'utf8'));
+  } catch (e) {
+    console.error(`failed to read JSON from ${fromPath}: ${e.message}`);
+    process.exit(1);
+  }
+  const body = bodyPath ? fs.readFileSync(bodyPath, 'utf8') : undefined;
+  let r;
+  try {
+    r = milestone.writeSummary(root, planId, data, { dryRun, body, overwrite });
+  } catch (err) {
+    if (err && (err.name === 'ValidationError' || err.code === 'EVALIDATION')) {
+      process.stderr.write(err.message + '\n');
+      process.exit(2);
+    }
+    throw err;
+  }
+  console.log(`${dryRun ? '·' : '✓'} ${path.relative(root, r.path)}`);
+  if (dryRun) {
+    console.log('--- normalised frontmatter ---');
+    console.log(JSON.stringify(r.fm, null, 2));
+  }
+}
+
+module.exports = { name: 'write-summary', run };

package/bin/cp.cmd

@@ -0,0 +1,2 @@
+@ECHO off
+node "%~dp0cp.js" %*