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

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -60,7 +60,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const { initHealthWidget } = await import("../health-widget.js");
             initHealthWidget(ctx);
         }
-        resetWriteGateState();
+        resetWriteGateState(process.cwd());
         resetToolCallLoopGuard();
         approvalQuestionAbortInFlight = false;
         await resetAskUserQuestionsTurnCache();
@@ -109,10 +109,10 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("session_switch", async (_event, ctx) => {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
-        resetWriteGateState();
+        resetWriteGateState(process.cwd());
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
-        clearDiscussionFlowState();
+        clearDiscussionFlowState(process.cwd());
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree. The worktree
@@ -137,13 +137,14 @@ export function registerHooks(pi, ecosystemHandlers) {
         // Wait for ecosystem loader to finish (no-op after first turn).
         const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
+        const beforeAgentBasePath = process.cwd();
         const pendingApprovalGate = getPendingGate();
         if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
-            markApprovalGateVerified(pendingApprovalGate);
+            markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
             const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
             if (milestoneId)
-                markDepthVerified(milestoneId);
-            clearPendingGate();
+                markDepthVerified(milestoneId, beforeAgentBasePath);
+            clearPendingGate(beforeAgentBasePath);
         }
         // GSD's own context injection (existing behavior — unchanged).
         const { buildBeforeAgentStartResult } = await import("./system-context.js");
@@ -318,7 +319,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId)
-            setPendingGate(gateId);
+            setPendingGate(gateId, process.cwd());
         approvalQuestionAbortInFlight = true;
         ctx.ui.notify(`${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
         // The pending gate set above blocks subsequent non-read-only tool calls
@@ -360,7 +361,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const questions = event.input?.questions ?? [];
             const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
             if (typeof questionId === "string") {
-                setPendingGate(questionId);
+                setPendingGate(questionId, discussionBasePath);
             }
         }
         // ── Discussion gate enforcement: block tool calls while gate is pending ──
@@ -501,7 +502,8 @@ export function registerHooks(pi, ecosystemHandlers) {
         const toolName = canonicalToolName(event.toolName);
         if (toolName !== "ask_user_questions")
             return;
-        const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+        const basePath = process.cwd();
+        const milestoneId = await getDiscussionMilestoneIdFor(basePath);
         const queueActive = isQueuePhaseActive();
         const details = event.details;
         // ── Discussion gate enforcement: handle gate question responses ──
@@ -533,11 +535,11 @@ export function registerHooks(pi, ecosystemHandlers) {
                 if (pendingQuestion) {
                     const answer = details.response?.answers?.[currentPendingGate];
                     if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
-                        markApprovalGateVerified(currentPendingGate);
+                        markApprovalGateVerified(currentPendingGate, basePath);
                         const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
                         if (milestoneIdFromGate)
-                            markDepthVerified(milestoneIdFromGate);
-                        clearPendingGate();
+                            markDepthVerified(milestoneIdFromGate, basePath);
+                        clearPendingGate(basePath);
                     }
                 }
             }
@@ -553,9 +555,9 @@ export function registerHooks(pi, ecosystemHandlers) {
                 if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
                     if (currentPendingGate && question.id !== currentPendingGate)
                         break;
-                    markApprovalGateVerified(question.id);
-                    markDepthVerified(inferredMilestoneId);
-                    clearPendingGate();
+                    markApprovalGateVerified(question.id, basePath);
+                    markDepthVerified(inferredMilestoneId, basePath);
+                    clearPendingGate(basePath);
                 }
                 break;
             }
@@ -564,7 +566,6 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         if (!milestoneId)
             return;
-        const basePath = process.cwd();
         const milestoneDir = resolveMilestonePath(basePath, milestoneId);
         if (!milestoneDir)
             return;

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -55,19 +55,31 @@ const QUEUE_SAFE_TOOLS = new Set([
  *   true / false        — shell no-ops / test exit codes
  */
 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();
-const verifiedApprovalGates = new Set();
-let activeQueuePhase = false;
+function createEmptyWriteGateState() {
+    return {
+        verifiedDepthMilestones: new Set(),
+        verifiedApprovalGates: new Set(),
+        activeQueuePhase: false,
+        pendingGateId: null,
+    };
+}
+const writeGateStatesByBasePath = new Map();
+function writeGateStateKey(basePath) {
+    return resolve(basePath);
+}
+function getWriteGateState(basePath = process.cwd()) {
+    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 = null;
 /**
  * Recognized gate question ID patterns.
  * These appear in discuss.md (depth/requirements/roadmap).
@@ -99,24 +111,25 @@ function shouldPersistWriteGateSnapshot(env = process.env) {
     const v = env.GSD_PERSIST_WRITE_GATE_STATE;
     return v !== "0" && v !== "false";
 }
-function writeGateSnapshotPath(basePath = process.cwd()) {
+function writeGateSnapshotPath(basePath) {
     return join(basePath, ".gsd", "runtime", "write-gate-state.json");
 }
-function currentWriteGateSnapshot() {
+function currentWriteGateSnapshot(basePath = process.cwd()) {
+    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 = process.cwd()) {
+function persistWriteGateSnapshot(basePath) {
     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);
     }
@@ -132,7 +145,7 @@ function persistWriteGateSnapshot(basePath = process.cwd()) {
         }
     }
 }
-function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
+function clearPersistedWriteGateSnapshot(basePath) {
     if (!shouldPersistWriteGateSnapshot())
         return;
     const path = writeGateSnapshotPath(basePath);
@@ -164,7 +177,7 @@ const EMPTY_SNAPSHOT = {
     activeQueuePhase: false,
     pendingGateId: null,
 };
-export function loadWriteGateSnapshot(basePath = process.cwd()) {
+export function loadWriteGateSnapshot(basePath) {
     const path = writeGateSnapshotPath(basePath);
     if (!existsSync(path)) {
         // When persist mode is active and the file has been deleted, treat it as a
@@ -172,61 +185,59 @@ export function loadWriteGateSnapshot(basePath = process.cwd()) {
         // 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() {
-    return verifiedDepthMilestones.size > 0;
+export function isDepthVerified(basePath = process.cwd()) {
+    return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
 /**
  * Check whether a specific milestone has passed depth verification.
  */
-export function isMilestoneDepthVerified(milestoneId) {
+export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return false;
-    return verifiedDepthMilestones.has(milestoneId);
+    return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
     if (!milestoneId)
         return false;
     return snapshot.verifiedDepthMilestones.includes(milestoneId);
 }
-export function isQueuePhaseActive() {
-    return activeQueuePhase;
+export function isQueuePhaseActive(basePath = process.cwd()) {
+    return getWriteGateState(basePath).activeQueuePhase;
 }
-export function setQueuePhaseActive(active) {
-    activeQueuePhase = active;
-    persistWriteGateSnapshot();
+export function setQueuePhaseActive(active, basePath) {
+    getWriteGateState(basePath).activeQueuePhase = active;
+    persistWriteGateSnapshot(basePath);
 }
-export function resetWriteGateState() {
-    verifiedDepthMilestones.clear();
-    verifiedApprovalGates.clear();
-    pendingGateId = null;
-    persistWriteGateSnapshot();
+export function resetWriteGateState(basePath) {
+    const state = getWriteGateState(basePath);
+    state.verifiedDepthMilestones.clear();
+    state.verifiedApprovalGates.clear();
+    state.pendingGateId = null;
+    persistWriteGateSnapshot(basePath);
 }
-export function clearDiscussionFlowState() {
-    verifiedDepthMilestones.clear();
-    verifiedApprovalGates.clear();
-    activeQueuePhase = false;
-    pendingGateId = null;
-    clearPersistedWriteGateSnapshot();
+export function clearDiscussionFlowState(basePath) {
+    writeGateStatesByBasePath.delete(writeGateStateKey(basePath));
+    clearPersistedWriteGateSnapshot(basePath);
 }
 export function markDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return;
-    verifiedDepthMilestones.add(milestoneId);
+    getWriteGateState(basePath).verifiedDepthMilestones.add(milestoneId);
     persistWriteGateSnapshot(basePath);
 }
 export function markApprovalGateVerified(gateId, basePath = process.cwd()) {
     if (!gateId)
         return;
-    verifiedApprovalGates.add(gateId);
+    getWriteGateState(basePath).verifiedApprovalGates.add(gateId);
     persistWriteGateSnapshot(basePath);
 }
 export function isApprovalGateVerifiedInSnapshot(snapshot, gateId) {
@@ -258,26 +269,27 @@ function extractContextMilestoneId(inputPath) {
 /**
  * Mark a gate as pending (called when ask_user_questions is invoked with a gate ID).
  */
-export function setPendingGate(gateId) {
-    pendingGateId = gateId;
-    verifiedApprovalGates.delete(gateId);
+export function setPendingGate(gateId, basePath) {
+    const state = getWriteGateState(basePath);
+    state.pendingGateId = gateId;
+    state.verifiedApprovalGates.delete(gateId);
     const milestoneId = extractDepthVerificationMilestoneId(gateId);
     if (milestoneId)
-        verifiedDepthMilestones.delete(milestoneId);
-    persistWriteGateSnapshot();
+        state.verifiedDepthMilestones.delete(milestoneId);
+    persistWriteGateSnapshot(basePath);
 }
 /**
  * Clear the pending gate (called when the user confirms).
  */
-export function clearPendingGate() {
-    pendingGateId = null;
-    persistWriteGateSnapshot();
+export function clearPendingGate(basePath) {
+    getWriteGateState(basePath).pendingGateId = null;
+    persistWriteGateSnapshot(basePath);
 }
 /**
  * Get the currently pending gate, if any.
  */
-export function getPendingGate() {
-    return pendingGateId;
+export function getPendingGate(basePath = process.cwd()) {
+    return getWriteGateState(basePath).pendingGateId;
 }
 /**
  * Check whether a tool call should be blocked because a discussion gate

package/dist/resources/extensions/gsd/db-writer.js

@@ -7,7 +7,7 @@
 //
 // Critical invariant: generated markdown must round-trip through
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
-import { resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { resolveGsdRootFile } from './paths.js';
 import { saveFile } from './files.js';
@@ -16,6 +16,7 @@ import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
+import { createWorkspace, scopeMilestone } from './workspace.js';
 // ─── Freeform Detection ───────────────────────────────────────────────────
 /**
  * Detect whether a DECISIONS.md file is in canonical table format
@@ -614,40 +615,102 @@ export async function updateRequirementInDb(id, updates, basePath) {
     }
 }
 /**
- * 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, opts) {
+    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.message) });
+            }
+        }
+        invalidateStateCache();
+        clearPathCache();
+        clearParseCache();
+    }
+    catch (err) {
+        logError('manifest', 'saveArtifactToDbForWorkspace failed', { fn: 'saveArtifactToDbForWorkspace', error: String(err.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(opts, basePath) {
+export async function saveArtifactToDbByScope(scope, opts) {
+    // 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);
         }
         // 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;
             }
         }
@@ -665,7 +728,7 @@ export async function saveArtifactToDb(opts, basePath) {
                 await saveFile(fullPath, contentToPersist);
             }
             catch (diskErr) {
-                logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String(diskErr.message) });
+                logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbByScope', path: opts.path, error: String(diskErr.message) });
             }
         }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
@@ -675,7 +738,24 @@ export async function saveArtifactToDb(opts, basePath) {
         clearParseCache();
     }
     catch (err) {
-        logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String(err.message) });
+        logError('manifest', 'saveArtifactToDbByScope failed', { fn: 'saveArtifactToDbByScope', error: String(err.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, basePath) {
+    const workspace = createWorkspace(basePath);
+    const milestoneId = opts.milestone_id;
+    if (milestoneId) {
+        return saveArtifactToDbByScope(scopeMilestone(workspace, milestoneId), opts);
+    }
+    return saveArtifactToDbForWorkspace(workspace, opts);
+}

package/dist/resources/extensions/gsd/delegation-policy.js

@@ -0,0 +1,155 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+const POLICY = {
+    gsd_plan_slice: {
+        toolName: "gsd_plan_slice",
+        unitType: "plan-slice",
+        verdict: "good",
+        rationale: "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+        constraints: [
+            "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+            "Foreground must not derive state for that slice while the transaction is in flight.",
+            "Foreground must await background completion before any tool reads the planned tasks/gates.",
+        ],
+    },
+    gsd_execute: {
+        toolName: "gsd_execute",
+        // No `unitType` set on purpose — the underlying tool is safe, but the
+        // unit-level orchestrations that invoke it (`execute-task`,
+        // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+        // harness work whose safety is a separate analysis. Default-deny those
+        // units until that analysis is recorded; adding `unitType` here would
+        // promote them silently.
+        verdict: "good",
+        rationale: "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+    },
+    gsd_validate_milestone: {
+        toolName: "gsd_validate_milestone",
+        unitType: "validate-milestone",
+        verdict: "good",
+        rationale: "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+    },
+    gsd_reassess_roadmap: {
+        toolName: "gsd_reassess_roadmap",
+        unitType: "reassess-roadmap",
+        verdict: "good",
+        rationale: "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+    },
+    gsd_doctor: {
+        toolName: "gsd_doctor",
+        verdict: "risky",
+        rationale: "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+        constraints: [
+            "Background only with fix=false (diagnostic-only).",
+            "Apply fixes synchronously, only when no foreground unit is dispatched.",
+        ],
+    },
+    gsd_plan_milestone: {
+        toolName: "gsd_plan_milestone",
+        unitType: "plan-milestone",
+        verdict: "risky",
+        rationale: "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+    },
+    gsd_replan_slice: {
+        toolName: "gsd_replan_slice",
+        unitType: "replan-slice",
+        verdict: "risky",
+        rationale: "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+    },
+    gsd_plan_task: {
+        toolName: "gsd_plan_task",
+        verdict: "no",
+        rationale: "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+    },
+};
+// Alias map keyed on the secondary name; resolves to the canonical entry above.
+// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
+// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
+const ALIASES = {
+    gsd_milestone_validate: "gsd_validate_milestone",
+    gsd_roadmap_reassess: "gsd_reassess_roadmap",
+    gsd_slice_replan: "gsd_replan_slice",
+    gsd_task_plan: "gsd_plan_task",
+};
+function resolveCanonical(name) {
+    return ALIASES[name] ?? name;
+}
+export function getDelegationVerdict(toolName) {
+    return POLICY[resolveCanonical(toolName)] ?? null;
+}
+export function isBackgroundable(toolName) {
+    const entry = getDelegationVerdict(toolName);
+    return entry?.verdict === "good";
+}
+export function listBackgroundableTools() {
+    return Object.values(POLICY)
+        .filter((entry) => entry.verdict === "good")
+        .map((entry) => entry.toolName)
+        .sort();
+}
+export function getVerdictByUnitType(unitType) {
+    for (const entry of Object.values(POLICY)) {
+        if (entry.unitType === unitType)
+            return entry;
+    }
+    return null;
+}
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable(action) {
+    if (action.action !== "dispatch")
+        return action;
+    const verdict = getVerdictByUnitType(action.unitType);
+    action.backgroundable = verdict?.verdict === "good";
+    return action;
+}