gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

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

@@ -19,13 +19,11 @@ import { clearActivityLogState } from "./activity-log.js";
 import { synthesizeCrashRecovery, getDeepDiagnostic, } from "./session-forensics.js";
 import { writeLock, clearLock, readCrashLock, isLockProcessAlive, } from "./crash-recovery.js";
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
-import { clearUnitRuntimeRecord, readUnitRuntimeRecord, writeUnitRuntimeRecord, } from "./unit-runtime.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, getIsolationMode, } from "./preferences.js";
 import { sendDesktopNotification } from "./notifications.js";
 import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, } from "./auto-budget.js";
 import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
-import { selfHealRuntimeRecords } from "./auto-recovery.js";
 import { selectAndApplyModel, resolveModelId } from "./auto-model-selection.js";
 import { syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree-sync.js";
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
@@ -44,7 +42,7 @@ import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import { createAutoWorktree, enterAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, } from "./auto-worktree.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
-import { verifyExpectedArtifact, reconcileMergeState, } from "./auto-recovery.js";
+import { reconcileMergeState, } from "./auto-recovery.js";
 import { resolveDispatch, DISPATCH_RULES } from "./auto-dispatch.js";
 import { initRegistry, convertDispatchRules } from "./rule-registry.js";
 import { emitJournalEvent as _emitJournalEvent } from "./journal.js";
@@ -82,11 +80,10 @@ const s = new AutoSession();
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 export function shouldUseWorktreeIsolation() {
     const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    if (prefs?.isolation === "none")
-        return false;
-    if (prefs?.isolation === "branch")
-        return false;
-    return true; // default: worktree
+    if (prefs?.isolation === "worktree")
+        return true;
+    // Default is false — worktree isolation requires explicit opt-in
+    return false;
 }
 /** Crash recovery prompt — set by startAuto, consumed by the main loop */
 /** Pending verification retry — set when gate fails with retries remaining, consumed by autoLoop */
@@ -146,7 +143,6 @@ export function getAutoDashboardData() {
             ? (s.autoStartTime > 0 ? Date.now() - s.autoStartTime : 0)
             : 0,
         currentUnit: s.currentUnit ? { ...s.currentUnit } : null,
-        completedUnits: [...s.completedUnits],
         basePath: s.basePath,
         totalCost: totals?.cost ?? 0,
         totalTokens: totals?.tokens.total ?? 0,
@@ -245,7 +241,6 @@ export function checkRemoteAutoSession(projectRoot) {
         unitType: lock.unitType,
         unitId: lock.unitId,
         startedAt: lock.startedAt,
-        completedUnits: lock.completedUnits,
     };
 }
 export function isStepMode() {
@@ -270,16 +265,12 @@ function clearUnitTimeout() {
     }
     clearInFlightTools();
 }
-/** Build snapshot metric opts, enriching with continueHereFired from the runtime record. */
-function buildSnapshotOpts(unitType, unitId) {
-    const runtime = s.currentUnit
-        ? readUnitRuntimeRecord(s.basePath, unitType, unitId)
-        : null;
+/** Build snapshot metric opts. */
+function buildSnapshotOpts(_unitType, _unitId) {
     return {
         promptCharCount: s.lastPromptCharCount,
         baselineCharCount: s.lastBaselineCharCount,
         ...(s.currentUnitRouting ?? {}),
-        ...(runtime?.continueHereFired ? { continueHereFired: true } : {}),
     };
 }
 function handleLostSessionLock(ctx, lockStatus) {
@@ -369,14 +360,41 @@ export async function stopAuto(ctx, pi, reason) {
             debugLog("stop-cleanup-sigterm", { error: e instanceof Error ? e.message : String(e) });
         }
         // ── Step 4: Auto-worktree exit ──
+        // When the milestone is complete (has a SUMMARY), merge the worktree branch
+        // back to main so code isn't stranded on the worktree branch (#2317).
+        // For incomplete milestones, preserve the branch for later resumption.
         try {
             if (s.currentMilestoneId) {
                 const notifyCtx = ctx
                     ? { notify: ctx.ui.notify.bind(ctx.ui) }
                     : { notify: () => { } };
-                buildResolver().exitMilestone(s.currentMilestoneId, notifyCtx, {
-                    preserveBranch: true,
-                });
+                const resolver = buildResolver();
+                // Check if the milestone is complete — SUMMARY file is the authoritative signal.
+                let milestoneComplete = false;
+                try {
+                    const summaryPath = resolveMilestoneFile(s.originalBasePath || s.basePath, s.currentMilestoneId, "SUMMARY");
+                    if (!summaryPath) {
+                        // Also check in the worktree path (SUMMARY may not be synced yet)
+                        const wtSummaryPath = resolveMilestoneFile(s.basePath, s.currentMilestoneId, "SUMMARY");
+                        milestoneComplete = wtSummaryPath !== null;
+                    }
+                    else {
+                        milestoneComplete = true;
+                    }
+                }
+                catch {
+                    // Non-fatal — fall through to preserveBranch path
+                }
+                if (milestoneComplete) {
+                    // Milestone is complete — merge worktree branch back to main
+                    resolver.mergeAndExit(s.currentMilestoneId, notifyCtx);
+                }
+                else {
+                    // Milestone still in progress — preserve branch for later resumption
+                    resolver.exitMilestone(s.currentMilestoneId, notifyCtx, {
+                        preserveBranch: true,
+                    });
+                }
             }
         }
         catch (e) {
@@ -560,12 +578,6 @@ export async function pauseAuto(ctx, _pi) {
         catch {
             // Non-fatal — best-effort closeout on pause
         }
-        try {
-            clearUnitRuntimeRecord(s.basePath, s.currentUnit.type, s.currentUnit.id);
-        }
-        catch {
-            // Non-fatal
-        }
         s.currentUnit = null;
     }
     if (lockBase()) {
@@ -684,9 +696,6 @@ function buildLoopDeps() {
         getMainBranch,
         // Unit closeout + runtime records
         closeoutUnit,
-        verifyExpectedArtifact,
-        clearUnitRuntimeRecord,
-        writeUnitRuntimeRecord,
         recordOutcome,
         writeLock,
         captureAvailableSkills,
@@ -835,15 +844,6 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             });
         }
         invalidateAllCaches();
-        // Clean stale runtime records left from the paused session
-        try {
-            await selfHealRuntimeRecords(s.basePath, ctx);
-        }
-        catch (e) {
-            debugLog("resume-self-heal-runtime-failed", {
-                error: e instanceof Error ? e.message : String(e),
-            });
-        }
         if (s.pausedSessionFile) {
             const activityDir = join(gsdRoot(s.basePath), "activity");
             const recovery = synthesizeCrashRecovery(s.basePath, s.currentUnit?.type ?? "unknown", s.currentUnit?.id ?? "unknown", s.pausedSessionFile ?? undefined, activityDir);
@@ -853,11 +853,9 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             }
             s.pausedSessionFile = null;
         }
-        updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
-        writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown", s.completedUnits.length);
+        updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
+        writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
-        // Clear orphaned runtime records from prior process deaths before entering the loop
-        await selfHealRuntimeRecords(s.basePath, ctx);
         await autoLoop(ctx, pi, s, buildLoopDeps());
         cleanupAfterLoopExit(ctx);
         return;
@@ -879,8 +877,6 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // Best-effort only — sidebar sync must never block auto-mode startup
     }
     logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
-    // Clear orphaned runtime records from prior process deaths before entering the loop
-    await selfHealRuntimeRecords(s.basePath, ctx);
     // Dispatch the first unit
     await autoLoop(ctx, pi, s, buildLoopDeps());
     cleanupAfterLoopExit(ctx);
@@ -979,7 +975,6 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.basePath = targetBasePath;
         s.autoStartTime = Date.now();
         s.currentUnit = null;
-        s.completedUnits = [];
         s.pendingQuickTasks = [];
     }
     const hookUnitType = `hook/${hookName}`;
