gsd-pi 2.74.0 → 2.75.0-dev.063e5a3

package/src/resources/extensions/gsd/commands-extract-learnings.ts

@@ -0,0 +1,304 @@
+/**
+ * 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 type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+
+import { gsdRoot, resolveMilestonePath } from "./paths.js";
+import { projectRoot } from "./commands/context.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface PhaseArtifacts {
+  plan: string | null;
+  summary: string | null;
+  verification: string | null;
+  uat: string | null;
+  missingRequired: string[];
+}
+
+export interface ExtractLearningsPromptContext {
+  milestoneId: string;
+  milestoneName: string;
+  outputPath: string;
+  relativeOutputPath: string;
+  planContent: string;
+  summaryContent: string;
+  verificationContent: string | null;
+  uatContent: string | null;
+  missingArtifacts: string[];
+  projectName: string;
+}
+
+export interface FrontmatterContext {
+  milestoneId: string;
+  milestoneName: string;
+  projectName: string;
+  generatedAt: string;
+  counts: {
+    decisions: number;
+    lessons: number;
+    patterns: number;
+    surprises: number;
+  };
+  missingArtifacts: string[];
+}
+
+// ─── Pure functions ───────────────────────────────────────────────────────────
+
+export function parseExtractLearningsArgs(args: string): { milestoneId: string | null } {
+  const trimmed = args.trim();
+  return { milestoneId: trimmed || null };
+}
+
+export function buildLearningsOutputPath(milestoneDir: string, milestoneId: string): string {
+  return join(milestoneDir, `${milestoneId}-LEARNINGS.md`);
+}
+
+export function resolvePhaseArtifacts(milestoneDir: string, milestoneId: string): PhaseArtifacts {
+  const missingRequired: string[] = [];
+
+  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: ExtractLearningsPromptContext): string {
+  const optionalSections: string[] = [];
+
+  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: FrontmatterContext): string {
+  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: string): string {
+  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: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+): Promise<void> {
+  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: string[] = [];
+  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/src/resources/extensions/gsd/commands-maintenance.ts

@@ -488,7 +488,7 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
  * Prints counts of recovered items and the resulting project phase.
  */
 export async function handleRecover(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
-  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");
 
@@ -498,12 +498,12 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
   }
 
   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);
     });
 

package/src/resources/extensions/gsd/commands-pr-branch.ts

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

@@ -756,8 +756,8 @@ export async function handlePrefsWizard(
 /** Wrap a YAML value in double quotes if it contains special characters. */
 export function yamlSafeString(val: unknown): string {
   if (typeof val !== "string") return String(val);
-  if (/[:#{\[\]'"`,|>&*!?@%]/.test(val) || val.trim() !== val || val === "") {
-    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  if (/[:#{\[\]'"`,|>&*!?@%\r\n]/.test(val) || val.trim() !== val || val === "") {
+    return `"${val.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n")}"`;
   }
   return val;
 }
@@ -822,10 +822,10 @@ export function serializePreferencesToFrontmatter(prefs: Record<string, unknown>
     "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",
+    "search_provider", "context_selection", "language",
   ];
 
   const seen = new Set<string>();
@@ -862,3 +862,57 @@ export async function ensurePreferencesFile(
     ctx.ui.notify(`Using existing ${scope} GSD skill preferences at ${path}`, "info");
   }
 }
+
+/**
+ * Handle `/gsd language [code]` — set or clear the global language preference.
+ * Without an argument, shows the current setting.
+ * Project-level override can be set by editing `.gsd/preferences.md` directly
+ * (project language overrides global when both are set).
+ */
+export async function handleLanguage(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const path = getGlobalGSDPreferencesPath();
+  const lang = args.trim();
+
+  // Show current setting when called without argument
+  if (!lang) {
+    const loaded = loadGlobalGSDPreferences();
+    const current = loaded?.preferences.language;
+    if (current) {
+      ctx.ui.notify(`Current language preference: ${current}\nUse /gsd language <name> to change, or /gsd language off to clear.`, "info");
+    } else {
+      ctx.ui.notify("No language preference set. Use /gsd language <name> to set one (e.g. /gsd language Chinese).", "info");
+    }
+    return;
+  }
+
+  // Ensure preferences file exists with the canonical template
+  await ensurePreferencesFile(path, ctx, "global");
+
+  // Read via the same validated path as other handlers
+  const existing = loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : { version: 1 };
+
+  if (lang === "off" || lang === "none" || lang === "clear") {
+    delete prefs.language;
+    ctx.ui.notify("Language preference cleared. GSD will use the default language.", "info");
+  } else {
+    // Validate before writing — reject values that would fail on next load
+    if (lang.length > 50 || /[\r\n]/.test(lang)) {
+      ctx.ui.notify(
+        "Language value must be 50 characters or fewer with no newlines (e.g. /gsd language Chinese).",
+        "warning",
+      );
+      return;
+    }
+    prefs.language = lang;
+    ctx.ui.notify(`Language preference set to: ${lang}\nGSD will now respond in ${lang} across all sessions.`, "info");
+  }
+
+  const rawContent = existsSync(path) ? readFileSync(path, "utf-8") : `---\nversion: 1\n---\n`;
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  const body = extractBodyAfterFrontmatter(rawContent)
+    ?? "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  await saveFile(path, `---\n${frontmatter}---${body}`);
+  await ctx.waitForIdle();
+  await ctx.reload();
+}