@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.b1abb545

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

@@ -9,6 +9,7 @@ import { deriveState } from "./state.js";
 import { gsdProjectionRoot, gsdRoot } from "./paths.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { logWarning } from "./workflow-logger.js";
+import { backupWorkflowDatabaseSnapshot, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 export async function handleCleanupBranches(ctx, basePath) {
     let branches;
     try {
@@ -511,7 +512,7 @@ async function confirmRecover(ctx, args, markdown, beforeDb, dataLoss) {
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx, basePath, args = "") {
-    const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction, backupDatabaseSnapshot } = await import("./gsd-db.js");
+    const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
     const { migrateHierarchyToDb } = await import("./md-importer.js");
     const { invalidateStateCache } = await import("./state.js");
     const { countDbHierarchy, countMarkdownHierarchy, recoverWouldDeleteDbRows } = await import("./migration-auto-check.js");
@@ -531,7 +532,7 @@ export async function handleRecover(ctx, basePath, args = "") {
         return;
     try {
         // 0. Snapshot the DB before the destructive clear so recover is reversible.
-        const backupPath = backupDatabaseSnapshot("pre-recover");
+        const backupPath = backupWorkflowDatabaseSnapshot("pre-recover");
         // 1. Delete + re-populate inside a single transaction for atomicity.
         //    clearEngineHierarchy() uses transaction() internally but transaction()
         //    is re-entrant, so wrapping in dbTransaction() keeps the whole
@@ -655,6 +656,49 @@ function parseRebuildTarget(args) {
         return "database";
     return "usage";
 }
+/**
+ * Re-render markdown planning projections from the authoritative DB.
+ *
+ * Quarantines open-unit SUMMARY files that contradict DB status before
+ * rendering. Safe to call after milestone merge/transition or during startup
+ * self-heal when the DB holds rows markdown lacks.
+ */
+export async function rebuildMarkdownProjectionsFromDb(basePath) {
+    const { deleteArtifactByPath } = await import("./gsd-db.js");
+    const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
+    const { renderAllFromDb } = await import("./markdown-renderer.js");
+    const { invalidateStateCache } = await import("./state.js");
+    invalidateStateCache();
+    refreshWorkflowDatabaseFromDisk();
+    const state = await deriveState(basePath);
+    const drifts = detectArtifactDbDrift(state, { basePath, state });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const quarantined = [];
+    const seen = new Set();
+    for (const drift of drifts) {
+        if (drift.kind !== "artifact-db-status-divergence")
+            continue;
+        if (drift.artifactType !== "SUMMARY" || !drift.artifactPath)
+            continue;
+        const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
+        if (seen.has(absPath) || !existsSync(absPath))
+            continue;
+        seen.add(absPath);
+        const artifactDbPath = artifactPathForDb(basePath, absPath);
+        const target = quarantineProjectionFile(basePath, absPath, stamp);
+        deleteArtifactByPath(artifactDbPath);
+        quarantined.push(target);
+    }
+    const rendered = await renderAllFromDb(basePath);
+    invalidateStateCache();
+    return {
+        rendered: rendered.rendered,
+        skipped: rendered.skipped,
+        errors: rendered.errors,
+        quarantined: quarantined.length,
+        quarantinedPaths: quarantined,
+    };
+}
 /**
  * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
  *
@@ -663,10 +707,7 @@ function parseRebuildTarget(args) {
  * under `.gsd/quarantine/projections/` before DB projections are rendered.
  */
 export async function handleRebuild(ctx, basePath, args = "") {
-    const { isDbAvailable: dbAvailable, deleteArtifactByPath } = await import("./gsd-db.js");
-    const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
-    const { renderAllFromDb } = await import("./markdown-renderer.js");
-    const { invalidateStateCache } = await import("./state.js");
+    const { isDbAvailable: dbAvailable } = await import("./gsd-db.js");
     const target = parseRebuildTarget(args);
     if (target === "usage") {
         ctx.ui.notify([
@@ -690,53 +731,32 @@ export async function handleRebuild(ctx, basePath, args = "") {
         return;
     }
     try {
-        invalidateStateCache();
-        const state = await deriveState(basePath);
-        const drifts = detectArtifactDbDrift(state, { basePath, state });
-        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const quarantined = [];
-        const seen = new Set();
-        for (const drift of drifts) {
-            if (drift.kind !== "artifact-db-status-divergence")
-                continue;
-            if (drift.artifactType !== "SUMMARY" || !drift.artifactPath)
-                continue;
-            const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
-            if (seen.has(absPath) || !existsSync(absPath))
-                continue;
-            seen.add(absPath);
-            const artifactDbPath = artifactPathForDb(basePath, absPath);
-            const target = quarantineProjectionFile(basePath, absPath, stamp);
-            deleteArtifactByPath(artifactDbPath);
-            quarantined.push(target);
-        }
-        const rendered = await renderAllFromDb(basePath);
-        invalidateStateCache();
+        const result = await rebuildMarkdownProjectionsFromDb(basePath);
         const lines = [
             "gsd rebuild markdown: rebuilt markdown projections from the canonical DB",
-            `  Rendered:    ${rendered.rendered}`,
-            `  Skipped:     ${rendered.skipped}`,
-            `  Quarantined: ${quarantined.length}`,
+            `  Rendered:    ${result.rendered}`,
+            `  Skipped:     ${result.skipped}`,
+            `  Quarantined: ${result.quarantined}`,
         ];
-        if (rendered.errors.length > 0) {
-            lines.push(`  Errors:      ${rendered.errors.length}`);
-            for (const err of rendered.errors.slice(0, 5)) {
+        if (result.errors.length > 0) {
+            lines.push(`  Errors:      ${result.errors.length}`);
+            for (const err of result.errors.slice(0, 5)) {
                 lines.push(`    - ${err}`);
             }
-            if (rendered.errors.length > 5) {
-                lines.push(`    - ${rendered.errors.length - 5} more`);
+            if (result.errors.length > 5) {
+                lines.push(`    - ${result.errors.length - 5} more`);
             }
         }
-        if (quarantined.length > 0) {
+        if (result.quarantined > 0) {
             lines.push("", "  Quarantine:");
-            for (const target of quarantined.slice(0, 5)) {
+            for (const target of result.quarantinedPaths.slice(0, 5)) {
                 lines.push(`    - ${target}`);
             }
-            if (quarantined.length > 5) {
-                lines.push(`    - ${quarantined.length - 5} more`);
+            if (result.quarantined > 5) {
+                lines.push(`    - ${result.quarantined - 5} more`);
             }
         }
-        ctx.ui.notify(lines.join("\n"), rendered.errors.length > 0 ? "warning" : "success");
+        ctx.ui.notify(lines.join("\n"), result.errors.length > 0 ? "warning" : "success");
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

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

@@ -10,7 +10,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
-import { buildPrEvidence } from "./pr-evidence.js";
+import { buildPullRequestEvidence } from "./pull-request-process.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -140,7 +140,7 @@ function generatePRContent(basePath, milestoneId, milestoneTitle) {
             metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
         }
     }
-    return buildPrEvidence({
+    return buildPullRequestEvidence({
         milestoneId,
         milestoneTitle,
         changeType: "feat",

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

@@ -1,11 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Handles manual milestone validation verdict overrides.
 import { loadFile } from "./files.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { gsdProjectionRoot, resolveMilestoneFile } from "./paths.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { join } from "node:path";
 import { deriveState } from "./state.js";
 import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getLatestAssessmentByScope } from "./gsd-db.js";
+import { checkpointWorkflowDatabase } from "./db-workspace.js";
 import { VALIDATION_VERDICTS, extractVerdict, isValidMilestoneVerdict, } from "./verdict-parser.js";
 const USAGE = 'Usage: /gsd verdict <pass|needs-attention|needs-remediation> [--milestone Mxxx] [--rationale "..."]';
 function tokenize(raw) {
@@ -86,8 +89,14 @@ export function parseValidationFile(content) {
     };
 }
 async function loadExistingValidation(basePath, milestoneId) {
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const canonicalValidationPath = join(gsdProjectionRoot(canonicalBase), "milestones", milestoneId, `${milestoneId}-VALIDATION.md`);
+    const canonicalContent = await loadFile(canonicalValidationPath);
+    if (canonicalContent) {
+        return { content: canonicalContent, source: canonicalValidationPath };
+    }
     const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
-    if (validationPath) {
+    if (validationPath && validationPath !== canonicalValidationPath) {
         const content = await loadFile(validationPath);
         if (content)
             return { content, source: validationPath };
@@ -157,6 +166,7 @@ export async function handleVerdict(rawArgs, ctx, basePath) {
         ctx.ui.notify(msg, "error");
         return;
     }
+    checkpointWorkflowDatabase();
     const prevVerdict = current.verdict ?? "unknown";
     const effectiveVerdict = extractEffectiveVerdict(result.details, parsed.verdict);
     if (effectiveVerdict !== parsed.verdict) {

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

@@ -0,0 +1,103 @@
+// Project/App: gsd-pi
+// File Purpose: Workspace-facing Interface for opening and maintaining the workflow database.
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { backupDatabaseSnapshot, checkpointDatabase, closeAllDatabases, closeDatabase, closeDatabaseByWorkspace, getDbPath, getDbStatus, getDbProvider, isDbAvailable, openDatabase, openDatabaseByScope, openDatabaseByWorkspace, refreshOpenDatabaseFromDisk, vacuumDatabase, wasDbOpenAttempted, } from "./gsd-db.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { setLogBasePath } from "./workflow-logger.js";
+export function resolveWorkflowDatabaseLocation(basePath) {
+    const contract = resolveGsdPathContract(basePath);
+    return {
+        projectRoot: dirname(dirname(contract.projectDb)),
+        projectGsd: contract.projectGsd,
+        projectDb: contract.projectDb,
+    };
+}
+/**
+ * Resolve the correct DB path for the current working directory.
+ * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
+ * the project root's `.gsd/gsd.db` (shared WAL — R012). Otherwise returns
+ * `<basePath>/.gsd/gsd.db`.
+ */
+export function resolveProjectRootDbPath(basePath) {
+    return resolveWorkflowDatabaseLocation(basePath).projectDb;
+}
+export function openWorkflowDatabase(basePath) {
+    const location = resolveWorkflowDatabaseLocation(basePath);
+    if (!existsSync(location.projectGsd)) {
+        return { ok: false, reason: "missing-gsd-dir", location };
+    }
+    const existed = existsSync(location.projectDb);
+    try {
+        const opened = openDatabase(location.projectDb);
+        if (!opened) {
+            return { ok: false, reason: "open-failed", location };
+        }
+        setLogBasePath(location.projectRoot);
+        return {
+            ok: true,
+            reason: existed ? "opened-existing" : "created-empty",
+            location,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "open-failed",
+            location,
+            error: err instanceof Error ? err : new Error(String(err)),
+        };
+    }
+}
+export function openExistingWorkflowDatabase(basePath) {
+    const location = resolveWorkflowDatabaseLocation(basePath);
+    if (!existsSync(location.projectDb)) {
+        return { ok: false, reason: "missing-database", location };
+    }
+    return openWorkflowDatabase(basePath);
+}
+export function openWorkflowDatabasePath(path) {
+    return openDatabase(path);
+}
+export function openWorkflowDatabaseByWorkspace(workspace) {
+    return openDatabaseByWorkspace(workspace);
+}
+export function openWorkflowDatabaseByScope(scope) {
+    return openDatabaseByScope(scope);
+}
+export function closeWorkflowDatabase() {
+    closeDatabase();
+}
+export function closeWorkflowDatabaseByWorkspace(workspace) {
+    closeDatabaseByWorkspace(workspace);
+}
+export function closeAllWorkflowDatabases() {
+    closeAllDatabases();
+}
+export function isWorkflowDatabaseOpen() {
+    return isDbAvailable();
+}
+export function wasWorkflowDatabaseOpenAttempted() {
+    return wasDbOpenAttempted();
+}
+export function getWorkflowDatabaseStatus() {
+    return getDbStatus();
+}
+export function getWorkflowDatabaseProvider() {
+    return getDbProvider();
+}
+export function getWorkflowDatabasePath() {
+    return getDbPath();
+}
+export function refreshWorkflowDatabaseFromDisk() {
+    return refreshOpenDatabaseFromDisk();
+}
+export function checkpointWorkflowDatabase() {
+    checkpointDatabase();
+}
+export function vacuumWorkflowDatabase() {
+    vacuumDatabase();
+}
+export function backupWorkflowDatabaseSnapshot(label) {
+    return backupDatabaseSnapshot(label);
+}

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

@@ -34,6 +34,7 @@
 // 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.
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
 const POLICY = {
     gsd_plan_slice: {
         toolName: "gsd_plan_slice",
@@ -96,17 +97,8 @@ const POLICY = {
         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;
+    return canonicalWorkflowSurfaceToolName(name);
 }
 export function getDelegationVerdict(toolName) {
     return POLICY[resolveCanonical(toolName)] ?? null;

package/dist/resources/extensions/gsd/discussion-handoff.js

@@ -0,0 +1,218 @@
+// Project/App: gsd-pi
+// File Purpose: Owns the guided-discuss to auto-mode handoff.
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { startAutoDetached } from "./auto.js";
+import { extractDepthVerificationMilestoneId, getPendingGate } from "./bootstrap/write-gate.js";
+import { getMilestone, insertMilestone, isDbAvailable } from "./gsd-db.js";
+import { assessMilestoneHandoffReadiness, formatAcceptedDiscussHandoffMessage, } from "./milestone-readiness.js";
+import { gsdRoot, resolveGsdRootFile, resolveMilestoneFile } from "./paths.js";
+import { _getPendingAutoStart, deletePendingAutoStart } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+import { readManifest } from "./workflow-manifest.js";
+// Cap failed in-flight DB row repair attempts before escalating to the user.
+const MAX_DB_ROW_RECOVERIES = 3;
+const PROJECT_DEPTH_GATE_IDS = new Set([
+    "depth_verification_project_confirm",
+    "depth_verification_requirements_confirm",
+    "depth_verification_research_decision_confirm",
+]);
+export function scheduleAutoStartAfterIdle(ctx, pi, basePath, verboseMode, options, launch = startAutoDetached) {
+    const waitForIdle = typeof ctx.waitForIdle === "function"
+        ? ctx.waitForIdle.bind(ctx)
+        : async () => { };
+    void waitForIdle()
+        .then(() => {
+        setTimeout(() => launch(ctx, pi, basePath, verboseMode, options), 0);
+    })
+        .catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Auto-start failed while waiting for the prior turn to settle: ${message}`, "error");
+        logWarning("guided", `auto-start idle wait failed: ${message}`);
+    });
+}
+function manifestContainsMilestone(basePath, milestoneId) {
+    try {
+        const manifest = readManifest(basePath);
+        return (Array.isArray(manifest?.milestones) &&
+            manifest.milestones.some(m => m.id === milestoneId));
+    }
+    catch (e) {
+        logWarning("guided", `R3b: failed to read state manifest: ${e.message}`);
+        return false;
+    }
+}
+function notifyDbRowRecoveryFailed(entry) {
+    entry.ctx.ui.notify(`Milestone ${entry.milestoneId}: DB row recovery failed ${entry.r3bRecoveryCount} times. ` +
+        `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
+}
+function noteDbRowRecoveryMiss(entry) {
+    entry.r3bRecoveryCount += 1;
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        notifyDbRowRecoveryFailed(entry);
+    }
+}
+function ensureMilestoneRowForAcceptedHandoff(entry, contextFile) {
+    if (!isDbAvailable())
+        return true;
+    const { basePath, milestoneId } = entry;
+    const milestoneRow = getMilestone(milestoneId);
+    if (milestoneRow)
+        return true;
+    if (manifestContainsMilestone(basePath, milestoneId)) {
+        logWarning("guided", `R3b: getMilestone(${milestoneId}) returned null but manifest has the row — treating as stale read`);
+        return true;
+    }
+    if (!contextFile) {
+        entry.ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+            `PROJECT.md may have failed to register milestones. ` +
+            `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+            `then re-run /gsd to recover.`, "error");
+        return false;
+    }
+    if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+        logWarning("guided", `R3b: milestone ${milestoneId} DB-row recovery limit reached ` +
+            `(${entry.r3bRecoveryCount}/${MAX_DB_ROW_RECOVERIES}); user already notified`);
+        return false;
+    }
+    logWarning("guided", `R3b: ${milestoneId} has CONTEXT.md but no DB row — inserting placeholder "queued" row ` +
+        `(attempt ${entry.r3bRecoveryCount + 1}/${MAX_DB_ROW_RECOVERIES})`);
+    try {
+        insertMilestone({ id: milestoneId, title: milestoneId, status: "queued" });
+    }
+    catch (e) {
+        logWarning("guided", `R3b: insertMilestone failed: ${e.message}`);
+    }
+    if (getMilestone(milestoneId))
+        return true;
+    noteDbRowRecoveryMiss(entry);
+    return false;
+}
+/**
+ * Extract milestone IDs from PROJECT.md milestone sequence table.
+ * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
+ */
+function parseMilestoneSequenceFromProject(content) {
+    const ids = [];
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+        const match = line.match(/^\|\s*(M\d{3}[A-Z0-9-]*)\s*\|/);
+        if (match)
+            ids.push(match[1]);
+    }
+    return ids;
+}
+function hasBlockingDepthGate(entry) {
+    const basePathForGate = entry.scope.workspace.projectRoot;
+    const pendingGateId = getPendingGate(basePathForGate);
+    if (!pendingGateId)
+        return false;
+    const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
+    return pendingMilestoneId === entry.milestoneId || PROJECT_DEPTH_GATE_IDS.has(pendingGateId);
+}
+function discussionManifestPath(entry) {
+    return join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
+}
+function warnForMissingProjectMilestones(entry) {
+    const { ctx, basePath } = entry;
+    const projectFile = resolveGsdRootFile(basePath, "PROJECT");
+    if (!projectFile)
+        return [];
+    try {
+        const projectContent = readFileSync(projectFile, "utf-8");
+        const projectIds = parseMilestoneSequenceFromProject(projectContent);
+        if (projectIds.length <= 1)
+            return projectIds;
+        const missing = projectIds.filter(id => {
+            const hasContext = !!resolveMilestoneFile(basePath, id, "CONTEXT");
+            const hasDraft = !!resolveMilestoneFile(basePath, id, "CONTEXT-DRAFT");
+            const hasDir = existsSync(join(gsdRoot(basePath), "milestones", id));
+            return !hasContext && !hasDraft && !hasDir;
+        });
+        if (missing.length > 0) {
+            ctx.ui.notify(`Multi-milestone validation: ${missing.join(", ")} not found in filesystem. ` +
+                `Discussion may not have completed all readiness gates.`, "warning");
+        }
+        return projectIds;
+    }
+    catch (e) {
+        logWarning("guided", `PROJECT.md parsing failed: ${e.message}`);
+        return [];
+    }
+}
+function discussionManifestIsComplete(entry, projectIds) {
+    const manifestPath = discussionManifestPath(entry);
+    if (!existsSync(manifestPath))
+        return true;
+    try {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+        const total = typeof manifest.total === "number" ? manifest.total : 0;
+        const completed = typeof manifest.gates_completed === "number" ? manifest.gates_completed : 0;
+        if (total > 1 && completed < total) {
+            return false;
+        }
+        if (projectIds.length > 0) {
+            const manifestIds = Object.keys(manifest.milestones ?? {});
+            const untracked = projectIds.filter(id => !manifestIds.includes(id));
+            if (untracked.length > 0) {
+                entry.ctx.ui.notify(`Discussion manifest missing gates for: ${untracked.join(", ")}`, "warning");
+            }
+        }
+    }
+    catch (e) {
+        logWarning("guided", `discussion manifest verification failed: ${e.message}`);
+    }
+    return true;
+}
+function cleanupAcceptedHandoffArtifacts(entry) {
+    const { basePath, milestoneId } = entry;
+    try {
+        const draftFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT-DRAFT");
+        if (draftFile)
+            unlinkSync(draftFile);
+    }
+    catch (e) {
+        logWarning("guided", `CONTEXT-DRAFT.md unlink failed: ${e.message}`);
+    }
+    const manifestPath = discussionManifestPath(entry);
+    if (existsSync(manifestPath)) {
+        try {
+            unlinkSync(manifestPath);
+        }
+        catch (e) {
+            logWarning("guided", `manifest unlink failed: ${e.message}`);
+        }
+    }
+}
+/** Called from agent_end to check if auto-mode should start after discuss. */
+export function checkAutoStartAfterDiscuss(lookupBasePath) {
+    const entry = _getPendingAutoStart(lookupBasePath);
+    if (!entry)
+        return false;
+    const { ctx, pi, basePath, milestoneId, step } = entry;
+    const contextFilePath = entry.scope.contextFile();
+    const roadmapFilePath = entry.scope.roadmapFile();
+    const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
+    const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
+    if (!contextFile && !roadmapFile)
+        return false;
+    if (hasBlockingDepthGate(entry))
+        return false;
+    if (!ensureMilestoneRowForAcceptedHandoff(entry, contextFile))
+        return false;
+    const projectIds = warnForMissingProjectMilestones(entry);
+    if (!discussionManifestIsComplete(entry, projectIds))
+        return false;
+    cleanupAcceptedHandoffArtifacts(entry);
+    deletePendingAutoStart(basePath);
+    const readiness = assessMilestoneHandoffReadiness({
+        milestoneId,
+        contextFile,
+        roadmapFile,
+    });
+    ctx.ui.notify(formatAcceptedDiscussHandoffMessage(milestoneId, readiness), "success");
+    if (entry.startAuto !== false) {
+        scheduleAutoStartAfterIdle(ctx, pi, basePath, false, { step: step ?? true });
+    }
+    return true;
+}

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -73,6 +73,15 @@ These are **separate concerns**:
 
 Setting `prefer_skills: []` does **not** disable skill discovery — it just means you have no preference overrides. Use `skill_discovery: off` to disable discovery entirely.
 
+### Parse & Validation Diagnostics
+
+Preference loading never throws. When a file is malformed or contains invalid settings, GSD falls back to safe defaults but attaches structured diagnostics (see `collectPreferenceDiagnostics()` in `preferences-diagnostics.ts`) so the problem is reported instead of silently ignored:
+
+- **Parse failures** (missing closing `---` delimiter, YAML syntax error, or an unrecognized file format) cause the whole file to be ignored. Loading continues to the next candidate — a valid global or legacy preferences file is still used, and a malformed project file never becomes the effective wrapper or blocks fallback.
+- **Validation problems** (unknown keys, type mismatches) are sanitized or dropped per-field; the remaining valid settings in the file still apply.
+
+Diagnostics record the file path, scope (global/project), severity (error/warning), kind (parse/validation), and — for YAML parse errors — the line and column. They surface through session-start notifications, `/gsd doctor`, and auto-mode preflight, with each surface deduping repeated diagnostics.
+
 ---
 
 ## Field Guide

package/dist/resources/extensions/gsd/doctor.js

@@ -2,11 +2,13 @@ import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "nod
 import { join } from "node:path";
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
@@ -286,13 +288,7 @@ export async function runGSDDoctor(basePath, options) {
     // CLI doctor can run before any tool handler has opened the DB. Runtime
     // health checks need the existing project DB to surface DB-backed crash
     // locks, paused sessions, and coordination rows.
-    const dbPath = resolveGsdPathContract(basePath).projectDb;
-    if (existsSync(dbPath)) {
-        try {
-            openDatabase(dbPath);
-        }
-        catch { /* surfaced later as db_unavailable */ }
-    }
+    openExistingWorkflowDatabase(basePath);
     // Issue codes that represent completion state transitions — creating summary
     // stubs, marking slices/milestones done in the roadmap. These belong to the
     // dispatch lifecycle (complete-slice, complete-milestone units), not to
@@ -307,6 +303,17 @@ export async function runGSDDoctor(basePath, options) {
         return true;
     };
     const prefs = loadEffectiveGSDPreferences(basePath);
+    for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+        issues.push({
+            severity: diagnostic.severity,
+            code: "invalid_preferences",
+            scope: "project",
+            unitId: "project",
+            message: `GSD preferences ${diagnostic.kind}: ${formatPreferenceDiagnosticDetail(diagnostic)}`,
+            file: diagnostic.path,
+            fixable: false,
+        });
+    }
     if (prefs) {
         const prefIssues = validatePreferenceShape(prefs.preferences);
         for (const issue of prefIssues) {

package/dist/resources/extensions/gsd/error-classifier.js

@@ -32,7 +32,7 @@ const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient cre
 // are emitted by SDK/harness transports for mid-stream disconnects.
 // These indicate transient network-level interruptions.
 // See: https://github.com/open-gsd/gsd-pi/issues/4558
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|web ?socket|fetch failed|connection.*reset|dns|unexpected eof|stream idle timeout|partial response received|stream ended without finish_reason/i;
 // Context overflow errors (context window/length exceeded) should be treated as server-class
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/open-gsd/gsd-pi/issues/4528

package/dist/resources/extensions/gsd/git-conflict-state.js

@@ -61,7 +61,22 @@ export function gitDiffCheckFailures(basePath) {
             .filter(Boolean)
             .join("\n")
             .trim();
-        failures.push(output || `git diff --check ${args.join(" ")} failed`);
+        // git diff --check exits non-zero for both whitespace errors and leftover
+        // conflict markers. Only conflict markers block the gate — whitespace errors
+        // in staged files (common in auto-generated code) must not be misread as an
+        // unresolved merge conflict. Filter to lines git explicitly labels as
+        // "leftover conflict marker".
+        if (!output) {
+            failures.push(`git diff --check ${args.join(" ")} failed`);
+            continue;
+        }
+        const conflictMarkerLines = output
+            .split("\n")
+            .filter((line) => /leftover conflict marker/i.test(line))
+            .join("\n");
+        if (conflictMarkerLines) {
+            failures.push(conflictMarkerLines);
+        }
     }
     return failures;
 }