gsd-pi 2.33.1 → 2.34.0-dev.0150ae9

package/dist/resources/extensions/gsd/provider-error-pause.js

@@ -0,0 +1,60 @@
+/**
+ * Classify a provider error as transient (auto-resume) or permanent (manual resume).
+ *
+ * Transient: rate limits, server errors (500/502/503), overloaded, internal errors.
+ * These are expected to self-resolve and should auto-resume after a delay.
+ *
+ * Permanent: auth errors, invalid API key, billing issues.
+ * These require user intervention and should pause indefinitely.
+ */
+export function classifyProviderError(errorMsg) {
+    const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
+    const isServerError = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i.test(errorMsg);
+    // Permanent errors — never auto-resume
+    const isPermanent = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i.test(errorMsg);
+    if (isPermanent && !isRateLimit) {
+        return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
+    }
+    if (isRateLimit) {
+        // Try to extract retry-after from the message
+        const resetMatch = errorMsg.match(/reset in (\d+)s/i);
+        const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000; // default 60s for rate limits
+        return { isTransient: true, isRateLimit: true, suggestedDelayMs: delayMs };
+    }
+    if (isServerError) {
+        return { isTransient: true, isRateLimit: false, suggestedDelayMs: 30_000 }; // 30s for server errors
+    }
+    // Unknown error — treat as permanent (user reviews)
+    return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
+}
+/**
+ * Pause auto-mode due to a provider error.
+ *
+ * For transient errors (rate limits, server errors, overloaded), schedules
+ * an automatic resume after a delay. For permanent errors (auth, billing),
+ * pauses indefinitely — user must manually resume.
+ */
+export async function pauseAutoForProviderError(ui, errorDetail, pause, options) {
+    const shouldAutoResume = (options?.isRateLimit || options?.isTransient)
+        && options.retryAfterMs
+        && options.retryAfterMs > 0
+        && options.resume;
+    if (shouldAutoResume) {
+        const delaySec = Math.ceil(options.retryAfterMs / 1000);
+        const reason = options.isRateLimit ? "Rate limited" : "Server error (transient)";
+        ui.notify(`${reason}${errorDetail}. Auto-resuming in ${delaySec}s...`, "warning");
+        await pause();
+        // Schedule auto-resume after the delay
+        setTimeout(() => {
+            const resumeMsg = options.isRateLimit
+                ? "Rate limit window elapsed. Resuming auto-mode."
+                : "Server error recovery delay elapsed. Resuming auto-mode.";
+            ui.notify(resumeMsg, "info");
+            options.resume();
+        }, options.retryAfterMs);
+    }
+    else {
+        ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
+        await pause();
+    }
+}

package/dist/resources/extensions/gsd/queue-order.js

