gsd-pi 2.74.0 → 2.75.0-dev.fd2382b9f

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

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { handleQuick } from "../../quick.js";
 import { showDiscuss, showHeadlessMilestoneCreation, showQueue } from "../../guided-flow.js";
-import { handleStart, handleTemplates } from "../../commands-workflow-templates.js";
+import { handleStart, handleTemplates, dispatchMarkdownPhasePlugin } from "../../commands-workflow-templates.js";
 import { gsdRoot } from "../../paths.js";
 import { deriveState } from "../../state.js";
 import { isParked, parkMilestone, unparkMilestone } from "../../milestone-actions.js";
@@ -14,44 +14,168 @@ import { projectRoot } from "../context.js";
 import { createRun, listRuns } from "../../run-manager.js";
 import { setActiveEngineId, setActiveRunDir, startAutoDetached, pauseAuto, isAutoActive, getActiveEngineId, } from "../../auto.js";
 import { validateDefinition } from "../../definition-loader.js";
+import { formatPluginInfo, listPluginsFormatted, resolvePlugin, } from "../../workflow-plugins.js";
+import { dispatchOneshot } from "../../workflow-dispatch.js";
+import { fetchWorkflowSource, globalInstallDir, inferPluginName, installPlugin, previewContent, projectInstallDir, resolveSourceUrl, uninstallPlugin, validateFetchedContent, } from "../../workflow-install.js";
 // ─── Custom Workflow Subcommands ─────────────────────────────────────────
+const RESERVED_SUBCOMMANDS = new Set([
+    "new", "run", "list", "validate", "pause", "resume",
+    "info", "install", "uninstall",
+]);
 const WORKFLOW_USAGE = [
-    "Usage: /gsd workflow <subcommand>",
+    "Usage: /gsd workflow [<name> | <subcommand>]",
     "",
+    "  <name> [args]     — Run a plugin directly (resolves project/global/bundled)",
     "  new               — Create a new workflow definition (via skill)",
-    "  run <name> [k=v]  — Create a run and start auto-mode",
+    "  run <name> [k=v]  — Explicit YAML run (creates a new run dir)",
     "  list [name]       — List workflow runs (optionally filtered by name)",
+    "  info <name>       — Show plugin details (source, mode, phases)",
+    "  install <source>  — Install a plugin from a URL / gist: / gh:",
+    "  uninstall <name>  — Remove an installed plugin",
     "  validate <name>   — Validate a workflow definition YAML",
     "  pause             — Pause custom workflow auto-mode",
     "  resume            — Resume paused custom workflow auto-mode",
 ].join("\n");
