gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

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

@@ -3,7 +3,7 @@ import { basename, dirname, join, sep } from "node:path";
 import { readRepoMeta, externalProjectsRoot, cleanNumberedGsdVariants } from "./repo-identity.js";
 import { loadFile } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { isDbAvailable, _getAdapter, getMilestoneSlices } from "./gsd-db.js";
 import { resolveMilestoneFile, milestonesDir, gsdRoot, resolveGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { saveFile } from "./files.js";
@@ -17,7 +17,9 @@ import { getAllWorktreeHealth } from "./worktree-health.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "worktree") {
+import { readEvents } from "./workflow-events.js";
+import { renderAllProjections } from "./workflow-projections.js";
+export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode = "none") {
     // Degrade gracefully if not a git repo
     if (!nativeIsRepo(basePath)) {
         return; // Not a git repo — skip all git health checks
@@ -1067,3 +1069,166 @@ export async function checkGlobalHealth(issues, fixesApplied, shouldFix) {
         // Non-fatal — global health check must not block per-project doctor
     }
 }
+// ── Engine Health Checks ────────────────────────────────────────────────────
+// DB constraint violation detection and projection drift checks.
+export async function checkEngineHealth(basePath, issues, fixesApplied) {
+    // ── DB constraint violation detection (full doctor only, not pre-dispatch per D-10) ──
+    try {
+        if (isDbAvailable()) {
+            const adapter = _getAdapter();
+            // a. Orphaned tasks (task.slice_id points to non-existent slice)
+            try {
+                const orphanedTasks = adapter
+                    .prepare(`SELECT t.id, t.slice_id, t.milestone_id
+             FROM tasks t
+             LEFT JOIN slices s ON t.milestone_id = s.milestone_id AND t.slice_id = s.id
+             WHERE s.id IS NULL`)
+                    .all();
+                for (const row of orphanedTasks) {
+                    issues.push({
+                        severity: "error",
+                        code: "db_orphaned_task",
+                        scope: "task",
+                        unitId: `${row.milestone_id}/${row.slice_id}/${row.id}`,
+                        message: `Task ${row.id} references slice ${row.slice_id} in milestone ${row.milestone_id} but no such slice exists in the database`,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — orphaned task check failed
+            }
+            // b. Orphaned slices (slice.milestone_id points to non-existent milestone)
+            try {
+                const orphanedSlices = adapter
+                    .prepare(`SELECT s.id, s.milestone_id
+             FROM slices s
+             LEFT JOIN milestones m ON s.milestone_id = m.id
+             WHERE m.id IS NULL`)
+                    .all();
+                for (const row of orphanedSlices) {
+                    issues.push({
+                        severity: "error",
+                        code: "db_orphaned_slice",
+                        scope: "slice",
+                        unitId: `${row.milestone_id}/${row.id}`,
+                        message: `Slice ${row.id} references milestone ${row.milestone_id} but no such milestone exists in the database`,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — orphaned slice check failed
+            }
+            // c. Tasks marked complete without summaries
+            try {
+                const doneTasks = adapter
+                    .prepare(`SELECT id, slice_id, milestone_id FROM tasks
+             WHERE status = 'done' AND (summary IS NULL OR summary = '')`)
+                    .all();
+                for (const row of doneTasks) {
+                    issues.push({
+                        severity: "warning",
+                        code: "db_done_task_no_summary",
+                        scope: "task",
+                        unitId: `${row.milestone_id}/${row.slice_id}/${row.id}`,
+                        message: `Task ${row.id} is marked done but has no summary in the database`,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — done-task-no-summary check failed
+            }
+            // d. Duplicate entity IDs (safety check)
+            try {
+                const dupMilestones = adapter
+                    .prepare("SELECT id, COUNT(*) as cnt FROM milestones GROUP BY id HAVING cnt > 1")
+                    .all();
+                for (const row of dupMilestones) {
+                    issues.push({
+                        severity: "error",
+                        code: "db_duplicate_id",
+                        scope: "milestone",
+                        unitId: row.id,
+                        message: `Duplicate milestone ID "${row.id}" appears ${row.cnt} times in the database`,
+                        fixable: false,
+                    });
+                }
+                const dupSlices = adapter
+                    .prepare("SELECT id, milestone_id, COUNT(*) as cnt FROM slices GROUP BY id, milestone_id HAVING cnt > 1")
+                    .all();
+                for (const row of dupSlices) {
+                    issues.push({
+                        severity: "error",
+                        code: "db_duplicate_id",
+                        scope: "slice",
+                        unitId: `${row.milestone_id}/${row.id}`,
+                        message: `Duplicate slice ID "${row.id}" in milestone ${row.milestone_id} appears ${row.cnt} times`,
+                        fixable: false,
+                    });
+                }
+                const dupTasks = adapter
+                    .prepare("SELECT id, slice_id, milestone_id, COUNT(*) as cnt FROM tasks GROUP BY id, slice_id, milestone_id HAVING cnt > 1")
+                    .all();
+                for (const row of dupTasks) {
+                    issues.push({
+                        severity: "error",
+                        code: "db_duplicate_id",
+                        scope: "task",
+                        unitId: `${row.milestone_id}/${row.slice_id}/${row.id}`,
+                        message: `Duplicate task ID "${row.id}" in slice ${row.slice_id} appears ${row.cnt} times`,
+                        fixable: false,
+                    });
+                }
+            }
+            catch {
+                // Non-fatal — duplicate ID check failed
+            }
+        }
+    }
+    catch {
+        // Non-fatal — DB constraint checks failed entirely
+    }
+    // ── Projection drift detection ──────────────────────────────────────────
+    // If the DB is available, check whether markdown projections are stale
+    // relative to the event log and re-render them.
+    try {
+        if (isDbAvailable()) {
+            const eventLogPath = join(basePath, ".gsd", "event-log.jsonl");
+            const events = readEvents(eventLogPath);
+            if (events.length > 0) {
+                const lastEventTs = new Date(events[events.length - 1].ts).getTime();
+                const state = await deriveState(basePath);
+                for (const milestone of state.registry) {
+                    if (milestone.status === "complete")
+                        continue;
+                    const roadmapPath = resolveMilestoneFile(basePath, milestone.id, "ROADMAP");
+                    if (!roadmapPath || !existsSync(roadmapPath)) {
+                        try {
+                            await renderAllProjections(basePath, milestone.id);
+                            fixesApplied.push(`re-rendered missing projections for ${milestone.id}`);
+                        }
+                        catch {
+                            // Non-fatal — projection re-render failed
+                        }
+                        continue;
+                    }
+                    const projectionMtime = statSync(roadmapPath).mtimeMs;
+                    if (lastEventTs > projectionMtime) {
+                        try {
+                            await renderAllProjections(basePath, milestone.id);
+                            fixesApplied.push(`re-rendered stale projections for ${milestone.id}`);
+                        }
+                        catch {
+                            // Non-fatal — projection re-render failed
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal — projection drift check must never block doctor
+    }
+}

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

@@ -8,7 +8,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
-import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth } from "./doctor-checks.js";
+import { checkGitHealth, checkRuntimeHealth, checkGlobalHealth, checkEngineHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
 export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt, formatDoctorReportJson } from "./doctor-format.js";
@@ -332,8 +332,8 @@ export async function runGSDDoctor(basePath, options) {
     // Git health checks — timed
     const t0git = Date.now();
     const isolationMode = options?.isolationMode ??
-        (prefs?.preferences?.git?.isolation === "none" ? "none" :
-            prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree");
+        (prefs?.preferences?.git?.isolation === "worktree" ? "worktree" :
+            prefs?.preferences?.git?.isolation === "branch" ? "branch" : "none");
     await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
     const gitMs = Date.now() - t0git;
     // Runtime health checks — timed
@@ -350,6 +350,8 @@ export async function runGSDDoctor(basePath, options) {
         includeTests: options?.includeTests,
     });
     const envMs = Date.now() - t0env;
+    // Engine health checks — DB constraints and projection drift
+    await checkEngineHealth(basePath, issues, fixesApplied);
     const milestonesPath = milestonesDir(basePath);
     if (!existsSync(milestonesPath)) {
         const report = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
@@ -441,6 +443,7 @@ export async function runGSDDoctor(basePath, options) {
                 id: s.id,
                 title: s.title,
                 done: s.status === "complete",
+                pending: s.status === "pending",
                 risk: (s.risk || "medium"),
                 depends: s.depends,
                 demo: s.demo,
@@ -528,6 +531,10 @@ export async function runGSDDoctor(basePath, options) {
             }
             const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
             if (!slicePath) {
+                // Pending slices haven't been planned yet — directories are created
+                // lazily by ensurePreconditions() at dispatch time. Skip them.
+                if (slice.pending)
+                    continue;
                 const expectedPath = relSlicePath(basePath, milestoneId, slice.id);
                 issues.push({
                     severity: slice.done ? "warning" : "error",
@@ -549,6 +556,9 @@ export async function runGSDDoctor(basePath, options) {
             }
             const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id);
             if (!tasksDir) {
+                // Pending slices haven't been planned yet — tasks/ is created on demand.
+                if (slice.pending)
+                    continue;
                 issues.push({
                     severity: slice.done ? "warning" : "error",
                     code: "missing_tasks_dir",

package/dist/resources/extensions/gsd/git-service.js

@@ -510,13 +510,18 @@ export class GitServiceImpl {
  * Returns the PR URL on success, or null on failure.
  * Non-fatal: callers should treat failure as best-effort.
  */
-export function createDraftPR(basePath, milestoneId, title, body) {
+export function createDraftPR(basePath, milestoneId, title, body, opts) {
     try {
-        const result = execFileSync("gh", [
+        const args = [
             "pr", "create", "--draft",
             "--title", title,
             "--body", body,
-        ], { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV });
+        ];
+        if (opts?.head)
+            args.push("--head", opts.head);
+        if (opts?.base)
+            args.push("--base", opts.base);
+        const result = execFileSync("gh", args, { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV });
         return result.trim();
     }
     catch {

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

@@ -56,7 +56,11 @@ function loadProvider() {
     catch {
         // unavailable
     }
-    process.stderr.write("gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3)\n");
+    const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
+    const versionHint = nodeMajor < 22
+        ? ` GSD requires Node >= 22.0.0 (current: v${process.versions.node}). Upgrade Node to fix this.`
+        : "";
+    process.stderr.write(`gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3).${versionHint}\n`);
 }
 function normalizeRow(row) {
     if (row == null)
@@ -105,7 +109,7 @@ function openRawDb(path) {
     const Database = providerModule;
     return new Database(path);
 }
-const SCHEMA_VERSION = 10;
+const SCHEMA_VERSION = 11;
 function initSchema(db, fileBacked) {
     if (fileBacked)
         db.exec("PRAGMA journal_mode=WAL");
@@ -253,6 +257,7 @@ function initSchema(db, fileBacked) {
         inputs TEXT NOT NULL DEFAULT '[]',
         expected_output TEXT NOT NULL DEFAULT '[]',
         observability_impact TEXT NOT NULL DEFAULT '',
+        full_plan_md TEXT NOT NULL DEFAULT '',
         sequence INTEGER DEFAULT 0, -- DEAD CODE: no tool exposes sequence — always 0
         PRIMARY KEY (milestone_id, slice_id, id),
         FOREIGN KEY (milestone_id, slice_id) REFERENCES slices(milestone_id, id)
@@ -542,6 +547,20 @@ function migrateSchema(db) {
                 ":applied_at": new Date().toISOString(),
             });
         }
+        if (currentVersion < 11) {
+            ensureColumn(db, "tasks", "full_plan_md", `ALTER TABLE tasks ADD COLUMN full_plan_md TEXT NOT NULL DEFAULT ''`);
+            // Add unique constraint to replan_history for idempotency:
+            // one replan record per blocker task per slice per milestone.
+            db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_replan_history_unique
+        ON replan_history(milestone_id, slice_id, task_id)
+        WHERE slice_id IS NOT NULL AND task_id IS NOT NULL
+      `);
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+                ":version": 11,
+                ":applied_at": new Date().toISOString(),
+            });
+        }
         db.exec("COMMIT");
     }
     catch (err) {
@@ -997,7 +1016,8 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
       verify = COALESCE(:verify, verify),
       inputs = COALESCE(:inputs, inputs),
       expected_output = COALESCE(:expected_output, expected_output),
-      observability_impact = COALESCE(:observability_impact, observability_impact)
+      observability_impact = COALESCE(:observability_impact, observability_impact),
+      full_plan_md = COALESCE(:full_plan_md, full_plan_md)
      WHERE milestone_id = :milestone_id AND slice_id = :slice_id AND id = :id`).run({
         ":milestone_id": milestoneId,
         ":slice_id": sliceId,
@@ -1010,6 +1030,7 @@ export function upsertTaskPlanning(milestoneId, sliceId, taskId, planning) {
         ":inputs": planning.inputs ? JSON.stringify(planning.inputs) : null,
         ":expected_output": planning.expectedOutput ? JSON.stringify(planning.expectedOutput) : null,
         ":observability_impact": planning.observabilityImpact ?? null,
+        ":full_plan_md": planning.fullPlanMd ?? null,
     });
 }
 function rowToSlice(row) {
@@ -1078,6 +1099,7 @@ function rowToTask(row) {
         inputs: JSON.parse(row["inputs"] || "[]"),
         expected_output: JSON.parse(row["expected_output"] || "[]"),
         observability_impact: row["observability_impact"] ?? "",
+        full_plan_md: row["full_plan_md"] ?? "",
         sequence: row["sequence"] ?? 0,
     };
 }
@@ -1300,7 +1322,9 @@ export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
 export function insertReplanHistory(entry) {
     if (!currentDb)
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    currentDb.prepare(`INSERT INTO replan_history (milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at)
+    // INSERT OR REPLACE: idempotent on (milestone_id, slice_id, task_id) via schema v11 unique index.
+    // Retrying the same replan silently updates summary instead of accumulating duplicate rows.
+    currentDb.prepare(`INSERT OR REPLACE INTO replan_history (milestone_id, slice_id, task_id, summary, previous_artifact_path, replacement_artifact_path, created_at)
      VALUES (:milestone_id, :slice_id, :task_id, :summary, :previous_artifact_path, :replacement_artifact_path, :created_at)`).run({
         ":milestone_id": entry.milestoneId,
         ":slice_id": entry.sliceId ?? null,

package/dist/resources/extensions/gsd/guided-flow.js

@@ -755,8 +755,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         // when the user exits during init wizard or discuss phase before any
         // real auto-mode work begins.
         const isBootstrapCrash = crashLock.unitType === "starting"
-            && crashLock.unitId === "bootstrap"
-            && crashLock.completedUnits === 0;
+            && crashLock.unitId === "bootstrap";
         if (!isBootstrapCrash) {
             const resume = await showNextAction(ctx, {
                 title: "GSD — Interrupted Session Detected",

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -298,7 +298,7 @@ export async function renderTaskPlanFromDb(basePath, milestoneId, sliceId, taskI
     mkdirSync(tasksDir, { recursive: true });
     const absPath = join(tasksDir, buildTaskFileName(taskId, "PLAN"));
     const artifactPath = toArtifactPath(absPath, basePath);
-    const content = renderTaskPlanMarkdown(task);
+    const content = task.full_plan_md.trim() ? task.full_plan_md : renderTaskPlanMarkdown(task);
     await writeAndStore(absPath, artifactPath, content, {
         artifact_type: "PLAN",
         milestone_id: milestoneId,

package/dist/resources/extensions/gsd/parallel-merge.js

@@ -17,7 +17,7 @@ import { getErrorMessage } from "./error-utils.js";
  * By-completion: merge in the order milestones finished.
  */
 export function determineMergeOrder(workers, order = "sequential") {
-    const completed = workers.filter(w => w.state === "stopped" && w.completedUnits > 0);
+    const completed = workers.filter(w => w.state === "stopped");
     if (order === "by-completion") {
         return completed
             .sort((a, b) => a.startedAt - b.startedAt) // earliest first

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -47,7 +47,6 @@ export function persistState(basePath) {
                 worktreePath: w.worktreePath,
                 startedAt: w.startedAt,
                 state: w.state,
-                completedUnits: w.completedUnits,
                 cost: w.cost,
             })),
             totalCost: state.totalCost,
@@ -158,7 +157,6 @@ function restoreRuntimeState(basePath) {
                 worktreePath: diskStatus?.worktreePath ?? w.worktreePath,
                 startedAt: w.startedAt,
                 state: diskStatus?.state ?? w.state,
-                completedUnits: diskStatus?.completedUnits ?? w.completedUnits,
                 cost: diskStatus?.cost ?? w.cost,
             });
         }
@@ -189,7 +187,6 @@ function restoreRuntimeState(basePath) {
             worktreePath: status.worktreePath,
             startedAt: status.startedAt,
             state: status.state,
-            completedUnits: status.completedUnits,
             cost: status.cost,
         });
         state.totalCost += status.cost;
@@ -296,7 +293,6 @@ export async function startParallel(basePath, milestoneIds, prefs) {
                 worktreePath: w.worktreePath,
                 startedAt: w.startedAt,
                 state: "running",
-                completedUnits: w.completedUnits,
                 cost: w.cost,
             });
             adopted.push(w.milestoneId);
@@ -341,7 +337,6 @@ export async function startParallel(basePath, milestoneIds, prefs) {
                 worktreePath: wtPath,
                 startedAt: now,
                 state: "running",
-                completedUnits: 0,
                 cost: 0,
             };
             state.workers.set(mid, worker);
@@ -486,7 +481,7 @@ export function spawnWorker(basePath, milestoneId) {
         pid: worker.pid,
         state: "running",
         currentUnit: null,
-        completedUnits: worker.completedUnits,
+        completedUnits: 0,
         cost: worker.cost,
         lastHeartbeat: Date.now(),
         startedAt: worker.startedAt,
@@ -527,7 +522,7 @@ export function spawnWorker(basePath, milestoneId) {
             pid: w.pid,
             state: w.state,
             currentUnit: null,
-            completedUnits: w.completedUnits,
+            completedUnits: 0,
             cost: w.cost,
             lastHeartbeat: Date.now(),
             startedAt: w.startedAt,
@@ -602,13 +597,6 @@ function processWorkerLine(basePath, milestoneId, line) {
                 }
             }
         }
-        // Track completed units (each message_end from assistant = progress)
-        if (msg.role === "assistant") {
-            const worker = state.workers.get(milestoneId);
-            if (worker) {
-                worker.completedUnits++;
-            }
-        }
         // Update session status file so dashboard sees live cost
         const worker = state.workers.get(milestoneId);
         if (worker) {
@@ -617,7 +605,7 @@ function processWorkerLine(basePath, milestoneId, line) {
                 pid: worker.pid,
                 state: worker.state,
                 currentUnit: null,
-                completedUnits: worker.completedUnits,
+                completedUnits: 0,
                 cost: worker.cost,
                 lastHeartbeat: Date.now(),
                 startedAt: worker.startedAt,
@@ -635,7 +623,7 @@ function processWorkerLine(basePath, milestoneId, line) {
                 pid: worker.pid,
                 state: worker.state,
                 currentUnit: null,
-                completedUnits: worker.completedUnits,
+                completedUnits: 0,
                 cost: worker.cost,
                 lastHeartbeat: Date.now(),
                 startedAt: worker.startedAt,
@@ -776,13 +764,12 @@ export function refreshWorkerStatuses(basePath, options = {}) {
             if (!isPidAlive(worker.pid)) {
                 worker.cleanup?.();
                 worker.cleanup = undefined;
-                worker.state = worker.completedUnits > 0 ? "stopped" : "error";
+                worker.state = "error";
                 worker.process = null;
             }
             continue;
         }
         worker.state = diskStatus.state;
-        worker.completedUnits = diskStatus.completedUnits;
         worker.cost = diskStatus.cost;
         worker.pid = diskStatus.pid;
     }

package/dist/resources/extensions/gsd/preferences-types.js

@@ -13,7 +13,7 @@ export const MODE_DEFAULTS = {
             push_branches: false,
             pre_merge_check: false,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: false,
     },
@@ -23,7 +23,7 @@ export const MODE_DEFAULTS = {
             push_branches: true,
             pre_merge_check: true,
             merge_strategy: "squash",
-            isolation: "worktree",
+            isolation: "none",
         },
         unique_milestone_ids: true,
     },

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

@@ -125,6 +125,11 @@ function loadPreferencesFile(path, scope) {
         ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
     };
 }
+let _warnedUnrecognizedFormat = false;
+/** @internal Reset the warn-once flag — exported for testing only. */
+export function _resetParseWarningFlag() {
+    _warnedUnrecognizedFormat = false;
+}
 /** @internal Exported for testing only */
 export function parsePreferencesMarkdown(content) {
     // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
@@ -142,7 +147,10 @@ export function parsePreferencesMarkdown(content) {
     if (/^##\s+\w/m.test(content)) {
         return parseHeadingListFormat(content);
     }
-    console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+    if (!_warnedUnrecognizedFormat) {
+        _warnedUnrecognizedFormat = true;
+        console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
+    }
     return null;
 }
 function parseFrontmatterBlock(frontmatter) {
@@ -385,15 +393,19 @@ export function resolvePreDispatchHooks() {
 // ─── Isolation & Parallel ─────────────────────────────────────────────────────
 /**
  * Resolve the effective git isolation mode from preferences.
- * Returns "worktree" (default), "branch", or "none".
+ * Returns "none" (default), "worktree", or "branch".
+ *
+ * Default is "none" so GSD works out of the box without preferences.md.
+ * Worktree isolation requires explicit opt-in because it depends on git
+ * branch infrastructure that must be set up before use.
  */
 export function getIsolationMode() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    if (prefs?.isolation === "none")
-        return "none";
+    if (prefs?.isolation === "worktree")
+        return "worktree";
     if (prefs?.isolation === "branch")
         return "branch";
-    return "worktree"; // default
+    return "none"; // default — no isolation, work on current branch
 }
 export function resolveParallelConfig(prefs) {
     return {

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -17,20 +17,31 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 Then:
 1. Use the **Milestone Summary** output template from the inlined context above
 2. {{skillActivation}}
-3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. In that case, do NOT mark the milestone as passing verification — document the gap clearly in the summary and state that implementation is missing.
-4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
-5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.
+3. **Verify code changes exist.** Run `git diff --stat HEAD $(git merge-base HEAD main) -- ':!.gsd/'` (or the equivalent for the integration branch). If no non-`.gsd/` files appear in the diff, the milestone produced only planning artifacts and no actual code. Record this as a **verification failure**.
+4. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. Record any criterion that was NOT met as a **verification failure**.
+5. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly. Record any unmet items as a **verification failure**.
 6. Validate **requirement status transitions**. For each requirement that changed status during this milestone, confirm the transition is supported by evidence. Requirements can move between Active, Validated, Deferred, Blocked, or Out of Scope — but only with proof.
-7. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
-8. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
+
+### Verification Gate — STOP if verification failed
+
+**If ANY verification failure was recorded in steps 3, 4, or 5, you MUST follow the failure path below. Do NOT proceed to step 7.**
+
+**Failure path** (verification failed):
+- Do NOT call `gsd_complete_milestone` — the milestone must not be marked as complete.
+- Do NOT update `.gsd/PROJECT.md` to reflect completion.
+- Do NOT update `.gsd/REQUIREMENTS.md` to mark requirements as validated.
+- Write a clear summary of what failed and why to help the next attempt.
+- Say: "Milestone {{milestoneId}} verification FAILED — not complete." and stop.
+
+**Success path** (all verifications passed — continue with steps 7–11):
+
+7. **Persist completion through `gsd_complete_milestone`.** Call it with: `milestoneId`, `title`, `oneLiner`, `narrative`, `successCriteriaResults`, `definitionOfDoneResults`, `requirementOutcomes`, `keyDecisions`, `keyFiles`, `lessonsLearned`, `followUps`, `deviations`, `verificationPassed: true`. The tool updates the milestone status in the DB, renders `{{milestoneSummaryPath}}`, and validates all slices are complete before proceeding.
+8. For each requirement whose status changed in step 6, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
 9. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
 10. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 11. Do not commit manually — the system auto-commits your changes after this unit completes.
+- Say: "Milestone {{milestoneId}} complete."
 
-**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met or no code changes exist, document it clearly in the summary and do not mark the milestone as passing verification.
+**Important:** Do NOT skip the code change verification, success criteria, or definition of done verification (steps 3-5). The milestone summary must reflect actual verified outcomes, not assumed success. Verification failures BLOCK completion — there is no override. The milestone stays in its current state until issues are resolved and verification is re-run.
 
 **File system safety:** When scanning milestone directories for evidence, use `ls` or `find` to list directory contents first — never pass a directory path (e.g. `tasks/`, `slices/`) directly to the `read` tool. The `read` tool only accepts file paths, not directories.
-
-**You MUST write `{{milestoneSummaryPath}}` AND update PROJECT.md before finishing.**
-
-When done, say: "Milestone {{milestoneId}} complete."

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -23,28 +23,15 @@ Then:
 2. {{skillActivation}}
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
-5. If `.gsd/REQUIREMENTS.md` exists, update it based on what this slice actually proved. Move requirements between Active, Validated, Deferred, Blocked, or Out of Scope only when the evidence from execution supports that change.
-6. Call the `gsd_slice_complete` tool (alias: `gsd_complete_slice`) to record the slice as complete. The tool validates all tasks are complete, updates the slice status in the DB, renders the summary to `{{sliceSummaryPath}}`, UAT to `{{sliceUatPath}}`, and re-renders `{{roadmapPath}}` — all atomically. Read the summary and UAT templates at `~/.gsd/agent/extensions/gsd/templates/` to understand the expected structure, then pass the following parameters:
-
-   **Identity:** `sliceId`, `milestoneId`, `sliceTitle`
-
-   **Narrative:** `oneLiner` (one-line summary of what the slice accomplished), `narrative` (detailed account of what happened across all tasks), `verification` (what was verified and how), `deviations` (deviations from plan, or "None."), `knownLimitations` (gaps or limitations, or "None."), `followUps` (follow-up work discovered, or "None.")
-
-   **Files:** `keyFiles` (array of key file paths), `filesModified` (array of `{path, description}` objects for all files changed)
-
-   **Requirements:** `requirementsAdvanced` (array of `{id, how}`), `requirementsValidated` (array of `{id, proof}`), `requirementsInvalidated` (array of `{id, what}`), `requirementsSurfaced` (array of new requirement strings)
-
-   **Patterns & decisions:** `keyDecisions` (array of decision strings), `patternsEstablished` (array), `observabilitySurfaces` (array)
-
-   **Dependencies:** `provides` (what this slice provides downstream), `affects` (downstream slice IDs affected), `requires` (array of `{slice, provides}` for upstream dependencies consumed), `drillDownPaths` (paths to task summaries)
-
-   **UAT content:** `uatContent` — the UAT markdown body. This must be a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built. The tool writes it to `{{sliceUatPath}}`.
-
-7. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-8. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
-9. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-10. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
-
-**You MUST call `gsd_slice_complete` before finishing.** The tool handles writing `{{sliceSummaryPath}}`, `{{sliceUatPath}}`, and updating `{{roadmapPath}}` atomically. You must still review decisions and knowledge manually (steps 7-8).
+5. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_save_decision` with scope="requirement", decision="{requirement-id}", choice="{new-status}", rationale="{evidence}". Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
+6. Write `{{sliceSummaryPath}}` (compress all task summaries).
+7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
+8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
+9. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+10. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
+12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
+
+**You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) call `gsd_complete_slice`. The unit will not be marked complete if any of these are missing.**
 
 When done, say: "Slice {{sliceId}} complete."