gsd-pi 2.37.1 → 2.38.0-dev.29edcdc

package/src/resources/extensions/gsd/reactive-graph.ts

@@ -0,0 +1,289 @@
+/**
+ * Reactive Task Graph — derives dependency edges from task plan IO signatures.
+ *
+ * Pure functions that build a DAG from task IO intersections and resolve
+ * which tasks are currently ready for parallel dispatch. Used by the
+ * reactive-execute dispatch path (ADR-004).
+ *
+ * Graph derivation and resolution functions are pure (no filesystem access).
+ * The `loadSliceTaskIO` loader at the bottom is the only async/IO function.
+ */
+
+import type { TaskIO, DerivedTaskNode, ReactiveExecutionState } from "./types.js";
+import { loadFile, parsePlan, parseTaskPlanIO } from "./files.js";
+import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
+import { join } from "node:path";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { existsSync, unlinkSync } from "node:fs";
+
+// ─── Graph Construction ───────────────────────────────────────────────────
+
+/**
+ * Build a dependency graph from task IO signatures.
+ *
+ * A task T_b depends on T_a when any of T_b's inputFiles appear in T_a's
+ * outputFiles. Self-references are excluded.
+ *
+ * Tasks are returned in the same order as the input array.
+ */
+export function deriveTaskGraph(tasks: TaskIO[]): DerivedTaskNode[] {
+  // Build output → producer lookup
+  const outputToProducer = new Map<string, string[]>();
+  for (const task of tasks) {
+    for (const outFile of task.outputFiles) {
+      const existing = outputToProducer.get(outFile);
+      if (existing) {
+        existing.push(task.id);
+      } else {
+        outputToProducer.set(outFile, [task.id]);
+      }
+    }
+  }
+
+  return tasks.map((task) => {
+    const deps = new Set<string>();
+    for (const inFile of task.inputFiles) {
+      const producers = outputToProducer.get(inFile);
+      if (producers) {
+        for (const pid of producers) {
+          if (pid !== task.id) deps.add(pid);
+        }
+      }
+    }
+    return {
+      ...task,
+      dependsOn: [...deps].sort(),
+    };
+  });
+}
+
+// ─── Ready Set Resolution ─────────────────────────────────────────────────
+
+/**
+ * Return task IDs whose dependencies are all in `completed`.
+ * Excludes tasks that are already done or in-flight.
+ */
+export function getReadyTasks(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): string[] {
+  return graph
+    .filter((node) => {
+      if (node.done || completed.has(node.id) || inFlight.has(node.id)) return false;
+      return node.dependsOn.every((dep) => completed.has(dep));
+    })
+    .map((node) => node.id);
+}
+
+// ─── Conflict-Free Subset Selection ──────────────────────────────────────
+
+/**
+ * Greedy selection of non-conflicting tasks up to `maxParallel`.
+ *
+ * Two tasks conflict if they share any outputFile. We also exclude tasks
+ * whose outputs overlap with `inFlightOutputs` (files being written by
+ * tasks currently in progress).
+ */
+export function chooseNonConflictingSubset(
+  readyIds: string[],
+  graph: DerivedTaskNode[],
+  maxParallel: number,
+  inFlightOutputs: Set<string>,
+): string[] {
+  const nodeMap = new Map(graph.map((n) => [n.id, n]));
+  const claimed = new Set(inFlightOutputs);
+  const selected: string[] = [];
+
+  for (const id of readyIds) {
+    if (selected.length >= maxParallel) break;
+    const node = nodeMap.get(id);
+    if (!node) continue;
+
+    // Check for output overlap with already-selected or in-flight
+    const conflicts = node.outputFiles.some((f) => claimed.has(f));
+    if (conflicts) continue;
+
+    // Claim this task's outputs
+    for (const f of node.outputFiles) claimed.add(f);
+    selected.push(id);
+  }
+
+  return selected;
+}
+
+// ─── Graph Quality Checks ─────────────────────────────────────────────────
+
+/**
+ * Returns true if any incomplete task has 0 inputFiles AND 0 outputFiles.
+ *
+ * An ambiguous graph means IO annotations are too sparse to derive reliable
+ * edges — the dispatcher should fall back to sequential execution.
+ */
+export function isGraphAmbiguous(graph: DerivedTaskNode[]): boolean {
+  return graph.some(
+    (node) =>
+      !node.done &&
+      node.inputFiles.length === 0 &&
+      node.outputFiles.length === 0,
+  );
+}
+
+/**
+ * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete
+ * tasks remain. This indicates a circular dependency or impossible state.
+ */
+export function detectDeadlock(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): boolean {
+  const incomplete = graph.filter(
+    (n) => !n.done && !completed.has(n.id) && !inFlight.has(n.id),
+  );
+  if (incomplete.length === 0) return false; // all done
+  if (inFlight.size > 0) return false; // something is running, wait for it
+
+  // Nothing in flight, but incomplete tasks remain — check if any are ready
+  const ready = getReadyTasks(graph, completed, inFlight);
+  return ready.length === 0;
+}
+
+// ─── Graph Metrics ────────────────────────────────────────────────────────
+
+/** Compute summary metrics for logging. */
+export function graphMetrics(graph: DerivedTaskNode[]): {
+  taskCount: number;
+  edgeCount: number;
+  readySetSize: number;
+  ambiguous: boolean;
+} {
+  const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+  const ready = getReadyTasks(graph, completed, new Set());
+  const edgeCount = graph.reduce((sum, n) => sum + n.dependsOn.length, 0);
+
+  return {
+    taskCount: graph.length,
+    edgeCount,
+    readySetSize: ready.length,
+    ambiguous: isGraphAmbiguous(graph),
+  };
+}
+
+// ─── IO Loader (async, filesystem) ────────────────────────────────────────
+
+/**
+ * Load TaskIO for all tasks in a slice by reading the slice plan (for done
+ * status and task IDs) and individual task plan files (for IO sections).
+ *
+ * Returns [] when the slice plan or tasks directory doesn't exist.
+ */
+export async function loadSliceTaskIO(
+  basePath: string,
+  mid: string,
+  sid: string,
+): Promise<TaskIO[]> {
+  const { resolveSliceFile } = await import("./paths.js");
+  const slicePlanPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const planContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
+  if (!planContent) return [];
+
+  const plan = parsePlan(planContent);
+  const tDir = resolveTasksDir(basePath, mid, sid);
+  if (!tDir) return [];
+
+  const results: TaskIO[] = [];
+
+  for (const taskEntry of plan.tasks) {
+    const planFiles = resolveTaskFiles(tDir, "PLAN");
+    const taskFileName = planFiles.find((f) =>
+      f.toUpperCase().startsWith(taskEntry.id.toUpperCase() + "-"),
+    );
+    if (!taskFileName) {
+      // Task plan file missing — include with empty IO (will trigger ambiguous)
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const taskContent = await loadFile(join(tDir, taskFileName));
+    if (!taskContent) {
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const io = parseTaskPlanIO(taskContent);
+    results.push({
+      id: taskEntry.id,
+      title: taskEntry.title,
+      inputFiles: io.inputFiles,
+      outputFiles: io.outputFiles,
+      done: taskEntry.done,
+    });
+  }
+
+  return results;
+}
+
+// ─── State Persistence ────────────────────────────────────────────────────
+
+function reactiveStatePath(basePath: string, mid: string, sid: string): string {
+  return join(basePath, ".gsd", "runtime", `${mid}-${sid}-reactive.json`);
+}
+
+function isReactiveState(data: unknown): data is ReactiveExecutionState {
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  return typeof d.sliceId === "string" && Array.isArray(d.completed) && Array.isArray(d.dispatched);
+}
+
+/**
+ * Load persisted reactive execution state for a slice.
+ * Returns null when no state file exists or the file is invalid.
+ */
+export function loadReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): ReactiveExecutionState | null {
+  return loadJsonFileOrNull(reactiveStatePath(basePath, mid, sid), isReactiveState);
+}
+
+/**
+ * Save reactive execution state to disk.
+ */
+export function saveReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+  state: ReactiveExecutionState,
+): void {
+  saveJsonFile(reactiveStatePath(basePath, mid, sid), state);
+}
+
+/**
+ * Remove the reactive state file when a slice completes.
+ */
+export function clearReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): void {
+  const path = reactiveStatePath(basePath, mid, sid);
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // Non-fatal
+  }
+}

