feat(#2833): phase-lifecycle status-line — read-side (parseStateMd + formatGsdState scenes + tests + docs) (#2884)

* feat(#2833): parseStateMd reads phase-lifecycle frontmatter fields

Extend parseStateMd() to parse 4 new STATE.md frontmatter fields that drive
the phase-lifecycle status-line proposed in #2833:

- active_phase   : phase number when orchestrator is in-flight, null when idle
- next_action    : recommended next command when idle
- next_phases    : YAML flow array of phase numbers for next_action
- progress       : nested block with completed_phases / total_phases / percent

All fields default to undefined when absent — formatGsdState() (next commit)
degrades gracefully so existing STATE.md files keep rendering as before.

YAML scope intentionally narrow:
- Only top-level scalar keys (status, milestone, active_phase, next_action)
- Only single-line flow array for next_phases ([...])
- progress block requires 2-space indent for nested keys

Block sequences (- item over multiple lines) and inline comments inside
nested blocks are NOT parsed — keeping the regex-based parser predictable.
Comments outside frontmatter or after the closing --- still work.

Tests: all 27 existing tests still pass (no behavior change for STATE.md
files that don't carry the new fields).

Refs #2833

* feat(#2833): formatGsdState renders phase-lifecycle scenes + opt-in progress bar

Extend formatGsdState() with three lifecycle scenes that activate when the
new STATE.md frontmatter fields (added in the previous commit) are present.
Also append an opt-in progress bar to the milestone segment when
progress.percent is available.

Scenes (first match wins; falls through to the existing path otherwise):

  1. active_phase set     → 'v2.0 [██░] X% · Phase 4.5 executing'
                             (status field carries the lifecycle stage:
                              discussing / planning / executing / verifying)

  2. active_phase null +  → 'v2.0 [██░] X% · next execute-phase 4.5'
     next_action set         (idle state — surfaces what the user should
                              run next without opening STATE.md)

  3. percent=100 (or       → 'v2.0 [██████████] 100% · milestone complete'
     completed=total)

  4. (default fallback)    → 'v1.9 Code Quality · executing · ph (1/5)'
                             (existing rendering, byte-for-byte preserved
                              when none of the new fields are populated)

Backward compat is the design priority:
- STATE.md files without the new fields render identically to v1.38.x
- progress bar is opt-in (empty string when percent absent)
- Each new scene only activates when its specific fields are populated

A new helper renderProgressBar() generates the 10-segment bar that matches
the existing context meter style (so the two bars on the status-line are
visually consistent).

Tests: 27/27 existing tests still pass.

Refs #2833

* test(#2833): cover parseStateMd lifecycle fields + formatGsdState scenes

26 new tests organized in 5 describe blocks, modeled after the existing
enh-2538-statusline-last-command.test.cjs convention:

  parseStateMd #2833 lifecycle fields (7 tests)
    - reads active_phase / next_action / next_phases / progress.percent
    - 'null' literal handled correctly
    - YAML flow array parsing (1 item, multiple items)
    - progress nested block (3 fields)
    - absent fields return undefined

  formatGsdState #2833 lifecycle scenes (6 tests)
    - Scene 1: active_phase set → 'Phase X.Y <stage>'
    - Scene 2: idle + next_action → 'next <action> <phases>' (1+ phases)
    - Scene 3: percent=100 OR completed=total → 'milestone complete'

  formatGsdState #2833 backward compatibility (4 tests) — CRITICAL
    - Legacy STATE.md (no new fields) renders byte-for-byte unchanged
    - Empty state, partial state, progress-bar-opt-in all preserved

  progress bar rendering (6 tests)
    - 0% / 50% / 100% / clamping / opt-in absence

  formatGsdState #2833 scene priority (3 tests)
    - active_phase wins over next_action when both populated
    - next_action wins over fallback when active_phase null
    - percent=100 wins over fallback even with phase set

Combined run: 53/53 tests pass (existing 27 + new 26).

Refs #2833

* docs(#2833): describe phase-lifecycle frontmatter fields and rendering scenes

Add docs/STATE-MD-LIFECYCLE.md as the canonical reference for the four new
STATE.md frontmatter fields and the four status-line rendering scenes
introduced by this proposal:

- Frontmatter field reference (active_phase / next_action / next_phases /
  progress.percent) with type and population semantics
- Why progress.percent is intentionally the phase dimension and not the
  plans dimension (plans dimension trends optimistic when future phases
  are unplanned)
- The four rendering scenes including their priority order
- Stage-label convention for Scene 1 (discussing / planning / executing /
  verifying matching the four phase orchestrators)
- Frontmatter parsing constraints — frontmatter must start at file head,
  no comments inside nested blocks, next_phases is single-line flow only
- Backward-compatibility guarantee (locked in by the test suite)
- Cross-links to the foundation issue #1989 and the read-side issues
  this proposal helps close

The document deliberately scopes itself to the read-side (what the hook
parses, what it renders). Write-side SDK and workflow changes that
auto-maintain the fields are out of scope for this PR so each piece can
be reviewed independently — see the issue thread for the full proposal.

Refs #2833

* test(#2833): simplify '0% renders 10 empty segments' assertion

Address CodeRabbit nitpick — drop the convoluted assert.equal that built
the expected value via .replace() and rely on the existing assert.ok
includes-check. The behavior under test is unchanged; the assertion is
just easier to read.

Refs #2884 review comment

hooks/gsd-statusline.js

@@ -120,22 +120,60 @@ function readGsdState(dir) {
 
 /**
  * Parse STATE.md frontmatter + Phase line from body.
- * Returns { status, milestone, milestoneName, phaseNum, phaseTotal, phaseName }
+ *
+ * Returns:
+ *   { status, milestone, milestoneName, phaseNum, phaseTotal, phaseName,
+ *     activePhase, nextAction, nextPhases, completedPhases, totalPhases, percent }
+ *
+ * Phase-lifecycle fields (issue #2833):
+ *   - activePhase  : phase number ("4.5") when an orchestrator is mid-flight, null otherwise
+ *   - nextAction   : recommended next command ("execute-phase") when idle, null otherwise
+ *   - nextPhases   : array of phase numbers (["4.5"]) for nextAction, null otherwise
+ *   - completedPhases / totalPhases / percent : milestone progress dimension
+ *
+ * All new fields default to undefined when absent — formatGsdState() degrades
+ * gracefully so existing STATE.md files (without these fields) keep working.
  */
 function parseStateMd(content) {
   const state = {};
 
-  // YAML frontmatter between --- markers
+  // YAML frontmatter between --- markers (anchored at file start)
   const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (fmMatch) {
-    for (const line of fmMatch[1].split('\n')) {
+    const fm = fmMatch[1];
+    // Top-level scalar key: value
+    for (const line of fm.split('\n')) {
       const m = line.match(/^(\w+):\s*(.+)/);
       if (!m) continue;
       const [, key, val] = m;
       const v = val.trim().replace(/^["']|["']$/g, '');
+      // status / milestone-level fields (existing — preserved exactly)
       if (key === 'status') state.status = v === 'null' ? null : v;
       if (key === 'milestone') state.milestone = v === 'null' ? null : v;
       if (key === 'milestone_name') state.milestoneName = v === 'null' ? null : v;
+      // Phase-lifecycle fields (new in issue #2833)
+      // active_phase: phase number when an orchestrator is in-flight, null when idle
+      if (key === 'active_phase') state.activePhase = (v === 'null' || v === '') ? null : v;
+      // next_action: recommended command when idle (discuss-phase / plan-phase / execute-phase / verify-phase)
+      if (key === 'next_action') state.nextAction = (v === 'null' || v === '') ? null : v;
+    }
+    // next_phases YAML flow array: ["4.5", "4.6"] — single-line flow only
+    // Block sequences (- 4.5 / - 4.6 over multiple lines) are intentionally
+    // not parsed here; statusline only needs the primary recommendation.
+    const npMatch = fm.match(/^next_phases:\s*\[([^\]]*)\]/m);
+    if (npMatch) {
+      const items = npMatch[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+      state.nextPhases = items.length > 0 ? items : null;
+    }
+    // progress nested block: completed_phases / total_phases / percent (2-space indent)
+    const progMatch = fm.match(/^progress:\s*\n((?:[ \t]+\w+:.+\n?)+)/m);
+    if (progMatch) {
+      const cp = progMatch[1].match(/^[ \t]+completed_phases:\s*(\d+)/m);
+      const tp = progMatch[1].match(/^[ \t]+total_phases:\s*(\d+)/m);
+      const pc = progMatch[1].match(/^[ \t]+percent:\s*(\d+)/m);
+      if (cp) state.completedPhases = cp[1];
+      if (tp) state.totalPhases = tp[1];
+      if (pc) state.percent = pc[1];
     }
   }
 
@@ -161,31 +199,77 @@ function parseStateMd(content) {
   return state;
 }
 
+/**
+ * Render a 10-segment milestone progress bar (matches the context meter style).
+ *
+ * @param {number|string|null|undefined} percent — 0-100; missing/NaN returns ''
+ * @returns {string} '[█████░░░░░] 50%' or '' (so callers can `[bar].filter(Boolean)`)
+ */
+function renderProgressBar(percent) {
+  if (percent == null || isNaN(percent)) return '';
+  const pct = Math.max(0, Math.min(100, parseInt(percent, 10)));
+  const filled = Math.floor(pct / 10);
+  const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+  return `[${bar}] ${pct}%`;
+}
+
 /**
  * Format GSD state into display string.
- * Format: "v1.9 Code Quality · executing · fix-graphiti-deployment (1/5)"
- * Gracefully degrades when parts are missing.
+ *
+ * Backward-compatible default (no new fields populated):
+ *   "v1.9 Code Quality · executing · fix-graphiti-deployment (1/5)"
+ *
+ * Phase-lifecycle scenes (issue #2833 — activate when STATE.md frontmatter
+ * carries the new fields; otherwise rendering falls through to the default):
+ *
+ *   active_phase set                       → "v2.0 [██░] X% · Phase 4.5 executing"
+ *   active_phase null + next_action set    → "v2.0 [██░] X% · next execute-phase 4.5"
+ *   percent=100 (milestone done)           → "v2.0 [██████████] 100% · milestone complete"
+ *   none of the above                      → existing "<status> · <phase>" path
+ *
+ * Progress bar is opt-in: appended to the milestone segment only when
+ * progress.percent is present in frontmatter; absent → empty string.
  */
 function formatGsdState(s) {
   const parts = [];
 
-  // Milestone: version + name (skip placeholder "milestone")
+  // Milestone segment: version + name + (opt-in) progress bar
   if (s.milestone || s.milestoneName) {
     const ver = s.milestone || '';
     const name = (s.milestoneName && s.milestoneName !== 'milestone') ? s.milestoneName : '';
-    const ms = [ver, name].filter(Boolean).join(' ');
-    if (ms) parts.push(ms);
+    const bar = renderProgressBar(s.percent);
+    const pieces = [ver, name, bar].filter(Boolean);
+    if (pieces.length > 0) parts.push(pieces.join(' '));
   }
 
-  // Status
-  if (s.status) parts.push(s.status);
+  // Phase-lifecycle scenes (issue #2833) — first match wins; falls through to
+  // the original "<status> · <phase>" path when none of the new fields apply.
+  const phasesStr = (s.nextPhases && s.nextPhases.length > 0) ? s.nextPhases.join('/') : null;
 
-  // Phase
-  if (s.phaseNum && s.phaseTotal) {
-    const phase = s.phaseName
-      ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
-      : `ph ${s.phaseNum}/${s.phaseTotal}`;
-    parts.push(phase);
+  if (s.activePhase) {
+    // Scene 1: an orchestrator is mid-flight on this phase.
+    // stage = whichever lifecycle status was written by the orchestrator
+    //   (discussing / planning / executing / verifying)
+    const stage = s.status || '';
+    parts.push(stage ? `Phase ${s.activePhase} ${stage}` : `Phase ${s.activePhase}`);
+  } else if (s.nextAction && phasesStr) {
+    // Scene 2: idle + a recommended next command is visible to the user.
+    // Surfaces "what to run next" without the user opening STATE.md.
+    parts.push(`next ${s.nextAction} ${phasesStr}`);
+  } else if (s.percent === '100' || (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases)) {
+    // Scene 3: milestone complete (every phase done).
+    parts.push('milestone complete');
+  } else {
+    // Backward-compatible default — preserved EXACTLY for STATE.md files that
+    // don't carry the new lifecycle fields. Identical output to v1.38.x and
+    // earlier so no existing project's status-line changes shape.
+    if (s.status) parts.push(s.status);
+    if (s.phaseNum && s.phaseTotal) {
+      const phase = s.phaseName
+        ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
+        : `ph ${s.phaseNum}/${s.phaseTotal}`;
+      parts.push(phase);
+    }
   }
 
   return parts.join(' · ');