gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.97e9e30

package/src/resources/extensions/gsd/dev-execution-policy.ts

@@ -0,0 +1,51 @@
+/**
+ * dev-execution-policy.ts — DevExecutionPolicy implementation.
+ *
+ * Stub policy for the dev engine. All methods return safe defaults.
+ * Real verification/closeout continues running through phases.ts via LoopDeps.
+ * Wiring this policy into the loop is S04's responsibility.
+ */
+
+import type { ExecutionPolicy } from "./execution-policy.js";
+import type { RecoveryAction, CloseoutResult } from "./engine-types.js";
+
+export class DevExecutionPolicy implements ExecutionPolicy {
+  async prepareWorkspace(
+    _basePath: string,
+    _milestoneId: string,
+  ): Promise<void> {
+    // no-op — workspace preparation handled by existing GSD logic
+  }
+
+  async selectModel(
+    _unitType: string,
+    _unitId: string,
+    _context: { basePath: string },
+  ): Promise<{ tier: string; modelDowngraded: boolean } | null> {
+    return null; // use default model selection
+  }
+
+  async verify(
+    _unitType: string,
+    _unitId: string,
+    _context: { basePath: string },
+  ): Promise<"continue" | "retry" | "pause"> {
+    return "continue";
+  }
+
+  async recover(
+    _unitType: string,
+    _unitId: string,
+    _context: { basePath: string },
+  ): Promise<RecoveryAction> {
+    return { outcome: "retry" };
+  }
+
+  async closeout(
+    _unitType: string,
+    _unitId: string,
+    _context: { basePath: string; startedAt: number },
+  ): Promise<CloseoutResult> {
+    return { committed: false, artifacts: [] };
+  }
+}

package/src/resources/extensions/gsd/dev-workflow-engine.ts

@@ -0,0 +1,110 @@
+/**
+ * dev-workflow-engine.ts — DevWorkflowEngine implementation.
+ *
+ * Implements WorkflowEngine by delegating to existing GSD state derivation
+ * and dispatch logic. This is the "dev" engine — it wraps the current GSD
+ * auto-mode behavior behind the engine-polymorphic interface.
+ */
+
+import type { WorkflowEngine } from "./workflow-engine.js";
+import type {
+  EngineState,
+  EngineDispatchAction,
+  CompletedStep,
+  ReconcileResult,
+  DisplayMetadata,
+} from "./engine-types.js";
+import type { GSDState } from "./types.js";
+import type { DispatchAction, DispatchContext } from "./auto-dispatch.js";
+
+import { deriveState } from "./state.js";
+import { resolveDispatch } from "./auto-dispatch.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+
+// ─── Bridge: DispatchAction → EngineDispatchAction ────────────────────────
+
+/**
+ * Map a GSD-specific DispatchAction (which carries `matchedRule`, `unitType`,
+ * etc.) to the engine-generic EngineDispatchAction discriminated union.
+ *
+ * Exported for unit testing.
+ */
+export function bridgeDispatchAction(da: DispatchAction): EngineDispatchAction {
+  switch (da.action) {
+    case "dispatch":
+      return {
+        action: "dispatch",
+        step: {
+          unitType: da.unitType,
+          unitId: da.unitId,
+          prompt: da.prompt,
+        },
+      };
+    case "stop":
+      return {
+        action: "stop",
+        reason: da.reason,
+        level: da.level,
+      };
+    case "skip":
+      return { action: "skip" };
+  }
+}
+
+// ─── DevWorkflowEngine ───────────────────────────────────────────────────
+
+export class DevWorkflowEngine implements WorkflowEngine {
+  readonly engineId = "dev" as const;
+
+  async deriveState(basePath: string): Promise<EngineState> {
+    const gsd: GSDState = await deriveState(basePath);
+    return {
+      phase: gsd.phase,
+      currentMilestoneId: gsd.activeMilestone?.id ?? null,
+      activeSliceId: gsd.activeSlice?.id ?? null,
+      activeTaskId: gsd.activeTask?.id ?? null,
+      isComplete: gsd.phase === "complete",
+      raw: gsd,
+    };
+  }
+
+  async resolveDispatch(
+    state: EngineState,
+    context: { basePath: string },
+  ): Promise<EngineDispatchAction> {
+    const gsd = state.raw as GSDState;
+    const mid = gsd.activeMilestone?.id ?? "";
+    const midTitle = gsd.activeMilestone?.title ?? "";
+    const loaded = loadEffectiveGSDPreferences();
+    const prefs = loaded?.preferences ?? undefined;
+
+    const dispatchCtx: DispatchContext = {
+      basePath: context.basePath,
+      mid,
+      midTitle,
+      state: gsd,
+      prefs,
+    };
+
+    const result = await resolveDispatch(dispatchCtx);
+    return bridgeDispatchAction(result);
+  }
+
+  async reconcile(
+    state: EngineState,
+    _completedStep: CompletedStep,
+  ): Promise<ReconcileResult> {
+    return {
+      outcome: state.isComplete ? "milestone-complete" : "continue",
+    };
+  }
+
+  getDisplayMetadata(state: EngineState): DisplayMetadata {
+    return {
+      engineLabel: "GSD Dev",
+      currentPhase: state.phase,
+      progressSummary: `${state.currentMilestoneId ?? "no milestone"} / ${state.activeSliceId ?? "—"} / ${state.activeTaskId ?? "—"}`,
+      stepCount: null,
+    };
+  }
+}

