gsd-pi 2.41.0-dev.0acbce9 → 2.41.0-dev.5a170d0

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/exit-command.ts

@@ -10,8 +10,20 @@ export function registerExitCommand(
     description: "Exit GSD gracefully",
     handler: async (_args: string, ctx: ExtensionCommandContext) => {
       // Stop auto-mode first so locks and activity state are cleaned up before shutdown.
-      const stopAuto = deps.stopAuto ?? (await importExtensionModule<typeof import("./auto.js")>(import.meta.url, "./auto.js")).stopAuto;
-      await stopAuto(ctx, pi, "Graceful exit");
+      // Wrapped in try/catch: if gsd-pi was updated on disk mid-session, the dynamic
+      // import may resolve a new auto-worktree.js whose static imports reference
+      // exports absent from the process-cached native-git-bridge.js (ESM cache is
+      // immutable). The user's work is already saved — this is cleanup only.
+      try {
+        const stopAuto = deps.stopAuto ?? (await importExtensionModule<typeof import("./auto.js")>(import.meta.url, "./auto.js")).stopAuto;
+        await stopAuto(ctx, pi, "Graceful exit");
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        ctx.ui?.notify?.(
+          `Auto-mode cleanup skipped (module version mismatch): ${msg}`,
+          "warning",
+        );
+      }
       ctx.shutdown();
     },
   });

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

@@ -4,7 +4,7 @@
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { writeFileSync, mkdirSync } from "node:fs";
 import { join, basename } from "node:path";
-import { exec } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import {
   getLedger, getProjectTotals, aggregateByPhase, aggregateBySlice,
   aggregateByModel, formatCost, formatTokenCount, loadLedgerFromDisk,
@@ -20,20 +20,13 @@ import { getErrorMessage } from "./error-utils.js";
  * Non-blocking, non-fatal — failures are silently ignored.
  */
 export function openInBrowser(filePath: string): void {
-  const cmd =
-    process.platform === "darwin" ? "open" :
-    process.platform === "win32" ? "start" :
-    "xdg-open";
-
-  // On Windows, `start` needs an empty title argument when the path has spaces
-  const args = process.platform === "win32"
-    ? `"" "${filePath}"`
-    : `"${filePath}"`;
-
-  exec(`${cmd} ${args}`, (err) => {
-    // Non-fatal — if the browser can't be opened, the file path is still shown
-    if (err) void err;
-  });
+  if (process.platform === "win32") {
+    // PowerShell's Start-Process handles paths with '&' and spaces safely.
+    execFile("powershell", ["-c", `Start-Process '${filePath.replace(/'/g, "''")}'`], () => {});
+  } else {
+    const cmd = process.platform === "darwin" ? "open" : "xdg-open";
+    execFile(cmd, [filePath], () => {});
+  }
 }
 
 /**

package/src/resources/extensions/gsd/extension-manifest.json

@@ -8,8 +8,8 @@
   "provides": {
     "tools": [
       "bash", "write", "read", "edit",
-      "gsd_save_decision", "gsd_save_summary",
-      "gsd_update_requirement", "gsd_generate_milestone_id"
+      "gsd_decision_save", "gsd_summary_save",
+      "gsd_requirement_update", "gsd_milestone_generate_id"
     ],
     "commands": ["gsd", "kill", "worktree", "exit"],
     "hooks": ["session_start"],

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

@@ -374,20 +374,37 @@ function _parsePlanImpl(content: string): SlicePlan {
 
     for (const line of taskLines) {
       const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
-      if (cbMatch) {
+      // Heading-style: ### T01 -- Title, ### T01: Title, ### T01 — Title
+      const hdMatch = !cbMatch ? line.match(/^#{2,4}\s+([\w.]+)\s*(?:--|—|:)\s*(.+)/) : null;
+      if (cbMatch || hdMatch) {
         if (currentTask) tasks.push(currentTask);
 
-        const rest = cbMatch[4] || '';
-        const estMatch = rest.match(/`est:([^`]+)`/);
-        const estimate = estMatch ? estMatch[1] : '';
-
-        currentTask = {
-          id: cbMatch[2],
-          title: cbMatch[3],
-          description: '',
-          done: cbMatch[1].toLowerCase() === 'x',
-          estimate,
-        };
+        if (cbMatch) {
+          const rest = cbMatch[4] || '';
+          const estMatch = rest.match(/`est:([^`]+)`/);
+          const estimate = estMatch ? estMatch[1] : '';
+
+          currentTask = {
+            id: cbMatch[2],
+            title: cbMatch[3],
+            description: '',
+            done: cbMatch[1].toLowerCase() === 'x',
+            estimate,
+          };
+        } else {
+          const rest = hdMatch![2] || '';
+          const titleEstMatch = rest.match(/^(.+?)\s*`est:([^`]+)`\s*$/);
+          const title = titleEstMatch ? titleEstMatch[1].trim() : rest.trim();
+          const estimate = titleEstMatch ? titleEstMatch[2] : '';
+
+          currentTask = {
+            id: hdMatch![1],
+            title,
+            description: '',
+            done: false,
+            estimate,
+          };
+        }
       } else if (currentTask && line.match(/^\s*-\s+Files:\s*(.*)/)) {
         const filesMatch = line.match(/^\s*-\s+Files:\s*(.*)/);
         if (filesMatch) {

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

@@ -12,6 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
 import { extractTrace, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -102,9 +103,14 @@ export async function handleForensics(
   const report = await buildForensicReport(basePath);
   const savedPath = saveForensicReport(basePath, report, problemDescription);
 
-  // Derive GSD source dir for prompt
-  const __extensionDir = dirname(fileURLToPath(import.meta.url));
-  const gsdSourceDir = __extensionDir;
+  // Derive GSD source dir for prompt — fall back to ~/.gsd/agent/extensions/gsd/
+  // when import.meta.url resolves to the npm-global install path (Windows).
+  let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
+  if (!existsSync(join(gsdSourceDir, "prompts"))) {
+    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+    const fallback = join(gsdHome, "agent", "extensions", "gsd");
+    if (existsSync(join(fallback, "prompts"))) gsdSourceDir = fallback;
+  }
 
   const forensicData = formatReportForPrompt(report);
   const content = loadPrompt("forensics", {

package/src/resources/extensions/gsd/git-service.ts

@@ -683,10 +683,11 @@ export function createDraftPR(
   body: string,
 ): string | null {
   try {
-    const result = execSync(
-      `gh pr create --draft --title ${JSON.stringify(title)} --body ${JSON.stringify(body)}`,
-      { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV },
-    );
+    const result = execFileSync("gh", [
+      "pr", "create", "--draft",
+      "--title", title,
+      "--body", body,
+    ], { cwd: basePath, encoding: "utf8", timeout: 30000, env: GIT_NO_PROMPT_ENV });
     return result.trim();
   } catch {
     return null;

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 };