@@ -999,14 +994,6 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         id: triggerUnitId,
         startedAt: hookStartedAt,
     };
-    writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: hookStartedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-    });
     if (hookModel) {
         const availableModels = ctx.modelRegistry.getAvailable();
         const match = resolveModelId(hookModel, availableModels, ctx.model?.provider);
@@ -1024,7 +1011,7 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         }
     }
     const sessionFile = ctx.sessionManager.getSessionFile();
-    writeLock(lockBase(), hookUnitType, triggerUnitId, s.completedUnits.length, sessionFile);
+    writeLock(lockBase(), hookUnitType, triggerUnitId, sessionFile);
     clearUnitTimeout();
     const supervisor = resolveAutoSupervisorConfig();
     const hookHardTimeoutMs = (supervisor.hard_timeout_minutes ?? 30) * 60 * 1000;
@@ -1032,12 +1019,6 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.unitTimeoutHandle = null;
         if (!s.active)
             return;
-        if (s.currentUnit) {
-            writeUnitRuntimeRecord(s.basePath, hookUnitType, triggerUnitId, hookStartedAt, {
-                phase: "timeout",
-                timeoutAt: Date.now(),
-            });
-        }
         ctx.ui.notify(`Hook ${hookName} exceeded ${supervisor.hard_timeout_minutes ?? 30}min timeout. Pausing auto-mode.`, "warning");
         resetHookState();
         await pauseAuto(ctx, pi);