@@ -0,0 +1,178 @@
+/**
+ * GSD Queue Order — Custom milestone execution ordering.
+ *
+ * Stores an explicit execution order in `.gsd/QUEUE-ORDER.json`.
+ * When present, `findMilestoneIds()` uses this order instead of
+ * the default numeric sort (milestoneIdSort).
+ *
+ * The file is committed to git (not gitignored) so ordering
+ * survives branch switches and is shared across sessions.
+ */
+import { join } from "node:path";
+import { gsdRoot } from "./paths.js";
+import { milestoneIdSort } from "./milestone-ids.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+// ─── Path ────────────────────────────────────────────────────────────────────
+function queueOrderPath(basePath) {
+    return join(gsdRoot(basePath), "QUEUE-ORDER.json");
+}
+// ─── Type Guards ─────────────────────────────────────────────────────────────
+function isQueueOrderFile(data) {
+    return data !== null && typeof data === "object" && "order" in data && Array.isArray(data.order);
+}
+// ─── Read / Write ────────────────────────────────────────────────────────────
+/**
+ * Load the custom queue order. Returns null if no file exists or if
+ * the file is corrupt/unreadable.
+ */
+export function loadQueueOrder(basePath) {
+    const data = loadJsonFileOrNull(queueOrderPath(basePath), isQueueOrderFile);
+    return data?.order ?? null;
+}
+/**
+ * Save a custom queue order to disk.
+ */
+export function saveQueueOrder(basePath, order) {
+    const data = {
+        order,
+        updatedAt: new Date().toISOString(),
+    };
+    saveJsonFile(queueOrderPath(basePath), data);
+}
+// ─── Sorting ─────────────────────────────────────────────────────────────────
+/**
+ * Sort milestone IDs respecting a custom order.
+ *
+ * - IDs present in `customOrder` appear in that exact sequence.
+ * - IDs on disk but NOT in `customOrder` are appended at the end,
+ *   sorted by the default `milestoneIdSort` (numeric).
+ * - IDs in `customOrder` but NOT on disk are silently skipped.
+ * - When `customOrder` is null, falls back to `milestoneIdSort`.
+ */
+export function sortByQueueOrder(ids, customOrder) {
+    if (!customOrder)
+        return [...ids].sort(milestoneIdSort);
+    const idSet = new Set(ids);
+    const ordered = [];
+    // First: IDs from customOrder that exist on disk
+    for (const id of customOrder) {
+        if (idSet.has(id)) {
+            ordered.push(id);
+            idSet.delete(id);
+        }
+    }
+    // Then: remaining IDs not in customOrder, in default sort order
+    const remaining = [...idSet].sort(milestoneIdSort);
+    return [...ordered, ...remaining];
+}
+// ─── Pruning ─────────────────────────────────────────────────────────────────
+/**
+ * Remove IDs from the queue order file that are no longer valid
+ * (completed or deleted milestones). No-op if file doesn't exist.
+ */
+export function pruneQueueOrder(basePath, validIds) {
+    const order = loadQueueOrder(basePath);
+    if (!order)
+        return;
+    const validSet = new Set(validIds);
+    const pruned = order.filter(id => validSet.has(id));
+    if (pruned.length !== order.length) {
+        saveQueueOrder(basePath, pruned);
+    }
+}
+// ─── Validation ──────────────────────────────────────────────────────────────
+/**
+ * Validate a proposed queue order against dependency constraints.
+ *
+ * Checks:
+ * - would_block: A milestone is placed before one of its dependencies
+ * - circular: Two or more milestones form a dependency cycle
+ * - missing_dep: A milestone depends on an ID that doesn't exist
+ * - redundant: A dependency is satisfied by queue position (dep comes earlier)
+ */
+export function validateQueueOrder(order, depsMap, completedIds) {
+    const violations = [];
+    const redundant = [];
+    const positionMap = new Map();
+    for (let i = 0; i < order.length; i++) {
+        positionMap.set(order[i], i);
+    }
+    const allKnownIds = new Set([...order, ...completedIds]);
+    for (const [mid, deps] of depsMap) {
+        const midPos = positionMap.get(mid);
+        if (midPos === undefined)
+            continue; // not in pending order
+        for (const dep of deps) {
+            // Dep already completed — always satisfied
+            if (completedIds.has(dep))
+                continue;
+            // Dep doesn't exist anywhere
+            if (!allKnownIds.has(dep)) {
+                violations.push({
+                    milestone: mid,
+                    dependsOn: dep,
+                    type: 'missing_dep',
+                    message: `${mid} depends on ${dep}, but ${dep} does not exist.`,
+                });
+                continue;
+            }
+            const depPos = positionMap.get(dep);
+            if (depPos === undefined)
+                continue; // dep not in pending order (edge case)
+            if (depPos > midPos) {
+                // Dep comes AFTER this milestone in the order — violation
+                violations.push({
+                    milestone: mid,
+                    dependsOn: dep,
+                    type: 'would_block',
+                    message: `${mid} cannot run before ${dep} — ${mid} depends_on: [${dep}].`,
+                });
+            }
+            else {
+                // Dep comes before — satisfied by position, redundant
+                redundant.push({ milestone: mid, dependsOn: dep });
+            }
+        }
+    }
+    // Check for circular dependencies
+    const visited = new Set();
+    const inStack = new Set();
+    function hasCycle(node, path) {
+        if (inStack.has(node))
+            return [...path, node];
+        if (visited.has(node))
+            return null;
+        visited.add(node);
+        inStack.add(node);
+        const deps = depsMap.get(node) ?? [];
+        for (const dep of deps) {
+            if (completedIds.has(dep))
+                continue;
+            const cycle = hasCycle(dep, [...path, node]);
+            if (cycle)
+                return cycle;
+        }
+        inStack.delete(node);
+        return null;
+    }
+    for (const mid of order) {
+        if (!visited.has(mid)) {
+            const cycle = hasCycle(mid, []);
+            if (cycle) {
+                const cycleStr = cycle.join(' → ');
+                violations.push({
+                    milestone: cycle[0],
+                    dependsOn: cycle[cycle.length - 2],
+                    type: 'circular',
+                    message: `Circular dependency: ${cycleStr}`,
+                });
+                break; // one cycle report is enough
+            }
+        }
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+        redundant,
+    };
+}

