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

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 ───────────────────────────────────────────────────
 
@@ -318,23 +320,6 @@ export async function saveRequirementToDb(
            LIMIT 1`,
         )
         .get({ ':description': fields.description });
-      const previousRow: Requirement | null = existingRow
-        ? {
-            id: existingRow['id'] as string,
-            class: existingRow['class'] as string,
-            status: existingRow['status'] as string,
-            description: existingRow['description'] as string,
-            why: existingRow['why'] as string,
-            source: existingRow['source'] as string,
-            primary_owner: existingRow['primary_owner'] as string,
-            supporting_slices: existingRow['supporting_slices'] as string,
-            validation: existingRow['validation'] as string,
-            notes: existingRow['notes'] as string,
-            full_content: existingRow['full_content'] as string,
-            superseded_by: (existingRow['superseded_by'] as string) ?? null,
-          }
-        : null;
-
       const row = adapter
         .prepare('SELECT MAX(CAST(SUBSTR(id, 2) AS INTEGER)) as max_num FROM requirements')
         .get();
@@ -361,9 +346,9 @@ export async function saveRequirementToDb(
       };
 
       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();
@@ -392,17 +377,7 @@ export async function saveRequirementToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String((diskErr as Error).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 as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'REQUIREMENTS.md projection write failed; DB requirement remains committed', { fn: 'saveRequirementToDb', id, error: String((diskErr as Error).message) });
     }
     invalidateStateCache();
     clearPathCache();
@@ -538,13 +513,7 @@ export async function saveDecisionToDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String((diskErr as Error).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 as Error).message) });
-      }
-      throw diskErr;
+      logWarning('projection', 'DECISIONS.md projection write failed; DB decision remains committed', { fn: 'saveDecisionToDb', id, error: String((diskErr as Error).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
@@ -667,34 +636,7 @@ export async function updateRequirementInDb(
   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: Requirement = existing ?? {
       id,
@@ -750,11 +692,7 @@ export async function updateRequirementInDb(
     try {
       await saveFile(filePath, md);
     } catch (diskErr) {
-      logError('manifest', 'disk write failed, reverting DB row', { fn: 'updateRequirementInDb', error: String((diskErr as Error).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 as Error).message) });
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
     // Do NOT clear the artifacts table — we just wrote to it intentionally.
@@ -779,46 +717,118 @@ 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);
     }
 
-    // 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;
       }
     }
@@ -829,7 +839,7 @@ export async function saveArtifactToDb(
       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)
@@ -837,9 +847,7 @@ export async function saveArtifactToDb(
       try {
         await saveFile(fullPath, contentToPersist);
       } catch (diskErr) {
-        logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String((diskErr as Error).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 as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
@@ -848,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);
+}

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -0,0 +1,197 @@
+// 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.
+
+export type BackgroundabilityVerdict = "good" | "risky" | "no";
+
+export interface DelegationPolicyEntry {
+  /** Canonical MCP tool name (the verb_object form, e.g. `gsd_plan_slice`). */
+  toolName: string;
+  /** Workflow unit type from auto-dispatch.ts, when one exists. */
+  unitType?: string;
+  verdict: BackgroundabilityVerdict;
+  /** One-line justification grounded in the evaluation findings. */
+  rationale: string;
+  /**
+   * Constraints the caller MUST satisfy when dispatching this unit in the
+   * background. Only populated for `good` and conditional `risky` entries.
+   */
+  constraints?: string[];
+}
+
+const POLICY: Record<string, DelegationPolicyEntry> = {
+  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: Record<string, string> = {
+  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: string): string {
+  return ALIASES[name] ?? name;
+}
+
+export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {
+  return POLICY[resolveCanonical(toolName)] ?? null;
+}
+
+export function isBackgroundable(toolName: string): boolean {
+  const entry = getDelegationVerdict(toolName);
+  return entry?.verdict === "good";
+}
+
+export function listBackgroundableTools(): string[] {
+  return Object.values(POLICY)
+    .filter((entry) => entry.verdict === "good")
+    .map((entry) => entry.toolName)
+    .sort();
+}
+
+export function getVerdictByUnitType(unitType: string): DelegationPolicyEntry | null {
+  for (const entry of Object.values(POLICY)) {
+    if (entry.unitType === unitType) return entry;
+  }
+  return null;
+}
+
+/**
+ * Minimal shape of a dispatch action that the annotator needs to operate on.
+ * Matches the `dispatch` and non-dispatch variants of auto-dispatch.ts'
+ * DispatchAction without depending on it (so this module stays free of
+ * workspace-package transitive imports).
+ */
+export type AnnotatableDispatchAction =
+  | { action: "dispatch"; unitType: string; backgroundable?: boolean; [k: string]: unknown }
+  | { action: "stop"; [k: string]: unknown }
+  | { action: "skip"; [k: string]: unknown };
+
+/**
+ * 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<T extends AnnotatableDispatchAction>(action: T): T {
+  if (action.action !== "dispatch") return action;
+  const verdict = getVerdictByUnitType(action.unitType);
+  action.backgroundable = verdict?.verdict === "good";
+  return action;
+}

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -54,21 +54,16 @@ export function getPriorSliceCompletionBlocker(
     // 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: string | null = null;
-      try { summaryContent = readFileSync(summaryPath, "utf-8"); } catch { /* ignore */ }
-      if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
+      try { summaryContent = summaryPath ? readFileSync(summaryPath, "utf-8") : null; } catch { /* ignore */ }
+      if (summaryContent && classifyMilestoneSummaryContent(summaryContent) !== "failure") {
         continue;
       }
     }

package/src/resources/extensions/gsd/doctor-engine-checks.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 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";
@@ -13,7 +13,7 @@ export async function checkEngineHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
 ): Promise<void> {
-  const dbPath = join(basePath, ".gsd", "gsd.db");
+  const dbPath = resolveGsdPathContract(basePath).projectDb;
 
   if (!isDbAvailable() && existsSync(dbPath)) {
     issues.push({