gsd-pi 2.37.1 → 2.38.0-dev.e40f839

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

@@ -1,14 +1,15 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { loadFile, parsePlan, parseRoadmap, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile } from "./paths.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
 
-import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
+import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
+import type { RoadmapSliceEntry } from "./types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
 import { runProviderChecks } from "./doctor-providers.js";
@@ -17,7 +18,7 @@ import { runProviderChecks } from "./doctor-providers.js";
 // All public types and functions from extracted modules are re-exported here
 // so that existing imports from "./doctor.js" continue to work unchanged.
 export type { DoctorSeverity, DoctorIssueCode, DoctorIssue, DoctorReport, DoctorSummary } from "./doctor-types.js";
-export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt } from "./doctor-format.js";
+export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt, formatDoctorReportJson } from "./doctor-format.js";
 export { runEnvironmentChecks, runFullEnvironmentChecks, formatEnvironmentReport, type EnvironmentCheckResult } from "./doctor-environment.js";
 export { computeProgressScore, computeProgressScoreWithContext, formatProgressLine, formatProgressReport, type ProgressScore, type ProgressLevel } from "./progress-score.js";
 
@@ -350,10 +351,60 @@ export async function selectDoctorScope(basePath: string, requestedScope?: strin
   return state.registry[0]?.id;
 }
 
