gsd-pi 2.41.0 → 2.42.0-dev.1df898f

package/src/resources/extensions/gsd/tests/rule-registry.test.ts

@@ -0,0 +1,413 @@
+// GSD Extension — Rule Registry Tests
+//
+// Tests the RuleRegistry class, UnifiedRule types, singleton accessors,
+// and evaluation methods using mock rules.
+
+import { test, describe, beforeEach } from "node:test";
+import { createTestContext } from "./test-helpers.ts";
+import {
+  RuleRegistry,
+  getRegistry,
+  setRegistry,
+  initRegistry,
+  resetRegistry,
+  convertDispatchRules,
+  getOrCreateRegistry,
+} from "../rule-registry.ts";
+import type { UnifiedRule } from "../rule-types.ts";
+import type { DispatchAction, DispatchContext } from "../auto-dispatch.ts";
+import { DISPATCH_RULES, getDispatchRuleNames } from "../auto-dispatch.ts";
+import type { GSDState } from "../types.ts";
+
+// ─── Mock Rule Factories ──────────────────────────────────────────────────
+
+function mockDispatchRule(name: string, matchPhase: string): UnifiedRule {
+  return {
+    name,
+    when: "dispatch",
+    evaluation: "first-match",
+    where: async (ctx: DispatchContext): Promise<DispatchAction | null> => {
+      if (ctx.state.phase === matchPhase) {
+        return {
+          action: "dispatch",
+          unitType: `test-${matchPhase}`,
+          unitId: "test-id",
+          prompt: `Prompt for ${matchPhase}`,
+        };
+      }
+      return null;
+    },
+    then: () => {},
+    description: `Mock rule for ${matchPhase}`,
+  };
+}
+
+function makeContext(phase: string): DispatchContext {
+  return {
+    basePath: "/tmp/test",
+    mid: "M001",
+    midTitle: "Test Milestone",
+    state: {
+      phase: phase as any,
+      activeMilestone: { id: "M001", title: "Test" },
+      activeSlice: null,
+      activeTask: null,
+      recentDecisions: [],
+      blockers: [],
+      nextAction: "",
+      registry: [],
+    },
+    prefs: undefined,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+describe("RuleRegistry", () => {
+  const { assertEq, assertTrue } = createTestContext();
+
+  beforeEach(() => {
+    resetRegistry();
+  });
+
+  test("construct with dispatch rules, listRules returns them", () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("rule-a", "planning"),
+      mockDispatchRule("rule-b", "executing"),
+      mockDispatchRule("rule-c", "complete"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const listed = registry.listRules();
+
+    // At minimum, dispatch rules are returned (hook rules depend on prefs)
+    const dispatchRules = listed.filter(r => r.when === "dispatch");
+    assertEq(dispatchRules.length, 3, "listRules returns 3 dispatch rules");
+    assertEq(dispatchRules[0].name, "rule-a", "first rule name is rule-a");
+    assertEq(dispatchRules[1].name, "rule-b", "second rule name is rule-b");
+    assertEq(dispatchRules[2].name, "rule-c", "third rule name is rule-c");
+  });
+
+  test("listRules returns correct fields on each rule", () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("check-fields", "planning"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const listed = registry.listRules();
+    const rule = listed.find(r => r.name === "check-fields")!;
+
+    assertTrue(rule !== undefined, "rule found by name");
+    assertEq(rule.when, "dispatch", "when field is dispatch");
+    assertEq(rule.evaluation, "first-match", "evaluation is first-match");
+    assertTrue(typeof rule.where === "function", "where is a function");
+    assertTrue(typeof rule.then === "function", "then is a function");
+    assertEq(rule.description, "Mock rule for planning", "description is set");
+  });
+
+  test("evaluateDispatch returns first matching rule", async () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("rule-planning", "planning"),
+      mockDispatchRule("rule-executing", "executing"),
+      mockDispatchRule("rule-complete", "complete"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const ctx = makeContext("executing");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "dispatch", "result is a dispatch action");
+    if (result.action === "dispatch") {
+      assertEq(result.unitType, "test-executing", "matched the executing rule");
+      assertEq(result.prompt, "Prompt for executing", "prompt from matched rule");
+    }
+  });
+
+  test("evaluateDispatch returns stop when no rule matches", async () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("only-planning", "planning"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const ctx = makeContext("blocked");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "stop", "result is a stop action");
+    if (result.action === "stop") {
+      assertTrue(result.reason.includes("blocked"), "stop reason mentions phase");
+    }
+  });
+
+  test("evaluateDispatch works with async where predicate", async () => {
+    const asyncRule: UnifiedRule = {
+      name: "async-rule",
+      when: "dispatch",
+      evaluation: "first-match",
+      where: async (ctx: DispatchContext): Promise<DispatchAction | null> => {
+        // Simulate async work
+        await new Promise(resolve => setTimeout(resolve, 1));
+        if (ctx.state.phase === "planning") {
+          return {
+            action: "dispatch",
+            unitType: "async-test",
+            unitId: "async-id",
+            prompt: "Async prompt",
+          };
+        }
+        return null;
+      },
+      then: () => {},
+    };
+
+    const registry = new RuleRegistry([asyncRule]);
+    const ctx = makeContext("planning");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "dispatch", "async dispatch resolved");
+    if (result.action === "dispatch") {
+      assertEq(result.unitType, "async-test", "async rule matched");
+    }
+  });
+
+  test("resetState clears all mutable state", () => {
+    const registry = new RuleRegistry([]);
+
+    // Set up some state
+    registry.activeHook = {
+      hookName: "test-hook",
+      triggerUnitType: "execute-task",
+      triggerUnitId: "M001/S01/T01",
+      cycle: 2,
+      pendingRetry: false,
+    };
+    registry.hookQueue.push({
+      config: { name: "q", after: [], prompt: "p" },
+      triggerUnitType: "execute-task",
+      triggerUnitId: "M001/S01/T02",
+    });
+    registry.cycleCounts.set("test/key", 3);
+    registry.retryPending = true;
+    registry.retryTrigger = { unitType: "execute-task", unitId: "M001/S01/T01", retryArtifact: "RETRY" };
+
+    // Reset
+    registry.resetState();
+
+    assertEq(registry.getActiveHook(), null, "activeHook cleared");
+    assertEq(registry.hookQueue.length, 0, "hookQueue cleared");
+    assertEq(registry.cycleCounts.size, 0, "cycleCounts cleared");
+    assertEq(registry.isRetryPending(), false, "retryPending cleared");
+    assertEq(registry.consumeRetryTrigger(), null, "retryTrigger cleared");
+  });
+
+  test("singleton getRegistry throws when not initialized", () => {
+    let threw = false;
+    try {
+      getRegistry();
+    } catch (e: any) {
+      threw = true;
+      assertTrue(e.message.includes("not initialized"), "error mentions not initialized");
+    }
+    assertTrue(threw, "getRegistry threw");
+  });
+
+  test("setRegistry / getRegistry round-trips", () => {
+    const registry = new RuleRegistry([mockDispatchRule("singleton-test", "planning")]);
+    setRegistry(registry);
+
+    const retrieved = getRegistry();
+    assertEq(retrieved, registry, "getRegistry returns the same instance");
+
+    const listed = retrieved.listRules().filter(r => r.when === "dispatch");
+    assertEq(listed.length, 1, "singleton has 1 dispatch rule");
+    assertEq(listed[0].name, "singleton-test", "rule name matches");
+  });
+
+  test("initRegistry creates and sets singleton", () => {
+    const rules = [mockDispatchRule("init-test", "executing")];
+    const registry = initRegistry(rules);
+
+    assertEq(getRegistry(), registry, "initRegistry sets the singleton");
+    const listed = getRegistry().listRules().filter(r => r.when === "dispatch");
+    assertEq(listed.length, 1, "singleton has the rule");
+  });
+
+  test("evaluateDispatch respects rule order (first match wins)", async () => {
+    // Both rules match "planning" but rule-first should win
+    const ruleFirst: UnifiedRule = {
+      name: "rule-first",
+      when: "dispatch",
+      evaluation: "first-match",
+      where: async (ctx: DispatchContext) => {
+        if (ctx.state.phase === "planning") {
+          return { action: "dispatch" as const, unitType: "first-wins", unitId: "id", prompt: "first" };
+        }
+        return null;
+      },
+      then: () => {},
+    };
+    const ruleSecond: UnifiedRule = {
+      name: "rule-second",
+      when: "dispatch",
+      evaluation: "first-match",
+      where: async (ctx: DispatchContext) => {
+        if (ctx.state.phase === "planning") {
+          return { action: "dispatch" as const, unitType: "second-loses", unitId: "id", prompt: "second" };
+        }
+        return null;
+      },
+      then: () => {},
+    };
+
+    const registry = new RuleRegistry([ruleFirst, ruleSecond]);
+    const ctx = makeContext("planning");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "dispatch", "dispatch action returned");
+    if (result.action === "dispatch") {
+      assertEq(result.unitType, "first-wins", "first rule won over second");
+    }
+  });
+
+  // ── Dispatch rule conversion tests ─────────────────────────────────
+
+  test("convertDispatchRules produces correct count of UnifiedRule objects", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    assertEq(converted.length, DISPATCH_RULES.length, `convertDispatchRules produces ${DISPATCH_RULES.length} rules`);
+  });
+
+  test("each converted rule has correct when, evaluation, and original name", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    for (let i = 0; i < converted.length; i++) {
+      const rule = converted[i];
+      assertEq(rule.when, "dispatch", `rule ${i} has when:"dispatch"`);
+      assertEq(rule.evaluation, "first-match", `rule ${i} has evaluation:"first-match"`);
+      assertEq(rule.name, DISPATCH_RULES[i].name, `rule ${i} preserves name "${DISPATCH_RULES[i].name}"`);
+      assertTrue(typeof rule.where === "function", `rule ${i} has a where function`);
+      assertTrue(typeof rule.then === "function", `rule ${i} has a then function`);
+    }
+  });
+
+  test("listRules after construction with real dispatch rules returns correct count", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    const registry = new RuleRegistry(converted);
+    const listed = registry.listRules().filter(r => r.when === "dispatch");
+    assertEq(listed.length, DISPATCH_RULES.length, `listRules returns ${DISPATCH_RULES.length} dispatch rules`);
+  });
+
+  test("rule names from listRules match getDispatchRuleNames in exact order", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    const registry = new RuleRegistry(converted);
+    const listedNames = registry.listRules()
+      .filter(r => r.when === "dispatch")
+      .map(r => r.name);
+    const originalNames = getDispatchRuleNames();
+
+    assertEq(listedNames.length, originalNames.length, "same number of names");
+    for (let i = 0; i < originalNames.length; i++) {
+      assertEq(listedNames[i], originalNames[i], `name at index ${i} matches: "${originalNames[i]}"`);
+    }
+  });
+
+  // ── getOrCreateRegistry (lazy init for facades) ────────────────────
+
+  test("getOrCreateRegistry lazily creates a registry with empty dispatch rules", () => {
+    // After resetRegistry(), getRegistry() would throw. getOrCreateRegistry() should not.
+    const registry = getOrCreateRegistry();
+    assertTrue(registry instanceof RuleRegistry, "returns a RuleRegistry instance");
+    const dispatchRules = registry.listRules().filter(r => r.when === "dispatch");
+    assertEq(dispatchRules.length, 0, "lazily-created registry has 0 dispatch rules");
+  });
+
+  test("getOrCreateRegistry returns existing registry when initialized", () => {
+    const rules = [mockDispatchRule("explicit-init", "planning")];
+    const explicit = initRegistry(rules);
+    const lazy = getOrCreateRegistry();
+    assertEq(lazy, explicit, "getOrCreateRegistry returns the same singleton as initRegistry");
+    const dispatchRules = lazy.listRules().filter(r => r.when === "dispatch");
+    assertEq(dispatchRules.length, 1, "singleton has the explicitly initialized dispatch rule");
+  });
+
+  // ── Hook-derived rules in listRules ────────────────────────────────
+
+  test("listRules returns only dispatch rules when no hooks are configured", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    const registry = new RuleRegistry(converted);
+    const allRules = registry.listRules();
+    const postUnitRules = allRules.filter(r => r.when === "post-unit");
+    const preDispatchRules = allRules.filter(r => r.when === "pre-dispatch");
+
+    // No preferences file = no hooks
+    assertEq(postUnitRules.length, 0, "no post-unit rules when no hooks configured");
+    assertEq(preDispatchRules.length, 0, "no pre-dispatch rules when no hooks configured");
+    assertEq(allRules.length, DISPATCH_RULES.length, "total rules equals dispatch rules only");
+  });
+
+  test("listRules dispatch rules appear first, hooks after", () => {
+    const converted = convertDispatchRules(DISPATCH_RULES);
+    const registry = new RuleRegistry(converted);
+    const allRules = registry.listRules();
+
+    // Verify dispatch rules come first (indices 0..N-1)
+    for (let i = 0; i < converted.length; i++) {
+      assertEq(allRules[i].when, "dispatch", `rule at index ${i} is a dispatch rule`);
+      assertEq(allRules[i].name, converted[i].name, `dispatch rule at index ${i} has correct name`);
+    }
+  });
+
+  // ── Facade delegation (post-unit-hooks.ts imports work through registry) ──
+
+  test("evaluatePostUnit returns null for hook-on-hook prevention", () => {
+    const registry = new RuleRegistry([]);
+    const result = registry.evaluatePostUnit("hook/code-review", "M001/S01/T01", "/tmp/test");
+    assertEq(result, null, "hook units don't trigger other hooks");
+  });
+
+  test("evaluatePostUnit returns null for triage-captures", () => {
+    const registry = new RuleRegistry([]);
+    const result = registry.evaluatePostUnit("triage-captures", "M001/S01/T01", "/tmp/test");
+    assertEq(result, null, "triage-captures skipped");
+  });
+
+  test("evaluatePostUnit returns null for quick-task", () => {
+    const registry = new RuleRegistry([]);
+    const result = registry.evaluatePostUnit("quick-task", "M001/S01/T01", "/tmp/test");
+    assertEq(result, null, "quick-task skipped");
+  });
+
+  test("evaluatePreDispatch bypasses hook units", () => {
+    const registry = new RuleRegistry([]);
+    const result = registry.evaluatePreDispatch("hook/review", "M001/S01/T01", "prompt", "/tmp/test");
+    assertEq(result.action, "proceed", "hook units always proceed");
+    assertEq(result.prompt, "prompt", "prompt unchanged");
+    assertEq(result.firedHooks.length, 0, "no hooks fired");
+  });
+
+  test("evaluatePreDispatch proceeds with empty hooks", () => {
+    const registry = new RuleRegistry([]);
+    const result = registry.evaluatePreDispatch("execute-task", "M001/S01/T01", "original prompt", "/tmp/test");
+    assertEq(result.action, "proceed", "proceeds when no hooks");
+    assertEq(result.prompt, "original prompt", "prompt unchanged");
+  });
+
+  // ── matchedRule provenance (S02 journal support) ───────────────────
+
+  test("evaluateDispatch result includes matchedRule on dispatch match", async () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("my-planning-rule", "planning"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const ctx = makeContext("planning");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "dispatch", "result is a dispatch action");
+    assertEq(result.matchedRule, "my-planning-rule", "matchedRule is the rule name");
+  });
+
+  test("evaluateDispatch result includes matchedRule '<no-match>' on fallback stop", async () => {
+    const rules: UnifiedRule[] = [
+      mockDispatchRule("only-planning", "planning"),
+    ];
+    const registry = new RuleRegistry(rules);
+    const ctx = makeContext("some-unknown-phase");
+    const result = await registry.evaluateDispatch(ctx);
+
+    assertEq(result.action, "stop", "result is a stop action");
+    assertEq(result.matchedRule, "<no-match>", "matchedRule is '<no-match>' on fallback");
+  });
+});

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

