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

package/src/resources/extensions/gsd/tests/tool-call-loop-guard.test.ts

@@ -118,6 +118,51 @@ console.log('\n── Loop guard: arg order is normalized ──');
   assertEq(getToolCallLoopCount(), 2, 'Should detect as same call regardless of key order');
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Nested/array arguments produce distinct hashes
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: nested args are not stripped ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // Simulate ask_user_questions-style calls with different nested content
+  for (let i = 1; i <= 5; i++) {
+    const result = checkToolCallLoop('ask_user_questions', {
+      questions: [{ id: `q${i}`, question: `Question ${i}?` }],
+    });
+    assertTrue(result.block === false, `Nested call ${i} with unique content should be allowed`);
+    assertEq(getToolCallLoopCount(), 1, `Each unique nested call should reset count to 1`);
+  }
+
+  // Truly identical nested calls should still be detected
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 4; i++) {
+    checkToolCallLoop('ask_user_questions', {
+      questions: [{ id: 'same', question: 'Same?' }],
+    });
+  }
+  const blocked = checkToolCallLoop('ask_user_questions', {
+    questions: [{ id: 'same', question: 'Same?' }],
+  });
+  assertTrue(blocked.block === true, 'Identical nested calls should still be blocked');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Nested object key order is normalized
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: nested key order is normalized ──');
+
+{
+  resetToolCallLoopGuard();
+
+  checkToolCallLoop('tool', { outer: { b: 2, a: 1 } });
+  const result = checkToolCallLoop('tool', { outer: { a: 1, b: 2 } });
+  assertEq(getToolCallLoopCount(), 2, 'Same nested args in different key order should match');
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 
 report();

package/src/resources/extensions/gsd/tests/worktree-manager.test.ts

@@ -1,4 +1,6 @@
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execSync } from "node:child_process";
@@ -13,82 +15,42 @@ import {
   worktreeBranchName,
   worktreePath,
 } from "../worktree-manager.ts";
-import { createTestContext } from './test-helpers.ts';
 
