gsd-pi 2.78.1-dev.b6a389b66 → 2.78.1-dev.d8826a445

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/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-session-scope.test.ts

@@ -0,0 +1,331 @@
+// GSD-2 + Tests for MilestoneScope threading through AutoSession state (C2)
+//
+// Strategy: construct AutoSession directly + call createWorkspace/scopeMilestone
+// to mirror the rebuildScope() helper in auto.ts — avoids importing the full
+// auto.ts module (too many .js resolved imports).
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, realpathSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { AutoSession } from "../auto/session.ts";
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import type { MilestoneScope } from "../workspace.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-scope-test-")));
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+function makeWorktreeDir(projectDir: string, milestoneId: string): string {
+  const wt = join(projectDir, ".gsd", "worktrees", milestoneId);
+  mkdirSync(wt, { recursive: true });
+  return wt;
+}
+
+/**
+ * Mirror the rebuildScope() helper from auto.ts — computes s.scope from the
+ * same inputs so tests can verify the behaviour without importing auto.ts.
+ */
+function applyRebuildScope(
+  s: AutoSession,
+  rawPath: string,
+  milestoneId: string | null,
+): void {
+  if (!milestoneId) {
+    s.scope = null;
+    return;
+  }
+  try {
+    const workspace = createWorkspace(rawPath);
+    s.scope = scopeMilestone(workspace, milestoneId);
+  } catch {
+    s.scope = null;
+  }
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("AutoSession.scope — project mode (basePath equals originalBasePath)", () => {
+  let s: AutoSession;
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    s = new AutoSession();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("scope is null when milestoneId is null", () => {
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = null;
+
+    applyRebuildScope(s, projectDir, null);
+
+    assert.equal(s.scope, null);
+  });
+
+  test("scope mode is 'project' when basePath equals originalBasePath", () => {
+    const mid = "M001";
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, projectDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.mode, "project");
+    assert.equal(s.scope.milestoneId, mid);
+  });
+
+  test("scope projectRoot matches realpath of projectDir", () => {
+    const mid = "M001";
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, projectDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.projectRoot, realpathSync(projectDir));
+  });
+
+  test("scope worktreeRoot is null in project mode", () => {
+    const mid = "M001";
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, projectDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.worktreeRoot, null);
+  });
+
+  test("scope path methods resolve under the .gsd directory", () => {
+    const mid = "M002";
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, projectDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    const gsd = join(projectDir, ".gsd");
+    assert.equal(s.scope.contextFile(), join(gsd, "milestones", mid, `${mid}-CONTEXT.md`));
+    assert.equal(s.scope.roadmapFile(), join(gsd, "milestones", mid, `${mid}-ROADMAP.md`));
+    assert.equal(s.scope.stateFile(), join(gsd, "STATE.md"));
+  });
+});
+
+describe("AutoSession.scope — worktree mode (basePath differs from originalBasePath)", () => {
+  let s: AutoSession;
+  let projectDir: string;
+  let worktreeDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    worktreeDir = makeWorktreeDir(projectDir, "M001");
+    s = new AutoSession();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("scope mode is 'worktree' when basePath is the worktree path", () => {
+    const mid = "M001";
+    s.basePath = worktreeDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, worktreeDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.mode, "worktree");
+  });
+
+  test("scope worktreeRoot matches realpath of worktreeDir", () => {
+    const mid = "M001";
+    s.basePath = worktreeDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, worktreeDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.worktreeRoot, realpathSync(worktreeDir));
+  });
+
+  test("scope projectRoot resolves to project root (not worktree)", () => {
+    const mid = "M001";
+    s.basePath = worktreeDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, worktreeDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.workspace.projectRoot, realpathSync(projectDir));
+  });
+
+  test("scope milestoneId matches the milestone being tracked", () => {
+    const mid = "M001";
+    s.basePath = worktreeDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, worktreeDir, mid);
+
+    assert.ok(s.scope, "scope should be set");
+    assert.equal(s.scope.milestoneId, mid);
+  });
+});
+
+describe("AutoSession.scope — milestoneId change rebuilds scope", () => {
+  let s: AutoSession;
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    s = new AutoSession();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("scope reflects the new milestoneId after rebuild", () => {
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = "M001";
+    applyRebuildScope(s, projectDir, "M001");
+
+    assert.ok(s.scope, "initial scope should be set");
+    assert.equal(s.scope.milestoneId, "M001");
+
+    // Simulate milestone transition mid-session
+    s.currentMilestoneId = "M002";
+    applyRebuildScope(s, projectDir, "M002");
+
+    assert.ok(s.scope, "scope should be set after transition");
+    assert.equal(s.scope.milestoneId, "M002");
+  });
+
+  test("scope contextFile changes when milestoneId changes", () => {
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+
+    s.currentMilestoneId = "M001";
+    applyRebuildScope(s, projectDir, "M001");
+    const ctxM001 = s.scope?.contextFile();
+
+    s.currentMilestoneId = "M002";
+    applyRebuildScope(s, projectDir, "M002");
+    const ctxM002 = s.scope?.contextFile();
+
+    assert.ok(ctxM001, "M001 contextFile should be set");
+    assert.ok(ctxM002, "M002 contextFile should be set");
+    assert.notEqual(ctxM001, ctxM002, "contextFile must differ between milestone IDs");
+    assert.ok(ctxM001.includes("M001"), "M001 path should contain M001");
+    assert.ok(ctxM002.includes("M002"), "M002 path should contain M002");
+  });
+});
+
+describe("AutoSession.scope — resume from persisted state", () => {
+  let s: AutoSession;
+  let projectDir: string;
+  let worktreeDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    worktreeDir = makeWorktreeDir(projectDir, "M003");
+    s = new AutoSession();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("resume without worktree: scope mode is project, projectRoot is base", () => {
+    // Mirror the paused-session resume path:
+    //   s.currentMilestoneId = meta.milestoneId
+    //   s.originalBasePath   = meta.originalBasePath || base
+    //   rawPath              = originalBasePath (no worktreePath present)
+    const mid = "M003";
+    s.currentMilestoneId = mid;
+    s.originalBasePath = projectDir;
+    s.basePath = projectDir;
+
+    applyRebuildScope(s, s.originalBasePath, s.currentMilestoneId);
+
+    assert.ok(s.scope, "scope should be reconstructed");
+    assert.equal(s.scope.milestoneId, mid);
+    assert.equal(s.scope.workspace.mode, "project");
+    assert.equal(s.scope.workspace.projectRoot, realpathSync(projectDir));
+    assert.equal(s.scope.workspace.worktreeRoot, null);
+  });
+
+  test("resume with valid worktree path: scope mode is worktree", () => {
+    // Mirror the paused-session resume path where worktreePath exists on disk:
+    //   rawPath = worktreePath (existsSync true)
+    const mid = "M003";
+    s.currentMilestoneId = mid;
+    s.originalBasePath = projectDir;
+    s.basePath = worktreeDir;
+
+    assert.ok(existsSync(worktreeDir), "worktreeDir must exist for this test");
+
+    applyRebuildScope(s, worktreeDir, s.currentMilestoneId);
+
+    assert.ok(s.scope, "scope should be reconstructed");
+    assert.equal(s.scope.milestoneId, mid);
+    assert.equal(s.scope.workspace.mode, "worktree");
+    assert.equal(s.scope.workspace.projectRoot, realpathSync(projectDir));
+    assert.equal(s.scope.workspace.worktreeRoot, realpathSync(worktreeDir));
+  });
+
+  test("scope is consistent with direct createWorkspace + scopeMilestone for same inputs", () => {
+    const mid = "M003";
+    s.currentMilestoneId = mid;
+    s.originalBasePath = projectDir;
+    s.basePath = projectDir;
+
+    applyRebuildScope(s, projectDir, mid);
+    assert.ok(s.scope, "scope should be set");
+
+    // Build expected scope via lower-level API to verify equivalence
+    const ws = createWorkspace(projectDir);
+    const expected = scopeMilestone(ws, mid);
+
+    assert.equal(s.scope.milestoneId, expected.milestoneId);
+    assert.equal(s.scope.contextFile(), expected.contextFile());
+    assert.equal(s.scope.roadmapFile(), expected.roadmapFile());
+    assert.equal(s.scope.stateFile(), expected.stateFile());
+    assert.equal(s.scope.dbPath(), expected.dbPath());
+    assert.equal(s.scope.milestoneDir(), expected.milestoneDir());
+    assert.equal(s.scope.metaJson(), expected.metaJson());
+  });
+
+  test("reset() clears scope", () => {
+    const mid = "M003";
+    s.basePath = projectDir;
+    s.originalBasePath = projectDir;
+    s.currentMilestoneId = mid;
+
+    applyRebuildScope(s, projectDir, mid);
+    assert.ok(s.scope, "scope should be set before reset");
+
+    s.reset();
+    assert.equal(s.scope, null, "scope must be null after reset()");
+  });
+});

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

