gsd-pi 2.74.0-dev.2b524c3 → 2.74.0-dev.703eabc

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

@@ -0,0 +1,225 @@
+/**
+ * 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
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+// ─── Pure functions ───────────────────────────────────────────────────────────
+export function parseExtractLearningsArgs(args) {
+    const trimmed = args.trim();
+    return { milestoneId: trimmed || null };
+}
+export function buildLearningsOutputPath(milestoneDir, milestoneId) {
+    return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+export function resolvePhaseArtifacts(milestoneDir, milestoneId) {
+    const missingRequired = [];
+    const planFile = `${milestoneId}-PLAN.md`;
+    const summaryFile = `${milestoneId}-SUMMARY.md`;
+    const verificationFile = `${milestoneId}-VERIFICATION.md`;
+    const uatFile = `${milestoneId}-UAT.md`;
+    const planPath = join(milestoneDir, planFile);
+    const summaryPath = join(milestoneDir, summaryFile);
+    const verificationPath = join(milestoneDir, verificationFile);
+    const uatPath = join(milestoneDir, uatFile);
+    const plan = existsSync(planPath) ? planPath : null;
+    const summary = existsSync(summaryPath) ? summaryPath : null;
+    const verification = existsSync(verificationPath) ? verificationPath : null;
+    const uat = existsSync(uatPath) ? uatPath : null;
+    if (!plan)
+        missingRequired.push(planFile);
+    if (!summary)
+        missingRequired.push(summaryFile);
+    return { plan, summary, verification, uat, missingRequired };
+}
+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`
+        : "";
+    return `# Extract Learnings — ${ctx.milestoneId}: ${ctx.milestoneName}
+
+**Project:** ${ctx.projectName}
+**Output file:** ${ctx.outputPath}
+
+## Your Task
+
+Analyse the artefacts below and extract structured knowledge from milestone **${ctx.milestoneId}**.
+
+Write a LEARNINGS document to \`${ctx.outputPath}\` with the following 4 sections:
+
+### Decisions
+Key architectural and design decisions made during this milestone, including the rationale and alternatives considered.
+
+### Lessons
+What the team learned — technical discoveries, process insights, and knowledge gaps that were filled.
+
+### Patterns
+Reusable patterns, approaches, or solutions that emerged and should be applied in future work.
+
+### Surprises
+Unexpected challenges, discoveries, or outcomes — things that deviated from assumptions.
+
+### Source Attribution (REQUIRED)
+
+Every extracted item MUST include a \`Source:\` line immediately after the item text.
+Format: \`Source: {artifact-filename}/{section}\`
+Example: \`Source: M001-PLAN.md/Architecture Decisions\`
+
+Items without a Source attribution are invalid and must not be included in the output.
+
+---
+
+## Artefacts
+
+### Plan
+
+${ctx.planContent}
+
+---
+
+### Summary
+
+${ctx.summaryContent}
+
+${optionalSections.join("\n\n---\n\n")}
+${missingNote}
+---
+
+## Output Format
+
+Write the LEARNINGS file to \`${ctx.relativeOutputPath}\` with YAML frontmatter followed by the 4 sections above.
+Each section should contain concise, actionable bullet points.
+Every bullet point MUST be followed by a source line, for example:
+
+\`\`\`
+### Decisions
+- Chose PostgreSQL over SQLite for concurrent write support.
+  Source: M001-PLAN.md/Architecture Decisions
+\`\`\`
+
+Items without a \`Source:\` line are invalid.
+
+---
+
+## Optional: Capture Individual Learnings
+
+If the \`capture_thought\` tool is available, call it once for each extracted item with:
+- category: "decision" | "lesson" | "pattern" | "surprise"
+- phase: "${ctx.milestoneId}"
+- content: {the learning text}
+- source: {artifact filename}
+
+If \`capture_thought\` is not available, skip this step silently — do not report an error.
+
+---
+
+## Rebuild Knowledge Graph
+
+After writing LEARNINGS.md, call the \`gsd_graph\` tool with \`{ "mode": "build" }\` to rebuild the knowledge graph so the new learnings are immediately queryable by future milestone prompts.
+
+If the \`gsd_graph\` tool is not available, skip this step silently.
+`;
+}
+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}
+---`;
+}
+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 ──────────────────────────────────────────────────────────────────
+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;
+    }
+    // Read required artefacts
+    const planContent = readFileSync(artifacts.plan, "utf-8");
+    const summaryContent = readFileSync(artifacts.summary, "utf-8");
+    // Read optional artefacts
+    const verificationContent = artifacts.verification
+        ? readFileSync(artifacts.verification, "utf-8")
+        : null;
+    const uatContent = artifacts.uat
+        ? readFileSync(artifacts.uat, "utf-8")
+        : null;
+    // Determine missing optional artefacts for context
+    const missingArtifacts = [];
+    if (!artifacts.verification)
+        missingArtifacts.push(`${milestoneId}-VERIFICATION.md`);
+    if (!artifacts.uat)
+        missingArtifacts.push(`${milestoneId}-UAT.md`);
+    // Extract milestone name from Plan H1 or fall back to milestoneId
+    const h1Match = planContent.match(/^#\s+(.+)$/m);
+    const milestoneName = h1Match?.[1]?.trim() ?? milestoneId;
+    const projectName = extractProjectName(basePath);
+    const outputPath = buildLearningsOutputPath(milestoneDir, milestoneId);
+    const relativeOutputPath = outputPath.replace(basePath + "/", "");
+    const prompt = buildExtractLearningsPrompt({
+        milestoneId,
+        milestoneName,
+        outputPath,
+        relativeOutputPath,
+        planContent,
+        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-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");
+    }
+}

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

@@ -705,7 +705,7 @@ export function serializePreferencesToFrontmatter(prefs) {
         "budget_ceiling", "budget_enforcement", "context_pause_threshold",
         "notifications", "cmux", "remote_questions", "git",
         "post_unit_hooks", "pre_dispatch_hooks",
-        "dynamic_routing", "token_profile", "phases", "parallel",
+        "dynamic_routing", "uok", "token_profile", "phases", "parallel",
         "auto_visualize", "auto_report",
         "verification_commands", "verification_auto_fix", "verification_max_retries",
         "search_provider", "context_selection",

package/dist/resources/extensions/gsd/commands-session-report.js

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