gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/extensions/gsd/workflow-templates/security-audit.md

@@ -0,0 +1,73 @@
+# Security Audit Workflow
+
+<template_meta>
+name: security-audit
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/audits/
+</template_meta>
+
+<purpose>
+Systematic security review of the codebase. Scan for vulnerabilities, triage
+findings by severity, remediate issues, and verify fixes. Covers OWASP Top 10,
+dependency vulnerabilities, and project-specific security concerns.
+</purpose>
+
+<phases>
+1. scan       — Identify potential vulnerabilities
+2. triage     — Prioritize findings by severity and exploitability
+3. remediate  — Fix critical and high-severity issues
+4. re-scan    — Verify fixes and document remaining items
+</phases>
+
+<process>
+
+## Phase 1: Scan
+
+**Goal:** Identify potential security issues across the codebase.
+
+1. **Dependency audit:** Run `npm audit` / `pip audit` / equivalent
+2. **Code review for common vulnerabilities:**
+   - Injection (SQL, command, XSS)
+   - Authentication/authorization flaws
+   - Sensitive data exposure (hardcoded secrets, logs)
+   - Insecure configuration
+   - Missing input validation at boundaries
+3. **Check security headers and CORS** (if web application)
+4. **Review secrets management:** .env files, config, environment variables
+5. **Produce:** Write `SCAN-RESULTS.md` with all findings
+
+## Phase 2: Triage
+
+**Goal:** Prioritize what to fix now vs later.
+
+1. **Rate each finding:**
+   - Critical: exploitable, high impact, fix immediately
+   - High: likely exploitable, fix in this workflow
+   - Medium: lower risk, fix if time allows
+   - Low: informational, document for later
+2. **Assess exploitability:** Is this theoretical or practically exploitable?
+3. **Produce:** Update `SCAN-RESULTS.md` with severity ratings and triage decisions
+
+4. **Gate:** Review triage with user. Agree on what to remediate now.
+
+## Phase 3: Remediate
+
+**Goal:** Fix critical and high-severity issues.
+
+1. Fix each issue with proper testing
+2. Commit each fix individually: `fix(security): <description>`
+3. Don't introduce new functionality — security fixes only
+
+## Phase 4: Re-scan
+
+**Goal:** Verify fixes and document the final state.
+
+1. Re-run the scans from Phase 1
+2. Verify all targeted issues are resolved
+3. **Produce:** Write `AUDIT-REPORT.md` with:
+   - Summary of findings and fixes
+   - Remaining medium/low items for future attention
+   - Recommendations for ongoing security practices
+
+</process>

package/dist/resources/extensions/gsd/workflow-templates/small-feature.md