@@ -1060,4 +1041,5 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
 // Direct phase dispatch → auto-direct-dispatch.ts
 export { dispatchDirectPhase } from "./auto-direct-dispatch.js";
 // Re-export recovery functions for external consumers
-export { resolveExpectedArtifactPath, verifyExpectedArtifact, writeBlockerPlaceholder, buildLoopRemediationSteps, } from "./auto-recovery.js";
+export { buildLoopRemediationSteps, } from "./auto-recovery.js";
+export { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";

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

@@ -1,7 +1,10 @@
 import { Type } from "@sinclair/typebox";
+import { Text } from "@gsd/pi-tui";
 import { findMilestoneIds, nextMilestoneId, claimReservedId, getReservedMilestoneIds } from "../guided-flow.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { StringEnum } from "@gsd/pi-ai";
+import { logError } from "../workflow-logger.js";
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
  * The alias description and promptGuidelines direct the LLM to prefer the canonical name.
@@ -43,7 +46,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: gsd_decision_save tool failed: ${msg}\n`);
+            logError("tool", `gsd_decision_save tool failed: ${msg}`, { tool: "gsd_decision_save", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error saving decision: ${msg}` }],
                 details: { operation: "save_decision", error: msg },
@@ -77,6 +80,26 @@ export function registerDbTools(pi) {
             ], { description: "Who made this decision: 'human' (user directed), 'agent' (LLM decided autonomously), or 'collaborative' (discussed and agreed). Default: 'agent'" })),
         }),
         execute: decisionSaveExecute,
+        renderCall(args, theme) {
+            let text = theme.fg("toolTitle", theme.bold("decision_save "));
+            if (args.scope)
+                text += theme.fg("accent", `[${args.scope}] `);
+            if (args.decision)
+                text += theme.fg("muted", args.decision);
+            if (args.choice)
+                text += theme.fg("dim", ` — ${args.choice}`);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            let text = theme.fg("success", `Decision ${d?.id ?? ""} saved`);
+            if (d?.id)
+                text += theme.fg("dim", ` → DECISIONS.md`);
+            return new Text(text, 0, 0);
+        },
     };
     pi.registerTool(decisionSaveTool);
     registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
@@ -120,7 +143,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: gsd_requirement_update tool failed: ${msg}\n`);
+            logError("tool", `gsd_requirement_update tool failed: ${msg}`, { tool: "gsd_requirement_update", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error updating requirement: ${msg}` }],
                 details: { operation: "update_requirement", id: params.id, error: msg },
@@ -149,6 +172,24 @@ export function registerDbTools(pi) {
             supporting_slices: Type.Optional(Type.String({ description: "Supporting slices" })),
         }),
         execute: requirementUpdateExecute,
+        renderCall(args, theme) {
+            let text = theme.fg("toolTitle", theme.bold("requirement_update "));
+            if (args.id)
+                text += theme.fg("accent", args.id);
+            const fields = ["status", "validation", "notes", "description"].filter((f) => args[f]);
+            if (fields.length > 0)
+                text += theme.fg("dim", ` (${fields.join(", ")})`);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            let text = theme.fg("success", `Requirement ${d?.id ?? ""} updated`);
+            text += theme.fg("dim", ` → REQUIREMENTS.md`);
+            return new Text(text, 0, 0);
+        },
     };
     pi.registerTool(requirementUpdateTool);
     registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
@@ -195,7 +236,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: gsd_summary_save tool failed: ${msg}\n`);
+            logError("tool", `gsd_summary_save tool failed: ${msg}`, { tool: "gsd_summary_save", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error saving artifact: ${msg}` }],
                 details: { operation: "save_summary", error: msg },
@@ -222,6 +263,25 @@ export function registerDbTools(pi) {
             content: Type.String({ description: "The full markdown content of the artifact" }),
         }),
         execute: summarySaveExecute,
