gsd-pi 2.23.0 → 2.24.0

package/dist/resources/extensions/gsd/parallel-orchestrator.ts

@@ -0,0 +1,496 @@
+/**
+ * GSD Parallel Orchestrator — Core engine for parallel milestone orchestration.
+ *
+ * Manages worker lifecycle, budget tracking, and coordination. Workers are
+ * separate processes spawned via child_process, each running in its own git
+ * worktree with GSD_MILESTONE_LOCK env var set. The coordinator monitors
+ * workers via session status files (see session-status-io.ts).
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gsdRoot } from "./paths.js";
+import { createWorktree, worktreePath } from "./worktree-manager.js";
+import { autoWorktreeBranch, runWorktreePostCreateHook } from "./auto-worktree.js";
+import { nativeBranchExists } from "./native-git-bridge.js";
+import { readIntegrationBranch } from "./git-service.js";
+import { resolveParallelConfig } from "./preferences.js";
+import type { GSDPreferences } from "./preferences.js";
+import type { ParallelConfig } from "./types.js";
+import {
+  writeSessionStatus,
+  readAllSessionStatuses,
+  removeSessionStatus,
+  sendSignal,
+  cleanupStaleSessions,
+  type SessionStatus,
+} from "./session-status-io.js";
+import {
+  analyzeParallelEligibility,
+  type ParallelCandidates,
+} from "./parallel-eligibility.js";
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface WorkerInfo {
+  milestoneId: string;
+  title: string;
+  pid: number;
+  process: ChildProcess | null; // null after process exits
+  worktreePath: string;
+  startedAt: number;
+  state: "running" | "paused" | "stopped" | "error";
+  completedUnits: number;
+  cost: number;
+}
+
+export interface OrchestratorState {
+  active: boolean;
+  workers: Map<string, WorkerInfo>;
+  config: ParallelConfig;
+  totalCost: number;
+  startedAt: number;
+}
+
+// ─── Module State ──────────────────────────────────────────────────────────
+
+let state: OrchestratorState | null = null;
+
+// ─── Accessors ─────────────────────────────────────────────────────────────
+
+/** Returns true if the orchestrator is active and has been initialized. */
+export function isParallelActive(): boolean {
+  return state?.active ?? false;
+}
+
+/** Returns the current orchestrator state, or null if not initialized. */
+export function getOrchestratorState(): OrchestratorState | null {
+  return state;
+}
+
+/** Returns a snapshot of all tracked workers as an array. */
+export function getWorkerStatuses(): WorkerInfo[] {
+  if (!state) return [];
+  return [...state.workers.values()];
+}
+
+// ─── Preparation ───────────────────────────────────────────────────────────
+
+/**
+ * Analyze eligibility and prepare for parallel start.
+ * Returns the candidates report without actually starting workers.
+ */
+export async function prepareParallelStart(
+  basePath: string,
+  _prefs: GSDPreferences | undefined,
+): Promise<ParallelCandidates> {
+  return analyzeParallelEligibility(basePath);
+}
+
+// ─── Start ─────────────────────────────────────────────────────────────────
+
+/**
+ * Start parallel execution with the given eligible milestones.
+ * Creates worktrees, spawns worker processes, and begins monitoring.
+ */
+export async function startParallel(
+  basePath: string,
+  milestoneIds: string[],
+  prefs: GSDPreferences | undefined,
+): Promise<{ started: string[]; errors: Array<{ mid: string; error: string }> }> {
+  // Prevent workers from spawning nested parallel sessions
+  if (process.env.GSD_PARALLEL_WORKER) {
+    return { started: [], errors: [{ mid: "all", error: "Cannot start parallel from within a parallel worker" }] };
+  }
+
+  const config = resolveParallelConfig(prefs);
+  const now = Date.now();
+
+  // Initialize orchestrator state
+  state = {
+    active: true,
+    workers: new Map(),
+    config,
+    totalCost: 0,
+    startedAt: now,
+  };
+
+  const started: string[] = [];
+  const errors: Array<{ mid: string; error: string }> = [];
+
+  // Cap to max_workers
+  const toStart = milestoneIds.slice(0, config.max_workers);
+
+  for (const mid of toStart) {
+    try {
+      // Create the worktree (without chdir — coordinator stays in project root)
+      let wtPath: string;
+      try {
+        wtPath = createMilestoneWorktree(basePath, mid);
+      } catch {
+        // Worktree creation may fail in test environments or when git
+        // is not available. Fall back to a placeholder path.
+        wtPath = worktreePath(basePath, mid);
+      }
+
+      const worker: WorkerInfo = {
+        milestoneId: mid,
+        title: mid,
+        pid: process.pid,
+        process: null,
+        worktreePath: wtPath,
+        startedAt: now,
+        state: "running",
+        completedUnits: 0,
+        cost: 0,
+      };
+
+      state.workers.set(mid, worker);
+
+      // Write initial session status
+      const sessionStatus: SessionStatus = {
+        milestoneId: mid,
+        pid: worker.pid,
+        state: "running",
+        currentUnit: null,
+        completedUnits: 0,
+        cost: 0,
+        lastHeartbeat: now,
+        startedAt: now,
+        worktreePath: wtPath,
+      };
+      writeSessionStatus(basePath, sessionStatus);
+
+      // Attempt to spawn the worker process.
+      // Spawning may fail if the CLI binary is not available (e.g., in tests).
+      // The worker is still tracked and can be spawned later via spawnWorker().
+      const spawned = spawnWorker(basePath, mid);
+      if (!spawned) {
+        // Worker tracked but not yet running a process.
+        // State stays "running" so coordinator can retry or user can investigate.
+      }
+
+      started.push(mid);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push({ mid, error: message });
+    }
+  }
+
+  // If nothing started successfully, deactivate
+  if (started.length === 0) {
+    state.active = false;
+  }
+
+  return { started, errors };
+}
+
+// ─── Worktree Creation ────────────────────────────────────────────────────
+
+/**
+ * Create a git worktree for a milestone without changing the coordinator's cwd.
+ * Uses milestone/<MID> branch naming (same as auto-worktree.ts).
+ */
+function createMilestoneWorktree(basePath: string, milestoneId: string): string {
+  const branch = autoWorktreeBranch(milestoneId);
+  const branchExists = nativeBranchExists(basePath, branch);
+
+  let info: { name: string; path: string; branch: string; exists: boolean };
+  if (branchExists) {
+    info = createWorktree(basePath, milestoneId, { branch, reuseExistingBranch: true });
+  } else {
+    const integrationBranch = readIntegrationBranch(basePath, milestoneId) ?? undefined;
+    info = createWorktree(basePath, milestoneId, { branch, startPoint: integrationBranch });
+  }
+
+  // Run post-create hook if configured
+  runWorktreePostCreateHook(basePath, info.path);
+
+  return info.path;
+}
+
+// ─── Worker Spawning ───────────────────────────────────────────────────
+
+/**
+ * Spawn a worker process for a milestone.
+ * The worker runs `gsd --print "/gsd auto"` in the milestone's worktree
+ * with GSD_MILESTONE_LOCK set to isolate state derivation.
+ */
+export function spawnWorker(
+  basePath: string,
+  milestoneId: string,
+): boolean {
+  if (!state) return false;
+  const worker = state.workers.get(milestoneId);
+  if (!worker) return false;
+  if (worker.process) return true; // already spawned
+
+  // Resolve the GSD CLI binary path
+  const binPath = resolveGsdBin();
+  if (!binPath) return false;
+
+  let child: ChildProcess;
+  try {
+    child = spawn(process.execPath, [binPath, "--print", "/gsd auto"], {
+      cwd: worker.worktreePath,
+      env: {
+        ...process.env,
+        GSD_MILESTONE_LOCK: milestoneId,
+        // Prevent workers from spawning their own parallel sessions
+        GSD_PARALLEL_WORKER: "1",
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+  } catch {
+    return false;
+  }
+
+  // Handle spawn errors (e.g., ENOENT when binary doesn't exist)
+  child.on("error", () => {
+    if (!state) return;
+    const w = state.workers.get(milestoneId);
+    if (w) {
+      w.process = null;
+      // Don't change state — spawn failure is non-fatal, coordinator can retry
+    }
+  });
+
+  worker.process = child;
+  worker.pid = child.pid ?? 0;
+
+  if (!child.pid) {
+    // Spawn returned but no PID — process failed to start
+    worker.process = null;
+    return false;
+  }
+
+  // Update session status with real PID
+  writeSessionStatus(basePath, {
+    milestoneId,
+    pid: worker.pid,
+    state: "running",
+    currentUnit: null,
+    completedUnits: worker.completedUnits,
+    cost: worker.cost,
+    lastHeartbeat: Date.now(),
+    startedAt: worker.startedAt,
+    worktreePath: worker.worktreePath,
+  });
+
+  // Handle worker exit
+  child.on("exit", (code) => {
+    if (!state) return;
+    const w = state.workers.get(milestoneId);
+    if (!w) return;
+
+    w.process = null;
+    if (w.state === "stopped") return; // graceful stop, already handled
+
+    if (code === 0) {
+      w.state = "stopped";
+    } else {
+      w.state = "error";
+    }
+
+    // Update session status
+    writeSessionStatus(basePath, {
+      milestoneId,
+      pid: w.pid,
+      state: w.state,
+      currentUnit: null,
+      completedUnits: w.completedUnits,
+      cost: w.cost,
+      lastHeartbeat: Date.now(),
+      startedAt: w.startedAt,
+      worktreePath: w.worktreePath,
+    });
+  });
+
+  return true;
+}
+
+/**
+ * Resolve the GSD CLI binary path.
+ * Uses GSD_BIN_PATH env var (set by loader.ts) or falls back to
+ * finding the binary relative to the current module.
+ */
+function resolveGsdBin(): string | null {
+  // GSD_BIN_PATH is set by loader.ts to the absolute path of dist/loader.js
+  if (process.env.GSD_BIN_PATH && existsSync(process.env.GSD_BIN_PATH)) {
+    return process.env.GSD_BIN_PATH;
+  }
+
+  // Fallback: try to find loader.js relative to this file
+  // This file is at dist/resources/extensions/gsd/parallel-orchestrator.js
+  // loader.js is at dist/loader.js
+  let thisDir: string;
+  try {
+    thisDir = dirname(fileURLToPath(import.meta.url));
+  } catch {
+    thisDir = process.cwd();
+  }
+  const candidates = [
+    join(thisDir, "..", "..", "..", "loader.js"),
+    join(thisDir, "..", "..", "..", "..", "dist", "loader.js"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+// ─── Stop ──────────────────────────────────────────────────────────────────
+
+/**
+ * Stop all workers or a specific milestone's worker.
+ * Sends stop signals and updates tracking state.
+ */
+export async function stopParallel(
+  basePath: string,
+  milestoneId?: string,
+): Promise<void> {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker) continue;
+
+    // Send stop signal via file-based IPC (worker checks on next dispatch)
+    sendSignal(basePath, mid, "stop");
+
+    // Also send SIGTERM to the process for immediate response
+    if (worker.process && worker.pid > 0) {
+      try {
+        worker.process.kill("SIGTERM");
+      } catch { /* process may already be dead */ }
+    }
+
+    // Update in-memory state
+    worker.state = "stopped";
+    worker.process = null;
+
+    // Clean up session status file
+    removeSessionStatus(basePath, mid);
+  }
+
+  // If stopping all workers, deactivate the orchestrator
+  if (!milestoneId) {
+    state.active = false;
+  }
+}
+
+// ─── Pause / Resume ────────────────────────────────────────────────────────
+
+/** Pause a specific worker or all workers. */
+export function pauseWorker(
+  basePath: string,
+  milestoneId?: string,
+): void {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker || worker.state !== "running") continue;
+
+    sendSignal(basePath, mid, "pause");
+    worker.state = "paused";
+  }
+}
+
+/** Resume a specific worker or all workers. */
+export function resumeWorker(
+  basePath: string,
+  milestoneId?: string,
+): void {
+  if (!state) return;
+
+  const targets = milestoneId
+    ? [milestoneId]
+    : [...state.workers.keys()];
+
+  for (const mid of targets) {
+    const worker = state.workers.get(mid);
+    if (!worker || worker.state !== "paused") continue;
+
+    sendSignal(basePath, mid, "resume");
+    worker.state = "running";
+  }
+}
+
+// ─── Status Refresh ────────────────────────────────────────────────────────
+
+/**
+ * Poll worker statuses from disk and update orchestrator state.
+ * Call this periodically from the dashboard refresh cycle.
+ */
+export function refreshWorkerStatuses(basePath: string): void {
+  if (!state) return;
+
+  // Clean up stale sessions first
+  const staleIds = cleanupStaleSessions(basePath);
+  for (const mid of staleIds) {
+    const worker = state.workers.get(mid);
+    if (worker) {
+      worker.state = "error";
+      worker.process = null;
+    }
+  }
+
+  // Read all live session statuses from disk
+  const statuses = readAllSessionStatuses(basePath);
+  const statusMap = new Map<string, SessionStatus>();
+  for (const s of statuses) {
+    statusMap.set(s.milestoneId, s);
+  }
+
+  // Update in-memory worker state from disk data
+  for (const [mid, worker] of state.workers) {
+    const diskStatus = statusMap.get(mid);
+    if (!diskStatus) continue;
+
+    worker.state = diskStatus.state;
+    worker.completedUnits = diskStatus.completedUnits;
+    worker.cost = diskStatus.cost;
+    worker.pid = diskStatus.pid;
+  }
+
+  // Recalculate aggregate cost
+  state.totalCost = 0;
+  for (const worker of state.workers.values()) {
+    state.totalCost += worker.cost;
+  }
+}
+
+// ─── Budget ────────────────────────────────────────────────────────────────
+
+/** Get aggregate cost across all workers. */
+export function getAggregateCost(): number {
+  if (!state) return 0;
+  return state.totalCost;
+}
+
+/** Check if budget ceiling has been reached. */
+export function isBudgetExceeded(): boolean {
+  if (!state) return false;
+  if (state.config.budget_ceiling == null) return false;
+  return state.totalCost >= state.config.budget_ceiling;
+}
+
+// ─── Reset ─────────────────────────────────────────────────────────────────
+
+/** Reset orchestrator state. Called on clean shutdown. */
+export function resetOrchestrator(): void {
+  state = null;
+}

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

@@ -75,6 +75,7 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "token_profile",
   "phases",
   "auto_visualize",
+  "parallel",
 ]);
 
 export interface GSDSkillRule {
@@ -171,6 +172,7 @@ export interface GSDPreferences {
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
   auto_visualize?: boolean;
+  parallel?: import("./types.js").ParallelConfig;
 }
 
 export interface LoadedGSDPreferences {
@@ -688,6 +690,7 @@ export function resolveProfileDefaults(profile: TokenProfile): Partial<GSDPrefer
           skip_research: true,
           skip_reassess: true,
           skip_slice_research: true,
+          skip_milestone_validation: true,
         },
       };
     case "balanced":
