fix(milestone): normalize STATE narrative after milestone completion

get-shit-done/bin/lib/milestone.cjs

@@ -196,7 +196,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     atomicWriteFileSync(milestonesPath, normalizeMd(`# Milestones\n\n${milestoneEntry}`));
   }
 
-  // Update STATE.md — use shared helpers that handle both **bold:** and plain Field: formats
+  // Update STATE.md — keep frontmatter/body semantically aligned after closure
   if (fs.existsSync(statePath)) {
     let stateContent = fs.readFileSync(statePath, 'utf-8');
 
@@ -205,6 +205,24 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null,
       `${version} milestone completed and archived`);
 
+    // Reset Current Position narrative so resume/progress flows do not keep
+    // pointing at closed-phase execution instructions.
+    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    const closedPositionBody =
+      `\nPhase: Milestone ${version} complete\n` +
+      `Plan: —\n` +
+      `Status: Awaiting next milestone\n` +
+      `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
+    if (positionPattern.test(stateContent)) {
+      stateContent = stateContent.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+    }
+
+    // Normalize operator-next-step tails that can become stale after close.
+    stateContent = stateContent.replace(
+      /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i,
+      `$1\n- Start the next milestone with /gsd-new-milestone\n\n`,
+    );
+
     writeStateMd(statePath, stateContent, cwd);
   }
 

sdk/src/query/phase-lifecycle.ts

@@ -1841,6 +1841,22 @@ export const milestoneComplete: QueryHandler = async (args, projectDir, workstre
         null,
         `${version} milestone completed and archived`,
       );
+
+      const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+      const closedPositionBody =
+        `\nPhase: Milestone ${version} complete\n` +
+        `Plan: —\n` +
+        `Status: Awaiting next milestone\n` +
+        `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
+      if (positionPattern.test(next)) {
+        next = next.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+      }
+
+      next = next.replace(
+        /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i,
+        `$1\n- Start the next milestone with /gsd-new-milestone\n\n`,
+      );
+
       return next;
     }, workstream);
   }

tests/milestone.test.cjs

@@ -227,6 +227,26 @@ describe('milestone complete command', () => {
     );
   });
 
+  test('normalizes stale STATE.md narrative tails after milestone complete (#3088)', () => {
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'ROADMAP.md'),
+      `# Roadmap v1.0\n`
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, '.planning', 'STATE.md'),
+      `# State\n\n**Status:** In progress\n**Last Activity:** 2025-01-01\n**Last Activity Description:** Working\n\n## Current Position\n\nPhase: 03 — EXECUTING\nPlan: 03-02\nStatus: Executing\nLast activity: 2025-01-01 — Running phase\n\n## Operator Next Steps\n\n- Re-run /gsd-complete-milestone v1.0\n`
+    );
+
+    const result = runGsdTools('milestone complete v1.0 --name Test', tmpDir);
+    assert.ok(result.success, `Command failed: ${result.error}`);
+
+    const state = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    assert.ok(state.includes('Phase: Milestone v1.0 complete'));
+    assert.ok(state.includes('Status: Awaiting next milestone'));
+    assert.ok(!state.includes('Re-run /gsd-complete-milestone'));
+    assert.ok(state.includes('/gsd-new-milestone'));
+  });
+
   test('handles missing ROADMAP.md gracefully', () => {
     // Only STATE.md — no ROADMAP.md, no REQUIREMENTS.md
     fs.writeFileSync(