gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/src/resources/extensions/gsd/prompts/guided-discuss-requirements.md

@@ -21,9 +21,13 @@ Before your first action, print this banner verbatim in chat:
 ## Pre-flight
 
 1. Read `.gsd/PROJECT.md` end-to-end. If it does not exist, STOP and emit: `"PROJECT.md missing — run discuss-project first."`
-2. Extract: Core Value, Anti-goals, Constraints, Milestone Sequence.
+2. Extract: Core Value, Anti-goals, Constraints, Milestone Sequence, and the project shape verdict — read the `## Project Shape` section and look for `**Complexity:**` (verdict is either `simple` or `complex`; default to `complex` if the section is missing or unclear).
 3. Check for existing `.gsd/REQUIREMENTS.md` — if present, this is a refinement pass, not a fresh write. Read existing requirements and treat them as the working set.
 
+**Shape-dependent cadence:**
+- **`simple`** — favor a single fast pass: extract requirements directly from PROJECT.md, ask 1–2 plain-text clarifying questions only if a class or status assignment is genuinely ambiguous, then write REQUIREMENTS.md.
+- **`complex`** — full multi-round questioning with structured 3–4-option questions where alternatives matter.
+
 ---
 
 ## Interview Protocol
@@ -51,7 +55,7 @@ Ask **1–3 questions per round**. Each round targets one dimension:
 
 **Never fabricate or simulate user input.** Wait for actual responses.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. Every question object MUST include a stable lowercase `id`. For class assignments, present the allowed classes as multi-select options. For status, present the four statuses as exclusive options. Ask 1–3 questions per call. Wait for each tool result before asking the next round.