-export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch" }): Promise<import("./doctor-types.js").DoctorReport> {
+// ── Helper: circular dependency detection ──────────────────────────────────
+function detectCircularDependencies(slices: RoadmapSliceEntry[]): string[][] {
+  const known = new Set(slices.map(s => s.id));
+  const adj = new Map<string, string[]>();
+  for (const s of slices) adj.set(s.id, s.depends.filter(d => known.has(d)));
+  const state = new Map<string, "unvisited" | "visiting" | "done">();
+  for (const s of slices) state.set(s.id, "unvisited");
+  const cycles: string[][] = [];
+  function dfs(id: string, path: string[]): void {
+    const st = state.get(id);
+    if (st === "done") return;
+    if (st === "visiting") { cycles.push([...path.slice(path.indexOf(id)), id]); return; }
+    state.set(id, "visiting");
+    for (const dep of adj.get(id) ?? []) dfs(dep, [...path, id]);
+    state.set(id, "done");
+  }
+  for (const s of slices) if (state.get(s.id) === "unvisited") dfs(s.id, []);
+  return cycles;
+}
+
+// ── Helper: doctor run history ──────────────────────────────────────────────
+interface DoctorHistoryEntry { ts: string; ok: boolean; errors: number; warnings: number; fixes: number; codes: string[] }
+
+async function appendDoctorHistory(basePath: string, report: DoctorReport): Promise<void> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      ok: report.ok,
+      errors: report.issues.filter(i => i.severity === "error").length,
+      warnings: report.issues.filter(i => i.severity === "warning").length,
+      fixes: report.fixesApplied.length,
+      codes: [...new Set(report.issues.map(i => i.code))],
+    } satisfies DoctorHistoryEntry);
+    const existing = existsSync(historyPath) ? readFileSync(historyPath, "utf-8") : "";
+    await saveFile(historyPath, existing + entry + "\n");
+  } catch { /* non-fatal */ }
+}
+
+/** Read the last N doctor history entries. Returns most-recent-first. */
+export async function readDoctorHistory(basePath: string, lastN = 50): Promise<DoctorHistoryEntry[]> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    if (!existsSync(historyPath)) return [];
+    const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+    return lines.slice(-lastN).reverse().map(l => JSON.parse(l) as DoctorHistoryEntry);
+  } catch { return []; }
+}
+
+export async function runGSDDoctor(basePath: string, options?: { fix?: boolean; dryRun?: boolean; scope?: string; fixLevel?: "task" | "all"; isolationMode?: "none" | "worktree" | "branch"; includeBuild?: boolean; includeTests?: boolean }): Promise<DoctorReport> {
   const issues: DoctorIssue[] = [];
   const fixesApplied: string[] = [];
   const fix = options?.fix === true;
+  const dryRun = options?.dryRun === true;
   const fixLevel = options?.fixLevel ?? "all";
 
   // Issue codes that represent completion state transitions — creating summary
@@ -364,11 +415,18 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
 
   /** Whether a given issue code should be auto-fixed at the current fixLevel. */
   const shouldFix = (code: DoctorIssueCode): boolean => {
-    if (!fix) return false;
+    if (!fix || dryRun) return false;
     if (fixLevel === "task" && COMPLETION_TRANSITION_CODES.has(code)) return false;
     return true;
   };
 
+  /** Log a dry-run "would fix" entry when fix=true but dryRun=true. */
+  const dryRunCanFix = (code: DoctorIssueCode, message: string): void => {
+    if (dryRun && fix && !(fixLevel === "task" && COMPLETION_TRANSITION_CODES.has(code))) {
+      fixesApplied.push(`[dry-run] would fix: ${message}`);
+    }
+  };
+
   const prefs = loadEffectiveGSDPreferences();
   if (prefs) {
     const prefIssues = validatePreferenceShape(prefs.preferences);
@@ -385,21 +443,33 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  // Git health checks (orphaned worktrees, stale branches, corrupt merge state, tracked runtime files)
+  // Git health checks — timed
+  const t0git = Date.now();
   const isolationMode: "none" | "worktree" | "branch" = options?.isolationMode ??
     (prefs?.preferences?.git?.isolation === "none" ? "none" :
     prefs?.preferences?.git?.isolation === "branch" ? "branch" : "worktree");
   await checkGitHealth(basePath, issues, fixesApplied, shouldFix, isolationMode);
+  const gitMs = Date.now() - t0git;
 
-  // Runtime health checks (crash locks, completed-units, hook state, activity logs, STATE.md, gitignore)
+  // Runtime health checks — timed
+  const t0runtime = Date.now();
   await checkRuntimeHealth(basePath, issues, fixesApplied, shouldFix);
+  const runtimeMs = Date.now() - t0runtime;
 
-  // Environment health checks (#1221: missing tools, port conflicts, stale deps, disk space)
-  await checkEnvironmentHealth(basePath, issues, { includeRemote: !options?.scope });
+  // Environment health checks — timed
+  const t0env = Date.now();
+  await checkEnvironmentHealth(basePath, issues, {
+    includeRemote: !options?.scope,
+    includeBuild: options?.includeBuild,
+    includeTests: options?.includeTests,
+  });
+  const envMs = Date.now() - t0env;
 
   const milestonesPath = milestonesDir(basePath);
   if (!existsSync(milestonesPath)) {
-    return { ok: issues.every(issue => issue.severity !== "error"), basePath, issues, fixesApplied };
+    const report: DoctorReport = { ok: issues.every(i => i.severity !== "error"), basePath, issues, fixesApplied, timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: 0 } };
+    await appendDoctorHistory(basePath, report);
+    return report;
   }
 
   const requirementsPath = resolveGsdRootFile(basePath, "REQUIREMENTS");
@@ -465,6 +535,43 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     if (!roadmapContent) continue;
     const roadmap = parseRoadmap(roadmapContent);
 
+    // ── Circular dependency detection ──────────────────────────────────────
+    for (const cycle of detectCircularDependencies(roadmap.slices)) {
+      issues.push({
+        severity: "error",
+        code: "circular_slice_dependency",
+        scope: "milestone",
+        unitId: milestoneId,
+        message: `Circular dependency detected: ${cycle.join(" → ")}`,
+        file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
+        fixable: false,
+      });
+    }
+
+    // ── Orphaned slice directories ─────────────────────────────────────────
+    try {
+      const slicesDir = join(milestonePath, "slices");
+      if (existsSync(slicesDir)) {
+        const knownSliceIds = new Set(roadmap.slices.map(s => s.id));
+        for (const entry of readdirSync(slicesDir)) {
+          try {
+            if (!lstatSync(join(slicesDir, entry)).isDirectory()) continue;
+          } catch { continue; }
+          if (!knownSliceIds.has(entry)) {
+            issues.push({
+              severity: "warning",
+              code: "orphaned_slice_directory",
+              scope: "milestone",
+              unitId: milestoneId,
+              message: `Directory "${entry}" exists in ${milestoneId}/slices/ but is not referenced in the roadmap`,
+              file: `${relMilestonePath(basePath, milestoneId)}/slices/${entry}`,
+              fixable: false,
+            });
+          }
+        }
+      }
+    } catch { /* non-fatal */ }
+
     for (const slice of roadmap.slices) {
       const unitId = `${milestoneId}/${slice.id}`;
       if (options?.scope && !matchesScope(unitId, options.scope) && options.scope !== milestoneId) continue;
@@ -539,6 +646,33 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         continue;
       }
 
+      // ── Duplicate task IDs ───────────────────────────────────────────────
+      const taskIdCounts = new Map<string, number>();
+      for (const task of plan.tasks) taskIdCounts.set(task.id, (taskIdCounts.get(task.id) ?? 0) + 1);
+      for (const [taskId, count] of taskIdCounts) {
+        if (count > 1) {
+          issues.push({ severity: "error", code: "duplicate_task_id", scope: "slice", unitId,
+            message: `Task ID "${taskId}" appears ${count} times in ${slice.id}-PLAN.md — duplicate IDs cause dispatch failures`,
+            file: relSliceFile(basePath, milestoneId, slice.id, "PLAN"), fixable: false });
+        }
+      }
+
+      // ── Task files on disk not in plan ────────────────────────────────────
+      try {
+        if (tasksDir) {
+          const planTaskIds = new Set(plan.tasks.map(t => t.id));
+          for (const f of readdirSync(tasksDir)) {
+            if (!f.endsWith("-SUMMARY.md")) continue;
+            const diskTaskId = f.replace(/-SUMMARY\.md$/, "");
+            if (!planTaskIds.has(diskTaskId)) {
+              issues.push({ severity: "info", code: "task_file_not_in_plan", scope: "slice", unitId,
+                message: `Task summary "${f}" exists on disk but "${diskTaskId}" is not in ${slice.id}-PLAN.md`,
+                file: relTaskFile(basePath, milestoneId, slice.id, diskTaskId, "SUMMARY"), fixable: false });
+            }
+          }
+        }
+      } catch { /* non-fatal */ }
+
       let allTasksDone = plan.tasks.length > 0;
       for (const task of plan.tasks) {
         const taskUnitId = `${unitId}/${task.id}`;
@@ -555,6 +689,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
             file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"),
             fixable: true,
           });
