@opengsd/gsd-core 1.16.0 → 1.18.0

package/gsd-core/bin/lib/smart-entry.cjs

@@ -43,6 +43,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // #3696: the calendar-validity predicate moved to the STATE.md document module
 // so `state validate` can assert the same `last_activity` invariant this reader
 // already enforces (ADR-227). Two copies would let the two surfaces disagree
@@ -52,7 +53,7 @@ const ioMod = require("./io.cjs");
 const { output } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningPaths } = planningWorkspace;
+const { planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 const { extractFrontmatter, frontmatterBlock } = frontmatter;
@@ -60,6 +61,9 @@ const { extractFrontmatter, frontmatterBlock } = frontmatter;
 const phaseLifecycle = require("./phase-lifecycle.cjs");
 const { deriveProgressFromRoadmap } = phaseLifecycle;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+const { extractCurrentMilestone, scanMilestonePhaseIds } = roadmapParser;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateDocument = require("./state-document.cjs");
 const { stateFieldValue } = stateDocument;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -352,6 +356,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: false,
         roadmap_total_phases: null,
         roadmap_completed_phases: null,
+        milestone_phases: [],
         // No STATE.md (or unreadable) → no stamp to compare. Unknown, not fresh.
         state_commits_behind: null,
         state_commit_stale: null,
@@ -425,12 +430,18 @@ function detectSignals(cwd, now = Date.now) {
     // Progress table — isComplete falls back to the legacy comparison in that case.
     let roadmapTotalPhases = null;
     let roadmapCompletedPhases = null;
+    let milestonePhases = [];
     if (hasRoadmap) {
         try {
             const roadmapContent = node_fs_1.default.readFileSync(paths.roadmap, 'utf8');
             const derived = deriveProgressFromRoadmap(roadmapContent);
             roadmapTotalPhases = derived.totalPhases;
             roadmapCompletedPhases = derived.completedPhases;
+            // #5228: the ordered phase list of the current milestone, from the same
+            // scan the milestone-scoped commands use.
+            milestonePhases = [
+                ...scanMilestonePhaseIds(extractCurrentMilestone(roadmapContent, cwd), resolvePhaseIdConvention(cwd)),
+            ].sort(comparePhaseNum);
         }
         catch {
             /* ROADMAP.md unreadable — leave null; isComplete falls back to legacy. */
@@ -457,6 +468,7 @@ function detectSignals(cwd, now = Date.now) {
         stale_activity: staleActivity,
         roadmap_total_phases: roadmapTotalPhases,
         roadmap_completed_phases: roadmapCompletedPhases,
+        milestone_phases: milestonePhases,
         state_commits_behind: freshness.commits_behind,
         state_commit_stale: freshness.commit_stale,
     };
@@ -488,10 +500,21 @@ function isComplete(s) {
         // Legacy path: STATE.md comparison. It only fires when ROADMAP.md is
         // absent or has no Progress table, and uses canonical phase-id ordering
         // so dotted phase ids are never coerced to JavaScript numbers.
-        if (s.total_phases === null || s.current_phase === null)
-            return false;
-        if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+        if (s.current_phase === null)
             return false;
+        if (s.milestone_phases.length > 0) {
+            // #5228: compare against the milestone's LAST phase. The phase count is
+            // not a phase number once numbering continues from an earlier milestone.
+            const last = s.milestone_phases[s.milestone_phases.length - 1];
+            if (comparePhaseNum(s.current_phase, last) < 0)
+                return false;
+        }
+        else {
+            if (s.total_phases === null)
+                return false;
+            if (comparePhaseNum(s.current_phase, s.total_phases) < 0)
+                return false;
+        }
     }
     // Status regex: require milestone-level completion language. The pre-fix
     // regex matched any "shipped" / "done" substring (per-phase language).
@@ -558,52 +581,54 @@ function rec(id, label, command) {
     return action(id, label, command, true);
 }
 /** Per-situation ordered action list; recommended action first. */
-function actionsFor(situation, s) {
+function actionsFor(situation, s, runtime = 'claude') {
+    // #4859: commands are printed verbatim, so name them the way this runtime registers them.
+    const cmd = (name) => (0, runtime_slash_cjs_1.formatGsdSlash)(name, runtime);
     const phaseN = s.current_phase ?? '';
     const execLabel = phaseN === '' ? 'Continue executing' : `Continue executing phase ${phaseN}`;
     switch (situation) {
         case 'no-project':
             return [
-                rec('new-project', 'Start a new project', '/gsd:new-project'),
-                action('map-codebase', 'Map an existing codebase', '/gsd:map-codebase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('new-project', 'Start a new project', cmd('new-project')),
+                action('map-codebase', 'Map an existing codebase', cmd('map-codebase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'paused':
             return [
-                rec('resume-work', 'Resume work', '/gsd:resume-work'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('resume-work', 'Resume work', cmd('resume-work')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
         case 'blocked':
             return [
-                rec('debug', 'Debug the blocker', '/gsd:debug'),
-                action('verify-work', 'Verify current work', '/gsd:verify-work'),
-                action('capture', 'Capture a note', '/gsd:capture'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('debug', 'Debug the blocker', cmd('debug')),
+                action('verify-work', 'Verify current work', cmd('verify-work')),
+                action('capture', 'Capture a note', cmd('capture')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'verify-failed':
             return [
-                rec('verify-work', 'Re-verify work', '/gsd:verify-work'),
-                action('debug', 'Debug the failure', '/gsd:debug'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('verify-work', 'Re-verify work', cmd('verify-work')),
+                action('debug', 'Debug the failure', cmd('debug')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'needs-first-phase':
             return [
-                rec('discuss-phase', 'Discuss the first phase', '/gsd:discuss-phase'),
-                action('plan-phase', 'Plan phase 1', '/gsd:plan-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('discuss-phase', 'Discuss the first phase', cmd('discuss-phase')),
+                action('plan-phase', 'Plan phase 1', cmd('plan-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'planning':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, '/gsd:progress --next'),
-                action('plan-phase', `Plan phase ${phaseN || 1}`, '/gsd:plan-phase'),
-                action('discuss-phase', 'Discuss before planning', '/gsd:discuss-phase'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('progress-next', `Advance to the next step (plan phase ${phaseN || 1})`, cmd('progress --next')),
+                action('plan-phase', `Plan phase ${phaseN || 1}`, cmd('plan-phase')),
+                action('discuss-phase', 'Discuss before planning', cmd('discuss-phase')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'executing':
             // In-project forward motion delegates to the single gated engine
@@ -612,44 +637,66 @@ function actionsFor(situation, s) {
             // /gsd:execute-phase here — that divergence is why the old flat /gsd-next
             // was removed (#3054). Direct execute stays as an explicit secondary choice.
             return [
-                rec('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('execute-phase', execLabel, '/gsd:execute-phase'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
+                rec('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('execute-phase', execLabel, cmd('execute-phase')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('code-review', 'Review recent work', cmd('code-review')),
             ];
         case 'verify-pending':
             // Forward motion → delegate to the single gated engine (see 'executing').
             return [
-                rec('progress-next', 'Advance to the next step (verify)', '/gsd:progress --next'),
-                action('verify-work', 'Verify work', '/gsd:verify-work'),
-                action('code-review', 'Review recent work', '/gsd:code-review'),
-                action('ship', 'Ship completed work', '/gsd:ship'),
+                rec('progress-next', 'Advance to the next step (verify)', cmd('progress --next')),
+                action('verify-work', 'Verify work', cmd('verify-work')),
+                action('code-review', 'Review recent work', cmd('code-review')),
+                action('ship', 'Ship completed work', cmd('ship')),
             ];
         case 'idle-stranded':
             return [
-                rec('ship', 'Ship committed work', '/gsd:ship'),
-                action('complete-milestone', 'Complete the milestone', '/gsd:complete-milestone'),
-                action('progress', 'Show progress', '/gsd:progress'),
-                action('capture', 'Capture a note', '/gsd:capture'),
+                rec('ship', 'Ship committed work', cmd('ship')),
+                action('complete-milestone', 'Complete the milestone', cmd('complete-milestone')),
+                action('progress', 'Show progress', cmd('progress')),
+                action('capture', 'Capture a note', cmd('capture')),
             ];
         case 'complete':
             return [
-                rec('new-milestone', 'Start a new milestone', '/gsd:new-milestone'),
-                action('extract-learnings', 'Extract learnings', '/gsd:extract-learnings'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('progress', 'Show progress', '/gsd:progress'),
+                rec('new-milestone', 'Start a new milestone', cmd('new-milestone')),
+                action('extract-learnings', 'Extract learnings', cmd('extract-learnings')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('progress', 'Show progress', cmd('progress')),
             ];
         case 'unknown':
         default:
             return [
-                rec('progress', 'Show progress', '/gsd:progress'),
-                action('progress-next', 'Advance to the next step', '/gsd:progress --next'),
-                action('quick', 'Quick task', '/gsd:quick'),
-                action('help', 'Show help', '/gsd:help'),
+                rec('progress', 'Show progress', cmd('progress')),
+                action('progress-next', 'Advance to the next step', cmd('progress --next')),
+                action('quick', 'Quick task', cmd('quick')),
+                action('help', 'Show help', cmd('help')),
             ];
     }
 }
 // ─── Summary line ─────────────────────────────────────────────────────────────
+function phaseSummary(s) {
+    const phase = s.current_phase;
+    // Preserve the milestone ordinal introduced by #5228 when it is known.
+    const at = phase === null ? -1 : s.milestone_phases.findIndex((id) => comparePhaseNum(id, phase) === 0);
+    if (at >= 0)
+        return `Phase ${at + 1} of ${s.milestone_phases.length}`;
+    const total = s.total_phases;
+    const legacy = `Phase ${phase ?? '?'} of ${total ?? '?'}`;
+    const roadmapTotal = s.roadmap_total_phases;
+    // Keep the recorded pair when roadmap counts are unavailable, or when the
+    // pair can describe a single milestone without changing its existing text.
+    if (phase === null || total === null || roadmapTotal === null || roadmapTotal <= 0
+        || (total === roadmapTotal && comparePhaseNum(phase, total) <= 0)) {
+        return legacy;
+    }
+    // When the recorded pair cannot safely describe this roadmap, label its
+    // counts separately rather than printing a mixed-scope ratio.
+    const roadmapDone = s.roadmap_completed_phases;
+    return roadmapDone === null
+        ? `Phase ${phase} (${roadmapTotal} roadmap phases)`
+        : `Phase ${phase} (${roadmapDone} of ${roadmapTotal} roadmap phases complete)`;
+}
 function buildSummary(situation, s) {
     switch (situation) {
         case 'no-project':
@@ -663,7 +710,7 @@ function buildSummary(situation, s) {
         case 'needs-first-phase':
             return 'Project initialized — plan your first phase';
         case 'planning':
-            return `Phase ${s.current_phase ?? '?'} of ${s.total_phases ?? '?'} — needs a plan`;
+            return `${phaseSummary(s)} — needs a plan`;
         case 'executing':
             return progressLine('executing', s);
         case 'verify-pending':
@@ -680,7 +727,7 @@ function buildSummary(situation, s) {
 function progressLine(tail, s) {
     const parts = [];
     if (s.current_phase !== null && s.total_phases !== null) {
-        parts.push(`Phase ${s.current_phase} of ${s.total_phases}`);
+        parts.push(phaseSummary(s));
     }
     else if (s.current_phase !== null) {
         parts.push(`Phase ${s.current_phase}`);
@@ -699,7 +746,7 @@ function progressLine(tail, s) {
 function classifyProject(cwd, now = Date.now) {
     const signals = detectSignals(cwd, now);
     const situation = classify(signals);
-    const actions = actionsFor(situation, signals);
+    const actions = actionsFor(situation, signals, (0, runtime_slash_cjs_1.resolveRuntime)(cwd));
     const recommended = actions.find((a) => a.recommended)?.id ?? 'progress';
     const summary = buildSummary(situation, signals);
     return { situation, recommended, summary, signals, actions };
@@ -718,6 +765,6 @@ function runSmartEntry(cwd, args, raw) {
         return;
     }
     // Human mode: a compact one-liner plus the recommended action.
-    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? '/gsd:progress'}`;
+    const human = `${result.summary}\nRecommended: ${result.recommended} → ${result.actions.find((a) => a.id === result.recommended)?.command ?? (0, runtime_slash_cjs_1.runtimeCommand)(cwd, 'progress')}`;
     output(null, true, human);
 }

package/gsd-core/bin/lib/state-document.cjs

@@ -14,6 +14,7 @@ exports.isUnfilledFieldValue = isUnfilledFieldValue;
 exports.leadingCalendarDate = leadingCalendarDate;
 exports.isRealCalendarDate = isRealCalendarDate;
 exports.stateFieldContinuation = stateFieldContinuation;
+exports.fieldContinuationEnd = fieldContinuationEnd;
 exports.stateExtractField = stateExtractField;
 exports.stateFieldValue = stateFieldValue;
 exports.stateCurrentPositionSlice = stateCurrentPositionSlice;
@@ -378,7 +379,16 @@ function stateFieldContinuation(content, fieldName) {
     if (!rest.startsWith('\n'))
         return null; // end of file: nothing follows
     const lines = rest.slice(1).split('\n').map((line) => line.replace(/\r$/, ''));
-    const continuation = [];
+    const continuation = lines.slice(0, continuationLineCount(lines)).map((line) => line.trim());
+    return continuation.length ? continuation.join(' ') : null;
+}
+/**
+ * How many of the lines directly below a single-line field belong to its value: the scan
+ * `stateFieldContinuation` reports on, shared so a writer that replaces the value removes exactly
+ * the lines a validator would call its continuation (#4945). `lines` are CR-free.
+ */
+function continuationLineCount(lines) {
+    let count = 0;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (!line.trim())
@@ -391,9 +401,33 @@ function stateFieldContinuation(content, fieldName) {
         // title, so stop before consuming it rather than after.
         if (i + 1 < lines.length && SETEXT_UNDERLINE_RE.test(lines[i + 1]))
             break;
-        continuation.push(line.trim());
+        count++;
     }
-    return continuation.length ? continuation.join(' ') : null;
+    return count;
+}
+/**
+ * The index just past a single-line field's value AND the continuation lines that wrap it
+ * (#4945). `valueEnd` is where the field's own line ends (before its line terminator). Replacing
+ * `content.slice(valueEnd, result)` with nothing removes every continuation line and the
+ * terminator in front of each, so the terminator after the last one stays. Returns `valueEnd`
+ * when nothing continues the value.
+ */
+function fieldContinuationEnd(content, valueEnd) {
+    const tail = content.slice(valueEnd);
+    const first = /^\r?\n/.exec(tail);
+    if (!first)
+        return valueEnd;
+    const rawLines = tail.slice(first[0].length).split('\n');
+    const count = continuationLineCount(rawLines.map((line) => line.replace(/\r$/, '')));
+    if (count === 0)
+        return valueEnd;
+    let removed = first[0].length + (count - 1);
+    for (let i = 0; i < count; i++)
+        removed += rawLines[i].length;
+    // The terminator after the last continuation line stays; on a CRLF document that includes its CR.
+    if (rawLines[count - 1].endsWith('\r'))
+        removed -= 1;
+    return valueEnd + removed;
 }
 function stateExtractField(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);

package/gsd-core/bin/lib/state-transition.cjs

@@ -417,7 +417,41 @@ function createStateWriteIntent(transaction, init = {}) {
         err.code = 'STATE_WRITE_INTENT_TRANSACTION_REQUIRED';
         throw err;
     }
-    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({ field: a.field, requirement: a.requirement })));
+    // C2 (ADR-4629 §8.2): an unknown `requirement` is a construction error. §8.2
+    // judges only `'required'` assertions, so a mistyped value (`'Required'`)
+    // would otherwise be silently skipped: a fail-open verifier.
+    for (const a of init.assertions ?? []) {
+        if (a.requirement !== 'required' && a.requirement !== 'best-effort') {
+            const err = new Error(`createStateWriteIntent: assertion ${JSON.stringify(a.field)} has unknown requirement ` +
+                `${JSON.stringify(a.requirement)}; expected 'required' or 'best-effort' (ADR-4629 §8.1).`);
+            err.code = 'STATE_WRITE_INTENT_REQUIREMENT_INVALID';
+            throw err;
+        }
+    }
+    if (init.scope !== undefined && init.scope !== 'narrow' && init.scope !== 'broad') {
+        const err = new Error(`createStateWriteIntent: unknown scope ${JSON.stringify(init.scope)}; expected 'narrow' or 'broad' ` +
+            '(ADR-4629 §8.1).');
+        err.code = 'STATE_WRITE_INTENT_SCOPE_INVALID';
+        throw err;
+    }
+    // C2 (ADR-4629 §8.2): an unknown `target` is a construction error, never a
+    // silent fall-back to field semantics (a JS caller passing `'sections'`).
+    for (const a of init.assertions ?? []) {
+        if (a.target !== undefined && a.target !== 'field' && a.target !== 'section') {
+            const err = new Error(`createStateWriteIntent: assertion ${JSON.stringify(a.field)} has unknown target ` +
+                `${JSON.stringify(a.target)}; expected 'field' or 'section' (ADR-4629 §8.2).`);
+            err.code = 'STATE_WRITE_INTENT_TARGET_INVALID';
+            throw err;
+        }
+    }
+    // C2 (ADR-4629 §8.2): `target` / `value` are copied only when the caller set
+    // them, so a C1-shaped assertion stays exactly `{ field, requirement }`.
+    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({
+        field: a.field,
+        requirement: a.requirement,
+        ...(a.target !== undefined ? { target: a.target } : {}),
+        ...(a.value !== undefined ? { value: a.value } : {}),
+    })));
     return Object.freeze({
         ...transaction,
         assertions,
@@ -888,6 +922,8 @@ function transitionCore(content, intent, deps) {
  */
 function beginPhaseCore(content, intent, deps) {
     const updated = [];
+    // #4945: a re-entry whose earlier plans already have summaries starts at the first plan still to run.
+    const startPlan = intent.startPlan && intent.startPlan > 0 ? Math.floor(intent.startPlan) : 1;
     // #1255: body-field replacements operate on body only (frontmatter stripped),
     // not on the full content. The YAML `status:` key matches `^Status:\s*`
     // before the body pipe-table row if full content is passed.
@@ -943,7 +979,7 @@ function beginPhaseCore(content, intent, deps) {
         if (intent.phaseName) {
             tryField('Current Phase Name', intent.phaseName);
         }
-        tryField('Current Plan', '1');
+        tryField('Current Plan', String(startPlan));
         if (intent.planCount) {
             tryField('Total Plans in Phase', String(intent.planCount));
         }
@@ -962,14 +998,21 @@ function beginPhaseCore(content, intent, deps) {
         // end-of-line (inert here since `.` never crosses line terminators
         // without `/s`, which is not set).
         const focusPattern = /^([ \t]*\*\*Current focus:\*\*[ \t]*)(.*)$/im;
-        if (focusPattern.test(body)) {
-            body = body.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
+        const focusMatch = focusPattern.exec(body);
+        if (focusMatch) {
+            // #4945: a value an author wrapped onto further lines is replaced whole, so its tail is not
+            // left behind under the new value. The lines that count are the ones `state validate` already
+            // reports as a field's continuation (stops at a blank line, a heading, a list item, a table
+            // row, a fence or a sibling field). An empty first line has no value to continue.
+            const valueEnd = focusMatch.index + focusMatch[0].length;
+            const end = focusMatch[2].trim() === '' ? valueEnd : (0, state_document_cjs_2.fieldContinuationEnd)(body, valueEnd);
+            body = body.slice(0, focusMatch.index) + focusMatch[1] + focusLabel + body.slice(end);
             updated.push('Current focus');
         }
         // ## Current Position section mutation (#1104, #1365).
         // `locateCurrentPosition` (fence-aware, tokenizeHeadings-based) locates
         // the section; mirrors state.cts:2261-2324 byte-for-behaviour.
-        body = mutateCurrentPositionFirstTime(body, intent, today, updated);
+        body = mutateCurrentPositionFirstTime(body, { ...intent, startPlan }, today, updated);
     }
     else {
         // Resume path: only update Last activity timestamp in Current Position
@@ -1073,7 +1116,7 @@ function mutateCurrentPositionFirstTime(body, intent, today, updated) {
             sectionBody = replaced;
     }
     // Plan line.
-    const planValue = `1 of ${intent.planCount || '?'}`;
+    const planValue = `${intent.startPlan} of ${intent.planCount || '?'}`;
     if (/^Plan:/m.test(sectionBody)) {
         sectionBody = sectionBody.replace(/^Plan:.*$/m, `Plan: ${planValue}`);
     }
@@ -1575,9 +1618,30 @@ function advancePlanCore(content, deps) {
         data: { advanced: true, previous_plan: currentPlan, current_plan: newPlan, total_plans: totalPlans },
     };
 }
-// ----------------------------------------------------------------------------
-// completePhase — intent implementation (Phase 3)
-// ----------------------------------------------------------------------------
+/**
+ * #4824: Status / Current Plan / Stopped-at wording for the phase a
+ * completion hands off to. The historical `Ready to plan` is only true for a
+ * phase with no plans; a phase that already has PLANs routes to execution,
+ * and one whose plans all have SUMMARYs awaits verification — never back to
+ * `/gsd-plan-phase`. Which phase is selected stays #4078's rule.
+ */
+function nextPhaseWording(disk) {
+    switch (disk?.status) {
+        case 'PLANNED':
+            return { status: 'Ready to execute', currentPlan: 'Not started', stoppedAt: 'ready to execute' };
+        case 'IN_PROGRESS':
+            return { status: 'Ready to execute', currentPlan: String(disk.summaryCount + 1), stoppedAt: 'ready to execute' };
+        case 'EXECUTED':
+        case 'NEEDS_REVIEW':
+            return {
+                status: 'Phase complete — ready for verification',
+                currentPlan: String(disk.planCount),
+                stoppedAt: 'ready to verify',
+            };
+        default:
+            return { status: 'Ready to plan', currentPlan: 'Not started', stoppedAt: 'ready to plan' };
+    }
+}
 /**
  * Apply a `completePhase` transition to STATE.md content.
  *
@@ -1585,7 +1649,9 @@ function advancePlanCore(content, deps) {
  * (phase.cts) onto the substrate. Owns the field-classification-governed body
  * mutations: Current Phase (preserving the `of total` shape and phase name),
  * Current Phase Name, Status (`All phases complete` on the last phase, else
- * `Ready to plan` per ADR-2207), Current Plan (`Not started`), Last Activity + Description,
+ * `Ready to plan` per ADR-2207 — or, #4824, the next phase's disk-derived
+ * wording when it is already planned or executed), Current Plan (`Not started`
+ * unless the next phase is in flight), Last Activity + Description,
  * and the Completed/Total Phases + Progress percent block (re-derived from the
  * roadmap via the injected `roadmapProvider`).
  *
@@ -1602,6 +1668,7 @@ function advancePlanCore(content, deps) {
 function completePhaseCore(content, intent, deps) {
     const updated = [];
     const today = deps.clock.localToday();
+    const nextWording = nextPhaseWording(intent.isLastPhase ? null : intent.nextPhaseDisk ?? null);
     // Consult the field-classification table for the frontmatter keys this
     // transition touches (same guard beginPhaseCore applies). A missing row is a
     // substrate defect — fail loudly rather than silently re-encoding policy.
@@ -1665,7 +1732,7 @@ function completePhaseCore(content, intent, deps) {
     // Status — `All phases complete` on the final phase (ADR-2207), otherwise
     // `Ready to plan`. Milestone termination (`<version> milestone complete`) is
     // owned solely by the milestone-close verb (milestoneCompleteCore).
-    const statusValue = intent.isLastPhase ? 'All phases complete' : 'Ready to plan';
+    const statusValue = intent.isLastPhase ? 'All phases complete' : nextWording.status;
     const statusAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Status', null, statusValue);
     if (statusAfter !== body) {
         body = statusAfter;
@@ -1682,10 +1749,10 @@ function completePhaseCore(content, intent, deps) {
     let planAfter;
     const positionScope = (0, state_document_cjs_1.stateCurrentPositionSlice)(body);
     if (positionScope !== null) {
-        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', 'Not started'), { levelBounded: true });
+        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', nextWording.currentPlan), { levelBounded: true });
     }
     else {
-        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', nextWording.currentPlan);
     }
     if (planAfter !== body) {
         body = planAfter;
@@ -1729,7 +1796,7 @@ function completePhaseCore(content, intent, deps) {
     // milestone termination wording stays owned by milestoneCompleteCore.
     const stoppedAtLine = intent.isLastPhase
         ? `Phase ${intent.phaseNum} complete — all phases complete`
-        : `Phase ${intent.phaseNum} complete${intent.nextPhaseNum ? `, ready to plan Phase ${intent.nextPhaseNum}` : ''}`;
+        : `Phase ${intent.phaseNum} complete${intent.nextPhaseNum ? `, ${nextWording.stoppedAt} Phase ${intent.nextPhaseNum}` : ''}`;
     const stoppedAfter = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, 'Stopped At', 'Stopped at', stoppedAtLine);
     if (stoppedAfter !== body) {
         body = stoppedAfter;
@@ -1740,15 +1807,27 @@ function completePhaseCore(content, intent, deps) {
     // Only runs when a Completed Phases field exists (the existing guard).
     const completedRaw = (0, state_document_cjs_1.stateExtractField)(body, 'Completed Phases');
     if (completedRaw !== null) {
-        let newCompleted = parseInt(completedRaw, 10);
+        const recordedCompleted = parseInt(completedRaw, 10);
+        let newCompleted = recordedCompleted;
         let derivedTotalPhases = null;
         const roadmapContent = deps.roadmapProvider ? deps.roadmapProvider() : null;
         if (roadmapContent) {
             const derived = (0, phase_lifecycle_cjs_1.deriveProgressFromRoadmap)(roadmapContent);
-            if (derived.completedPhases !== null)
-                newCompleted = derived.completedPhases;
-            if (derived.totalPhases !== null)
-                derivedTotalPhases = derived.totalPhases;
+            // #4901: completed counters only ratchet up, like the frontmatter twin
+            // (applyAuthoritativeProgressSubkeys, completedOnlyRaise). A derivation
+            // that lands BELOW the recorded counter read a narrower scope than the
+            // counter spans (e.g. the first `## Progress` section of a multi-milestone
+            // roadmap), so its total is just as suspect: keep the recorded counter and
+            // fall back to the recorded Total Phases for the percent below.
+            const derivedLowered = derived.completedPhases !== null
+                && Number.isFinite(recordedCompleted)
+                && derived.completedPhases < recordedCompleted;
+            if (!derivedLowered) {
+                if (derived.completedPhases !== null)
+                    newCompleted = derived.completedPhases;
+                if (derived.totalPhases !== null)
+                    derivedTotalPhases = derived.totalPhases;
+            }
         }
         // #3057 B9: only mark 'Completed Phases' updated when the text actually
         // changed. `stateReplaceField` returns the full (re-)substituted content