+**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions`. Every question object MUST include a stable lowercase `id`. For class assignments, present the allowed classes as multi-select options. For status, present the four statuses as exclusive options. In **`complex`** mode, any free-form question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option grounded in the investigation above. The class-assignment and status questions are exempt — they have fixed enumerations. Ask 1–3 questions per call. Wait for each tool result before asking the next round.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text. Keep each round to 1–3 questions.
 

package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -8,6 +8,13 @@ Your goal is **not** to center the discussion on tech stack trivia, naming conve
 
 ## Interview Protocol
 
+### Read project shape
+
+Before your first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. The verdict is either **`simple`** or **`complex`** (default to `complex` if the section is missing or unclear).
+
+- **`simple`** — favor 1–2 plain-text rounds, write the slice context fast. Skip parallel-research investigation.
+- **`complex`** — full investigation with structured 3–4-option questions.
+
 ### Before your first question round
 
 Do a lightweight targeted investigation so your questions are grounded in reality:
@@ -24,7 +31,7 @@ Do **not** go deep — just enough that your questions reflect what's actually t
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
+**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus a final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not generic placeholders. In **`simple`** mode, 2 options is fine. Binary wrap-up gates are exempt from the 3-or-4 rule. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
 **If `{{structuredQuestionsAvailable}}` is `false`:** Ask **1–3 questions per round** in plain text. Number them and wait for the user's response before asking the next round.
 Keep each question focused on one of:
 - **UX and user-facing behaviour** — what does the user see, click, trigger, or experience?

package/src/resources/extensions/gsd/state.ts

@@ -270,6 +270,21 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
   return null;
 }
 
+/**
+ * Options for deriveState read-path routing.
+ *
+ * `projectRootForReads`: canonical project root (e.g. from
+ * `s.canonicalProjectRoot`) used for both the cache key and the artifact-read
+ * root in `_deriveStateImpl`. When omitted, behavior is identical to the
+ * single-arg signature (back-compat for all existing callers).
+ *
+ * Typed as an object literal (not `string | DeriveStateOptions`) so accidental
+ * `deriveState(path, "string")` is rejected at compile time.
+ */
+export interface DeriveStateOptions {
+  projectRootForReads?: string;
+}
+
 /**
  * Reconstruct GSD state from the authoritative DB.
  * STATE.md is a rendered cache of this output.
@@ -278,11 +293,22 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
  * Legacy filesystem parsing is available only through an explicit opt-in for
  * tests/recovery flows; runtime must not silently infer state from markdown.
  */
-export async function deriveState(basePath: string): Promise<GSDState> {
-  // Return cached result if within the TTL window for the same basePath
+export async function deriveState(
+  basePath: string,
+  opts?: DeriveStateOptions,
+): Promise<GSDState> {
+  // Use the canonical project root (when provided) as the cache key so that
+  // two calls with different basePath strings (e.g. worktree path vs project
+  // root) but the same canonical .gsd/ share a single cache entry. The same
+  // key is used for both the lookup AND the write below — keying lookup on
+  // canonical-root while writing on basePath would silently return stale
+  // results across path-form alternation.
+  const cacheKey = opts?.projectRootForReads ?? basePath;
+
+  // Return cached result if within the TTL window for the same cacheKey
   if (
     _stateCache &&
-    _stateCache.basePath === basePath &&
+    _stateCache.basePath === cacheKey &&
     Date.now() - _stateCache.timestamp < CACHE_TTL_MS
   ) {
     return _stateCache.result;
@@ -303,7 +329,7 @@ export async function deriveState(basePath: string): Promise<GSDState> {
     if (wasDbOpenAttempted()) {
       logWarning("state", "DB unavailable — using explicit legacy filesystem state derivation");
     }
-    result = await _deriveStateImpl(basePath);
+    result = await _deriveStateImpl(basePath, opts);
     _telemetry.markdownDeriveCount++;
   } else {
     if (wasDbOpenAttempted()) {
@@ -325,7 +351,7 @@ export async function deriveState(basePath: string): Promise<GSDState> {
 
   stopTimer({ phase: result.phase, milestone: result.activeMilestone?.id });
   debugCount("deriveStateCalls");
-  _stateCache = { basePath, result, timestamp: Date.now() };
+  _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
   return result;
 }
 
@@ -838,7 +864,19 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
 // LEGACY: Filesystem-based state derivation for unmigrated projects.
 // DB-backed projects use deriveStateFromDb() above. Target: extract to
 // state-legacy.ts when all projects are DB-backed.
-export async function _deriveStateImpl(basePath: string): Promise<GSDState> {
+export async function _deriveStateImpl(
+  basePath: string,
+  opts?: DeriveStateOptions,
+): Promise<GSDState> {
+  // When the caller supplies a canonical project root for reads (e.g.
+  // s.canonicalProjectRoot from auto-mode), route all artifact reads through
+  // it. This prevents the worktree-local empty `.gsd/` from being consulted
+  // when the canonical state lives at the project root (or via a `.gsd`
+  // symlink into the external state dir).
+  if (opts?.projectRootForReads) {
+    basePath = opts.projectRootForReads;
+  }
+
   const diskIds = findMilestoneIds(basePath);
   const customOrder = loadQueueOrder(basePath);
   const milestoneIds = sortByQueueOrder(diskIds, customOrder);

package/src/resources/extensions/gsd/templates/project.md

@@ -11,6 +11,16 @@
 
 {{theOneThingThatMustWorkEvenIfEverythingElseIsCut}}
 
+## Project Shape
+
+<!-- Drives questioning depth in downstream stages. `simple` → short plain-text
+     rounds, fast PROJECT/CONTEXT/REQUIREMENTS writes. `complex` → researched
+     3–4-option questions with an "Other — let me discuss" hatch.
+     Default to `complex` when uncertain. -->
+
+- **Complexity:** {{simple | complex}}
+- **Why:** {{one-line rationale citing the signals that decided it}}
+
 ## Current State
 
 {{whatHasBeenBuiltSoFar — what works, what exists, what's deployed}}

package/src/resources/extensions/gsd/tests/auto-discuss-milestone-deadlock-4973.test.ts

@@ -35,7 +35,7 @@ import { _setAutoActiveForTest } from '../auto.ts';
 // Reset all relevant state before and after each test.
 function resetState(): void {
   _setAutoActiveForTest(false);
-  clearDiscussionFlowState();
+  clearDiscussionFlowState(process.cwd());
 }
 
 describe('auto-discuss-milestone-deadlock-4973', () => {
@@ -51,7 +51,7 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
     _setAutoActiveForTest(true);
 
     // Before mark: blocked
-    const snapshotBefore = loadWriteGateSnapshot();
+    const snapshotBefore = loadWriteGateSnapshot(process.cwd());
     const beforeResult = shouldBlockContextArtifactSaveInSnapshot(
       snapshotBefore,
       'CONTEXT',
@@ -61,10 +61,10 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
     assert.strictEqual(beforeResult.block, true, 'should block before markDepthVerified');
 
     // Simulate what the dispatch rule now does in auto-mode
-    markDepthVerified('M001');
+    markDepthVerified('M001', process.cwd());
 
     // After mark: unblocked
-    const snapshotAfter = loadWriteGateSnapshot();
+    const snapshotAfter = loadWriteGateSnapshot(process.cwd());
     const afterResult = shouldBlockContextArtifactSaveInSnapshot(
       snapshotAfter,
       'CONTEXT',
@@ -87,7 +87,7 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
     assert.strictEqual(beforeResult.block, true, 'write should be blocked before markDepthVerified');
 
     // Simulate dispatch rule auto-mark
-    markDepthVerified('M001');
+    markDepthVerified('M001', process.cwd());
 
     // After mark: unblocked
     const afterResult = shouldBlockContextWrite('write', contextPath, 'M001');
@@ -109,8 +109,8 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
   // the dispatch-site call site is safe regardless of prior session state.
   test('Test 3: session_switch ordering — clearDiscussionFlowState clears mark; dispatch-site call re-establishes it', () => {
     // Simulate a mark from a prior session
-    markDepthVerified('M001');
-    let snapshot = loadWriteGateSnapshot();
+    markDepthVerified('M001', process.cwd());
+    let snapshot = loadWriteGateSnapshot(process.cwd());
     assert.strictEqual(
       isMilestoneDepthVerifiedInSnapshot(snapshot, 'M001'),
       true,
@@ -119,8 +119,8 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
 
     // session_switch fires clearDiscussionFlowState() — this is exactly what
     // register-hooks.ts:106 does
-    clearDiscussionFlowState();
-    snapshot = loadWriteGateSnapshot();
+    clearDiscussionFlowState(process.cwd());
+    snapshot = loadWriteGateSnapshot(process.cwd());
     assert.strictEqual(
       isMilestoneDepthVerifiedInSnapshot(snapshot, 'M001'),
       false,
@@ -130,9 +130,9 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
     // Now the dispatch rule fires (after session_switch cleared state)
     // and re-establishes the mark for the new session
     _setAutoActiveForTest(true);
-    markDepthVerified('M001'); // this is what the dispatch rule does
+    markDepthVerified('M001', process.cwd()); // this is what the dispatch rule does
 
-    snapshot = loadWriteGateSnapshot();
+    snapshot = loadWriteGateSnapshot(process.cwd());
     assert.strictEqual(
       isMilestoneDepthVerifiedInSnapshot(snapshot, 'M001'),
       true,
@@ -158,7 +158,7 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
 
     // CONTEXT artifact save is still blocked
     const snapshotResult = shouldBlockContextArtifactSaveInSnapshot(
-      loadWriteGateSnapshot(),
+      loadWriteGateSnapshot(process.cwd()),
       'CONTEXT',
       'M002',
       null,
@@ -238,7 +238,7 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
       );
 
       // ── Deep auto-mode case: the user-facing approval gate must stay closed ──
-      clearDiscussionFlowState();
+      clearDiscussionFlowState(process.cwd());
       if (existsSync(snapshotFile)) unlinkSync(snapshotFile);
       _setAutoActiveForTest(true);
       const deepCtx = {
@@ -264,7 +264,7 @@ describe('auto-discuss-milestone-deadlock-4973', () => {
       // ── Interactive case: the rule must NOT call markDepthVerified ──
       // clearDiscussionFlowState() only deletes the snapshot at process.cwd(),
       // so we must explicitly remove the snapshot under our tempBase too.
-      clearDiscussionFlowState();
+      clearDiscussionFlowState(process.cwd());
       if (existsSync(snapshotFile)) unlinkSync(snapshotFile);
       _setAutoActiveForTest(false);
       snap = loadWriteGateSnapshot(tempBase);

package/src/resources/extensions/gsd/tests/auto-loop-no-copy-artifacts.test.ts

@@ -0,0 +1,72 @@
+// gsd-2 + Phase C deletion regression: createAutoWorktree no longer copies .gsd/
+//
+// Verifies that createAutoWorktree on a project with a real (non-symlinked)
+// .gsd/ does NOT populate .gsd/milestones/ inside the worktree. Pre-Phase-C,
+// copyPlanningArtifacts would mirror the project-root .gsd/ into the
+// worktree-local .gsd/. Phase C deleted that helper because writers in
+// auto-mode now route through s.canonicalProjectRoot, so the worktree never
+// needs a parallel .gsd/ projection.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, realpathSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import { createAutoWorktree, teardownAutoWorktree } from "../auto-worktree.ts";
+
+function git(args: string[], cwd: string): void {
+  execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+test("createAutoWorktree does NOT copy project-root .gsd/milestones into the worktree", (t) => {
+  const base = realpathSync(mkdtempSync(join(tmpdir(), "gsd-no-copy-")));
+
+  // Initialize a real git repo with a real .gsd/ directory containing some
+  // planning artifacts that the deleted copyPlanningArtifacts would have
+  // mirrored.
+  git(["init", "-b", "main"], base);
+  git(["config", "user.name", "Pi Test"], base);
+  git(["config", "user.email", "pi@example.com"], base);
+  writeFileSync(join(base, "README.md"), "# Test\n", "utf-8");
+  git(["add", "README.md"], base);
+  git(["commit", "-m", "chore: init"], base);
+
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+    "# M001 Context\n",
+    "utf-8",
+  );
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001 Roadmap\n",
+    "utf-8",
+  );
+
+  const wtPath = createAutoWorktree(base, "M001");
+  t.after(() => {
+    try { teardownAutoWorktree(base, "M001"); } catch { /* noop */ }
+    try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  // Phase C invariant: the worktree's .gsd/milestones/M001 must NOT exist
+  // (no copyPlanningArtifacts), and the project-root version must still be
+  // intact (it was the source, not destination).
+  assert.equal(
+    existsSync(join(wtPath, ".gsd", "milestones", "M001", "M001-CONTEXT.md")),
+    false,
+    "worktree should NOT have a copy of M001-CONTEXT.md (copyPlanningArtifacts deleted)",
+  );
+  assert.equal(
+    existsSync(join(wtPath, ".gsd", "milestones", "M001", "M001-ROADMAP.md")),
+    false,
+    "worktree should NOT have a copy of M001-ROADMAP.md",
+  );
+  assert.equal(
+    existsSync(join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md")),
+    true,
+    "project-root .gsd/ retains the canonical CONTEXT.md",
+  );
+});

package/src/resources/extensions/gsd/tests/auto-loop-symlink-worktree.test.ts

@@ -0,0 +1,190 @@
+// gsd-2 + Symlinked .gsd worktree-loop reproduction (Phase A pt 2 follow-up to PR #5236)
+//
+// Regression coverage for the auto-mode loop bug observed on projects whose
+// .gsd/ is a symlink into ~/.gsd/projects/<hash>/ (the external-state layout).
+//
+// Two assertions:
+//   1. deriveState's cache key is the canonical project root when callers
+//      opt into projectRootForReads — so two derive calls that should refer
+//      to the same canonical state share a single cache entry, regardless of
+//      whether the caller passed the worktree path or the project-root path.
+//   2. _deriveStateImpl's projectRootForReads option routes legacy markdown
+//      reads through the canonical project root, finding files that live in
+//      the symlink target rather than the worktree-local empty .gsd/.
+//
+// Per project rule #11: regression test using node:test + node:assert/strict,
+// no source-grep assertions. The first test would fail on main without the
+// cache-key fix in state.ts (lookup vs write keys would diverge across
+// path-form alternation, producing cache misses). The second test would
+// fail on main because _deriveStateImpl doesn't accept the option at all.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  deriveState,
+  _deriveStateImpl,
+  invalidateStateCache,
+  type DeriveStateOptions,
+} from "../state.ts";
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+} from "../gsd-db.ts";
+
+// ─── Fixture helpers ──────────────────────────────────────────────────────
+
+interface SymlinkedFixture {
+  /** Project root containing .gsd as a symlink. */
+  projectRoot: string;
+  /** External state dir that .gsd points at (acts as the canonical .gsd/). */
+  externalState: string;
+  /** Worktree path under the external state's worktrees/ dir. */
+  worktreePath: string;
+}
+
+function makeSymlinkedFixture(prefix: string): SymlinkedFixture {
+  // Use realpathSync on tmpdir so that subsequent realpath comparisons are stable
+  // — macOS /var symlinks to /private/var, which would otherwise pollute the
+  // canonical-root assertions below.
+  const root = realpathSync(mkdtempSync(join(tmpdir(), `gsd-${prefix}-`)));
+  const projectRoot = join(root, "project");
+  const externalState = join(root, "external-state", "projects", "abc123");
+
+  mkdirSync(projectRoot, { recursive: true });
+  mkdirSync(externalState, { recursive: true });
+
+  // .gsd → externalState (the layout that triggered the original bug)
+  symlinkSync(externalState, join(projectRoot, ".gsd"), "junction");
+
+  // Worktree path lives under the external state's worktrees/ dir, mirroring
+  // the canonicalProjectRoot resolution that resolveGsdPathContract performs
+  // for the external-state layout.
+  const worktreePath = join(externalState, "worktrees", "M001");
+  mkdirSync(worktreePath, { recursive: true });
+
+  return { projectRoot, externalState, worktreePath };
+}
+
+function cleanupFixture(fx: SymlinkedFixture): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  // The mkdtemp root is two levels above projectRoot.
+  try {
+    const root = join(fx.projectRoot, "..");
+    rmSync(root, { recursive: true, force: true });
+  } catch { /* noop */ }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 1: cache-key invariance under projectRootForReads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("deriveState: cache key is canonical when projectRootForReads is supplied", async (t) => {
+  const fx = makeSymlinkedFixture("symlink-cache");
+  t.after(() => cleanupFixture(fx));
+
+  // Open the DB at the canonical .gsd location (externalState).
+  openDatabase(join(fx.externalState, "gsd.db"));
+  insertMilestone({ id: "M001", title: "Symlinked", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice" });
+  // No tasks → DB-derived state is "planning".
+
+  invalidateStateCache();
+
+  const optsCanonical: DeriveStateOptions = { projectRootForReads: fx.projectRoot };
+
+  // First call: seed the cache through the worktree-path form.
+  const stateA = await deriveState(fx.worktreePath, optsCanonical);
+  assert.equal(stateA.activeMilestone?.id, "M001");
+  assert.equal(stateA.activeSlice?.id, "S01");
+  assert.equal(stateA.phase, "planning");
+
+  // Second call: canonical project-root form must hit the same cache entry.
+  const stateB = await deriveState(fx.projectRoot);
+  assert.equal(stateB, stateA, "second call with same canonical key must return the cached object");
+
+  // Third call: worktree-path form with projectRootForReads must also hit the
+  // same cache entry, proving the cache key is symmetric across both call
+  // orders.
+  const stateC = await deriveState(fx.worktreePath, optsCanonical);
+  assert.equal(stateC, stateA, "third call with worktree path plus canonical reads must hit the same cache entry");
+
+  // Mutation invalidates: insert a task, clear cache, re-derive — must
+  // observe the new state via the canonical key path.
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Task", status: "active" });
+  invalidateStateCache();
+
+  const stateD = await deriveState(fx.worktreePath, optsCanonical);
+  assert.notEqual(stateD, stateA, "post-mutation derive must re-compute, not reuse the prior cached object");
+  assert.equal(stateD.activeTask?.id, "T01", "mutation must surface in the re-derived state");
+  assert.equal(stateD.phase, "executing");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 2: _deriveStateImpl reads from canonical root via projectRootForReads
+// ═══════════════════════════════════════════════════════════════════════════
+
+test("_deriveStateImpl: projectRootForReads routes legacy markdown reads to the canonical .gsd/", async (t) => {
+  const fx = makeSymlinkedFixture("symlink-md");
+  t.after(() => cleanupFixture(fx));
+  // No DB opened — exercise the markdown fallback.
+
+  // Seed the external state dir (the symlink target) with a roadmap so the
+  // legacy filesystem state derivation has a milestone to find.
+  const m1Dir = join(fx.externalState, "milestones", "M001");
+  mkdirSync(m1Dir, { recursive: true });
+  writeFileSync(
+    join(m1Dir, "M001-CONTEXT.md"),
+    "# M001: Symlinked legacy md test\n\nTest project.\n",
+    "utf-8",
+  );
+  writeFileSync(
+    join(m1Dir, "M001-ROADMAP.md"),
+    [
+      "# M001 Roadmap",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S01: First slice** — depends:",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  invalidateStateCache();
+
+  // Calling _deriveStateImpl with the worktree path AND projectRootForReads
+  // pointing at the project root must consult the canonical .gsd/ (via the
+  // symlink target externalState), find M001/S01, and report planning phase
+  // because no slice plan file exists yet.
+  const state = await _deriveStateImpl(fx.worktreePath, { projectRootForReads: fx.projectRoot });
+  assert.equal(state.activeMilestone?.id, "M001", "must find M001 via canonical .gsd/ reads");
+  assert.equal(state.activeSlice?.id, "S01", "must find S01 from the roadmap");
+  assert.equal(state.phase, "planning", "no slice PLAN.md yet → planning phase");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test 3: type-safety guard for the deriveState opts overload (compile-time)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// The DeriveStateOptions parameter is typed as an object literal so accidental
+// `deriveState(path, "string")` is a TypeScript compile error. The
+// expect-error directive verifies that this guard is in place — if the
+// overload were widened to `string | DeriveStateOptions`, the directive would
+// trigger TS2578 ("Unused '@ts-expect-error' directive") at build time.
+
+test("deriveState: opts param rejects non-object values at compile time", () => {
+  // The actual assertion is the TypeScript compile-time check below; the
+  // runtime body just confirms the test ran.
+  if (false) {
+    // @ts-expect-error — projectRootForReads must be a string
+    void deriveState("/nonexistent", { projectRootForReads: 123 });
+  }
+  assert.ok(true);
+});