@@ -767,6 +770,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     phases: (base.phases || override.phases)
       ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
       : undefined,
+    parallel: (base.parallel || override.parallel)
+      ? { ...(base.parallel ?? {}), ...(override.parallel ?? {}) } as import("./types.js").ParallelConfig
+      : undefined,
   };
 }
 
@@ -909,8 +915,9 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (p.skip_research !== undefined) validatedPhases.skip_research = !!p.skip_research;
       if (p.skip_reassess !== undefined) validatedPhases.skip_reassess = !!p.skip_reassess;
       if (p.skip_slice_research !== undefined) validatedPhases.skip_slice_research = !!p.skip_slice_research;
+      if (p.skip_milestone_validation !== undefined) validatedPhases.skip_milestone_validation = !!p.skip_milestone_validation;
       // Warn on unknown phase keys
-      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research"]);
+      const knownPhaseKeys = new Set(["skip_research", "skip_reassess", "skip_slice_research", "skip_milestone_validation"]);
       for (const key of Object.keys(p)) {
         if (!knownPhaseKeys.has(key)) {
           warnings.push(`unknown phases key "${key}" — ignored`);
@@ -1152,6 +1159,51 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Parallel Config ────────────────────────────────────────────────────
+  if (preferences.parallel && typeof preferences.parallel === "object") {
+    const p = preferences.parallel as unknown as Record<string, unknown>;
+    const parallel: Record<string, unknown> = {};
+
+    if (p.enabled !== undefined) {
+      if (typeof p.enabled === "boolean") parallel.enabled = p.enabled;
+      else errors.push("parallel.enabled must be a boolean");
+    }
+    if (p.max_workers !== undefined) {
+      if (typeof p.max_workers === "number" && p.max_workers >= 1 && p.max_workers <= 4) {
+        parallel.max_workers = Math.floor(p.max_workers);
+      } else {
+        errors.push("parallel.max_workers must be a number between 1 and 4");
+      }
+    }
+    if (p.budget_ceiling !== undefined) {
+      if (typeof p.budget_ceiling === "number" && p.budget_ceiling > 0) {
+        parallel.budget_ceiling = p.budget_ceiling;
+      } else {
+        errors.push("parallel.budget_ceiling must be a positive number");
+      }
+    }
+    if (p.merge_strategy !== undefined) {
+      const validStrategies = new Set(["per-slice", "per-milestone"]);
+      if (typeof p.merge_strategy === "string" && validStrategies.has(p.merge_strategy)) {
+        parallel.merge_strategy = p.merge_strategy;
+      } else {
+        errors.push("parallel.merge_strategy must be one of: per-slice, per-milestone");
+      }
+    }
+    if (p.auto_merge !== undefined) {
+      const validModes = new Set(["auto", "confirm", "manual"]);
+      if (typeof p.auto_merge === "string" && validModes.has(p.auto_merge)) {
+        parallel.auto_merge = p.auto_merge;
+      } else {
+        errors.push("parallel.auto_merge must be one of: auto, confirm, manual");
+      }
+    }
+
+    if (Object.keys(parallel).length > 0) {
+      validated.parallel = parallel as unknown as import("./types.js").ParallelConfig;
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};
@@ -1369,3 +1421,15 @@ export function updatePreferencesModels(models: GSDModelConfigV2): void {
 
   writeFileSync(prefsPath, content, "utf-8");
 }
+
+// ─── Parallel Config Resolver ──────────────────────────────────────────────
+
+export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {
+  return {
+    enabled: prefs?.parallel?.enabled ?? false,
+    max_workers: Math.max(1, Math.min(4, prefs?.parallel?.max_workers ?? 2)),
+    budget_ceiling: prefs?.parallel?.budget_ceiling,
+    merge_strategy: prefs?.parallel?.merge_strategy ?? "per-milestone",
+    auto_merge: prefs?.parallel?.auto_merge ?? "confirm",
+  };
+}

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -0,0 +1,86 @@
+# Headless Milestone Creation
+
+You are creating a GSD milestone from a provided specification document. This is a **headless** (non-interactive) flow — do NOT ask the user any questions. Work entirely from the provided specification.
+
+## Provided Specification
+
+{{seedContext}}
+
+## Your Task
+
+### Step 1: Reflect
+
+Summarize your understanding of the specification concretely:
+- What is being built
+- Major capabilities/features
+- Scope estimate (how many milestones × slices)
+- Any ambiguities or gaps you notice
+
+### Step 2: Investigate
+
+Scout the codebase to understand what already exists:
+- `ls` the project root and key directories
+- Search for relevant existing code, patterns, dependencies
+- Check library docs if needed (`resolve_library` / `get_library_docs`)
+
+### Step 3: Make Decisions
+
+For any ambiguities or gaps in the specification:
+- Make your best-guess decision based on the spec's intent, codebase patterns, and domain conventions
+- Document each assumption clearly in the Context file
+
+### Step 4: Assess Scope
+
+Based on reflection + investigation:
+- Is this a single milestone or multiple milestones?
+- If multi-milestone: plan the full sequence with dependencies
+
+### Step 5: Write Artifacts
+
+**Milestone ID**: {{milestoneId}}
+
+Use these templates exactly:
+
+{{inlinedTemplates}}
+
+**For single milestone**, write in this order:
+1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
+2. Write `.gsd/PROJECT.md` (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` (using Requirements template)
+4. Write `{{contextPath}}` (using Context template) — preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. Document assumptions under an "Assumptions" section.
+5. Write `{{roadmapPath}}` (using Roadmap template) — decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice.
+6. Seed `.gsd/DECISIONS.md` (using Decisions template)
+7. Update `.gsd/STATE.md`
+8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
+9. Say exactly: "Milestone {{milestoneId}} ready."
+
+**For multi-milestone**, write in this order:
+1. Create all milestone directories: `mkdir -p .gsd/milestones/{M###}/slices` for each
+2. Write `.gsd/PROJECT.md` — full vision across ALL milestones (using Project template)
+3. Write `.gsd/REQUIREMENTS.md` — full capability contract (using Requirements template)
+4. Seed `.gsd/DECISIONS.md` (using Decisions template)
+5. Write PRIMARY `{{contextPath}}` — full context with all assumptions documented
+6. Write PRIMARY `{{roadmapPath}}` — detailed slices for the first milestone only
+7. For each remaining milestone, write full CONTEXT.md with `depends_on` frontmatter:
+   ```yaml
+   ---
+   depends_on: [M001, M002]
+   ---
+
+   # M003: Title
+   ```
+   Each context file should be rich enough that a future agent — with no memory of this conversation — can understand the intent, constraints, dependencies, what the milestone unlocks, and what "done" looks like.
+8. Update `.gsd/STATE.md`
+9. Commit: `docs: project plan — N milestones`
+10. Say exactly: "Milestone {{milestoneId}} ready."
+
+## Critical Rules
+
+- **DO NOT ask the user any questions** — this is headless mode
+- **Preserve the specification's terminology** — don't paraphrase domain-specific language
+- **Document assumptions** — when you make a judgment call, note it in CONTEXT.md under "Assumptions"
+- **Investigate before writing** — always scout the codebase first
+- **Use depends_on frontmatter** for multi-milestone sequences (the state machine reads this field to determine execution order)
+- **Anti-reduction rule** — if the spec describes a big vision, plan the big vision. Do not ask "what's the minimum viable version?" or reduce scope. Phase complex/risky work into later milestones — do not cut it.
+- **Naming convention** — directories use bare IDs (`M001/`, `S01/`), files use ID-SUFFIX format (`M001-CONTEXT.md`, `M001-ROADMAP.md`)
+- **End with "Milestone {{milestoneId}} ready."** — this triggers auto-start detection