@hanzlaa/rcode 4.4.3 → 4.5.0

package/rcode/bin/rcode-tools.cjs

@@ -1031,12 +1031,42 @@ function cmdState(subArgs) {
     }
     try {
       const raw = JSON.parse(fs.readFileSync(statePath, 'utf8'));
-      return migrateState(raw);
+      const migrated = migrateState(raw);
+      // One-time idempotent status migration (#955): persist the normalized
+      // phase statuses back to disk the first time legacy aliases are found,
+      // so state.json itself becomes canonical and every other reader (e.g.
+      // resolveActivePhase() in state-reader.cjs, which reads the file
+      // directly rather than through this helper) sees clean values too.
+      // Idempotent: once written, raw already matches migrated and this is a
+      // no-op on every subsequent load.
+      const rawPhases = Array.isArray(raw?.phases) ? raw.phases : [];
+      const migratedPhases = Array.isArray(migrated?.phases) ? migrated.phases : [];
+      const hasLegacyStatus = rawPhases.some((p, i) => p?.status !== migratedPhases[i]?.status);
+      if (hasLegacyStatus) {
+        writeState(migrated);
+      }
+      return migrated;
     } catch (e) {
       throw new Error(`Invalid JSON in state.json: ${e.message}`);
     }
   }
 
+  // Canonical phase status enum (#955). Legacy state files accumulated four
+  // spellings for the same three states — normalize on every read so callers
+  // never have to special-case 'completed'/'executed' against 'complete'.
+  const PHASE_STATUS_ALIASES = {
+    completed: 'complete',
+    executed: 'complete',
+    verified: 'complete',
+  };
+  const PHASE_STATUS_ENUM = new Set(['planned', 'executing', 'complete']);
+
+  /** Map a legacy status spelling to the canonical enum value (idempotent). */
+  function normalizePhaseStatus(status) {
+    if (typeof status !== 'string') return status;
+    return PHASE_STATUS_ALIASES[status] ?? status;
+  }
+
   /**
    * migrateState — pure normalizer that upgrades any legacy state shape to v2.
    *
@@ -1081,7 +1111,7 @@ function cmdState(subArgs) {
           number: number ?? p.id ?? null,
           id: id ?? null,
           name: p.name ?? null,
-          status: p.status ?? 'planned',
+          status: normalizePhaseStatus(p.status ?? 'planned'),
           started: p.started ?? null,
           completed: p.completed ?? null,
           sprints: Array.isArray(p.sprints) ? p.sprints : [],
@@ -2278,12 +2308,16 @@ function cmdState(subArgs) {
     }
 
     writeState(state);
+    // #942 — surface the milestone close nudge for inserted phases too.
+    const insHealth = milestoneCloseNudge();
     return {
       ok: true,
       phase_number: phaseNumber,
       name: phaseName,
       slug: slug,
       directory: path.join(PLANNING_DIR, 'phases', `${phaseNumber}-${slug}`),
+      milestone_health: insHealth.milestone_health,
+      ...(insHealth.nudge ? { nudge: insHealth.nudge } : {}),
     };
   }
 
@@ -3173,10 +3207,36 @@ function cmdState(subArgs) {
     if (previousStatus === 'planned') {
       process.stderr.write(`Warning: completing phase ${phaseKey} from 'planned' without executing.\n`);
     }
+
+    // State-hygiene gate (#955): if an earlier-numbered phase is still stuck
+    // 'executing' while this later phase gets marked complete, that's exactly
+    // the drift that misorients resolveActivePhase() / the SessionStart greeter.
+    // Warn rather than block — completing out of order is sometimes correct
+    // (parallel workstreams), but it must never happen silently.
+    const thisNum = parseFloat(phaseKey);
+    const stalePhases = Number.isNaN(thisNum) ? [] : state.phases.filter((p) => {
+      if (!p || p.status !== 'executing') return false;
+      const n = parseFloat(p.number ?? p.id);
+      return !Number.isNaN(n) && n < thisNum;
+    });
+    if (stalePhases.length > 0 && !flags.force) {
+      const staleList = stalePhases.map((p) => p.number ?? p.id).join(', ');
+      process.stderr.write(
+        `Warning: phase ${phaseKey} marked complete while earlier phase(s) ${staleList} are still 'executing'. ` +
+        `Use --force to suppress this warning, or close out the stale phase(s) first.\n`
+      );
+    }
+
     entry.status = 'complete';
     entry.completed = new Date().toISOString();
     writeState(state);
-    return { updated: true, phase: phaseKey, status: 'complete', previous_status: previousStatus };
+    return {
+      updated: true,
+      phase: phaseKey,
+      status: 'complete',
+      previous_status: previousStatus,
+      stale_executing_phases: stalePhases.map((p) => p.number ?? p.id),
+    };
   }
 
   // Truncates execution state but preserves decisions, council_sessions, and workstreams.
@@ -3734,22 +3794,30 @@ function cmdPhase(subArgs) {
       // value at the scales we operate. Applies to phases, sprints, epics, stories,
       // tasks, decisions across all artifacts (dirs, ROADMAP, state.json, banners).
 
-      // #583 sanity guard: prevent phantom phase numbers caused by stale high-number
-      // entries in ROADMAP.md or phases/ (e.g. a prior phantom "## Phase 1009" left
-      // in ROADMAP triggers the next add to produce 1010). If computed next is more
-      // than 50 above the count of currently tracked phases, the maxNum source is
-      // suspect. Abort and require an explicit --number N to override.
-      const trackedCount = state.phases.filter(p => {
-        const n = parseInt(String(p.number || ''), 10);
-        return !Number.isNaN(n) && n > 0;
-      }).length;
-      if (next > trackedCount + 50) {
+      // #583 / #944 sanity guard: prevent phantom phase numbers caused by stale
+      // high-number entries in ROADMAP.md or phases/ (e.g. a prior phantom
+      // "## Phase 1009" left in ROADMAP triggers the next add to produce 1010).
+      //
+      // The guard must NOT misfire on an INTENTIONAL high-base numbering scheme
+      // (e.g. a milestone that deliberately numbers phases 1031, 1032, …). The
+      // discriminant: is the high number an actual TRACKED phase in state.json,
+      // or only a ROADMAP/dir entry that state has never seen?
+      //   - next === maxTracked + 1  → contiguous with real tracked phases →
+      //     intentional, allow regardless of absolute magnitude.
+      //   - maxNum (overall) sits far ABOVE maxTracked → a non-tracked phantom
+      //     is driving the number → suspect, abort.
+      const trackedNums = state.phases
+        .map(p => parseInt(String(p.number || ''), 10))
+        .filter(n => !Number.isNaN(n) && n > 0);
+      const trackedCount = trackedNums.length;
+      const maxTracked = trackedNums.length ? Math.max(...trackedNums) : 0;
+      if (maxNum > maxTracked && (maxNum - maxTracked) > 50) {
         throw new Error(
-          `Computed phase number ${next} is unexpectedly large ` +
-          `(only ${trackedCount} phases tracked in state.json). ` +
-          `ROADMAP.md or the phases/ directory may contain a stale high-number entry. ` +
+          `Computed phase number ${next} is driven by a non-tracked entry ` +
+          `(highest in ROADMAP/phases = ${maxNum}, highest in state.json = ${maxTracked}). ` +
+          `ROADMAP.md or the phases/ directory likely contains a stale high-number entry. ` +
           `Inspect with: node rcode-tools.cjs phases list\n` +
-          `Then retry with an explicit number: rcode-tools.cjs phase add "${phaseName}" --number ${trackedCount + 1}`
+          `Then retry with an explicit number: rcode-tools.cjs phase add "${phaseName}" --number ${maxTracked + 1}`
         );
       }
 
@@ -3822,12 +3890,17 @@ function cmdPhase(subArgs) {
     }
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
 
+    // #942 — surface the milestone close nudge from the CLI itself so it can't
+    // be bypassed by adding phases outside the add-phase workflow.
+    const { milestone_health, nudge } = milestoneCloseNudge();
     return {
       ok: true,
       phase_number: number,
       name: phaseName,
       slug,
       directory: path.relative(PROJECT_ROOT, directory),
+      milestone_health,
+      ...(nudge ? { nudge } : {}),
     };
   }
 
@@ -3866,6 +3939,19 @@ function cmdPhase(subArgs) {
       .sort((a, b) => parseInt(String(a.number), 10) - parseInt(String(b.number), 10))[0] || null;
 
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+
+    // #943 — when no open phases remain, the milestone is effectively finished.
+    // Surface the close/next guidance from this chokepoint so finishing the
+    // last phase via execute/verify/dev-story doesn't strand the user (the
+    // guidance previously only appeared in /rcode-status or progress insights).
+    const doneStatuses = new Set(['complete', 'completed', 'verified', 'shipped']);
+    const openRemaining = state.phases.filter(p => !doneStatuses.has(p.status)).length;
+    let nudge = null;
+    if (openRemaining === 0 && state.phases.length > 0) {
+      nudge = 'All phases are complete — this milestone is finished. ' +
+        'Run /rcode-complete-milestone to archive it, then /rcode-new-milestone to start the next.';
+    }
+
     return {
       ok: true,
       phase: phaseRef,
@@ -3874,6 +3960,8 @@ function cmdPhase(subArgs) {
       next_phase: next ? next.number : null,
       next_phase_name: next ? (next.name || null) : null,
       is_last_phase: !next,
+      open_phases_remaining: openRemaining,
+      ...(nudge ? { nudge } : {}),
       warnings: [],
       has_warnings: false,
     };
@@ -4175,7 +4263,13 @@ function cmdPhase(subArgs) {
     if (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });
     fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
 
-    return { ok: true, count: created.length, phases: created, roadmap_skipped: roadmapSkipped };
+    // #942 — same milestone close nudge for the bulk-draft path.
+    const bulkHealth = milestoneCloseNudge();
+    return {
+      ok: true, count: created.length, phases: created, roadmap_skipped: roadmapSkipped,
+      milestone_health: bulkHealth.milestone_health,
+      ...(bulkHealth.nudge ? { nudge: bulkHealth.nudge } : {}),
+    };
   }
 
   // =====================================================================
@@ -4421,15 +4515,21 @@ function cmdCommit(argv) {
 }
 
 /**
- * cmdGenerateClaudeMd — Phase 11 / #467 / closes part of #465.
+ * cmdGenerateClaudeMd — Phase 11 / #467 / closes part of #465. Phase 42 / #946.
  *
- * Bootstrap a project CLAUDE.md scaffold. Used by new-project-roadmap.md.
- * Refuses to overwrite an existing CLAUDE.md unless --force is set.
+ * Bootstrap project agent-rules scaffolds. Writes the same rule set to both
+ * CLAUDE.md (Claude Code, Grok) and AGENTS.md (the cross-tool open standard read
+ * by Codex, Cursor, Windsurf, Antigravity, Gemini) so the rcode Command Routing
+ * rule reaches every supported agent — not just Claude. Used by
+ * new-project-roadmap.md. Refuses to overwrite an existing CLAUDE.md unless
+ * --force is set; AGENTS.md is written when absent (or with --force) so an
+ * install-managed roster section is never clobbered.
  */
 function cmdGenerateClaudeMd(rawArgs) {
   const args = (rawArgs || '').split(/\s+/).filter(Boolean);
   const force = args.includes('--force');
   const claudeMdPath = path.join(PROJECT_ROOT, 'CLAUDE.md');
+  const agentsMdPath = path.join(PROJECT_ROOT, 'AGENTS.md');
 
   if (fs.existsSync(claudeMdPath) && !force) {
     throw new Error(`CLAUDE.md already exists at ${claudeMdPath}. Use --force to overwrite.`);
@@ -4516,15 +4616,40 @@ If you have a real reason to bypass (e.g. retroactively documenting a phase that
 
 ---
 
+## rcode Command Routing
+
+Before handling planning, exploration, auditing, refactoring, or multi-step build work ad-hoc, check whether a matching rcode command exists first.
+
+**How to check:** read \`.rcode/workflows/do.md\` (installed by rcode) for the intent → command routing table — it is the single source of truth. Common cases: planning a phase → \`/rcode-plan\`, adding a phase → \`/rcode-add-phase\`, exploring/brainstorming → \`/rcode-brainstorm\`, auditing → \`/rcode-audit\`, executing a sprint → \`/rcode-execute\`, mapping the codebase → \`/rcode-map-codebase\`. Always consult \`do.md\` — never infer from memory alone, as the table changes with the release.
+
+**Why:** rcode commands record outcomes in \`.rcode/state.json\` and \`.planning/\`. Work done ad-hoc creates silent state divergence. If you must proceed ad-hoc, run \`/rcode-memory-update\` afterward to keep long-term memory consistent.
+
+---
+
 **This file is part of the project. Treat it as load-bearing.**
 `;
 
+  const claudeExisted = fs.existsSync(claudeMdPath);
   fs.writeFileSync(claudeMdPath, content);
+
+  // Mirror the same rules to AGENTS.md (the cross-tool standard Codex, Cursor,
+  // Windsurf, Antigravity, and Gemini read). Skip when it already exists without
+  // --force so an install-appended "## rcode Agents (installed)" roster survives.
+  const agentsExisted = fs.existsSync(agentsMdPath);
+  const wroteAgents = !agentsExisted || force;
+  if (wroteAgents) {
+    fs.writeFileSync(agentsMdPath, content);
+  }
+
   return {
     ok: true,
     path: path.relative(PROJECT_ROOT, claudeMdPath),
+    paths: wroteAgents
+      ? [path.relative(PROJECT_ROOT, claudeMdPath), path.relative(PROJECT_ROOT, agentsMdPath)]
+      : [path.relative(PROJECT_ROOT, claudeMdPath)],
     project_name: projectName,
-    overwritten: force && fs.existsSync(claudeMdPath),
+    overwritten: force && claudeExisted,
+    agents_md_skipped: !wroteAgents,
   };
 }
 
@@ -6017,20 +6142,6 @@ function cmdNotesCount() {
   return { count };
 }
 
-/**
- * cmdBrain — pull rcode brain content from configured sources.
- *
- * Subcommands:
- *   brain pull           Fetch all configured sources into rcode/brain/
- *   brain pull <name>    Fetch a single named source
- *   brain status         Report cache freshness and placeholder status
- *   brain list           Print configured sources
- *
- * Uses git sparse-checkout so we pull only the paths listed per source.
- * Placeholder URLs (containing `<PLACEHOLDER`) are skipped with a clear
- * message — useful in v2.0 before M5 lands real rcode repo URLs.
- */
-
 /**
  * cmdHandoff — cross-skill continuation token system. Closes #741.
  *
@@ -6119,827 +6230,7 @@ function cmdHandoff(args) {
   return { ok: false, error: `Unknown handoff subcommand: ${sub}. Valid: write, read, clear` };
 }
 
-function cmdBrain(args) {
-  const sub = args[0] || 'help';
-  // sources.yaml lives under .rcode/brain/ in user installs (v2.2+).
-  // Older installs may have it at rcode/brain/ (pre-v2.2) — fall back for compat.
-  let sourcesPath = path.join(RCODE_DIR, 'brain', 'sources.yaml');
-  let brainDir = path.join(RCODE_DIR, 'brain');
-  if (!fs.existsSync(sourcesPath)) {
-    const legacyPath = path.join(PROJECT_ROOT, 'rcode', 'brain', 'sources.yaml');
-    if (fs.existsSync(legacyPath)) {
-      sourcesPath = legacyPath;
-      brainDir = path.join(PROJECT_ROOT, 'rcode', 'brain');
-    }
-  }
-
-  // Resolve a source's dest directory relative to brainDir.
-  // Accepts legacy absolute-looking values ("rcode/brain/rcode-github/") by
-  // stripping any leading "rcode/brain/" so the resolved path sits inside the
-  // chosen brainDir. New sources.yaml should use bare names ("rcode-github/").
-  function resolveDest(dest) {
-    const trimmed = String(dest || '').replace(/^rcode\/brain\//, '').replace(/^\/+/, '');
-    return path.join(brainDir, trimmed);
-  }
-
-  if (!fs.existsSync(sourcesPath)) {
-    return {
-      ok: false,
-      error: `sources.yaml missing at ${sourcesPath}. Run install or see issue #158.`,
-    };
-  }
-
-  // Minimal YAML reader specifically for sources.yaml — not a general parser.
-  // Handles: `version: 1`, `defaults:` block, `sources:` list where each
-  // entry is a `- name: X` block with sibling key: value lines and an
-  // `paths:` sub-list of strings.
-  function parseSourcesYaml(text) {
-    const root = { version: null, defaults: {}, sources: [] };
-    const lines = text.split('\n');
-    let section = null;
-    let current = null;     // current source map
-    let inPaths = false;
-    let inDescription = false;
-    let descLines = [];
-
-    function unquote(s) { return s.replace(/^['"]|['"]$/g, ''); }
-
-    for (const raw of lines) {
-      if (!raw.trim() || raw.trim().startsWith('#')) continue;
-
-      // Flush description if we were collecting
-      if (inDescription && raw.match(/^ {4}\S/) && !raw.trim().startsWith('-')) {
-        // still inside the description block
-        const m = raw.match(/^ *(.*)$/);
-        if (m) descLines.push(m[1]);
-        continue;
-      } else if (inDescription) {
-        current.description = descLines.join(' ').trim();
-        inDescription = false;
-        descLines = [];
-      }
-
-      // Top-level keys
-      const top = raw.match(/^(\w+):\s*(.*)$/);
-      if (top) {
-        const key = top[1], val = top[2].trim();
-        if (key === 'version') { root.version = unquote(val); section = null; continue; }
-        if (key === 'defaults') { section = 'defaults'; continue; }
-        if (key === 'sources') { section = 'sources'; continue; }
-      }
-
-      // defaults: indented key-value
-      if (section === 'defaults') {
-        const m = raw.match(/^ +([\w_]+):\s*(.*)$/);
-        if (m) root.defaults[m[1]] = unquote(m[2]);
-        continue;
-      }
-
-      // sources: list items
-      if (section === 'sources') {
-        const startItem = raw.match(/^ *- ([\w_-]+):\s*(.*)$/);
-        if (startItem) {
-          current = {};
-          current[startItem[1]] = unquote(startItem[2]);
-          root.sources.push(current);
-          inPaths = false;
-          continue;
-        }
-        // paths: list-of-strings under current
-        const pathsStart = raw.match(/^ +paths:\s*$/);
-        if (pathsStart) { current.paths = []; inPaths = true; continue; }
-        if (inPaths) {
-          const pItem = raw.match(/^ *- (.*)$/);
-          if (pItem) { current.paths.push(unquote(pItem[1])); continue; }
-          inPaths = false;
-        }
-        // description: block scalar `>`
-        const descStart = raw.match(/^ +description:\s*>\s*$/);
-        if (descStart) { inDescription = true; descLines = []; continue; }
-        // Regular key: value on current item
-        const kv = raw.match(/^ +([\w_-]+):\s*(.*)$/);
-        if (kv && current) {
-          current[kv[1]] = unquote(kv[2]);
-        }
-      }
-    }
-    // final flush
-    if (inDescription && current) current.description = descLines.join(' ').trim();
-    return root;
-  }
-
-  const cfg = parseSourcesYaml(fs.readFileSync(sourcesPath, 'utf8'));
-  const sources = Array.isArray(cfg.sources) ? cfg.sources : [];
-
-  if (sub === 'list') {
-    return {
-      ok: true,
-      version: cfg.version,
-      sources: sources.map(s => ({
-        name: s.name,
-        repo: s.repo,
-        dest: s.dest,
-        placeholder: String(s.repo || '').includes('<PLACEHOLDER'),
-      })),
-    };
-  }
-
-  if (sub === 'status') {
-    const report = { ok: true, sources: [] };
-    for (const s of sources) {
-      const destPath = resolveDest(s.dest);
-      const exists = fs.existsSync(destPath);
-      report.sources.push({
-        name: s.name,
-        dest: s.dest,
-        fetched: exists,
-        placeholder: String(s.repo || '').includes('<PLACEHOLDER'),
-      });
-    }
-    return report;
-  }
-
-  if (sub !== 'pull') {
-    return {
-      ok: false,
-      error: `Unknown brain subcommand: ${sub}. Try: pull | status | list`,
-    };
-  }
-
-  // sub === 'pull'
-  const onlyName = args[1];
-  const report = { ok: true, pulled: [], skipped: [], errors: [] };
-
-  for (const s of sources) {
-    if (onlyName && s.name !== onlyName) continue;
-    const repo = String(s.repo || '');
-
-    if (repo.includes('<PLACEHOLDER')) {
-      report.skipped.push({ name: s.name, reason: 'placeholder URL — fill in via issue #162 (M5)' });
-      continue;
-    }
-
-    if (repo === 'self') {
-      // In-repo copy — use rsync-ish node copy from paths under project root.
-      const destPath = resolveDest(s.dest);
-      fs.mkdirSync(destPath, { recursive: true });
-      const paths = Array.isArray(s.paths) ? s.paths : [];
-      let copied = 0;
-      for (const pattern of paths) {
-        // Very simple glob: expand ** to recursive copy.
-        const base = pattern.split('**')[0].replace(/\/$/, '');
-        const srcDir = path.join(PROJECT_ROOT, base);
-        if (!fs.existsSync(srcDir)) continue;
-        // Recursive copy of .md files
-        function walk(dir) {
-          for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, e.name);
-            if (e.isDirectory()) { walk(full); continue; }
-            if (!e.isFile()) continue;
-            if (!full.endsWith('.md')) continue;
-            const rel = path.relative(srcDir, full);
-            const out = path.join(destPath, rel);
-            fs.mkdirSync(path.dirname(out), { recursive: true });
-            fs.copyFileSync(full, out);
-            copied++;
-          }
-        }
-        walk(srcDir);
-      }
-      report.pulled.push({ name: s.name, kind: 'self', files: copied });
-      continue;
-    }
-
-    // #925 — supply-chain guard. `brain pull` clones a remote repo and copies
-    // its content into every rcode user's project context, so an attacker who
-    // can edit sources.yaml (or a typo) must not silently pull untrusted code.
-    // Only allow github.com URLs under an approved org allowlist; anything else
-    // is rejected unless the user explicitly opts in with
-    // RCODE_BRAIN_ALLOW_UNVERIFIED=1. Pinning to a commit SHA (source.ref) is
-    // recommended over a moving branch — warn when a source tracks a branch.
-    const BRAIN_ALLOWED_HOSTS = new Set(['github.com']);
-    const BRAIN_ALLOWED_ORGS = new Set(['hanzlahabib', 'rcode-om']);
-    if (process.env.RCODE_BRAIN_ALLOW_UNVERIFIED !== '1') {
-      let host = '', org = '';
-      const mm = repo.match(/(?:https?:\/\/|git@)([^/:]+)[/:]([^/]+)\//);
-      if (mm) { host = mm[1]; org = mm[2]; }
-      if (!BRAIN_ALLOWED_HOSTS.has(host) || !BRAIN_ALLOWED_ORGS.has(org)) {
-        report.skipped.push({
-          name: s.name,
-          reason: `repo not in brain allowlist (${host || 'unknown host'}/${org || '?'}). ` +
-            `Add the org to BRAIN_ALLOWED_ORGS or set RCODE_BRAIN_ALLOW_UNVERIFIED=1 to override.`,
-        });
-        continue;
-      }
-      if (!s.ref) {
-        // Tracking a branch is mutable — a force-push changes what you pull.
-        // Not fatal, but surface it so maintainers can pin a SHA via `ref:`.
-        report.skipped.push({
-          name: s.name,
-          reason: `no pinned 'ref:' SHA — tracking branch '${s.branch || root.defaults.branch || 'main'}' is mutable. ` +
-            `Pin a commit SHA in sources.yaml, or set RCODE_BRAIN_ALLOW_UNVERIFIED=1 to pull the branch tip.`,
-        });
-        continue;
-      }
-    }
-
-    // External git source — use sparse checkout into a tmp dir then copy.
-    // #170 — global brain cache at ~/.rcode/brain-cache/<sha1(repo+branch+paths)>/.
-    // Same source pulled from N projects = N clones today, 1 clone + N copies
-    // after this change. Cache TTL is configurable per source (defaults to 6h).
-    const { execSync, execFileSync: execFileSyncBrain } = require('child_process');
-    const crypto = require('crypto');
-    const os = require('os');
-    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rcode-brain-'));
-    const branch = s.branch || cfg.defaults?.branch || 'main';
-    const sparsePaths = Array.isArray(s.paths) ? s.paths : [];
-
-    // Cache key = sha1(repo + branch + sparsePaths joined). Changing any of
-    // those gets a fresh cache slot. Different projects pulling the same
-    // (repo, branch, paths) tuple share one cached download.
-    const cacheKey = crypto
-      .createHash('sha1')
-      .update(`${repo}\n${branch}\n${sparsePaths.sort().join(',')}`)
-      .digest('hex')
-      .slice(0, 16);
-    const cacheRoot = path.join(os.homedir(), '.rcode', 'brain-cache');
-    const cacheDir = path.join(cacheRoot, cacheKey);
-    const cacheManifest = path.join(cacheDir, '.cache-manifest.json');
-
-    // Parse cache_ttl: accept '6h', '15m', '2d', or seconds as bare number.
-    function parseTtlSeconds(raw, fallback) {
-      if (raw == null || raw === '') return fallback;
-      const s = String(raw).trim();
-      const m = s.match(/^(\d+)([smhd]?)$/i);
-      if (!m) return fallback;
-      const n = parseInt(m[1], 10);
-      switch ((m[2] || 's').toLowerCase()) {
-        case 'd': return n * 86400;
-        case 'h': return n * 3600;
-        case 'm': return n * 60;
-        default:  return n;
-      }
-    }
-    const ttlSeconds = parseTtlSeconds(s.cache_ttl || cfg.defaults?.cache_ttl, 6 * 3600);
-
-    function readCacheManifest() {
-      if (!fs.existsSync(cacheManifest)) return null;
-      try { return JSON.parse(fs.readFileSync(cacheManifest, 'utf8')); }
-      catch { return null; }
-    }
-    function isCacheFresh(manifest) {
-      if (!manifest || typeof manifest.pulled_at !== 'string') return false;
-      const ageMs = Date.now() - Date.parse(manifest.pulled_at);
-      return Number.isFinite(ageMs) && (ageMs / 1000) < ttlSeconds;
-    }
-    function copyTree(src, dst) {
-      for (const e of fs.readdirSync(src, { withFileTypes: true })) {
-        if (e.name === '.git' || e.name === '.cache-manifest.json') continue;
-        const sp = path.join(src, e.name);
-        const dp = path.join(dst, e.name);
-        if (e.isDirectory()) { fs.mkdirSync(dp, { recursive: true }); copyTree(sp, dp); }
-        else if (e.isFile()) fs.copyFileSync(sp, dp);
-      }
-    }
-
-    const destPath = resolveDest(s.dest);
-    try {
-      // Cache hit path — copy from ~/.rcode/brain-cache/<key>/ directly.
-      const cached = readCacheManifest();
-      if (cached && isCacheFresh(cached)) {
-        fs.mkdirSync(destPath, { recursive: true });
-        copyTree(cacheDir, destPath);
-        report.pulled.push({ name: s.name, kind: 'git', repo, branch, cache: 'hit', cache_key: cacheKey });
-        continue;
-      }
-
-      // Cache miss — clone, then warm the cache for next time.
-      // Use --no-checkout + explicit sparse-checkout init + set + checkout
-      // because `git clone --sparse` combined with --filter=blob:none has
-      // an intermittent failure mode where git misreads the URL as a path.
-      // execFileSync — repo/branch/tmp/sparsePaths from user config; no shell so
-      // values with spaces, quotes, or semicolons cannot inject commands (#754).
-      execFileSyncBrain('git', [
-        'clone', '--depth=1', '--filter=blob:none', '--no-checkout',
-        `--branch=${branch}`, repo, tmp,
-      ], { stdio: 'pipe' });
-      execFileSyncBrain('git', ['-C', tmp, 'sparse-checkout', 'init', '--no-cone'], { stdio: 'pipe' });
-      execFileSyncBrain('git', ['-C', tmp, 'sparse-checkout', 'set', ...sparsePaths], { stdio: 'pipe' });
-      execFileSyncBrain('git', ['-C', tmp, 'checkout'], { stdio: 'pipe' });
-
-      // Warm cache before destination copy so a copy failure to dest still
-      // saves the next pull. Replace any stale slot atomically.
-      try {
-        fs.rmSync(cacheDir, { recursive: true, force: true });
-        fs.mkdirSync(cacheDir, { recursive: true });
-        copyTree(tmp, cacheDir);
-        const commitSha = (() => {
-          try { return execFileSyncBrain('git', ['-C', tmp, 'rev-parse', 'HEAD'], { stdio: ['pipe', 'pipe', 'pipe'] }).toString().trim(); }
-          catch { return null; }
-        })();
-        fs.writeFileSync(cacheManifest, JSON.stringify({
-          repo, branch, paths: sparsePaths,
-          pulled_at: new Date().toISOString(),
-          commit_sha: commitSha,
-          ttl_seconds: ttlSeconds,
-        }, null, 2));
-      } catch (_) { /* cache warming is best-effort */ }
-
-      fs.mkdirSync(destPath, { recursive: true });
-      copyTree(tmp, destPath);
-      report.pulled.push({ name: s.name, kind: 'git', repo, branch, cache: 'miss', cache_key: cacheKey });
-    } catch (e) {
-      report.errors.push({ name: s.name, error: String(e.message || e).slice(0, 200) });
-    } finally {
-      try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {}
-    }
-  }
-
-  if (report.errors.length) report.ok = false;
-  return report;
-}
-
-/**
- * cmdProgress — single pre-computed progress blob (issue #159).
- *
- * Subcommands:
- *   progress init          Full snapshot — everything /rcode-progress needs.
- *   progress bar --raw     ASCII bar only (e.g. "[████░░░░] 50%").
- *   progress insights      insights[] array (drift warnings, between-milestone detection).
- *   progress routes        intent-tree routes[] for Next Up menu.
- *
- * Pushing logic into the CLI lets the workflow file shrink to pure
- * rendering — no ROADMAP.md parsing, no SUMMARY.md walking, no grep.
- */
-function cmdProgress(args) {
-  const sub = args[0] || 'init';
-  const rawMode = args.includes('--raw');
-  // #200 — opt-in strict mode: exit 1 when insights contain drift/undercount.
-  // Off by default (warning preserves the soft-surface UX). Toggle via --strict
-  // flag or RCODE_STRICT_STATE=true env var. Used by CI / pre-deploy gates.
-  const strictMode = args.includes('--strict')
-    || /^(true|1|yes)$/i.test(process.env.RCODE_STRICT_STATE || '');
-
-  // Resolve paths — workflow files may run this from any subdirectory.
-  const statePath = path.join(RCODE_DIR, 'state.json');
-  const roadmapPath = path.join(PLANNING_DIR, 'ROADMAP.md');
-  const phasesDir = path.join(PLANNING_DIR, 'phases');
-
-  function readState() {
-    if (!fs.existsSync(statePath)) return null;
-    try { return JSON.parse(fs.readFileSync(statePath, 'utf8')); }
-    catch { return null; }
-  }
-
-  function parseRoadmapPhases() {
-    if (!fs.existsSync(roadmapPath)) return [];
-    const text = fs.readFileSync(roadmapPath, 'utf8');
-    const phases = [];
-    const seen = new Set();
-
-    // Format A — markdown pipe tables: | 07 | Name | Goal |
-    // Phase 14 / #476 — \d+ supports high-N phases (1000+, hot-track).
-    const rowRe = /^\|\s*(\d+(?:\.\d+)?)\s*\|\s*([^|]+?)\s*\|\s*([^|]*?)\s*\|/gm;
-    let m;
-    while ((m = rowRe.exec(text)) !== null) {
-      const num = m[1].trim();
-      const name = m[2].trim();
-      const goal = m[3].trim();
-      if (!/^\d/.test(num)) continue;
-      if (name.toLowerCase() === 'phase') continue;
-      if (seen.has(num)) continue;
-      seen.add(num);
-      phases.push({ number: num, name, goal });
-    }
-
-    // Format B — heading style: ## Phase 07 — Name  /  ### Phase 07: Name  /  ## Phase 07 - Name
-    // Phase 14 / #476 — \d+ supports high-N phases (1000+, hot-track).
-    const headRe = /^#{2,4}\s*Phase\s+(\d+(?:\.\d+)?)\s*[—\-:]\s*([^\n]+)$/gm;
-    while ((m = headRe.exec(text)) !== null) {
-      const num = m[1].trim();
-      const name = m[2].trim();
-      if (seen.has(num)) continue;
-      seen.add(num);
-      // Goal: pull the first non-empty line after the heading that starts with **Goal:** or is plain text
-      const after = text.slice(headRe.lastIndex).split(/\n/).slice(0, 8).join('\n');
-      const goalMatch = after.match(/\*\*Goal:\*\*\s*([^\n]+)/i);
-      phases.push({ number: num, name, goal: goalMatch ? goalMatch[1].trim() : '' });
-    }
-
-    // Sort numerically (handles "07" vs "10" string ordering correctly)
-    phases.sort((a, b) => parseFloat(a.number) - parseFloat(b.number));
-    return phases;
-  }
-
-  function extractMilestoneName() {
-    // 1. Try ROADMAP.md headings — match any milestone header form
-    if (fs.existsSync(roadmapPath)) {
-      const text = fs.readFileSync(roadmapPath, 'utf8');
-      // Bold form: **Milestone: v1.0 — Name** or **Milestone v1.0 — Name**
-      let m = text.match(/\*\*\s*Milestone\s*:?\s*([^\n*]+?)\s*\*\*/i);
-      if (m) return m[1].trim();
-      // Header form: ## Milestone v1.0 — Name  /  ## Milestone: v1.0 — Name
-      m = text.match(/^#{1,4}\s+Milestone\s*:?\s*([^\n]+)$/m);
-      if (m) return m[1].trim();
-    }
-    // 2. Fall back to state.json milestone field
-    try {
-      if (fs.existsSync(statePath)) {
-        const s = JSON.parse(fs.readFileSync(statePath, 'utf8'));
-        if (s && s.milestone) return String(s.milestone).trim();
-      }
-    } catch { /* ignore */ }
-    return null;
-  }
-
-  // Treat any of `number`, `id`, or `name` as the phase identifier.
-  // Different commands historically write different field names — accept all.
-  function phaseKey(p) {
-    return String(p?.number ?? p?.id ?? p?.name ?? '').trim();
-  }
-
-  function walkPhaseDirs() {
-    if (!fs.existsSync(phasesDir)) return {};
-    const byNum = {};
-    for (const entry of fs.readdirSync(phasesDir)) {
-      const full = path.join(phasesDir, entry);
-      if (!fs.statSync(full).isDirectory()) continue;
-      // Phase 14 / #476 — \d+ supports high-N phase dirs (1000+).
-      const numMatch = entry.match(/^(\d+(?:\.\d+)?)/);
-      if (!numMatch) continue;
-      const num = numMatch[1];
-      const files = fs.readdirSync(full);
-      byNum[num] = {
-        path: full,
-        dirName: entry,
-        plan_count: files.filter(f => /-SPRINT\.md$/i.test(f)).length,
-        summary_count: files.filter(f => /SUMMARY\.md$|-SUMMARY\.md$/.test(f)).length,
-        has_research: files.includes('RESEARCH.md'),
-        has_context: files.includes('CONTEXT.md'),
-        has_verification: files.some(f => /VERIFICATION\.md$/i.test(f)),
-      };
-    }
-    return byNum;
-  }
-
-  // #200 — opt-in strict gate. Walks insights for drift/undercount kinds and
-  // exits 1 with the failure list to stderr. No-op when strictMode=false.
-  function enforceStrictGate(insightsList) {
-    if (!strictMode) return;
-    const blocking = (insightsList || []).filter(i =>
-      i && (i.kind === 'drift' || i.kind === 'undercount') && i.severity !== 'info'
-    );
-    if (blocking.length === 0) return;
-    process.stderr.write('✖ State drift detected — state.json is out of sync with disk.\n');
-    for (const i of blocking) process.stderr.write(`  • ${i.message}\n`);
-    process.stderr.write('\n  Auto-fix:  node .rcode/bin/rcode-tools.cjs state sync --from-disk\n');
-    process.stderr.write('  Inspect:   node .rcode/bin/rcode-tools.cjs state read\n');
-    process.exit(1);
-  }
-
-  function detectInsights(state, roadmapPhases, diskByNum) {
-    const insights = [];
-    const statePhases = (state && (state.state?.phases || state.phases)) || [];
-
-    // Drift: ROADMAP phase count vs state.json phase count
-    if (roadmapPhases.length > 0 && statePhases.length !== roadmapPhases.length) {
-      insights.push({
-        kind: 'drift',
-        severity: 'warn',
-        message: `ROADMAP.md has ${roadmapPhases.length} phases, state.json has ${statePhases.length}. Run: node .rcode/bin/rcode-tools.cjs state sync --from-disk`,
-      });
-    }
-
-    // Undercount: phases that exist on disk but not in state.
-    // Accept any of `number`, `id`, or `name` as the phase identifier — the codebase historically writes different fields.
-    // Also normalize "07" / "7" / 7 to a comparable form.
-    const norm = (k) => String(k ?? '').replace(/^0+(\d)/, '$1');
-    const statePhaseNums = new Set(statePhases.map(p => norm(phaseKey(p))));
-    const diskPhaseNums = Object.keys(diskByNum);
-    const missingFromState = diskPhaseNums.filter(n => !statePhaseNums.has(norm(n)));
-    if (missingFromState.length > 0) {
-      insights.push({
-        kind: 'undercount',
-        severity: 'warn',
-        message: `${missingFromState.length} phase dir(s) on disk not registered in state.json: ${missingFromState.slice(0, 5).join(', ')}`,
-      });
-    }
-
-    // Phantom-complete: phase claimed Complete (in ROADMAP or state) but missing
-    // PLAN.md AND SUMMARY.md on disk. User-visible bug: /rcode-status would
-    // happily report 'all complete' while /rcode-audit correctly flagged the
-    // gap because the two read different sources of truth.
-    // Surfaced 2026-04-29 in a real session — siraaj phases 07-12 had ROADMAP
-    // markers but zero artifacts.
-    const phantomCompletes = [];
-    const claimedComplete = (p) => {
-      if (!p) return false;
-      const s = String(p.status ?? '').toLowerCase();
-      return p.completed || s === 'complete' || s === 'completed' || s === 'done';
-    };
-    // Walk ROADMAP-claimed completes and state-claimed completes, both directions.
-    const completeKeys = new Set();
-    for (const p of roadmapPhases) if (claimedComplete(p)) completeKeys.add(norm(phaseKey(p)));
-    for (const p of statePhases) if (claimedComplete(p)) completeKeys.add(norm(phaseKey(p)));
-    for (const k of completeKeys) {
-      const disk = diskByNum[k] || diskByNum[k.padStart(2, '0')];
-      // Only flag when the phase dir EXISTS — purely-state-only entries are a
-      // separate problem (drift/undercount above). Here we want claim-vs-files.
-      if (!disk) continue;
-      if (disk.plan_count === 0 && disk.summary_count === 0) {
-        phantomCompletes.push(k);
-      }
-    }
-    if (phantomCompletes.length > 0) {
-      insights.push({
-        kind: 'phantom-complete',
-        severity: 'warn',
-        message: `${phantomCompletes.length} phase(s) marked Complete but missing both PLAN.md and SUMMARY.md on disk: ${phantomCompletes.slice(0, 5).join(', ')}. The completion claim is unsupported. Run /rcode-audit phase <N> to inspect.`,
-      });
-    }
-
-    // Between-milestones heuristic: no current_phase + previous milestone's last phase is complete
-    if (state && state.current_phase === null && statePhases.length > 0) {
-      const allComplete = statePhases.every(p => p.status === 'complete' || p.completed);
-      if (allComplete) {
-        insights.push({
-          kind: 'between-milestones',
-          severity: 'info',
-          message: 'All registered phases complete — effectively between milestones. Consider /rcode-audit-milestone or /rcode-new-milestone.',
-        });
-      }
-    }
-
-    // Stuck-phase: in_progress phase with no commits touching its .planning dir in 7+ days
-    try {
-      const inProgressPhases = statePhases.filter(p => {
-        const s = String(p.status ?? '').toLowerCase();
-        return s === 'in_progress' || s === 'in-progress' || s === 'executing';
-      });
-      for (const p of inProgressPhases) {
-        const key = norm(phaseKey(p));
-        const disk = diskByNum[key] || diskByNum[key.padStart(2, '0')];
-        if (!disk) continue;
-        const dirName = disk.dirName;
-        const gitArgs = ['log', '--oneline', '--since=7 days ago', '--', `.planning/phases/${dirName}/`];
-        let recentCommits = '';
-        try {
-          recentCommits = require('child_process').execSync(
-            `git ${gitArgs.join(' ')}`,
-            { cwd: PROJECT_ROOT, stdio: 'pipe', timeout: 5000 }
-          ).toString().trim();
-        } catch { /* git not available or no history */ }
-        if (recentCommits === '') {
-          insights.push({
-            kind: 'stuck-phase',
-            severity: 'warn',
-            message: `Phase ${key} is in progress but has no commits in the last 7 days. It may be stuck. Run /rcode-status or /rcode-audit phase ${key} to investigate.`,
-          });
-        }
-      }
-    } catch { /* non-fatal — git unavailable or project root not set */ }
-
-    return insights;
-  }
-
-  function deriveRoutes(state, roadmapPhases, diskByNum, insights) {
-    const routes = [];
-    const statePhases = (state && (state.state?.phases || state.phases)) || [];
-
-    // Route A — phases with pending plans (ready to execute).
-    // Issue #653 — never recommend executing a phase whose state.json status
-    // is already complete/done/verified, even if its on-disk plan_count >
-    // summary_count. Missing second summary file is not the canonical
-    // completion signal; state.json is. Run /rcode-audit phase <N> for
-    // disk-vs-state drift, but stop steering users into re-executing
-    // finished work.
-    const isPhaseDone = (p) => {
-      const s = String((p && p.status) || '').toLowerCase();
-      return s === 'complete' || s === 'completed' || s === 'done' || s === 'verified' || Boolean(p && p.completed);
-    };
-    const pendingExec = statePhases.filter(p => {
-      if (isPhaseDone(p)) return false;
-      const disk = diskByNum[phaseKey(p)];
-      return disk && disk.plan_count > disk.summary_count;
-    }).slice(0, 3);
-    for (const p of pendingExec) {
-      const k = phaseKey(p);
-      routes.push({ letter: 'A', label: '', command: `/rcode-execute ${k}` });
-    }
-
-    // Route B — phases with research but no plans
-    const researchOnly = Object.entries(diskByNum)
-      .filter(([num, d]) => d.has_research && d.plan_count === 0)
-      .slice(0, 3);
-    for (const [num] of researchOnly) {
-      routes.push({ letter: 'B', label: '', command: `/rcode-plan ${num}` });
-    }
-
-    // Route B' — in-progress phases without plans
-    const inProgressNoPlan = statePhases
-      .filter(p => (p.status === 'in_progress' || p.status === 'in-progress'))
-      .filter(p => {
-        const disk = diskByNum[phaseKey(p)];
-        return !disk || disk.plan_count === 0;
-      })
-      .slice(0, 2);
-    for (const p of inProgressNoPlan) {
-      const k = phaseKey(p);
-      routes.push({ letter: 'B', label: '', command: `/rcode-plan ${k}` });
-    }
-
-    // Route C — close out milestone if everything seems done
-    const allDone = statePhases.length > 0 && statePhases.every(p => p.status === 'complete' || p.completed);
-    if (allDone) {
-      // Count unverified phases (complete but no VERIFICATION.md on disk)
-      const unverifiedCount = statePhases.filter(p => {
-        const disk = diskByNum[phaseKey(p)];
-        return (p.status === 'complete' || p.completed) && disk && !disk.has_verification;
-      }).length;
-      const hasDrift = (insights || []).some(i => i.kind === 'roadmap-drift' || (i.message && i.message.includes('ROADMAP')));
-      const auditArgs = [];
-      if (unverifiedCount > 0) auditArgs.push(String(unverifiedCount));
-      if (hasDrift) auditArgs.push('--fix-drift');
-      const auditCmd = auditArgs.length > 0
-        ? `/rcode-audit-milestone ${auditArgs.join(' ')}`
-        : '/rcode-audit-milestone';
-      routes.push({ letter: 'C', label: '', command: auditCmd });
-      routes.push({ letter: 'C', label: '', command: '/rcode-complete-milestone' });
-    }
-
-    // Fallback — nothing obvious: offer status
-    if (routes.length === 0) {
-      routes.push({ letter: 'A', label: '', command: '/rcode-progress' });
-      routes.push({ letter: 'B', label: '', command: '/rcode-council' });
-    }
-
-    return routes;
-  }
-
-  function buildBar(completed, total) {
-    if (!total) return '[░░░░░░░░░░░░░░░░░░░░] 0/0 (0%)';
-    const pct = Math.round((completed / total) * 100);
-    const width = 20;
-    const filled = Math.min(width, Math.round((completed / total) * width));
-    const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
-    return `[${bar}] ${completed}/${total} (${pct}%)`;
-  }
-
-  /**
-   * Compute weighted progress that recognizes intermediate phase states.
-   * Weights: has_context only = 0.15, has_research = 0.25, has plan = 0.5,
-   * has verification or summary = 1.0.
-   * Returns { weighted: number (0..total), pct: number (0..100) }.
-   */
-  function computeWeightedProgress(stPhases, diskMap) {
-    if (!stPhases.length) return { weighted: 0, pct: 0 };
-    const norm = (k) => String(k ?? '').replace(/^0+(\d)/, '$1');
-    let sum = 0;
-    for (const p of stPhases) {
-      const k = norm(phaseKey(p));
-      if (p.status === 'complete' || p.completed) { sum += 1; continue; }
-      const disk = diskMap[k] || diskMap[phaseKey(p)];
-      if (!disk) continue;
-      if (disk.summary_count > 0)       { sum += 1;    continue; }
-      if (disk.has_verification)         { sum += 0.85; continue; }
-      if (disk.plan_count > 0)           { sum += 0.5;  continue; }
-      if (disk.has_research)             { sum += 0.25; continue; }
-      if (disk.has_context)              { sum += 0.15; continue; }
-    }
-    const total = Math.max(stPhases.length, 1);
-    return { weighted: Math.round(sum * 100) / 100, pct: Math.round((sum / total) * 100) };
-  }
-
-  function buildWeightedBar(stPhases, diskMap, total) {
-    const { weighted, pct } = computeWeightedProgress(stPhases, diskMap);
-    if (!total) return '[░░░░░░░░░░░░░░░░░░░░] 0/0 (0%)';
-    const width = 20;
-    const filled = Math.min(width, Math.round((weighted / total) * width));
-    const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
-    return `[${bar}] ~${pct}% weighted`;
-  }
-
-  // Build the core snapshot once — all subcommands derive from it.
-  const state = readState();
-  const roadmapPhases = parseRoadmapPhases();
-  const diskByNum = walkPhaseDirs();
-  const statePhases = (state && (state.state?.phases || state.phases)) || [];
-  const completedCount = statePhases.filter(p => p.status === 'complete' || p.completed).length;
-  const phaseCount = Math.max(statePhases.length, roadmapPhases.length);
-
-  if (sub === 'bar') {
-    const bar = buildBar(completedCount, phaseCount);
-    if (rawMode) { console.log(bar); process.exit(0); }
-    return { ok: true, bar, completed: completedCount, total: phaseCount };
-  }
-
-  if (sub === 'insights') {
-    const insightsList = detectInsights(state, roadmapPhases, diskByNum);
-    enforceStrictGate(insightsList);
-    return { ok: true, insights: insightsList };
-  }
-
-  if (sub === 'routes') {
-    const routeInsights = detectInsights(state, roadmapPhases, diskByNum);
-    return { ok: true, routes: deriveRoutes(state, roadmapPhases, diskByNum, routeInsights) };
-  }
-
-  // sub === 'init' (default) — full snapshot
-  const currentPhase = state && state.current_phase;
-  const insights = detectInsights(state, roadmapPhases, diskByNum);
-  enforceStrictGate(insights);
-  const routes = deriveRoutes(state, roadmapPhases, diskByNum, insights);
-  const { weighted: weightedCompleted, pct: weightedPct } = computeWeightedProgress(statePhases, diskByNum);
-
-  return {
-    ok: true,
-    project: state && state.project,
-    milestone: extractMilestoneName(),
-    current_phase: currentPhase,
-    phase_count: phaseCount,
-    completed_count: completedCount,
-    weighted_progress: weightedPct,
-    bar: buildBar(completedCount, phaseCount),
-    weighted_bar: buildWeightedBar(statePhases, diskByNum, phaseCount),
-    phases: (() => {
-      // Prefer ROADMAP-parsed phases when available; fall back to state.phases
-      // when the roadmap doesn't use a parseable format. Normalize "07" / "7" / 7.
-      const norm = (k) => String(k ?? '').replace(/^0+(\d)/, '$1');
-      const source = roadmapPhases.length > 0 ? roadmapPhases : statePhases.map(p => ({
-        number: phaseKey(p),
-        name: p.name || '',
-        goal: p.goal || '',
-        status: p.status,
-      }));
-      return source.map(p => {
-        const k = phaseKey(p);
-        const sp = statePhases.find(x => norm(phaseKey(x)) === norm(k));
-        return {
-          ...p,
-          number: k,
-          status: p.status || (sp && sp.status) || null,
-          disk: diskByNum[k] || null,
-          in_state: !!sp,
-        };
-      });
-    })(),
-    decisions: state ? (state.decisions || []).slice(-3) : [],
-    blockers: state ? (state.blockers || []).filter(b => !b.resolved).slice(0, 5) : [],
-    insights,
-    routes,
-    updated: state && state.updated,
-  };
-}
-
-/**
- * cmdSummaryExtract — surgically pull named fields from a SUMMARY.md.
- * Avoids whole-file loads when the caller only wants one or two headings.
- * Usage: summary-extract <path> --fields one_liner,status
- */
-function cmdSummaryExtract(args) {
-  const filePath = args[0];
-  const fieldsFlag = args.indexOf('--fields');
-  const fields = fieldsFlag >= 0 ? (args[fieldsFlag + 1] || '').split(',').map(s => s.trim()).filter(Boolean) : ['one_liner'];
-
-  if (!filePath) return { ok: false, error: 'Usage: summary-extract <path> [--fields a,b,c]' };
-  if (!fs.existsSync(filePath)) return { ok: false, error: `file not found: ${filePath}` };
-
-  const text = fs.readFileSync(filePath, 'utf8');
-  const out = { ok: true, path: filePath };
-
-  const fieldToPatterns = {
-    one_liner: [/^##\s+One[-\s]?liner\s*\n([\s\S]*?)(?=\n##|\n---|$)/im, /^##\s+Summary\s*\n([\s\S]*?)(?=\n##|\n---|$)/im],
-    status: [/^##\s+Status\s*\n([\s\S]*?)(?=\n##|\n---|$)/im, /^status:\s*(.+)$/im],
-    outcomes: [/^##\s+Outcomes?\s*\n([\s\S]*?)(?=\n##|\n---|$)/im],
-    decisions: [/^##\s+Decisions?\s*\n([\s\S]*?)(?=\n##|\n---|$)/im],
-    blockers: [/^##\s+Blockers?\s*\n([\s\S]*?)(?=\n##|\n---|$)/im],
-    followups: [/^##\s+Follow[-\s]?ups?\s*\n([\s\S]*?)(?=\n##|\n---|$)/im, /^##\s+Next[-\s]?steps?\s*\n([\s\S]*?)(?=\n##|\n---|$)/im],
-  };
 
-  for (const f of fields) {
-    const patterns = fieldToPatterns[f] || [new RegExp(`^##\\s+${f.replace(/_/g, '[ _-]?')}\\s*\\n([\\s\\S]*?)(?=\\n##|\\n---|$)`, 'im')];
-    let value = null;
-    for (const re of patterns) {
-      const m = text.match(re);
-      if (m && m[1]) { value = m[1].trim().split('\n').map(l => l.trim()).filter(Boolean).join('\n'); break; }
-    }
-    // Fallback for one_liner: first non-empty paragraph after H1
-    if (f === 'one_liner' && !value) {
-      const afterH1 = text.replace(/^#[^\n]*\n/, '');
-      const firstPara = afterH1.match(/^[^\n#][^\n]*(?:\n(?!\n)[^\n#][^\n]*)*/m);
-      if (firstPara) value = firstPara[0].trim();
-    }
-    out[f] = value;
-  }
-
-  return out;
-}
-
-/**
- * cmdStateSnapshot — compact, display-friendly state extract.
- * Hides internal machinery (lock metadata, full history) from callers
- * that only need a render-ready summary.
- */
 /**
  * cmdProjectStatus — classify project lifecycle state into one of:
  *   uninstalled    — no .rcode/config.yaml
@@ -7226,142 +6517,31 @@ function cmdMilestoneHealth() {
   };
 }
 
-function cmdStateSnapshot() {
-  const statePath = path.join(RCODE_DIR, 'state.json');
-  if (!fs.existsSync(statePath)) return { ok: true, state: null };
-  let state;
-  try { state = JSON.parse(fs.readFileSync(statePath, 'utf8')); }
-  catch (e) { return { ok: false, error: `invalid state.json: ${e.message}` }; }
-
-  return {
-    ok: true,
-    project: state.project,
-    current_phase: state.current_phase,
-    current_plan: state.current_plan,
-    current_sprint: state.current_sprint,
-    phase_count: (state.phases || []).length,
-    decisions_count: (state.decisions || []).length,
-    blockers_open: (state.blockers || []).filter(b => !b.resolved).length,
-    last_session: state.last_session,
-    updated: state.updated,
-    active_workstream: state.active_workstream,
+// #942 — build a milestone-health summary + human-readable nudge for any
+// phase-adding code path (single add, bulk draft, plan, insert) so the
+// "milestone has too many open phases" guidance can't be bypassed by adding
+// phases outside the add-phase workflow. Returns { milestone_health, nudge }.
+function milestoneCloseNudge() {
+  let h;
+  try { h = cmdMilestoneHealth(); } catch { return { milestone_health: null, nudge: null }; }
+  if (!h || !h.ok) return { milestone_health: null, nudge: null };
+  const summary = {
+    open_phases: h.open_phases,
+    recommendation: h.recommendation,
+    threshold_should: h.threshold_should,
+    threshold_consider: h.threshold_consider,
   };
-}
-
-/**
- * cmdGitignore — re-render the rcode-managed block in .gitignore based on
- * current config (specifically commit_planning from .rcode/config.yaml).
- *
- * Subcommands:
- *   gitignore refresh   rewrite the rcode block in-place
- *   gitignore status    report current commit_planning + block presence
- *
- * Mirrors the logic in cli/install.js ensureRcodeGitignore — kept in sync
- * by convention. Any change to the block format should update both.
- * Closes #189 — runtime toggle for commit_planning.
- */
-function cmdGitignore(args) {
-  const sub = args[0] || 'refresh';
-  const gitignorePath = path.join(PROJECT_ROOT, '.gitignore');
-  const configPath = path.join(RCODE_DIR, 'config.yaml');
-
-  // Read commit_planning from config; default true if missing.
-  let commitPlanning = true;
-  if (fs.existsSync(configPath)) {
-    const cfg = fs.readFileSync(configPath, 'utf8');
-    const m = cfg.match(/^\s*commit_planning:\s*(true|false)\s*$/m);
-    if (m) commitPlanning = (m[1] === 'true');
-  }
-
-  const BEGIN = '# ===== rcode-managed gitignore block (npx @hanzlaa/rcode install) =====';
-  const END   = '# ===== end rcode-managed gitignore block =====';
-
-  if (sub === 'status') {
-    const exists = fs.existsSync(gitignorePath);
-    const hasBlock = exists && fs.readFileSync(gitignorePath, 'utf8').includes(BEGIN);
-    return {
-      ok: true,
-      gitignore_exists: exists,
-      block_present: hasBlock,
-      commit_planning: commitPlanning,
-    };
-  }
-
-  if (sub !== 'refresh') {
-    return { ok: false, error: `Unknown gitignore subcommand: ${sub}. Try: refresh | status` };
-  }
-
-  const lines = [
-    '',
-    BEGIN,
-    '# Added automatically on rcode install. Idempotent — safe to re-run.',
-    '# Edit `commit_planning` in .rcode/config.yaml, then: rcode-tools gitignore refresh',
-    '',
-    '# Installed methodology files (regenerate with: npx @hanzlaa/rcode install)',
-    '.claude/',
-    '.rcode/bin/',
-    '.rcode/workflows/',
-    '.rcode/references/',
-    '.rcode/commands/',
-    '.rcode/skills/',
-    '',
-    '# Pulled rcode brain content (refresh with: rcode brain pull)',
-    '.rcode/brain/rcode-github/',
-    '.rcode/brain/rcode-docs/',
-    '.rcode/brain/best-practices/',
-    '',
-    '# Runtime noise',
-    'node_modules/',
-    '.rcode/state.json.lock',
-    '.planning/debug/',
-    '.planning/_backup/',
-  ];
-  if (!commitPlanning) {
-    lines.push('', '# Planning artifacts — kept local (commit_planning: false)', '.planning/');
-  }
-  lines.push(
-    '',
-    '# What you DO commit:',
-    '#   .rcode/config.yaml        - project mode/language/profile/commit_planning',
-    '#   .rcode/state.json         - decisions, roadmap pointer, blockers',
-    '#   .rcode/brain/sources.yaml - brain source manifest',
-    commitPlanning
-      ? '#   .planning/                - PRD, roadmap, sprints, SUMMARY.md files'
-      : '#   (planning artifacts are NOT committed — see commit_planning in config)',
-    END,
-    ''
-  );
-  const BLOCK = lines.join('\n');
-
-  /** Replace the rcode block in text using indexOf — safer than regex. */
-  function spliceBlock(existing, newBlock) {
-    const start = existing.indexOf(BEGIN);
-    if (start < 0) return null;
-    const endIdx = existing.indexOf(END, start);
-    if (endIdx < 0) return null;
-    // Include trailing newline after END if present, and leading newline before BEGIN.
-    let sliceStart = start;
-    if (sliceStart > 0 && existing[sliceStart - 1] === '\n') sliceStart -= 1;
-    let sliceEnd = endIdx + END.length;
-    if (existing[slice_end] === '\n') slice_end += 1;
-    return existing.slice(0, sliceStart) + newBlock + existing.slice(slice_end);
-  }
-
-  if (!fs.existsSync(gitignorePath)) {
-    fs.writeFileSync(gitignorePath, BLOCK);
-    return { ok: true, action: 'created', commit_planning: commitPlanning };
-  }
-  const existing = fs.readFileSync(gitignorePath, 'utf8');
-  if (existing.includes(BEGIN)) {
-    const rewritten = spliceBlock(existing, BLOCK);
-    if (rewritten !== null && rewritten !== existing) {
-      fs.writeFileSync(gitignorePath, rewritten);
-      return { ok: true, action: 'updated', commit_planning: commitPlanning };
-    }
-    return { ok: true, action: 'no-change', commit_planning: commitPlanning };
-  }
-  fs.writeFileSync(gitignorePath, existing + BLOCK);
-  return { ok: true, action: 'appended', commit_planning: commitPlanning };
+  let nudge = null;
+  if (h.recommendation === 'should-close') {
+    nudge = `Milestone "${h.milestone || 'current'}" has ${h.open_phases} open phases ` +
+      `(≥${h.threshold_should}). Consider /rcode-complete-milestone to archive done ` +
+      `phases, then /rcode-new-milestone for ongoing work — before adding more.`;
+  } else if (h.recommendation === 'consider-closing') {
+    nudge = `Milestone "${h.milestone || 'current'}" has ${h.open_phases} open phases ` +
+      `(≥${h.threshold_consider}). Getting large — /rcode-complete-milestone + ` +
+      `/rcode-new-milestone will keep the roadmap navigable.`;
+  }
+  return { milestone_health: summary, nudge };
 }
 
 function cmdFindFiles(rawArgs) {
@@ -7833,7 +7013,8 @@ async function main() {
         break;
       }
       case 'brain': {
-        result = cmdBrain(args);
+        const brain = require(path.join(__dirname, 'lib', 'brain.cjs'));
+        result = brain.cmdBrain(args, { PROJECT_ROOT, RCODE_DIR });
         break;
       }
       case 'handoff': {
@@ -7841,19 +7022,23 @@ async function main() {
         break;
       }
       case 'progress': {
-        result = cmdProgress(args);
+        const progress = require(path.join(__dirname, 'lib', 'progress.cjs'));
+        result = progress.cmdProgress(args, { PROJECT_ROOT, RCODE_DIR, PLANNING_DIR });
         break;
       }
       case 'summary-extract': {
-        result = cmdSummaryExtract(args);
+        const summary = require(path.join(__dirname, 'lib', 'summary.cjs'));
+        result = summary.cmdSummaryExtract(args);
         break;
       }
       case 'state-snapshot': {
-        result = cmdStateSnapshot();
+        const summary = require(path.join(__dirname, 'lib', 'summary.cjs'));
+        result = summary.cmdStateSnapshot({ RCODE_DIR });
         break;
       }
       case 'gitignore': {
-        result = cmdGitignore(args);
+        const gitignore = require(path.join(__dirname, 'lib', 'gitignore.cjs'));
+        result = gitignore.cmdGitignore(args, { PROJECT_ROOT, RCODE_DIR });
         break;
       }
       case 'agent-skills':
@@ -7878,8 +7063,9 @@ async function main() {
         // Closes #836 — top-level health check so agents can call
         // `rcode-tools.cjs health` directly without the CLI wrapper.
         // Returns a combined snapshot: milestone health + state snapshot + project status.
+        const summary = require(path.join(__dirname, 'lib', 'summary.cjs'));
         const mh = cmdMilestoneHealth();
-        const ss = cmdStateSnapshot();
+        const ss = summary.cmdStateSnapshot({ RCODE_DIR });
         const ps = cmdProjectStatus();
         result = { ok: mh.ok && ss.ok, milestone_health: mh, state: ss, project: ps };
         break;