gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.1df898f

package/dist/resources/extensions/gsd/repo-identity.js

@@ -7,7 +7,7 @@
  */
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
@@ -247,14 +247,52 @@ export function externalProjectsRoot() {
     const base = process.env.GSD_STATE_DIR || gsdHome;
     return join(base, "projects");
 }
+// ─── Numbered Variant Cleanup ────────────────────────────────────────────────
+/**
+ * macOS collision pattern: `.gsd 2`, `.gsd 3`, `.gsd 4`, etc.
+ *
+ * When `symlinkSync` (or Finder) tries to create `.gsd` but a real directory
+ * already exists at that path, macOS APFS silently renames the new entry to
+ * `.gsd 2`, then `.gsd 3`, and so on. These numbered variants confuse GSD
+ * because the canonical `.gsd` path no longer resolves to the external state
+ * directory, making tracked planning files appear deleted.
+ *
+ * This helper scans the project root for entries matching `.gsd <digits>` and
+ * removes them. It is called early in `ensureGsdSymlink()` so that the
+ * canonical `.gsd` path is always the one in use.
+ */
+const GSD_NUMBERED_VARIANT_RE = /^\.gsd \d+$/;
+export function cleanNumberedGsdVariants(projectPath) {
+    const removed = [];
+    try {
+        const entries = readdirSync(projectPath);
+        for (const entry of entries) {
+            if (GSD_NUMBERED_VARIANT_RE.test(entry)) {
+                const fullPath = join(projectPath, entry);
+                try {
+                    rmSync(fullPath, { recursive: true, force: true });
+                    removed.push(entry);
+                }
+                catch {
+                    // Best-effort: if removal fails (e.g. permissions), continue with next
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal: readdir failure should not block symlink creation
+    }
+    return removed;
+}
 // ─── Symlink Management ─────────────────────────────────────────────────────
 /**
  * Ensure the `<project>/.gsd` symlink points to the external state directory.
  *
- * 1. mkdir -p the external dir
- * 2. If `<project>/.gsd` doesn't exist → create symlink
- * 3. If `<project>/.gsd` is already the correct symlink → no-op
- * 4. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
+ * 1. Clean up any macOS numbered collision variants (`.gsd 2`, `.gsd 3`, etc.)
+ * 2. mkdir -p the external dir
+ * 3. If `<project>/.gsd` doesn't exist → create symlink
+ * 4. If `<project>/.gsd` is already the correct symlink → no-op
+ * 5. If `<project>/.gsd` is a real directory → return as-is (migration handles later)
  *
  * Returns the resolved external path.
  */
@@ -270,6 +308,9 @@ export function ensureGsdSymlink(projectPath) {
     if (localGsdNormalized === gsdHomePath) {
         return localGsd;
     }
+    // Clean up macOS numbered collision variants (.gsd 2, .gsd 3, etc.) before
+    // any existence checks — otherwise they accumulate and confuse state (#2205).
+    cleanNumberedGsdVariants(projectPath);
     // Ensure external directory exists
     mkdirSync(externalPath, { recursive: true });
     // Write repo metadata once so cleanup commands can identify this directory later.

package/dist/resources/extensions/gsd/run-manager.js

@@ -0,0 +1,134 @@
+/**
+ * run-manager.ts — Create and list isolated workflow run directories.
+ *
+ * Each run lives under `.gsd/workflow-runs/<name>/<timestamp>/` and contains:
+ * - DEFINITION.yaml — frozen snapshot of the workflow definition at run-creation time
+ * - GRAPH.yaml — initialized step graph with all steps pending
+ * - PARAMS.json — (optional) parameter overrides used for this run
+ *
+ * Observability:
+ * - All run state is on disk in human-readable YAML/JSON — inspectable with cat/less.
+ * - `listRuns()` returns structured metadata including step counts and overall status.
+ * - Timestamp directory names are filesystem-safe (ISO with hyphens replacing colons).
+ * - Errors include the full path context for diagnosis.
+ */
+import { mkdirSync, writeFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { loadDefinition, substituteParams } from "./definition-loader.js";
+import { initializeGraph, writeGraph, readGraph } from "./graph.js";
+// ─── Constants ───────────────────────────────────────────────────────────
+const RUNS_DIR = "workflow-runs";
+const DEFS_DIR = "workflow-defs";
+// ─── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Generate a filesystem-safe timestamp: `YYYY-MM-DDTHH-MM-SS`.
+ * Replaces colons with hyphens so the string is safe as a directory name
+ * on all platforms (Windows forbids colons in paths).
+ */
+function makeTimestamp(date = new Date()) {
+    return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "");
+}
+/**
+ * Derive overall status from a graph's step statuses.
+ */
+function deriveStatus(graph) {
+    const hasActive = graph.steps.some((s) => s.status === "active");
+    const allDone = graph.steps.every((s) => s.status === "complete" || s.status === "expanded");
+    if (allDone)
+        return "complete";
+    if (hasActive)
+        return "running";
+    return "pending";
+}
+// ─── Public API ──────────────────────────────────────────────────────────
+/**
+ * Create a new isolated run directory for a workflow definition.
+ *
+ * 1. Loads the definition from `<basePath>/.gsd/workflow-defs/<defName>.yaml`
+ * 2. Applies parameter substitution if overrides are provided
+ * 3. Creates `<basePath>/.gsd/workflow-runs/<defName>/<timestamp>/`
+ * 4. Writes frozen DEFINITION.yaml, initialized GRAPH.yaml, and optional PARAMS.json
+ *
+ * @param basePath — project root directory
+ * @param defName — definition filename (without .yaml extension)
+ * @param overrides — optional parameter overrides (merged with definition defaults)
+ * @returns Full path to the created run directory
+ * @throws Error if the definition file doesn't exist or is invalid
+ */
+export function createRun(basePath, defName, overrides) {
+    const defsDir = join(basePath, ".gsd", DEFS_DIR);
+    // Load and validate the definition
+    const rawDef = loadDefinition(defsDir, defName);
+    // Apply parameter substitution if overrides provided
+    const def = overrides
+        ? substituteParams(rawDef, overrides)
+        : substituteParams(rawDef); // still resolve default params if any
+    // Create the run directory
+    const timestamp = makeTimestamp();
+    const runDir = join(basePath, ".gsd", RUNS_DIR, defName, timestamp);
+    mkdirSync(runDir, { recursive: true });
+    // Freeze the definition as DEFINITION.yaml
+    writeFileSync(join(runDir, "DEFINITION.yaml"), stringify(def), "utf-8");
+    // Initialize and write GRAPH.yaml
+    const graph = initializeGraph(def);
+    writeGraph(runDir, graph);
+    // Write PARAMS.json if overrides were provided
+    if (overrides && Object.keys(overrides).length > 0) {
+        writeFileSync(join(runDir, "PARAMS.json"), JSON.stringify(overrides, null, 2), "utf-8");
+    }
+    return runDir;
+}
+/**
+ * List existing workflow runs with metadata.
+ *
+ * Scans `<basePath>/.gsd/workflow-runs/` for run directories. Each run's
+ * GRAPH.yaml is read to derive step counts and overall status.
+ *
+ * @param basePath — project root directory
+ * @param defName — optional filter: only list runs for this definition name
+ * @returns Array of run metadata, sorted newest-first within each definition
+ */
+export function listRuns(basePath, defName) {
+    const runsRoot = join(basePath, ".gsd", RUNS_DIR);
+    if (!existsSync(runsRoot))
+        return [];
+    const results = [];
+    // Get workflow name directories
+    const nameDirs = defName ? [defName] : readdirSync(runsRoot).filter((entry) => {
+        const full = join(runsRoot, entry);
+        return statSync(full).isDirectory();
+    });
+    for (const name of nameDirs) {
+        const nameDir = join(runsRoot, name);
+        if (!existsSync(nameDir))
+            continue;
+        const timestamps = readdirSync(nameDir).filter((entry) => {
+            const full = join(nameDir, entry);
+            return statSync(full).isDirectory();
+        });
+        // Sort newest-first (ISO strings sort lexicographically)
+        timestamps.sort().reverse();
+        for (const ts of timestamps) {
+            const runDir = join(nameDir, ts);
+            try {
+                const graph = readGraph(runDir);
+                const total = graph.steps.length;
+                const completed = graph.steps.filter((s) => s.status === "complete").length;
+                const pending = graph.steps.filter((s) => s.status === "pending").length;
+                const active = graph.steps.filter((s) => s.status === "active").length;
+                results.push({
+                    name,
+                    timestamp: ts,
+                    runDir,
+                    steps: { total, completed, pending, active },
+                    status: deriveStatus(graph),
+                });
+            }
+            catch {
+                // Skip runs with invalid/missing GRAPH.yaml
+            }
+        }
+    }
+    return results;
+}

package/dist/resources/extensions/gsd/service-tier.js

@@ -11,6 +11,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { saveFile } from "./files.js";
 import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, } from "./preferences.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+const SERVICE_TIER_SCOPE_NOTE = "Only affects gpt-5.4 models, regardless of provider.";
 // ─── Gating ──────────────────────────────────────────────────────────────────
 /**
  * Returns true when the given model ID supports OpenAI service tiers.
@@ -37,7 +38,7 @@ export function formatServiceTierStatus(tier) {
             "  /gsd fast flex   Set to flex (0.5x cost, slower)",
             "  /gsd fast off    Disable service tier",
             "",
-            "Only affects gpt-5.4 models.",
+            SERVICE_TIER_SCOPE_NOTE,
         ].join("\n");
     }
     const label = tier === "priority" ? "priority (2x cost, faster)" : "flex (0.5x cost, slower)";
@@ -49,9 +50,14 @@ export function formatServiceTierStatus(tier) {
         "  /gsd fast flex   Set to flex (0.5x cost, slower)",
         "  /gsd fast off    Disable service tier",
         "",
-        "Only affects gpt-5.4 models.",
+        SERVICE_TIER_SCOPE_NOTE,
     ].join("\n");
 }
+export function formatServiceTierFooterStatus(tier, modelId) {
+    if (!tier || !modelId || !supportsServiceTier(modelId))
+        return undefined;
+    return tier === "priority" ? "fast: ⚡ priority" : "fast: 💰 flex";
+}
 // ─── Icon Resolution ─────────────────────────────────────────────────────────
 /**
  * Returns the appropriate icon for the active service tier and model.
@@ -121,17 +127,20 @@ export async function handleFast(args, ctx) {
     }
     if (trimmed === "on") {
         await writeGlobalServiceTier(ctx, "priority");
-        ctx.ui.notify("Service tier set to priority (2x cost, faster responses). Only affects gpt-5.4 models.", "info");
+        ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus("priority", ctx.model?.id));
+        ctx.ui.notify("Service tier set to priority (2x cost, faster responses). Only affects gpt-5.4 models, regardless of provider.", "info");
         return;
     }
     if (trimmed === "off") {
         await writeGlobalServiceTier(ctx, undefined);
+        ctx.ui.setStatus("gsd-fast", undefined);
         ctx.ui.notify("Service tier disabled.", "info");
         return;
     }
     if (trimmed === "flex") {
         await writeGlobalServiceTier(ctx, "flex");
-        ctx.ui.notify("Service tier set to flex (0.5x cost, slower responses). Only affects gpt-5.4 models.", "info");
+        ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus("flex", ctx.model?.id));
+        ctx.ui.notify("Service tier set to flex (0.5x cost, slower responses). Only affects gpt-5.4 models, regardless of provider.", "info");
         return;
     }
     ctx.ui.notify("Usage: /gsd fast [on|off|flex|status]\n\n  on    Priority tier (2x cost, faster)\n  off   Disable service tier\n  flex  Flex tier (0.5x cost, slower)\n  status Show current setting", "warning");

package/dist/resources/extensions/gsd/session-lock.js

@@ -199,7 +199,7 @@ export function acquireSessionLock(basePath) {
                 // during a long LLM call — not a real takeover. Log and continue.
                 const elapsed = Date.now() - _lockAcquiredAt;
                 if (elapsed < 1_800_000) {
-                    process.stderr.write(`[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`);
+                    process.stderr.write(`[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`);
                     return; // Suppress false positive
                 }
                 // Past the stale window — check if the lock file still belongs to us before
@@ -252,7 +252,7 @@ export function acquireSessionLock(basePath) {
                         // on benign mtime drift (laptop sleep, heavy LLM event loop stalls).
                         const elapsed = Date.now() - _lockAcquiredAt;
                         if (elapsed < 1_800_000) {
-                            process.stderr.write(`[gsd] Lock heartbeat mismatch after ${Math.round(elapsed / 1000)}s — event loop stall, continuing.\n`);
+                            process.stderr.write(`[gsd] Lock heartbeat caught up after ${Math.round(elapsed / 1000)}s — long LLM call, no action needed.\n`);
                             return;
                         }
                         // Check PID ownership before declaring compromise (#1578)

package/dist/resources/extensions/gsd/workflow-engine.js

@@ -0,0 +1,7 @@
+/**
+ * workflow-engine.ts — WorkflowEngine interface.
+ *
+ * Defines the contract every engine implementation must satisfy.
+ * Imports only from the leaf-node engine-types.
+ */
+export {};

package/dist/resources/extensions/gsd/worktree-resolver.js

@@ -286,9 +286,9 @@ export class WorktreeResolver {
             });
             // Surface a clear, actionable error. The worktree and milestone branch are
             // intentionally preserved — nothing has been deleted. The user can retry
-            // /complete-milestone or merge manually once the underlying issue is fixed
+            // /gsd dispatch complete-milestone or merge manually once the underlying issue is fixed
             // (e.g. checkout to wrong branch, unresolved conflicts). (#1668)
-            ctx.notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry /complete-milestone or merge manually.`, "warning");
+            ctx.notify(`Milestone merge failed: ${msg}. Your worktree and milestone branch are preserved — retry /gsd dispatch complete-milestone or merge manually.`, "warning");
             // Clean up stale merge state left by failed squash-merge (#1389)
             try {
                 const gitDir = join(originalBase || this.s.basePath, ".git");

package/dist/resources/extensions/gsd/worktree.js

@@ -48,14 +48,14 @@ export function setActiveMilestoneId(basePath, milestoneId) {
  * record when the user starts from a different branch (#300). Always a no-op
  * if on a GSD slice branch.
  */
-export function captureIntegrationBranch(basePath, milestoneId, options) {
+export function captureIntegrationBranch(basePath, milestoneId) {
     // In a worktree, the base branch is implicit (worktree/<name>).
     // Writing it to META.json would leave stale metadata after merge back to main.
     if (detectWorktreeName(basePath))
         return;
     const svc = getService(basePath);
     const current = svc.getCurrentBranch();
-    writeIntegrationBranch(basePath, milestoneId, current, options);
+    writeIntegrationBranch(basePath, milestoneId, current);
 }
 // ─── Pure Utility Functions (unchanged) ────────────────────────────────────
 /**

package/dist/resources/extensions/mcp-client/index.js

@@ -108,7 +108,8 @@ async function getOrConnect(name, signal) {
         });
     }
     else if (config.transport === "http" && config.url) {
-        transport = new StreamableHTTPClientTransport(new URL(config.url));
+        const resolvedUrl = config.url.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+        transport = new StreamableHTTPClientTransport(new URL(resolvedUrl));
     }
     else {
         throw new Error(`Server "${name}" has unsupported transport: ${config.transport}`);

package/dist/resources/extensions/search-the-web/tool-search.js

@@ -259,9 +259,9 @@ export function registerSearchTool(pi) {
             // with brief interruptions every MAX_CONSECUTIVE_DUPES+1 calls.
             if (cacheKey === lastSearchKey) {
                 consecutiveDupeCount++;
-                if (consecutiveDupeCount >= MAX_CONSECUTIVE_DUPES) {
+                if (consecutiveDupeCount > MAX_CONSECUTIVE_DUPES) {
                     return {
-                        content: [{ type: "text", text: `⚠️ Search loop detected: the query "${params.query}" has been searched ${consecutiveDupeCount + 1} times consecutively with identical results. The information you need is already in the previous search results above. Stop searching and use those results to proceed with your task.` }],
+                        content: [{ type: "text", text: `⚠️ Search loop detected: the query "${params.query}" has been searched ${consecutiveDupeCount} times consecutively with identical results. The information you need is already in the previous search results above. Stop searching and use those results to proceed with your task.` }],
                         isError: true,
                         details: { errorKind: "search_loop", error: "Consecutive duplicate search detected" },
                     };
@@ -269,7 +269,7 @@ export function registerSearchTool(pi) {
             }
             else {
                 lastSearchKey = cacheKey;
-                consecutiveDupeCount = 0;
+                consecutiveDupeCount = 1;
             }
             const cached = searchCache.get(cacheKey);
             if (cached) {

package/dist/resources/skills/create-workflow/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: create-workflow
+description: Conversational guide for creating valid YAML workflow definitions. Use when asked to "create a workflow", "new workflow definition", "build a workflow", "workflow YAML", "define workflow steps", or "workflow from template".
+---
+
+<essential_principles>
+You are a workflow definition author. You help users create valid V1 YAML workflow definitions that the GSD workflow engine can execute.
+
+**V1 Schema Basics:**
+
+- Every definition requires `version: 1`, a non-empty `name`, and at least one step in `steps[]`.
+- Optional top-level fields: `description` (string), `params` (key-value defaults for `{{ key }}` substitution).
+- Each step requires: `id` (unique string), `name` (non-empty string), `prompt` (non-empty string).
+- Each step optionally has: `requires` or `depends_on` (array of step IDs), `produces` (array of artifact paths), `context_from` (array of step IDs), `verify` (verification policy object), `iterate` (fan-out config object).
+- YAML uses **snake_case** keys: `depends_on`, `context_from`. The engine converts to camelCase internally.
+
+**Validation Rules:**
+
+- Step IDs must be unique across the workflow.
+- Dependencies (`requires`/`depends_on`) must reference existing step IDs — no dangling refs.
+- A step cannot depend on itself.
+- The dependency graph must be acyclic (no circular dependencies).
+- `produces` paths must not contain `..` (path traversal rejected).
+- `iterate.source` must not contain `..` (path traversal rejected).
+- `iterate.pattern` must be a valid regex with at least one capture group.
+
+**Four Verification Policies:**
+
+1. `content-heuristic` — Checks artifact content. Optional: `minSize` (number), `pattern` (string).
+2. `shell-command` — Runs a shell command. Required: `command` (non-empty string).
+3. `prompt-verify` — Asks an LLM to verify. Required: `prompt` (non-empty string).
+4. `human-review` — Pauses for human approval. No extra fields required.
+
+**Parameter Substitution:**
+
+- Define defaults in top-level `params: { key: "default_value" }`.
+- Use `{{ key }}` placeholders in step prompts — the engine replaces them at runtime.
+- CLI overrides take precedence over definition defaults.
+- Parameter values must not contain `..` (path traversal guard).
+- Any unresolved `{{ key }}` after substitution causes an error.
+
+**Path Traversal Guard:**
+
+- The engine rejects any `produces` path or `iterate.source` containing `..`.
+- Parameter values are also checked for `..` during substitution.
+
+**Output Location:**
+
+- Finished definitions go in `.gsd/workflow-defs/<name>.yaml`.
+- After writing, tell the user to validate with `/gsd workflow validate <name>`.
+</essential_principles>
+
+<routing>
+Determine the user's intent and route to the appropriate workflow:
+
+**"I want to create a workflow from scratch" / "new workflow" / "build a workflow":**
+→ Read `workflows/create-from-scratch.md` and follow it.
+
+**"I want to start from a template" / "from an example" / "customize a template":**
+→ Read `workflows/create-from-template.md` and follow it.
+
+**"Help me understand the schema" / "what fields are available?":**
+→ Read `references/yaml-schema-v1.md` and explain the relevant parts.
+
+**"How does verification work?" / "verify policies":**
+→ Read `references/verification-policies.md` and explain.
+
+**"How do I use context_from / iterate / params?":**
+→ Read `references/feature-patterns.md` and explain the relevant feature.
+
+**If intent is unclear, ask one clarifying question:**
+- "Do you want to create a workflow from scratch, or start from an existing template?"
+- Then route based on the answer.
+</routing>
+
+<reference_index>
+Read these files when you need detailed schema knowledge during workflow authoring:
+
+- `references/yaml-schema-v1.md` — Complete field-by-field V1 schema reference. Read when you need to explain any field's type, constraints, or defaults.
+- `references/verification-policies.md` — All four verify policies with complete YAML examples. Read when helping the user choose or configure verification for a step.
+- `references/feature-patterns.md` — Usage patterns for `context_from`, `iterate`, and `params` with complete YAML examples. Read when the user wants context chaining, fan-out iteration, or parameterized workflows.
+</reference_index>
+
+<templates_index>
+Available templates in `templates/`:
+
+- `workflow-definition.yaml` — Blank scaffold with all fields shown as comments. Copy and fill for a quick start.
+- `blog-post-pipeline.yaml` — Linear chain with params and content-heuristic verification.
+- `code-audit.yaml` — Iterate-based fan-out with shell-command verification.
+- `release-checklist.yaml` — Diamond dependency graph with human-review verification.
+</templates_index>
+
+<output_conventions>
+When assembling the final YAML:
+
+1. Use 2-space indentation consistently.
+2. Quote string values that contain special YAML characters (`:`, `{`, `}`, `[`, `]`, `#`).
+3. Always include `version: 1` as the first field.
+4. Order top-level fields: `version`, `name`, `description`, `params`, `steps`.
+5. Order step fields: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
+6. Write the file to `.gsd/workflow-defs/<name>.yaml`.
+7. After writing, tell the user: "Run `/gsd workflow validate <name>` to check the definition."
+</output_conventions>

package/dist/resources/skills/create-workflow/references/feature-patterns.md

@@ -0,0 +1,128 @@
+<feature_patterns>
+Advanced workflow features: `context_from`, `iterate`, and `params`. Each section includes a complete YAML example.
+
+**Feature 1: `context_from` — Context Chaining**
+
+Injects artifacts from prior steps as context when the current step runs. The value is an array of step IDs.
+
+```yaml
+version: 1
+name: research-and-synthesize
+steps:
+  - id: gather
+    name: Gather sources
+    prompt: "Find and summarize the top 5 sources on the topic."
+    produces:
+      - sources.md
+
+  - id: analyze
+    name: Analyze sources
+    prompt: "Analyze the gathered sources for key themes."
+    requires:
+      - gather
+    context_from:
+      - gather
+    produces:
+      - analysis.md
+
+  - id: synthesize
+    name: Write synthesis
+    prompt: "Synthesize the analysis into a coherent report."
+    requires:
+      - analyze
+    context_from:
+      - gather
+      - analyze
+    produces:
+      - report.md
+```
+
+How it works:
+- `context_from: [gather]` means the engine includes artifacts from the `gather` step when executing `analyze`.
+- You can reference multiple prior steps: `context_from: [gather, analyze]`.
+- The referenced steps must exist in the workflow (they are validated as step IDs).
+- `context_from` does not imply a dependency — if you want the step to wait, also add the ID to `requires`.
+
+**Feature 2: `iterate` — Fan-Out Iteration**
+
+Reads an artifact, applies a regex pattern, and creates one sub-execution per match. The capture group extracts the iteration variable.
+
+```yaml
+version: 1
+name: file-by-file-review
+steps:
+  - id: inventory
+    name: List files to review
+    prompt: "List all TypeScript files in src/ that need review, one per line."
+    produces:
+      - file-list.txt
+
+  - id: review
+    name: Review each file
+    prompt: "Review the file for code quality issues."
+    requires:
+      - inventory
+    iterate:
+      source: file-list.txt
+      pattern: "^(.+\\.ts)$"
+    produces:
+      - reviews/
+```
+
+How it works:
+- `source`: Path to an artifact (relative to the run directory). Must not contain `..`.
+- `pattern`: A regex string applied with the global flag. Must contain at least one capture group `(...)`.
+- The engine reads the source artifact, applies the pattern, and creates one execution per match.
+- Each capture group match becomes available as the iteration variable.
+- The regex is validated at definition-load time — invalid regex or missing capture groups are rejected.
+
+Pattern requirements:
+- Must be a valid JavaScript regex.
+- Must contain at least one non-lookahead capture group: `(...)` not `(?:...)`.
+- Example valid patterns: `^(.+)$`, `- (.+\.ts)`, `\[(.+?)\]`.
+
+**Feature 3: `params` — Parameterized Workflows**
+
+Define default parameter values at the top level. Use `{{ key }}` placeholders in step prompts. CLI overrides take precedence.
+
+```yaml
+version: 1
+name: blog-post
+description: Generate a blog post on a configurable topic.
+params:
+  topic: "AI in healthcare"
+  audience: "technical professionals"
+  word_count: "1500"
+steps:
+  - id: outline
+    name: Create outline
+    prompt: "Create a detailed outline for a blog post about {{ topic }} targeting {{ audience }}."
+    produces:
+      - outline.md
+
+  - id: draft
+    name: Write draft
+    prompt: "Write a {{ word_count }}-word blog post about {{ topic }} for {{ audience }} based on the outline."
+    requires:
+      - outline
+    context_from:
+      - outline
+    produces:
+      - draft.md
+    verify:
+      policy: content-heuristic
+      minSize: 500
+```
+
+How it works:
+- `params` is a top-level object mapping string keys to string default values.
+- `{{ key }}` in any step prompt is replaced with the corresponding param value.
+- Merge order: definition `params` (defaults) ← CLI overrides (win).
+- After substitution, any remaining `{{ key }}` that has no value causes an error — all placeholders must resolve.
+- Parameter values must not contain `..` (path traversal guard).
+- Keys in `{{ }}` match `\w+` (letters, digits, underscore).
+
+Common usage:
+- Make workflows reusable across different topics, projects, or configurations.
+- Users override defaults at run time: `/gsd workflow run blog-post topic="Rust performance"`.
+</feature_patterns>