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

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -15,7 +15,7 @@ import { appendOverride, appendKnowledge } from "./files.js";
 import { formatDoctorIssuesForPrompt, formatDoctorReport, formatDoctorReportJson, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } from "./doctor.js";
 import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
@@ -169,7 +169,7 @@ export async function handleCapture(args, ctx) {
         ctx.ui.notify('Usage: /gsd capture "your thought here"', "warning");
         return;
     }
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     // Ensure .gsd/ exists — capture should work even without a milestone
     const gsdDir = gsdRoot(basePath);
     if (!existsSync(gsdDir)) {
@@ -220,7 +220,7 @@ export async function handleTriage(ctx, pi, basePath) {
     }, { triggerTurn: true });
 }
 export async function handleSteer(change, ctx, pi) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const state = await deriveState(basePath);
     const mid = state.activeMilestone?.id ?? "none";
     const sid = state.activeSlice?.id ?? "none";
@@ -284,7 +284,7 @@ export async function handleKnowledge(args, ctx) {
         return;
     }
     const type = typeArg;
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const state = await deriveState(basePath);
     const scope = state.activeMilestone?.id
         ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
@@ -310,7 +310,7 @@ Examples:
         return;
     }
     const [hookName, unitType, unitId] = parts;
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     // Import the hook trigger function
     const { triggerHookManually, formatHookStatus, getHookStatus } = await import("./post-unit-hooks.js");
     const { dispatchHookUnit } = await import("./auto.js");

package/dist/resources/extensions/gsd/commands-logs.js

