gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.b62439b9f

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Auto-mode worktree lifecycle, merge, and cleanup management.
+
 /**
  * GSD Auto-Worktree -- lifecycle management for auto-mode worktrees.
  *
@@ -18,7 +21,7 @@ import {
   statSync,
   lstatSync as lstatSyncFn,
 } from "node:fs";
-import { isAbsolute, join, sep as pathSep } from "node:path";
+import { isAbsolute, join, relative, sep as pathSep } from "node:path";
 import { GSDError, GSD_IO_ERROR, GSD_GIT_ERROR } from "./errors.js";
 import {
   reconcileWorktreeDb,
@@ -50,7 +53,8 @@ import {
   normalizeWorktreePathForCompare,
   resolveWorktreeProjectRoot,
 } from "./worktree-root.js";
-import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
+import { MergeConflictError, createDraftPR, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -266,6 +270,38 @@ function getActiveWorkspace(): GsdWorkspace | null {
   return activeWorkspace;
 }
 
+function gitPathspecForWorktreePath(basePath: string, targetPath: string): string | null {
+  let base = basePath;
+  let target = targetPath;
+  try {
+    base = realpathSync.native(basePath);
+  } catch (err) {
+    logWarning("worktree", `base realpath failed; using original path: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  try {
+    target = realpathSync.native(targetPath);
+  } catch (err) {
+    logWarning("worktree", `target realpath failed; using original path: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const rel = relative(base, target);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
+  return rel.replaceAll("\\", "/");
+}
+
+function gitRemoteExists(basePath: string, remote: string): boolean {
+  try {
+    execFileSync("git", ["remote", "get-url", remote], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function clearProjectRootStateFiles(basePath: string, milestoneId: string): void {
   const gsdDir = gsdRoot(basePath);
   // Phase C pt 2: auto.lock removed from this list — the file is gone
@@ -301,11 +337,14 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void
   for (const dir of syncedDirs) {
     try {
       if (existsSync(dir)) {
+        const pathspec = gitPathspecForWorktreePath(basePath, dir);
+        if (!pathspec) continue;
+
         // Only remove files that are untracked by git — tracked files are
         // managed by the branch checkout and should not be deleted.
         const untrackedOutput = execFileSync(
           "git",
-          ["ls-files", "--others", "--exclude-standard", dir],
+          ["ls-files", "--others", "--exclude-standard", pathspec],
           { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" },
         ).trim();
         if (untrackedOutput) {
@@ -2187,16 +2226,18 @@ export function mergeMilestoneToMain(
   let pushed = false;
   if (prefs.auto_push === true && prefs.auto_pr !== true && !nothingToCommit) {
     const remote = prefs.remote ?? "origin";
-    try {
-      execFileSync("git", ["push", remote, mainBranch], {
-        cwd: originalBasePath_,
-        stdio: ["ignore", "pipe", "pipe"],
-        encoding: "utf-8",
-      });
-      pushed = true;
-    } catch (err) {
-      // Push failure is non-fatal
-      logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
+    if (gitRemoteExists(originalBasePath_, remote)) {
+      try {
+        execFileSync("git", ["push", remote, mainBranch], {
+          cwd: originalBasePath_,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        });
+        pushed = true;
+      } catch (err) {
+        // Push failure is non-fatal
+        logWarning("worktree", `git push failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   }
 
@@ -2205,29 +2246,35 @@ export function mergeMilestoneToMain(
   if (prefs.auto_pr === true && !nothingToCommit) {
     const remote = prefs.remote ?? "origin";
     const prTarget = prefs.pr_target_branch ?? mainBranch;
-    try {
-      // Push the milestone branch to remote first
-      execFileSync("git", ["push", remote, milestoneBranch], {
-        cwd: originalBasePath_,
-        stdio: ["ignore", "pipe", "pipe"],
-        encoding: "utf-8",
-      });
-      // Create PR via gh CLI with explicit --head and --base (#2302)
-      execFileSync("gh", [
-        "pr", "create", "--draft",
-        "--base", prTarget,
-        "--head", milestoneBranch,
-        "--title", `Milestone ${milestoneId} complete`,
-        "--body", "Auto-created by GSD on milestone completion.",
-      ], {
-        cwd: originalBasePath_,
-        stdio: ["ignore", "pipe", "pipe"],
-        encoding: "utf-8",
-      });
-      prCreated = true;
-    } catch (err) {
-      // PR creation failure is non-fatal — gh may not be installed or authenticated
-      logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+    if (gitRemoteExists(originalBasePath_, remote)) {
+      try {
+        // Push the milestone branch to remote first
+        execFileSync("git", ["push", remote, milestoneBranch], {
+          cwd: originalBasePath_,
+          stdio: ["ignore", "pipe", "pipe"],
+          encoding: "utf-8",
+        });
+        const prEvidence = buildPrEvidence({
+          milestoneId,
+          milestoneTitle,
+          changeType: "feat",
+          summaries: completedSlices.map((slice) => `### ${slice.id}\n${slice.title}`),
+          testsRun: ["Auto-created after milestone merge. Run `npm run verify:pr` before marking this draft ready."],
+          rollbackNotes: ["Close the draft PR or revert the merge commit if review finds a behavior regression."],
+          how: "Generated by git.auto_pr after the milestone branch was pushed and merged locally.",
+        });
+        const prUrl = createDraftPR(originalBasePath_, milestoneId, prEvidence.title, prEvidence.body, {
+          head: milestoneBranch,
+          base: prTarget,
+        });
+        if (!prUrl) {
+          throw new Error("gh pr create returned no URL");
+        }
+        prCreated = true;
+      } catch (err) {
+        // PR creation failure is non-fatal — gh may not be installed or authenticated
+        logWarning("worktree", `PR creation failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   }
 

package/src/resources/extensions/gsd/auto.ts

@@ -147,6 +147,7 @@ import {
   MergeConflictError,
   parseSliceBranch,
   setActiveMilestoneId,
+  resolveProjectRoot,
 } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
@@ -231,6 +232,8 @@ import type { ErrorContext } from "./auto/types.js";
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
+import { createAutoOrchestrator } from "./auto/orchestrator.js";
+import type { AutoOrchestrationModule, AutoOrchestratorDeps } from "./auto/contracts.js";
 // Slice-level parallelism (#2340)
 import { getEligibleSlices } from "./slice-parallel-eligibility.js";
 import { startSliceParallel } from "./slice-parallel-orchestrator.js";
@@ -1208,6 +1211,12 @@ export async function stopAuto(
     // changes the user made between sessions (#4959 / CodeRabbit).
     if (pi) clearToolBaseline(pi);
 
+    try {
+      await s.orchestration?.stop(reason ?? "stop");
+    } catch (err) {
+      debugLog("stop-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+    }
+
     // Reset all session state in one call
     s.reset();
   }
@@ -1264,6 +1273,7 @@ export async function pauseAuto(
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
       milestoneLock: s.sessionMilestoneLock ?? undefined,
+      pauseReason: _errorContext?.message,
     };
     setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
   } catch (err) {
@@ -1306,6 +1316,12 @@ export async function pauseAuto(
   resolveAgentEnd({ messages: [] });
   _resetPendingResolve();
 
+  try {
+    await s.orchestration?.stop("pause");
+  } catch (err) {
+    debugLog("pause-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+  }
+
   s.active = false;
   s.paused = true;
   deactivateGSD();
@@ -1363,6 +1379,141 @@ function buildResolver(): WorktreeResolver {
   return new WorktreeResolver(s, buildResolverDeps());
 }
 
+/**
+ * Thin entry glue for the new Auto Orchestration module.
+ *
+ * This intentionally wires only dispatch + error notification today, with
+ * no behavior changes to the existing auto loop. It provides a concrete seam
+ * the next refactor steps can adopt incrementally.
+ */
+export function createWiredAutoOrchestrationModule(
+  ctx: ExtensionContext,
+  _pi: ExtensionAPI,
+  dispatchBasePath: string,
+  runtimeBasePath = resolveProjectRoot(dispatchBasePath),
+): AutoOrchestrationModule {
+  const flowId = `auto-orchestrator-${Date.now()}`;
+  let seq = 0;
+
+  const deps: AutoOrchestratorDeps = {
+    dispatch: {
+      async decideNextUnit() {
+        const state = await deriveState(dispatchBasePath);
+        const active = state.activeMilestone;
+        if (!active) return null;
+
+        const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+        const action = await resolveDispatch({
+          basePath: dispatchBasePath,
+          mid: active.id,
+          midTitle: active.title,
+          state,
+          prefs,
+        });
+
+        if (action.action !== "dispatch") return null;
+        return {
+          unitType: action.unitType,
+          unitId: action.unitId,
+          reason: action.matchedRule ?? "dispatch",
+          preconditions: [],
+        };
+      },
+    },
+    recovery: {
+      async classifyAndRecover(input) {
+        const reason = input.error instanceof Error ? input.error.message : String(input.error ?? "unknown auto error");
+        return { action: "escalate" as const, reason };
+      },
+    },
+    worktree: {
+      async prepareForUnit() {},
+      async syncAfterUnit() {},
+      async cleanupOnStop() {},
+    },
+    health: {
+      async preAdvanceGate() {
+        const gate = await preDispatchHealthGate(dispatchBasePath);
+        return {
+          allow: gate.proceed,
+          reason: gate.reason,
+        };
+      },
+      async postAdvanceRecord(result) {
+        if (result.kind === "error") {
+          recordHealthSnapshot(1, 0, 0, [{
+            code: "orchestration-error",
+            message: result.reason ?? "orchestration error",
+            severity: "error",
+            unitId: "orchestration",
+          }], [], "orchestration");
+        } else if (result.kind === "blocked") {
+          recordHealthSnapshot(0, 1, 0, [{
+            code: "orchestration-blocked",
+            message: result.reason ?? "orchestration blocked",
+            severity: "warning",
+            unitId: "orchestration",
+          }], [], "orchestration");
+        }
+      },
+    },
+    runtime: {
+      async ensureLockOwnership() {
+        const status = getSessionLockStatus(runtimeBasePath);
+        if (!status.valid || status.failureReason === "pid-mismatch") {
+          throw new Error("session lock held by another process");
+        }
+      },
+      async journalTransition(event) {
+        const eventType = event.name === "start"
+          ? "iteration-start"
+          : event.name === "resume"
+            ? "iteration-start"
+            : event.name === "advance"
+              ? "dispatch-match"
+              : event.name === "advance-blocked"
+                ? "guard-block"
+                : event.name === "advance-stopped"
+                  ? "dispatch-stop"
+                  : event.name === "advance-error"
+                    ? "iteration-end"
+                    : event.name === "advance-paused" || event.name === "advance-retry"
+                      ? "guard-block"
+                      : event.name === "stop"
+                      ? "terminal"
+                      : "iteration-end";
+
+        _emitJournalEvent(runtimeBasePath, {
+          ts: new Date().toISOString(),
+          flowId,
+          seq: ++seq,
+          eventType,
+          data: {
+            source: "auto-orchestrator",
+            name: event.name,
+            reason: event.reason,
+            unitType: event.unitType,
+            unitId: event.unitId,
+          },
+        });
+      },
+    },
+    notifications: {
+      async notifyLifecycle(event) {
+        if (event.name === "error") {
+          ctx.ui.notify(event.detail ?? "auto orchestration error", "error");
+        }
+      },
+    },
+  };
+
+  return createAutoOrchestrator(deps);
+}
+
+function ensureOrchestrationModule(ctx: ExtensionContext, pi: ExtensionAPI, basePath: string): void {
+  s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
+}
+
 /**
  * Build the LoopDeps object from auto.ts private scope.
  * This bundles all private functions that autoLoop needs without exporting them.
@@ -1785,6 +1936,7 @@ export async function startAuto(
       rebuildScope(s.basePath, s.currentMilestoneId);
     }
 
+    ensureOrchestrationModule(ctx, pi, s.basePath || base);
     registerSigtermHandler(lockBase());
 
     ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
@@ -1797,15 +1949,15 @@ export async function startAuto(
     // Re-sync managed resources on resume so long-lived auto sessions pick up
     // bundled extension updates before resume-time verification/state logic runs.
     // GSD_PKG_ROOT is set by loader.ts and points to the gsd-pi package root.
-    // The relative import ("../../../resource-loader.js") only works from the source
+    // The relative import ("../../../resource-runtime/resource-loader.js") only works from the source
     // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
     // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
     // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
     const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
     const pkgRoot = process.env.GSD_PKG_ROOT;
     const resourceLoaderPath = pkgRoot
-      ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
-      : new URL("../../../resource-loader.js", import.meta.url).href;
+      ? pathToFileURL(join(pkgRoot, "dist", "resource-runtime", "resource-loader.js")).href
+      : new URL("../../../resource-runtime/resource-loader.js", import.meta.url).href;
     const { initResources } = await import(resourceLoaderPath);
     initResources(agentDir);
     // Open the project DB before rebuild/derive so resume uses DB-backed
@@ -1868,6 +2020,11 @@ export async function startAuto(
     }
     pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
 
+    try {
+      await s.orchestration?.resume();
+    } catch (err) {
+      debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
+    }
     startAutoCommandPolling(s.basePath);
     await runAutoLoopWithUok({
       ctx,
@@ -1904,7 +2061,7 @@ export async function startAuto(
   // Build scope after bootstrap has populated s.basePath / s.originalBasePath /
   // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
   rebuildScope(s.basePath, s.currentMilestoneId);
-
+  ensureOrchestrationModule(ctx, pi, s.basePath || base);
   captureProjectRootEnv(s.originalBasePath || s.basePath);
   registerAutoWorkerForSession(s);
   try {
@@ -1915,6 +2072,12 @@ export async function startAuto(
   }
   pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: requestedStepMode ? "Step-mode started." : "Auto-mode started.", level: "progress" });
 
+  try {
+    await s.orchestration?.start({ basePath: s.basePath, trigger: "auto-loop" });
+  } catch (err) {
+    debugLog("start-orchestration-start", { error: err instanceof Error ? err.message : String(err) });
+  }
+
   startAutoCommandPolling(s.basePath);
 
   // Dispatch the first unit
@@ -2037,6 +2200,9 @@ export async function dispatchHookUnit(
   }
 
   s.basePath = targetBasePath;
+  if (!s.orchestration) {
+    ensureOrchestrationModule(ctx, pi, s.basePath);
+  }
 
   const hookUnitType = `hook/${hookName}`;
   const hookStartedAt = Date.now();

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -56,6 +56,19 @@ function resolveAgentEndBasePath(): string | undefined {
   }
 }
 
+export function _buildAbortedPauseContext(lastMsg: { errorMessage?: unknown }): {
+  message: string;
+  category: "aborted";
+  isTransient: true;
+} {
+  const hasErrorMessage = Object.prototype.hasOwnProperty.call(lastMsg, "errorMessage") && !!lastMsg.errorMessage;
+  return {
+    message: hasErrorMessage ? String(lastMsg.errorMessage) : "Operation aborted",
+    category: "aborted",
+    isTransient: true,
+  };
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -159,7 +172,7 @@ export async function handleAgentEnd(
       return;
     }
 
-    await pauseAuto(ctx, pi);
+    await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
     return;
   }
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
@@ -8,6 +10,7 @@ import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 
 async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow-tool-executors.js")> {
   return import("../tools/workflow-tool-executors.js");
@@ -19,11 +22,19 @@ async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canonicalName: string): void {
+  const execute = typeof toolDef.execute === "function"
+    ? async (...args: any[]) => {
+        incrementLegacyTelemetry("legacy.mcpAliasUsed");
+        return toolDef.execute(...args);
+      }
+    : toolDef.execute;
+
   pi.registerTool({
     ...toolDef,
     name: aliasName,
     description: toolDef.description + ` (alias for ${canonicalName} — prefer the canonical name)`,
     promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
+    execute,
   });
 }
 

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -22,6 +22,7 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 
@@ -64,6 +65,16 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
+  return resolveWorktreeProjectRoot(cwd);
+}
+
+function initSessionNotifications(ctx: ExtensionContext): void {
+  initNotificationStore(resolveNotificationStoreBasePath());
+  installNotifyInterceptor(ctx);
+  initNotificationWidget(ctx);
+}
+
 async function writeContextModeCompactionSnapshot(basePath: string): Promise<void> {
   try {
     const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -101,9 +112,7 @@ export function registerHooks(
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
   pi.on("session_start", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
-    initNotificationWidget(ctx);
+    initSessionNotifications(ctx);
     if (!isAutoActive()) {
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
@@ -156,8 +165,7 @@ export function registerHooks(
   });
 
   pi.on("session_switch", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
+    initSessionNotifications(ctx);
     resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();

package/src/resources/extensions/gsd/commands-ship.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
+
 /**
  * GSD Command — /gsd ship
  *
@@ -18,6 +21,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -32,11 +36,6 @@ function isValidRefName(name: string): boolean {
   }
 }
 
-interface PRContent {
-  title: string;
-  body: string;
-}
-
 function listSliceIds(basePath: string, milestoneId: string): string[] {
   // Slices live at <milestoneDir>/slices/<sliceId>/ with canonical S\d+ IDs.
   // Use resolveSlicePath with a probe to find the real slices directory root.
@@ -148,74 +147,48 @@ export async function checkSliceEvalReview(
   };
 }
 
-function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string): PRContent {
-  const title = `feat: ${milestoneTitle || milestoneId}`;
-
-  const sections: string[] = [];
-
-  // TL;DR
-  sections.push("## TL;DR\n");
-  sections.push(`**What:** Ship milestone ${milestoneId} — ${milestoneTitle || "(untitled)"}`);
-  sections.push(`**Why:** Milestone work complete, ready for review.`);
-  sections.push(`**How:** See slice summaries below.\n`);
-
-  // What — slice summaries
+function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string) {
   const summaries = collectSliceSummaries(basePath, milestoneId);
-  if (summaries.length > 0) {
-    sections.push("## What\n");
-    sections.push(summaries.join("\n\n"));
-    sections.push("");
-  }
-
-  // Roadmap status
+  const roadmapItems: string[] = [];
   const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   if (roadmapPath && existsSync(roadmapPath)) {
     try {
       const roadmap = readFileSync(roadmapPath, "utf-8");
       const checkboxLines = roadmap.split("\n").filter((l) => /^\s*-\s*\[[ x]\]/.test(l));
-      if (checkboxLines.length > 0) {
-        sections.push("## Roadmap\n");
-        sections.push(checkboxLines.join("\n"));
-        sections.push("");
-      }
+      roadmapItems.push(...checkboxLines);
     } catch {
       // non-fatal
     }
   }
 
-  // Metrics
+  const metrics: string[] = [];
   const ledger = getLedger();
   const units = ledger?.units ?? loadLedgerFromDisk(basePath)?.units ?? [];
   if (units.length > 0) {
     const totals = getProjectTotals(units);
     const byModel = aggregateByModel(units);
-    sections.push("## Metrics\n");
-    sections.push(`- **Units executed:** ${units.length}`);
-    sections.push(`- **Total cost:** ${formatCost(totals.cost)}`);
-    sections.push(`- **Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
+    metrics.push(`**Units executed:** ${units.length}`);
+    metrics.push(`**Total cost:** ${formatCost(totals.cost)}`);
+    metrics.push(`**Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
     if (totals.duration > 0) {
-      sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+      metrics.push(`**Duration:** ${formatDuration(totals.duration)}`);
     }
     if (byModel.length > 0) {
-      sections.push(`- **Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
+      metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
     }
-    sections.push("");
   }
 
-  // Change type checklist
-  sections.push("## Change type\n");
-  sections.push("- [x] `feat` — New feature or capability");
-  sections.push("- [ ] `fix` — Bug fix");
-  sections.push("- [ ] `refactor` — Code restructuring");
-  sections.push("- [ ] `test` — Adding or updating tests");
-  sections.push("- [ ] `docs` — Documentation only");
-  sections.push("- [ ] `chore` — Build, CI, or tooling changes\n");
-
-  // AI disclosure
-  sections.push("---\n");
-  sections.push("*This PR was prepared with AI assistance (GSD auto-mode).*");
-
-  return { title, body: sections.join("\n") };
+  return buildPrEvidence({
+    milestoneId,
+    milestoneTitle,
+    changeType: "feat",
+    summaries,
+    roadmapItems,
+    metrics,
+    testsRun: ["Run `npm run verify:pr` before marking this PR ready."],
+    rollbackNotes: ["Revert the merge commit or close the PR before merge if review finds a regression."],
+    how: "Generated from GSD milestone slice summaries, roadmap status, and local metrics.",
+  });
 }
 
 export async function handleShip(