+        renderCall(args, theme) {
+            let text = theme.fg("toolTitle", theme.bold("summary_save "));
+            if (args.artifact_type)
+                text += theme.fg("accent", args.artifact_type);
+            const path = [args.milestone_id, args.slice_id, args.task_id].filter(Boolean).join("/");
+            if (path)
+                text += theme.fg("dim", ` ${path}`);
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            let text = theme.fg("success", `${d?.artifact_type ?? "Artifact"} saved`);
+            if (d?.path)
+                text += theme.fg("dim", ` → ${d.path}`);
+            return new Text(text, 0, 0);
+        },
     };
     pi.registerTool(summarySaveTool);
     registerAlias(pi, summarySaveTool, "gsd_save_summary", "gsd_summary_save");
@@ -232,6 +292,7 @@ export function registerDbTools(pi) {
             // This guarantees the ID shown in the UI matches the one materialised on disk.
             const reserved = claimReservedId();
             if (reserved) {
+                await ensureMilestoneDbRow(reserved);
                 return {
                     content: [{ type: "text", text: reserved }],
                     details: { operation: "generate_milestone_id", id: reserved, source: "reserved" },
@@ -242,6 +303,7 @@ export function registerDbTools(pi) {
             const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const allIds = [...new Set([...existingIds, ...getReservedMilestoneIds()])];
             const newId = nextMilestoneId(allIds, uniqueEnabled);
+            await ensureMilestoneDbRow(newId);
             return {
                 content: [{ type: "text", text: newId }],
                 details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, uniqueEnabled },
@@ -255,6 +317,24 @@ export function registerDbTools(pi) {
             };
         }
     };
+    /**
+     * Insert a minimal DB row for a milestone ID so it's visible to the state
+     * machine. Uses INSERT OR IGNORE — safe to call even if gsd_plan_milestone
+     * later writes the full row. Silently skips if the DB isn't available yet
+     * (pre-migration).
+     */
+    async function ensureMilestoneDbRow(milestoneId) {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable)
+            return;
+        try {
+            const { insertMilestone } = await import("../gsd-db.js");
+            insertMilestone({ id: milestoneId, status: "queued" });
+        }
+        catch {
+            // Non-fatal — the safety-net in deriveStateFromDb will catch this
+        }
+    }
     const milestoneGenerateIdTool = {
         name: "gsd_milestone_generate_id",
         label: "Generate Milestone ID",
@@ -270,6 +350,19 @@ export function registerDbTools(pi) {
         ],
         parameters: Type.Object({}),
         execute: milestoneGenerateIdExecute,
+        renderCall(_args, theme) {
+            return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const d = result.details;
+            if (result.isError || d?.error) {
+                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+            }
+            let text = theme.fg("success", `Generated ${d?.id ?? "ID"}`);
+            if (d?.source === "reserved")
+                text += theme.fg("dim", " (reserved)");
+            return new Text(text, 0, 0);
+        },
     };
     pi.registerTool(milestoneGenerateIdTool);
     registerAlias(pi, milestoneGenerateIdTool, "gsd_generate_milestone_id", "gsd_milestone_generate_id");
@@ -302,7 +395,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: plan_milestone tool failed: ${msg}\n`);
+            logError("tool", `plan_milestone tool failed: ${msg}`, { tool: "gsd_plan_milestone", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error planning milestone: ${msg}` }],
                 details: { operation: "plan_milestone", error: msg },
@@ -391,7 +484,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: plan_slice tool failed: ${msg}\n`);
+            logError("tool", `plan_slice tool failed: ${msg}`, { tool: "gsd_plan_slice", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error planning slice: ${msg}` }],
                 details: { operation: "plan_slice", error: msg },
@@ -464,7 +557,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: plan_task tool failed: ${msg}\n`);
+            logError("tool", `plan_task tool failed: ${msg}`, { tool: "gsd_plan_task", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error planning task: ${msg}` }],
                 details: { operation: "plan_task", error: msg },
@@ -530,7 +623,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: complete_task tool failed: ${msg}\n`);
+            logError("tool", `complete_task tool failed: ${msg}`, { tool: "gsd_task_complete", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error completing task: ${msg}` }],
                 details: { operation: "complete_task", error: msg },
