gsd-pi 2.44.0-dev.848dd4c → 2.44.0-dev.8dd0d8e

package/dist/resources/extensions/gsd/activity-log.js

@@ -134,6 +134,13 @@ export function pruneActivityLogs(activityDir, retentionDays) {
         for (const entry of entries) {
             if (entry.seq === maxSeq)
                 continue; // always preserve highest-seq
+            if (retentionDays === 0) {
+                try {
+                    unlinkSync(entry.filePath);
+                }
+                catch { /* skip */ }
+                continue;
+            }
             try {
                 const mtime = statSync(entry.filePath).mtimeMs;
                 if (Math.floor(mtime) <= cutoff)

package/dist/resources/extensions/gsd/auto/infra-errors.js

@@ -17,6 +17,9 @@ export const INFRA_ERROR_CODES = new Set([
     "EDQUOT", // disk quota exceeded
     "EMFILE", // too many open files (process)
     "ENFILE", // too many open files (system)
+    "ECONNREFUSED", // connection refused (offline / local server down)
+    "ENOTFOUND", // DNS lookup failed (offline / no network)
+    "ENETUNREACH", // network unreachable (offline / no route)
 ]);
 /**
  * Detect whether an error is an unrecoverable infrastructure failure.

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

@@ -14,7 +14,9 @@ import { debugLog } from "../debug-logger.js";
 import { gsdRoot } from "../paths.js";
 import { atomicWriteSync } from "../atomic-write.js";
 import { PROJECT_FILES } from "../detection.js";
+import { MergeConflictError } from "../git-service.js";
 import { join } from "node:path";
+import { existsSync, cpSync } from "node:fs";
 // ─── generateMilestoneReport ──────────────────────────────────────────────────
 /**
  * Generate and write an HTML milestone report snapshot.
@@ -145,20 +147,19 @@ export async function runPreDispatch(ic, loopState) {
         loopState.recentUnits.length = 0;
         loopState.stuckRecoveryAttempts = 0;
         // Worktree lifecycle on milestone transition — merge current, enter next
-        deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-        // Opt-in: create draft PR on milestone completion
-        if (prefs?.git?.auto_pr) {
-            try {
-                const { createDraftPR } = await import("../git-service.js");
-                const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                if (prUrl) {
-                    ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                }
-            }
-            catch {
-                // Non-fatal — PR creation is best-effort
+        try {
+            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+        }
+        catch (mergeErr) {
+            if (mergeErr instanceof MergeConflictError) {
+                // Real code conflicts — stop the loop instead of retrying forever (#2330)
+                ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                return { action: "break", reason: "merge-conflict" };
             }
+            // Non-conflict errors — log and continue
         }
+        // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         deps.invalidateAllCaches();
         state = await deps.deriveState(s.basePath);
         mid = state.activeMilestone?.id;
@@ -179,9 +180,14 @@ export async function runPreDispatch(ic, loopState) {
         // Reset completed-units tracking for the new milestone — stale entries
         // from the previous milestone cause the dispatch loop to skip units
         // that haven't actually been completed in the new milestone's context.
+        // Archive the old completed-units.json instead of wiping it (#2313).
         s.completedUnits = [];
         try {
             const completedKeysPath = join(gsdRoot(s.basePath), "completed-units.json");
+            if (existsSync(completedKeysPath) && s.currentMilestoneId) {
+                const archivePath = join(gsdRoot(s.basePath), `completed-units-${s.currentMilestoneId}.json`);
+                cpSync(completedKeysPath, archivePath);
+            }
             atomicWriteSync(completedKeysPath, JSON.stringify([], null, 2));
         }
         catch { /* non-fatal */ }
@@ -209,20 +215,17 @@ export async function runPreDispatch(ic, loopState) {
         if (incomplete.length === 0 && state.registry.length > 0) {
             // All milestones complete — merge milestone branch before stopping
             if (s.currentMilestoneId) {
-                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-                // Opt-in: create draft PR on milestone completion
-                if (prefs?.git?.auto_pr) {
-                    try {
-                        const { createDraftPR } = await import("../git-service.js");
-                        const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                        if (prUrl) {
-                            ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                        }
-                    }
-                    catch {
-                        // Non-fatal — PR creation is best-effort
+                try {
+                    deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+                }
+                catch (mergeErr) {
+                    if (mergeErr instanceof MergeConflictError) {
+                        ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                        await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                        return { action: "break", reason: "merge-conflict" };
                     }
                 }
+                // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
             }
             deps.sendDesktopNotification("GSD", "All milestones complete!", "success", "milestone");
             deps.logCmuxEvent(prefs, "All milestones complete.", "success");
@@ -277,20 +280,17 @@ export async function runPreDispatch(ic, loopState) {
     if (state.phase === "complete") {
         // Milestone merge on complete (before closeout so branch state is clean)
         if (s.currentMilestoneId) {
-            deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
-            // Opt-in: create draft PR on milestone completion
-            if (prefs?.git?.auto_pr) {
-                try {
-                    const { createDraftPR } = await import("../git-service.js");
-                    const prUrl = createDraftPR(s.basePath, s.currentMilestoneId, `[GSD] ${s.currentMilestoneId} complete`, `Milestone ${s.currentMilestoneId} completed by GSD auto-mode.\n\nSee .gsd/${s.currentMilestoneId}/ for details.`);
-                    if (prUrl) {
-                        ctx.ui.notify(`Draft PR created: ${prUrl}`, "info");
-                    }
-                }
-                catch {
-                    // Non-fatal — PR creation is best-effort
+            try {
+                deps.resolver.mergeAndExit(s.currentMilestoneId, ctx.ui);
+            }
+            catch (mergeErr) {
+                if (mergeErr instanceof MergeConflictError) {
+                    ctx.ui.notify(`Merge conflict: ${mergeErr.conflictedFiles.join(", ")}. Resolve conflicts manually and run /gsd auto to resume.`, "error");
+                    await deps.stopAuto(ctx, pi, `Merge conflict on milestone ${s.currentMilestoneId}`);
+                    return { action: "break", reason: "merge-conflict" };
                 }
             }
+            // PR creation (auto_pr) is handled inside mergeMilestoneToMain (#2302)
         }
         deps.sendDesktopNotification("GSD", `Milestone ${mid} complete!`, "success", "milestone");
         deps.logCmuxEvent(prefs, `Milestone ${mid} complete.`, "success");
@@ -591,6 +591,7 @@ export async function runUnitPhase(ic, iterData, loopState, sidecarItem) {
         lastProgressAt: s.currentUnit.startedAt,
         progressCount: 0,
         lastProgressKind: "dispatch",
+        recoveryAttempts: 0, // Reset so re-dispatched units get full recovery budget (#2322)
     });
     // Status bar + progress widget
     ctx.ui.setStatus("gsd-auto", "auto");

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

@@ -1156,6 +1156,12 @@ export async function buildCompleteMilestonePrompt(mid, midTitle, base, level) {
         roadmapPath: roadmapRel,
         inlinedContext,
         milestoneSummaryPath,
+        skillActivation: buildSkillActivationBlock({
+            base,
+            milestoneId: mid,
+            milestoneTitle: midTitle,
+            extraContext: [inlinedContext],
+        }),
     });
 }
 export async function buildValidateMilestonePrompt(mid, midTitle, base, level) {
@@ -1236,6 +1242,12 @@ export async function buildValidateMilestonePrompt(mid, midTitle, base, level) {
         inlinedContext,
         validationPath: validationOutputPath,
         remediationRound: String(remediationRound),
+        skillActivation: buildSkillActivationBlock({
+            base,
+            milestoneId: mid,
+            milestoneTitle: midTitle,
+            extraContext: [inlinedContext],
+        }),
     });
 }
 export async function buildReplanSlicePrompt(mid, midTitle, sid, sTitle, base) {
@@ -1332,6 +1344,12 @@ export async function buildRunUatPrompt(mid, sliceId, uatPath, uatContent, base)
         uatResultPath,
         uatType,
         inlinedContext,
+        skillActivation: buildSkillActivationBlock({
+            base,
+            milestoneId: mid,
+            sliceId,
+            extraContext: [inlinedContext],
+        }),
     });
 }
 export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId, base, level) {
@@ -1378,11 +1396,16 @@ export async function buildReassessRoadmapPrompt(mid, midTitle, completedSliceId
         milestoneTitle: midTitle,
         completedSliceId,
         roadmapPath: roadmapRel,
-        completedSliceSummaryPath: summaryRel,
         assessmentPath,
         inlinedContext,
         deferredCaptures,
         commitInstruction: reassessCommitInstruction,
+        skillActivation: buildSkillActivationBlock({
+            base,
+            milestoneId: mid,
+            milestoneTitle: midTitle,
+            extraContext: [inlinedContext, deferredCaptures],
+        }),
     });
 }
 // ─── Reactive Execute Prompt ──────────────────────────────────────────────

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

@@ -197,10 +197,13 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 state = await deriveState(wtPath);
             }
         }