package/dist/resources/extensions/gsd/queue-reorder-ui.js

@@ -0,0 +1,234 @@
+/**
+ * GSD Queue Reorder UI
+ *
+ * Interactive TUI overlay for reordering pending milestones.
+ * ↑/↓ navigates cursor. Space grabs/releases item for moving.
+ * While grabbed, ↑/↓ swaps the item with its neighbor.
+ * Enter confirms all changes. Esc cancels.
+ * Conflicting depends_on entries are auto-removed on confirm.
+ */
+import { Key, matchesKey, truncateToWidth } from "@gsd/pi-tui";
+import { makeUI, GLYPH } from "../shared/mod.js";
+import { validateQueueOrder } from "./queue-order.js";
+/**
+ * Show the queue reorder overlay.
+ * Returns the new order + deps to remove, or null if cancelled.
+ */
+export async function showQueueReorder(ctx, completed, pending) {
+    if (!ctx.hasUI)
+        return null;
+    if (pending.length < 2)
+        return null;
+    const result = await ctx.ui.custom((tui, theme, _kb, done) => {
+        const items = [...pending];
+        let cursor = 0;
+        let grabbed = false;
+        let cachedLines;
+        let validation;
+        // Mutable deps map — tracks removals during this session
+        const liveDeps = new Map();
+        for (const item of [...completed, ...pending]) {
+            if (item.dependsOn && item.dependsOn.length > 0) {
+                liveDeps.set(item.id, [...item.dependsOn]);
+            }
+        }
+        const removedDeps = [];
+        const completedIds = new Set(completed.map(c => c.id));
+        function revalidate() {
+            validation = validateQueueOrder(items.map(i => i.id), liveDeps, completedIds);
+        }
+        revalidate();
+        function refresh() {
+            cachedLines = undefined;
+            tui.requestRender();
+        }
+        function swapItems(fromIdx, toIdx) {
+            if (toIdx < 0 || toIdx >= items.length)
+                return;
+            const [item] = items.splice(fromIdx, 1);
+            items.splice(toIdx, 0, item);
+            cursor = toIdx;
+            revalidate();
+            refresh();
+        }
+        function removeDep(milestone, dep) {
+            const deps = liveDeps.get(milestone);
+            if (!deps)
+                return;
+            const idx = deps.indexOf(dep);
+            if (idx >= 0) {
+                deps.splice(idx, 1);
+                if (deps.length === 0)
+                    liveDeps.delete(milestone);
+                removedDeps.push({ milestone, dep });
+                const item = items.find(i => i.id === milestone);
+                if (item?.dependsOn) {
+                    item.dependsOn = item.dependsOn.filter(d => d !== dep);
+                }
+                revalidate();
+                refresh();
+            }
+        }
+        function handleInput(data) {
+            if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+                done(null);
+                return;
+            }
+            // Confirm — auto-resolve would_block violations
+            if (matchesKey(data, Key.enter)) {
+                const wouldBlock = validation.violations.filter(v => v.type === 'would_block');
+                for (const v of wouldBlock) {
+                    removeDep(v.milestone, v.dependsOn);
+                }
+                done({ order: items.map(i => i.id), depsToRemove: removedDeps });
+                return;
+            }
+            // Space — toggle grab mode
+            if (data === " ") {
+                grabbed = !grabbed;
+                refresh();
+                return;
+            }
+            // ↑/↓ — move grabbed item OR navigate cursor
+            if (matchesKey(data, Key.up)) {
+                if (grabbed) {
+                    swapItems(cursor, cursor - 1);
+                }
+                else {
+                    cursor = Math.max(0, cursor - 1);
+                    refresh();
+                }
+                return;
+            }
+            if (matchesKey(data, Key.down)) {
+                if (grabbed) {
+                    swapItems(cursor, cursor + 1);
+                }
+                else {
+                    cursor = Math.min(items.length - 1, cursor + 1);
+                    refresh();
+                }
+                return;
+            }
+            // 'd' — manually remove a dep on the cursor item
+            if (data === "d" || data === "D") {
+                const item = items[cursor];
+                const deps = liveDeps.get(item.id);
+                if (deps) {
+                    const activeDep = deps.find(d => !completedIds.has(d));
+                    if (activeDep)
+                        removeDep(item.id, activeDep);
+                }
+                return;
+            }
+        }
+        function render(width) {
+            if (cachedLines)
+                return cachedLines;
+            const ui = makeUI(theme, width);
+            const lines = [];
+            const push = (...rows) => { for (const r of rows)
+                lines.push(...r); };
+            const add = (s) => truncateToWidth(s, width);
+            const headerText = grabbed ? "  Queue Reorder — Moving Item" : "  Queue Reorder";
+            push(ui.bar(), ui.blank(), ui.header(headerText), ui.blank());
+            // Completed milestones (dimmed)
+            if (completed.length > 0) {
+                lines.push(add(theme.fg("dim", "  Completed:")));
+                for (const m of completed) {
+                    const label = m.title && m.title !== m.id ? `${m.id}  ${m.title}` : m.id;
+                    lines.push(add(`    ${theme.fg("dim", `${GLYPH.statusDone} ${label}`)}`));
+                }
+                push(ui.blank());
+            }
+            // Pending milestones
+            const queueLabel = grabbed ? "  Queue (space to release, ↑/↓ to move):" : "  Queue (space to grab, ↑/↓ to navigate):";
+            lines.push(add(theme.fg("text", queueLabel)));
+            const violatedPairs = new Set(validation.violations.filter(v => v.type === 'would_block').map(v => `${v.milestone}:${v.dependsOn}`));
+            const redundantPairs = new Set(validation.redundant.map(r => `${r.milestone}:${r.dependsOn}`));
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const isCursor = i === cursor;
+                const num = i + 1;
+                const label = item.title && item.title !== item.id ? `${item.id}  ${item.title}` : item.id;
+                if (isCursor && grabbed) {
+                    lines.push(add(`  ${theme.fg("warning", `▸▸ ${num}. ${label}`)}`));
+                }
+                else if (isCursor) {
+                    lines.push(add(`  ${theme.fg("accent", `${GLYPH.cursor} ${num}. ${label}`)}`));
+                }
+                else {
+                    lines.push(add(`    ${theme.fg("text", `${num}. ${label}`)}`));
+                }
+                // depends_on annotations
+                const deps = liveDeps.get(item.id) ?? [];
+                for (const dep of deps) {
+                    if (completedIds.has(dep))
+                        continue;
+                    const pairKey = `${item.id}:${dep}`;
+                    if (violatedPairs.has(pairKey)) {
+                        lines.push(add(`       ${theme.fg("warning", `${GLYPH.statusWarning} depends_on: ${dep} — auto-removed on confirm`)}`));
+                    }
+                    else if (redundantPairs.has(pairKey)) {
+                        lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep} (redundant)`)}`));
+                    }
+                    else {
+                        lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep}`)}`));
+                    }
+                }
+                // Missing deps
+                for (const v of validation.violations.filter(v => v.milestone === item.id && v.type === 'missing_dep')) {
+                    lines.push(add(`       ${theme.fg("error", `${GLYPH.statusWarning} depends_on: ${v.dependsOn} (does not exist)`)}`));
+                }
+            }
+            // Removed deps feedback
+            if (removedDeps.length > 0) {
+                push(ui.blank());
+                for (const r of removedDeps) {
+                    lines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
+                }
+            }
+            // Circular warning
+            const circ = validation.violations.find(v => v.type === 'circular');
+            if (circ) {
+                push(ui.blank());
+                lines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
+            }
+            push(ui.blank());
+            // Hints — context-sensitive based on grab state
+            const hints = [];
+            if (grabbed) {
+                hints.push("↑/↓ move item", "space release");
+            }
+            else {
+                hints.push("↑/↓ navigate", "space grab");
+            }
+            const hasDeps = liveDeps.get(items[cursor]?.id)?.some(d => !completedIds.has(d));
+            if (hasDeps)
+                hints.push("d del dep");
+            const wouldBlockCount = validation.violations.filter(v => v.type === 'would_block').length;
+            if (wouldBlockCount > 0) {
+                hints.push(`enter (fixes ${wouldBlockCount} dep)`);
+            }
+            else {
+                hints.push("enter ok");
+            }
+            hints.push("esc");
+            push(ui.hints(hints), ui.bar());
+            cachedLines = lines;
+            return lines;
+        }
+        return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+    }, {
+        overlay: true,
+        overlayOptions: { width: "70%", minWidth: 50, maxHeight: "80%", anchor: "center" },
+    });
+    // Fallback for RPC mode where ctx.ui.custom() returns undefined.
+    // Reorder requires interactive input — notify and return null.
+    if (result === undefined) {
+        ctx.ui.notify("Queue reorder requires an interactive terminal. Current order: " +
+            pending.map(p => p.id).join(" → "), "warning");
+        return null;
+    }
+    return result;
+}

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

