gsd-pi 2.41.0-dev.3557dc4 → 2.41.0-dev.5a170d0

package/dist/resources/extensions/gsd/custom-verification.js

@@ -0,0 +1,145 @@
+/**
+ * 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 { resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { readFrozenDefinition } from "./custom-workflow-engine.js";
+/**
+ * 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, stepId) {
+    const def = readFrozenDefinition(runDir);
+    const step = def.steps.find((s) => 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, step, verify) {
+    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, step, verify) {
+    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, verify) {
+    // 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/dist/resources/extensions/gsd/custom-workflow-engine.js

@@ -0,0 +1,164 @@
+/**
+ * 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 { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { readGraph, writeGraph, getNextPendingStep, markStepComplete, expandIteration, } from "./graph.js";
+import { injectContext } from "./context-injector.js";
+/** Read and parse the frozen DEFINITION.yaml from a run directory. */
+export function readFrozenDefinition(runDir) {
+    const defPath = join(runDir, "DEFINITION.yaml");
+    const raw = readFileSync(defPath, "utf-8");
+    return parse(raw, { schema: "core" });
+}
+export class CustomWorkflowEngine {
+    engineId = "custom";
+    runDir;
+    constructor(runDir) {
+        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) {
+        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, _context) {
+        let graph = state.raw;
+        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) => s.id === next.id);
+        if (stepDef?.iterate) {
+            const iterate = stepDef.iterate;
+            // Read source artifact
+            const sourcePath = join(this.runDir, iterate.source);
+            let sourceContent;
+            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 = [];
+            const matchStart = Date.now();
+            let match;
+            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, completedStep) {
+        const graph = state.raw;
+        // 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) {
+        const graph = state.raw;
+        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/dist/resources/extensions/gsd/dashboard-overlay.js

@@ -30,6 +30,7 @@ function unitLabel(type) {
         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/dist/resources/extensions/gsd/definition-loader.js

@@ -0,0 +1,352 @@
+/**
+ * definition-loader.ts — Parse and validate V1 YAML workflow definitions.
+ *
+ * Loads definition YAML files from `.gsd/workflow-defs/`, validates the
+ * V1 schema shape, and returns typed TypeScript objects. Pure functions
+ * with no engine or runtime dependencies — just `yaml` and `node:fs`.
+ *
+ * YAML uses snake_case (`depends_on`, `context_from`) per project convention (P005).
+ * TypeScript uses camelCase (`dependsOn`, `contextFrom`).
+ *
+ * Observability: All validation errors are collected into a string[] — callers
+ * can log, surface in dashboards, or return to agents for self-repair.
+ * substituteParams errors include the offending key name for traceability.
+ */
+import { parse } from "yaml";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+// ─── Validation ──────────────────────────────────────────────────────────
+/**
+ * Validate a parsed (but untyped) YAML object against the V1 workflow schema.
+ *
+ * Collects all errors (does not short-circuit) so a single call reveals
+ * every problem with the definition.
+ *
+ * Unknown fields are silently accepted for forward compatibility with
+ * S05/S06 features (`context_from`, `verify`, `iterate`).
+ */
+export function validateDefinition(parsed) {
+    const errors = [];
+    if (parsed == null || typeof parsed !== "object") {
+        return { valid: false, errors: ["Definition must be a non-null object"] };
+    }
+    const def = parsed;
+    // version: must be 1 (number)
+    if (def.version === undefined || def.version === null) {
+        errors.push("Missing required field: version");
+    }
+    else if (def.version !== 1) {
+        errors.push(`Unsupported version: ${def.version} (expected 1)`);
+    }
+    // name: must be a non-empty string
+    if (typeof def.name !== "string" || def.name.trim() === "") {
+        errors.push("Missing or empty required field: name");
+    }
+    // steps: must be a non-empty array
+    if (!Array.isArray(def.steps)) {
+        errors.push("Missing required field: steps (must be an array)");
+    }
+    else if (def.steps.length === 0) {
+        errors.push("steps must contain at least one step");
+    }
+    else {
+        // Track whether all steps have valid IDs — graph-level checks only run when true
+        let allStepIdsValid = true;
+        for (let i = 0; i < def.steps.length; i++) {
+            const step = def.steps[i];
+            if (step == null || typeof step !== "object") {
+                errors.push(`Step at index ${i} is not an object`);
+                allStepIdsValid = false;
+                continue;
+            }
+            // Required step fields
+            if (typeof step.id !== "string" || step.id.trim() === "") {
+                errors.push(`Step at index ${i} missing required field: id`);
+                allStepIdsValid = false;
+            }
+            if (typeof step.name !== "string" || step.name.trim() === "") {
+                errors.push(`Step at index ${i} missing required field: name`);
+            }
+            if (typeof step.prompt !== "string" || step.prompt.trim() === "") {
+                errors.push(`Step at index ${i} missing required field: prompt`);
+            }
+            // produces: path traversal guard
+            if (Array.isArray(step.produces)) {
+                for (const p of step.produces) {
+                    if (typeof p === "string" && p.includes("..")) {
+                        errors.push(`Step "${step.id}" produces path contains disallowed '..': ${p}`);
+                    }
+                }
+            }
+            // iterate: optional, but if present must conform to IterateConfig shape
+            if (step.iterate !== undefined) {
+                const it = step.iterate;
+                const sid = typeof step.id === "string" ? step.id : `index ${i}`;
+                if (it == null || typeof it !== "object" || Array.isArray(it)) {
+                    errors.push(`Step "${sid}" iterate must be an object with "source" and "pattern" fields`);
+                }
+                else {
+                    const itObj = it;
+                    if (typeof itObj.source !== "string" || itObj.source.trim() === "") {
+                        errors.push(`Step "${sid}" iterate.source must be a non-empty string`);
+                    }
+                    else if (itObj.source.includes("..")) {
+                        errors.push(`Step "${sid}" iterate.source contains disallowed '..' path traversal`);
+                    }
+                    if (typeof itObj.pattern !== "string" || itObj.pattern.trim() === "") {
+                        errors.push(`Step "${sid}" iterate.pattern must be a non-empty string`);
+                    }
+                    else {
+                        const pat = itObj.pattern;
+                        let regexValid = true;
+                        try {
+                            new RegExp(pat);
+                        }
+                        catch {
+                            regexValid = false;
+                            errors.push(`Step "${sid}" iterate.pattern is not a valid regex: ${pat}`);
+                        }
+                        if (regexValid && !/\((?!\?)/.test(pat)) {
+                            errors.push(`Step "${sid}" iterate.pattern must contain at least one capture group`);
+                        }
+                    }
+                }
+            }
+            // verify: optional, but if present must conform to VerifyPolicy shape
+            if (step.verify !== undefined) {
+                const v = step.verify;
+                const sid = typeof step.id === "string" ? step.id : `index ${i}`;
+                if (v == null || typeof v !== "object" || Array.isArray(v)) {
+                    errors.push(`Step "${sid}" verify must be an object with a "policy" field`);
+                }
+                else {
+                    const vObj = v;
+                    const VALID_POLICIES = ["content-heuristic", "shell-command", "prompt-verify", "human-review"];
+                    if (typeof vObj.policy !== "string" || !VALID_POLICIES.includes(vObj.policy)) {
+                        errors.push(`Step "${sid}" verify.policy must be one of: ${VALID_POLICIES.join(", ")}`);
+                    }
+                    else {
+                        // Policy-specific required field checks
+                        if (vObj.policy === "shell-command") {
+                            if (typeof vObj.command !== "string" || vObj.command.trim() === "") {
+                                errors.push(`Step "${sid}" verify policy "shell-command" requires a non-empty "command" field`);
+                            }
+                        }
+                        if (vObj.policy === "prompt-verify") {
+                            if (typeof vObj.prompt !== "string" || vObj.prompt.trim() === "") {
+                                errors.push(`Step "${sid}" verify policy "prompt-verify" requires a non-empty "prompt" field`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // ─── Graph-level validations (only when all step IDs are valid) ────
+        if (allStepIdsValid) {
+            const steps = def.steps;
+            // 1. Duplicate step ID check
+            const idCounts = new Map();
+            for (const step of steps) {
+                const id = step.id;
+                idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+            }
+            for (const [id, count] of idCounts) {
+                if (count > 1) {
+                    errors.push(`Duplicate step id: ${id}`);
+                }
+            }
+            // Build valid ID set for remaining checks
+            const validIds = new Set(steps.map((s) => s.id));
+            // 2. Dangling dependency check + 3. Self-referencing dependency check
+            for (const step of steps) {
+                const sid = step.id;
+                const deps = Array.isArray(step.requires)
+                    ? step.requires
+                    : Array.isArray(step.depends_on)
+                        ? step.depends_on
+                        : [];
+                for (const depId of deps) {
+                    if (depId === sid) {
+                        errors.push(`Step '${sid}' depends on itself`);
+                    }
+                    else if (!validIds.has(depId)) {
+                        errors.push(`Step '${sid}' requires unknown step '${depId}'`);
+                    }
+                }
+            }
+            // 4. Cycle detection (DFS) — only when no duplicate IDs
+            if (![...idCounts.values()].some((c) => c > 1)) {
+                // Build adjacency list: step → its dependencies
+                const adj = new Map();
+                for (const step of steps) {
+                    const sid = step.id;
+                    const deps = Array.isArray(step.requires)
+                        ? step.requires
+                        : Array.isArray(step.depends_on)
+                            ? step.depends_on
+                            : [];
+                    adj.set(sid, deps.filter((d) => validIds.has(d) && d !== sid));
+                }
+                const WHITE = 0, GRAY = 1, BLACK = 2;
+                const color = new Map();
+                for (const id of validIds)
+                    color.set(id, WHITE);
+                const parent = new Map();
+                function dfs(node) {
+                    color.set(node, GRAY);
+                    for (const dep of adj.get(node) ?? []) {
+                        if (color.get(dep) === GRAY) {
+                            // Back edge found — reconstruct cycle path
+                            const cycle = [dep, node];
+                            let cur = node;
+                            while (parent.has(cur) && parent.get(cur) !== null && parent.get(cur) !== dep) {
+                                cur = parent.get(cur);
+                                cycle.push(cur);
+                            }
+                            cycle.push(dep);
+                            cycle.reverse();
+                            return cycle;
+                        }
+                        if (color.get(dep) === WHITE) {
+                            parent.set(dep, node);
+                            const result = dfs(dep);
+                            if (result)
+                                return result;
+                        }
+                    }
+                    color.set(node, BLACK);
+                    return null;
+                }
+                for (const id of validIds) {
+                    if (color.get(id) === WHITE) {
+                        parent.set(id, null);
+                        const cycle = dfs(id);
+                        if (cycle) {
+                            errors.push(`Cycle detected: ${cycle.join(" → ")}`);
+                            break; // One cycle error is enough
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ─── Loading ─────────────────────────────────────────────────────────────
+/**
+ * Load and validate a YAML workflow definition from the filesystem.
+ *
+ * Reads `<defsDir>/<name>.yaml`, parses YAML, validates the V1 schema,
+ * and converts snake_case YAML keys to camelCase TypeScript types.
+ *
+ * @param defsDir — directory containing definition YAML files
+ * @param name — definition filename without extension
+ * @returns Parsed and validated WorkflowDefinition
+ * @throws Error if file is missing, YAML is malformed, or schema is invalid
+ */
+export function loadDefinition(defsDir, name) {
+    const filePath = join(defsDir, `${name}.yaml`);
+    if (!existsSync(filePath)) {
+        throw new Error(`Definition file not found: ${filePath}`);
+    }
+    const raw = readFileSync(filePath, "utf-8");
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`Failed to parse YAML in ${filePath}: ${msg}`);
+    }
+    const { valid, errors } = validateDefinition(parsed);
+    if (!valid) {
+        throw new Error(`Invalid workflow definition in ${filePath}:\n  - ${errors.join("\n  - ")}`);
+    }
+    // Convert snake_case YAML → camelCase TypeScript
+    const yamlDef = parsed;
+    const yamlSteps = yamlDef.steps;
+    return {
+        version: yamlDef.version,
+        name: yamlDef.name,
+        description: typeof yamlDef.description === "string" ? yamlDef.description : undefined,
+        params: yamlDef.params != null && typeof yamlDef.params === "object"
+            ? Object.fromEntries(Object.entries(yamlDef.params).map(([k, v]) => [k, String(v)]))
+            : undefined,
+        steps: yamlSteps.map((s) => ({
+            id: s.id,
+            name: s.name,
+            prompt: s.prompt,
+            requires: Array.isArray(s.requires)
+                ? s.requires
+                : Array.isArray(s.depends_on)
+                    ? s.depends_on
+                    : [],
+            produces: Array.isArray(s.produces) ? s.produces : [],
+            contextFrom: Array.isArray(s.context_from) ? s.context_from : undefined,
+            verify: s.verify,
+            iterate: (s.iterate != null && typeof s.iterate === "object")
+                ? s.iterate
+                : undefined,
+        })),
+    };
+}
+// ─── Parameter Substitution ──────────────────────────────────────────────
+/** Regex matching `{{key}}` placeholders — captures the key name. */
+const PARAM_PATTERN = /\{\{(\w+)\}\}/g;
+/**
+ * Replace `{{key}}` placeholders in a single prompt string.
+ *
+ * Exported for use by the engine on iteration-instance prompts that live
+ * in GRAPH.yaml (outside the definition's step list).
+ *
+ * @throws Error if any merged param value contains `..` (path-traversal guard)
+ */
+export function substitutePromptString(prompt, merged) {
+    return prompt.replace(PARAM_PATTERN, (match, key) => {
+        const value = merged[key];
+        return value !== undefined ? value : match;
+    });
+}
+/**
+ * Replace `{{key}}` placeholders in all step prompts with param values.
+ *
+ * Merge order: `definition.params` (defaults) ← `overrides` (CLI wins).
+ * Returns a **new** WorkflowDefinition — the input is never mutated.
+ *
+ * @throws Error if any param value contains `..` (path-traversal guard)
+ * @throws Error if any `{{key}}` remains unresolved after substitution
+ */
+export function substituteParams(definition, overrides) {
+    const merged = {
+        ...(definition.params ?? {}),
+        ...(overrides ?? {}),
+    };
+    // Path-traversal guard: reject any value containing ".."
+    for (const [key, value] of Object.entries(merged)) {
+        if (value.includes("..")) {
+            throw new Error(`Parameter "${key}" contains disallowed '..' (path traversal): ${value}`);
+        }
+    }
+    // Substitute in each step prompt
+    const substitutedSteps = definition.steps.map((step) => ({
+        ...step,
+        prompt: substitutePromptString(step.prompt, merged),
+    }));
+    // Check for unresolved placeholders
+    const unresolved = new Set();
+    for (const step of substitutedSteps) {
+        let m;
+        const re = new RegExp(PARAM_PATTERN.source, "g");
+        while ((m = re.exec(step.prompt)) !== null) {
+            unresolved.add(m[1]);
+        }
+    }
+    if (unresolved.size > 0) {
+        const keys = [...unresolved].sort().join(", ");
+        throw new Error(`Unresolved parameter(s) in step prompts: ${keys}`);
+    }
+    return {
+        ...definition,
+        steps: substitutedSteps,
+    };
+}