@@ -604,7 +697,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: complete_slice tool failed: ${msg}\n`);
+            logError("tool", `complete_slice tool failed: ${msg}`, { tool: "gsd_slice_complete", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error completing slice: ${msg}` }],
                 details: { operation: "complete_slice", error: msg },
@@ -696,7 +789,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: complete_milestone tool failed: ${msg}\n`);
+            logError("tool", `complete_milestone tool failed: ${msg}`, { tool: "gsd_complete_milestone", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error completing milestone: ${msg}` }],
                 details: { operation: "complete_milestone", error: msg },
@@ -712,6 +805,7 @@ export function registerDbTools(pi) {
         promptGuidelines: [
             "Use gsd_complete_milestone when all slices in a milestone are finished and the milestone needs to be recorded.",
             "All slices in the milestone must have status 'complete' — the handler validates this before proceeding.",
+            "verificationPassed must be explicitly set to true — the handler rejects completion if verification did not pass.",
             "On success, returns summaryPath where the MILESTONE-SUMMARY.md was written.",
         ],
         parameters: Type.Object({
@@ -727,11 +821,76 @@ export function registerDbTools(pi) {
             lessonsLearned: Type.Array(Type.String(), { description: "Lessons learned during the milestone" }),
             followUps: Type.Optional(Type.String({ description: "Follow-up items for future milestones" })),
             deviations: Type.Optional(Type.String({ description: "Deviations from the original plan" })),
+            verificationPassed: Type.Boolean({ description: "Must be true — confirms that code change verification, success criteria, and definition of done checks all passed before completion" }),
         }),
         execute: milestoneCompleteExecute,
     };
     pi.registerTool(milestoneCompleteTool);
     registerAlias(pi, milestoneCompleteTool, "gsd_milestone_complete", "gsd_complete_milestone");
+    // ─── gsd_validate_milestone (gsd_milestone_validate alias) ─────────────
+    const milestoneValidateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const dbAvailable = await ensureDbOpen();
+        if (!dbAvailable) {
+            return {
+                content: [{ type: "text", text: "Error: GSD database is not available. Cannot validate milestone." }],
+                details: { operation: "validate_milestone", error: "db_unavailable" },
+            };
+        }
+        try {
+            const { handleValidateMilestone } = await import("../tools/validate-milestone.js");
+            const result = await handleValidateMilestone(params, process.cwd());
+            if ("error" in result) {
+                return {
+                    content: [{ type: "text", text: `Error validating milestone: ${result.error}` }],
+                    details: { operation: "validate_milestone", error: result.error },
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Validated milestone ${result.milestoneId} — verdict: ${result.verdict}. Written to ${result.validationPath}` }],
+                details: {
+                    operation: "validate_milestone",
+                    milestoneId: result.milestoneId,
+                    verdict: result.verdict,
+                    validationPath: result.validationPath,
+                },
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logError("tool", `validate_milestone tool failed: ${msg}`, { tool: "gsd_validate_milestone", error: String(err) });
+            return {
+                content: [{ type: "text", text: `Error validating milestone: ${msg}` }],
+                details: { operation: "validate_milestone", error: msg },
+            };
+        }
+    };
+    const milestoneValidateTool = {
+        name: "gsd_validate_milestone",
+        label: "Validate Milestone",
+        description: "Validate a milestone before completion — persist validation results to the DB, render VALIDATION.md to disk. " +
+            "Records verdict (pass/needs-attention/needs-remediation) and rationale.",
+        promptSnippet: "Validate a GSD milestone (DB write + VALIDATION.md render)",
+        promptGuidelines: [
+            "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
+            "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verdictRationale, remediationPlan (optional).",
+            "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
+            "On success, returns validationPath where VALIDATION.md was written.",
+        ],
+        parameters: Type.Object({
+            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            verdict: StringEnum(["pass", "needs-attention", "needs-remediation"], { description: "Validation verdict" }),
+            remediationRound: Type.Number({ description: "Remediation round (0 for first validation)" }),
+            successCriteriaChecklist: Type.String({ description: "Markdown checklist of success criteria with pass/fail and evidence" }),
+            sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
+            crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
+            requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
+            verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
+            remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
+        }),
+        execute: milestoneValidateExecute,
+    };
+    pi.registerTool(milestoneValidateTool);
+    registerAlias(pi, milestoneValidateTool, "gsd_milestone_validate", "gsd_validate_milestone");
     // ─── gsd_replan_slice (gsd_slice_replan alias) ─────────────────────────
     const replanSliceExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
         const dbAvailable = await ensureDbOpen();
@@ -763,7 +922,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: replan_slice tool failed: ${msg}\n`);
+            logError("tool", `replan_slice tool failed: ${msg}`, { tool: "gsd_replan_slice", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error replanning slice: ${msg}` }],
                 details: { operation: "replan_slice", error: msg },
@@ -836,7 +995,7 @@ export function registerDbTools(pi) {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            process.stderr.write(`gsd-db: reassess_roadmap tool failed: ${msg}\n`);
+            logError("tool", `reassess_roadmap tool failed: ${msg}`, { tool: "gsd_reassess_roadmap", error: String(err) });
             return {
                 content: [{ type: "text", text: `Error reassessing roadmap: ${msg}` }],
                 details: { operation: "reassess_roadmap", error: msg },

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -4,6 +4,7 @@ import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolve
 import { buildBeforeAgentStartResult } from "./system-context.js";
 import { handleAgentEnd } from "./agent-end-recovery.js";
 import { isDepthVerified, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite } from "./write-gate.js";
+import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { getDiscussionMilestoneId } from "../guided-flow.js";
 import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -128,6 +129,23 @@ export function registerHooks(pi) {
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
+        // ── Single-writer engine: block direct writes to STATE.md ──────────
+        // Covers write, edit, and bash tools to prevent bypass vectors.
+        if (isToolCallEventType("write", event)) {
+            if (isBlockedStateFile(event.input.path)) {
+                return { block: true, reason: BLOCKED_WRITE_ERROR };
+            }
+        }
+        if (isToolCallEventType("edit", event)) {
+            if (isBlockedStateFile(event.input.path)) {
+                return { block: true, reason: BLOCKED_WRITE_ERROR };
+            }
+        }
+        if (isToolCallEventType("bash", event)) {
+            if (isBashWriteToStateFile(event.input.command)) {
+                return { block: true, reason: BLOCKED_WRITE_ERROR };
+            }
+        }
         if (!isToolCallEventType("write", event))
             return;
         const result = shouldBlockContextWrite(event.toolName, event.input.path, getDiscussionMilestoneId(), isDepthVerified(), isQueuePhaseActive());

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -45,18 +45,9 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
         }
     }
-    let knowledgeBlock = "";
-    const knowledgePath = resolveGsdRootFile(process.cwd(), "KNOWLEDGE");
-    if (existsSync(knowledgePath)) {
-        try {
-            const content = readFileSync(knowledgePath, "utf-8").trim();
-            if (content) {
-                knowledgeBlock = `\n\n[PROJECT KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${content}`;
-            }
-        }
-        catch {
-            // skip
-        }
+    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome, process.cwd());
+    if (globalSizeKb > 4) {
+        ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }
     let memoryBlock = "";
     try {
@@ -102,6 +93,49 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             : {}),
     };
 }
+export function loadKnowledgeBlock(gsdHomeDir, cwd) {
+    // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
+    let globalKnowledge = "";
+    let globalSizeKb = 0;
+    const globalKnowledgePath = join(gsdHomeDir, "agent", "KNOWLEDGE.md");
+    if (existsSync(globalKnowledgePath)) {
+        try {
+            const content = readFileSync(globalKnowledgePath, "utf-8").trim();
+            if (content) {
+                globalSizeKb = Buffer.byteLength(content, "utf-8") / 1024;
+                globalKnowledge = content;
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
+    let projectKnowledge = "";
+    const knowledgePath = resolveGsdRootFile(cwd, "KNOWLEDGE");
+    if (existsSync(knowledgePath)) {
+        try {
+            const content = readFileSync(knowledgePath, "utf-8").trim();
+            if (content)
+                projectKnowledge = content;
+        }
+        catch {
+            // skip
+        }
+    }
+    if (!globalKnowledge && !projectKnowledge) {
+        return { block: "", globalSizeKb: 0 };
+    }
+    const parts = [];
+    if (globalKnowledge)
+        parts.push(`## Global Knowledge\n\n${globalKnowledge}`);
+    if (projectKnowledge)
+        parts.push(`## Project Knowledge\n\n${projectKnowledge}`);
+    return {
+        block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${parts.join("\n\n")}`,
+        globalSizeKb,
+    };
+}
 function buildWorktreeContextBlock() {
     const worktreeName = getActiveWorktreeName();
     const worktreeMainCwd = getWorktreeOriginalCwd();