gsd-pi 2.74.0-dev.2b524c3 → 2.74.0-dev.b741afb

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

@@ -0,0 +1,109 @@
+/**
+ * GSD Command — /gsd do
+ *
+ * Routes freeform natural language to the correct /gsd subcommand
+ * using keyword matching. Falls back to /gsd quick for task-like input.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+interface Route {
+  keywords: string[];
+  command: string;
+}
+
+const ROUTES: Route[] = [
+  { keywords: ["progress", "status", "dashboard", "how far", "where are we"], command: "status" },
+  { keywords: ["auto", "autonomous", "run all", "keep going", "start auto"], command: "auto" },
+  { keywords: ["stop", "halt", "abort"], command: "stop" },
+  { keywords: ["pause", "break", "take a break"], command: "pause" },
+  { keywords: ["history", "past", "what happened", "previous"], command: "history" },
+  { keywords: ["doctor", "health", "diagnose", "check health"], command: "doctor" },
+  { keywords: ["clean up", "cleanup", "remove old", "prune", "tidy"], command: "cleanup" },
+  { keywords: ["export", "report", "share results"], command: "export" },
+  { keywords: ["ship", "pull request", "create pr", "open pr", "merge"], command: "ship" },
+  { keywords: ["discuss", "talk about", "architecture", "design"], command: "discuss" },
+  { keywords: ["undo", "revert", "rollback", "take back"], command: "undo" },
+  { keywords: ["skip", "skip task", "skip this"], command: "skip" },
+  { keywords: ["queue", "reorder", "milestone order", "order milestones"], command: "queue" },
+  { keywords: ["visualize", "viz", "graph", "chart", "show graph"], command: "visualize" },
+  { keywords: ["capture", "note", "idea", "thought", "remember"], command: "capture" },
+  { keywords: ["inspect", "database", "sqlite", "db state"], command: "inspect" },
+  { keywords: ["knowledge", "rule", "pattern", "lesson"], command: "knowledge" },
+  { keywords: ["session report", "session summary", "cost summary", "how much"], command: "session-report" },
+  { keywords: ["backlog", "parking lot", "later", "someday"], command: "backlog" },
+  { keywords: ["pr branch", "clean branch", "filter commits"], command: "pr-branch" },
+  { keywords: ["add tests", "write tests", "generate tests", "test coverage"], command: "add-tests" },
+  { keywords: ["next", "step", "next step", "what's next"], command: "next" },
+  { keywords: ["migrate", "migration", "convert", "upgrade"], command: "migrate" },
+  { keywords: ["steer", "change direction", "pivot", "redirect"], command: "steer" },
+  { keywords: ["park", "shelve", "set aside"], command: "park" },
+  { keywords: ["widget", "toggle widget"], command: "widget" },
+  { keywords: ["logs", "debug logs", "log files"], command: "logs" },
+];
+
+interface MatchResult {
+  command: string;
+  remainingArgs: string;
+  score: number;
+}
+
+function matchRoute(input: string): MatchResult | null {
+  const lower = input.toLowerCase();
+  let bestMatch: MatchResult | null = null;
+
+  for (const route of ROUTES) {
+    for (const keyword of route.keywords) {
+      if (lower.includes(keyword)) {
+        const score = keyword.length; // Longer match = higher confidence
+        if (!bestMatch || score > bestMatch.score) {
+          // Strip the matched keyword from input to get remaining args
+          const idx = lower.indexOf(keyword);
+          const remaining = (input.slice(0, idx) + input.slice(idx + keyword.length)).trim();
+          bestMatch = { command: route.command, remainingArgs: remaining, score };
+        }
+      }
+    }
+  }
+
+  return bestMatch;
+}
+
+export async function handleDo(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  if (!args.trim()) {
+    ctx.ui.notify(
+      "Usage: /gsd do <what you want to do>\n\n" +
+      "Examples:\n" +
+      "  /gsd do show me progress\n" +
+      "  /gsd do run autonomously\n" +
+      "  /gsd do clean up old branches\n" +
+      "  /gsd do fix the login bug",
+      "warning",
+    );
+    return;
+  }
+
+  const match = matchRoute(args);
+
+  if (match) {
+    const fullCommand = match.remainingArgs
+      ? `${match.command} ${match.remainingArgs}`
+      : match.command;
+
+    ctx.ui.notify(`→ /gsd ${fullCommand}`, "info");
+
+    // Re-dispatch through the main dispatcher
+    const { handleGSDCommand } = await import("./commands/dispatcher.js");
+    await handleGSDCommand(fullCommand, ctx, pi);
+    return;
+  }
+
+  // No keyword match → treat as quick task
+  ctx.ui.notify(`→ /gsd quick ${args}`, "info");
+  const { handleQuick } = await import("./quick.js");
+  await handleQuick(args, ctx, pi);
+}

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

@@ -488,7 +488,7 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
-  const { isDbAvailable: dbAvailable, _getAdapter, transaction: dbTransaction } = await import("./gsd-db.js");
+  const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
   const { migrateHierarchyToDb } = await import("./md-importer.js");
   const { invalidateStateCache } = await import("./state.js");
 
@@ -498,12 +498,12 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
   }
 
   try {
-    // 1. Delete + re-populate inside a single transaction for atomicity
-    const db = _getAdapter()!;
+    // 1. Delete + re-populate inside a single transaction for atomicity.
+    //    clearEngineHierarchy() uses transaction() internally but transaction()
+    //    is re-entrant, so wrapping in dbTransaction() keeps the whole
+    //    clear+repopulate atomic.
     const counts = dbTransaction(() => {
-      db.exec("DELETE FROM tasks");
-      db.exec("DELETE FROM slices");
-      db.exec("DELETE FROM milestones");
+      clearEngineHierarchy();
       return migrateHierarchyToDb(basePath);
     });
 

package/src/resources/extensions/gsd/commands-pr-branch.ts

@@ -0,0 +1,234 @@
+/**
+ * GSD Command — /gsd pr-branch
+ *
+ * Creates a clean PR branch by cherry-picking commits while stripping
+ * any changes to .gsd/, .planning/, and PLAN.md paths. Useful for
+ * upstream PRs where planning artifacts should not be included.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { execFileSync } from "node:child_process";
+
+import {
+  nativeGetCurrentBranch,
+  nativeDetectMainBranch,
+  nativeBranchExists,
+} from "./native-git-bridge.js";
+
+const EXCLUDED_PATHS = [".gsd", ".planning", "PLAN.md"] as const;
+
+function git(basePath: string, args: readonly string[]): string {
+  return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
+}
+
+function gitAllowFail(basePath: string, args: readonly string[]): void {
+  try {
+    execFileSync("git", args, { cwd: basePath, encoding: "utf-8", stdio: "pipe" });
+  } catch {
+    // ignored — caller opts into non-fatal behavior
+  }
+}
+
+function hasStagedChanges(basePath: string): boolean {
+  try {
+    execFileSync("git", ["diff", "--cached", "--quiet"], {
+      cwd: basePath,
+      stdio: "pipe",
+    });
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function isValidBranchName(name: string): boolean {
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getCodeOnlyCommits(basePath: string, base: string, head: string): string[] {
+  try {
+    const allCommits = git(basePath, ["log", "--format=%H", `${base}..${head}`])
+      .split("\n")
+      .filter(Boolean);
+    const codeCommits: string[] = [];
+
+    for (const sha of allCommits) {
+      const files = git(basePath, ["diff-tree", "--no-commit-id", "--name-only", "-r", sha])
+        .split("\n")
+        .filter(Boolean);
+      const hasCodeChanges = files.some(
+        (f) => !f.startsWith(".gsd/") && !f.startsWith(".planning/") && f !== "PLAN.md",
+      );
+      if (hasCodeChanges) {
+        codeCommits.push(sha);
+      }
+    }
+
+    return codeCommits.reverse(); // chronological for cherry-picking
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Cherry-pick a commit while stripping excluded paths from the resulting
+ * commit. Returns true if a commit was produced, false if nothing remained
+ * after filtering.
+ */
+function cherryPickFiltered(basePath: string, sha: string): boolean {
+  git(basePath, ["cherry-pick", "--no-commit", "--allow-empty", sha]);
+
+  // Unstage any excluded paths introduced by the cherry-pick.
+  gitAllowFail(basePath, ["reset", "HEAD", "--", ...EXCLUDED_PATHS]);
+
+  // Restore worktree state for excluded paths from HEAD (if tracked),
+  // then remove any newly introduced untracked files under those paths.
+  gitAllowFail(basePath, ["checkout", "HEAD", "--", ...EXCLUDED_PATHS]);
+  gitAllowFail(basePath, ["clean", "-fdq", "--", ...EXCLUDED_PATHS]);
+
+  if (!hasStagedChanges(basePath)) {
+    // Nothing remained after filtering — discard worktree residue and skip.
+    git(basePath, ["reset", "--hard", "HEAD"]);
+    return false;
+  }
+
+  git(basePath, ["commit", "-C", sha]);
+  return true;
+}
+
+function assertNoExcludedPaths(basePath: string, base: string): void {
+  const files = git(basePath, [
+    "diff",
+    "--name-only",
+    `${base}..HEAD`,
+  ])
+    .split("\n")
+    .filter(Boolean);
+  const leaked = files.filter(
+    (f) => f.startsWith(".gsd/") || f.startsWith(".planning/") || f === "PLAN.md",
+  );
+  if (leaked.length > 0) {
+    throw new Error(
+      `PR branch still contains excluded paths: ${leaked.slice(0, 5).join(", ")}${
+        leaked.length > 5 ? ` (+${leaked.length - 5} more)` : ""
+      }`,
+    );
+  }
+}
+
+export async function handlePrBranch(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const basePath = process.cwd();
+  const dryRun = args.includes("--dry-run");
+  const nameMatch = args.match(/--name\s+(\S+)/);
+
+  const currentBranch = nativeGetCurrentBranch(basePath);
+  const mainBranch = nativeDetectMainBranch(basePath);
+
+  // Determine base ref (prefer upstream/main if available)
+  let baseRef: string;
+  try {
+    git(basePath, ["rev-parse", "--verify", "upstream/main"]);
+    baseRef = "upstream/main";
+  } catch {
+    baseRef = mainBranch;
+  }
+
+  // Find commits with code changes
+  const commits = getCodeOnlyCommits(basePath, baseRef, "HEAD");
+
+  if (commits.length === 0) {
+    ctx.ui.notify("No code-only commits found (all commits only touch .gsd/ files).", "info");
+    return;
+  }
+
+  if (dryRun) {
+    const lines = [`Would create PR branch with ${commits.length} commits (filtering .gsd/ paths):\n`];
+    for (const sha of commits) {
+      const msg = git(basePath, ["log", "--format=%s", "-1", sha]);
+      lines.push(`  ${sha.slice(0, 8)} ${msg}`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+    return;
+  }
+
+  const requestedName = nameMatch?.[1];
+  if (requestedName && !isValidBranchName(requestedName)) {
+    ctx.ui.notify(
+      `Invalid branch name: ${requestedName}. Must satisfy git check-ref-format.`,
+      "error",
+    );
+    return;
+  }
+
+  const defaultName = `pr/${currentBranch}`;
+  const prBranch = requestedName ?? defaultName;
+
+  if (!isValidBranchName(prBranch)) {
+    ctx.ui.notify(
+      `Derived branch name is invalid: ${prBranch}. Use --name to override.`,
+      "error",
+    );
+    return;
+  }
+
+  if (nativeBranchExists(basePath, prBranch)) {
+    ctx.ui.notify(
+      `Branch ${prBranch} already exists. Use --name to specify a different name, or delete it first.`,
+      "warning",
+    );
+    return;
+  }
+
+  try {
+    // Create clean branch from base
+    git(basePath, ["checkout", "-b", prBranch, baseRef]);
+
+    // Cherry-pick with path filter
+    let picked = 0;
+    let skipped = 0;
+    for (const sha of commits) {
+      try {
+        if (cherryPickFiltered(basePath, sha)) {
+          picked++;
+        } else {
+          skipped++;
+        }
+      } catch (pickErr) {
+        gitAllowFail(basePath, ["cherry-pick", "--abort"]);
+        gitAllowFail(basePath, ["reset", "--hard", "HEAD"]);
+        const detail = pickErr instanceof Error ? pickErr.message : String(pickErr);
+        ctx.ui.notify(
+          `Cherry-pick conflict at ${sha.slice(0, 8)}. Picked ${picked}/${commits.length} commits. Resolve manually.\n${detail}`,
+          "warning",
+        );
+        git(basePath, ["checkout", currentBranch]);
+        return;
+      }
+    }
+
+    // Post-condition: no excluded paths should appear in the PR branch diff.
+    assertNoExcludedPaths(basePath, baseRef);
+
+    const skippedMsg = skipped > 0 ? ` (${skipped} skipped — contained only planning artifacts)` : "";
+    ctx.ui.notify(
+      `Created ${prBranch} with ${picked} commits${skippedMsg} (no .gsd/ artifacts).\nSwitch back: git checkout ${currentBranch}`,
+      "success",
+    );
+  } catch (err) {
+    // Restore original branch on failure
+    gitAllowFail(basePath, ["cherry-pick", "--abort"]);
+    gitAllowFail(basePath, ["reset", "--hard", "HEAD"]);
+    gitAllowFail(basePath, ["checkout", currentBranch]);
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to create PR branch: ${msg}`, "error");
+  }
+}

package/src/resources/extensions/gsd/commands-session-report.ts

@@ -0,0 +1,101 @@
+/**
+ * GSD Command — /gsd session-report
+ *
+ * Summarizes the current session: tasks completed, cost, tokens,
+ * duration, model usage breakdown.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
+import type { UnitMetrics } from "./metrics.js";
+import { gsdRoot } from "./paths.js";
+import { formatDuration } from "../shared/format-utils.js";
+
+function formatSessionReport(units: UnitMetrics[]): string {
+  const totals = getProjectTotals(units);
+  const byModel = aggregateByModel(units);
+
+  const lines: string[] = [];
+  lines.push("╭─ Session Report ──────────────────────────────────────╮");
+
+  if (totals.duration > 0) {
+    lines.push(`│ Duration:    ${formatDuration(totals.duration).padEnd(40)}│`);
+  }
+  lines.push(`│ Units:       ${String(units.length).padEnd(40)}│`);
+  lines.push(`│ Cost:        ${formatCost(totals.cost).padEnd(40)}│`);
+  lines.push(`│ Tokens:      ${`${formatTokenCount(totals.tokens.input)} in / ${formatTokenCount(totals.tokens.output)} out`.padEnd(40)}│`);
+  lines.push("│                                                       │");
+
+  // Work completed
+  if (units.length > 0) {
+    lines.push("│ Work Completed:                                       │");
+    for (const unit of units) {
+      const finished = unit.finishedAt > 0;
+      const status = finished ? "✓" : "•";
+      const label = `  ${status} ${unit.id ?? "unknown"}`;
+      lines.push(`│ ${label.padEnd(53)}│`);
+    }
+    lines.push("│                                                       │");
+  }
+
+  // Model usage
+  if (byModel.length > 0) {
+    lines.push("│ Model Usage:                                          │");
+    for (const m of byModel) {
+      const label = `  ${m.model}: ${m.units} units (${formatCost(m.cost)})`;
+      lines.push(`│ ${label.padEnd(53)}│`);
+    }
+  }
+
+  lines.push("╰───────────────────────────────────────────────────────╯");
+  return lines.join("\n");
+}
+
+export async function handleSessionReport(
+  args: string,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  const basePath = process.cwd();
+
+  // Get units from in-memory ledger or disk
+  const ledger = getLedger();
+  let units: UnitMetrics[];
+
+  if (ledger && ledger.units.length > 0) {
+    units = ledger.units;
+  } else {
+    const diskLedger = loadLedgerFromDisk(basePath);
+    if (!diskLedger || diskLedger.units.length === 0) {
+      ctx.ui.notify("No session data — no units have been executed yet.", "info");
+      return;
+    }
+    units = diskLedger.units;
+  }
+
+  // JSON output
+  if (args.includes("--json")) {
+    const totals = getProjectTotals(units);
+    const byModel = aggregateByModel(units);
+    ctx.ui.notify(JSON.stringify({ units: units.length, totals, byModel }, null, 2), "info");
+    return;
+  }
+
+  // Save to file
+  if (args.includes("--save")) {
+    const report = formatSessionReport(units);
+    const reportsDir = join(gsdRoot(basePath), "reports");
+    mkdirSync(reportsDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const outPath = join(reportsDir, `session-${timestamp}.md`);
+    writeFileSync(outPath, `\`\`\`\n${report}\n\`\`\`\n`, "utf-8");
+    ctx.ui.notify(`Report saved: ${outPath}`, "success");
+    return;
+  }
+
+  // Display
+  ctx.ui.notify(formatSessionReport(units), "info");
+}

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

@@ -0,0 +1,219 @@
+/**
+ * GSD Command — /gsd ship
+ *
+ * Creates a PR from milestone artifacts: generates title + body from
+ * roadmap, slice summaries, and metrics, then opens via `gh pr create`.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+
+import { deriveState } from "./state.js";
+import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile } from "./paths.js";
+import { getLedger, getProjectTotals, aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk } from "./metrics.js";
+import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bridge.js";
+import { formatDuration } from "../shared/format-utils.js";
+
+function git(basePath: string, args: readonly string[]): string {
+  return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
+}
+
+function isValidRefName(name: string): boolean {
+  try {
+    execFileSync("git", ["check-ref-format", "--branch", name], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+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.
+  const probe = resolveSlicePath(basePath, milestoneId, "S01");
+  let slicesDir: string | null = null;
+  if (probe) {
+    // probe looks like <milestoneDir>/slices/S01 — parent is slices dir.
+    slicesDir = probe.replace(/[\\/][^\\/]+$/, "");
+  } else {
+    // Fall back to scanning the milestones roadmap file's sibling slices dir.
+    const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (roadmap) {
+      slicesDir = roadmap.replace(/[\\/][^\\/]+$/, "") + "/slices";
+    }
+  }
+  if (!slicesDir || !existsSync(slicesDir)) return [];
+
+  try {
+    return readdirSync(slicesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && /^S\d+$/.test(e.name))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function collectSliceSummaries(basePath: string, milestoneId: string): string[] {
+  const summaries: string[] = [];
+  for (const sliceId of listSliceIds(basePath, milestoneId)) {
+    const summaryPath = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+    if (!summaryPath || !existsSync(summaryPath)) continue;
+    try {
+      const content = readFileSync(summaryPath, "utf-8").trim();
+      if (content) summaries.push(`### ${sliceId}\n${content}`);
+    } catch {
+      // non-fatal
+    }
+  }
+  return summaries;
+}
+
+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
+  const summaries = collectSliceSummaries(basePath, milestoneId);
+  if (summaries.length > 0) {
+    sections.push("## What\n");
+    sections.push(summaries.join("\n\n"));
+    sections.push("");
+  }
+
+  // Roadmap status
+  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("");
+      }
+    } catch {
+      // non-fatal
+    }
+  }
+
+  // Metrics
+  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`);
+    if (totals.duration > 0) {
+      sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+    }
+    if (byModel.length > 0) {
+      sections.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") };
+}
+
+export async function handleShip(
+  args: string,
+  ctx: ExtensionCommandContext,
+  _pi: ExtensionAPI,
+): Promise<void> {
+  const basePath = process.cwd();
+  const dryRun = args.includes("--dry-run");
+  const draft = args.includes("--draft");
+  const force = args.includes("--force");
+  const baseMatch = args.match(/--base\s+(\S+)/);
+  const base = baseMatch?.[1] ?? nativeDetectMainBranch(basePath);
+
+  if (!isValidRefName(base)) {
+    ctx.ui.notify(`Invalid base branch name: ${base}`, "error");
+    return;
+  }
+
+  // 1. Validate milestone state
+  const state = await deriveState(basePath);
+  if (!state.activeMilestone) {
+    ctx.ui.notify("No active milestone to ship. Complete milestone work first.", "warning");
+    return;
+  }
+
+  const milestoneId = state.activeMilestone.id;
+  const milestoneTitle = state.activeMilestone.title ?? "";
+
+  // 2. Check for incomplete work (use GSD phase as proxy — no phase field on ActiveRef)
+  if (state.phase !== "complete" && !force) {
+    ctx.ui.notify(
+      `Milestone ${milestoneId} may not be complete (phase: ${state.phase}). Use --force to ship anyway.`,
+      "warning",
+    );
+    return;
+  }
+
+  // 3. Generate PR content
+  const { title, body } = generatePRContent(basePath, milestoneId, milestoneTitle);
+
+  // 4. Dry-run — just show the PR content
+  if (dryRun) {
+    ctx.ui.notify(`--- PR Preview ---\n\nTitle: ${title}\n\n${body}`, "info");
+    return;
+  }
+
+  // 5. Check git state
+  const currentBranch = nativeGetCurrentBranch(basePath);
+  if (!isValidRefName(currentBranch)) {
+    ctx.ui.notify(`Current branch name is invalid for git: ${currentBranch}`, "error");
+    return;
+  }
+  if (currentBranch === base) {
+    ctx.ui.notify(`You're on ${base} — create a feature branch first.`, "warning");
+    return;
+  }
+
+  // 6. Push and create PR (all argv-safe, no shell interpolation)
+  try {
+    git(basePath, ["push", "-u", "origin", currentBranch]);
+
+    const ghArgs = ["pr", "create", "--base", base, "--title", title, "--body", body];
+    if (draft) ghArgs.push("--draft");
+
+    const prUrl = execFileSync("gh", ghArgs, { cwd: basePath, encoding: "utf-8" }).trim();
+
+    ctx.ui.notify(`PR created: ${prUrl}`, "success");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`Failed to create PR: ${msg}`, "error");
+  }
+}