+          dryRunCanFix("task_done_missing_summary", `create stub summary for ${taskUnitId}`);
           if (shouldFix("task_done_missing_summary")) {
             const stubPath = join(
               basePath, ".gsd", "milestones", milestoneId, "slices", slice.id, "tasks",
@@ -618,6 +753,22 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           }
         }
 
+        // ── Future timestamp check ─────────────────────────────────────
+        if (task.done && hasSummary && summaryPath) {
+          try {
+            const rawSummary = await loadFile(summaryPath);
+            const m = rawSummary?.match(/^completed_at:\s*(.+)$/m);
+            if (m) {
+              const ts = new Date(m[1].trim());
+              if (!isNaN(ts.getTime()) && ts.getTime() > Date.now() + 24 * 60 * 60 * 1000) {
+                issues.push({ severity: "warning", code: "future_timestamp", scope: "task", unitId: taskUnitId,
+                  message: `Task ${task.id} has completed_at "${m[1].trim()}" which is more than 24h in the future`,
+                  file: relTaskFile(basePath, milestoneId, slice.id, task.id, "SUMMARY"), fixable: false });
+              }
+            }
+          } catch { /* non-fatal */ }
+        }
+
         allTasksDone = allTasksDone && task.done;
       }
 
@@ -646,6 +797,13 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
         }
       }
 
