gsd-pi 2.65.0 → 2.66.0-dev.6c91c1f

package/src/resources/extensions/gsd/tests/discuss-incremental-persistence.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Regression test for discuss phase incremental persistence (#2152).
+ * Verifies both milestone and slice discuss prompts instruct agents to
+ * save CONTEXT-DRAFT incrementally during question rounds.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const promptsDir = join(__dirname, "..", "prompts");
+
+describe("discuss incremental persistence (#2152)", () => {
+  test("milestone discuss prompt includes CONTEXT-DRAFT save instruction", () => {
+    const content = readFileSync(join(promptsDir, "guided-discuss-milestone.md"), "utf-8");
+    assert.match(content, /CONTEXT-DRAFT/, "should mention CONTEXT-DRAFT");
+    assert.match(content, /Incremental persistence/, "should have incremental persistence section");
+    assert.match(content, /gsd_summary_save/, "should use gsd_summary_save tool");
+  });
+
+  test("slice discuss prompt includes CONTEXT-DRAFT save instruction", () => {
+    const content = readFileSync(join(promptsDir, "guided-discuss-slice.md"), "utf-8");
+    assert.match(content, /CONTEXT-DRAFT/, "should mention CONTEXT-DRAFT");
+    assert.match(content, /Incremental persistence/, "should have incremental persistence section");
+  });
+
+  test("drafts are saved silently without user notification", () => {
+    const milestone = readFileSync(join(promptsDir, "guided-discuss-milestone.md"), "utf-8");
+    const slice = readFileSync(join(promptsDir, "guided-discuss-slice.md"), "utf-8");
+    assert.match(milestone, /Do NOT mention this save to the user/);
+    assert.match(slice, /Do NOT mention this to the user/);
+  });
+});

package/src/resources/extensions/gsd/tests/discuss-slice-structured-questions.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Regression test for discuss-slice structured questions availability
+ *
+ * The guided-discuss-slice.md template must use the structuredQuestionsAvailable
+ * template variable to conditionally switch between ask_user_questions tool
+ * calls and plain-text questions, so the prompt works correctly when the
+ * structured questions tool is not available.
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const template = readFileSync(
+  resolve(process.cwd(), 'src', 'resources', 'extensions', 'gsd', 'prompts', 'guided-discuss-slice.md'),
+  'utf-8',
+)
+
+describe('discuss-slice structuredQuestionsAvailable template variable', () => {
+  it('template references structuredQuestionsAvailable variable', () => {
+    assert.ok(
+      template.includes('{{structuredQuestionsAvailable}}'),
+      'guided-discuss-slice.md must use {{structuredQuestionsAvailable}} template variable',
+    )
+  })
+
+  it('template handles both true and false cases', () => {
+    const trueCase = template.includes('`{{structuredQuestionsAvailable}}` is `true`')
+    const falseCase = template.includes('`{{structuredQuestionsAvailable}}` is `false`')
+
+    assert.ok(trueCase, 'template must have a branch for structuredQuestionsAvailable=true')
+    assert.ok(falseCase, 'template must have a branch for structuredQuestionsAvailable=false')
+  })
+
+  it('false case instructs plain text questions', () => {
+    const falseIdx = template.indexOf('`{{structuredQuestionsAvailable}}` is `false`')
+    assert.ok(falseIdx !== -1)
+
+    const afterFalse = template.slice(falseIdx, falseIdx + 300)
+    assert.ok(
+      afterFalse.includes('plain text'),
+      'when structuredQuestionsAvailable is false, questions should be in plain text',
+    )
+  })
+})

package/src/resources/extensions/gsd/tests/dispatch-guard-closed-status.test.ts

@@ -0,0 +1,33 @@
+/**
+ * dispatch-guard-closed-status.test.ts — #3653
+ *
+ * Verify that the dispatch guard uses isClosedStatus() instead of a raw
+ * `status === "complete"` check when determining whether a slice is done.
+ * Reconciled slices may carry statuses like "skipped" or "cancelled" which
+ * are also closed — the raw check caused false dispatch blocks.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "dispatch-guard.ts");
+
+describe("dispatch-guard isClosedStatus migration (#3653)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("imports isClosedStatus from status-guards", () => {
+    assert.match(source, /import\s*\{[^}]*isClosedStatus[^}]*\}\s*from\s*["']\.\/status-guards/);
+  });
+
+  test("uses isClosedStatus() for slice done check instead of raw comparison", () => {
+    assert.match(source, /done:\s*isClosedStatus\(r\.status\)/);
+  });
+
+  test("does not use raw status === 'complete' for DB slice rows", () => {
+    assert.doesNotMatch(source, /done:\s*r\.status\s*===\s*["']complete["']/);
+  });
+});

package/src/resources/extensions/gsd/tests/dispatcher-stuck-planning.test.ts

@@ -0,0 +1,37 @@
+/**
+ * dispatcher-stuck-planning.test.ts — #3656
+ *
+ * Verify that state.ts contains the disk-to-DB task reconciliation logic
+ * that prevents the dispatcher from getting stuck in an infinite planning
+ * loop when the planner writes a PLAN.md but never calls the persistence
+ * tool, leaving the DB with zero task rows.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "state.ts");
+
+describe("dispatcher stuck-planning reconciliation (#3656)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("imports insertTask from gsd-db", () => {
+    assert.match(source, /import\s*\{[^}]*insertTask[^}]*\}\s*from/);
+  });
+
+  test("contains plan-file task reconciliation block", () => {
+    assert.match(source, /tasks\.length\s*===\s*0\s*&&\s*planFile/);
+  });
+
+  test("calls insertTask for each disk plan task", () => {
+    assert.match(source, /insertTask\(\{/);
+  });
+
+  test("references issue #3600 in reconciliation comment", () => {
+    assert.match(source, /#3600/);
+  });
+});

package/src/resources/extensions/gsd/tests/error-success-mask.test.ts

@@ -0,0 +1,37 @@
+/**
+ * error-success-mask.test.ts — #3664
+ *
+ * Verify that the agent-end-recovery error handler detects when errorMessage
+ * is uninformative (e.g. "success", "ok", "unknown") and falls back to
+ * extracting the real error from the assistant message text content.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const sourceFile = join(__dirname, "..", "bootstrap", "agent-end-recovery.ts");
+
+describe("error-success mask detection (#3664)", () => {
+  const source = readFileSync(sourceFile, "utf-8");
+
+  test("detects useless errorMessage values with regex", () => {
+    assert.match(source, /success\|ok\|true\|error\|unknown/i);
+  });
+
+  test("extracts display message from content text block", () => {
+    assert.match(source, /textBlock/);
+    assert.match(source, /\.text\.slice\(0,\s*300\)/);
+  });
+
+  test("classifies using rawErrorMsg, not displayMsg", () => {
+    assert.match(source, /classifyError\(rawErrorMsg/);
+  });
+
+  test("references issue #3588 in comments", () => {
+    assert.match(source, /#3588/);
+  });
+});

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -19,8 +19,10 @@
 import { createTestContext } from "./test-helpers.ts";
 import {
   withTimeout,
+  FINALIZE_PRE_TIMEOUT_MS,
   FINALIZE_POST_TIMEOUT_MS,
 } from "../auto/finalize-timeout.ts";
+import { MAX_FINALIZE_TIMEOUTS } from "../auto/types.ts";
 
 const { assertTrue, assertEq, report } = createTestContext();
 
@@ -78,6 +80,25 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertTrue(caught, "rejection should propagate");
 }
 
+// ═══ Test: FINALIZE_PRE_TIMEOUT_MS is defined and reasonable ═════════════════
+
+{
+  console.log("\n=== #3757: pre-verification timeout constant is defined and reasonable ===");
+
+  assertTrue(
+    typeof FINALIZE_PRE_TIMEOUT_MS === "number",
+    "FINALIZE_PRE_TIMEOUT_MS should be a number",
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS >= 30_000,
+    `pre timeout should be >= 30s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS <= 120_000,
+    `pre timeout should be <= 120s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+}
+
 // ═══ Test: FINALIZE_POST_TIMEOUT_MS is defined and reasonable ═════════════════
 
 {
@@ -113,4 +134,108 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertEq(result.timedOut, false, "should not time out");
 }
 
+// ═══ Test: runFinalize wraps BOTH pre and post verification with withTimeout ═
+
+{
+  console.log("\n=== #3757: runFinalize wraps preVerification with timeout guard ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  // Find the runFinalize function body
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
+
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // postUnitPreVerification must be wrapped in withTimeout
+  const preTimeoutIdx = fnBody.indexOf("withTimeout(");
+  assertTrue(preTimeoutIdx > 0, "withTimeout should appear in runFinalize");
+
+  const preVerIdx = fnBody.indexOf("postUnitPreVerification");
+  assertTrue(preVerIdx > 0, "postUnitPreVerification should appear in runFinalize");
+
+  // The first withTimeout should wrap postUnitPreVerification (not postUnitPostVerification)
+  const firstWithTimeout = fnBody.slice(preTimeoutIdx, preTimeoutIdx + 200);
+  assertTrue(
+    firstWithTimeout.includes("postUnitPreVerification"),
+    "first withTimeout in runFinalize should wrap postUnitPreVerification",
+  );
+
+  // postUnitPostVerification must also be wrapped
+  const postVerIdx = fnBody.indexOf("postUnitPostVerification");
+  assertTrue(postVerIdx > 0, "postUnitPostVerification should appear in runFinalize");
+
+  // Count withTimeout occurrences — should be at least 2 (pre + post)
+  const timeoutCount = (fnBody.match(/withTimeout\(/g) || []).length;
+  assertTrue(
+    timeoutCount >= 2,
+    `runFinalize should have at least 2 withTimeout guards (found ${timeoutCount})`,
+  );
+}
+
+// ═══ Test: MAX_FINALIZE_TIMEOUTS is defined and reasonable ═══════════════════
+
+{
+  console.log("\n=== #3757: MAX_FINALIZE_TIMEOUTS is defined and reasonable ===");
+
+  assertTrue(
+    typeof MAX_FINALIZE_TIMEOUTS === "number",
+    "MAX_FINALIZE_TIMEOUTS should be a number",
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS >= 2,
+    `threshold should be >= 2 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS <= 10,
+    `threshold should be <= 10 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+}
+
+// ═══ Test: timeout handlers escalate after consecutive timeouts ══════════════
+
+{
+  console.log("\n=== #3757: timeout handlers escalate and detach currentUnit ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // Both timeout handlers should increment consecutiveFinalizeTimeouts
+  const incrementCount = (fnBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
+  assertTrue(
+    incrementCount >= 2,
+    `should increment consecutiveFinalizeTimeouts in both pre and post handlers (found ${incrementCount})`,
+  );
+
+  // Both timeout handlers should check MAX_FINALIZE_TIMEOUTS for escalation
+  const escalationCount = (fnBody.match(/MAX_FINALIZE_TIMEOUTS/g) || []).length;
+  assertTrue(
+    escalationCount >= 2,
+    `should check MAX_FINALIZE_TIMEOUTS in both handlers (found ${escalationCount})`,
+  );
+
+  // Both timeout handlers should null out s.currentUnit to prevent late mutations
+  const detachCount = (fnBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
+  assertTrue(
+    detachCount >= 2,
+    `should detach s.currentUnit in both timeout handlers (found ${detachCount})`,
+  );
+
+  // Successful finalize should reset the counter
+  assertTrue(
+    fnBody.includes("consecutiveFinalizeTimeouts = 0"),
+    "should reset consecutiveFinalizeTimeouts on successful finalize",
+  );
+}
+
 report();

package/src/resources/extensions/gsd/tests/find-missing-summaries-closed.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Regression test for #3669 — findMissingSummaries skips closed slices
+ *
+ * When a slice has status "skipped", "complete", or "done", it should be
+ * excluded from the missing-summary check because closed slices intentionally
+ * lack SUMMARY files (or their DB status is authoritative).
+ *
+ * This is a structural verification test — it reads the source to confirm the
+ * CLOSED_STATUSES guard exists at the filter site.
+ */
+
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const source = readFileSync(join(__dirname, '..', 'auto-dispatch.ts'), 'utf-8');
+
+describe('findMissingSummaries closed-status exclusion (#3669)', () => {
+  test('CLOSED_STATUSES set includes skipped, complete, and done', () => {
+    // The source must define a CLOSED_STATUSES set with all three statuses
+    assert.match(source, /CLOSED_STATUSES.*=.*new Set\(/,
+      'CLOSED_STATUSES set should be defined');
+    assert.match(source, /"skipped"/, 'CLOSED_STATUSES should include "skipped"');
+    assert.match(source, /"complete"/, 'CLOSED_STATUSES should include "complete"');
+    assert.match(source, /"done"/, 'CLOSED_STATUSES should include "done"');
+  });
+
+  test('filter uses CLOSED_STATUSES.has() to exclude closed slices', () => {
+    assert.match(source, /CLOSED_STATUSES\.has\(s\.status\)/,
+      'filter should call CLOSED_STATUSES.has(s.status)');
+  });
+
+  test('findMissingSummaries function exists', () => {
+    assert.match(source, /function findMissingSummaries\(/,
+      'findMissingSummaries function should be defined');
+  });
+
+  test('filter is negated (excludes closed, keeps open)', () => {
+    // The filter should use !CLOSED_STATUSES.has() to exclude closed slices
+    assert.match(source, /!CLOSED_STATUSES\.has\(s\.status\)/,
+      'filter should negate CLOSED_STATUSES.has() to exclude closed slices');
+  });
+});

package/src/resources/extensions/gsd/tests/format-shortcut.test.ts

@@ -0,0 +1,69 @@
+// GSD Extension — formatShortcut tests
+// Verifies OS-specific keyboard shortcut rendering.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatShortcut } from '../files.ts';
+
+// ─── formatShortcut renders per-platform shortcuts ──────────────────────
+
+test('formatShortcut: converts Ctrl+Alt combo on macOS', () => {
+  // formatShortcut uses process.platform at module load time.
+  // We can only test the current platform's behavior.
+  const result = formatShortcut('Ctrl+Alt+G');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥G', 'macOS should use ⌃⌥ symbols');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+G', 'non-macOS should pass through unchanged');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+N', () => {
+  const result = formatShortcut('Ctrl+Alt+N');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥N');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+N');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+B', () => {
+  const result = formatShortcut('Ctrl+Alt+B');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥B');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+B');
+  }
+});
+
+test('formatShortcut: converts standalone Ctrl modifier', () => {
+  const result = formatShortcut('Ctrl+C');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃C');
+  } else {
+    assert.strictEqual(result, 'Ctrl+C');
+  }
+});
+
+test('formatShortcut: converts Shift modifier', () => {
+  const result = formatShortcut('Shift+Tab');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⇧Tab');
+  } else {
+    assert.strictEqual(result, 'Shift+Tab');
+  }
+});
+
+test('formatShortcut: converts Cmd modifier', () => {
+  const result = formatShortcut('Cmd+S');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌘S');
+  } else {
+    assert.strictEqual(result, 'Cmd+S');
+  }
+});
+
+test('formatShortcut: passes through plain key names', () => {
+  assert.strictEqual(formatShortcut('Escape'), 'Escape');
+  assert.strictEqual(formatShortcut('Enter'), 'Enter');
+});