@@ -0,0 +1,229 @@
+/**
+ * run-manager.test.ts — Tests for run directory creation and listing.
+ *
+ * Uses real temp directories with actual definition YAML files and
+ * GRAPH.yaml persistence — no mocks.
+ */
+
+import { describe, it, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  readdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { parse } from "yaml";
+
+import { createRun, listRuns } from "../run-manager.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+const tmpDirs: string[] = [];
+
+function makeTmpBase(): string {
+  const dir = mkdtempSync(join(tmpdir(), "run-mgr-test-"));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const d of tmpDirs) {
+    try { rmSync(d, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* Windows EPERM */ }
+  }
+  tmpDirs.length = 0;
+});
+
+/** Write a minimal valid workflow definition YAML to the expected location. */
+function writeDefinition(
+  basePath: string,
+  name: string,
+  content: string,
+): void {
+  const defsDir = join(basePath, ".gsd", "workflow-defs");
+  mkdirSync(defsDir, { recursive: true });
+  writeFileSync(join(defsDir, `${name}.yaml`), content, "utf-8");
+}
+
+const SIMPLE_DEF = `
+version: 1
+name: test-workflow
+description: A test workflow
+steps:
+  - id: step-1
+    name: First Step
+    prompt: Do step 1
+    requires: []
+    produces: []
+  - id: step-2
+    name: Second Step
+    prompt: Do step 2
+    requires:
+      - step-1
+    produces: []
+`;
+
+const PARAMETERIZED_DEF = `
+version: 1
+name: param-workflow
+description: A parameterized workflow
+params:
+  target: default-target
+steps:
+  - id: step-1
+    name: Build
+    prompt: "Build {{target}}"
+    requires: []
+    produces: []
+`;
+
+// ─── createRun ───────────────────────────────────────────────────────────
+
+describe("createRun", () => {
+  it("creates directory structure with DEFINITION.yaml and GRAPH.yaml", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "test-workflow", SIMPLE_DEF);
+
+    const runDir = createRun(base, "test-workflow");
+
+    // Run directory exists
+    assert.ok(existsSync(runDir), "run directory should exist");
+
+    // DEFINITION.yaml exists and contains the definition
+    const defPath = join(runDir, "DEFINITION.yaml");
+    assert.ok(existsSync(defPath), "DEFINITION.yaml should exist");
+    const defContent = parse(readFileSync(defPath, "utf-8"));
+    assert.equal(defContent.name, "test-workflow");
+    assert.equal(defContent.steps.length, 2);
+
+    // GRAPH.yaml exists with all steps pending
+    const graphPath = join(runDir, "GRAPH.yaml");
+    assert.ok(existsSync(graphPath), "GRAPH.yaml should exist");
+    const graphContent = parse(readFileSync(graphPath, "utf-8"));
+    assert.equal(graphContent.steps.length, 2);
+    assert.equal(graphContent.steps[0].status, "pending");
+    assert.equal(graphContent.steps[1].status, "pending");
+    assert.equal(graphContent.metadata.name, "test-workflow");
+
+    // No PARAMS.json without overrides
+    assert.ok(!existsSync(join(runDir, "PARAMS.json")), "PARAMS.json should not exist without overrides");
+
+    // Run directory path matches convention
+    assert.ok(runDir.includes(join(".gsd", "workflow-runs", "test-workflow")), "path should follow convention");
+  });
+
+  it("writes PARAMS.json and substituted prompts when overrides provided", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "param-workflow", PARAMETERIZED_DEF);
+
+    const runDir = createRun(base, "param-workflow", { target: "my-app" });
+
+    // PARAMS.json exists with overrides
+    const paramsPath = join(runDir, "PARAMS.json");
+    assert.ok(existsSync(paramsPath), "PARAMS.json should exist");
+    const params = JSON.parse(readFileSync(paramsPath, "utf-8"));
+    assert.deepStrictEqual(params, { target: "my-app" });
+
+    // DEFINITION.yaml has substituted prompts
+    const defPath = join(runDir, "DEFINITION.yaml");
+    const defContent = parse(readFileSync(defPath, "utf-8"));
+    assert.equal(defContent.steps[0].prompt, "Build my-app");
+
+    // GRAPH.yaml also has substituted prompts
+    const graphPath = join(runDir, "GRAPH.yaml");
+    const graphContent = parse(readFileSync(graphPath, "utf-8"));
+    assert.equal(graphContent.steps[0].prompt, "Build my-app");
+  });
+
+  it("throws for unknown definition", () => {
+    const base = makeTmpBase();
+    // Don't write any definition file
+
+    assert.throws(
+      () => createRun(base, "nonexistent"),
+      (err: Error) => err.message.includes("not found"),
+    );
+  });
+
+  it("uses filesystem-safe timestamp directory names", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "test-workflow", SIMPLE_DEF);
+
+    const runDir = createRun(base, "test-workflow");
+
+    // Extract the timestamp directory name (use path.sep for cross-platform)
+    const timestamp = runDir.split(/[/\\]/).pop()!;
+
+    // Should not contain colons (filesystem-unsafe on Windows)
+    assert.ok(!timestamp.includes(":"), `timestamp should not contain colons: ${timestamp}`);
+    // Should match YYYY-MM-DDTHH-MM-SS pattern
+    assert.match(timestamp, /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}$/);
+  });
+});
+
+// ─── listRuns ────────────────────────────────────────────────────────────
+
+describe("listRuns", () => {
+  it("returns empty array when no runs exist", () => {
+    const base = makeTmpBase();
+    const runs = listRuns(base);
+    assert.deepStrictEqual(runs, []);
+  });
+
+  it("returns correct metadata for existing runs", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "test-workflow", SIMPLE_DEF);
+
+    // Create a run
+    const runDir = createRun(base, "test-workflow");
+
+    const runs = listRuns(base);
+    assert.equal(runs.length, 1);
+    assert.equal(runs[0].name, "test-workflow");
+    assert.equal(runs[0].runDir, runDir);
+    assert.equal(runs[0].steps.total, 2);
+    assert.equal(runs[0].steps.completed, 0);
+    assert.equal(runs[0].steps.pending, 2);
+    assert.equal(runs[0].steps.active, 0);
+    assert.equal(runs[0].status, "pending");
+  });
+
+  it("filters by definition name", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "test-workflow", SIMPLE_DEF);
+    writeDefinition(base, "param-workflow", PARAMETERIZED_DEF);
+
+    createRun(base, "test-workflow");
+    createRun(base, "param-workflow", { target: "app" });
+
+    const allRuns = listRuns(base);
+    assert.equal(allRuns.length, 2);
+
+    const filtered = listRuns(base, "test-workflow");
+    assert.equal(filtered.length, 1);
+    assert.equal(filtered[0].name, "test-workflow");
+  });
+
+  it("returns newest-first within same definition", () => {
+    const base = makeTmpBase();
+    writeDefinition(base, "test-workflow", SIMPLE_DEF);
+
+    const run1 = createRun(base, "test-workflow");
+    // Ensure different timestamp by creating run dir manually with earlier timestamp
+    const earlyDir = join(base, ".gsd", "workflow-runs", "test-workflow", "2020-01-01T00-00-00");
+    mkdirSync(earlyDir, { recursive: true });
+    // Copy GRAPH.yaml to make it a valid run
+    const graphContent = readFileSync(join(run1, "GRAPH.yaml"), "utf-8");
+    writeFileSync(join(earlyDir, "GRAPH.yaml"), graphContent, "utf-8");
+
+    const runs = listRuns(base, "test-workflow");
+    assert.equal(runs.length, 2);
+    // First should be the newer one (the one we just created)
+    assert.ok(runs[0].timestamp > runs[1].timestamp, "should be sorted newest-first");
+  });
+});