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

package/src/resources/extensions/gsd/discussion-handoff.ts

@@ -0,0 +1,276 @@
+// Project/App: gsd-pi
+// File Purpose: Owns the guided-discuss to auto-mode handoff.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+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, type PendingAutoStartEntry } from "./pending-auto-start.js";
+import { logWarning } from "./workflow-logger.js";
+import { readManifest } from "./workflow-manifest.js";
+
+type AutoStartOptions = Parameters<typeof startAutoDetached>[4];
+type AutoStartLauncher = typeof startAutoDetached;
+
+// 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: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  verboseMode: boolean,
+  options?: AutoStartOptions,
+  launch: AutoStartLauncher = startAutoDetached,
+): void {
+  const waitForIdle =
+    typeof (ctx as { waitForIdle?: unknown }).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: string, milestoneId: string): boolean {
+  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 as Error).message}`);
+    return false;
+  }
+}
+
+function notifyDbRowRecoveryFailed(entry: PendingAutoStartEntry): void {
+  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: PendingAutoStartEntry): void {
+  entry.r3bRecoveryCount += 1;
+  if (entry.r3bRecoveryCount >= MAX_DB_ROW_RECOVERIES) {
+    notifyDbRowRecoveryFailed(entry);
+  }
+}
+
+function ensureMilestoneRowForAcceptedHandoff(
+  entry: PendingAutoStartEntry,
+  contextFile: string | null,
+): boolean {
+  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 as Error).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: string): string[] {
+  const ids: string[] = [];
+  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: PendingAutoStartEntry): boolean {
+  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: PendingAutoStartEntry): string {
+  return join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
+}
+
+function warnForMissingProjectMilestones(entry: PendingAutoStartEntry): string[] {
+  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 as Error).message}`);
+    return [];
+  }
+}
+
+function discussionManifestIsComplete(entry: PendingAutoStartEntry, projectIds: string[]): boolean {
+  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 as Error).message}`);
+  }
+  return true;
+}
+
+function cleanupAcceptedHandoffArtifacts(entry: PendingAutoStartEntry): void {
+  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 as Error).message}`);
+  }
+
+  const manifestPath = discussionManifestPath(entry);
+  if (existsSync(manifestPath)) {
+    try {
+      unlinkSync(manifestPath);
+    } catch (e) {
+      logWarning("guided", `manifest unlink failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+/** Called from agent_end to check if auto-mode should start after discuss. */
+export function checkAutoStartAfterDiscuss(lookupBasePath?: string): boolean {
+  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/src/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/src/resources/extensions/gsd/doctor.ts

@@ -3,11 +3,13 @@ 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 { 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, resolveGsdPathContract } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
+import { collectPreferenceDiagnostics, formatPreferenceDiagnosticDetail } from "./preferences-diagnostics.js";
 import { isClosedStatus } from "./status-guards.js";
 
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
@@ -314,10 +316,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   // 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
@@ -333,6 +332,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   };
 
   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/src/resources/extensions/gsd/error-classifier.ts

@@ -58,7 +58,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/src/resources/extensions/gsd/git-conflict-state.ts

@@ -64,7 +64,23 @@ export function gitDiffCheckFailures(basePath: string): string[] | null {
       .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;

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

@@ -1150,6 +1150,11 @@ export function insertSlice(s: {
   planning?: Partial<SlicePlanningRecord>;
 }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+  const invalidDep = (s.depends ?? []).find(d => !SLICE_ID_RE.test(d));
+  if (invalidDep !== undefined) {
+    throw new GSDError(GSD_STALE_STATE, `insertSlice: depends element "${invalidDep}" is not a valid slice ID`);
+  }
   currentDb.prepare(
     `INSERT INTO slices (
       milestone_id, id, title, status, risk, depends, demo, created_at,
@@ -2499,6 +2504,13 @@ export function updateSliceFields(milestoneId: string, sliceId: string, fields:
   demo?: string;
 }): void {
   if (!currentDb) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+  const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+  if (fields.depends !== undefined) {
+    const invalidDep = fields.depends.find(d => !SLICE_ID_RE.test(d));
+    if (invalidDep !== undefined) {
+      throw new GSDError(GSD_STALE_STATE, `updateSliceFields: depends element "${invalidDep}" is not a valid slice ID`);
+    }
+  }
   currentDb.prepare(
     `UPDATE slices SET
       title = COALESCE(:title, title),