+      // ── Stale REPLAN: exists but all tasks done ────────────────────────
+      if (replanPath && allTasksDone) {
+        issues.push({ severity: "info", code: "stale_replan_file", scope: "slice", unitId,
+          message: `${slice.id} has a REPLAN.md but all tasks are done — REPLAN.md may be stale`,
+          file: relSliceFile(basePath, milestoneId, slice.id, "REPLAN"), fixable: false });
+      }
+
       const sliceSummaryPath = resolveSliceFile(basePath, milestoneId, slice.id, "SUMMARY");
       const sliceUatPath = join(slicePath, `${slice.id}-UAT.md`);
       const hasSliceSummary = !!(sliceSummaryPath && await loadFile(sliceSummaryPath));
@@ -661,6 +819,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relSliceFile(basePath, milestoneId, slice.id, "SUMMARY"),
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_missing_slice_summary", `create placeholder summary for ${unitId}`);
         if (shouldFix("all_tasks_done_missing_slice_summary")) await ensureSliceSummaryStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
@@ -674,6 +833,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: `${relSlicePath(basePath, milestoneId, slice.id)}/${slice.id}-UAT.md`,
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_missing_slice_uat", `create placeholder UAT for ${unitId}`);
         if (shouldFix("all_tasks_done_missing_slice_uat")) await ensureSliceUatStub(basePath, milestoneId, slice.id, fixesApplied);
       }
 
@@ -687,6 +847,7 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
           file: relMilestoneFile(basePath, milestoneId, "ROADMAP"),
           fixable: true,
         });
+        dryRunCanFix("all_tasks_done_roadmap_not_checked", `mark ${slice.id} done in roadmap`);
         if (shouldFix("all_tasks_done_roadmap_not_checked") && (hasSliceSummary || issues.some(issue => issue.code === "all_tasks_done_missing_slice_summary" && issue.unitId === unitId))) {
           await markSliceDoneInRoadmap(basePath, milestoneId, slice.id, fixesApplied);
         }
@@ -744,14 +905,17 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     }
   }
 