@@ -0,0 +1,206 @@
+/**
+ * GSD Quick Mode — /gsd quick <task>
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ *
+ * Lightweight task execution with GSD guarantees (atomic commits, state
+ * tracking) but without the full milestone/slice ceremony.
+ *
+ * Quick tasks live in `.gsd/quick/` and are tracked in STATE.md's
+ * "Quick Tasks Completed" table.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadPrompt } from "./prompt-loader.js";
+import { gsdRoot } from "./paths.js";
+import { GitServiceImpl, runGit } from "./git-service.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { nativeHasStagedChanges } from "./native-git-bridge.js";
+let pendingQuickReturn = null;
+// ─── Quick Task Helpers ───────────────────────────────────────────────────────
+/**
+ * Generate a URL-friendly slug from a description.
+ * Lowercase, hyphens, max 40 chars.
+ */
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40)
+        .replace(/-$/, "");
+}
+/**
+ * Determine the next quick task number by scanning existing directories.
+ */
+function getNextTaskNum(quickDir) {
+    if (!existsSync(quickDir))
+        return 1;
+    try {
+        const entries = readdirSync(quickDir, { withFileTypes: true });
+        let max = 0;
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const match = entry.name.match(/^(\d+)-/);
+            if (match) {
+                const num = parseInt(match[1], 10);
+                if (num > max)
+                    max = num;
+            }
+        }
+        return max + 1;
+    }
+    catch {
+        return 1;
+    }
+}
+/**
+ * Ensure the quick task directory structure exists.
+ * Returns the task directory path.
+ */
+function ensureQuickDir(basePath, taskNum, slug) {
+    const quickDir = join(gsdRoot(basePath), "quick");
+    const taskDir = join(quickDir, `${taskNum}-${slug}`);
+    mkdirSync(taskDir, { recursive: true });
+    return taskDir;
+}
+function quickReturnStatePath(basePath) {
+    return join(gsdRoot(basePath), "runtime", "quick-return.json");
+}
+function persistPendingReturn(state) {
+    pendingQuickReturn = state;
+    mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
+    writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
+}
+function readPendingReturn(basePath) {
+    if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
+        return pendingQuickReturn;
+    }
+    try {
+        const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.basePath === "string"
+            && typeof parsed.originalBranch === "string"
+            && typeof parsed.quickBranch === "string"
+            && typeof parsed.taskNum === "number"
+            && typeof parsed.slug === "string"
+            && typeof parsed.description === "string") {
+            pendingQuickReturn = parsed;
+            return pendingQuickReturn;
+        }
+    }
+    catch {
+        // No persisted quick-return state
+    }
+    return null;
+}
+function clearPendingReturn(basePath) {
+    if (pendingQuickReturn?.basePath === basePath) {
+        pendingQuickReturn = null;
+    }
+    rmSync(quickReturnStatePath(basePath), { force: true });
+}
+function hasStagedChanges(basePath) {
+    return nativeHasStagedChanges(basePath);
+}
+export function cleanupQuickBranch(basePath = process.cwd()) {
+    const state = readPendingReturn(basePath);
+    if (!state)
+        return false;
+    const repoPath = state.basePath;
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+    const git = new GitServiceImpl(repoPath, gitPrefs);
+    if (git.getCurrentBranch() === state.quickBranch) {
+        try {
+            git.autoCommit("quick-task", `Q${state.taskNum}`, []);
+        }
+        catch {
+            // Best-effort: quick work may already be committed.
+        }
+    }
+    if (git.getCurrentBranch() !== state.originalBranch) {
+        runGit(repoPath, ["checkout", state.originalBranch]);
+    }
+    runGit(repoPath, ["merge", "--squash", state.quickBranch]);
+    if (hasStagedChanges(repoPath)) {
+        runGit(repoPath, ["commit", "-m", `quick(Q${state.taskNum}): ${state.slug}`]);
+    }
+    runGit(repoPath, ["branch", "-D", state.quickBranch], { allowFailure: true });
+    clearPendingReturn(repoPath);
+    return true;
+}
+// ─── Main Handler ─────────────────────────────────────────────────────────────
+export async function handleQuick(args, ctx, pi) {
+    const basePath = process.cwd();
+    const root = gsdRoot(basePath);
+    // Validate: .gsd/ must exist
+    if (!existsSync(root)) {
+        ctx.ui.notify("No .gsd/ directory found. Run /gsd to initialize a project first.", "error");
+        return;
+    }
+    // Parse description from args
+    let description = args.trim();
+    if (!description) {
+        ctx.ui.notify("Usage: /gsd quick <task description>\n\nExample: /gsd quick fix login button not responding on mobile", "info");
+        return;
+    }
+    // Setup
+    const quickDir = join(root, "quick");
+    const taskNum = getNextTaskNum(quickDir);
+    const slug = slugify(description);
+    const taskDir = ensureQuickDir(basePath, taskNum, slug);
+    const taskDirRel = `.gsd/quick/${taskNum}-${slug}`;
+    const date = new Date().toISOString().split("T")[0];
+    // Create git branch for the quick task
+    const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+    const git = new GitServiceImpl(basePath, gitPrefs);
+    const branchName = `gsd/quick/${taskNum}-${slug}`;
+    let originalBranch = git.getCurrentBranch();
+    let branchCreated = false;
+    try {
+        const current = originalBranch;
+        if (current !== branchName) {
+            // Auto-commit any dirty state before switching
+            try {
+                git.autoCommit("quick-task", `Q${taskNum}`, []);
+            }
+            catch { /* nothing to commit — fine */ }
+            runGit(basePath, ["checkout", "-b", branchName]);
+            branchCreated = true;
+        }
+    }
+    catch (err) {
+        // Branch creation failed — continue on current branch
+        const message = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Could not create branch ${branchName}: ${message}. Working on current branch.`, "warning");
+    }
+    const actualBranch = branchCreated ? branchName : git.getCurrentBranch();
+    if (actualBranch === branchName && originalBranch !== branchName) {
+        persistPendingReturn({
+            basePath,
+            originalBranch,
+            quickBranch: branchName,
+            taskNum,
+            slug,
+            description,
+        });
+    }
+    // Notify user
+    ctx.ui.notify(`Quick task ${taskNum}: ${description}\nDirectory: ${taskDirRel}\nBranch: ${actualBranch}`, "info");
+    // Build and dispatch the quick task prompt
+    const summaryPath = `${taskDirRel}/${taskNum}-SUMMARY.md`;
+    const prompt = loadPrompt("quick-task", {
+        description,
+        taskDir: taskDirRel,
+        branch: actualBranch,
+        summaryPath,
+        date,
+        taskNum: String(taskNum),
+        slug,
+    });
+    pi.sendMessage({
+        customType: "gsd-quick-task",
+        content: prompt,
+        display: false,
+    }, { triggerTurn: true });
+}