-        // Milestone branch recovery (#601)
+        // Milestone branch recovery (#601, #2358)
+        // Detect survivor milestone branches in both pre-planning and complete phases.
+        // In phase=complete, the milestone artifacts exist but finalization (merge,
+        // worktree cleanup) was never run — the survivor branch must be merged.
         let hasSurvivorBranch = false;
         if (state.activeMilestone &&
-            state.phase === "pre-planning" &&
+            (state.phase === "pre-planning" || state.phase === "complete") &&
             shouldUseWorktreeIsolation() &&
             !detectWorktreeName(base) &&
             !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
@@ -231,6 +234,22 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
                 return releaseLockAndReturn();
             }
         }
+        // Survivor branch exists and milestone is complete (#2358):
+        // The milestone artifacts were written but finalization (merge, worktree
+        // cleanup) never ran. Run mergeAndExit to finalize, then re-derive state
+        // so the normal "all milestones complete" or "next milestone" path runs.
+        if (hasSurvivorBranch && state.phase === "complete") {
+            const mid = state.activeMilestone.id;
+            ctx.ui.notify(`Milestone ${mid} is complete but branch/worktree was not finalized. Running merge now.`, "info");
+            const resolver = buildResolver();
+            resolver.mergeAndExit(mid, {
+                notify: ctx.ui.notify.bind(ctx.ui),
+            });
+            invalidateAllCaches();
+            state = await deriveState(base);
+            // Clear survivor flag — finalization is done
+            hasSurvivorBranch = false;
+        }
         if (!hasSurvivorBranch) {
             // No active work — start a new milestone via discuss flow
             if (!state.activeMilestone || state.phase === "complete") {

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

@@ -6,6 +6,7 @@
  * via startUnitSupervision() and torn down by the caller via clearUnitTimeout().
  */
 import { readUnitRuntimeRecord, writeUnitRuntimeRecord } from "./unit-runtime.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
 import { resolveAutoSupervisorConfig } from "./preferences.js";
 import { computeBudgets, resolveExecutorContextWindow } from "./context-budget.js";
 import { getInFlightToolCount, getOldestInFlightToolStart, } from "./auto-tool-tracking.js";
@@ -21,12 +22,65 @@ import { resolveAgentEndCancelled } from "./auto/resolve.js";
  * 3. Hard timeout (pause + recovery)
  * 4. Context-pressure monitor (continue-here)
  */
+/**
+ * Parse a task estimate string (e.g. "30m", "2h", "1h30m") into minutes.
+ * Returns null if the string cannot be parsed.
+ */
+export function parseEstimateMinutes(estimate) {
+    if (!estimate || typeof estimate !== "string")
+        return null;
+    const trimmed = estimate.trim();
+    if (!trimmed)
+        return null;
+    let totalMinutes = 0;
+    let matched = false;
+    // Match hours component
+    const hoursMatch = trimmed.match(/(\d+)\s*h/i);
+    if (hoursMatch) {
+        totalMinutes += Number(hoursMatch[1]) * 60;
+        matched = true;
+    }
+    // Match minutes component
+    const minutesMatch = trimmed.match(/(\d+)\s*m/i);
+    if (minutesMatch) {
+        totalMinutes += Number(minutesMatch[1]);
+        matched = true;
+    }
+    return matched ? totalMinutes : null;
+}
 export function startUnitSupervision(sctx) {
     const { s, ctx, pi, unitType, unitId, prefs, buildSnapshotOpts, buildRecoveryContext, pauseAuto } = sctx;
     const supervisor = resolveAutoSupervisorConfig();
-    const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000;
-    const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000;
-    const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000;
+    // Scale timeouts based on task estimate annotations (#2243).
+    // If the task has an est: annotation, use it to extend the hard and soft timeouts
+    // so longer tasks don't get prematurely timed out.
+    let taskEstimate = sctx.taskEstimate;
+    if (!taskEstimate && unitType === "task" && isDbAvailable()) {
+        // Look up the task estimate from the DB (#2243).
+        try {
+            if (s.currentMilestoneId) {
+                const slices = getMilestoneSlices(s.currentMilestoneId);
+                for (const slice of slices) {
+                    const tasks = getSliceTasks(s.currentMilestoneId, slice.id);
+                    const task = tasks.find(t => t.id === unitId);
+                    if (task?.estimate) {
+                        taskEstimate = task.estimate;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            // Non-fatal — fall through with no estimate
+        }
+    }
+    const estimateMinutes = taskEstimate ? parseEstimateMinutes(taskEstimate) : null;
+    const timeoutScale = estimateMinutes && estimateMinutes > 0
+        ? Math.max(1, estimateMinutes / 10) // 10min task = 1x, 30min = 3x, 2h = 12x
+        : 1;
+    const softTimeoutMs = (supervisor.soft_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
+    const idleTimeoutMs = (supervisor.idle_timeout_minutes ?? 0) * 60 * 1000; // idle not scaled — idle is idle
+    const hardTimeoutMs = (supervisor.hard_timeout_minutes ?? 0) * 60 * 1000 * timeoutScale;
     // ── 1. Soft timeout warning ──
     s.wrapupWarningHandle = setTimeout(() => {
         s.wrapupWarningHandle = null;

package/dist/resources/extensions/gsd/auto-worktree-sync.js

@@ -63,6 +63,10 @@ export function syncStateToProjectRoot(worktreePath, projectRoot, milestoneId) {
     // 2. Milestone directory — ROADMAP, slice PLANs, task summaries
     // Copy the entire milestone .gsd subtree so deriveState reads current checkboxes
     safeCopyRecursive(join(wtGsd, "milestones", milestoneId), join(prGsd, "milestones", milestoneId), { force: true });
+    // 3. metrics.json — session cost/token tracking (#2313).
+    // Without this, metrics accumulated in the worktree are invisible from the
+    // project root and never appear in the dashboard or skill-health reports.
+    safeCopy(join(wtGsd, "metrics.json"), join(prGsd, "metrics.json"), { force: true });
     // 4. Runtime records — unit dispatch state used by selfHealRuntimeRecords().
     // Without this, a crash during a unit leaves the runtime record only in the
     // worktree. If the next session resolves basePath before worktree re-entry,

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

@@ -109,6 +109,7 @@ export function syncGsdStateToWorktree(mainBasePath, worktreePath_) {
         "OVERRIDES.md",
         "QUEUE.md",
         "completed-units.json",
+        "metrics.json",
     ];
     for (const f of rootFiles) {
         const src = join(mainGsd, f);
@@ -269,8 +270,9 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
     // ── 1. Sync root-level .gsd/ files back ──────────────────────────────
     // The worktree is authoritative — complete-milestone updates REQUIREMENTS,
     // PROJECT, etc. These must overwrite main's copies so they survive teardown.
-    // Also includes QUEUE.md and completed-units.json which are written during
-    // milestone closeout and lost on teardown without explicit sync (#1787).
+    // Also includes QUEUE.md, completed-units.json, and metrics.json which are
+    // written during milestone closeout and lost on teardown without explicit sync
+    // (#1787, #2313).
     const rootFiles = [
         "DECISIONS.md",
         "REQUIREMENTS.md",
@@ -279,6 +281,7 @@ export function syncWorktreeStateBack(mainBasePath, worktreePath, milestoneId) {
         "OVERRIDES.md",
         "QUEUE.md",
         "completed-units.json",
+        "metrics.json",
     ];
     for (const f of rootFiles) {
         const src = join(wtGsd, f);
@@ -1133,9 +1136,9 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
             // Push failure is non-fatal
         }
     }
-    // 9b. Auto-create PR if enabled (requires push_branches + push succeeded)
+    // 9b. Auto-create PR if enabled (#2302: no longer gated on pushed/auto_push)
     let prCreated = false;
-    if (prefs.auto_pr === true && pushed) {
+    if (prefs.auto_pr === true && !nothingToCommit) {
         const remote = prefs.remote ?? "origin";
         const prTarget = prefs.pr_target_branch ?? mainBranch;
         try {
@@ -1145,9 +1148,9 @@ export function mergeMilestoneToMain(originalBasePath_, milestoneId, roadmapCont
                 stdio: ["ignore", "pipe", "pipe"],
                 encoding: "utf-8",
             });
-            // Create PR via gh CLI
+            // Create PR via gh CLI with explicit --head and --base (#2302)
             execFileSync("gh", [
-                "pr", "create",
+                "pr", "create", "--draft",
                 "--base", prTarget,
                 "--head", milestoneBranch,
                 "--title", `Milestone ${milestoneId} complete`,

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

@@ -369,14 +369,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) {

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

@@ -1,7 +1,9 @@
 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";
 /**
  * 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.
@@ -77,6 +79,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");
@@ -149,6 +171,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");
@@ -222,6 +262,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 +291,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 +302,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 +316,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 +349,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");
@@ -732,6 +824,70 @@ export function registerDbTools(pi) {
     };
     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);
+            process.stderr.write(`gsd-db: validate_milestone tool failed: ${msg}\n`);
+            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();