package/src/resources/extensions/gsd/engine-resolver.ts

@@ -0,0 +1,57 @@
+/**
+ * engine-resolver.ts — Route sessions to engine/policy pairs.
+ *
+ * Routes `null` and `"dev"` engine IDs to the DevWorkflowEngine/DevExecutionPolicy
+ * pair. Any other non-null engine ID is treated as a custom workflow engine that
+ * reads its state from an `activeRunDir`. Respects `GSD_ENGINE_BYPASS=1` kill
+ * switch to skip the engine layer entirely.
+ */
+
+import type { WorkflowEngine } from "./workflow-engine.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { DevWorkflowEngine } from "./dev-workflow-engine.js";
+import { DevExecutionPolicy } from "./dev-execution-policy.js";
+import { CustomWorkflowEngine } from "./custom-workflow-engine.js";
+import { CustomExecutionPolicy } from "./custom-execution-policy.js";
+
+/** A resolved engine + policy pair ready for the auto-loop. */
+export interface ResolvedEngine {
+  engine: WorkflowEngine;
+  policy: ExecutionPolicy;
+}
+
+/**
+ * Resolve an engine/policy pair for the given session.
+ *
+ * - `null` or `"dev"` → DevWorkflowEngine + DevExecutionPolicy
+ * - any other non-null ID → CustomWorkflowEngine(activeRunDir) + CustomExecutionPolicy()
+ *   (requires activeRunDir to be a non-empty string)
+ *
+ * Note: `GSD_ENGINE_BYPASS=1` is checked in autoLoop before calling this function.
+ */
+export function resolveEngine(
+  session: { activeEngineId: string | null; activeRunDir?: string | null },
+): ResolvedEngine {
+  const { activeEngineId, activeRunDir } = session;
+
+  if (activeEngineId === null || activeEngineId === "dev") {
+    return {
+      engine: new DevWorkflowEngine(),
+      policy: new DevExecutionPolicy(),
+    };
+  }
+
+  // Any non-null, non-"dev" engine ID is a custom workflow engine.
+  // activeRunDir is required — the engine reads GRAPH.yaml from it.
+  if (!activeRunDir || typeof activeRunDir !== "string") {
+    throw new Error(
+      `Custom engine "${activeEngineId}" requires activeRunDir to be a non-empty string, ` +
+      `got: ${JSON.stringify(activeRunDir)}`,
+    );
+  }
+
+  return {
+    engine: new CustomWorkflowEngine(activeRunDir),
+    policy: new CustomExecutionPolicy(activeRunDir),
+  };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * engine-types.ts — Engine-polymorphic type contracts.
+ *
+ * LEAF NODE: This file must have ZERO imports from any GSD module.
+ * Only `node:` imports are permitted. All engine/policy interfaces
+ * depend on these types; nothing here depends on GSD internals.
+ */
+
+/** Snapshot of engine state at a point in time. */
+export interface EngineState {
+  phase: string;
+  currentMilestoneId: string | null;
+  activeSliceId: string | null;
+  activeTaskId: string | null;
+  isComplete: boolean;
+  /** Opaque engine-specific state — never narrowed to a GSD-specific type. */
+  raw: unknown;
+}
+
+/** A unit of work the engine wants the agent to execute. */
+export interface StepContract {
+  unitType: string;
+  unitId: string;
+  prompt: string;
+}
+
+/** UI-facing metadata for progress display. */
+export interface DisplayMetadata {
+  engineLabel: string;
+  currentPhase: string;
+  progressSummary: string;
+  stepCount: { completed: number; total: number } | null;
+}
+
+/**
+ * Discriminated union: what the engine tells the loop to do next.
+ *
+ * - `dispatch` — execute a step
+ * - `stop` — halt the loop with a reason and severity
+ * - `skip` — nothing to do right now, advance without executing
+ */
+export type EngineDispatchAction =
+  | { action: "dispatch"; step: StepContract }
+  | { action: "stop"; reason: string; level: "info" | "warning" | "error" }
+  | { action: "skip" };
+
+/** Outcome of reconciling state after a step completes. */
+export interface ReconcileResult {
+  outcome: "continue" | "milestone-complete" | "pause" | "stop";
+  reason?: string;
+}
+
+/** Recovery strategy when a step fails. */
+export interface RecoveryAction {
+  outcome: "retry" | "skip" | "stop" | "pause";
+  reason?: string;
+}
+
+/** Result of closing out a completed unit. */
+export interface CloseoutResult {
+  committed: boolean;
+  artifacts: string[];
+}
+
+/** Record of a completed execution step. */
+export interface CompletedStep {
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  finishedAt: number;
+}

package/src/resources/extensions/gsd/execution-policy.ts

@@ -0,0 +1,43 @@
+/**
+ * execution-policy.ts — ExecutionPolicy interface.
+ *
+ * Defines the policy layer that governs model selection, verification,
+ * recovery, and closeout for each execution step. Imports only from
+ * the leaf-node engine-types.
+ */
+
+import type { RecoveryAction, CloseoutResult } from "./engine-types.js";
+
+/** Policy governing how each step is executed, verified, and closed out. */
+export interface ExecutionPolicy {
+  /** Prepare the workspace before a milestone begins (e.g. worktree setup). */
+  prepareWorkspace(basePath: string, milestoneId: string): Promise<void>;
+
+  /** Select the model tier for a given unit. Returns null to use defaults. */
+  selectModel(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<{ tier: string; modelDowngraded: boolean } | null>;
+
+  /** Verify unit output. Returns disposition for the loop. */
+  verify(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<"continue" | "retry" | "pause">;
+
+  /** Determine recovery action when a unit fails. */
+  recover(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<RecoveryAction>;
+
+  /** Close out a completed unit (commit, snapshot, artifact capture). */
+  closeout(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string; startedAt: number },
+  ): Promise<CloseoutResult>;
+}

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

@@ -0,0 +1,312 @@
+/**
+ * graph.ts — Pure data module for GRAPH.yaml workflow step tracking.
+ *
+ * Provides types and functions for reading, writing, and querying the
+ * step graph that drives CustomWorkflowEngine. Zero engine dependencies.
+ *
+ * GRAPH.yaml lives in a run directory and tracks step statuses
+ * (pending → active → complete) with optional dependency edges.
+ *
+ * Observability:
+ * - readGraph/writeGraph use YAML on disk — human-readable, diffable,
+ *   inspectable with `cat` or any YAML viewer.
+ * - Each GraphStep has status, startedAt, finishedAt fields visible in GRAPH.yaml.
+ * - writeGraph uses atomic write (tmp + rename) for crash safety.
+ * - All operations are immutable — callers always get a new graph object.
+ */
+
+import { parse, stringify } from "yaml";
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { WorkflowDefinition } from "./definition-loader.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+export interface GraphStep {
+  /** Unique step identifier within the workflow. */
+  id: string;
+  /** Human-readable step title. */
+  title: string;
+  /** Current status: pending → active → complete → expanded (iterate parent). */
+  status: "pending" | "active" | "complete" | "expanded";
+  /** The prompt to dispatch for this step. */
+  prompt: string;
+  /** IDs of steps that must be "complete" before this step can run. */
+  dependsOn: string[];
+  /** For iteration instances: ID of the parent step that was expanded. */
+  parentStepId?: string;
+  /** ISO timestamp when the step started executing. */
+  startedAt?: string;
+  /** ISO timestamp when the step finished executing. */
+  finishedAt?: string;
+}
+
+export interface WorkflowGraph {
+  /** Ordered list of steps in the workflow. */
+  steps: GraphStep[];
+  /** Workflow metadata. */
+  metadata: {
+    name: string;
+    createdAt: string;
+  };
+}
+
+// ─── YAML schema mapping ─────────────────────────────────────────────────
+
+const GRAPH_FILENAME = "GRAPH.yaml";
+
+/**
+ * Internal YAML shape — uses snake_case for YAML keys.
+ * Converted to/from the camelCase TypeScript types on read/write.
+ */
+interface YamlStep {
+  id: string;
+  title: string;
+  status: string;
+  prompt: string;
+  depends_on?: string[];
+  parent_step_id?: string;
+  started_at?: string;
+  finished_at?: string;
+}
+
+interface YamlGraph {
+  steps: YamlStep[];
+  metadata: { name: string; created_at: string };
+}
+
+// ─── Functions ───────────────────────────────────────────────────────────
+
+/**
+ * Read and parse GRAPH.yaml from a run directory.
+ *
+ * @param runDir — directory containing GRAPH.yaml
+ * @returns Parsed workflow graph
+ * @throws Error if file doesn't exist or YAML is malformed
+ */
+export function readGraph(runDir: string): WorkflowGraph {
+  const filePath = join(runDir, GRAPH_FILENAME);
+  if (!existsSync(filePath)) {
+    throw new Error(`GRAPH.yaml not found: ${filePath}`);
+  }
+  const raw = readFileSync(filePath, "utf-8");
+  const yaml = parse(raw) as YamlGraph;
+
+  if (!yaml?.steps || !Array.isArray(yaml.steps)) {
+    throw new Error(`Invalid GRAPH.yaml: missing or invalid 'steps' array in ${filePath}`);
+  }
+
+  return {
+    steps: yaml.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status as GraphStep["status"],
+      prompt: s.prompt,
+      dependsOn: s.depends_on ?? [],
+      ...(s.parent_step_id != null ? { parentStepId: s.parent_step_id } : {}),
+      ...(s.started_at != null ? { startedAt: s.started_at } : {}),
+      ...(s.finished_at != null ? { finishedAt: s.finished_at } : {}),
+    })),
+    metadata: {
+      name: yaml.metadata?.name ?? "unnamed",
+      createdAt: yaml.metadata?.created_at ?? new Date().toISOString(),
+    },
+  };
+}
+
+/**
+ * Write a workflow graph to GRAPH.yaml in a run directory.
+ * Creates the directory if it doesn't exist. Write is atomic (write + rename).
+ *
+ * @param runDir — directory to write GRAPH.yaml into
+ * @param graph — the workflow graph to serialize
+ */
+export function writeGraph(runDir: string, graph: WorkflowGraph): void {
+  if (!existsSync(runDir)) {
+    mkdirSync(runDir, { recursive: true });
+  }
+
+  const yamlData: YamlGraph = {
+    steps: graph.steps.map((s) => ({
+      id: s.id,
+      title: s.title,
+      status: s.status,
+      prompt: s.prompt,
+      depends_on: s.dependsOn.length > 0 ? s.dependsOn : undefined,
+      parent_step_id: s.parentStepId ?? undefined,
+      started_at: s.startedAt ?? undefined,
+      finished_at: s.finishedAt ?? undefined,
+    })) as YamlStep[],
+    metadata: {
+      name: graph.metadata.name,
+      created_at: graph.metadata.createdAt,
+    },
+  };
+
+  const filePath = join(runDir, GRAPH_FILENAME);
+  const tmpPath = filePath + ".tmp";
+  const content = stringify(yamlData);
+  writeFileSync(tmpPath, content, "utf-8");
+  // Atomic rename for crash safety
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Get the next pending step whose dependencies are all complete.
+ *
+ * Returns the first step (in array order) with status "pending" where
+ * every step in its `dependsOn` list has status "complete".
+ *
+ * @param graph — the workflow graph to query
+ * @returns The next dispatchable step, or null if none available
+ */
+export function getNextPendingStep(graph: WorkflowGraph): GraphStep | null {
+  const statusMap = new Map(graph.steps.map((s) => [s.id, s.status]));
+
+  for (const step of graph.steps) {
+    if (step.status !== "pending") continue;
+    const depsComplete = step.dependsOn.every(
+      (depId) => statusMap.get(depId) === "complete",
+    );
+    if (depsComplete) return step;
+  }
+
+  return null;
+}
+
+/**
+ * Return a new graph with the specified step marked as "complete".
+ * Immutable — does not mutate the input graph.
+ *
+ * @param graph — the current workflow graph
+ * @param stepId — ID of the step to mark complete
+ * @returns New graph with the step's status set to "complete"
+ * @throws Error if stepId is not found in the graph
+ */
+export function markStepComplete(
+  graph: WorkflowGraph,
+  stepId: string,
+): WorkflowGraph {
+  const found = graph.steps.some((s) => s.id === stepId);
+  if (!found) {
+    throw new Error(`Step not found: ${stepId}`);
+  }
+
+  return {
+    ...graph,
+    steps: graph.steps.map((s) =>
+      s.id === stepId
+        ? { ...s, status: "complete" as const, finishedAt: new Date().toISOString() }
+        : s,
+    ),
+  };
+}
+
+// ─── Iteration expansion ─────────────────────────────────────────────────
+
+/**
+ * Expand an iterate step into concrete instances. Pure and deterministic —
+ * identical inputs always produce identical output.
+ *
+ * Given a parent step with status "pending" and an array of matched items,
+ * creates one instance step per item, marks the parent as "expanded", and
+ * rewrites any downstream dependsOn references from the parent ID to the
+ * full set of instance IDs.
+ *
+ * @param graph — the current workflow graph (not mutated)
+ * @param stepId — ID of the iterate step to expand
+ * @param items — matched items from the source artifact
+ * @param promptTemplate — template with {{item}} placeholders
+ * @returns New WorkflowGraph with instances inserted and deps rewritten
+ * @throws Error if stepId not found or step is not pending
+ */
+export function expandIteration(
+  graph: WorkflowGraph,
+  stepId: string,
+  items: string[],
+  promptTemplate: string,
+): WorkflowGraph {
+  const parentIndex = graph.steps.findIndex((s) => s.id === stepId);
+  if (parentIndex === -1) {
+    throw new Error(`expandIteration: step not found: ${stepId}`);
+  }
+  const parentStep = graph.steps[parentIndex];
+  if (parentStep.status !== "pending") {
+    throw new Error(
+      `expandIteration: step "${stepId}" has status "${parentStep.status}", expected "pending"`,
+    );
+  }
+
+  // Create instance steps
+  const instanceIds: string[] = [];
+  const instances: GraphStep[] = items.map((item, i) => {
+    const instanceId = `${stepId}--${String(i + 1).padStart(3, "0")}`;
+    instanceIds.push(instanceId);
+    return {
+      id: instanceId,
+      title: `${parentStep.title}: ${item}`,
+      status: "pending" as const,
+      prompt: promptTemplate.replace(/\{\{item\}\}/g, () => item),
+      dependsOn: [...parentStep.dependsOn],
+      parentStepId: stepId,
+    };
+  });
+
+  // Build new steps array: copy everything, mark parent as expanded,
+  // insert instances right after the parent, rewrite downstream deps.
+  const newSteps: GraphStep[] = [];
+  for (let i = 0; i < graph.steps.length; i++) {
+    if (i === parentIndex) {
+      // Mark parent as expanded
+      newSteps.push({ ...parentStep, status: "expanded" as const });
+      // Insert instances immediately after parent
+      newSteps.push(...instances);
+    } else {
+      const step = graph.steps[i];
+      // Rewrite dependsOn: replace parent ID with all instance IDs
+      const hasDep = step.dependsOn.includes(stepId);
+      if (hasDep) {
+        const rewritten = step.dependsOn.flatMap((dep) =>
+          dep === stepId ? instanceIds : [dep],
+        );
+        newSteps.push({ ...step, dependsOn: rewritten });
+      } else {
+        newSteps.push(step);
+      }
+    }
+  }
+
+  return {
+    ...graph,
+    steps: newSteps,
+  };
+}
+
+// ─── Definition → Graph conversion ──────────────────────────────────────
+
+/**
+ * Convert a parsed WorkflowDefinition into a WorkflowGraph with all
+ * steps in "pending" status. Used by run-manager to generate the initial
+ * GRAPH.yaml for a new run.
+ *
+ * @param def — a validated WorkflowDefinition from definition-loader
+ * @returns WorkflowGraph with pending steps and metadata from the definition
+ */
+export function initializeGraph(def: WorkflowDefinition): WorkflowGraph {
+  return {
+    steps: def.steps.map((s) => ({
+      id: s.id,
+      title: s.name,
+      status: "pending" as const,
+      prompt: s.prompt,
+      dependsOn: s.requires ?? [],
+    })),
+    metadata: {
+      name: def.name,
+      createdAt: new Date().toISOString(),
+    },
+  };
+}
+
+/** @deprecated Use initializeGraph instead. Kept for backward compatibility. */
+export { initializeGraph as graphFromDefinition };