package/src/resources/extensions/gsd/repo-identity.ts

@@ -12,6 +12,8 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, s
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
 /**
@@ -90,14 +92,31 @@ function resolveGitRoot(basePath: string): string {
   }
 }
 
+/**
+ * Validate a GSD_PROJECT_ID value.
+ *
+ * Must contain only alphanumeric characters, hyphens, and underscores.
+ * Call this once at startup so the user gets immediate feedback on bad values.
+ */
+export function validateProjectId(id: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
 /**
  * Compute a stable identity for a repository.
  *
- * SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated to 12 hex chars.
- * Deterministic: same repo always produces the same hash regardless of
- * which worktree the caller is inside.
+ * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected
+ * to have already happened at startup via `validateProjectId`).
+ *
+ * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated
+ * to 12 hex chars. Deterministic: same repo always produces the same hash
+ * regardless of which worktree the caller is inside.
  */
 export function repoIdentity(basePath: string): string {
+  const projectId = process.env.GSD_PROJECT_ID;
+  if (projectId) {
+    return projectId;
+  }
   const remoteUrl = getRemoteUrl(basePath);
   const root = resolveGitRoot(basePath);
   const input = `${remoteUrl}\n${root}`;
@@ -113,7 +132,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+  const base = process.env.GSD_STATE_DIR || gsdHome;
   return join(base, "projects", repoIdentity(basePath));
 }
 

package/src/resources/extensions/gsd/resource-version.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { resolveProjectRoot } from "./worktree.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Resource Staleness ───────────────────────────────────────────────────
 
 /**
@@ -23,7 +25,7 @@ function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
 }
 
 export function readResourceVersion(): string | null {
-  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
   return manifest?.gsdVersion ?? null;

package/src/resources/extensions/gsd/roadmap-mutations.ts

@@ -39,6 +39,35 @@ export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: strin
   return true;
 }
 
+/**
+ * Mark a slice as not done ([ ]) in the milestone roadmap.
+ * Idempotent — no-op if already unchecked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceUndoneInRoadmap(basePath: string, mid: string, sid: string): boolean {
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  if (!roadmapFile) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(roadmapFile, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[ ] **${sid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(roadmapFile, updated);
+  clearParseCache();
+  return true;
+}
+
 /**
  * Mark a task as done ([x]) in the slice plan.
  * Idempotent — no-op if already checked or if the task isn't found.

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

@@ -31,7 +31,7 @@ import {
   gsdRoot,
 } from './paths.js';
 
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';

package/src/resources/extensions/gsd/templates/task-plan.md

@@ -42,11 +42,19 @@ estimated_files: {{estimatedFiles}}
 
 ## Inputs
 
+<!-- Every input MUST be a backtick-wrapped file path. These paths are machine-parsed to
+     derive task dependencies — vague descriptions without paths break dependency detection.
+     For the first task in a slice with no prior task outputs, list the existing source files
+     this task reads or modifies. -->
+
 - `{{filePath}}` — {{whatThisTaskNeedsFromPriorWork}}
-- {{priorTaskSummaryInsight}}
 
 ## Expected Output
 
-<!-- This task should produce a real increment toward making the slice goal/demo true. A full slice plan should not be able to mark every task complete while the claimed slice behavior still does not work at the stated proof level. -->
+<!-- Every output MUST be a backtick-wrapped file path — the specific files this task creates
+     or modifies. These paths are machine-parsed to derive task dependencies.
+     This task should produce a real increment toward making the slice goal/demo true. A full
+     slice plan should not be able to mark every task complete while the claimed slice behavior
+     still does not work at the stated proof level. -->
 
-- `{{filePath}}` — {{whatThisTaskShouldProduceOrModify}}
+- `{{filePath}}` — {{whatThisTaskCreatesOrModifies}}

package/src/resources/extensions/gsd/tests/agent-end-retry.test.ts

@@ -1,9 +1,9 @@
 /**
- * agent-end-retry.test.ts — Regression checks for the post-#1419 agent_end model.
+ * agent-end-retry.test.ts — Regression checks for the agent_end model.
  *
- * The old recursive handleAgentEnd retry path is gone. The loop now keeps
- * pendingResolve + pendingAgentEndQueue on AutoSession, and handleAgentEnd is
- * only a thin compatibility wrapper around resolveAgentEnd().
+ * The per-unit one-shot resolve function lives at module level in auto-loop.ts
+ * (_currentResolve). handleAgentEnd is a thin compatibility wrapper around
+ * resolveAgentEnd().
  */
 
 import test from "node:test";
@@ -14,40 +14,43 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
+const AUTO_LOOP_TS_PATH = join(__dirname, "..", "auto-loop.ts");
 const SESSION_TS_PATH = join(__dirname, "..", "auto", "session.ts");
 
 function getAutoTsSource(): string {
   return readFileSync(AUTO_TS_PATH, "utf-8");
 }
 
+function getAutoLoopTsSource(): string {
+  return readFileSync(AUTO_LOOP_TS_PATH, "utf-8");
+}
+
 function getSessionTsSource(): string {
   return readFileSync(SESSION_TS_PATH, "utf-8");
 }
 
-test("AutoSession declares pending agent_end queue state", () => {
-  const source = getSessionTsSource();
+test("auto-loop.ts declares _currentResolve for per-unit one-shot promises", () => {
+  const source = getAutoLoopTsSource();
   assert.ok(
-    source.includes("pendingResolve"),
-    "AutoSession must declare pendingResolve for the in-flight unit promise",
+    source.includes("_currentResolve"),
+    "auto-loop.ts must declare _currentResolve for the per-unit resolve function",
   );
   assert.ok(
-    source.includes("pendingAgentEndQueue"),
-    "AutoSession must declare pendingAgentEndQueue for between-iteration agent_end events",
+    source.includes("_sessionSwitchInFlight"),
+    "auto-loop.ts must declare _sessionSwitchInFlight guard",
   );
 });
 
-test("AutoSession reset clears pending agent_end queue state", () => {
+test("AutoSession no longer holds promise state (moved to auto-loop.ts module scope)", () => {
   const source = getSessionTsSource();
-  const resetIdx = source.indexOf("reset(): void");
-  assert.ok(resetIdx > -1, "AutoSession must have a reset() method");
-  const resetBlock = source.slice(resetIdx, resetIdx + 4000);
+  // Properties should NOT exist as class fields
   assert.ok(
-    resetBlock.includes("this.pendingResolve = null"),
-    "reset() must clear pendingResolve",
+    !source.includes("pendingResolve:"),
+    "AutoSession must not declare pendingResolve (moved to auto-loop.ts)",
   );
   assert.ok(
-    resetBlock.includes("this.pendingAgentEndQueue = []"),
-    "reset() must clear pendingAgentEndQueue",
+    !source.includes("pendingAgentEndQueue:"),
+    "AutoSession must not declare pendingAgentEndQueue (removed — events are dropped)",
   );
 });