@@ -13,7 +13,7 @@ import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "nod
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { loadJsonFileOrNull } from "./json-persistence.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Helpers ────────────────────────────────────────────────────────────────
 function activityDir(basePath) {
     return join(gsdRoot(basePath), "activity");
@@ -227,7 +227,7 @@ function summarizeDebugLog(filePath) {
 }
 // ─── Main Handler ───────────────────────────────────────────────────────────
 export async function handleLogs(args, ctx) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const parts = args.trim().split(/\s+/).filter(Boolean);
     const subCmd = parts[0] ?? "";
     // /gsd logs clear

package/dist/resources/extensions/gsd/commands-scan.js

@@ -16,7 +16,7 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 export const DEFAULT_FOCUS = "tech+arch";
 export const VALID_FOCUS_AREAS = ["tech", "arch", "quality", "concerns", "tech+arch"];
@@ -67,7 +67,7 @@ export function checkExistingDocuments(paths) {
 }
 // ─── Command handler ──────────────────────────────────────────────────────────
 export async function handleScan(args, ctx, pi) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const { focus } = parseScanArgs(args);
     const outputDir = join(basePath, ".gsd", "codebase");
     const outputPaths = buildScanOutputPaths(focus, basePath);

package/dist/resources/extensions/gsd/commands-ship.js

@@ -13,7 +13,7 @@ import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenC
 import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -176,7 +176,7 @@ function generatePRContent(basePath, milestoneId, milestoneTitle) {
     return { title, body: sections.join("\n") };
 }
 export async function handleShip(args, ctx, _pi) {
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const dryRun = args.includes("--dry-run");
     const draft = args.includes("--draft");
     const force = args.includes("--force");

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -13,7 +13,7 @@ import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin } from "./workflow-plugins.js";
-import { projectRoot } from "./commands/context.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -143,7 +143,7 @@ export async function handleStart(args, ctx, pi) {
     // ─── Resume detection ───────────────────────────────────────────────────
     // /gsd start --resume or /gsd start resume → resume in-progress workflow
     if (trimmed === "--resume" || trimmed === "resume") {
-        const basePath = projectRoot();
+        const basePath = currentDirectoryRoot();
         const inProgress = findInProgressWorkflows(basePath);
         if (inProgress.length === 0) {
             ctx.ui.notify("No in-progress workflows found.", "info");
@@ -182,7 +182,7 @@ export async function handleStart(args, ctx, pi) {
     }
     // Show in-progress workflows when /gsd start is called with no args
     if (!trimmed) {
-        const basePath = projectRoot();
+        const basePath = currentDirectoryRoot();
         const inProgress = findInProgressWorkflows(basePath);
         if (inProgress.length > 0) {
             const wf = inProgress[0];
@@ -257,7 +257,7 @@ export async function handleStart(args, ctx, pi) {
     // ─── Resolved template ───────────────────────────────────────────────────
     const templateId = match.id;
     const template = match.template;
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const date = new Date().toISOString().split("T")[0];
     // Load the workflow template content — prefer a project/global plugin
     // override if one exists (same name, .md format).
@@ -437,7 +437,7 @@ export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
         return;
     }
     const templateId = plugin.name;
-    const basePath = projectRoot();
+    const basePath = currentDirectoryRoot();
     const date = new Date().toISOString().split("T")[0];
     let workflowContent;
     try {

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
@@ -273,22 +274,6 @@ export async function saveRequirementToDb(fields, basePath) {
            ORDER BY id
            LIMIT 1`)
                 .get({ ':description': fields.description });
-            const previousRow = existingRow
-                ? {
-                    id: existingRow['id'],
-                    class: existingRow['class'],
-                    status: existingRow['status'],
-                    description: existingRow['description'],
-                    why: existingRow['why'],
-                    source: existingRow['source'],
-                    primary_owner: existingRow['primary_owner'],
-                    supporting_slices: existingRow['supporting_slices'],
-                    validation: existingRow['validation'],
-                    notes: existingRow['notes'],
-                    full_content: existingRow['full_content'],
-                    superseded_by: existingRow['superseded_by'] ?? null,
-                }
-                : null;
             const row = adapter
                 .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
                 .get();
@@ -313,9 +298,9 @@ export async function saveRequirementToDb(fields, basePath) {
                 superseded_by: existingRow?.['superseded_by'] ?? null,
             };
             db.upsertRequirement(requirement);
-            return { id: nextId, isNew: !existingRow, previousRow };
+            return { id: nextId };
         });
-        const { id, isNew, previousRow } = txResult;
+        const { id } = txResult;
         // Fetch all requirements for full file regeneration
         const adapter = db._getAdapter();
         let allRequirements = [];
@@ -343,19 +328,7 @@ export async function saveRequirementToDb(fields, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String(diskErr.message) });
-            try {
-                if (isNew) {
-                    db.deleteRequirementById(id);
-                }
-                else if (previousRow) {
-                    db.upsertRequirement(previousRow);
-                }
-            }
-            catch (rollbackErr) {
-                logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String(rollbackErr.message) });
-            }
-            throw diskErr;
+            logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String(diskErr.message) });
         }
         invalidateStateCache();
         clearPathCache();
@@ -463,14 +436,7 @@ export async function saveDecisionToDb(fields, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String(diskErr.message) });
-            try {
-                db.deleteDecisionById(id);
-            }
-            catch (rollbackErr) {
-                logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String(rollbackErr.message) });
-            }
-            throw diskErr;
+            logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String(diskErr.message) });
         }
         // #2661: When a decision defers a slice, update the slice status in the DB
         // so the dispatcher skips it. Without this, STATE.md and DECISIONS.md are
@@ -584,34 +550,7 @@ export function extractDeferredSliceRef(fields) {
 export async function updateRequirementInDb(id, updates, basePath) {
     try {
         const db = await import('./gsd-db.js');
-        let existing = db.getRequirementById(id);
-        // If requirement doesn't exist in DB, seed the entire requirements table
-        // from REQUIREMENTS.md first (#3346). This handles the standard workflow
-        // where requirements are authored in markdown during discussion but never
-        // imported into the database — making gsd_requirement_update always fail
-        // with "not_found" at milestone completion.
-        if (!existing) {
-            const reqFilePath = resolveGsdRootFile(basePath, 'REQUIREMENTS');
-            try {
-                const content = readFileSync(reqFilePath, 'utf-8');
-                const { parseRequirementsSections } = await import('./md-importer.js');
-                const parsed = parseRequirementsSections(content);
-                if (parsed.length > 0) {
-                    logWarning('manifest', `Seeding ${parsed.length} requirements from REQUIREMENTS.md into DB (first update triggers import)`, { fn: 'updateRequirementInDb' });
-                    for (const req of parsed) {
-                        // Only seed if not already in DB (avoid overwriting concurrent inserts)
-                        if (!db.getRequirementById(req.id)) {
-                            db.upsertRequirement(req);
-                        }
-                    }
-                    // Re-check after seeding
-                    existing = db.getRequirementById(id);
-                }
-            }
-            catch {
-                // REQUIREMENTS.md missing or unparseable — fall through to skeleton
-            }
-        }
+        const existing = db.getRequirementById(id);
         const base = existing ?? {
             id,
             class: '',
@@ -662,11 +601,7 @@ export async function updateRequirementInDb(id, updates, basePath) {
             await saveFile(filePath, md);
         }
         catch (diskErr) {
-            logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String(diskErr.message) });
-            if (existing) {
-                db.upsertRequirement(existing);
-            }
-            throw diskErr;
+            logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement update remains committed', { fn: 'updateRequirementInDb', id, error: String(diskErr.message) });
         }
         // Invalidate file-read caches so deriveState() sees the updated markdown.
         // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -680,41 +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 file already exists and the new content is
-        // significantly smaller (<50%), preserve the richer file on disk and
-        // store its content in the DB instead of the abbreviated version. 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.
-        let dbContent = contentToPersist;
+        // 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.
+        // 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('manifest', `new content (${newSize}B) is <50% of existing file (${existingSize}B), preserving disk file`, { fn: 'saveArtifactToDb', path: opts.path });
-                dbContent = readFileSync(fullPath, 'utf-8');
+                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;
             }
         }
@@ -724,7 +720,7 @@ export async function saveArtifactToDb(opts, basePath) {
             milestone_id: opts.milestone_id ?? null,
             slice_id: opts.slice_id ?? null,
             task_id: opts.task_id ?? null,
-            full_content: dbContent,
+            full_content: contentToPersist,
         });
         // Write the file to disk (only if we're not preserving a richer existing file)
         if (!skipDiskWrite) {
@@ -732,9 +728,7 @@ export async function saveArtifactToDb(opts, basePath) {
                 await saveFile(fullPath, contentToPersist);
             }
             catch (diskErr) {
-                logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String(diskErr.message) });
-                db.deleteArtifactByPath(opts.path);
-                throw diskErr;
+                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.
@@ -744,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;
+}

package/dist/resources/extensions/gsd/dispatch-guard.js

@@ -45,25 +45,21 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
         // completion, which is wrong when the SUMMARY is a failure-path report
         // (verification FAILED, blocker placeholder, etc.). Resolve as follows:
         //   1. When DB is available and status is closed → skip (authoritative).
-        //   2. When SUMMARY exists but looks like a failure/blocker report →
-        //      do not short-circuit; fall through to the slice-level check so
-        //      the guard can still block dependents of an active milestone.
-        //   3. Otherwise (SUMMARY without failure markers) → skip. Preserves
-        //      the #1716 contract where a completed milestone with unchecked
-        //      remediation slices is still treated as done.
-        const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
+        //   2. When DB is unavailable, legacy SUMMARY.md fallback may skip.
+        //      DB-backed projects must not treat SUMMARY.md as authoritative.
         if (isDbAvailable()) {
             const milestoneRow = getMilestone(mid);
             if (milestoneRow && isClosedStatus(milestoneRow.status))
                 continue;
         }
-        if (summaryPath) {
+        else {
+            const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
             let summaryContent = null;
             try {
-                summaryContent = readFileSync(summaryPath, "utf-8");
+                summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null;
             }
             catch { /* ignore */ }
-            if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+            if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
                 continue;
             }
         }

package/dist/resources/extensions/gsd/doctor-engine-checks.js

@@ -1,12 +1,12 @@
 import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
 import { renderAllProjections } from "./workflow-projections.js";
 export async function checkEngineHealth(basePath, issues, fixesApplied) {
-    const dbPath = join(basePath, ".gsd", "gsd.db");
+    const dbPath = resolveGsdPathContract(basePath).projectDb;
     if (!isDbAvailable() && existsSync(dbPath)) {
         issues.push({
             severity: "warning",