gsd-pi 2.78.0 → 2.78.1-dev.2d3fd6e71

package/src/resources/extensions/gsd/tests/workflow-logger-wiring.test.ts

@@ -205,17 +205,22 @@ test("readTransaction logs ROLLBACK failures as split-brain signal", () => {
   );
 });
 
-// ─── Runtime: state.ts and workflow-projections.ts log silent bailouts ─────
+// ─── Runtime: startup/projection diagnostics stay explicit ─────────────────
 
-test("state.ts logs roadmap read failures instead of silently continuing", () => {
-  const stateSrc = readFileSync(
-    join(import.meta.dirname, "..", "state.ts"),
+test("auto-start initializes the DB without implicit markdown migration", () => {
+  const autoStartSrc = readFileSync(
+    join(import.meta.dirname, "..", "auto-start.ts"),
     "utf-8",
   );
+  assert.doesNotMatch(
+    autoStartSrc,
+    /migrateFromMarkdown|md-importer/,
+    "auto-start must not import markdown into the runtime DB implicitly",
+  );
   assert.match(
-    stateSrc,
-    /logWarning\("state",\s*"reconcileDiskToDb: roadmap read failed/,
-    "state.ts reconcileDiskToDb should log roadmap read failures",
+    autoStartSrc,
+    /failed to initialize project database/,
+    "DB initialization failures should still be logged",
   );
 });
 

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -15,7 +15,7 @@ test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport"
   assert.equal(result, true);
 });
 
-test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is ready", () => {
+test("shouldAutoPrepareWorkflowMcp stays disabled for non-Claude active provider even when claude-code is ready", () => {
   const result = shouldAutoPrepareWorkflowMcp({
     model: { provider: "openai", baseUrl: "https://api.openai.com" },
     modelRegistry: {
@@ -24,10 +24,10 @@ test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is rea
     },
   });
 
-  assert.equal(result, true);
+  assert.equal(result, false);
 });
 
-test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is registered", () => {
+test("shouldAutoPrepareWorkflowMcp stays disabled for non-Claude active provider even when claude-code is registered", () => {
   const result = shouldAutoPrepareWorkflowMcp({
     model: { provider: "openai", baseUrl: "https://api.openai.com" },
     modelRegistry: {
@@ -36,7 +36,7 @@ test("shouldAutoPrepareWorkflowMcp enables prep when claude-code provider is reg
     },
   });
 
-  assert.equal(result, true);
+  assert.equal(result, false);
 });
 
 test("shouldAutoPrepareWorkflowMcp stays disabled when neither transport nor provider readiness match", () => {

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -30,6 +30,17 @@ function readSrc(file: string): string {
   return readFileSync(join(gsdDir, file), "utf-8");
 }
 
+function listTsFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const stat = statSync(full);
+    if (stat.isDirectory()) out.push(...listTsFiles(full));
+    else if (entry.endsWith(".ts")) out.push(full);
+  }
+  return out;
+}
+
 function extractElicitPayload(request: unknown): ElicitPayload {
   const payload = (request as { params?: unknown }).params ?? request;
   return payload as ElicitPayload;
@@ -39,8 +50,35 @@ test("guided execute-task requires canonical task completion tool", () => {
   assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), ["gsd_task_complete"]);
 });
 
-test("auto execute-task requires legacy completion alias until prompt contract is aligned", () => {
-  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_complete_task"]);
+test("auto execute-task requires canonical task completion tool", () => {
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_task_complete"]);
+});
+
+test("deep project setup units declare required workflow MCP tools", () => {
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("discuss-project"), [
+    "ask_user_questions",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("discuss-requirements"), [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("research-decision"), [
+    "ask_user_questions",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("discuss-project"), [
+    "ask_user_questions",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("discuss-requirements"), [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("research-decision"), [
+    "ask_user_questions",
+  ]);
 });
 
 test("detectWorkflowMcpLaunchConfig prefers explicit env override", () => {
@@ -62,12 +100,29 @@ test("detectWorkflowMcpLaunchConfig prefers explicit env override", () => {
   });
   assert.equal(launch?.env?.FOO, "bar");
   assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd");
+  assert.equal(launch?.env?.GSD_BIN_PATH, "/tmp/gsd");
   assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
 });
 
+test("detectWorkflowMcpLaunchConfig normalizes explicit workflow MCP env CLI aliases", () => {
+  const binOnly = detectWorkflowMcpLaunchConfig("/tmp/project", {
+    GSD_WORKFLOW_MCP_COMMAND: "node",
+    GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_BIN_PATH: "/tmp/gsd-bin" }),
+  });
+  assert.equal(binOnly?.env?.GSD_CLI_PATH, "/tmp/gsd-bin");
+  assert.equal(binOnly?.env?.GSD_BIN_PATH, "/tmp/gsd-bin");
+
+  const cliOnly = detectWorkflowMcpLaunchConfig("/tmp/project", {
+    GSD_WORKFLOW_MCP_COMMAND: "node",
+    GSD_WORKFLOW_MCP_ENV: JSON.stringify({ GSD_CLI_PATH: "/tmp/gsd-cli" }),
+  });
+  assert.equal(cliOnly?.env?.GSD_CLI_PATH, "/tmp/gsd-cli");
+  assert.equal(cliOnly?.env?.GSD_BIN_PATH, "/tmp/gsd-cli");
+});
+
 test("buildWorkflowMcpServers mirrors explicit launch config", () => {
   const servers = buildWorkflowMcpServers("/tmp/project", {
     GSD_WORKFLOW_MCP_COMMAND: "node",
@@ -135,6 +190,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server from GSD_BIN_PAT
     env: launch?.env,
   });
   assert.equal(launch?.env?.GSD_CLI_PATH, devCliPath);
+  assert.equal(launch?.env?.GSD_BIN_PATH, devCliPath);
   assert.equal(launch?.env?.GSD_PERSIST_WRITE_GATE_STATE, "1");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, worktreeRoot);
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
@@ -149,6 +205,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the
   assert.equal(launch?.command, process.execPath);
   assert.equal(launch?.cwd, "/tmp/project");
   assert.equal(launch?.env?.GSD_CLI_PATH, "/tmp/gsd-loader.js");
+  assert.equal(launch?.env?.GSD_BIN_PATH, "/tmp/gsd-loader.js");
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
@@ -166,6 +223,7 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the
   assert.equal(launch?.command, process.execPath);
   assert.equal(launch?.cwd, "/tmp/project");
   assert.equal(launch?.env?.GSD_CLI_PATH, undefined);
+  assert.equal(launch?.env?.GSD_BIN_PATH, undefined);
   assert.equal(launch?.env?.GSD_WORKFLOW_PROJECT_ROOT, "/tmp/project");
   assert.match(launch?.env?.GSD_WORKFLOW_EXECUTORS_MODULE ?? "", /workflow-tool-executors\.(js|ts)$/);
   assert.match(launch?.env?.GSD_WORKFLOW_WRITE_GATE_MODULE ?? "", /write-gate\.(js|ts)$/);
@@ -464,11 +522,20 @@ test("usesWorkflowMcpTransport matches local externalCli providers", () => {
   assert.equal(usesWorkflowMcpTransport("oauth", "local://custom"), false);
 });
 
-test("supportsStructuredQuestions stays enabled on workflow MCP transports when ask_user_questions is available", () => {
+test("supportsStructuredQuestions disables local workflow MCP questions unless explicitly enabled", () => {
   assert.equal(
     supportsStructuredQuestions(["ask_user_questions"], {
       authMode: "externalCli",
       baseUrl: "local://claude-code",
+      env: {},
+    }),
+    false,
+  );
+  assert.equal(
+    supportsStructuredQuestions(["mcp__gsd-workflow__ask_user_questions"], {
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      env: { GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS: "1" } as NodeJS.ProcessEnv,
     }),
     true,
   );
@@ -716,3 +783,15 @@ test("workflow transport error guidance includes /gsd mcp init hint", () => {
   const src = readSrc("workflow-mcp.ts");
   assert.match(src, /Please run \/gsd mcp init \./);
 });
+
+test("buildWorkflowMcpServers is only imported by tests or Claude Code MCP boundary code", () => {
+  const offenders: string[] = [];
+  for (const file of listTsFiles(gsdDir)) {
+    const rel = file.slice(gsdDir.length + 1).replace(/\\/g, "/");
+    if (rel === "workflow-mcp.ts" || rel.startsWith("tests/")) continue;
+    const src = readFileSync(file, "utf-8");
+    if (/\bimport\b[\s\S]*\bbuildWorkflowMcpServers\b/.test(src)) offenders.push(rel);
+  }
+
+  assert.deepEqual(offenders, []);
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -10,8 +10,9 @@ import {
   closeDatabase,
   _getAdapter,
   insertGateRow,
+  upsertRequirement,
 } from "../gsd-db.ts";
-import { markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot } from "../bootstrap/write-gate.ts";
+import { markApprovalGateVerified, markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot, setPendingGate } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
   executePlanMilestone,
@@ -676,7 +677,243 @@ test("executeSummarySave removes sibling CONTEXT-DRAFT when writing milestone CO
       "CONTEXT-DRAFT.md should be removed after final CONTEXT.md is written",
     );
   } finally {
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave supports root-level deep planning artifacts", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const project = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+    }, base));
+    assert.equal(project.isError, undefined);
+    assert.equal(project.details.path, "PROJECT.md");
+    assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
+
+    upsertRequirement({
+      id: "R001",
+      class: "primary-user-loop",
+      status: "active",
+      description: "User can add a task",
+      why: "Core loop",
+      source: "user",
+      primary_owner: "M001/none yet",
+      supporting_slices: "none",
+      validation: "unmapped",
+      notes: "",
+      full_content: "",
+      superseded_by: null,
+    });
+
+    const requirements = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "REQUIREMENTS",
+      content: "# Requirements\n\n## Active\n\n## Validated\n\n## Deferred\n\n## Out of Scope\n\n## Traceability\n\n## Coverage Summary\n",
+    }, base));
+    assert.equal(requirements.isError, undefined);
+    assert.equal(requirements.details.path, "REQUIREMENTS.md");
+    assert.equal(requirements.details.content_source, "requirements_table");
+    assert.ok(existsSync(join(base, ".gsd", "REQUIREMENTS.md")));
+
+    const db = _getAdapter();
+    const rows = db!.prepare(
+      "SELECT path, artifact_type, milestone_id FROM artifacts WHERE path IN ('PROJECT.md', 'REQUIREMENTS.md') ORDER BY path",
+    ).all() as Array<Record<string, unknown>>;
+    assert.deepEqual(
+      rows.map((row) => [row.path, row.artifact_type, row.milestone_id]),
+      [
+        ["PROJECT.md", "PROJECT", null],
+        ["REQUIREMENTS.md", "REQUIREMENTS", null],
+      ],
+    );
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave blocks final root artifacts while approval gate is pending", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    setPendingGate("depth_verification_requirements_confirm", base);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "REQUIREMENTS",
+      content: "# Requirements\n\n## Active\n",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.error, "root_artifact_write_blocked");
+    assert.match(result.content[0].text, /has not been confirmed/);
+    assert.equal(existsSync(join(base, ".gsd", "REQUIREMENTS.md")), false);
+
+    const draft = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "REQUIREMENTS-DRAFT",
+      content: "# Draft Requirements\n",
+    }, base));
+    assert.equal(draft.isError, undefined);
+    assert.ok(existsSync(join(base, ".gsd", "REQUIREMENTS-DRAFT.md")));
+  } finally {
+    clearDiscussionFlowState(base);
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave requires verified root approval in deep mode", async () => {
+  const base = makeTmpBase();
+  try {
+    writeFileSync(join(base, ".gsd", "PREFERENCES.md"), "---\nplanning_depth: deep\n---\n");
+    openTestDb(base);
+
+    const blocked = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+    }, base));
+
+    assert.equal(blocked.isError, true);
+    assert.equal(blocked.details.error, "root_artifact_write_blocked");
+    assert.match(blocked.content[0].text, /fail-closed/);
+    assert.equal(existsSync(join(base, ".gsd", "PROJECT.md")), false);
+
+    markApprovalGateVerified("depth_verification_project_confirm", base);
+
+    const unblocked = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: "# Project\n\n## What This Is\n\nA root project artifact.",
+    }, base));
+
+    assert.equal(unblocked.isError, undefined);
+    assert.equal(unblocked.details.path, "PROJECT.md");
+    assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
+  } finally {
+    clearDiscussionFlowState(base);
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave renders final REQUIREMENTS from the DB source of truth", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+    markApprovalGateVerified("depth_verification_requirements_confirm", base);
+
+    upsertRequirement({
+      id: "R001",
+      class: "primary-user-loop",
+      status: "active",
+      description: "User can add a task",
+      why: "Core loop",
+      source: "user",
+      primary_owner: "M001/none yet",
+      supporting_slices: "none",
+      validation: "unmapped",
+      notes: "saved through requirement tool",
+      full_content: "",
+      superseded_by: null,
+    });
+
+    const requirementsPath = join(base, ".gsd", "REQUIREMENTS.md");
+    const bloatedMarkdown = [
+      "# Requirements",
+      "",
+      "## Active",
+      "",
+      ...Array.from({ length: 30 }, (_, i) => [
+        `### R${String(i + 100).padStart(3, "0")} — Duplicate`,
+        "- Class: primary-user-loop",
+        "- Status: active",
+        "- Description: Duplicate retry row",
+        "- Why it matters: Retry drift",
+        "- Source: test",
+        "- Primary owning slice: M001/none yet",
+        "- Supporting slices: none",
+        "- Validation: unmapped",
+        "",
+      ].join("\n")),
+    ].join("\n");
+    writeFileSync(requirementsPath, bloatedMarkdown);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "REQUIREMENTS",
+      content: "# Requirements\n\n## Active\n\n### R999 — Wrong markdown source\n\n- Description: This content must not become canonical.\n",
+    }, base));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.path, "REQUIREMENTS.md");
+    assert.equal(result.details.content_source, "requirements_table");
+
+    const content = readFileSync(requirementsPath, "utf-8");
+    assert.match(content, /### R001 — User can add a task/);
+    assert.match(content, /## Validated/);
+    assert.match(content, /## Deferred/);
+    assert.match(content, /## Out of Scope/);
+    assert.doesNotMatch(content, /R999|Wrong markdown source|This content must not become canonical/);
+    assert.ok(
+      Buffer.byteLength(content, "utf-8") < Buffer.byteLength(bloatedMarkdown, "utf-8") * 0.5,
+      "test setup proves final DB projection may be much smaller than accumulated retry output",
+    );
+
+    const db = _getAdapter();
+    const reqRows = db!
+      .prepare("SELECT id, description FROM requirements ORDER BY id")
+      .all() as Array<Record<string, unknown>>;
+    assert.deepEqual(
+      reqRows.map((row) => [row.id, row.description]),
+      [["R001", "User can add a task"]],
+      "summary save must not parse markdown back into requirements rows",
+    );
+
+    const artifact = db!
+      .prepare("SELECT full_content FROM artifacts WHERE path = ?")
+      .get("REQUIREMENTS.md") as Record<string, unknown>;
+    assert.equal(artifact.full_content, content);
+  } finally {
+    clearDiscussionFlowState(base);
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave rejects final REQUIREMENTS when the DB source is empty", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "REQUIREMENTS",
+      content: "# Requirements\n\n## Active\n\n",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.error, "no_active_requirements");
+    assert.match(result.content[0].text, /no active requirements found/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSummarySave rejects milestone-scoped artifacts without milestone_id", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "CONTEXT",
+      content: "# Context\n",
+    }, base));
+    assert.equal(result.isError, true);
+    assert.equal(result.details.error, "missing_milestone_id");
+    assert.match(result.content[0].text, /milestone_id is required/);
+  } finally {
     closeDatabase();
     cleanup(base);
   }