-  if (fix && fixesApplied.length > 0) {
+  if (fix && !dryRun && fixesApplied.length > 0) {
     await updateStateFile(basePath, fixesApplied);
   }
 
-  return {
+  const report: DoctorReport = {
     ok: issues.every(issue => issue.severity !== "error"),
     basePath,
     issues,
     fixesApplied,
+    timing: { git: gitMs, runtime: runtimeMs, environment: envMs, gsdState: Math.max(0, Date.now() - t0env - envMs) },
   };
+  await appendDoctorHistory(basePath, report);
+  return report;
 }

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

@@ -11,7 +11,7 @@ import {
 } from "./metrics.js";
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
-import { formatDuration, fileLink } from "../shared/mod.js";
+import { formatDuration, fileLink } from "../shared/format-utils.js";
 import { getErrorMessage } from "./error-utils.js";
 
 /**

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

@@ -7,7 +7,7 @@ import { promises as fs } from 'node:fs';
 import { resolve } from 'node:path';
 import { atomicWriteAsync } from './atomic-write.js';
 import { resolveMilestoneFile, relMilestoneFile, resolveGsdRootFile } from './paths.js';
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 
 import type {
   Roadmap, BoundaryMapEntry,
@@ -15,11 +15,12 @@ import type {
   Summary, SummaryFrontmatter, SummaryRequires, FileModified,
   Continue, ContinueFrontmatter, ContinueStatus,
   RequirementCounts,
+  TaskIO,
   SecretsManifest, SecretsManifestEntry, SecretsManifestEntryStatus,
   ManifestStatus,
 } from './types.js';
 
-import { checkExistingEnvKeys } from '../get-secrets-from-user.js';
+import { checkExistingEnvKeys } from '../env-utils.js';
 import { parseRoadmapSlices } from './roadmap-slices.js';
 import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativeParseSummaryFile, NATIVE_UNAVAILABLE } from './native-parser-bridge.js';
 import { debugTime, debugCount } from './debug-logger.js';
@@ -724,6 +725,50 @@ export function countMustHavesMentionedInSummary(
   return count;
 }
 
+// ─── Task Plan IO Extractor ────────────────────────────────────────────────
+
+/**
+ * Extract input and output file paths from a task plan's `## Inputs` and
+ * `## Expected Output` sections. Looks for backtick-wrapped file paths on
+ * each line (e.g. `` `src/foo.ts` ``).
+ *
+ * Returns empty arrays for missing/empty sections — callers should treat
+ * tasks with no IO as ambiguous (sequential fallback trigger).
+ */
+export function parseTaskPlanIO(content: string): { inputFiles: string[]; outputFiles: string[] } {
+  const backtickPathRegex = /`([^`]+)`/g;
+
+  function extractPaths(sectionText: string | null): string[] {
+    if (!sectionText) return [];
+    const paths: string[] = [];
+    for (const line of sectionText.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      let match: RegExpExecArray | null;
+      backtickPathRegex.lastIndex = 0;
+      while ((match = backtickPathRegex.exec(trimmed)) !== null) {
+        const candidate = match[1];
+        // Filter out things that look like code tokens rather than file paths
+        // (e.g. `true`, `false`, `npm run test`). A file path has at least one
+        // dot or slash.
+        if (candidate.includes("/") || candidate.includes(".")) {
+          paths.push(candidate);
+        }
+      }
+    }
+    return paths;
+  }
+
+  const [, body] = splitFrontmatter(content);
+  const inputSection = extractSection(body, "Inputs");
+  const outputSection = extractSection(body, "Expected Output");
+
+  return {
+    inputFiles: extractPaths(inputSection),
+    outputFiles: extractPaths(outputSection),
+  };
+}
+
 // ─── UAT Type Extractor ────────────────────────────────────────────────────
 
 /**

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

@@ -27,7 +27,7 @@ import { deriveState } from "./state.js";
 import { isAutoActive } from "./auto.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { formatDuration } from "../shared/mod.js";
+import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────

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

@@ -60,6 +60,8 @@ import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { shortcutDesc } from "../shared/mod.js";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { Text } from "@gsd/pi-tui";
 import { pauseAutoForProviderError, classifyProviderError } from "./provider-error-pause.js";
 import { toPosixPath } from "../shared/mod.js";
@@ -73,7 +75,7 @@ import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../cmux/index.js"
 
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
-    join(homedir(), ".gsd", "agent-instructions.md"),
+    join(gsdHome, "agent-instructions.md"),
     join(process.cwd(), ".gsd", "agent-instructions.md"),
   ];
   for (const p of paths) {

package/src/resources/extensions/gsd/migrate/parsers.ts

@@ -3,7 +3,7 @@
 // Zero Pi dependencies — uses only exported helpers from files.ts.
 
 import { splitFrontmatter, parseFrontmatterMap, extractBoldField } from '../files.js';
-import { normalizeStringArray } from '../../shared/mod.js';
+import { normalizeStringArray } from '../../shared/format-utils.js';
 
 import type {
   PlanningRoadmap,

package/src/resources/extensions/gsd/observability-validator.ts

@@ -235,6 +235,33 @@ export function validateTaskPlanContent(file: string, content: string): Validati
     }
   }
 
+  // Rule: Inputs and Expected Output should contain backtick-wrapped file paths
+  const inputsSection = getSection(content, "Inputs", 2);
+  const outputSection = getSection(content, "Expected Output", 2);
+  const backtickPathPattern = /`[^`]*[./][^`]*`/;
+
+  if (outputSection === null || !backtickPathPattern.test(outputSection)) {
+    issues.push({
+      severity: "warning",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_output_file_paths",
+      message: "Task plan `## Expected Output` is missing or has no backtick-wrapped file paths.",
+      suggestion: "List concrete output file paths in backticks (e.g. `src/types.ts`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
+  if (inputsSection !== null && inputsSection.trim().length > 0 && !backtickPathPattern.test(inputsSection)) {
+    issues.push({
+      severity: "info",
+      scope: "task-plan",
+      file,
+      ruleId: "missing_input_file_paths",
+      message: "Task plan `## Inputs` has content but no backtick-wrapped file paths.",
+      suggestion: "List input file paths in backticks (e.g. `src/config.json`). These are machine-parsed to derive task dependencies.",
+    });
+  }
+
   // ── Observability rules (gated by runtime relevance) ──
 
   const relevant = textSuggestsObservabilityRelevant(content);

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

