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

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 */ }
+  });
+});

package/src/resources/extensions/gsd/tests/complete-task-rollback-evidence.test.ts

@@ -41,7 +41,7 @@ const VALID_PARAMS = {
   ],
 };
 
-describe("complete-task rollback cleans up verification_evidence (#2724)", () => {
+describe("complete-task projection failures keep DB completion committed", () => {
   let base: string;
 
   afterEach(() => {
@@ -75,7 +75,7 @@ describe("complete-task rollback cleans up verification_evidence (#2724)", () =>
     assert.equal(rows.length, 2, "should have 2 evidence rows after success");
   });
 
-  it("deletes verification_evidence rows on disk-render rollback", async () => {
+  it("keeps task completion and verification_evidence when disk projection write fails", async () => {
     base = makeTmpBase();
     openDatabase(join(base, ".gsd", "gsd.db"));
     insertMilestone({ id: "M001" });
@@ -87,20 +87,19 @@ describe("complete-task rollback cleans up verification_evidence (#2724)", () =>
     writeFileSync(tasksDir, "not-a-directory");
 
     const result = await handleCompleteTask(VALID_PARAMS, base);
-    assert.ok("error" in result, "should return error when disk write fails");
+    assert.ok(!("error" in result), `unexpected error: ${"error" in result ? result.error : ""}`);
+    assert.equal(result.stale, true, "result should report stale projection");
 
-    // Task should be rolled back to pending
     const adapter = _getAdapter()!;
     const task = adapter.prepare(
       `SELECT status FROM tasks WHERE milestone_id = 'M001' AND slice_id = 'S01' AND id = 'T01'`,
     ).get() as { status: string } | undefined;
     assert.ok(task, "task row should still exist");
-    assert.equal(task!.status, "pending", "task status should be rolled back to pending");
+    assert.equal(task!.status, "complete", "task status should remain complete");
 
-    // Verification evidence should be cleaned up — no orphaned rows
     const evidenceRows = adapter.prepare(
       `SELECT * FROM verification_evidence WHERE task_id = 'T01' AND slice_id = 'S01' AND milestone_id = 'M001'`,
     ).all();
-    assert.equal(evidenceRows.length, 0, "verification_evidence should be empty after rollback");
+    assert.equal(evidenceRows.length, 2, "verification_evidence should remain committed");
   });
 });

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -403,12 +403,11 @@ console.log('\n=== complete-task: handler idempotency ===');
   const r1 = await handleCompleteTask(params, basePath);
   assertTrue(!('error' in r1), 'first call should succeed');
 
-  // Verify complete-task did not duplicate T01. State reconciliation may import
-  // the remaining plan task from disk so the DB stays aligned with S01-PLAN.md.
+  // Verify complete-task did not duplicate T01. S01-PLAN.md is a projection,
+  // so the remaining plan task is not imported implicitly.
   const tasks = getSliceTasks('M001', 'S01');
-  assertEq(tasks.length, 2, 'should have T01 plus reconciled T02 after first call');
+  assertEq(tasks.length, 1, 'should only have the completed DB task after first call');
   assertEq(tasks.filter(t => t.id === 'T01').length, 1, 'should have exactly one T01 row after first call');
-  assertEq(tasks.find(t => t.id === 'T02')?.status, 'pending', 'T02 should be reconciled as pending');
 
   // Second call with same params — state machine guard rejects (task is already complete)
   const r2 = await handleCompleteTask(params, basePath);
@@ -419,7 +418,7 @@ console.log('\n=== complete-task: handler idempotency ===');
 
   // Still no duplicate rows from the rejected second call.
   const tasksAfter = getSliceTasks('M001', 'S01');
-  assertEq(tasksAfter.length, 2, 'should still have T01 plus reconciled T02 after rejected second call');
+  assertEq(tasksAfter.length, 1, 'should still only have T01 after rejected second call');
   assertEq(tasksAfter.filter(t => t.id === 'T01').length, 1, 'should still have exactly one T01 row');
 
   cleanupDir(basePath);
@@ -447,10 +446,13 @@ console.log('\n=== complete-task: handler with missing plan file ===');
   const params = makeValidParams();
   const result = await handleCompleteTask(params, basePath);
 
-  // Should succeed even without plan file — just skip checkbox toggle
+  // Should succeed and regenerate the missing plan projection from DB.
   assertTrue(!('error' in result), 'handler should succeed without plan file');
   if (!('error' in result)) {
     assertTrue(fs.existsSync(result.summaryPath), 'summary should be written even without plan file');
+    const planPath = path.join(basePath, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md');
+    assertTrue(fs.existsSync(planPath), 'missing plan projection should be regenerated from DB');
+    assertTrue(fs.readFileSync(planPath, 'utf-8').includes('[x] **T01:'), 'regenerated plan should reflect DB task completion');
   }
 
   cleanupDir(basePath);

package/src/resources/extensions/gsd/tests/completed-at-reconcile.test.ts

@@ -1,15 +1,9 @@
 /**
- * Behavioural regression test for #4129.
+ * Behavioural regression test for DB-authoritative task completion.
  *
- * When deriveStateFromDb's reconcileSliceTasks finds a SUMMARY.md on disk
- * for a task whose DB row is still pending, it flips the row to "complete".
- * Before #4129, the call to updateTaskStatus omitted the completedAt
- * timestamp, leaving completed_at NULL forever.
- *
- * The fix passes new Date().toISOString() as the 5th argument; this test
- * exercises that path end-to-end and asserts the column is populated.
- *
- * Refs #4829 (rewrite from positional source-grep).
+ * A task SUMMARY.md on disk is a projection, not a completion command.
+ * deriveStateFromDb must not flip a pending DB task to complete or invent a
+ * completed_at timestamp from disk evidence.
  */
 
 import { describe, test, beforeEach, afterEach } from 'node:test';
@@ -46,27 +40,26 @@ function setupProject(): void {
     `# M001\n\n## Slices\n\n- [ ] **S01: Slice** \`risk:low\` \`depends:[]\`\n  - After this: works\n`,
   );
 
-  // Plan file for the slice so reconcile can populate task list if DB is empty.
+  // Plan file for the slice. It is a projection and must not drive DB state.
   writeFileSync(
     join(basePath, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'S01-PLAN.md'),
     `# S01: Slice\n\n## Tasks\n\n- [ ] **T01: Test task** \`est:30m\`\n  - Do: x\n  - Verify: y\n`,
   );
 
-  // The summary file: this is the on-disk evidence that flips the task
-  // status to "complete" inside reconcileSliceTasks.
+  // The summary file is a projection and must not complete the task.
   writeFileSync(
     join(basePath, '.gsd', 'milestones', 'M001', 'slices', 'S01', 'tasks', 'T01-SUMMARY.md'),
     '---\nid: T01\nparent: S01\nmilestone: M001\nblocker_discovered: false\n---\n# T01\n',
   );
 }
 
-describe('completed_at reconcile (#4129)', () => {
+describe('completed_at DB-authoritative derivation', () => {
   beforeEach(() => {
     setupProject();
     openDatabase(join(basePath, '.gsd', 'gsd.db'));
     insertMilestone({ id: 'M001', title: 'M001', status: 'active' });
     insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Slice', status: 'active' });
-    // Task is "pending" in DB, but SUMMARY.md exists on disk → reconcile flips it.
+    // Task is "pending" in DB, even though SUMMARY.md exists on disk.
     insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Test task', status: 'pending' });
     invalidateStateCache();
   });
@@ -76,24 +69,16 @@ describe('completed_at reconcile (#4129)', () => {
     try { rmSync(basePath, { recursive: true, force: true }); } catch { /* */ }
   });
 
-  test('reconcileSliceTasks sets completed_at when flipping a pending task to complete via SUMMARY.md', async () => {
+  test('deriveStateFromDb does not set completed_at from a disk SUMMARY projection', async () => {
     const before = getTask('M001', 'S01', 'T01');
     assert.strictEqual(before?.status, 'pending', 'task starts pending');
     assert.strictEqual(before?.completed_at, null, 'task starts with completed_at NULL');
 
-    // Trigger the reconcile path (state.ts → reconcileSliceTasks).
+    // Derive runtime state. Disk SUMMARY.md must not mutate the DB row.
     await deriveStateFromDb(basePath);
 
     const after = getTask('M001', 'S01', 'T01');
-    assert.strictEqual(after?.status, 'complete', 'task should be flipped to complete');
-    assert.ok(
-      typeof after?.completed_at === 'string' && after.completed_at.length > 0,
-      `completed_at must be populated by reconcileSliceTasks (#4129); got ${JSON.stringify(after?.completed_at)}`,
-    );
-    // Sanity: timestamp parses as a valid ISO date.
-    assert.ok(
-      !Number.isNaN(Date.parse(after!.completed_at!)),
-      `completed_at should be a valid ISO timestamp, got ${after!.completed_at}`,
-    );
+    assert.strictEqual(after?.status, 'pending', 'task remains pending');
+    assert.strictEqual(after?.completed_at, null, 'completed_at remains NULL');
   });
 });

package/src/resources/extensions/gsd/tests/completed-units-metrics-sync.test.ts

@@ -58,13 +58,26 @@ test("#2313: syncStateToProjectRoot should sync metrics.json", () => {
   );
 });
 
-test("#2313: syncWorktreeStateBack should include metrics.json in ROOT_STATE_FILES", () => {
+test("syncStateToProjectRoot should back-sync completed-units.json", () => {
+  const syncSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
+  const syncSrc = readFileSync(syncSrcPath, "utf-8");
+  const fnIdx = syncSrc.indexOf("export function syncStateToProjectRoot(");
+  assert.ok(fnIdx !== -1, "syncStateToProjectRoot exists");
+  const fnBlock = syncSrc.slice(fnIdx, syncSrc.indexOf("// ─── Resource Staleness", fnIdx));
+
+  assert.ok(
+    fnBlock.includes('"completed-units.json"'),
+    "syncStateToProjectRoot should copy completed-units.json back to the project root",
+  );
+});
+
+test("#2313: syncWorktreeStateBack should include metrics.json in ROOT_DIAGNOSTIC_FILES", () => {
   const autoWorktreeSrcPath = join(import.meta.dirname, "..", "auto-worktree.ts");
   const autoWorktreeSrc = readFileSync(autoWorktreeSrcPath, "utf-8");
 
-  // Find the ROOT_STATE_FILES constant (single source of truth for both sync directions)
-  const constIdx = autoWorktreeSrc.indexOf("ROOT_STATE_FILES");
-  assert.ok(constIdx !== -1, "ROOT_STATE_FILES constant exists");
+  // Find the ROOT_DIAGNOSTIC_FILES constant used for worktree copy-back.
+  const constIdx = autoWorktreeSrc.indexOf("ROOT_DIAGNOSTIC_FILES");
+  assert.ok(constIdx !== -1, "ROOT_DIAGNOSTIC_FILES constant exists");
 
   // Get the array content
   const arrayStart = autoWorktreeSrc.indexOf("[", constIdx);
@@ -73,7 +86,7 @@ test("#2313: syncWorktreeStateBack should include metrics.json in ROOT_STATE_FIL
 
   assert.ok(
     rootFilesBlock.includes("metrics.json"),
-    "metrics.json should be in ROOT_STATE_FILES list",
+    "metrics.json should be in ROOT_DIAGNOSTIC_FILES list",
   );
 });
 

package/src/resources/extensions/gsd/tests/db-path-worktree-symlink.test.ts

@@ -47,7 +47,7 @@ const symlinkResult = resolveProjectRootDbPath(symlinkPath);
 assertEq(
   symlinkResult,
   join("/home/user/myproject/.gsd/projects/abc123def", "gsd.db"),
-  "/.gsd/projects/<hash>/worktrees/ resolves to hash-level DB (#2517, updated for #2952)",
+  "/.gsd/projects/<hash>/worktrees/ resolves to external project state DB",
 );
 
 // Windows-style separators for symlink layout
@@ -57,7 +57,7 @@ if (sep === "\\") {
   assertEq(
     winResult,
     join("C:\\Users\\dev\\project\\.gsd\\projects\\abc123def", "gsd.db"),
-    "Windows /.gsd/projects/<hash>/worktrees/ resolves to hash-level DB",
+    "Windows /.gsd/projects/<hash>/worktrees/ resolves to external project state DB",
   );
 } else {
   // On non-Windows, test forward-slash variant explicitly
@@ -66,7 +66,7 @@ if (sep === "\\") {
   assertEq(
     fwdResult,
     join("/home/user/myproject/.gsd/projects/abc123def", "gsd.db"),
-    "Forward-slash /.gsd/projects/<hash>/worktrees/ resolves to hash-level DB on POSIX",
+    "Forward-slash /.gsd/projects/<hash>/worktrees/ resolves to external project state DB on POSIX",
   );
 }
 
@@ -76,7 +76,7 @@ const deepResult = resolveProjectRootDbPath(deepSymlinkPath);
 assertEq(
   deepResult,
   join("/home/user/myproject/.gsd/projects/deadbeef42", "gsd.db"),
-  "Deep /.gsd/projects/<hash>/worktrees/ path resolves to hash-level DB (#2952)",
+  "Deep /.gsd/projects/<hash>/worktrees/ path resolves to external project state DB",
 );
 
 // Non-worktree path should be unchanged

package/src/resources/extensions/gsd/tests/db-writer-path-containment.test.ts

@@ -0,0 +1,152 @@
+// GSD-2 + db-writer path containment: regression tests for path.relative-based traversal guard
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { openDatabase, closeDatabase } from "../gsd-db.ts";
+import { createWorkspace, scopeMilestone } from "../workspace.ts";
+import {
+  saveArtifactToDbForWorkspace,
+  saveArtifactToDbByScope,
+} from "../db-writer.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(base: string): string {
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  return base;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("saveArtifactToDbForWorkspace: path.relative containment guard", () => {
+  let tmp: string;
+  let projectDir: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "gsd-path-contain-fw-"));
+    projectDir = makeProjectDir(tmp);
+    openDatabase(join(projectDir, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  // Attack: /foo/.gsd-other/file resolves to a path that startsWith("/foo/.gsd")
+  // but is NOT inside /foo/.gsd/. The path.relative fix correctly detects this.
+  test("rejects sibling directory that startsWith would have accepted", async () => {
+    // Create a sibling directory next to .gsd that shares the prefix
+    const sibling = join(projectDir, ".gsd-other");
+    mkdirSync(sibling, { recursive: true });
+
+    const ws = createWorkspace(projectDir);
+    // Craft an opts.path that traverses out of .gsd into .gsd-other
+    // resolve(gsdDir, "../.gsd-other/evil.md") === projectDir + "/.gsd-other/evil.md"
+    // which startsWith(projectDir + "/.gsd") because ".gsd-other" starts with ".gsd"
+    const traversalPath = "../.gsd-other/evil.md";
+
+    await assert.rejects(
+      () =>
+        saveArtifactToDbForWorkspace(ws, {
+          path: traversalPath,
+          artifact_type: "CONTEXT",
+          content: "attack",
+        }),
+      /path escapes \.gsd\/ directory/,
+    );
+  });
+
+  test("rejects absolute path input", async () => {
+    const ws = createWorkspace(projectDir);
+    await assert.rejects(
+      () =>
+        saveArtifactToDbForWorkspace(ws, {
+          path: "/etc/passwd",
+          artifact_type: "CONTEXT",
+          content: "attack",
+        }),
+      /path escapes \.gsd\/ directory/,
+    );
+  });
+
+  test("accepts a legitimate path inside .gsd/", async () => {
+    const ws = createWorkspace(projectDir);
+    // Should not throw — CONTEXT.md inside .gsd is valid
+    await assert.doesNotReject(() =>
+      saveArtifactToDbForWorkspace(ws, {
+        path: "CONTEXT.md",
+        artifact_type: "CONTEXT",
+        content: "# Context\n",
+      }),
+    );
+  });
+});
+
+describe("saveArtifactToDbByScope: path.relative containment guard", () => {
+  let tmp: string;
+  let projectDir: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), "gsd-path-contain-bs-"));
+    projectDir = makeProjectDir(tmp);
+    openDatabase(join(projectDir, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("rejects sibling directory that startsWith would have accepted", async () => {
+    const sibling = join(projectDir, ".gsd-other");
+    mkdirSync(sibling, { recursive: true });
+
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+    const traversalPath = "../.gsd-other/evil.md";
+
+    await assert.rejects(
+      () =>
+        saveArtifactToDbByScope(scope, {
+          path: traversalPath,
+          artifact_type: "CONTEXT",
+          content: "attack",
+        }),
+      /path escapes \.gsd\/ directory/,
+    );
+  });
+
+  test("rejects absolute path input", async () => {
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+    await assert.rejects(
+      () =>
+        saveArtifactToDbByScope(scope, {
+          path: "/etc/passwd",
+          artifact_type: "CONTEXT",
+          content: "attack",
+        }),
+      /path escapes \.gsd\/ directory/,
+    );
+  });
+
+  test("accepts a legitimate milestone-relative path inside .gsd/", async () => {
+    mkdirSync(join(projectDir, ".gsd", "milestones", "M001"), {
+      recursive: true,
+    });
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, "M001");
+    await assert.doesNotReject(() =>
+      saveArtifactToDbByScope(scope, {
+        path: "milestones/M001/M001-CONTEXT.md",
+        artifact_type: "CONTEXT",
+        content: "# Context\n",
+      }),
+    );
+  });
+});