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

package/src/resources/extensions/gsd/bootstrap/tests/write-gate-basepath.test.ts

@@ -0,0 +1,103 @@
+// GSD-2 write-gate bootstrap — regression test for required basePath (commit A3)
+//
+// Verifies that persistWriteGateSnapshot / loadWriteGateSnapshot are pinned to
+// the basePath argument and do not silently fall back to process.cwd(). The
+// underlying bug: both functions defaulted `basePath = process.cwd()`, so a
+// persist in cwd-A followed by a chdir to cwd-B and a load (which also
+// defaulted to process.cwd(), now cwd-B) missed the persisted file entirely —
+// the depth-verification state became invisible across cwd boundaries.
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  markDepthVerified,
+  loadWriteGateSnapshot,
+  clearDiscussionFlowState,
+} from "../write-gate.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "wg-basepath-test-"));
+}
+
+// Save and restore process.cwd() across tests to avoid cross-test pollution.
+let originalCwd: string;
+before(() => {
+  originalCwd = process.cwd();
+});
+after(() => {
+  if (process.cwd() !== originalCwd) {
+    process.chdir(originalCwd);
+  }
+});
+
+// ─── Scenario: persist with basePath=A, chdir, load with basePath=A ─────────
+//
+// This is the exact failure mode from the bug: persist used process.cwd() and
+// load used process.cwd(), and they resolved to different directories after a
+// chdir.  With the fix, both calls receive an explicit basePath so cwd changes
+// have no effect.
+
+describe("write-gate basePath regression", () => {
+  let baseDirA: string;
+  let baseDirB: string;
+
+  before(() => {
+    baseDirA = makeTempDir();
+    baseDirB = makeTempDir();
+  });
+
+  after(() => {
+    // Restore cwd before cleanup to avoid issues on Windows.
+    process.chdir(originalCwd);
+    rmSync(baseDirA, { recursive: true, force: true });
+    rmSync(baseDirB, { recursive: true, force: true });
+  });
+
+  test("snapshot persisted to basePath=A is readable after chdir to basePath=B", (t) => {
+    // Arrange: enable persistence (the default when env var is not set to "0"/"false").
+    const prev = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    t.after(() => {
+      if (prev === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = prev;
+      }
+    });
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+    // Reset state and clear any stale snapshot files from both dirs.
+    clearDiscussionFlowState(baseDirA);
+    clearDiscussionFlowState(baseDirB);
+
+    // Act: persist a milestone as depth-verified into baseDirA.
+    markDepthVerified("M001", baseDirA);
+
+    // Confirm the snapshot file was written under baseDirA.
+    const snapshotPath = join(baseDirA, ".gsd", "runtime", "write-gate-state.json");
+    assert.ok(existsSync(snapshotPath), "snapshot file should exist under baseDirA");
+
+    // Simulate what happens when cwd changes to a different project root.
+    process.chdir(baseDirB);
+    assert.notEqual(process.cwd(), baseDirA, "cwd should differ from baseDirA after chdir");
+
+    // Load snapshot using the explicit baseDirA — must see the persisted state.
+    const snapshot = loadWriteGateSnapshot(baseDirA);
+    assert.ok(
+      snapshot.verifiedDepthMilestones.includes("M001"),
+      "loadWriteGateSnapshot(baseDirA) must return the persisted milestone despite cwd being baseDirB",
+    );
+
+    // Loading with baseDirB must NOT see the state from baseDirA.
+    const snapshotB = loadWriteGateSnapshot(baseDirB);
+    assert.ok(
+      !snapshotB.verifiedDepthMilestones.includes("M001"),
+      "loadWriteGateSnapshot(baseDirB) must not bleed state from baseDirA",
+    );
+  });
+});

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -63,20 +63,42 @@ const QUEUE_SAFE_TOOLS = new Set([
  */
 const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
 
-const verifiedDepthMilestones = new Set<string>();
-const verifiedApprovalGates = new Set<string>();
-let activeQueuePhase = false;
+interface InMemoryWriteGateState {
+  verifiedDepthMilestones: Set<string>;
+  verifiedApprovalGates: Set<string>;
+  activeQueuePhase: boolean;
+  pendingGateId: string | null;
+}
+
+function createEmptyWriteGateState(): InMemoryWriteGateState {
+  return {
+    verifiedDepthMilestones: new Set<string>(),
+    verifiedApprovalGates: new Set<string>(),
+    activeQueuePhase: false,
+    pendingGateId: null,
+  };
+}
+
+const writeGateStatesByBasePath = new Map<string, InMemoryWriteGateState>();
+
+function writeGateStateKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function getWriteGateState(basePath: string = process.cwd()): InMemoryWriteGateState {
+  const key = writeGateStateKey(basePath);
+  let state = writeGateStatesByBasePath.get(key);
+  if (!state) {
+    state = createEmptyWriteGateState();
+    writeGateStatesByBasePath.set(key, state);
+  }
+  return state;
+}
 
 /**
- * Discussion gate enforcement state.
- *
- * When ask_user_questions is called with a recognized gate question ID,
- * we track the pending gate. Until the gate is confirmed (user selects the
- * first/recommended option), all non-read-only tool calls are blocked.
- * This mechanically prevents the model from rationalizing past failed or
- * cancelled gate questions.
+ * Discussion gate enforcement state is scoped per basePath so multiple
+ * workspaces can coexist in the same process without sharing gate state.
  */
-let pendingGateId: string | null = null;
 
 /**
  * Recognized gate question ID patterns.
@@ -119,25 +141,26 @@ function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): b
   return v !== "0" && v !== "false";
 }
 
-function writeGateSnapshotPath(basePath: string = process.cwd()): string {
+function writeGateSnapshotPath(basePath: string): string {
   return join(basePath, ".gsd", "runtime", "write-gate-state.json");
 }
 
-function currentWriteGateSnapshot(): WriteGateSnapshot {
+function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+  const state = getWriteGateState(basePath);
   return {
-    verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
-    verifiedApprovalGates: [...verifiedApprovalGates].sort(),
-    activeQueuePhase,
-    pendingGateId,
+    verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
+    verifiedApprovalGates: [...state.verifiedApprovalGates].sort(),
+    activeQueuePhase: state.activeQueuePhase,
+    pendingGateId: state.pendingGateId,
   };
 }
 
-function persistWriteGateSnapshot(basePath: string = process.cwd()): void {
+function persistWriteGateSnapshot(basePath: string): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
   mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-  writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
+  writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(basePath), null, 2), "utf-8");
   try {
     renameSync(tempPath, path);
   } catch (err: unknown) {
@@ -152,7 +175,7 @@ function persistWriteGateSnapshot(basePath: string = process.cwd()): void {
   }
 }
 
-function clearPersistedWriteGateSnapshot(basePath: string = process.cwd()): void {
+function clearPersistedWriteGateSnapshot(basePath: string): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
   try {
@@ -185,32 +208,35 @@ const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   pendingGateId: null,
 };
 
-export function loadWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
   if (!existsSync(path)) {
     // When persist mode is active and the file has been deleted, treat it as a
     // full state reset so deleting the file clears the HARD BLOCK gate.
     // In non-persist mode the file is never written, so fall back to in-memory.
     if (shouldPersistWriteGateSnapshot()) return EMPTY_SNAPSHOT;
-    return currentWriteGateSnapshot();
+    return currentWriteGateSnapshot(basePath);
   }
   try {
     return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
   } catch {
-    return currentWriteGateSnapshot();
+    return currentWriteGateSnapshot(basePath);
   }
 }
 
-export function isDepthVerified(): boolean {
-  return verifiedDepthMilestones.size > 0;
+export function isDepthVerified(basePath: string = process.cwd()): boolean {
+  return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
 
 /**
  * Check whether a specific milestone has passed depth verification.
  */
-export function isMilestoneDepthVerified(milestoneId: string | null | undefined): boolean {
+export function isMilestoneDepthVerified(
+  milestoneId: string | null | undefined,
+  basePath: string = process.cwd(),
+): boolean {
   if (!milestoneId) return false;
-  return verifiedDepthMilestones.has(milestoneId);
+  return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 
 export function isMilestoneDepthVerifiedInSnapshot(
@@ -221,39 +247,37 @@ export function isMilestoneDepthVerifiedInSnapshot(
   return snapshot.verifiedDepthMilestones.includes(milestoneId);
 }
 
-export function isQueuePhaseActive(): boolean {
-  return activeQueuePhase;
+export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
+  return getWriteGateState(basePath).activeQueuePhase;
 }
 
-export function setQueuePhaseActive(active: boolean): void {
-  activeQueuePhase = active;
-  persistWriteGateSnapshot();
+export function setQueuePhaseActive(active: boolean, basePath: string): void {
+  getWriteGateState(basePath).activeQueuePhase = active;
+  persistWriteGateSnapshot(basePath);
 }
 
-export function resetWriteGateState(): void {
-  verifiedDepthMilestones.clear();
-  verifiedApprovalGates.clear();
-  pendingGateId = null;
-  persistWriteGateSnapshot();
+export function resetWriteGateState(basePath: string): void {
+  const state = getWriteGateState(basePath);
+  state.verifiedDepthMilestones.clear();
+  state.verifiedApprovalGates.clear();
+  state.pendingGateId = null;
+  persistWriteGateSnapshot(basePath);
 }
 
-export function clearDiscussionFlowState(): void {
-  verifiedDepthMilestones.clear();
-  verifiedApprovalGates.clear();
-  activeQueuePhase = false;
-  pendingGateId = null;
-  clearPersistedWriteGateSnapshot();
+export function clearDiscussionFlowState(basePath: string): void {
+  writeGateStatesByBasePath.delete(writeGateStateKey(basePath));
+  clearPersistedWriteGateSnapshot(basePath);
 }
 
 export function markDepthVerified(milestoneId?: string | null, basePath: string = process.cwd()): void {
   if (!milestoneId) return;
-  verifiedDepthMilestones.add(milestoneId);
+  getWriteGateState(basePath).verifiedDepthMilestones.add(milestoneId);
   persistWriteGateSnapshot(basePath);
 }
 
 export function markApprovalGateVerified(gateId?: string | null, basePath: string = process.cwd()): void {
   if (!gateId) return;
-  verifiedApprovalGates.add(gateId);
+  getWriteGateState(basePath).verifiedApprovalGates.add(gateId);
   persistWriteGateSnapshot(basePath);
 }
 
@@ -292,27 +316,28 @@ function extractContextMilestoneId(inputPath: string): string | null {
 /**
  * Mark a gate as pending (called when ask_user_questions is invoked with a gate ID).
  */
-export function setPendingGate(gateId: string): void {
-  pendingGateId = gateId;
-  verifiedApprovalGates.delete(gateId);
+export function setPendingGate(gateId: string, basePath: string): void {
+  const state = getWriteGateState(basePath);
+  state.pendingGateId = gateId;
+  state.verifiedApprovalGates.delete(gateId);
   const milestoneId = extractDepthVerificationMilestoneId(gateId);
-  if (milestoneId) verifiedDepthMilestones.delete(milestoneId);
-  persistWriteGateSnapshot();
+  if (milestoneId) state.verifiedDepthMilestones.delete(milestoneId);
+  persistWriteGateSnapshot(basePath);
 }
 
 /**
  * Clear the pending gate (called when the user confirms).
  */
-export function clearPendingGate(): void {
-  pendingGateId = null;
-  persistWriteGateSnapshot();
+export function clearPendingGate(basePath: string): void {
+  getWriteGateState(basePath).pendingGateId = null;
+  persistWriteGateSnapshot(basePath);
 }
 
 /**
  * Get the currently pending gate, if any.
  */
-export function getPendingGate(): string | null {
-  return pendingGateId;
+export function getPendingGate(basePath: string = process.cwd()): string | null {
+  return getWriteGateState(basePath).pendingGateId;
 }
 
 /**

package/src/resources/extensions/gsd/db-writer.ts

@@ -8,7 +8,7 @@
 // Critical invariant: generated markdown must round-trip through
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
 
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import type { Decision, Requirement } from './types.js';
 import { resolveGsdRootFile } from './paths.js';
@@ -18,6 +18,8 @@ import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
+import type { MilestoneScope, GsdWorkspace } from './workspace.js';
+import { createWorkspace, scopeMilestone } from './workspace.js';
 
 // ─── Freeform Detection ───────────────────────────────────────────────────
 
@@ -715,28 +717,104 @@ export interface SaveArtifactOpts {
 }
 
 /**
- * Save an artifact to DB and write the corresponding markdown file to disk.
+ * Save a root-level artifact (no milestone) to DB and write to disk,
+ * routing path construction through workspace.contract.projectGsd directly.
+ * Use this instead of saveArtifactToDbByScope when milestone_id is absent.
+ */
+export async function saveArtifactToDbForWorkspace(
+  workspace: GsdWorkspace,
+  opts: SaveArtifactOpts,
+): Promise<void> {
+  try {
+    const db = await import('./gsd-db.js');
+
+    const gsdDir = workspace.contract.projectGsd;
+    const fullPath = resolve(gsdDir, opts.path);
+
+    const rel0 = relative(gsdDir, fullPath);
+    if (rel0.startsWith('..') || isAbsolute(rel0)) {
+      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbForWorkspace: path escapes .gsd/ directory: ${opts.path}`);
+    }
+
+    let contentToPersist = opts.content;
+    if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+      const activeRequirements = db.getActiveRequirements();
+      if (activeRequirements.length === 0) {
+        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbForWorkspace: REQUIREMENTS final save requires active DB-backed requirements');
+      }
+      contentToPersist = generateRequirementsMd(activeRequirements);
+    }
+
+    let skipDiskWrite = false;
+    if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
+      const existingSize = statSync(fullPath).size;
+      const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
+      if (existingSize > 0 && newSize < existingSize * 0.5) {
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbForWorkspace', path: opts.path });
+        skipDiskWrite = true;
+      }
+    }
+
+    db.insertArtifact({
+      path: opts.path,
+      artifact_type: opts.artifact_type,
+      milestone_id: null,
+      slice_id: null,
+      task_id: null,
+      full_content: contentToPersist,
+    });
+
+    if (!skipDiskWrite) {
+      try {
+        await saveFile(fullPath, contentToPersist);
+      } catch (diskErr) {
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbForWorkspace', path: opts.path, error: String((diskErr as Error).message) });
+      }
+    }
+    invalidateStateCache();
+    clearPathCache();
+    clearParseCache();
+  } catch (err) {
+    logError('manifest', 'saveArtifactToDbForWorkspace failed', { fn: 'saveArtifactToDbForWorkspace', error: String((err as Error).message) });
+    throw err;
+  }
+}
+
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk,
+ * routing all path construction through the workspace contract.
+ *
  * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
- * The full file path is computed as basePath + '.gsd/' + path.
+ * The full file path is computed as scope.workspace.contract.projectGsd + '/' + path.
  */
-export async function saveArtifactToDb(
+export async function saveArtifactToDbByScope(
+  scope: MilestoneScope,
   opts: SaveArtifactOpts,
-  basePath: string,
 ): Promise<void> {
+  // Guard: an empty milestoneId produces malformed paths (milestoneDir = join(gsd, "milestones", "")).
+  // Callers that have no milestone should use saveArtifactToDbForWorkspace instead.
+  if (!scope.milestoneId) {
+    throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: milestoneId is empty — use saveArtifactToDbForWorkspace for root artifacts`);
+  }
+
   try {
     const db = await import('./gsd-db.js');
 
+    // Use contract.projectGsd as the canonical .gsd directory — never a hand-rolled basePath join.
+    const gsdDir = scope.workspace.contract.projectGsd;
+    const fullPath = resolve(gsdDir, opts.path);
+
     // Guard against path traversal before any reads/writes
-    const gsdDir = resolve(basePath, '.gsd');
-    const fullPath = resolve(basePath, '.gsd', opts.path);
-    if (!fullPath.startsWith(gsdDir)) {
-      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+    const rel1 = relative(gsdDir, fullPath);
+    if (rel1.startsWith('..') || isAbsolute(rel1)) {
+      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: path escapes .gsd/ directory: ${opts.path}`);
     }
+
     let contentToPersist = opts.content;
     if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
       const activeRequirements = db.getActiveRequirements();
       if (activeRequirements.length === 0) {
-        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbByScope: REQUIREMENTS final save requires active DB-backed requirements');
       }
       contentToPersist = generateRequirementsMd(activeRequirements);
     }
@@ -744,16 +822,13 @@ export async function saveArtifactToDb(
     // Shrinkage guard: if the projection file already exists and the new
     // content is significantly smaller (<50%), preserve the richer file on
     // disk, but keep the DB row authoritative with the caller-provided content.
-    // The disk file is a stale projection until the next explicit render.
-    // Root canonical artifacts are exempt because their content is rendered
-    // from canonical DB state, and cleanup/consolidation is often intentionally
-    // much smaller than a malformed accumulated file.
+    // Root canonical artifacts are exempt (rendered from canonical DB state).
     let skipDiskWrite = false;
     if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
       const existingSize = statSync(fullPath).size;
       const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
       if (existingSize > 0 && newSize < existingSize * 0.5) {
-        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbByScope', path: opts.path });
         skipDiskWrite = true;
       }
     }
@@ -772,7 +847,7 @@ export async function saveArtifactToDb(
       try {
         await saveFile(fullPath, contentToPersist);
       } catch (diskErr) {
-        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String((diskErr as Error).message) });
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbByScope', path: opts.path, error: String((diskErr as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
@@ -781,7 +856,28 @@ export async function saveArtifactToDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String((err as Error).message) });
+    logError('manifest', 'saveArtifactToDbByScope failed', { fn: 'saveArtifactToDbByScope', error: String((err as Error).message) });
     throw err;
   }
 }
+
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk.
+ * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
+ * The full file path is computed as basePath + '.gsd/' + path.
+ *
+ * @deprecated Use saveArtifactToDbByScope instead, which routes through the
+ * workspace contract for canonical path resolution.
+ * TODO(C-future): remove this legacy wrapper once all callers are migrated.
+ */
+export async function saveArtifactToDb(
+  opts: SaveArtifactOpts,
+  basePath: string,
+): Promise<void> {
+  const workspace = createWorkspace(basePath);
+  const milestoneId = opts.milestone_id;
+  if (milestoneId) {
+    return saveArtifactToDbByScope(scopeMilestone(workspace, milestoneId), opts);
+  }
+  return saveArtifactToDbForWorkspace(workspace, opts);
+}