fix(insert-phase): update STATE.md next-phase recommendation after phase insertion (#2509)

* fix(insert-phase): update STATE.md next-phase recommendation after inserting a phase

Closes #2502

* fix(insert-phase): update all STATE.md pointers; tighten test scope

Two follow-up fixes from CodeRabbit review of #2509:

1. The update_project_state instruction only said to find "the line" for
   the next-phase recommendation. STATE.md can have multiple pointers
   (structured current_phase: field AND prose recommendation text).
   Updated wording to explicitly require updating all of them in the same
   edit.

2. The regression test for the next-phase pointer update scanned the
   entire file, so a match anywhere would pass even if update_project_state
   itself was missing the instruction. Scoped the assertion to only the
   content inside <step name="update_project_state"> to prevent false
   positives.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

get-shit-done/workflows/insert-phase.md

@@ -66,7 +66,11 @@ Extract from result: `phase_number`, `after_phase`, `name`, `slug`, `directory`.
 Update STATE.md to reflect the inserted phase:
 
 1. Read `.planning/STATE.md`
-2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+2. Update STATE.md's next-phase pointers to the newly inserted phase `{decimal_phase}`:
+   - Update structured field(s) used by tooling (e.g. `current_phase:`) to `{decimal_phase}`.
+   - Update human-readable recommendation text (e.g. `## Current Phase`, `Next recommended run:`) to `{decimal_phase}`.
+   - If multiple pointer locations exist, update all of them in the same edit.
+3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
    ```
    - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
    ```

tests/bug-2502-insert-phase-state-update.test.cjs

@@ -0,0 +1,62 @@
+/**
+ * Regression test for #2502: insert-phase does not update STATE.md's
+ * next-phase recommendation after inserting a decimal phase.
+ *
+ * Root cause: insert-phase.md's update_project_state step only added a
+ * "Roadmap Evolution" note to STATE.md, but never updated the "Current Phase"
+ * / next-run recommendation to point at the newly inserted phase.
+ *
+ * Fix: insert-phase.md must include a step that updates STATE.md's next-phase
+ * pointer (current_phase / next recommended run) to the newly inserted phase.
+ */
+
+'use strict';
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const INSERT_PHASE_PATH = path.join(
+  __dirname, '..', 'get-shit-done', 'workflows', 'insert-phase.md'
+);
+
+describe('bug-2502: insert-phase must update STATE.md next-phase recommendation', () => {
+  test('insert-phase.md exists', () => {
+    assert.ok(fs.existsSync(INSERT_PHASE_PATH), 'insert-phase.md should exist');
+  });
+
+  test('insert-phase.md contains a STATE.md next-phase update instruction', () => {
+    const content = fs.readFileSync(INSERT_PHASE_PATH, 'utf-8');
+
+    // Must reference STATE.md and the concept of updating the next/current phase pointer
+    const mentionsStateUpdate = (
+      /STATE\.md.{0,200}(next.phase|current.phase|next.run|recommendation)/is.test(content) ||
+      /(next.phase|current.phase|next.run|recommendation).{0,200}STATE\.md/is.test(content)
+    );
+
+    assert.ok(
+      mentionsStateUpdate,
+      'insert-phase.md must instruct updating STATE.md\'s next-phase recommendation to point to the newly inserted phase'
+    );
+  });
+
+  test('insert-phase.md update_project_state step covers next-phase pointer', () => {
+    const content = fs.readFileSync(INSERT_PHASE_PATH, 'utf-8');
+
+    const stepMatch = content.match(/<step name="update_project_state">([\s\S]*?)<\/step>/i);
+    assert.ok(stepMatch, 'insert-phase.md must contain update_project_state step');
+    const stepContent = stepMatch[1];
+
+    const hasNextPhasePointerUpdate = (
+      /\bcurrent[_ -]?phase\b/i.test(stepContent) ||
+      /\bnext[_ -]?phase\b/i.test(stepContent) ||
+      /\bnext recommended run\b/i.test(stepContent)
+    );
+
+    assert.ok(
+      hasNextPhasePointerUpdate,
+      'insert-phase.md update_project_state step must update STATE.md\'s next-phase pointer (current_phase) to the inserted decimal phase'
+    );
+  });
+});