gsd-pi 2.58.0-dev.d63175c → 2.58.0-dev.e002a57

package/dist/resources/extensions/gsd/codebase-generator.js

@@ -0,0 +1,279 @@
+/**
+ * GSD Codebase Map Generator
+ *
+ * Produces .gsd/CODEBASE.md — a structural table of contents for the project.
+ * Gives fresh agent contexts instant orientation without filesystem exploration.
+ *
+ * Generation: walk `git ls-files`, group by directory, output with descriptions.
+ * Maintenance: agent updates descriptions as it works; incremental update preserves them.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname, extname } from "node:path";
+import { execSync } from "node:child_process";
+import { gsdRoot } from "./paths.js";
+// ─── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_EXCLUDES = [
+    ".gsd/",
+    ".planning/",
+    ".git/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    ".next/",
+    "coverage/",
+    "__pycache__/",
+    ".venv/",
+    "vendor/",
+];
+const DEFAULT_MAX_FILES = 500;
+const DEFAULT_COLLAPSE_THRESHOLD = 20;
+// ─── Parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Parse an existing CODEBASE.md to extract file → description mappings.
+ * Also scans <!-- gsd:collapsed-descriptions --> comment blocks to preserve
+ * descriptions for files in collapsed directories across incremental updates.
+ */
+export function parseCodebaseMap(content) {
+    const descriptions = new Map();
+    let inCollapsedBlock = false;
+    for (const line of content.split("\n")) {
+        // Track collapsed-description comment blocks
+        if (line.trimStart().startsWith("<!-- gsd:collapsed-descriptions")) {
+            inCollapsedBlock = true;
+            continue;
+        }
+        if (inCollapsedBlock && line.trimStart().startsWith("-->")) {
+            inCollapsedBlock = false;
+            continue;
+        }
+        // Match: - `path/to/file.ts` — Description here
+        const match = line.match(/^- `(.+?)` — (.+)$/);
+        if (match) {
+            descriptions.set(match[1], match[2]);
+            continue;
+        }
+        // Match: - `path/to/file.ts` (no description) — only outside collapsed blocks
+        if (!inCollapsedBlock) {
+            const bareMatch = line.match(/^- `(.+?)`\s*$/);
+            if (bareMatch) {
+                descriptions.set(bareMatch[1], "");
+            }
+        }
+    }
+    return descriptions;
+}
+// ─── File Enumeration ────────────────────────────────────────────────────────
+function shouldExclude(filePath, excludes) {
+    for (const pattern of excludes) {
+        if (pattern.endsWith("/")) {
+            if (filePath.startsWith(pattern) || filePath.includes(`/${pattern}`))
+                return true;
+        }
+        else if (filePath === pattern || filePath.endsWith(`/${pattern}`)) {
+            return true;
+        }
+    }
+    // Skip binary/lock files
+    const ext = extname(filePath).toLowerCase();
+    if ([".lock", ".png", ".jpg", ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf", ".eot", ".svg"].includes(ext)) {
+        return true;
+    }
+    return false;
+}
+function lsFiles(basePath) {
+    try {
+        const result = execSync("git ls-files", { cwd: basePath, encoding: "utf-8", timeout: 10000 });
+        return result.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Enumerate tracked files, applying exclusions and the maxFiles cap.
+ * Returns both the file list and whether truncation occurred.
+ */
+function enumerateFiles(basePath, excludes, maxFiles) {
+    const allFiles = lsFiles(basePath);
+    const filtered = allFiles.filter((f) => !shouldExclude(f, excludes));
+    const truncated = filtered.length > maxFiles;
+    return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
+}
+// ─── Grouping ────────────────────────────────────────────────────────────────
+function groupByDirectory(files, descriptions, collapseThreshold) {
+    const dirMap = new Map();
+    for (const file of files) {
+        const dir = dirname(file);
+        const dirKey = dir === "." ? "" : dir;
+        if (!dirMap.has(dirKey)) {
+            dirMap.set(dirKey, []);
+        }
+        dirMap.get(dirKey).push({
+            path: file,
+            description: descriptions.get(file) ?? "",
+        });
+    }
+    const groups = [];
+    const sortedDirs = [...dirMap.keys()].sort();
+    for (const dir of sortedDirs) {
+        const dirFiles = dirMap.get(dir);
+        dirFiles.sort((a, b) => a.path.localeCompare(b.path));
+        groups.push({
+            path: dir,
+            files: dirFiles,
+            collapsed: dirFiles.length > collapseThreshold,
+        });
+    }
+    return groups;
+}
+// ─── Rendering ───────────────────────────────────────────────────────────────
+function renderCodebaseMap(groups, totalFiles, truncated) {
+    const lines = [];
+    const now = new Date().toISOString().split(".")[0] + "Z";
+    const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0);
+    lines.push("# Codebase Map");
+    lines.push("");
+    lines.push(`Generated: ${now} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+    if (truncated) {
+        lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
+    }
+    lines.push("");
+    for (const group of groups) {
+        const heading = group.path || "(root)";
+        lines.push(`### ${heading}/`);
+        if (group.collapsed) {
+            // Summarize collapsed directories
+            const extensions = new Map();
+            for (const f of group.files) {
+                const ext = extname(f.path) || "(no ext)";
+                extensions.set(ext, (extensions.get(ext) ?? 0) + 1);
+            }
+            const extSummary = [...extensions.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .map(([ext, count]) => `${count} ${ext}`)
+                .join(", ");
+            lines.push(`- *(${group.files.length} files: ${extSummary})*`);
+            // Preserve any existing descriptions in a hidden comment block so
+            // incremental updates can recover them via parseCodebaseMap.
+            const descLines = group.files
+                .filter((f) => f.description)
+                .map((f) => `- \`${f.path}\` — ${f.description}`);
+            if (descLines.length > 0) {
+                lines.push("<!-- gsd:collapsed-descriptions");
+                lines.push(...descLines);
+                lines.push("-->");
+            }
+        }
+        else {
+            for (const file of group.files) {
+                if (file.description) {
+                    lines.push(`- \`${file.path}\` — ${file.description}`);
+                }
+                else {
+                    lines.push(`- \`${file.path}\``);
+                }
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Generate a fresh CODEBASE.md from scratch.
+ * Preserves existing descriptions if `existingDescriptions` is provided.
+ */
+export function generateCodebaseMap(basePath, options, existingDescriptions) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
+    const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
+    const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
+    const { files, truncated } = enumerateFiles(basePath, excludes, maxFiles);
+    const descriptions = existingDescriptions ?? new Map();
+    const groups = groupByDirectory(files, descriptions, collapseThreshold);
+    const content = renderCodebaseMap(groups, files.length, truncated);
+    return { content, fileCount: files.length, truncated, files };
+}
+/**
+ * Incremental update: re-scan files, preserve existing descriptions,
+ * add new files, remove deleted files.
+ */
+export function updateCodebaseMap(basePath, options) {
+    const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+    // Load existing descriptions
+    let existingDescriptions = new Map();
+    if (existsSync(codebasePath)) {
+        const existing = readFileSync(codebasePath, "utf-8");
+        existingDescriptions = parseCodebaseMap(existing);
+    }
+    const existingFiles = new Set(existingDescriptions.keys());
+    // Generate new map preserving descriptions — reuse the returned file list
+    // to avoid a second enumeration (prevents race between content and stats).
+    const result = generateCodebaseMap(basePath, options, existingDescriptions);
+    const currentSet = new Set(result.files);
+    // Count changes
+    let added = 0;
+    let removed = 0;
+    for (const f of result.files) {
+        if (!existingFiles.has(f))
+            added++;
+    }
+    for (const f of existingFiles) {
+        if (!currentSet.has(f))
+            removed++;
+    }
+    return {
+        content: result.content,
+        added,
+        removed,
+        unchanged: result.files.length - added,
+        fileCount: result.fileCount,
+        truncated: result.truncated,
+    };
+}
+/**
+ * Write CODEBASE.md to .gsd/ directory.
+ */
+export function writeCodebaseMap(basePath, content) {
+    const root = gsdRoot(basePath);
+    mkdirSync(root, { recursive: true });
+    const outPath = join(root, "CODEBASE.md");
+    writeFileSync(outPath, content, "utf-8");
+    return outPath;
+}
+/**
+ * Read existing CODEBASE.md, or return null if it doesn't exist.
+ */
+export function readCodebaseMap(basePath) {
+    const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+    if (!existsSync(codebasePath))
+        return null;
+    try {
+        return readFileSync(codebasePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get stats about the codebase map.
+ */
+export function getCodebaseMapStats(basePath) {
+    const content = readCodebaseMap(basePath);
+    if (!content) {
+        return { exists: false, fileCount: 0, describedCount: 0, undescribedCount: 0, generatedAt: null };
+    }
+    // Parse total file count from the header line (accurate even for collapsed dirs)
+    const fileCountMatch = content.match(/Files:\s*(\d+)/);
+    const totalFiles = fileCountMatch ? parseInt(fileCountMatch[1], 10) : 0;
+    // Use parseCodebaseMap to count described files (includes collapsed-description blocks)
+    const descriptions = parseCodebaseMap(content);
+    const described = [...descriptions.values()].filter((d) => d.length > 0).length;
+    const dateMatch = content.match(/Generated: (\S+)/);
+    return {
+        exists: true,
+        fileCount: totalFiles,
+        describedCount: described,
+        undescribedCount: totalFiles - described,
+        generatedAt: dateMatch?.[1] ?? null,
+    };
+}

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -59,6 +59,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
     { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
     { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
+    { cmd: "codebase", desc: "Generate and manage codebase map (.gsd/CODEBASE.md)" },
 ];
 const NESTED_COMPLETIONS = {
     auto: [
@@ -212,6 +213,14 @@ const NESTED_COMPLETIONS = {
         { cmd: "pause", desc: "Pause custom workflow auto-mode" },
         { cmd: "resume", desc: "Resume paused custom workflow auto-mode" },
     ],
+    codebase: [
+        { cmd: "generate", desc: "Generate or regenerate CODEBASE.md" },
+        { cmd: "generate --max-files", desc: "Generate with custom file limit (default: 500)" },
+        { cmd: "update", desc: "Incremental update (preserves descriptions)" },
+        { cmd: "update --max-files", desc: "Update with custom file limit" },
+        { cmd: "stats", desc: "Show file count, description coverage, and generation time" },
+        { cmd: "help", desc: "Show usage and available subcommands" },
+    ],
 };
 function filterOptions(partial, options, prefix = "") {
     const normalizedPrefix = prefix ? `${prefix} ` : "";

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

@@ -203,5 +203,10 @@ Examples:
         await handleRethink(trimmed, ctx, pi);
         return true;
     }
+    if (trimmed === "codebase" || trimmed.startsWith("codebase ")) {
+        const { handleCodebase } = await import("../../commands-codebase.js");
+        await handleCodebase(trimmed.replace(/^codebase\s*/, "").trim(), ctx, pi);
+        return true;
+    }
     return false;
 }

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

@@ -0,0 +1,115 @@
+/**
+ * GSD Command — /gsd codebase
+ *
+ * Generate and manage the codebase map (.gsd/CODEBASE.md).
+ * Subcommands: generate, update, stats, help
+ */
+import { generateCodebaseMap, updateCodebaseMap, writeCodebaseMap, getCodebaseMapStats, readCodebaseMap, } from "./codebase-generator.js";
+const USAGE = "Usage: /gsd codebase [generate|update|stats]\n\n" +
+    "  generate [--max-files N]  — Generate or regenerate CODEBASE.md\n" +
+    "  update                    — Incremental update (preserves descriptions)\n" +
+    "  stats                     — Show file count, coverage, and generation time\n" +
+    "  help                      — Show this help\n\n" +
+    "With no subcommand, shows stats if a map exists or help if not.";
+export async function handleCodebase(args, ctx, _pi) {
+    const basePath = process.cwd();
+    const parts = args.trim().split(/\s+/);
+    const sub = parts[0] ?? "";
+    switch (sub) {
+        case "generate": {
+            const maxFiles = parseMaxFiles(args, ctx);
+            if (maxFiles === false)
+                return; // validation failed, message already shown
+            const existing = readCodebaseMap(basePath);
+            const existingDescriptions = existing
+                ? (await import("./codebase-generator.js")).parseCodebaseMap(existing)
+                : undefined;
+            const result = generateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined }, existingDescriptions);
+            if (result.fileCount === 0) {
+                ctx.ui.notify("Codebase map generated with 0 files.\n" +
+                    "Is this a git repository? Run 'git ls-files' to verify.", "warning");
+                return;
+            }
+            const outPath = writeCodebaseMap(basePath, result.content);
+            ctx.ui.notify(`Codebase map generated: ${result.fileCount} files\n` +
+                `Written to: ${outPath}` +
+                (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""), "success");
+            return;
+        }
+        case "update": {
+            const existing = readCodebaseMap(basePath);
+            if (!existing) {
+                ctx.ui.notify("No codebase map found. Run /gsd codebase generate to create one.", "warning");
+                return;
+            }
+            const maxFiles = parseMaxFiles(args, ctx);
+            if (maxFiles === false)
+                return;
+            const result = updateCodebaseMap(basePath, { maxFiles: maxFiles ?? undefined });
+            writeCodebaseMap(basePath, result.content);
+            ctx.ui.notify(`Codebase map updated: ${result.fileCount} files\n` +
+                `  Added: ${result.added} | Removed: ${result.removed} | Unchanged: ${result.unchanged}` +
+                (result.truncated ? `\n⚠ Truncated — increase --max-files to include all files` : ""), "success");
+            return;
+        }
+        case "stats": {
+            showStats(basePath, ctx);
+            return;
+        }
+        case "help":
+            ctx.ui.notify(USAGE, "info");
+            return;
+        case "": {
+            // Safe default: show stats if map exists, help if not
+            const existing = readCodebaseMap(basePath);
+            if (existing) {
+                showStats(basePath, ctx);
+            }
+            else {
+                ctx.ui.notify(USAGE, "info");
+            }
+            return;
+        }
+        default:
+            ctx.ui.notify(`Unknown subcommand "${sub}".\n\n${USAGE}`, "warning");
+    }
+}
+function showStats(basePath, ctx) {
+    const stats = getCodebaseMapStats(basePath);
+    if (!stats.exists) {
+        ctx.ui.notify("No codebase map found. Run /gsd codebase generate to create one.", "info");
+        return;
+    }
+    const coverage = stats.fileCount > 0
+        ? Math.round((stats.describedCount / stats.fileCount) * 100)
+        : 0;
+    ctx.ui.notify(`Codebase Map Stats:\n` +
+        `  Files: ${stats.fileCount}\n` +
+        `  Described: ${stats.describedCount} (${coverage}%)\n` +
+        `  Undescribed: ${stats.undescribedCount}\n` +
+        `  Generated: ${stats.generatedAt ?? "unknown"}\n\n` +
+        (stats.undescribedCount > 0
+            ? `Tip: Run /gsd codebase update to refresh after file changes.`
+            : `Coverage is complete.`), "info");
+}
+/**
+ * Parse and validate --max-files flag.
+ * Returns the parsed number, undefined if flag not present, or false if invalid.
+ */
+function parseMaxFiles(args, ctx) {
+    const maxFilesStr = extractFlag(args, "--max-files");
+    if (!maxFilesStr)
+        return undefined;
+    const maxFiles = parseInt(maxFilesStr, 10);
+    if (isNaN(maxFiles) || maxFiles < 1) {
+        ctx.ui.notify("--max-files must be a positive integer (e.g. --max-files 200).", "warning");
+        return false;
+    }
+    return maxFiles;
+}
+function extractFlag(args, flag) {
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(`${escaped}[=\\s]+(\\S+)`);
+    const match = args.match(regex);
+    return match?.[1];
+}

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -151,11 +151,24 @@ export function buildCategorySummaries(prefs) {
     }
     // Git
     const git = prefs.git;
+    const staleThreshold = prefs.stale_commit_threshold_minutes;
+    const absorbSnapshots = git?.absorb_snapshot_commits;
     let gitSummary = "(defaults)";
-    if (git && Object.keys(git).length > 0) {
-        const branch = git.main_branch ?? "main";
-        const push = git.auto_push ? "on" : "off";
-        gitSummary = `main: ${branch}, push: ${push}`;
+    {
+        const parts = [];
+        if (git && Object.keys(git).length > 0) {
+            const branch = git.main_branch ?? "main";
+            const push = git.auto_push ? "on" : "off";
+            parts.push(`main: ${branch}, push: ${push}`);
+        }
+        if (staleThreshold !== undefined) {
+            parts.push(`stale: ${staleThreshold === 0 ? "off" : `${staleThreshold}m`}`);
+        }
+        if (absorbSnapshots !== undefined) {
+            parts.push(`absorb: ${absorbSnapshots ? "on" : "off"}`);
+        }
+        if (parts.length > 0)
+            gitSummary = parts.join(", ");
     }
     // Skills
     const discovery = prefs.skill_discovery;
@@ -394,9 +407,33 @@ async function configureGit(ctx, prefs) {
     if (isolationChoice && isolationChoice !== "(keep current)") {
         git.isolation = isolationChoice;
     }
+    // absorb_snapshot_commits (git sub-key)
+    const currentAbsorb = git.absorb_snapshot_commits;
+    const absorbStr = currentAbsorb !== undefined ? String(currentAbsorb) : "";
+    const absorbChoice = await ctx.ui.select(`Absorb snapshot commits into real commits${absorbStr ? ` (current: ${absorbStr})` : " (default: true)"}:`, ["true", "false", "(keep current)"]);
+    if (absorbChoice && absorbChoice !== "(keep current)") {
+        git.absorb_snapshot_commits = absorbChoice === "true";
+    }
     if (Object.keys(git).length > 0) {
         prefs.git = git;
     }
+    // stale_commit_threshold_minutes (top-level pref, shown in Git section)
+    const currentThreshold = prefs.stale_commit_threshold_minutes;
+    const thresholdStr = currentThreshold !== undefined ? String(currentThreshold) : "";
+    const thresholdInput = await ctx.ui.input(`Stale commit threshold (minutes, 0 to disable)${thresholdStr ? ` (current: ${thresholdStr})` : " (default: 30)"}:`, thresholdStr || "30");
+    if (thresholdInput !== null && thresholdInput !== undefined) {
+        const val = thresholdInput.trim();
+        const parsed = tryParseInteger(val);
+        if (val && parsed !== null && parsed >= 0) {
+            prefs.stale_commit_threshold_minutes = parsed;
+        }
+        else if (val && parsed === null) {
+            ctx.ui.notify(`Invalid value "${val}" — must be a whole number. Keeping previous value.`, "warning");
+        }
+        else if (!val && currentThreshold !== undefined) {
+            delete prefs.stale_commit_threshold_minutes;
+        }
+    }
 }
 async function configureSkills(ctx, prefs) {
     // Skill discovery mode

package/dist/resources/extensions/gsd/complexity-classifier.js

@@ -11,14 +11,16 @@ const UNIT_TYPE_TIERS = {
     // Tier 1 — Light: structured summaries, completion, UAT
     "complete-slice": "light",
     "run-uat": "light",
-    // Tier 2 — Standard: research, routine planning, discussion
+    // Tier 2 — Standard: research, routine discussion
     "discuss-milestone": "standard",
     "discuss-slice": "standard",
     "research-milestone": "standard",
     "research-slice": "standard",
-    "plan-milestone": "standard",
-    "plan-slice": "standard",
-    // Tier 3 — Heavy: execution, replanning (requires deep reasoning)
+    // Tier 3 — Heavy: planning, execution, replanning (requires deep reasoning)
+    // Planning is heavy so it uses the best configured model (e.g. Opus) and is
+    // not downgraded by dynamic routing when a capable model is configured.
+    "plan-milestone": "heavy",
+    "plan-slice": "heavy",
     "execute-task": "standard", // default standard, upgraded by metadata
     "replan-slice": "heavy",
     "reassess-roadmap": "heavy",
@@ -124,8 +126,8 @@ function analyzePlanComplexity(unitId, basePath) {
     // Check if this is a milestone-level plan (more complex) vs single slice
     const { milestone: mid, slice: sid } = parseUnitId(unitId);
     if (!sid) {
-        // Milestone-level planning is always at least standard
-        return { tier: "standard", reason: "milestone-level planning" };
+        // Milestone-level planning is always heavy — requires full context and best model
+        return { tier: "heavy", reason: "milestone-level planning" };
     }
     // For slice planning, try to read the context/research to gauge complexity
     // If research exists and is large, bump to heavy