gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/dist/resources/extensions/gsd/commands-extract-learnings.js

@@ -0,0 +1,383 @@
+/**
+ * GSD Command — /gsd extract-learnings
+ *
+ * Analyses completed milestone artefacts and dispatches an LLM turn that
+ * extracts structured knowledge into 4 categories (Decisions · Lessons ·
+ * Patterns · Surprises), writes a LEARNINGS.md audit trail, and persists
+ * the durable subset to GSD's cross-session surfaces:
+ *
+ *   - Patterns + Lessons → appended to .gsd/KNOWLEDGE.md (inlined into
+ *     every future dispatch prompt via auto-prompts::inlineGsdRootFile).
+ *   - Decisions → persisted via the gsd_save_decision MCP tool, which
+ *     regenerates .gsd/DECISIONS.md from the DB.
+ *   - Surprises → stay only in LEARNINGS.md (milestone-local context).
+ *
+ * The same extraction steps are reused by the complete-milestone prompt
+ * via buildExtractionStepsBlock — single source of truth.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename, relative } from "node:path";
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+// ─── Pure functions ───────────────────────────────────────────────────────────
+/**
+ * Parses the argument string passed to `/gsd extract-learnings`.
+ *
+ * Returns `{ milestoneId: null }` for empty / whitespace-only input — the
+ * handler surfaces a usage hint in that case. A non-empty trimmed value is
+ * returned as-is; the handler validates that the milestone actually exists.
+ */
+export function parseExtractLearningsArgs(args) {
+    const trimmed = args.trim();
+    return { milestoneId: trimmed || null };
+}
+/**
+ * Builds the absolute path at which the LEARNINGS.md audit trail should be
+ * written for the given milestone.
+ */
+export function buildLearningsOutputPath(milestoneDir, milestoneId) {
+    return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+/**
+ * Resolves the milestone-scoped artefact paths needed to perform an
+ * extraction. The milestone's ROADMAP and SUMMARY files are required; the
+ * VERIFICATION and UAT files are optional. Missing required files are
+ * reported by filename in `missingRequired` so the handler can surface a
+ * precise error without swallowing the cause.
+ */
+export function resolvePhaseArtifacts(milestoneDir, milestoneId) {
+    const missingRequired = [];
+    const roadmapFile = `${milestoneId}-ROADMAP.md`;
+    const summaryFile = `${milestoneId}-SUMMARY.md`;
+    const verificationFile = `${milestoneId}-VERIFICATION.md`;
+    const uatFile = `${milestoneId}-UAT.md`;
+    const roadmapPath = join(milestoneDir, roadmapFile);
+    const summaryPath = join(milestoneDir, summaryFile);
+    const verificationPath = join(milestoneDir, verificationFile);
+    const uatPath = join(milestoneDir, uatFile);
+    const roadmap = existsSync(roadmapPath) ? roadmapPath : null;
+    const summary = existsSync(summaryPath) ? summaryPath : null;
+    const verification = existsSync(verificationPath) ? verificationPath : null;
+    const uat = existsSync(uatPath) ? uatPath : null;
+    if (!roadmap)
+        missingRequired.push(roadmapFile);
+    if (!summary)
+        missingRequired.push(summaryFile);
+    return { roadmap, summary, verification, uat, missingRequired };
+}
+/**
+ * Canonical structured-extraction instructions.
+ *
+ * Used in two places — kept in sync by construction:
+ *   1. /gsd extract-learnings manual path (buildExtractLearningsPrompt).
+ *   2. complete-milestone auto path ({{extractLearningsSteps}} placeholder,
+ *      injected by auto-prompts::buildCompleteMilestonePrompt).
+ *
+ * The block assumes the LLM already has the milestone artefacts available —
+ * either inlined directly in the manual path, or via {{inlinedContext}} in
+ * complete-milestone. It does not re-inline artefacts.
+ */
+export function buildExtractionStepsBlock(ctx) {
+    return `## Structured Learnings Extraction
+
+Perform the following steps IN ORDER. Each step is mandatory unless explicitly
+marked optional. These instructions are the single source of truth shared by
+\`/gsd extract-learnings\` and the auto-mode milestone-completion turn.
+
+### Step 1 — Classify findings into four categories
+
+Review the milestone artefacts (roadmap, slice summaries, verification report,
+UAT report) and structure your findings into exactly four categories:
+
+- **Decisions** — architectural or design choices made during this milestone, including rationale and alternatives considered.
+- **Lessons** — technical discoveries, process insights, knowledge gaps that were filled.
+- **Patterns** — reusable approaches or solutions that emerged and should be applied in future work.
+- **Surprises** — unexpected challenges, discoveries, or outcomes that deviated from assumptions.
+
+Every item MUST carry a \`Source:\` line using the format
+\`Source: {artifact-filename}/{section}\` (e.g.
+\`Source: ${ctx.milestoneId}-ROADMAP.md/Architecture Decisions\`).
+Items without a source attribution are invalid — drop them.
+
+### Step 2 — Write the LEARNINGS.md audit trail
+
+Using the \`write\` tool, persist the full structured report to
+\`${ctx.relativeOutputPath}\` with this shape:
+
+- YAML frontmatter with keys: \`phase\`, \`phase_name\`, \`project\`, \`generated\` (ISO-8601 UTC), \`counts\` (decisions / lessons / patterns / surprises), \`missing_artifacts\`.
+- Four H3 sections (\`### Decisions\`, \`### Lessons\`, \`### Patterns\`, \`### Surprises\`) containing bullet points. Each bullet is followed by its \`Source:\` line.
+
+LEARNINGS.md is the full, cited audit trail. Write it first — subsequent steps
+feed from its content.
+
+### Step 3 — Read \`.gsd/KNOWLEDGE.md\` to prepare append
+
+Read \`.gsd/KNOWLEDGE.md\`. It is a markdown file with three tables:
+\`## Rules\`, \`## Patterns\`, and \`## Lessons Learned\`.
+
+If the file does not exist yet, create it first using the \`write\` tool with
+exactly this canonical structure, then treat all tables as empty (next IDs
+\`P001\` / \`L001\`):
+
+\`\`\`
+# Project Knowledge
+
+Append-only register of project-specific rules, patterns, and lessons learned.
+Agents read this before every unit. Add entries when you discover something worth remembering.
+
+## Rules
+
+| # | Scope | Rule | Why | Added |
+|---|-------|------|-----|-------|
+
+## Patterns
+
+| # | Pattern | Where | Notes |
+|---|---------|-------|-------|
+
+## Lessons Learned
+
+| # | What Happened | Root Cause | Fix | Scope |
+|---|--------------|------------|-----|-------|
+\`\`\`
+
+If the file already exists:
+
+- find the highest existing \`P###\` ID in the \`## Patterns\` table — the next pattern ID is that + 1, zero-padded to three digits
+- find the highest existing \`L###\` ID in the \`## Lessons Learned\` table — same rule for the next lesson ID
+- read the existing \`Pattern\` and \`What Happened\` column text so you can skip semantic duplicates in steps 4 and 5
+
+### Step 4 — Append Patterns to \`## Patterns\`
+
+For each extracted Pattern that is **not** already represented in the table
+(semantic match, not exact-string match), append exactly one row to the
+\`## Patterns\` table in \`.gsd/KNOWLEDGE.md\`:
+
+\`\`\`
+| P<NNN> | <Pattern — one concise line> | <Where — component / file / subsystem> | ${ctx.milestoneId} |
+\`\`\`
+
+Rules:
+- Zero-pad IDs to three digits (\`P017\`, not \`P17\`).
+- Append-only — never reorder, edit, or delete existing rows.
+- If a column value is genuinely unknown, write \`—\` (em-dash). Never leave a cell empty.
+
+### Step 5 — Append Lessons to \`## Lessons Learned\`
+
+For each extracted Lesson that is not already represented, append one row to
+the \`## Lessons Learned\` table:
+
+\`\`\`
+| L<NNN> | <What happened> | <Root cause> | <Fix or forward guidance> | ${ctx.milestoneId} |
+\`\`\`
+
+Same ID numbering, append-only, and em-dash rules as Step 4.
+
+### Step 6 — Do NOT modify the \`## Rules\` table
+
+The \`## Rules\` table holds project-wide constraints authored manually via
+\`/gsd knowledge\`. Milestone learnings never produce rules — leave this
+table untouched.
+
+### Step 7 — Persist Decisions via \`gsd_save_decision\`
+
+For each extracted Decision, call the \`gsd_save_decision\` MCP tool exactly
+once with these parameters:
+
+- \`scope\` (string) — \`"${ctx.milestoneId}"\`
+- \`decision\` (string) — the question or issue that was decided
+- \`choice\` (string) — the concrete option selected
+- \`rationale\` (string) — why this choice was made, with a brief citation to the source artefact
+- \`made_by\` (string) — \`"agent"\`
+- \`revisable\` (string, optional) — \`"yes"\` or \`"no"\` only if the source artefact clearly indicates reversibility; otherwise omit
+
+The tool writes the decision to the GSD database and regenerates
+\`.gsd/DECISIONS.md\` atomically. Never edit \`DECISIONS.md\` manually — the
+file is DB-authoritative and manual edits will be overwritten.
+
+### Step 8 — Surprises stay only in LEARNINGS.md
+
+Surprises are milestone-local context and are NOT cross-session-reusable. Do
+not append them to \`KNOWLEDGE.md\`. Do not persist them via any MCP tool.
+They are captured only in the LEARNINGS.md file written in Step 2.
+
+### Step 9 — Deduplication rule (applies to Steps 4, 5, 7)
+
+Before appending a Pattern or Lesson row, or before calling
+\`gsd_save_decision\`, check whether a semantically equivalent entry already
+exists in the target surface. If so, skip that item entirely. Prefer skipping
+a near-duplicate over creating a second slightly-different row — redundancy
+degrades the signal.`;
+}
+/**
+ * Build the full dispatch prompt for the manual `/gsd extract-learnings` path.
+ *
+ * Composes a header block (title, project, output file), the inlined milestone
+ * artefacts (roadmap, summary, optional verification and UAT reports), and the
+ * canonical {@link buildExtractionStepsBlock} procedure. The same procedure is
+ * rendered verbatim in the auto-mode `complete-milestone` turn via the
+ * `{{extractLearningsSteps}}` placeholder, guaranteeing a single source of
+ * truth for how learnings flow into `KNOWLEDGE.md` and the DECISIONS database.
+ *
+ * Missing optional artefacts are surfaced as a note at the end of the artefact
+ * section so the LLM can mark them explicitly in the LEARNINGS frontmatter.
+ */
+export function buildExtractLearningsPrompt(ctx) {
+    const optionalSections = [];
+    if (ctx.verificationContent) {
+        optionalSections.push(`### Verification Report\n\n${ctx.verificationContent}`);
+    }
+    if (ctx.uatContent) {
+        optionalSections.push(`### UAT Report\n\n${ctx.uatContent}`);
+    }
+    const missingNote = ctx.missingArtifacts.length > 0
+        ? `\nNote: the following optional artefacts were not available: ${ctx.missingArtifacts.join(", ")}\n`
+        : "";
+    const stepsBlock = buildExtractionStepsBlock({
+        milestoneId: ctx.milestoneId,
+        outputPath: ctx.outputPath,
+        relativeOutputPath: ctx.relativeOutputPath,
+    });
+    return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the milestone artefacts inlined below and follow the Structured
+Learnings Extraction procedure in full. The procedure writes LEARNINGS.md
+and routes the durable subset into \`.gsd/KNOWLEDGE.md\` and the DECISIONS
+database so future milestone dispatches benefit from what was learned here.
+
+---
+
+## Artefacts
+
+### Roadmap
+
+${ctx.roadmapContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+${optionalSections.length > 0 ? `\n---\n\n${optionalSections.join("\n\n---\n\n")}\n` : ""}${missingNote}
+---
+
+${stepsBlock}
+`;
+}
+/**
+ * Serialises the YAML frontmatter block prepended to `{MID}-LEARNINGS.md`.
+ *
+ * The output begins and ends with a `---` fence so it can be concatenated
+ * directly with the body. Empty `missingArtifacts` is rendered as an
+ * inline empty list (`missing_artifacts: []`) to keep the frontmatter valid
+ * YAML in every case.
+ */
+export function buildFrontmatter(ctx) {
+    const missingList = ctx.missingArtifacts.length > 0
+        ? ctx.missingArtifacts.map((a) => `  - ${a}`).join("\n")
+        : "  []";
+    const missingValue = ctx.missingArtifacts.length > 0
+        ? `\n${missingList}`
+        : " []";
+    return `---
+phase: ${ctx.milestoneId}
+phase_name: ${ctx.milestoneName}
+project: ${ctx.projectName}
+generated: ${ctx.generatedAt}
+counts:
+  decisions: ${ctx.counts.decisions}
+  lessons: ${ctx.counts.lessons}
+  patterns: ${ctx.counts.patterns}
+  surprises: ${ctx.counts.surprises}
+missing_artifacts:${missingValue}
+---`;
+}
+/**
+ * Extracts the project display name from `.gsd/PROJECT.md` frontmatter.
+ *
+ * Falls back to the project directory's basename if PROJECT.md is missing,
+ * unreadable, or has no `name:` field. Never throws — surfacing the raw
+ * directory name is preferable to crashing an extraction over a display
+ * string.
+ */
+export function extractProjectName(basePath) {
+    const projectMdPath = join(gsdRoot(basePath), "PROJECT.md");
+    if (existsSync(projectMdPath)) {
+        try {
+            const content = readFileSync(projectMdPath, "utf-8");
+            const match = content.match(/^name:\s*(.+)$/m);
+            if (match)
+                return match[1].trim();
+        }
+        catch {
+            // non-fatal
+        }
+    }
+    return basename(basePath);
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+/**
+ * Handles the `/gsd extract-learnings <MID>` slash command.
+ *
+ * Resolves and reads the milestone artefacts, constructs the dispatch prompt
+ * via {@link buildExtractLearningsPrompt}, and triggers a new LLM turn via
+ * `pi.sendMessage({ triggerTurn: true })`. Returns quickly with a UI
+ * notification (not an error) when the milestone cannot be found or required
+ * artefacts are missing, matching the behaviour of sibling `/gsd` commands.
+ */
+export async function handleExtractLearnings(args, ctx, pi) {
+    const { milestoneId } = parseExtractLearningsArgs(args);
+    if (!milestoneId) {
+        ctx.ui.notify("Usage: /gsd extract-learnings <milestoneId>  (e.g. M001)", "warning");
+        return;
+    }
+    // projectRoot() throws GSDNoProjectError if no project found — intentional, handled by dispatcher
+    const basePath = projectRoot();
+    const milestoneDir = resolveMilestonePath(basePath, milestoneId);
+    if (!milestoneDir) {
+        ctx.ui.notify(`Milestone not found: ${milestoneId}`, "error");
+        return;
+    }
+    const artifacts = resolvePhaseArtifacts(milestoneDir, milestoneId);
+    if (artifacts.missingRequired.length > 0) {
+        ctx.ui.notify(`Cannot extract learnings — required artefacts missing: ${artifacts.missingRequired.join(", ")}`, "error");
+        return;
+    }
+    const roadmapContent = readFileSync(artifacts.roadmap, "utf-8");
+    const summaryContent = readFileSync(artifacts.summary, "utf-8");
+    const verificationContent = artifacts.verification
+        ? readFileSync(artifacts.verification, "utf-8")
+        : null;
+    const uatContent = artifacts.uat
+        ? readFileSync(artifacts.uat, "utf-8")
+        : null;
+    const missingArtifacts = [];
+    if (!artifacts.verification)
+        missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+    if (!artifacts.uat)
+        missingArtifacts.push(`${milestoneId}-UAT.md`);
+    const h1Match = roadmapContent.match(/^#\s+(.+)$/m);
+    const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+    const projectName = extractProjectName(basePath);
+    const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+    const relativeOutputPath = relative(basePath, outputPath);
+    const prompt = buildExtractLearningsPrompt({
+        milestoneId,
+        milestoneName,
+        outputPath,
+        relativeOutputPath,
+        roadmapContent,
+        summaryContent,
+        verificationContent,
+        uatContent,
+        missingArtifacts,
+        projectName,
+    });
+    ctx.ui.notify(`Extracting learnings for ${milestoneId}: "${milestoneName}"...`, "info");
+    pi.sendMessage({ customType: "gsd-extract-learnings", content: prompt, display: false }, { triggerTurn: true });
+}

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -5,7 +5,8 @@
  * handleRunHook, handleUpdate, handleSkillHealth
  */
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve as resolvePath, sep } from "node:path";
+import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
@@ -17,8 +18,26 @@ import { projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
-function resolveInstallCommand(pkg) {
+// Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
+// src/update-check.ts — duplicated because tsconfig.resources.json rootDir
+// prevents importing from src/. See #4145 for why the runtime-only check
+// (process.versions.bun) is insufficient: bun's global bin shims are plain
+// symlinks, so the target's #!/usr/bin/env node shebang runs the script under
+// Node even when it was installed by bun.
+function isBunInstall(argv1 = process.argv[1]) {
     if ('bun' in process.versions)
+        return true;
+    if (!argv1)
+        return false;
+    const bunBinDirs = [];
+    if (process.env.BUN_INSTALL)
+        bunBinDirs.push(join(process.env.BUN_INSTALL, "bin"));
+    bunBinDirs.push(join(homedir(), ".bun", "bin"));
+    const resolved = resolvePath(argv1);
+    return bunBinDirs.some((dir) => resolved.startsWith(resolvePath(dir) + sep));
+}
+function resolveInstallCommand(pkg) {
+    if (isBunInstall())
         return `bun add -g ${pkg}`;
     return `npm install -g ${pkg}`;
 }

package/dist/resources/extensions/gsd/commands-maintenance.js

@@ -449,7 +449,7 @@ export async function handleCleanupProjects(args, ctx) {
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx, basePath) {
-    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");
     if (!dbAvailable()) {
@@ -457,12 +457,12 @@ export async function handleRecover(ctx, basePath) {
         return;
     }
     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);
         });
         // 3. Invalidate state cache so deriveState() picks up fresh DB data

package/dist/resources/extensions/gsd/commands-pr-branch.js

@@ -0,0 +1,180 @@
+/**
+ * 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 { execFileSync } from "node:child_process";
+import { nativeGetCurrentBranch, nativeDetectMainBranch, nativeBranchExists, } from "./native-git-bridge.js";
+const EXCLUDED_PATHS = [".gsd", ".planning", "PLAN.md"];
+function git(basePath, args) {
+    return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
+}
+function gitAllowFail(basePath, args) {
+    try {
+        execFileSync("git", args, { cwd: basePath, encoding: "utf-8", stdio: "pipe" });
+    }
+    catch {
+        // ignored — caller opts into non-fatal behavior
+    }
+}
+function hasStagedChanges(basePath) {
+    try {
+        execFileSync("git", ["diff", "--cached", "--quiet"], {
+            cwd: basePath,
+            stdio: "pipe",
+        });
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function isValidBranchName(name) {
+    try {
+        execFileSync("git", ["check-ref-format", "--branch", name], { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getCodeOnlyCommits(basePath, base, head) {
+    try {
+        const allCommits = git(basePath, ["log", "--format=%H", `${base}..${head}`])
+            .split("\n")
+            .filter(Boolean);
+        const codeCommits = [];
+        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, sha) {
+    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, base) {
+    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, ctx) {
+    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;
+    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");
+    }
+}