gsd-pi 2.18.0 → 2.20.0

package/src/resources/extensions/gsd/tests/worktree-post-create-hook.test.ts

@@ -0,0 +1,165 @@
+/**
+ * worktree-post-create-hook.test.ts — Tests for #597 worktree post-create hook.
+ *
+ * Verifies that runWorktreePostCreateHook correctly executes user scripts
+ * with SOURCE_DIR and WORKTREE_DIR environment variables.
+ *
+ * Uses Node.js scripts instead of bash for Windows compatibility.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync, readFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { runWorktreePostCreateHook } from "../auto-worktree.ts";
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-wt-hook-test-"));
+}
+
+const isWin = process.platform === "win32";
+
+/** Return the platform-appropriate hook file path (adds .bat on Windows). */
+function hookPath(base: string): string {
+  return isWin ? `${base}.bat` : base;
+}
+
+/** Create a cross-platform Node.js hook script. */
+function writeNodeHookScript(filePath: string, code: string): void {
+  if (isWin) {
+    // Write the JS code to a companion .js file and have the .bat invoke it.
+    // node -e with multi-line code breaks on Windows because cmd.exe splits on newlines.
+    const jsPath = filePath.replace(/\.bat$/, ".js");
+    writeFileSync(jsPath, code);
+    writeFileSync(filePath, `@echo off\nnode "%~dp0${jsPath.split("\\").pop()}" %*\n`);
+  } else {
+    writeFileSync(filePath, `#!/usr/bin/env node\n${code}\n`);
+    chmodSync(filePath, 0o755);
+  }
+}
+
+// ─── runWorktreePostCreateHook ──────────────────────────────────────────────
+
+test("returns null when no hook path is provided", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    const result = runWorktreePostCreateHook(src, wt, undefined);
+    assert.equal(result, null);
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("returns error when hook script does not exist", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    const result = runWorktreePostCreateHook(src, wt, ".gsd/hooks/nonexistent");
+    assert.ok(result !== null, "should return error string");
+    assert.ok(result!.includes("not found"), "error should mention 'not found'");
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("executes hook script with correct SOURCE_DIR and WORKTREE_DIR env vars", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    const hookFile = hookPath(join(hooksDir, "post-create"));
+    const code = [
+      `const fs = require("fs");`,
+      `const path = require("path");`,
+      `const out = path.join(process.env.WORKTREE_DIR, "hook-output.txt");`,
+      `fs.writeFileSync(out, "SOURCE=" + process.env.SOURCE_DIR + "\\n" + "WORKTREE=" + process.env.WORKTREE_DIR + "\\n");`,
+    ].join("\n");
+    writeNodeHookScript(hookFile, code);
+
+    const result = runWorktreePostCreateHook(src, wt, hookPath(".gsd/hooks/post-create"));
+    assert.equal(result, null, "should succeed");
+
+    const outputFile = join(wt, "hook-output.txt");
+    assert.ok(existsSync(outputFile), "hook should have created output file");
+
+    const output = readFileSync(outputFile, "utf-8");
+    assert.ok(output.includes(`SOURCE=${src}`), "SOURCE_DIR should match source dir");
+    assert.ok(output.includes(`WORKTREE=${wt}`), "WORKTREE_DIR should match worktree dir");
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("returns error message when hook script fails", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    const hookFile = hookPath(join(hooksDir, "failing-hook"));
+    writeNodeHookScript(hookFile, `process.exit(1);`);
+
+    const result = runWorktreePostCreateHook(src, wt, hookPath(".gsd/hooks/failing-hook"));
+    assert.ok(result !== null, "should return error string");
+    assert.ok(result!.includes("hook failed"), "error should mention 'hook failed'");
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("supports absolute hook paths", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    const hookFile = hookPath(join(src, "absolute-hook"));
+    const code = [
+      `const fs = require("fs");`,
+      `const path = require("path");`,
+      `fs.writeFileSync(path.join(process.env.WORKTREE_DIR, "absolute-hook-ran"), "");`,
+    ].join("\n");
+    writeNodeHookScript(hookFile, code);
+
+    const result = runWorktreePostCreateHook(src, wt, hookFile);
+    assert.equal(result, null, "absolute path hook should succeed");
+    assert.ok(existsSync(join(wt, "absolute-hook-ran")), "hook should have run");
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("hook can copy files from source to worktree", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  try {
+    writeFileSync(join(src, ".env"), "DB_HOST=localhost\nAPI_KEY=secret123\n");
+
+    const hookFile = hookPath(join(src, "setup-hook"));
+    const code = [
+      `const fs = require("fs");`,
+      `const path = require("path");`,
+      `const envSrc = path.join(process.env.SOURCE_DIR, ".env");`,
+      `const envDst = path.join(process.env.WORKTREE_DIR, ".env");`,
+      `fs.copyFileSync(envSrc, envDst);`,
+    ].join("\n");
+    writeNodeHookScript(hookFile, code);
+
+    const result = runWorktreePostCreateHook(src, wt, hookFile);
+    assert.equal(result, null, "hook should succeed");
+
+    assert.ok(existsSync(join(wt, ".env")), ".env should be copied to worktree");
+    const envContent = readFileSync(join(wt, ".env"), "utf-8");
+    assert.ok(envContent.includes("API_KEY=secret123"), ".env content should match");
+  } finally {
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/triage-resolution.ts

@@ -0,0 +1,200 @@
+/**
+ * GSD Triage Resolution — Execute triage classifications
+ *
+ * Provides resolution executors for each capture classification type:
+ *
+ * - inject: appends a new task to the current slice plan
+ * - replan: writes REPLAN-TRIGGER.md so next dispatchNextUnit enters replanning-slice
+ * - defer/note: query helpers for loading deferred/replan captures
+ *
+ * Also provides detectFileOverlap() for surfacing downstream impact on quick tasks.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Classification, CaptureEntry } from "./captures.js";
+import {
+  loadPendingCaptures,
+  loadAllCaptures,
+  markCaptureResolved,
+} from "./captures.js";
+
+// ─── Resolution Executors ─────────────────────────────────────────────────────
+
+/**
+ * Inject a new task into the current slice plan.
+ * Reads the plan, finds the highest task ID, appends a new task entry.
+ * Returns the new task ID, or null if injection failed.
+ */
+export function executeInject(
+  basePath: string,
+  mid: string,
+  sid: string,
+  capture: CaptureEntry,
+): string | null {
+  try {
+    // Resolve the plan file path
+    const planPath = join(basePath, ".gsd", "milestones", mid, "slices", sid, `${sid}-PLAN.md`);
+    if (!existsSync(planPath)) return null;
+
+    const content = readFileSync(planPath, "utf-8");
+
+    // Find the highest existing task ID
+    const taskMatches = [...content.matchAll(/- \[[ x]\] \*\*T(\d+):/g)];
+    if (taskMatches.length === 0) return null;
+
+    const maxId = Math.max(...taskMatches.map(m => parseInt(m[1], 10)));
+    const newId = `T${String(maxId + 1).padStart(2, "0")}`;
+
+    // Build the new task entry
+    const newTask = [
+      `- [ ] **${newId}: ${capture.text}** \`est:30m\``,
+      `  - Why: Injected from capture ${capture.id} during triage`,
+      `  - Do: ${capture.text}`,
+      `  - Done when: Capture intent fulfilled`,
+    ].join("\n");
+
+    // Find the last task entry and append after it
+    // Look for the "## Files Likely Touched" section as the boundary
+    const filesSection = content.indexOf("## Files Likely Touched");
+    if (filesSection !== -1) {
+      const updated = content.slice(0, filesSection) + newTask + "\n\n" + content.slice(filesSection);
+      writeFileSync(planPath, updated, "utf-8");
+    } else {
+      // No Files section — append at end
+      writeFileSync(planPath, content.trimEnd() + "\n\n" + newTask + "\n", "utf-8");
+    }
+
+    return newId;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Trigger replanning by writing a REPLAN-TRIGGER.md marker file.
+ * The existing state.ts derivation detects this and sets phase to "replanning-slice".
+ * Returns true if the trigger was written successfully.
+ */
+export function executeReplan(
+  basePath: string,
+  mid: string,
+  sid: string,
+  capture: CaptureEntry,
+): boolean {
+  try {
+    const triggerPath = join(
+      basePath, ".gsd", "milestones", mid, "slices", sid, `${sid}-REPLAN-TRIGGER.md`,
+    );
+    const content = [
+      `# Replan Trigger`,
+      ``,
+      `**Source:** Capture ${capture.id}`,
+      `**Capture:** ${capture.text}`,
+      `**Rationale:** ${capture.rationale ?? "User-initiated replan via capture triage"}`,
+      `**Triggered:** ${new Date().toISOString()}`,
+      ``,
+      `This file was created by the triage pipeline. The next dispatch cycle`,
+      `will detect it and enter the replanning-slice phase.`,
+    ].join("\n");
+
+    writeFileSync(triggerPath, content, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── File Overlap Detection ───────────────────────────────────────────────────
+
+/**
+ * Detect file overlap between a capture's affected files and planned tasks.
+ *
+ * Parses the slice plan for task file references and returns task IDs
+ * whose files overlap with the capture's affected files.
+ *
+ * @param affectedFiles - Files the capture would touch
+ * @param planContent - Content of the slice plan.md
+ * @returns Array of task IDs (e.g., ["T03", "T04"]) whose files overlap
+ */
+export function detectFileOverlap(
+  affectedFiles: string[],
+  planContent: string,
+): string[] {
+  if (!affectedFiles || affectedFiles.length === 0) return [];
+
+  const overlappingTasks: string[] = [];
+
+  // Normalize affected files for comparison
+  const normalizedAffected = new Set(
+    affectedFiles.map(f => f.replace(/^\.\//, "").toLowerCase()),
+  );
+
+  // Parse plan for incomplete tasks and their file references
+  const taskPattern = /- \[ \] \*\*(T\d+):[^*]*\*\*/g;
+  const tasks = [...planContent.matchAll(taskPattern)];
+
+  for (const taskMatch of tasks) {
+    const taskId = taskMatch[1];
+    const taskStart = taskMatch.index!;
+
+    // Find the end of this task (next task or end of section)
+    const nextTask = planContent.indexOf("- [", taskStart + 1);
+    const sectionEnd = planContent.indexOf("##", taskStart + 1);
+    const taskEnd = Math.min(
+      nextTask === -1 ? planContent.length : nextTask,
+      sectionEnd === -1 ? planContent.length : sectionEnd,
+    );
+
+    const taskContent = planContent.slice(taskStart, taskEnd);
+
+    // Extract file references — look for backtick-quoted paths
+    const fileRefs = [...taskContent.matchAll(/`([^`]+\.[a-z]+)`/g)]
+      .map(m => m[1].replace(/^\.\//, "").toLowerCase());
+
+    // Check for overlap
+    const hasOverlap = fileRefs.some(f => normalizedAffected.has(f));
+    if (hasOverlap) {
+      overlappingTasks.push(taskId);
+    }
+  }
+
+  return overlappingTasks;
+}
+
+/**
+ * Load deferred captures (classification === "defer") for injection into
+ * reassess-roadmap prompts.
+ */
+export function loadDeferredCaptures(basePath: string): CaptureEntry[] {
+  return loadAllCaptures(basePath).filter(c => c.classification === "defer");
+}
+
+/**
+ * Load replan-triggering captures for injection into replan-slice prompts.
+ */
+export function loadReplanCaptures(basePath: string): CaptureEntry[] {
+  return loadAllCaptures(basePath).filter(c => c.classification === "replan");
+}
+
+/**
+ * Build a quick-task execution prompt from a capture.
+ */
+export function buildQuickTaskPrompt(capture: CaptureEntry): string {
+  return [
+    `You are executing a quick one-off task captured during a GSD auto-mode session.`,
+    ``,
+    `## Quick Task`,
+    ``,
+    `**Capture ID:** ${capture.id}`,
+    `**Task:** ${capture.text}`,
+    ``,
+    `## Instructions`,
+    ``,
+    `1. Execute this task as a small, self-contained change.`,
+    `2. Do NOT modify any \`.gsd/\` plan files — this is a one-off, not a planned task.`,
+    `3. Commit your changes with a descriptive message.`,
+    `4. Keep changes minimal and focused on the capture text.`,
+    `5. When done, say: "Quick task complete."`,
+  ].join("\n");
+}

package/src/resources/extensions/gsd/triage-ui.ts

@@ -0,0 +1,175 @@
+/**
+ * GSD Triage UI — Confirmation flow for programmatic triage results
+ *
+ * Used by auto-mode dispatch (S02) when triage fires between tasks.
+ * For manual `/gsd triage`, the LLM session handles confirmation directly.
+ *
+ * This module provides `showTriageConfirmation` which presents each
+ * triage result to the user via `showNextAction` and returns the
+ * confirmed classifications.
+ */
+
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { showNextAction } from "../shared/next-action-ui.js";
+import type { CaptureEntry, Classification, TriageResult } from "./captures.js";
+import { markCaptureResolved } from "./captures.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ConfirmedTriage {
+  captureId: string;
+  classification: Classification;
+  rationale: string;
+  affectedFiles?: string[];
+  targetSlice?: string;
+  userOverride: boolean;  // true if user changed the proposed classification
+}
+
+// ─── Classification Labels ────────────────────────────────────────────────────
+
+const CLASSIFICATION_LABELS: Record<Classification, { label: string; description: string }> = {
+  "quick-task": {
+    label: "Quick task",
+    description: "Execute as a one-off at the next seam — no plan modification.",
+  },
+  "inject": {
+    label: "Inject into plan",
+    description: "Add a new task to the current slice plan.",
+  },
+  "defer": {
+    label: "Defer",
+    description: "Move to a future slice or milestone — not urgent now.",
+  },
+  "replan": {
+    label: "Replan slice",
+    description: "Remaining tasks need rewriting — triggers slice replan.",
+  },
+  "note": {
+    label: "Note",
+    description: "Informational only — no action needed.",
+  },
+};
+
+const ALL_CLASSIFICATIONS: Classification[] = [
+  "quick-task", "inject", "defer", "replan", "note",
+];
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Present triage results to the user for confirmation.
+ *
+ * For each capture:
+ * - note/defer: auto-confirm (no user interaction needed)
+ * - quick-task/inject/replan: show confirmation UI with proposed + alternatives
+ *
+ * Returns confirmed results with final classifications.
+ * Updates CAPTURES.md with resolved status.
+ *
+ * @param fileOverlaps - Map of captureId → list of planned task IDs whose files overlap
+ */
+export async function showTriageConfirmation(
+  ctx: ExtensionCommandContext,
+  triageResults: TriageResult[],
+  captures: CaptureEntry[],
+  basePath: string,
+  fileOverlaps?: Map<string, string[]>,
+): Promise<ConfirmedTriage[]> {
+  const confirmed: ConfirmedTriage[] = [];
+  const captureMap = new Map(captures.map(c => [c.id, c]));
+
+  for (const result of triageResults) {
+    const capture = captureMap.get(result.captureId);
+    if (!capture) continue;
+
+    // Auto-confirm note and defer — low-impact, no plan modification
+    if (result.classification === "note" || result.classification === "defer") {
+      const resolution = result.classification === "note"
+        ? "acknowledged as note"
+        : `deferred${result.targetSlice ? ` to ${result.targetSlice}` : ""}`;
+
+      markCaptureResolved(
+        basePath,
+        result.captureId,
+        result.classification,
+        resolution,
+        result.rationale,
+      );
+
+      confirmed.push({
+        captureId: result.captureId,
+        classification: result.classification,
+        rationale: result.rationale,
+        affectedFiles: result.affectedFiles,
+        targetSlice: result.targetSlice,
+        userOverride: false,
+      });
+      continue;
+    }
+
+    // Build summary lines for the confirmation UI
+    const summary: string[] = [
+      `"${capture.text}"`,
+      "",
+      `Proposed: **${CLASSIFICATION_LABELS[result.classification].label}** — ${result.rationale}`,
+    ];
+
+    // Add file overlap warning if present
+    const overlaps = fileOverlaps?.get(result.captureId);
+    if (overlaps && overlaps.length > 0) {
+      summary.push("");
+      summary.push(`⚠ Touches files planned for ${overlaps.join(", ")} — consider inject or defer`);
+    }
+
+    if (result.affectedFiles && result.affectedFiles.length > 0) {
+      summary.push("");
+      summary.push(`Files: ${result.affectedFiles.join(", ")}`);
+    }
+
+    // Build action options — proposed first (recommended), then alternatives
+    const proposed = result.classification;
+    const actions = ALL_CLASSIFICATIONS.map(cls => ({
+      id: cls,
+      label: CLASSIFICATION_LABELS[cls].label,
+      description: CLASSIFICATION_LABELS[cls].description,
+      recommended: cls === proposed,
+    }));
+
+    const choice = await showNextAction(ctx as any, {
+      title: `Triage: ${result.captureId}`,
+      summary,
+      actions,
+      notYetMessage: "Capture will remain pending for later triage.",
+    });
+
+    if (choice === "not_yet") {
+      // User skipped — leave capture pending
+      continue;
+    }
+
+    const finalClassification = choice as Classification;
+    const userOverride = finalClassification !== proposed;
+    const resolution = userOverride
+      ? `user chose ${finalClassification} (was ${proposed})`
+      : `confirmed as ${finalClassification}`;
+
+    markCaptureResolved(
+      basePath,
+      result.captureId,
+      finalClassification,
+      resolution,
+      userOverride ? `User override: ${result.rationale}` : result.rationale,
+    );
+
+    confirmed.push({
+      captureId: result.captureId,
+      classification: finalClassification,
+      rationale: result.rationale,
+      affectedFiles: result.affectedFiles,
+      targetSlice: result.targetSlice,
+      userOverride,
+    });
+  }
+
+  return confirmed;
+}

package/src/resources/extensions/gsd/types.ts

@@ -334,3 +334,32 @@ export interface HookStatusEntry {
   /** Current cycle counts for active triggers. */
   activeCycles: Record<string, number>;
 }
+
+// ─── Database Types (Decisions & Requirements) ────────────────────────────
+
+export interface Decision {
+  seq: number;              // auto-increment primary key
+  id: string;               // e.g. "D001"
+  when_context: string;     // when/context of the decision
+  scope: string;            // scope (milestone, slice, global, etc.)
+  decision: string;         // what was decided
+  choice: string;           // the specific choice made
+  rationale: string;        // why this choice
+  revisable: string;        // whether/when revisable
+  superseded_by: string | null;  // ID of superseding decision, or null
+}
+
+export interface Requirement {
+  id: string;               // e.g. "R001"
+  class: string;            // requirement class (functional, non-functional, etc.)
+  status: string;           // active, validated, deferred, etc.
+  description: string;      // short description
+  why: string;              // rationale
+  source: string;           // origin (milestone, user, etc.)
+  primary_owner: string;    // owning slice/milestone
+  supporting_slices: string; // other slices that touch this
+  validation: string;       // how to validate
+  notes: string;            // additional notes
+  full_content: string;     // full requirement text
+  superseded_by: string | null;  // ID of superseding requirement, or null
+}

package/src/resources/extensions/gsd/undo.ts

@@ -1,6 +1,5 @@
 // GSD Extension — Undo Last Unit
 // Rollback the most recent completed unit: revert git, remove state, uncheck plans.
-// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import type { ExtensionCommandContext, ExtensionAPI } from "@gsd/pi-coding-agent";
 import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from "node:fs";

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -36,6 +36,7 @@ export interface AutoUnitRuntimeRecord {
   updatedAt: number;
   phase: UnitRuntimePhase;
   wrapupWarningSent: boolean;
+  continueHereFired: boolean;
   timeoutAt: number | null;
   lastProgressAt: number;
   progressCount: number;
@@ -50,7 +51,9 @@ function runtimeDir(basePath: string): string {
 }
 
 function runtimePath(basePath: string, unitType: string, unitId: string): string {
-  return join(runtimeDir(basePath), `${unitType}-${unitId.replace(/[\/]/g, "-")}.json`);
+  const sanitizedUnitType = unitType.replace(/[\/]/g, "-");
+  const sanitizedUnitId = unitId.replace(/[\/]/g, "-");
+  return join(runtimeDir(basePath), `${sanitizedUnitType}-${sanitizedUnitId}.json`);
 }
 
 export function writeUnitRuntimeRecord(
@@ -72,6 +75,7 @@ export function writeUnitRuntimeRecord(
     updatedAt: Date.now(),
     phase: updates.phase ?? prev?.phase ?? "dispatched",
     wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+    continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
     timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
     lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
     progressCount: updates.progressCount ?? prev?.progressCount ?? 0,