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

package/src/resources/extensions/gsd/tests/validator-scope-parity.test.ts

@@ -0,0 +1,239 @@
+// GSD-2 + Tests verifying writer/validator path parity via MilestoneScope (C3)
+//
+// Critical invariant: a writer that constructs paths via scope.contextFile() /
+// scope.roadmapFile() and a validator that resolves paths via the scope-based
+// wrappers in guided-flow.ts must produce IDENTICAL absolute paths for the same
+// logical inputs.  If they diverge, writes go to a different location than the
+// validator checks, causing silent failures.
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, realpathSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import {
+  verifyExpectedArtifactForScope,
+  resolveExpectedArtifactPathForScope,
+  isGhostMilestoneByScope,
+} from "../guided-flow.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(label = "gsd-vsp-"): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), label)));
+  mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true });
+  return dir;
+}
+
+// ─── Suite: writer/validator path parity ─────────────────────────────────────
+
+describe("validator-scope-parity: writer and validator produce identical paths", () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = makeProjectDir();
+  });
+
+  afterEach(() => {
+    if (base) rmSync(base, { recursive: true, force: true });
+  });
+
+  test("resolveExpectedArtifactPathForScope('discuss-milestone') matches scope.contextFile()", () => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    // Writer path: what the discuss/plan agent writes to
+    const writerPath = scope.contextFile();
+
+    // Validator path: what the validator checks
+    const validatorPath = resolveExpectedArtifactPathForScope(scope, "discuss-milestone", "M001");
+
+    assert.equal(
+      validatorPath,
+      writerPath,
+      "discuss-milestone artifact path must match scope.contextFile()",
+    );
+  });
+
+  test("resolveExpectedArtifactPathForScope('plan-milestone') matches scope.roadmapFile()", () => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    const writerPath = scope.roadmapFile();
+    const validatorPath = resolveExpectedArtifactPathForScope(scope, "plan-milestone", "M001");
+
+    assert.equal(
+      validatorPath,
+      writerPath,
+      "plan-milestone artifact path must match scope.roadmapFile()",
+    );
+  });
+
+  test("resolveExpectedArtifactPathForScope returns an absolute path", () => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    const path = resolveExpectedArtifactPathForScope(scope, "discuss-milestone", "M001");
+    assert.ok(path, "path must be non-null for a milestone unit");
+    assert.ok(path!.startsWith("/"), "path must be absolute");
+  });
+});
+
+// ─── Suite: cwd-drift immunity ────────────────────────────────────────────────
+
+describe("validator-scope-parity: scope-based validators are immune to cwd-drift", () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = makeProjectDir();
+  });
+
+  afterEach(() => {
+    if (base) rmSync(base, { recursive: true, force: true });
+  });
+
+  test("resolveExpectedArtifactPathForScope path is unchanged after process.chdir", (t) => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    const pathBefore = resolveExpectedArtifactPathForScope(scope, "plan-milestone", "M001");
+
+    const originalCwd = process.cwd();
+    const altDir = mkdtempSync(join(tmpdir(), "gsd-cwd-alt-"));
+    t.after(() => {
+      process.chdir(originalCwd);
+      rmSync(altDir, { recursive: true, force: true });
+    });
+
+    process.chdir(altDir);
+
+    const pathAfter = resolveExpectedArtifactPathForScope(scope, "plan-milestone", "M001");
+
+    assert.equal(
+      pathAfter,
+      pathBefore,
+      "artifact path must not change after cwd drift",
+    );
+  });
+
+  test("isGhostMilestoneByScope result is consistent before and after process.chdir", (t) => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    // No DB, no content files — should be ghost
+    const resultBefore = isGhostMilestoneByScope(scope);
+
+    const originalCwd = process.cwd();
+    const altDir = mkdtempSync(join(tmpdir(), "gsd-cwd-alt2-"));
+    t.after(() => {
+      process.chdir(originalCwd);
+      rmSync(altDir, { recursive: true, force: true });
+    });
+
+    process.chdir(altDir);
+
+    const resultAfter = isGhostMilestoneByScope(scope);
+
+    assert.equal(
+      resultAfter,
+      resultBefore,
+      "isGhostMilestoneByScope result must be consistent across cwd change",
+    );
+  });
+});
+
+// ─── Suite: isGhostMilestoneByScope behavior ─────────────────────────────────
+
+describe("validator-scope-parity: isGhostMilestoneByScope correctness", () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = makeProjectDir();
+  });
+
+  afterEach(() => {
+    if (base) rmSync(base, { recursive: true, force: true });
+  });
+
+  test("isGhostMilestoneByScope returns true for milestone dir with no content files", () => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    // M001 dir exists (created in beforeEach) but has no CONTEXT/ROADMAP/SUMMARY
+    assert.equal(
+      isGhostMilestoneByScope(scope),
+      true,
+      "empty milestone dir with no content files should be ghost",
+    );
+  });
+
+  test("isGhostMilestoneByScope returns false when CONTEXT.md exists", (t) => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    // Write CONTEXT.md so the milestone is no longer a ghost
+    writeFileSync(scope.contextFile(), "# M001: Test\n\nContext.\n");
+    t.after(() => {
+      try { unlinkSync(scope.contextFile()); } catch {}
+    });
+
+    assert.equal(
+      isGhostMilestoneByScope(scope),
+      false,
+      "milestone with CONTEXT.md should not be ghost",
+    );
+  });
+});
+
+// ─── Suite: worktree path resolves to canonical project root ─────────────────
+
+describe("validator-scope-parity: scope uses canonical projectRoot not worktree path", () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = makeProjectDir("gsd-wt-parity-");
+  });
+
+  afterEach(() => {
+    if (base) rmSync(base, { recursive: true, force: true });
+  });
+
+  test("scope.workspace.projectRoot equals the input base for a non-worktree project", () => {
+    const ws = createWorkspace(base);
+    // For a plain project (not a worktree), projectRoot should be the realpath of base
+    assert.equal(
+      ws.projectRoot,
+      realpathSync(base),
+      "projectRoot must be realpath of the input base for a non-worktree project",
+    );
+  });
+
+  test("validator wrapper paths are rooted at scope.workspace.projectRoot, not at a worktree dir", () => {
+    // Simulate calling with a workspace that has projectRoot set.
+    // The validator should use projectRoot, not a different runtime path.
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    const artifactPath = resolveExpectedArtifactPathForScope(scope, "plan-milestone", "M001");
+
+    assert.ok(
+      artifactPath!.startsWith(scope.workspace.projectRoot),
+      `artifact path '${artifactPath}' must be rooted at projectRoot '${scope.workspace.projectRoot}'`,
+    );
+  });
+
+  test("verifyExpectedArtifactForScope uses projectRoot: returns false for non-existent artifact", () => {
+    const ws = createWorkspace(base);
+    const scope = scopeMilestone(ws, "M001");
+
+    // The artifact does not exist on disk yet
+    const ready = verifyExpectedArtifactForScope(scope, "plan-milestone", "M001");
+    assert.equal(
+      ready,
+      false,
+      "verifyExpectedArtifactForScope should return false when artifact is absent",
+    );
+  });
+});

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