@@ -0,0 +1,176 @@
+// GSD-2 + Unit tests for the workspace registry that replaced the originalBase singleton
+
+import { describe, test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import {
+  getAutoWorktreeOriginalBase,
+  getActiveAutoWorktreeContext,
+  _resetAutoWorktreeOriginalBaseForTests,
+  createAutoWorktree,
+  enterAutoWorktree,
+  teardownAutoWorktree,
+} from "../auto-worktree.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+// Safe: all inputs below are hardcoded test strings, not user input.
+function git(subArgs: string[], cwd: string): void {
+  execFileSync("git", subArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function createTempRepo(t: { after: (fn: () => void) => void }): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "awreg-test-")));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  git(["init"], dir);
+  git(["config", "user.email", "test@test.com"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  git(["add", "."], dir);
+  git(["commit", "-m", "init"], dir);
+  git(["branch", "-M", "main"], dir);
+  return dir;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("auto-worktree workspace registry", () => {
+  const savedCwd = process.cwd();
+
+  beforeEach(() => {
+    _resetAutoWorktreeOriginalBaseForTests();
+    process.chdir(savedCwd);
+  });
+
+  test("getAutoWorktreeOriginalBase() is null at baseline", () => {
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null);
+  });
+
+  test("getActiveAutoWorktreeContext() is null at baseline", () => {
+    assert.strictEqual(getActiveAutoWorktreeContext(), null);
+  });
+
+  test("_resetAutoWorktreeOriginalBaseForTests() clears the registry — idempotent", () => {
+    _resetAutoWorktreeOriginalBaseForTests();
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null);
+    _resetAutoWorktreeOriginalBaseForTests();
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null);
+  });
+
+  test("behavioral equivalence: createAutoWorktree populates registry; teardown clears it", (t) => {
+    const tempDir = createTempRepo(t);
+    const msDir = join(tempDir, ".gsd", "milestones", "M001");
+    mkdirSync(msDir, { recursive: true });
+    writeFileSync(join(msDir, "CONTEXT.md"), "# M001 Context\n");
+    git(["add", "."], tempDir);
+    git(["commit", "-m", "add milestone"], tempDir);
+
+    // Before entering: registry must be empty
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null,
+      "originalBase is null before entering worktree");
+
+    createAutoWorktree(tempDir, "M001");
+
+    // After enter: getAutoWorktreeOriginalBase must equal tempDir
+    assert.strictEqual(
+      getAutoWorktreeOriginalBase(),
+      tempDir,
+      "getAutoWorktreeOriginalBase() returns projectRoot after createAutoWorktree",
+    );
+
+    // getActiveAutoWorktreeContext must return the correct shape
+    const ctx = getActiveAutoWorktreeContext();
+    assert.ok(ctx !== null, "context is non-null inside worktree");
+    assert.strictEqual(ctx.originalBase, tempDir, "context.originalBase matches tempDir");
+    assert.strictEqual(ctx.worktreeName, "M001", "context.worktreeName is M001");
+    assert.strictEqual(ctx.branch, "milestone/M001", "context.branch is milestone/M001");
+
+    // Teardown: registry must be cleared
+    teardownAutoWorktree(tempDir, "M001");
+
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null,
+      "getAutoWorktreeOriginalBase() is null after teardown");
+    assert.strictEqual(getActiveAutoWorktreeContext(), null,
+      "getActiveAutoWorktreeContext() is null after teardown");
+
+    try { process.chdir(savedCwd); } catch { /* ignore */ }
+  });
+
+  test("behavioral equivalence: enterAutoWorktree also populates registry", (t) => {
+    const tempDir = createTempRepo(t);
+    const msDir = join(tempDir, ".gsd", "milestones", "M002");
+    mkdirSync(msDir, { recursive: true });
+    writeFileSync(join(msDir, "CONTEXT.md"), "# M002 Context\n");
+    git(["add", "."], tempDir);
+    git(["commit", "-m", "add milestone"], tempDir);
+
+    createAutoWorktree(tempDir, "M002");
+
+    // Simulate leaving the worktree (crash/pause)
+    _resetAutoWorktreeOriginalBaseForTests();
+    process.chdir(tempDir);
+
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null,
+      "registry is empty after manual reset");
+
+    // Re-enter via enterAutoWorktree
+    enterAutoWorktree(tempDir, "M002");
+
+    assert.strictEqual(
+      getAutoWorktreeOriginalBase(),
+      tempDir,
+      "getAutoWorktreeOriginalBase() returns projectRoot after enterAutoWorktree",
+    );
+    const ctx = getActiveAutoWorktreeContext();
+    assert.ok(ctx !== null, "context is non-null after re-entry");
+    assert.strictEqual(ctx.originalBase, tempDir);
+    assert.strictEqual(ctx.worktreeName, "M002");
+    assert.strictEqual(ctx.branch, "milestone/M002");
+
+    teardownAutoWorktree(tempDir, "M002");
+    try { process.chdir(savedCwd); } catch { /* ignore */ }
+  });
+
+  test("single-occupancy: entering a new workspace replaces the previous one", (t) => {
+    const dir1 = createTempRepo(t);
+    const dir2 = createTempRepo(t);
+
+    // Set up milestone in dir1
+    const ms1Dir = join(dir1, ".gsd", "milestones", "M010");
+    mkdirSync(ms1Dir, { recursive: true });
+    writeFileSync(join(ms1Dir, "CONTEXT.md"), "# M010\n");
+    git(["add", "."], dir1);
+    git(["commit", "-m", "add milestone"], dir1);
+
+    // Set up milestone in dir2
+    const ms2Dir = join(dir2, ".gsd", "milestones", "M020");
+    mkdirSync(ms2Dir, { recursive: true });
+    writeFileSync(join(ms2Dir, "CONTEXT.md"), "# M020\n");
+    git(["add", "."], dir2);
+    git(["commit", "-m", "add milestone"], dir2);
+
+    // Enter dir1/M010
+    createAutoWorktree(dir1, "M010");
+    assert.strictEqual(getAutoWorktreeOriginalBase(), dir1,
+      "registry holds dir1 after entering M010");
+
+    // Tear down dir1 cleanly
+    teardownAutoWorktree(dir1, "M010");
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null, "registry cleared after M010 teardown");
+
+    // Enter dir2/M020 — registry should now hold dir2 only
+    createAutoWorktree(dir2, "M020");
+    assert.strictEqual(getAutoWorktreeOriginalBase(), dir2,
+      "registry holds dir2 after entering M020 (single-occupancy preserved)");
+    assert.notStrictEqual(getAutoWorktreeOriginalBase(), dir1,
+      "dir1 is no longer in the registry");
+
+    teardownAutoWorktree(dir2, "M020");
+    try { process.chdir(savedCwd); } catch { /* ignore */ }
+  });
+});