@@ -749,7 +986,7 @@ test("executeSummarySave CONTEXT HARD BLOCK clears after write-gate state file i
   process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
   try {
     openTestDb(base);
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
 
     // First call: CONTEXT artifact without depth verification → HARD BLOCK
     const blocked = await inProjectDir(base, () => executeSummarySave({
@@ -800,7 +1037,7 @@ test("executeSummarySave CONTEXT HARD BLOCK clears after write-gate state file i
     } else {
       process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
     }
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
     closeDatabase();
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/workspace.test.ts

@@ -0,0 +1,196 @@
+// GSD-2 + Workspace handle tests: createWorkspace and scopeMilestone
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  realpathSync,
+  symlinkSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-ws-test-")));
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe("createWorkspace", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("from a project root produces mode=project and worktreeRoot=null", () => {
+    const ws = createWorkspace(projectDir);
+    assert.equal(ws.mode, "project");
+    assert.equal(ws.worktreeRoot, null);
+    assert.equal(ws.projectRoot, realpathSync(projectDir));
+  });
+
+  test("from a worktree path produces mode=worktree, worktreeRoot=realpath, projectRoot=realpath of project", () => {
+    // Construct a worktree path: <projectDir>/.gsd/worktrees/M001
+    const worktreePath = join(projectDir, ".gsd", "worktrees", "M001");
+    mkdirSync(worktreePath, { recursive: true });
+
+    const ws = createWorkspace(worktreePath);
+    assert.equal(ws.mode, "worktree");
+    assert.equal(ws.worktreeRoot, realpathSync(worktreePath));
+    assert.equal(ws.projectRoot, realpathSync(projectDir));
+  });
+
+  test("normalizes /foo and /foo/ to identical identityKey", () => {
+    const wsTrailing = createWorkspace(projectDir + "/");
+    const wsNoTrailing = createWorkspace(projectDir);
+    assert.equal(wsTrailing.identityKey, wsNoTrailing.identityKey);
+  });
+
+  test("follows symlinks — identityKey matches realpath of target", (t) => {
+    const linkParent = mkdtempSync(join(tmpdir(), "gsd-ws-link-"));
+    const linkPath = join(linkParent, "project");
+    t.after(() => {
+      rmSync(linkParent, { recursive: true, force: true });
+    });
+    symlinkSync(projectDir, linkPath, "junction");
+
+    const ws = createWorkspace(linkPath);
+    assert.equal(ws.identityKey, realpathSync(projectDir));
+  });
+});
+
+describe("GsdWorkspace and MilestoneScope are frozen", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("workspace is frozen", () => {
+    const ws = createWorkspace(projectDir);
+    assert.ok(Object.isFrozen(ws), "workspace should be frozen");
+    assert.throws(() => {
+      (ws as { mode: string }).mode = "worktree";
+    }, /Cannot assign/);
+  });
+
+  test("scope is frozen", () => {
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+    assert.ok(Object.isFrozen(scope), "scope should be frozen");
+    assert.throws(() => {
+      (scope as { milestoneId: string }).milestoneId = "M999";
+    }, /Cannot assign/);
+  });
+
+  test("contract inside workspace is frozen", () => {
+    const ws = createWorkspace(projectDir);
+    assert.ok(Object.isFrozen(ws.contract), "contract should be frozen");
+  });
+});
+
+describe("scopeMilestone path methods", () => {
+  let projectDir: string;
+  const MID = "M001";
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("produces correct paths for a known milestone ID", () => {
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, MID);
+    const gsd = ws.contract.projectGsd;
+
+    assert.equal(scope.milestoneId, MID);
+    assert.equal(scope.contextFile(), join(gsd, "milestones", MID, `${MID}-CONTEXT.md`));
+    assert.equal(scope.roadmapFile(), join(gsd, "milestones", MID, `${MID}-ROADMAP.md`));
+    assert.equal(scope.stateFile(), join(gsd, "STATE.md"));
+    assert.equal(scope.dbPath(), ws.contract.projectDb);
+    assert.equal(scope.milestoneDir(), join(gsd, "milestones", MID));
+    assert.equal(scope.metaJson(), join(gsd, `${MID}-META.json`));
+  });
+
+  test("two scopes from same workspace + same MID produce identical paths", () => {
+    const ws = createWorkspace(projectDir);
+    const scope1 = scopeMilestone(ws, MID);
+    const scope2 = scopeMilestone(ws, MID);
+
+    assert.equal(scope1.contextFile(), scope2.contextFile());
+    assert.equal(scope1.roadmapFile(), scope2.roadmapFile());
+    assert.equal(scope1.stateFile(), scope2.stateFile());
+    assert.equal(scope1.dbPath(), scope2.dbPath());
+    assert.equal(scope1.milestoneDir(), scope2.milestoneDir());
+    assert.equal(scope1.metaJson(), scope2.metaJson());
+  });
+});
+
+describe("createWorkspace: contract.projectGsd is realpath-canonicalized when basePath is a symlink", () => {
+  let projectDir = "";
+  let linkParent = "";
+  let linkPath = "";
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+    linkParent = mkdtempSync(join(tmpdir(), "gsd-ws-symlink-"));
+    linkPath = join(linkParent, "project");
+    symlinkSync(projectDir, linkPath, "junction");
+  });
+
+  afterEach(() => {
+    if (linkParent) rmSync(linkParent, { recursive: true, force: true });
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    linkParent = "";
+    linkPath = "";
+    projectDir = "";
+  });
+
+  test("contract.projectGsd matches realpath of projectRoot when workspace is created via symlink", () => {
+    const ws = createWorkspace(linkPath);
+
+    const canonicalProjectRoot = realpathSync(projectDir);
+
+    // identityKey must be the realpath of the canonical project root
+    assert.equal(ws.identityKey, canonicalProjectRoot);
+    assert.equal(ws.projectRoot, canonicalProjectRoot);
+
+    // contract.projectGsd must start with the canonical project root —
+    // not with the symlink path. If the bug is present, contract.projectGsd
+    // would be linkPath + "/.gsd" instead of canonicalProjectRoot + "/.gsd".
+    assert.ok(
+      ws.contract.projectGsd.startsWith(canonicalProjectRoot),
+      `contract.projectGsd ("${ws.contract.projectGsd}") must be under the realpath'd projectRoot ("${canonicalProjectRoot}"), not the symlink path`,
+    );
+  });
+
+  test("contract.projectDb matches realpath of projectRoot when workspace is created via symlink", () => {
+    const ws = createWorkspace(linkPath);
+    const canonicalProjectRoot = realpathSync(projectDir);
+
+    assert.ok(
+      ws.contract.projectDb.startsWith(canonicalProjectRoot),
+      `contract.projectDb ("${ws.contract.projectDb}") must be under the realpath'd projectRoot ("${canonicalProjectRoot}")`,
+    );
+  });
+});