+function splitWorkflowRunArgs(input) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escapeNext = false;
+    for (const ch of input) {
+        if (escapeNext) {
+            current += ch;
+            escapeNext = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escapeNext = true;
+            continue;
+        }
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (escapeNext)
+        current += "\\";
+    if (current)
+        tokens.push(current);
+    return tokens;
+}
+export function parseWorkflowRunArgs(args) {
+    const parts = splitWorkflowRunArgs(args);
+    const defName = parts[0] ?? "";
+    const overrides = {};
+    for (let i = 1; i < parts.length; i++) {
+        const eqIdx = parts[i].indexOf("=");
+        if (eqIdx > 0) {
+            overrides[parts[i].slice(0, eqIdx)] = parts[i].slice(eqIdx + 1);
+        }
+    }
+    return { defName, overrides };
+}
+/**
+ * Parse every token as an optional `k=v` override. Use when the workflow name
+ * is already known (e.g., direct `/gsd workflow <name> ...` dispatch) so the
+ * first token isn't eaten as a def name.
+ */
+export function parseWorkflowOverridesOnly(args) {
+    const parts = splitWorkflowRunArgs(args);
+    const overrides = {};
+    for (const part of parts) {
+        const eqIdx = part.indexOf("=");
+        if (eqIdx > 0) {
+            overrides[part.slice(0, eqIdx)] = part.slice(eqIdx + 1);
+        }
+    }
+    return overrides;
+}
+/**
+ * Dispatch a resolved plugin according to its declared mode.
+ */
+function dispatchPluginByMode(plugin, args, ctx, pi) {
+    switch (plugin.meta.mode) {
+        case "oneshot": {
+            dispatchOneshot(plugin, pi, args.trim());
+            ctx.ui.notify(`Running oneshot workflow: ${plugin.meta.displayName}`, "info");
+            return;
+        }
+        case "yaml-step": {
+            const overrides = parseWorkflowOverridesOnly(args);
+            try {
+                const base = projectRoot();
+                const runDir = createRun(base, plugin.name, Object.keys(overrides).length > 0 ? overrides : undefined);
+                setActiveEngineId("custom");
+                setActiveRunDir(runDir);
+                ctx.ui.notify(`Created workflow run: ${plugin.name}\nRun dir: ${runDir}`, "info");
+                startAutoDetached(ctx, pi, base, false);
+            }
+            catch (err) {
+                setActiveEngineId(null);
+                setActiveRunDir(null);
+                const msg = err instanceof Error ? err.message : String(err);
+                ctx.ui.notify(`Failed to run workflow "${plugin.name}": ${msg}`, "error");
+            }
+            return;
+        }
+        case "markdown-phase": {
+            if (isAutoActive()) {
+                ctx.ui.notify("Cannot start a markdown-phase workflow while auto-mode is running.\n" +
+                    "Run /gsd pause first.", "warning");
+                return;
+            }
+            // Delegate to commands-workflow-templates which handles branch + state file.
+            dispatchMarkdownPhasePlugin(plugin, args.trim(), ctx, pi);
+            return;
+        }
+        case "auto-milestone": {
+            ctx.ui.notify(`'${plugin.name}' runs via the full milestone pipeline.\n` +
+                `Use /gsd auto or /gsd start ${plugin.name}.`, "info");
+            return;
+        }
+    }
+}
 async function handleCustomWorkflow(sub, ctx, pi) {
-    // Bare `/gsd workflow` — show usage
+    // Bare `/gsd workflow` — list plugins
     if (!sub) {
-        ctx.ui.notify(WORKFLOW_USAGE, "info");
+        const base = projectRoot();
+        const listing = listPluginsFormatted(base);
+        ctx.ui.notify(listing, "info");
         return true;
     }
+    // Split into head + rest for subcommand detection.
+    const spaceIdx = sub.indexOf(" ");
+    const head = (spaceIdx === -1 ? sub : sub.slice(0, spaceIdx)).trim();
+    const rest = spaceIdx === -1 ? "" : sub.slice(spaceIdx + 1).trim();
     // ── new ──
-    if (sub === "new") {
+    if (head === "new") {
         ctx.ui.notify("Use the create-workflow skill: /skill create-workflow", "info");
         return true;
     }
     // ── run <name> [param=value ...] ──
-    if (sub === "run" || sub.startsWith("run ")) {
-        const args = sub.slice("run".length).trim();
-        if (!args) {
+    if (head === "run") {
+        if (!rest) {
             ctx.ui.notify("Usage: /gsd workflow run <name> [param=value ...]", "warning");
             return true;
         }
-        const parts = args.split(/\s+/);
-        const defName = parts[0];
-        const overrides = {};
-        for (let i = 1; i < parts.length; i++) {
-            const eqIdx = parts[i].indexOf("=");
-            if (eqIdx > 0) {
-                overrides[parts[i].slice(0, eqIdx)] = parts[i].slice(eqIdx + 1);
-            }
-        }
+        const { defName, overrides } = parseWorkflowRunArgs(rest);
         try {
             const base = projectRoot();
             const runDir = createRun(base, defName, Object.keys(overrides).length > 0 ? overrides : undefined);
@@ -61,7 +185,6 @@ async function handleCustomWorkflow(sub, ctx, pi) {
             startAutoDetached(ctx, pi, base, false);
         }
         catch (err) {
-            // Clean up engine state so a failed workflow run doesn't pollute the next /gsd auto
             setActiveEngineId(null);
             setActiveRunDir(null);
             const msg = err instanceof Error ? err.message : String(err);
@@ -69,11 +192,10 @@ async function handleCustomWorkflow(sub, ctx, pi) {
         }
         return true;
     }
-    // ── list [name] ──
-    if (sub === "list" || sub.startsWith("list ")) {
-        const filterName = sub.slice("list".length).trim() || undefined;
+    // ── list [name] — list YAML runs ──
+    if (head === "list") {
         const base = projectRoot();
-        const runs = listRuns(base, filterName);
+        const runs = listRuns(base, rest || undefined);
         if (runs.length === 0) {
             ctx.ui.notify("No workflow runs found.", "info");
             return true;
@@ -85,38 +207,152 @@ async function handleCustomWorkflow(sub, ctx, pi) {
         ctx.ui.notify(lines.join("\n"), "info");
         return true;
     }
+    // ── info <name> ──
+    if (head === "info") {
+        if (!rest) {
+            ctx.ui.notify("Usage: /gsd workflow info <name>", "warning");
+            return true;
+        }
+        const base = projectRoot();
+        const plugin = resolvePlugin(base, rest);
+        if (!plugin) {
+            ctx.ui.notify(`Plugin not found: ${rest}\nRun /gsd workflow to list plugins.`, "warning");
+            return true;
+        }
+        ctx.ui.notify(formatPluginInfo(plugin), "info");
+        return true;
+    }
+    // ── install <source> [--project] [--name <override>] ──
+    if (head === "install") {
+        if (!rest) {
+            ctx.ui.notify("Usage: /gsd workflow install <source> [--project] [--name <n>]\n\n" +
+                "Sources:\n" +
+                "  https://…/path/workflow.yaml\n" +
+                "  gist:<id>\n" +
+                "  gh:owner/repo/path[@ref]", "warning");
+            return true;
+        }
+        const tokens = rest.split(/\s+/);
+        let source = "";
+        let scope = "global";
+        let nameOverride;
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t === "--project")
+                scope = "project";
+            else if (t === "--name")
+                nameOverride = tokens[++i];
+            else if (t && !source)
+                source = t;
+        }
+        const base = projectRoot();
+        try {
+            const url = resolveSourceUrl(source);
+            ctx.ui.notify(`Fetching ${url}…`, "info");
+            const fetched = await fetchWorkflowSource(url);
+            validateFetchedContent(fetched);
+            const name = nameOverride ? nameOverride.trim().toLowerCase() : inferPluginName(fetched);
+            if (!name)
+                throw new Error("Could not infer plugin name. Use --name <n>.");
+            const target = scope === "global"
+                ? { scope: "global", dir: globalInstallDir() }
+                : { scope: "project", dir: projectInstallDir(base) };
+            const preview = previewContent(fetched.content, 20);
+            const summary = [
+                `Install workflow plugin:`,
+                `  Source:    ${fetched.url}`,
+                `  Name:      ${name}`,
+                `  Format:    ${fetched.ext.slice(1)}`,
+                `  Target:    ${join(target.dir, `${name}${fetched.ext}`)}`,
+                `  Scope:     ${target.scope}`,
+                "",
+                `Preview (first 20 lines):`,
+                "  " + preview.split("\n").join("\n  "),
+                "",
+                `Proceeding with install. Run /gsd workflow uninstall ${name} to revert.`,
+            ].join("\n");
+            ctx.ui.notify(summary, "info");
+            const result = installPlugin(target, fetched, name);
+            ctx.ui.notify(`✓ Installed plugin "${result.name}" (${result.ext.slice(1)}) to ${result.path}`, "info");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Failed to install: ${msg}`, "error");
+        }
+        return true;
+    }
+    // ── uninstall <name> ──
+    if (head === "uninstall") {
+        if (!rest) {
+            ctx.ui.notify("Usage: /gsd workflow uninstall <name>", "warning");
+            return true;
+        }
+        const base = projectRoot();
+        const result = uninstallPlugin(base, rest.trim());
+        if (!result.removed) {
+            ctx.ui.notify(`No installed plugin named "${rest}" found in ${globalInstallDir()} or ${projectInstallDir(base)}.`, "warning");
+            return true;
+        }
+        const warning = result.warnedNotInProvenance
+            ? " (no provenance record — was this hand-authored?)"
+            : "";
+        ctx.ui.notify(`✓ Removed ${result.path}${warning}`, "info");
+        return true;
+    }
     // ── validate <name> ──
-    if (sub === "validate" || sub.startsWith("validate ")) {
-        const defName = sub.slice("validate".length).trim();
-        if (!defName) {
+    if (head === "validate") {
+        if (!rest) {
             ctx.ui.notify("Usage: /gsd workflow validate <name>", "warning");
             return true;
         }
         const base = projectRoot();
-        const defPath = join(base, ".gsd", "workflow-defs", `${defName}.yaml`);
-        if (!existsSync(defPath)) {
-            ctx.ui.notify(`Definition not found: ${defPath}`, "error");
-            return true;
+        const plugin = resolvePlugin(base, rest);
+        let raw;
+        let sourceLabel;
+        if (plugin && plugin.format === "yaml") {
+            try {
+                raw = readFileSync(plugin.path, "utf-8");
+                sourceLabel = plugin.path;
+            }
+            catch (err) {
+                ctx.ui.notify(`Failed to read definition: ${err instanceof Error ? err.message : String(err)}`, "error");
+                return true;
+            }
+        }
+        else {
+            // Legacy fallback path for names that don't resolve via plugins.
+            const defPath = join(base, ".gsd", "workflow-defs", `${rest}.yaml`);
+            if (!existsSync(defPath)) {
+                ctx.ui.notify(`Definition not found: ${defPath}`, "error");
+                return true;
+            }
+            try {
+                raw = readFileSync(defPath, "utf-8");
+                sourceLabel = defPath;
+            }
+            catch (err) {
+                ctx.ui.notify(`Failed to read definition: ${err instanceof Error ? err.message : String(err)}`, "error");
+                return true;
+            }
         }
         try {
-            const raw = readFileSync(defPath, "utf-8");
             const parsed = parseYaml(raw);
             const result = validateDefinition(parsed);
             if (result.valid) {
-                ctx.ui.notify(`✓ "${defName}" is a valid workflow definition.`, "info");
+                ctx.ui.notify(`✓ "${rest}" is a valid workflow definition (${sourceLabel}).`, "info");
             }
             else {
-                ctx.ui.notify(`✗ "${defName}" has errors:\n  - ${result.errors.join("\n  - ")}`, "error");
+                ctx.ui.notify(`✗ "${rest}" has errors:\n  - ${result.errors.join("\n  - ")}`, "error");
             }
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            ctx.ui.notify(`Failed to validate "${defName}": ${msg}`, "error");
+            ctx.ui.notify(`Failed to validate "${rest}": ${msg}`, "error");
         }
         return true;
     }
     // ── pause ──
-    if (sub === "pause") {
+    if (head === "pause" && !rest) {
         const engineId = getActiveEngineId();
         if (engineId === "dev" || engineId === null) {
             ctx.ui.notify("No custom workflow is running. Use /gsd pause for dev workflow.", "warning");
@@ -131,7 +367,7 @@ async function handleCustomWorkflow(sub, ctx, pi) {
         return true;
     }
     // ── resume ──
-    if (sub === "resume") {
+    if (head === "resume" && !rest) {
         const engineId = getActiveEngineId();
         if (engineId === "dev" || engineId === null) {
             ctx.ui.notify("No custom workflow to resume. Use /gsd auto for dev workflow.", "warning");
@@ -141,11 +377,33 @@ async function handleCustomWorkflow(sub, ctx, pi) {
         ctx.ui.notify("Custom workflow resumed.", "info");
         return true;
     }
+    // ── Direct dispatch: /gsd workflow <name> [args] ──
+    // If the first token isn't a reserved subcommand, resolve it as a plugin.
+    if (!RESERVED_SUBCOMMANDS.has(head)) {
+        const base = projectRoot();
+        const plugin = resolvePlugin(base, head);
+        if (plugin) {
+            dispatchPluginByMode(plugin, rest, ctx, pi);
+            return true;
+        }
+    }
     // Unknown subcommand — show usage
-    ctx.ui.notify(`Unknown workflow subcommand: "${sub}"\n\n${WORKFLOW_USAGE}`, "warning");
+    ctx.ui.notify(`Unknown workflow subcommand or plugin: "${head}"\n\n${WORKFLOW_USAGE}`, "warning");
     return true;
 }
 export async function handleWorkflowCommand(trimmed, ctx, pi) {
+    // ── /gsd do — natural language routing (must be early to route to other commands) ──
+    if (trimmed === "do" || trimmed.startsWith("do ")) {
+        const { handleDo } = await import("../../commands-do.js");
+        await handleDo(trimmed.replace(/^do\s*/, "").trim(), ctx, pi);
+        return true;
+    }
+    // ── Backlog management ──
+    if (trimmed === "backlog" || trimmed.startsWith("backlog ")) {
+        const { handleBacklog } = await import("../../commands-backlog.js");
+        await handleBacklog(trimmed.replace(/^backlog\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     // ── Custom workflow commands (`/gsd workflow ...`) ──
     if (trimmed === "workflow" || trimmed.startsWith("workflow ")) {
         const sub = trimmed.slice("workflow".length).trim();

package/dist/resources/extensions/gsd/commands-add-tests.js

@@ -0,0 +1,111 @@
+/**
+ * GSD Command — /gsd add-tests
+ *
+ * Generates tests for a completed slice by dispatching an LLM prompt
+ * with implementation context (summaries, changed files, test patterns).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { deriveState } from "./state.js";
+import { gsdRoot, resolveSliceFile } from "./paths.js";
+import { loadPrompt } from "./prompt-loader.js";
+function findLastCompletedSlice(basePath, milestoneId) {
+    // Scan disk for slices that have a SUMMARY.md (indicating completion)
+    const slicesDir = join(gsdRoot(basePath), "milestones", milestoneId, "slices");
+    if (!existsSync(slicesDir))
+        return null;
+    try {
+        const entries = readdirSync(slicesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && /^S\d+$/.test(e.name))
+            .sort((a, b) => b.name.localeCompare(a.name)); // reverse order — latest first
+        for (const entry of entries) {
+            const summaryPath = join(slicesDir, entry.name, `${entry.name}-SUMMARY.md`);
+            if (existsSync(summaryPath))
+                return entry.name;
+        }
+    }
+    catch {
+        // non-fatal
+    }
+    return null;
+}
+function readSliceSummary(basePath, milestoneId, sliceId) {
+    const summaryPath = resolveSliceFile(basePath, milestoneId, sliceId, "SUMMARY");
+    if (summaryPath && existsSync(summaryPath)) {
+        const content = readFileSync(summaryPath, "utf-8");
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        return { title: titleMatch?.[1] ?? sliceId, content };
+    }
+    return { title: sliceId, content: "(no summary available)" };
+}
+function detectTestPatterns(basePath) {
+    const patterns = [];
+    // Check for common test configs
+    const checks = [
+        { file: "jest.config.ts", name: "Jest" },
+        { file: "jest.config.js", name: "Jest" },
+        { file: "vitest.config.ts", name: "Vitest" },
+        { file: "vitest.config.js", name: "Vitest" },
+        { file: ".mocharc.yml", name: "Mocha" },
+    ];
+    for (const check of checks) {
+        if (existsSync(join(basePath, check.file))) {
+            patterns.push(`Framework: ${check.name} (${check.file})`);
+        }
+    }
+    // Look for existing test files to infer patterns
+    const testDirs = ["tests", "test", "src/__tests__", "__tests__"];
+    for (const dir of testDirs) {
+        const fullDir = join(basePath, dir);
+        if (existsSync(fullDir)) {
+            try {
+                const files = readdirSync(fullDir).filter((f) => f.endsWith(".test.ts") || f.endsWith(".spec.ts") || f.endsWith(".test.js"));
+                if (files.length > 0) {
+                    patterns.push(`Test directory: ${dir}/ (${files.length} test files)`);
+                    // Read first test file for patterns
+                    const samplePath = join(fullDir, files[0]);
+                    const sample = readFileSync(samplePath, "utf-8").slice(0, 500);
+                    patterns.push(`Sample pattern from ${files[0]}:\n${sample}`);
+                    break;
+                }
+            }
+            catch {
+                // non-fatal
+            }
+        }
+    }
+    return patterns.length > 0 ? patterns.join("\n") : "No test framework detected. Use Node.js built-in test runner.";
+}
+export async function handleAddTests(args, ctx, pi) {
+    const basePath = process.cwd();
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone) {
+        ctx.ui.notify("No active milestone.", "warning");
+        return;
+    }
+    const milestoneId = state.activeMilestone.id;
+    // Determine target
+    const targetId = args.trim() || findLastCompletedSlice(basePath, milestoneId);
+    if (!targetId) {
+        ctx.ui.notify("No completed slices found. Specify a slice ID: /gsd add-tests S03", "warning");
+        return;
+    }
+    // Gather context
+    const summary = readSliceSummary(basePath, milestoneId, targetId);
+    const testPatterns = detectTestPatterns(basePath);
+    ctx.ui.notify(`Generating tests for ${targetId}: "${summary.title}"...`, "info");
+    try {
+        const prompt = loadPrompt("add-tests", {
+            sliceId: targetId,
+            sliceTitle: summary.title,
+            sliceSummary: summary.content,
+            existingTestPatterns: testPatterns,
+            workingDirectory: basePath,
+        });
+        pi.sendMessage({ customType: "gsd-add-tests", content: prompt, display: false }, { triggerTurn: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Failed to dispatch test generation: ${msg}`, "error");
+    }
+}

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

@@ -0,0 +1,140 @@
+/**
+ * GSD Command — /gsd backlog
+ *
+ * Structured backlog management with 999.x numbering.
+ * Items stored in .gsd/BACKLOG.md as markdown checklist.
+ * Items can be promoted to active slices via add-slice.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { gsdRoot } from "./paths.js";
+function backlogPath(basePath) {
+    return join(gsdRoot(basePath), "BACKLOG.md");
+}
+function parseBacklog(basePath) {
+    const filePath = backlogPath(basePath);
+    if (!existsSync(filePath))
+        return [];
+    const content = readFileSync(filePath, "utf-8");
+    const items = [];
+    for (const line of content.split("\n")) {
+        const match = line.match(/^- \[([ x])\] (999\.\d+) — (.+?)(?:\s*\((.+)\))?$/);
+        if (match) {
+            items.push({
+                id: match[2],
+                title: match[3].trim(),
+                done: match[1] === "x",
+                note: match[4] ?? "",
+            });
+        }
+    }
+    return items;
+}
+function writeBacklog(basePath, items) {
+    const filePath = backlogPath(basePath);
+    mkdirSync(dirname(filePath), { recursive: true });
+    const lines = ["# Backlog\n"];
+    for (const item of items) {
+        const check = item.done ? "x" : " ";
+        const note = item.note ? ` (${item.note})` : "";
+        lines.push(`- [${check}] ${item.id} — ${item.title}${note}`);
+    }
+    lines.push(""); // trailing newline
+    writeFileSync(filePath, lines.join("\n"), "utf-8");
+}
+function nextBacklogId(items) {
+    let maxNum = 0;
+    for (const item of items) {
+        const match = item.id.match(/^999\.(\d+)$/);
+        if (match) {
+            const num = parseInt(match[1], 10);
+            if (num > maxNum)
+                maxNum = num;
+        }
+    }
+    return `999.${maxNum + 1}`;
+}
+async function listBacklog(basePath, ctx) {
+    const items = parseBacklog(basePath);
+    if (items.length === 0) {
+        ctx.ui.notify("Backlog is empty. Add items with /gsd backlog add <title>", "info");
+        return;
+    }
+    const lines = ["Backlog:\n"];
+    for (const item of items) {
+        const status = item.done ? "✓" : "○";
+        const note = item.note ? ` (${item.note})` : "";
+        lines.push(`  ${status} ${item.id} — ${item.title}${note}`);
+    }
+    const pending = items.filter((i) => !i.done).length;
+    lines.push(`\n${pending} pending, ${items.length - pending} promoted/done`);
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+async function addBacklogItem(basePath, title, ctx) {
+    if (!title) {
+        ctx.ui.notify("Usage: /gsd backlog add <title>", "warning");
+        return;
+    }
+    const items = parseBacklog(basePath);
+    const id = nextBacklogId(items);
+    const date = new Date().toISOString().slice(0, 10);
+    items.push({ id, title: title.replace(/^['"]|['"]$/g, ""), done: false, note: `added ${date}` });
+    writeBacklog(basePath, items);
+    ctx.ui.notify(`Added ${id}: "${title}"`, "success");
+}
+async function promoteBacklogItem(basePath, itemId, ctx, pi) {
+    if (!itemId) {
+        ctx.ui.notify("Usage: /gsd backlog promote <id>\nExample: /gsd backlog promote 999.1", "warning");
+        return;
+    }
+    const items = parseBacklog(basePath);
+    const item = items.find((i) => i.id === itemId);
+    if (!item) {
+        ctx.ui.notify(`Backlog item ${itemId} not found.`, "warning");
+        return;
+    }
+    if (item.done) {
+        ctx.ui.notify(`${itemId} is already promoted/done.`, "info");
+        return;
+    }
+    // Promote — currently requires single-writer engine (not yet available)
+    // Mark as promoted in backlog for now; slice creation will be available with the engine.
+    item.done = true;
+    item.note = `promoted ${new Date().toISOString().slice(0, 10)}`;
+    writeBacklog(basePath, items);
+    ctx.ui.notify(`Promoted ${itemId}: "${item.title}" — add it to the roadmap manually or wait for engine slice commands.`, "info");
+}
+async function removeBacklogItem(basePath, itemId, ctx) {
+    if (!itemId) {
+        ctx.ui.notify("Usage: /gsd backlog remove <id>", "warning");
+        return;
+    }
+    const items = parseBacklog(basePath);
+    const idx = items.findIndex((i) => i.id === itemId);
+    if (idx === -1) {
+        ctx.ui.notify(`Backlog item ${itemId} not found.`, "warning");
+        return;
+    }
+    const removed = items.splice(idx, 1)[0];
+    writeBacklog(basePath, items);
+    ctx.ui.notify(`Removed ${removed.id}: "${removed.title}"`, "success");
+}
+export async function handleBacklog(args, ctx, pi) {
+    const basePath = process.cwd();
+    const parts = args.trim().split(/\s+/);
+    const sub = parts[0] ?? "";
+    const rest = parts.slice(1).join(" ");
+    switch (sub) {
+        case "":
+            return listBacklog(basePath, ctx);
+        case "add":
+            return addBacklogItem(basePath, rest, ctx);
+        case "promote":
+            return promoteBacklogItem(basePath, rest.trim(), ctx, pi);
+        case "remove":
+            return removeBacklogItem(basePath, rest.trim(), ctx);
+        default:
+            // Treat as implicit add
+            return addBacklogItem(basePath, args, ctx);
+    }
+}