@@ -50,8 +50,8 @@ 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", () => {

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

@@ -677,7 +677,7 @@ 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);
   }
@@ -741,9 +741,7 @@ test("executeSummarySave blocks final root artifacts while approval gate is pend
   const base = makeTmpBase();
   try {
     openTestDb(base);
-    await inProjectDir(base, async () => {
-      setPendingGate("depth_verification_requirements_confirm");
-    });
+    setPendingGate("depth_verification_requirements_confirm", base);
 
     const result = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "REQUIREMENTS",
@@ -762,7 +760,7 @@ test("executeSummarySave blocks final root artifacts while approval gate is pend
     assert.equal(draft.isError, undefined);
     assert.ok(existsSync(join(base, ".gsd", "REQUIREMENTS-DRAFT.md")));
   } finally {
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
     closeDatabase();
     cleanup(base);
   }
@@ -784,9 +782,7 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
     assert.match(blocked.content[0].text, /fail-closed/);
     assert.equal(existsSync(join(base, ".gsd", "PROJECT.md")), false);
 
-    await inProjectDir(base, async () => {
-      markApprovalGateVerified("depth_verification_project_confirm", base);
-    });
+    markApprovalGateVerified("depth_verification_project_confirm", base);
 
     const unblocked = await inProjectDir(base, () => executeSummarySave({
       artifact_type: "PROJECT",
@@ -797,7 +793,7 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
     assert.equal(unblocked.details.path, "PROJECT.md");
     assert.ok(existsSync(join(base, ".gsd", "PROJECT.md")));
   } finally {
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
     closeDatabase();
     cleanup(base);
   }
@@ -807,9 +803,7 @@ test("executeSummarySave renders final REQUIREMENTS from the DB source of truth"
   const base = makeTmpBase();
   try {
     openTestDb(base);
-    await inProjectDir(base, async () => {
-      markApprovalGateVerified("depth_verification_requirements_confirm", base);
-    });
+    markApprovalGateVerified("depth_verification_requirements_confirm", base);
 
     upsertRequirement({
       id: "R001",
@@ -882,7 +876,7 @@ test("executeSummarySave renders final REQUIREMENTS from the DB source of truth"
       .get("REQUIREMENTS.md") as Record<string, unknown>;
     assert.equal(artifact.full_content, content);
   } finally {
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(base);
     closeDatabase();
     cleanup(base);
   }
@@ -992,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({
@@ -1043,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}")`,
+    );
+  });
+});