@@ -18,6 +18,7 @@ import type {
   ParallelConfig,
   CompressionStrategy,
   ContextSelectionMode,
+  ReactiveExecutionConfig,
 } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 
@@ -86,12 +87,13 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "compression_strategy",
   "context_selection",
   "widget_mode",
+  "reactive_execution",
 ]);
 
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [
   "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-  "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+  "execute-task", "reactive-execute", "complete-slice", "replan-slice", "reassess-roadmap",
   "run-uat", "complete-milestone",
 ] as const;
 export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
@@ -215,6 +217,8 @@ export interface GSDPreferences {
   context_selection?: ContextSelectionMode;
   /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
   widget_mode?: "full" | "small" | "min" | "off";
+  /** Reactive (graph-derived parallel) task execution within slices. Disabled by default. */
+  reactive_execution?: ReactiveExecutionConfig;
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -10,7 +10,7 @@ import type { GitPreferences } from "./git-service.js";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile, PhaseSkipPreferences } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
-import { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
@@ -496,6 +496,47 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Reactive Execution ─────────────────────────────────────────────────
+  if (preferences.reactive_execution !== undefined) {
+    if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {
+      const re = preferences.reactive_execution as unknown as Record<string, unknown>;
+      const validRe: Record<string, unknown> = {};
+
+      if (re.enabled !== undefined) {
+        if (typeof re.enabled === "boolean") validRe.enabled = re.enabled;
+        else errors.push("reactive_execution.enabled must be a boolean");
+      }
+      if (re.max_parallel !== undefined) {
+        const mp = typeof re.max_parallel === "number" ? re.max_parallel : Number(re.max_parallel);
+        if (Number.isFinite(mp) && mp >= 1 && mp <= 8) {
+          validRe.max_parallel = Math.floor(mp);
+        } else {
+          errors.push("reactive_execution.max_parallel must be a number between 1 and 8");
+        }
+      }
+      if (re.isolation_mode !== undefined) {
+        if (re.isolation_mode === "same-tree") {
+          validRe.isolation_mode = "same-tree";
+        } else {
+          errors.push('reactive_execution.isolation_mode must be "same-tree"');
+        }
+      }
+
+      const knownReKeys = new Set(["enabled", "max_parallel", "isolation_mode"]);
+      for (const key of Object.keys(re)) {
+        if (!knownReKeys.has(key)) {
+          warnings.push(`unknown reactive_execution key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validRe).length > 0) {
+        validated.reactive_execution = validRe as unknown as import("./types.js").ReactiveExecutionConfig;
+      }
+    } else {
+      errors.push("reactive_execution must be an object");
+    }
+  }
+
   // ─── Verification Preferences ───────────────────────────────────────────
   if (preferences.verification_commands !== undefined) {
     if (Array.isArray(preferences.verification_commands)) {

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

@@ -13,11 +13,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import type { PostUnitHookConfig, PreDispatchHookConfig, TokenProfile } from "./types.js";
 import type { DynamicRoutingConfig } from "./model-router.js";
-import { normalizeStringArray } from "../shared/mod.js";
+import { normalizeStringArray } from "../shared/format-utils.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
@@ -82,14 +84,14 @@ export {
 
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 
-const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
+const GLOBAL_PREFERENCES_PATH = join(gsdHome, "preferences.md");
 const LEGACY_GLOBAL_PREFERENCES_PATH = join(homedir(), ".pi", "agent", "gsd-preferences.md");
 function projectPreferencesPath(): string {
   return join(gsdRoot(process.cwd()), "preferences.md");
 }
 // Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
 // Check uppercase as a fallback so those files aren't silently ignored.
-const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(homedir(), ".gsd", "PREFERENCES.md");
+const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(gsdHome, "PREFERENCES.md");
 function projectPreferencesPathUppercase(): string {
   return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -61,13 +61,14 @@ Then:
    - a concrete, action-oriented title
    - the inline task entry fields defined in the plan.md template (Why / Files / Do / Verify / Done when)
    - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
+   - **Inputs and Expected Output must list concrete backtick-wrapped file paths** (e.g. `` `src/types.ts` ``). These are machine-parsed to derive task dependencies — vague prose without paths breaks parallel execution. Every task must have at least one output file path.
    - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
 6. Write `{{outputPath}}`
 7. Write individual task plans in `{{slicePath}}/tasks/`: `T01-PLAN.md`, `T02-PLAN.md`, etc.
 8. **Self-audit the plan.** Walk through each check — if any fail, fix the plan files before moving on:
     - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true.
     - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task.
-    - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague.
+    - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague. Inputs and Expected Output list backtick-wrapped file paths, not prose descriptions.
     - **Dependency correctness:** Task ordering is consistent. No task references work from a later task.
     - **Key links planned:** For every pair of artifacts that must connect, there is an explicit step that wires them.
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.

package/src/resources/extensions/gsd/prompts/reactive-execute.md

@@ -0,0 +1,41 @@
+# Reactive Task Execution — Parallel Dispatch
+
+**Working directory:** `{{workingDirectory}}`
+**Milestone:** {{milestoneId}} — {{milestoneTitle}}
+**Slice:** {{sliceId}} — {{sliceTitle}}
+
+## Mission
+
+You are executing **multiple tasks in parallel** for this slice. The task graph below shows which tasks are ready for simultaneous execution based on their input/output dependencies.
+
+**Critical rule:** Use the `subagent` tool in **parallel mode** to dispatch all ready tasks simultaneously. Each subagent gets a self-contained execute-task prompt. After all subagents return, verify each task's outputs and write summaries.
+
+## Task Dependency Graph
+
+{{graphContext}}
+
+## Ready Tasks for Parallel Dispatch
+
+{{readyTaskCount}} tasks are ready for parallel execution:
+
+{{readyTaskList}}
+
+## Execution Protocol
+
+1. **Dispatch all ready tasks** using `subagent` in parallel mode. Each subagent prompt is provided below.
+2. **Wait for all subagents** to complete.
+3. **Verify each task's outputs** — check that expected files were created/modified and that verification commands pass.
+4. **Write task summaries** for each completed task using the task-summary template.
+5. **Mark completed tasks** as done in the slice plan (checkbox `[x]`).
+6. **Commit** all changes with a clear message covering the parallel batch.
+
+If any subagent fails:
+- Write a summary for the failed task with `blocker_discovered: true`
+- Continue marking the successful tasks as done
+- The orchestrator will handle re-dispatch on the next iteration
+
+## Subagent Prompts
+
+{{subagentPrompts}}
+
+{{inlinedTemplates}}