package/src/resources/extensions/gsd/tests/frontmatter-parse-noise.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Regression test for #3693 — suppress repeated frontmatter parse warnings
+ *
+ * parseFrontmatterBlock was logging a YAML parse warning on every call.
+ * The fix adds a _warnedFrontmatterParse flag so the warning only fires once.
+ */
+
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const prefsSrc = readFileSync(
+  join(__dirname, '..', 'preferences.ts'),
+  'utf-8',
+);
+
+describe('frontmatter parse noise suppression (#3693)', () => {
+  test('_warnedFrontmatterParse flag is defined', () => {
+    assert.match(prefsSrc, /_warnedFrontmatterParse/,
+      '_warnedFrontmatterParse flag should exist in preferences.ts');
+  });
+
+  test('parseFrontmatterBlock function exists', () => {
+    assert.match(prefsSrc, /function parseFrontmatterBlock\(/,
+      'parseFrontmatterBlock function should be defined');
+  });
+
+  test('flag is checked before warning', () => {
+    assert.match(prefsSrc, /if\s*\(\s*!_warnedFrontmatterParse\s*\)/,
+      'should check !_warnedFrontmatterParse before logging');
+  });
+
+  test('flag is set to true after first warning', () => {
+    assert.match(prefsSrc, /_warnedFrontmatterParse\s*=\s*true/,
+      'should set _warnedFrontmatterParse = true after warning');
+  });
+});

package/src/resources/extensions/gsd/tests/gitignore-bg-shell.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Regression test — .bg-shell/ added to BASELINE_PATTERNS in gitignore.ts
+ *
+ * The bg-shell background process directory was not included in the
+ * baseline gitignore patterns, causing it to appear as untracked in
+ * git status and potentially be committed.
+ *
+ * Structural verification test — reads source to confirm .bg-shell/
+ * is in BASELINE_PATTERNS.
+ */
+
+import { describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const source = readFileSync(join(__dirname, '..', 'gitignore.ts'), 'utf-8');
+
+describe('.bg-shell/ in BASELINE_PATTERNS', () => {
+  test('BASELINE_PATTERNS array is defined', () => {
+    assert.match(source, /const BASELINE_PATTERNS\s*=/,
+      'BASELINE_PATTERNS should be defined');
+  });
+
+  test('.bg-shell/ is included in BASELINE_PATTERNS', () => {
+    // Extract the BASELINE_PATTERNS array content
+    const patternsStart = source.indexOf('BASELINE_PATTERNS');
+    const arrayStart = source.indexOf('[', patternsStart);
+    const arrayEnd = source.indexOf('] as const', arrayStart);
+    const patternsContent = source.slice(arrayStart, arrayEnd);
+    assert.match(patternsContent, /\.bg-shell\//,
+      '.bg-shell/ should be in BASELINE_PATTERNS');
+  });
+});

package/src/resources/extensions/gsd/tests/guided-flow-state-rebuild.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Regression test for #3475: guided-flow must rebuild STATE.md from derived
+ * state before dispatching workflows.
+ *
+ * Verifies that buildStateMarkdown() produces content matching the derived
+ * state (not a stale on-disk cache), and that the rebuild helper is wired
+ * correctly from doctor.ts.
+ */
+
+import { describe, test, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { deriveState, invalidateStateCache } from "../state.ts";
+import { buildStateMarkdown, rebuildState } from "../doctor.ts";
+import { resolveGsdRootFile } from "../paths.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+} from "../gsd-db.ts";
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-guided-state-"));
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+function writeFile(base: string, relativePath: string, content: string): void {
+  const full = join(base, ".gsd", relativePath);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content);
+}
+
+describe("guided-flow STATE.md rebuild (#3475)", () => {
+  let base: string;
+
+  afterEach(() => {
+    closeDatabase();
+    if (base) rmSync(base, { recursive: true, force: true });
+  });
+
+  test("rebuildState writes STATE.md matching derived state, not stale cache", async () => {
+    base = createFixtureBase();
+    openDatabase(":memory:");
+
+    // Set up real active milestone M010
+    insertMilestone({ id: "M010", title: "Real Active", status: "active" });
+    insertSlice({ id: "S03", milestoneId: "M010", title: "Slice Three", status: "active", risk: "low", depends: [] });
+    insertTask({ id: "T05", sliceId: "S03", milestoneId: "M010", title: "Task Five", status: "pending" });
+    writeFile(base, "milestones/M010/M010-CONTEXT.md", "# M010: Real Active\n\nReal work here.");
+    writeFile(base, "milestones/M010/M010-ROADMAP.md", "# M010\n\n## Slices\n\n- [ ] **S03: Slice Three**");
+
+    // Write a STALE STATE.md pointing to wrong milestone
+    writeFile(base, "STATE.md", [
+      "# GSD State",
+      "",
+      "**Active Milestone:** M008: Old Queued",
+      "**Active Slice:** None",
+      "**Phase:** pre-planning",
+      "",
+      "## Next Action",
+      "Milestone M008 has a roadmap but no slices defined.",
+    ].join("\n"));
+
+    // Derive state — should return M010
+    invalidateStateCache();
+    const state = await deriveState(base);
+    assert.equal(state.activeMilestone?.id, "M010", "Derived state should be M010");
+
+    // Rebuild STATE.md
+    await rebuildState(base);
+
+    // Read the rebuilt STATE.md
+    const statePath = resolveGsdRootFile(base, "STATE");
+    const rebuilt = readFileSync(statePath, "utf-8");
+
+    // Should contain M010, NOT M008
+    assert.ok(rebuilt.includes("M010"), "Rebuilt STATE.md should reference M010");
+    assert.ok(!rebuilt.includes("M008"), "Rebuilt STATE.md should NOT reference stale M008");
+  });
+
+  test("buildStateMarkdown produces correct active milestone from GSDState", async () => {
+    base = createFixtureBase();
+    openDatabase(":memory:");
+
+    insertMilestone({ id: "M070", title: "Current Work", status: "active" });
+    insertSlice({ id: "S01", milestoneId: "M070", title: "First Slice", status: "active", risk: "low", depends: [] });
+    writeFile(base, "milestones/M070/M070-CONTEXT.md", "# M070: Current Work");
+    writeFile(base, "milestones/M070/M070-ROADMAP.md", "# M070\n\n## Slices\n\n- [ ] **S01: First Slice**");
+
+    invalidateStateCache();
+    const state = await deriveState(base);
+    const md = buildStateMarkdown(state);
+
+    assert.ok(md.includes("M070"), "State markdown should include active milestone M070");
+    assert.ok(md.includes("Current Work") || md.includes("M070"), "State markdown should include milestone title or ID");
+  });
+});