@@ -0,0 +1,81 @@
+# Small Feature Workflow
+
+<template_meta>
+name: small-feature
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/features/
+</template_meta>
+
+<purpose>
+Build a small-to-medium feature with lightweight planning. Designed for work that
+needs more structure than /gsd quick but doesn't warrant full milestone ceremony.
+Typical scope: a new command, endpoint, component, or module.
+</purpose>
+
+<phases>
+1. scope      — Define what we're building and confirm boundaries
+2. plan       — Break into 2-5 implementable tasks
+3. implement  — Execute the plan with atomic commits
+4. verify     — Run tests, build, and validate
+</phases>
+
+<process>
+
+## Phase 1: Scope
+
+**Goal:** Align on what to build and what's out of scope.
+
+1. **Understand the request:** Clarify the feature's purpose and user-facing behavior
+2. **Identify gray areas:** Surface 3-4 design decisions that need answers:
+   - API shape / interface design
+   - Where in the codebase this fits
+   - What existing patterns to follow
+   - Edge cases to handle (or explicitly skip)
+3. **Define boundaries:** What's in scope vs out of scope for this workflow
+4. **Produce:** Write a brief `CONTEXT.md` in the artifact directory with:
+   - Feature description
+   - Key decisions made
+   - Scope boundaries
+
+5. **Gate:** Confirm scope with user before planning.
+
+## Phase 2: Plan
+
+**Goal:** Create a clear, executable plan.
+
+1. **Research (if needed):** Read relevant existing code to understand patterns
+2. **Break into tasks:** 2-5 tasks, each independently committable:
+   - Each task should take ~10-30 minutes of AI work
+   - Include file paths and specific changes
+   - Include verification steps per task
+3. **Produce:** Write `PLAN.md` in the artifact directory
+
+4. **Gate:** Present plan to user for approval. Adjust if needed.
+
+## Phase 3: Implement
+
+**Goal:** Build the feature following the plan.
+
+1. Execute tasks in order
+2. After each task:
+   - Verify the specific task's acceptance criteria
+   - Commit with message: `feat(<scope>): <description>`
+3. If a task reveals the plan needs adjustment, note the deviation and adapt
+4. Run incremental tests as you go (don't wait until the end)
+
+## Phase 4: Verify
+
+**Goal:** Ensure everything works together.
+
+1. Run the full test suite
+2. Run the build
+3. Run the linter
+4. Manual smoke check if applicable
+5. **Produce:** Write a brief `SUMMARY.md` with:
+   - What was built
+   - Files changed
+   - How to test/use the feature
+6. Present summary to user
+
+</process>

package/dist/resources/extensions/gsd/workflow-templates/spike.md

@@ -0,0 +1,69 @@
+# Research Spike Workflow
+
+<template_meta>
+name: spike
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/spikes/
+</template_meta>
+
+<purpose>
+Investigate a question, evaluate options, prototype if needed, and produce a
+clear recommendation. No production code is shipped — the output is knowledge.
+Use for: technology evaluation, architecture decisions, "should we X?" questions.
+</purpose>
+
+<phases>
+1. scope      — Define the question and success criteria
+2. research   — Investigate from multiple angles
+3. synthesize — Combine findings into a recommendation
+</phases>
+
+<process>
+
+## Phase 1: Scope
+
+**Goal:** Define exactly what we're investigating and what a good answer looks like.
+
+1. **Frame the question:** What specific question(s) need answering?
+2. **Define success criteria:** What would a useful answer include?
+   - Comparison criteria (performance, DX, maintenance, ecosystem, etc.)
+   - Constraints (must integrate with X, must support Y)
+   - Decision format (go/no-go, pick from options, tradeoff matrix)
+3. **Identify research angles:** 2-3 distinct approaches to investigate:
+   - e.g., "evaluate library A", "evaluate library B", "evaluate building our own"
+   - e.g., "performance implications", "DX implications", "migration path"
+4. **Produce:** Write `SCOPE.md` in the artifact directory
+
+5. **Gate:** Confirm scope and research angles with user.
+
+## Phase 2: Research
+
+**Goal:** Investigate each angle thoroughly.
+
+1. For each research angle:
+   - Search for relevant documentation, benchmarks, comparisons
+   - Read relevant source code in the project
+   - Build small prototypes or proof-of-concepts if needed
+   - Note pros, cons, risks, and unknowns
+2. **Produce:** Write a research doc per angle in `research/` subdirectory:
+   - `research/ANGLE-1.md`, `research/ANGLE-2.md`, etc.
+   - Each doc: findings, evidence, pros/cons, confidence level
+
+## Phase 3: Synthesize
+
+**Goal:** Combine findings into a clear recommendation.
+
+1. **Compare across angles:** Build a comparison matrix or summary table
+2. **Make a recommendation:** Based on the evidence, what should we do?
+   - Primary recommendation with rationale
+   - Alternative if the primary doesn't work out
+   - What would change the recommendation (risk factors)
+3. **Produce:** Write `RECOMMENDATION.md` with:
+   - Executive summary (1-2 paragraphs)
+   - Comparison matrix
+   - Recommendation with rationale
+   - Next steps if the recommendation is accepted
+4. **Present** the recommendation to the user for discussion
+
+</process>

package/dist/resources/extensions/gsd/workflow-templates.ts

@@ -0,0 +1,241 @@
+/**
+ * GSD Workflow Templates — Registry & Resolution
+ *
+ * Loads the workflow template registry and resolves templates by name,
+ * alias, or trigger-keyword matching against user input.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __extensionDir = dirname(fileURLToPath(import.meta.url));
+const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TemplateEntry {
+  name: string;
+  description: string;
+  file: string;
+  phases: string[];
+  triggers: string[];
+  artifact_dir: string | null;
+  estimated_complexity: string;
+  requires_project: boolean;
+}
+
+export interface TemplateRegistry {
+  version: number;
+  templates: Record<string, TemplateEntry>;
+}
+
+export interface TemplateMatch {
+  id: string;
+  template: TemplateEntry;
+  confidence: "exact" | "high" | "medium" | "low";
+  matchedTrigger?: string;
+}
+
+// ─── Registry Cache ──────────────────────────────────────────────────────────
+
+let cachedRegistry: TemplateRegistry | null = null;
+
+/**
+ * Load and cache the workflow template registry.
+ */
+export function loadRegistry(): TemplateRegistry {
+  if (cachedRegistry) return cachedRegistry;
+
+  const content = readFileSync(registryPath, "utf-8");
+  cachedRegistry = JSON.parse(content) as TemplateRegistry;
+  return cachedRegistry;
+}
+
+/**
+ * Resolve a template by exact name or alias.
+ * Returns null if no match found.
+ */
+export function resolveByName(nameOrAlias: string): TemplateMatch | null {
+  const registry = loadRegistry();
+  const normalized = nameOrAlias.toLowerCase().trim();
+
+  // Exact key match
+  if (registry.templates[normalized]) {
+    return {
+      id: normalized,
+      template: registry.templates[normalized],
+      confidence: "exact",
+    };
+  }
+
+  // Match by template name (case-insensitive)
+  for (const [id, entry] of Object.entries(registry.templates)) {
+    if (entry.name.toLowerCase() === normalized) {
+      return { id, template: entry, confidence: "exact" };
+    }
+  }
+
+  // Fuzzy: prefix match on id
+  for (const [id, entry] of Object.entries(registry.templates)) {
+    if (id.startsWith(normalized) || normalized.startsWith(id)) {
+      return { id, template: entry, confidence: "high" };
+    }
+  }
+
+  // Common aliases
+  const aliases: Record<string, string> = {
+    "bug": "bugfix",
+    "fix": "bugfix",
+    "feature": "small-feature",
+    "feat": "small-feature",
+    "research": "spike",
+    "investigate": "spike",
+    "hot": "hotfix",
+    "urgent": "hotfix",
+    "security": "security-audit",
+    "audit": "security-audit",
+    "upgrade": "dep-upgrade",
+    "deps": "dep-upgrade",
+    "update-deps": "dep-upgrade",
+    "migration": "refactor",
+    "project": "full-project",
+    "full": "full-project",
+  };
+
+  const aliasMatch = aliases[normalized];
+  if (aliasMatch && registry.templates[aliasMatch]) {
+    return {
+      id: aliasMatch,
+      template: registry.templates[aliasMatch],
+      confidence: "high",
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Auto-detect the best template based on user description text.
+ * Returns ranked matches sorted by confidence.
+ */
+export function autoDetect(description: string): TemplateMatch[] {
+  const registry = loadRegistry();
+  const lower = description.toLowerCase();
+  const words = lower.split(/\s+/);
+  const matches: TemplateMatch[] = [];
+
+  for (const [id, entry] of Object.entries(registry.templates)) {
+    let bestScore = 0;
+    let bestTrigger = "";
+
+    for (const trigger of entry.triggers) {
+      const triggerLower = trigger.toLowerCase();
+
+      // Exact phrase match in description
+      if (lower.includes(triggerLower)) {
+        const score = triggerLower.split(/\s+/).length * 2; // multi-word triggers score higher
+        if (score > bestScore) {
+          bestScore = score;
+          bestTrigger = trigger;
+        }
+        continue;
+      }
+
+      // Single-word trigger match against description words
+      if (!triggerLower.includes(" ") && words.includes(triggerLower)) {
+        if (1 > bestScore) {
+          bestScore = 1;
+          bestTrigger = trigger;
+        }
+      }
+    }
+
+    if (bestScore > 0) {
+      const confidence = bestScore >= 4 ? "high" : bestScore >= 2 ? "medium" : "low";
+      matches.push({
+        id,
+        template: entry,
+        confidence,
+        matchedTrigger: bestTrigger,
+      });
+    }
+  }
+
+  // Sort by confidence (high > medium > low), then alphabetically
+  const order = { exact: 0, high: 1, medium: 2, low: 3 };
+  matches.sort((a, b) => order[a.confidence] - order[b.confidence] || a.id.localeCompare(b.id));
+
+  return matches;
+}
+
+/**
+ * List all templates as formatted text for display.
+ */
+export function listTemplates(): string {
+  const registry = loadRegistry();
+  const lines: string[] = ["Workflow Templates\n"];
+
+  for (const [id, entry] of Object.entries(registry.templates)) {
+    const phases = entry.phases.join(" → ");
+    const complexity = entry.estimated_complexity;
+    lines.push(`  ${id.padEnd(16)} ${entry.name}`);
+    lines.push(`  ${"".padEnd(16)} ${entry.description}`);
+    lines.push(`  ${"".padEnd(16)} Phases: ${phases}  |  Complexity: ${complexity}`);
+    lines.push("");
+  }
+
+  lines.push("Usage: /gsd start <template> [description]");
+  lines.push("       /gsd templates info <name>");
+
+  return lines.join("\n");
+}
+
+/**
+ * Get detailed info about a specific template.
+ */
+export function getTemplateInfo(name: string): string | null {
+  const match = resolveByName(name);
+  if (!match) return null;
+
+  const { id, template: t } = match;
+  const lines = [
+    `Template: ${t.name} (${id})`,
+    "",
+    `Description: ${t.description}`,
+    `Complexity:  ${t.estimated_complexity}`,
+    `Requires .gsd/: ${t.requires_project ? "yes" : "no"}`,
+    "",
+    "Phases:",
+    ...t.phases.map((p, i) => `  ${i + 1}. ${p}`),
+    "",
+    "Triggers:",
+    `  ${t.triggers.join(", ")}`,
+  ];
+
+  if (t.artifact_dir) {
+    lines.push("", `Artifacts: ${t.artifact_dir}`);
+  }
+
+  const templateFilePath = join(__extensionDir, "workflow-templates", t.file);
+  if (existsSync(templateFilePath)) {
+    lines.push("", "Template file: loaded");
+  } else {
+    lines.push("", "Template file: not yet created");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Load the raw content of a workflow template .md file.
+ */
+export function loadWorkflowTemplate(templateId: string): string | null {
+  const match = resolveByName(templateId);
+  if (!match) return null;
+
+  const filePath = join(__extensionDir, "workflow-templates", match.template.file);
+  if (!existsSync(filePath)) return null;
+
+  return readFileSync(filePath, "utf-8");
+}

package/dist/resources/extensions/gsd/worktree-command.ts

@@ -12,9 +12,9 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { loadPrompt } from "./prompt-loader.js";
-import { autoCommitCurrentBranch } from "./worktree.js";
+import { autoCommitCurrentBranch, getMainBranch, resolveGitHeadPath, nudgeGitBranchCache } from "./worktree.js";
 import { runWorktreePostCreateHook } from "./auto-worktree.js";
-import { showConfirm } from "../shared/confirm-ui.js";
+import { showConfirm } from "../shared/mod.js";
 import { gsdRoot, milestonesDir } from "./paths.js";
 import {
   createWorktree,
@@ -23,7 +23,6 @@ import {
   mergeWorktreeToMain,
   diffWorktreeAll,
   diffWorktreeNumstat,
-  getMainBranch,
   getWorktreeGSDDiff,
   getWorktreeCodeDiff,
   getWorktreeLog,
@@ -32,9 +31,9 @@ import {
 } from "./worktree-manager.js";
 import { inferCommitType } from "./git-service.js";
 import type { FileLineStat } from "./worktree-manager.js";
-import { existsSync, realpathSync, readFileSync, readdirSync, rmSync, unlinkSync, utimesSync } from "node:fs";
+import { existsSync, realpathSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { nativeMergeAbort } from "./native-git-bridge.js";
-import { join, resolve, sep } from "node:path";
+import { join, sep } from "node:path";
 
 /**
  * Tracks the original project root so we can switch back.
@@ -47,52 +46,6 @@ export function getWorktreeOriginalCwd(): string | null {
   return originalCwd;
 }
 
-/**
- * Resolve the git HEAD file path for a given directory.
- * Handles both normal repos (.git is a directory) and worktrees (.git is a file).
- */
-function resolveGitHeadPath(dir: string): string | null {
-  const gitPath = join(dir, ".git");
-  if (!existsSync(gitPath)) return null;
-
-  try {
-    const content = readFileSync(gitPath, "utf8").trim();
-    if (content.startsWith("gitdir: ")) {
-      // Worktree — .git is a file pointing to the real gitdir
-      const gitDir = resolve(dir, content.slice(8));
-      const headPath = join(gitDir, "HEAD");
-      return existsSync(headPath) ? headPath : null;
-    }
-    // Normal repo — .git is a directory
-    const headPath = join(dir, ".git", "HEAD");
-    return existsSync(headPath) ? headPath : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Nudge pi's FooterDataProvider to re-read the git branch.
- *
- * The footer caches the branch and watches a single .git dir for changes.
- * After process.chdir() into a worktree (or back), the watcher is stale —
- * it's still watching the old git dir. We touch HEAD in both the old and
- * new git dirs to ensure the watcher fires regardless of which one it's
- * monitoring. This clears cachedBranch; the next getGitBranch() call uses
- * the new process.cwd() and picks up the correct branch.
- */
-function nudgeGitBranchCache(previousCwd: string): void {
-  const now = new Date();
-  for (const dir of [previousCwd, process.cwd()]) {
-    try {
-      const headPath = resolveGitHeadPath(dir);
-      if (headPath) utimesSync(headPath, now, now);
-    } catch {
-      // Best-effort — branch display may be stale
-    }
-  }
-}
-
 /** Get the name of the active worktree, or null if not in one. */
 export function getActiveWorktreeName(): string | null {
   if (!originalCwd) return null;

package/dist/resources/extensions/gsd/worktree-manager.ts

@@ -17,6 +17,7 @@
 
 import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
 import {
   nativeBranchDelete,
   nativeBranchExists,
@@ -70,10 +71,6 @@ function normalizePathForComparison(path: string): string {
   return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
-export function getMainBranch(basePath: string): string {
-  return nativeDetectMainBranch(basePath);
-}
-
 // ─── resolveGitDir ─────────────────────────────────────────────────────────
 
 /**
@@ -125,14 +122,14 @@ export function worktreeBranchName(name: string): string {
 export function createWorktree(basePath: string, name: string, opts: { branch?: string; startPoint?: string; reuseExistingBranch?: boolean } = {}): WorktreeInfo {
   // Validate name: alphanumeric, hyphens, underscores only
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    throw new Error(`Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
+    throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
   }
 
   const wtPath = worktreePath(basePath, name);
   const branch = opts.branch ?? worktreeBranchName(name);
 
   if (existsSync(wtPath)) {
-    throw new Error(`Worktree "${name}" already exists at ${wtPath}`);
+    throw new GSDError(GSD_STALE_STATE, `Worktree "${name}" already exists at ${wtPath}`);
   }
 
   // Ensure the .gsd/worktrees/ directory exists
@@ -155,7 +152,8 @@ export function createWorktree(basePath: string, name: string, opts: { branch?:
     const branchInUse = worktreeEntries.some(entry => entry.branch === branch);
 
     if (branchInUse) {
-      throw new Error(
+      throw new GSDError(
+        GSD_LOCK_HELD,
         `Branch "${branch}" is already in use by another worktree. ` +
         `Remove the existing worktree first with /worktree remove ${name}.`,
       );
@@ -436,12 +434,12 @@ export function mergeWorktreeToMain(basePath: string, name: string, commitMessag
   const current = nativeGetCurrentBranch(basePath);
 
   if (current !== mainBranch) {
-    throw new Error(`Must be on ${mainBranch} to merge. Currently on ${current}.`);
+    throw new GSDError(GSD_GIT_ERROR, `Must be on ${mainBranch} to merge. Currently on ${current}.`);
   }
 
   const result = nativeMergeSquash(basePath, branch);
   if (!result.success) {
-    throw new Error(`Merge conflicts detected in: ${result.conflicts.join(", ")}`);
+    throw new GSDError(GSD_MERGE_CONFLICT, `Merge conflicts detected in: ${result.conflicts.join(", ")}`);
   }
 
   nativeCommit(basePath, commitMessage);

package/dist/resources/extensions/gsd/worktree.ts

@@ -12,7 +12,8 @@
  * SLICE_BRANCH_RE) remain for backwards compatibility with legacy branches.
  */
 
-import { sep } from "node:path";
+import { existsSync, readFileSync, utimesSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
 
 import { GitServiceImpl, writeIntegrationBranch, type TaskCommitContext } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -177,4 +178,43 @@ export function autoCommitCurrentBranch(
   return getService(basePath).autoCommit(unitType, unitId, [], taskContext);
 }
 
+// ─── Git HEAD Resolution ────────────────────────────────────────────────────
 
+/**
+ * Resolve the git HEAD file path for a given directory.
+ * Handles both normal repos (.git is a directory) and worktrees (.git is a file
+ * containing a `gitdir:` pointer to the real gitdir).
+ */
+export function resolveGitHeadPath(dir: string): string | null {
+  const gitPath = join(dir, ".git");
+  if (!existsSync(gitPath)) return null;
+
+  try {
+    const content = readFileSync(gitPath, "utf8").trim();
+    if (content.startsWith("gitdir: ")) {
+      const gitDir = resolve(dir, content.slice(8));
+      const headPath = join(gitDir, "HEAD");
+      return existsSync(headPath) ? headPath : null;
+    }
+    const headPath = join(dir, ".git", "HEAD");
+    return existsSync(headPath) ? headPath : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Nudge pi's FooterDataProvider to re-read the git branch after chdir.
+ * Touches HEAD in both old and new cwd to fire the fs watcher.
+ */
+export function nudgeGitBranchCache(previousCwd: string): void {
+  const now = new Date();
+  for (const dir of [previousCwd, process.cwd()]) {
+    try {
+      const headPath = resolveGitHeadPath(dir);
+      if (headPath) utimesSync(headPath, now, now);
+    } catch {
+      // Best-effort
+    }
+  }
+}