-const { assertEq, assertTrue, report } = createTestContext();
 function run(command: string, cwd: string): string {
   return execSync(command, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
 }
 
-// Set up a test repo
-const base = mkdtempSync(join(tmpdir(), "gsd-worktree-mgr-test-"));
-run("git init -b main", base);
-run('git config user.name "Pi Test"', base);
-run('git config user.email "pi@example.com"', base);
-
-// Create initial project structure
-mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
-writeFileSync(join(base, "README.md"), "# Test Project\n", "utf-8");
-writeFileSync(
-  join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
-  "# M001: Demo\n\n## Slices\n- [ ] **S01: First** `risk:low` `depends:[]`\n  > After this: it works\n",
-  "utf-8",
-);
-run("git add .", base);
-run('git commit -m "chore: init"', base);
-
-async function main(): Promise<void> {
-  console.log("\n=== worktreeBranchName ===");
-  assertEq(worktreeBranchName("feature-x"), "worktree/feature-x", "branch name format");
-
-  console.log("\n=== createWorktree ===");
-  const info = createWorktree(base, "feature-x");
-  assertTrue(info.name === "feature-x", "name matches");
-  assertTrue(info.branch === "worktree/feature-x", "branch matches");
-  assertTrue(info.exists, "worktree exists");
-  assertTrue(existsSync(info.path), "worktree path exists on disk");
-  assertTrue(existsSync(join(info.path, "README.md")), "README.md copied to worktree");
-  assertTrue(existsSync(join(info.path, ".gsd", "milestones", "M001", "M001-ROADMAP.md")), ".gsd files copied");
-
-  // Branch was created
-  const branches = run("git branch", base);
-  assertTrue(branches.includes("worktree/feature-x"), "branch was created");
-
-  console.log("\n=== createWorktree — duplicate ===");
-  let duplicateError = "";
-  try {
-    createWorktree(base, "feature-x");
-  } catch (e) {
-    duplicateError = (e as Error).message;
-  }
-  assertTrue(duplicateError.includes("already exists"), "duplicate creation fails");
+function makeBaseRepo(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-wt-test-"));
+  run("git init -b main", base);
+  run('git config user.name "Test User"', base);
+  run('git config user.email "test@example.com"', base);
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  writeFileSync(join(base, "README.md"), "# Test Project\n", "utf-8");
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+    "# M001: Demo\n\n## Slices\n- [ ] **S01: First** `risk:low` `depends:[]`\n  > After this: it works\n",
+    "utf-8",
+  );
+  run("git add .", base);
+  run('git commit -m "chore: init"', base);
+  return base;
+}
 
-  console.log("\n=== createWorktree — invalid name ===");
-  let invalidError = "";
-  try {
-    createWorktree(base, "bad name!");
-  } catch (e) {
-    invalidError = (e as Error).message;
-  }
-  assertTrue(invalidError.includes("Invalid worktree name"), "invalid name rejected");
-
-  console.log("\n=== listWorktrees ===");
-  const list = listWorktrees(base);
-  assertEq(list.length, 1, "one worktree listed");
-  assertEq(list[0]!.name, "feature-x", "correct name");
-  assertEq(list[0]!.branch, "worktree/feature-x", "correct branch");
-  assertTrue(list[0]!.exists, "exists flag is true");
-
-  console.log("\n=== make changes in worktree ===");
-  const wtPath = worktreePath(base, "feature-x");
-  // Add a new GSD artifact in the worktree
+function makeRepoWithWorktree(worktreeName: string): { base: string; wtPath: string } {
+  const base = makeBaseRepo();
+  createWorktree(base, worktreeName);
+  return { base, wtPath: worktreePath(base, worktreeName) };
+}
+
+function makeRepoWithChanges(worktreeName: string): { base: string; wtPath: string } {
+  const { base, wtPath } = makeRepoWithWorktree(worktreeName);
   mkdirSync(join(wtPath, ".gsd", "milestones", "M002"), { recursive: true });
   writeFileSync(
     join(wtPath, ".gsd", "milestones", "M002", "M002-ROADMAP.md"),
     "# M002: New Feature\n\n## Slices\n- [ ] **S01: Setup** `risk:low` `depends:[]`\n  > After this: new feature ready\n",
     "utf-8",
   );
-  // Modify an existing artifact
   writeFileSync(
     join(wtPath, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
     "# M001: Demo (updated)\n\n## Slices\n- [x] **S01: First** `risk:low` `depends:[]`\n  > Done\n",
@@ -96,46 +58,174 @@ async function main(): Promise<void> {
   );
   run("git add .", wtPath);
   run('git commit -m "feat: add M002 and update M001"', wtPath);
-
-  console.log("\n=== diffWorktreeGSD ===");
-  const diff = diffWorktreeGSD(base, "feature-x");
-  assertTrue(diff.added.length > 0, "has added files");
-  assertTrue(diff.added.some(f => f.includes("M002")), "M002 roadmap is in added");
-  assertTrue(diff.modified.length > 0, "has modified files");
-  assertTrue(diff.modified.some(f => f.includes("M001")), "M001 roadmap is in modified");
-  assertEq(diff.removed.length, 0, "no removed files");
-
-  console.log("\n=== getWorktreeGSDDiff ===");
-  const fullDiff = getWorktreeGSDDiff(base, "feature-x");
-  assertTrue(fullDiff.includes("M002"), "full diff mentions M002");
-  assertTrue(fullDiff.includes("updated"), "full diff mentions update");
-
-  console.log("\n=== getWorktreeLog ===");
-  const log = getWorktreeLog(base, "feature-x");
-  assertTrue(log.includes("add M002"), "log shows commit message");
-
-  console.log("\n=== removeWorktree ===");
-  removeWorktree(base, "feature-x", { deleteBranch: true });
-  assertTrue(!existsSync(wtPath), "worktree directory removed");
-  const branchesAfter = run("git branch", base);
-  assertTrue(!branchesAfter.includes("worktree/feature-x"), "branch deleted");
-
-  console.log("\n=== listWorktrees after removal ===");
-  const listAfter = listWorktrees(base);
-  assertEq(listAfter.length, 0, "no worktrees after removal");
-
-  console.log("\n=== removeWorktree — already gone ===");
-  // Should not throw
-  removeWorktree(base, "feature-x", { deleteBranch: true });
-  assertTrue(true, "removeWorktree on missing worktree does not throw");
-
-  // Cleanup
-  rmSync(base, { recursive: true, force: true });
-
-  report();
+  return { base, wtPath };
 }
 
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
+// ─── worktreeBranchName ───────────────────────────────────────────────────────
+
+test("worktreeBranchName formats branch name", () => {
+  assert.strictEqual(
+    worktreeBranchName("feature-x"),
+    "worktree/feature-x",
+    "should prefix with worktree/",
+  );
+});
+
+// ─── createWorktree ───────────────────────────────────────────────────────────
+
+test("createWorktree creates worktree with correct metadata", () => {
+  const base = makeBaseRepo();
+  try {
+    const info = createWorktree(base, "feature-x");
+    assert.strictEqual(info.name, "feature-x", "name should match");
+    assert.strictEqual(info.branch, "worktree/feature-x", "branch should be prefixed");
+    assert.ok(info.exists, "exists flag should be true");
+    assert.ok(existsSync(info.path), "worktree path should exist on disk");
+    assert.ok(existsSync(join(info.path, "README.md")), "README.md should be in worktree");
+    assert.ok(
+      existsSync(join(info.path, ".gsd", "milestones", "M001", "M001-ROADMAP.md")),
+      ".gsd files should be in worktree",
+    );
+    const branches = run("git branch", base);
+    assert.ok(branches.includes("worktree/feature-x"), "branch should be created in base repo");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("createWorktree rejects duplicate name", () => {
+  const { base } = makeRepoWithWorktree("feature-x");
+  try {
+    assert.throws(
+      () => createWorktree(base, "feature-x"),
+      (err: Error) => {
+        assert.ok(
+          err.message.includes("already exists"),
+          `expected "already exists" in error, got: ${err.message}`,
+        );
+        return true;
+      },
+      "should throw on duplicate worktree name",
+    );
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("createWorktree rejects invalid name", () => {
+  const base = makeBaseRepo();
+  try {
+    assert.throws(
+      () => createWorktree(base, "bad name!"),
+      (err: Error) => {
+        assert.ok(
+          err.message.includes("Invalid worktree name"),
+          `expected "Invalid worktree name" in error, got: ${err.message}`,
+        );
+        return true;
+      },
+      "should throw on invalid worktree name",
+    );
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ─── listWorktrees ────────────────────────────────────────────────────────────
+
+test("listWorktrees returns active worktrees", () => {
+  const { base } = makeRepoWithWorktree("feature-x");
+  try {
+    const list = listWorktrees(base);
+    assert.strictEqual(list.length, 1, "should list exactly one worktree");
+    assert.strictEqual(list[0]!.name, "feature-x", "name should match");
+    assert.strictEqual(list[0]!.branch, "worktree/feature-x", "branch should match");
+    assert.ok(list[0]!.exists, "exists flag should be true");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("listWorktrees returns empty after removal", () => {
+  const { base } = makeRepoWithWorktree("feature-x");
+  try {
+    removeWorktree(base, "feature-x");
+    const list = listWorktrees(base);
+    assert.strictEqual(list.length, 0, "should have no worktrees after removal");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ─── diffWorktreeGSD ─────────────────────────────────────────────────────────
+
+test("diffWorktreeGSD detects added and modified GSD files", () => {
+  const { base } = makeRepoWithChanges("feature-x");
+  try {
+    const diff = diffWorktreeGSD(base, "feature-x");
+    assert.ok(diff.added.length > 0, "should have added files");
+    assert.ok(
+      diff.added.some((f) => f.includes("M002")),
+      "M002 roadmap should be in added files",
+    );
+    assert.ok(diff.modified.length > 0, "should have modified files");
+    assert.ok(
+      diff.modified.some((f) => f.includes("M001")),
+      "M001 roadmap should be in modified files",
+    );
+    assert.strictEqual(diff.removed.length, 0, "should have no removed files");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ─── getWorktreeGSDDiff ───────────────────────────────────────────────────────
+
+test("getWorktreeGSDDiff returns patch content", () => {
+  const { base } = makeRepoWithChanges("feature-x");
+  try {
+    const fullDiff = getWorktreeGSDDiff(base, "feature-x");
+    assert.ok(fullDiff.includes("M002"), "diff should mention M002");
+    assert.ok(fullDiff.includes("updated"), "diff should mention the update");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ─── getWorktreeLog ───────────────────────────────────────────────────────────
+
+test("getWorktreeLog shows commits", () => {
+  const { base } = makeRepoWithChanges("feature-x");
+  try {
+    const log = getWorktreeLog(base, "feature-x");
+    assert.ok(log.includes("add M002"), "log should include the commit message");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ─── removeWorktree ───────────────────────────────────────────────────────────
+
+test("removeWorktree removes directory and branch", () => {
+  const { base, wtPath } = makeRepoWithWorktree("feature-x");
+  try {
+    removeWorktree(base, "feature-x", { deleteBranch: true });
+    assert.ok(!existsSync(wtPath), "worktree directory should be gone");
+    const branches = run("git branch", base);
+    assert.ok(!branches.includes("worktree/feature-x"), "branch should be deleted");
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("removeWorktree on missing worktree does not throw", () => {
+  const base = makeBaseRepo();
+  try {
+    assert.doesNotThrow(
+      () => removeWorktree(base, "nonexistent"),
+      "should not throw when worktree does not exist",
+    );
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
 });

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

@@ -0,0 +1,38 @@
+/**
+ * workflow-engine.ts — WorkflowEngine interface.
+ *
+ * Defines the contract every engine implementation must satisfy.
+ * Imports only from the leaf-node engine-types.
+ */
+
+import type {
+  EngineState,
+  EngineDispatchAction,
+  CompletedStep,
+  ReconcileResult,
+  DisplayMetadata,
+} from "./engine-types.js";
+
+/** A pluggable workflow engine that drives the auto-loop. */
+export interface WorkflowEngine {
+  /** Unique identifier for this engine (e.g. "dev", "custom"). */
+  readonly engineId: string;
+
+  /** Derive the current engine state from the project on disk. */
+  deriveState(basePath: string): Promise<EngineState>;
+
+  /** Decide what the loop should do next given current state. */
+  resolveDispatch(
+    state: EngineState,
+    context: { basePath: string },
+  ): Promise<EngineDispatchAction>;
+
+  /** Reconcile state after a step has been executed. */
+  reconcile(
+    state: EngineState,
+    completedStep: CompletedStep,
+  ): Promise<ReconcileResult>;
+
+  /** Return UI-facing metadata for progress display. */
+  getDisplayMetadata(state: EngineState): DisplayMetadata;
+}

package/src/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/src/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>