@hanzlaa/rcode 4.4.3 → 4.4.4

package/README.md

@@ -23,7 +23,7 @@ pnpm dlx @hanzlaa/rcode install
 [![CI](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml/badge.svg)](https://github.com/hanzlahabib/rcode/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Status: `@hanzlaa/rcode` v4.4.3 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
+Status: `@hanzlaa/rcode` v4.4.4 on npm. 45 agents · 117 commands · 129 workflows · **1 runtime dependency**. Test status tracked by CI badge above. Actively dogfooded on real projects every week.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzlaa/rcode",
-  "version": "4.4.3",
+  "version": "4.4.4",
   "description": "rcode — the AI team that never forgets. Persistent memory, specialist agents, and slash commands for AI IDEs. Works in Claude Code, Cursor, Gemini, VS Code, and Antigravity.",
   "main": "cli/index.js",
   "bin": {

package/rcode/bin/rcode-tools.cjs

@@ -2278,12 +2278,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 } : {}),
     };
   }
 
@@ -3734,22 +3738,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 +3834,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 +3883,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 +3904,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 +4207,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 } : {}),
+    };
   }
 
   // =====================================================================
@@ -7226,6 +7264,33 @@ function cmdMilestoneHealth() {
   };
 }
 
+// #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,
+  };
+  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 cmdStateSnapshot() {
   const statePath = path.join(RCODE_DIR, 'state.json');
   if (!fs.existsSync(statePath)) return { ok: true, state: null };

package/rcode/workflows/execute.md

@@ -871,7 +871,16 @@ The CLI handles:
 - Updating REQUIREMENTS.md traceability
 - Scanning for verification debt (returns `warnings` array)
 
-Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `warnings`, `has_warnings`.
+Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`, `warnings`, `has_warnings`, `open_phases_remaining`, `nudge`.
+
+**If `nudge` is present (#943 — no open phases remain, milestone finished):**
+Surface it verbatim so the user is guided forward instead of stranded:
+```
+✓ Milestone complete — all phases done.
+{nudge}
+```
+Do not auto-advance past a finished milestone; let the user choose
+`/rcode-complete-milestone` or `/rcode-new-milestone`.
 
 **If has_warnings is true:**
 ```

package/rcode/workflows/insert-phase.md

@@ -83,6 +83,14 @@ Next steps:
 Or continue with current work and return to this phase later.
 ```
 
+## Step 3.5 — Surface milestone-health nudge (#942)
+
+`state insert-phase` returns a `nudge` field when the milestone has too many
+open phases (≥8 = consider, ≥12 = should-close). If `RESULT.nudge` is present,
+print it verbatim so the user is guided toward `/rcode-complete-milestone` +
+`/rcode-new-milestone` instead of silently accumulating phases. If absent, say
+nothing.
+
 ## Anti-patterns
 
 - Don't insert before Phase 1 (decimal 0.1 makes no sense)

package/rcode/workflows/plan.md

@@ -906,6 +906,23 @@ node ".rcode/bin/rcode-tools.cjs" state planned-phase --phase "${PHASE_NUMBER}"
 
 This updates STATUS to "Ready to execute", sets the correct plan count, and timestamps Last Activity.
 
+## 13c. Milestone-health nudge (#942)
+
+After recording completion, check whether the milestone has accumulated too many
+open phases — so planning the Nth phase of a sprawling milestone guides the user
+toward closing it instead of silently growing the roadmap:
+
+```bash
+HEALTH=$(node ".rcode/bin/rcode-tools.cjs" milestone-health 2>/dev/null)
+REC=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).recommendation||'')}catch{console.log('')}})")
+OPEN=$(echo "$HEALTH" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{console.log(JSON.parse(s).open_phases||0)}catch{console.log(0)}})")
+```
+
+- If `REC` is `should-close` (≥12 open): surface a hard nudge recommending
+  `/rcode-complete-milestone` then `/rcode-new-milestone`.
+- If `REC` is `consider-closing` (8–11 open): softer nudge.
+- If `healthy`: say nothing.
+
 ## 14. Present Final Status
 
 Route to `<offer_next>` OR `auto_advance` depending on flags/config.