gsd-pi 2.41.0 → 2.42.0-dev.eedc83f

package/src/resources/extensions/gsd/custom-verification.ts

@@ -0,0 +1,180 @@
+/**
+ * custom-verification.ts — Step verification for custom workflows.
+ *
+ * Reads the frozen DEFINITION.yaml from a run directory, finds the step's
+ * `verify` policy, and dispatches to the appropriate handler. Four policies:
+ *
+ *   - content-heuristic: file existence + optional minSize + optional pattern match
+ *   - shell-command: spawnSync with 30s timeout, exit 0 → continue, else retry
+ *   - prompt-verify: always "pause" (defers to agent)
+ *   - human-review: always "pause" (waits for manual inspection)
+ *   - (no policy): returns "continue" (passthrough)
+ *
+ * Observability:
+ * - Return value is the typed verification outcome ("continue" | "retry" | "pause").
+ * - shell-command captures stderr from spawnSync — callers can inspect on retry.
+ * - content-heuristic logs the specific failure (missing file, below minSize, pattern mismatch).
+ * - The frozen DEFINITION.yaml on disk is the single source of truth for step policies.
+ */
+
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { StepDefinition, VerifyPolicy } from "./definition-loader.js";
+import { readFrozenDefinition } from "./custom-workflow-engine.js";
+
+/** Verification outcome type — matches ExecutionPolicy.verify() return type. */
+export type VerificationOutcome = "continue" | "retry" | "pause";
+
+/**
+ * Run custom verification for a specific step in a workflow run.
+ *
+ * Reads the frozen DEFINITION.yaml from `runDir`, finds the step with the
+ * given `stepId`, and dispatches to the appropriate verification handler
+ * based on the step's `verify.policy` field.
+ *
+ * @param runDir — absolute path to the workflow run directory
+ * @param stepId — the step ID to verify (e.g. "step-1")
+ * @returns "continue" if verification passes, "retry" if it should retry, "pause" if it needs review
+ * @throws Error if DEFINITION.yaml is missing or unreadable
+ */
+export function runCustomVerification(
+  runDir: string,
+  stepId: string,
+): VerificationOutcome {
+  const def = readFrozenDefinition(runDir);
+
+  const step = def.steps.find((s: StepDefinition) => s.id === stepId);
+  if (!step) {
+    // Step not found in definition — nothing to verify, continue
+    return "continue";
+  }
+
+  if (!step.verify) {
+    // No verification policy configured — passthrough
+    return "continue";
+  }
+
+  return dispatchPolicy(runDir, step, step.verify);
+}
+
+/**
+ * Dispatch to the correct policy handler.
+ */
+function dispatchPolicy(
+  runDir: string,
+  step: StepDefinition,
+  verify: VerifyPolicy,
+): VerificationOutcome {
+  switch (verify.policy) {
+    case "content-heuristic":
+      return handleContentHeuristic(runDir, step, verify);
+    case "shell-command":
+      return handleShellCommand(runDir, verify);
+    case "prompt-verify":
+      return "pause";
+    case "human-review":
+      return "pause";
+    default:
+      // Unknown policy — safe default is pause
+      return "pause";
+  }
+}
+
+/**
+ * content-heuristic handler.
+ *
+ * For each path in the step's `produces` array:
+ * 1. Check that the file exists (resolved relative to runDir)
+ * 2. If `minSize` is set, check that file size >= minSize bytes
+ * 3. If `pattern` is set, check that file content matches the regex
+ *
+ * Returns "continue" if all checks pass, "pause" if any fail.
+ * If `produces` is empty or undefined, returns "continue" (nothing to check).
+ */
+function handleContentHeuristic(
+  runDir: string,
+  step: StepDefinition,
+  verify: { policy: "content-heuristic"; minSize?: number; pattern?: string },
+): VerificationOutcome {
+  const produces = step.produces;
+  if (!produces || produces.length === 0) {
+    return "continue";
+  }
+
+  for (const relPath of produces) {
+    const absPath = resolve(runDir, relPath);
+    // Path traversal guard
+    if (!absPath.startsWith(resolve(runDir) + sep) && absPath !== resolve(runDir)) {
+      return "pause";
+    }
+
+    // 1. File existence
+    if (!existsSync(absPath)) {
+      return "pause";
+    }
+
+    // 2. Minimum size check
+    if (verify.minSize !== undefined) {
+      const stat = statSync(absPath);
+      if (stat.size < verify.minSize) {
+        return "pause";
+      }
+    }
+
+    // 3. Pattern match check (with timeout guard against ReDoS)
+    if (verify.pattern !== undefined) {
+      const content = readFileSync(absPath, "utf-8");
+      try {
+        if (!new RegExp(verify.pattern).test(content)) {
+          return "pause";
+        }
+      } catch {
+        // Invalid regex at runtime — treat as verification failure
+        return "pause";
+      }
+    }
+  }
+
+  return "continue";
+}
+
+/**
+ * shell-command handler.
+ *
+ * Runs the command via `sh -c` with cwd set to the run directory
+ * and a 30-second timeout. Returns "continue" if exit code 0,
+ * "retry" otherwise (including timeout/signal kills).
+ *
+ * SECURITY: The command string comes from a frozen DEFINITION.yaml written
+ * at run-creation time. The trust boundary is the workflow definition author.
+ * Commands run with the same privileges as the GSD process. Only use
+ * shell-command verification with definitions you trust.
+ */
+function handleShellCommand(
+  runDir: string,
+  verify: { policy: "shell-command"; command: string },
+): VerificationOutcome {
+  // Guard: reject commands containing shell expansion patterns that suggest injection
+  const dangerousPatterns = /\$\(|`|;\s*(rm|curl|wget|nc|bash|sh|eval)\b/;
+  if (dangerousPatterns.test(verify.command)) {
+    console.warn(
+      `custom-verification: shell-command contains suspicious pattern, skipping: ${verify.command}`,
+    );
+    return "pause";
+  }
+
+  const result = spawnSync("sh", ["-c", verify.command], {
+    cwd: runDir,
+    timeout: 30_000,
+    encoding: "utf-8",
+    stdio: "pipe",
+    env: { ...process.env, PATH: process.env.PATH },
+  });
+
+  if (result.status === 0) {
+    return "continue";
+  }
+
+  return "retry";
+}

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

@@ -0,0 +1,216 @@
+/**
+ * custom-workflow-engine.ts — WorkflowEngine implementation for custom workflows.
+ *
+ * Drives the auto-loop using GRAPH.yaml step state from a run directory.
+ * Each iteration: deriveState reads the graph, resolveDispatch picks the
+ * next eligible step, reconcile marks it complete and persists.
+ *
+ * Observability:
+ * - All state reads/writes go through graph.ts YAML I/O — inspectable on disk.
+ * - `resolveDispatch` returns unitType "custom-step" with unitId "<name>/<stepId>".
+ * - `getDisplayMetadata` provides step N/M progress for dashboard rendering.
+ * - Phase transitions are derivable from GRAPH.yaml step statuses.
+ */
+
+import type { WorkflowEngine } from "./workflow-engine.js";
+import type {
+  EngineState,
+  EngineDispatchAction,
+  CompletedStep,
+  ReconcileResult,
+  DisplayMetadata,
+} from "./engine-types.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import {
+  readGraph,
+  writeGraph,
+  getNextPendingStep,
+  markStepComplete,
+  expandIteration,
+  type WorkflowGraph,
+} from "./graph.js";
+import { injectContext } from "./context-injector.js";
+import type { WorkflowDefinition, StepDefinition } from "./definition-loader.js";
+
+/** Read and parse the frozen DEFINITION.yaml from a run directory. */
+export function readFrozenDefinition(runDir: string): WorkflowDefinition {
+  const defPath = join(runDir, "DEFINITION.yaml");
+  const raw = readFileSync(defPath, "utf-8");
+  return parse(raw, { schema: "core" }) as WorkflowDefinition;
+}
+
+export class CustomWorkflowEngine implements WorkflowEngine {
+  readonly engineId = "custom";
+  private readonly runDir: string;
+
+  constructor(runDir: string) {
+    this.runDir = runDir;
+  }
+
+  /**
+   * Derive engine state from GRAPH.yaml on disk.
+   *
+   * Phase is "complete" when all steps are complete or expanded,
+   * "running" otherwise (any pending or active steps remain).
+   */
+  async deriveState(_basePath: string): Promise<EngineState> {
+    const graph = readGraph(this.runDir);
+    const allDone = graph.steps.every(
+      (s) => s.status === "complete" || s.status === "expanded",
+    );
+    const phase = allDone ? "complete" : "running";
+
+    return {
+      phase,
+      currentMilestoneId: null,
+      activeSliceId: null,
+      activeTaskId: null,
+      isComplete: allDone,
+      raw: graph,
+    };
+  }
+
+  /**
+   * Resolve the next dispatch action from graph state.
+   *
+   * Uses getNextPendingStep to find the first step whose dependencies
+   * are all satisfied. If the step has an `iterate` config in the frozen
+   * DEFINITION.yaml, expands it into instance steps before dispatching.
+   *
+   * Returns a dispatch with unitType "custom-step" and unitId in
+   * "<workflowName>/<stepId>" format.
+   *
+   * Observability:
+   * - Iterate expansion is logged to stderr with item count and parent step ID.
+   * - Missing source artifacts throw with the full resolved path for diagnosis.
+   * - Zero-match expansions return a stop action with level "info".
+   * - Expanded GRAPH.yaml is written to disk before dispatch — inspectable on disk.
+   */
+  async resolveDispatch(
+    state: EngineState,
+    _context: { basePath: string },
+  ): Promise<EngineDispatchAction> {
+    let graph = state.raw as WorkflowGraph;
+    let next = getNextPendingStep(graph);
+
+    if (!next) {
+      return {
+        action: "stop",
+        reason: "All steps complete",
+        level: "info",
+      };
+    }
+
+    // Check frozen DEFINITION.yaml for iterate config on this step
+    const def = readFrozenDefinition(this.runDir);
+    const stepDef = def.steps.find((s: StepDefinition) => s.id === next!.id);
+
+    if (stepDef?.iterate) {
+      const iterate = stepDef.iterate;
+
+      // Read source artifact
+      const sourcePath = join(this.runDir, iterate.source);
+      let sourceContent: string;
+      try {
+        sourceContent = readFileSync(sourcePath, "utf-8");
+      } catch {
+        throw new Error(
+          `Iterate source artifact not found: ${sourcePath} (step "${next.id}", source: "${iterate.source}")`,
+        );
+      }
+
+      // Extract items via regex with global+multiline flags.
+      // Guard against ReDoS: if matching takes too long on large inputs, bail.
+      const regex = new RegExp(iterate.pattern, "gm");
+      const items: string[] = [];
+      const matchStart = Date.now();
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(sourceContent)) !== null) {
+        if (match[1] !== undefined) items.push(match[1]);
+        if (Date.now() - matchStart > 5_000) {
+          throw new Error(
+            `Iterate pattern "${iterate.pattern}" exceeded 5s timeout on step "${next.id}" — possible ReDoS`,
+          );
+        }
+      }
+
+      // Expand the graph
+      const expandedGraph = expandIteration(graph, next.id, items, next.prompt);
+      writeGraph(this.runDir, expandedGraph);
+      graph = expandedGraph;
+
+      // Re-query for first instance step
+      next = getNextPendingStep(expandedGraph);
+
+      if (!next) {
+        return {
+          action: "stop",
+          reason: "Iterate expansion produced no instances",
+          level: "info",
+        };
+      }
+    }
+
+    // Enrich prompt with context from prior step artifacts
+    const enrichedPrompt = injectContext(this.runDir, next.id, next.prompt);
+
+    return {
+      action: "dispatch",
+      step: {
+        unitType: "custom-step",
+        unitId: `${graph.metadata.name}/${next.id}`,
+        prompt: enrichedPrompt,
+      },
+    };
+  }
+
+  /**
+   * Reconcile state after a step completes.
+   *
+   * Extracts the stepId from the completedStep's unitId (last segment after `/`),
+   * marks it complete in the graph, and writes the updated GRAPH.yaml to disk.
+   *
+   * Returns "milestone-complete" when all steps are now done, "continue" otherwise.
+   */
+  async reconcile(
+    state: EngineState,
+    completedStep: CompletedStep,
+  ): Promise<ReconcileResult> {
+    const graph = state.raw as WorkflowGraph;
+
+    // Extract stepId from "<workflowName>/<stepId>"
+    const parts = completedStep.unitId.split("/");
+    const stepId = parts[parts.length - 1];
+
+    const updatedGraph = markStepComplete(graph, stepId);
+    writeGraph(this.runDir, updatedGraph);
+
+    const allDone = updatedGraph.steps.every(
+      (s) => s.status === "complete" || s.status === "expanded",
+    );
+
+    return {
+      outcome: allDone ? "milestone-complete" : "continue",
+    };
+  }
+
+  /**
+   * Return UI-facing metadata for progress display.
+   *
+   * Shows "Step N/M" progress where N = completed count and M = total.
+   */
+  getDisplayMetadata(state: EngineState): DisplayMetadata {
+    const graph = state.raw as WorkflowGraph;
+    const total = graph.steps.length;
+    const completed = graph.steps.filter((s) => s.status === "complete").length;
+
+    return {
+      engineLabel: "WORKFLOW",
+      currentPhase: state.phase,
+      progressSummary: `Step ${completed}/${total}`,
+      stepCount: { completed, total },
+    };
+  }
+}

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -38,6 +38,7 @@ function unitLabel(type: string): string {
     case "triage-captures": return "Triage";
     case "quick-task": return "Quick Task";
     case "replan-slice": return "Replan";
+    case "custom-step": return "Workflow Step";
     default: return type;
   }
 }

package/src/resources/extensions/gsd/db-writer.ts

@@ -35,8 +35,8 @@ export function generateDecisionsMd(decisions: Decision[]): string {
   lines.push('     To reverse a decision, add a new row that supersedes it.');
   lines.push('     Read this file at the start of any planning or research phase. -->');
   lines.push('');
-  lines.push('| # | When | Scope | Decision | Choice | Rationale | Revisable? |');
-  lines.push('|---|------|-------|----------|--------|-----------|------------|');
+  lines.push('| # | When | Scope | Decision | Choice | Rationale | Revisable? | Made By |');
+  lines.push('|---|------|-------|----------|--------|-----------|------------|---------|');
 
   for (const d of decisions) {
     // Escape pipe characters within cell values to preserve table structure
@@ -48,6 +48,7 @@ export function generateDecisionsMd(decisions: Decision[]): string {
       d.choice,
       d.rationale,
       d.revisable,
+      d.made_by ?? 'agent',
     ].map(cell => (cell ?? '').replace(/\|/g, '\\|'));
 
     lines.push(`| ${cells.join(' | ')} |`);
@@ -181,6 +182,7 @@ export interface SaveDecisionFields {
   rationale: string;
   revisable?: string;
   when_context?: string;
+  made_by?: import('./types.js').DecisionMadeBy;
 }
 
 /**
@@ -205,6 +207,7 @@ export async function saveDecisionToDb(
       choice: fields.choice,
       rationale: fields.rationale,
       revisable: fields.revisable ?? 'Yes',
+      made_by: fields.made_by ?? 'agent',
       superseded_by: null,
     });
 
@@ -222,6 +225,7 @@ export async function saveDecisionToDb(
         choice: row['choice'] as string,
         rationale: row['rationale'] as string,
         revisable: row['revisable'] as string,
+        made_by: (row['made_by'] as string as import('./types.js').DecisionMadeBy) ?? 'agent',
         superseded_by: (row['superseded_by'] as string) ?? null,
       }));
     }