gsd-pi 2.37.0 → 2.37.1-dev.49503be

package/src/resources/extensions/gsd/tests/reactive-executor.test.ts

@@ -0,0 +1,367 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  loadSliceTaskIO,
+  deriveTaskGraph,
+  isGraphAmbiguous,
+  getReadyTasks,
+  chooseNonConflictingSubset,
+  loadReactiveState,
+  saveReactiveState,
+  clearReactiveState,
+} from "../reactive-graph.ts";
+import { validatePreferences } from "../preferences-validation.ts";
+import type { ReactiveExecutionState } from "../types.ts";
+
+// ─── Preference Validation ────────────────────────────────────────────────
+
+test("reactive_execution validation accepts valid config", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 4,
+      isolation_mode: "same-tree",
+    },
+  });
+  assert.equal(result.errors.length, 0);
+  assert.deepEqual(result.preferences.reactive_execution, {
+    enabled: true,
+    max_parallel: 4,
+    isolation_mode: "same-tree",
+  });
+});
+
+test("reactive_execution validation rejects max_parallel out of range", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 10,
+      isolation_mode: "same-tree",
+    } as any,
+  });
+  assert.ok(result.errors.some((e) => e.includes("max_parallel")));
+});
+
+test("reactive_execution validation rejects invalid isolation_mode", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 2,
+      isolation_mode: "separate-branch",
+    } as any,
+  });
+  assert.ok(result.errors.some((e) => e.includes("isolation_mode")));
+});
+
+test("reactive_execution validation warns on unknown keys", () => {
+  const result = validatePreferences({
+    reactive_execution: {
+      enabled: true,
+      max_parallel: 2,
+      isolation_mode: "same-tree",
+      unknown_thing: true,
+    } as any,
+  });
+  assert.equal(result.errors.length, 0);
+  assert.ok(result.warnings.some((w) => w.includes("unknown_thing")));
+});
+
+// ─── Dispatch Rule Matching Logic ─────────────────────────────────────────
+
+test("reactive dispatch requires enabled config and multiple ready tasks", async () => {
+  // Build a minimal filesystem with a slice plan and task plans
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-dispatch-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    // Slice plan with 3 tasks
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Test Slice",
+        "",
+        "**Goal:** Test reactive execution",
+        "**Demo:** All three tasks run in parallel",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: First** `est:15m`",
+        "  Create initial types",
+        "- [ ] **T02: Second** `est:15m`",
+        "  Create models",
+        "- [ ] **T03: Third** `est:15m`",
+        "  Create service layer",
+        "",
+      ].join("\n"),
+    );
+
+    // Task plans with non-overlapping IO (all independent)
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      [
+        "# T01: First",
+        "",
+        "## Description",
+        "Create types.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/config.json` — Config schema",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/types.ts` — Type definitions",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      [
+        "# T02: Second",
+        "",
+        "## Description",
+        "Create models.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/schema.json` — Schema file",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/models.ts` — Model definitions",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T03-PLAN.md"),
+      [
+        "# T03: Third",
+        "",
+        "## Description",
+        "Create service.",
+        "",
+        "## Inputs",
+        "",
+        "- `src/api.json` — API spec",
+        "",
+        "## Expected Output",
+        "",
+        "- `src/service.ts` — Service layer",
+      ].join("\n"),
+    );
+
+    // Load IO and build graph
+    const basePath = repo;
+    const taskIO = await loadSliceTaskIO(basePath, "M001", "S01");
+    assert.equal(taskIO.length, 3);
+
+    const graph = deriveTaskGraph(taskIO);
+    assert.equal(isGraphAmbiguous(graph), false, "Graph should not be ambiguous");
+
+    // All independent → all should be ready
+    const ready = getReadyTasks(graph, new Set(), new Set());
+    assert.equal(ready.length, 3);
+
+    // Choose subset with max_parallel=2
+    const selected = chooseNonConflictingSubset(ready, graph, 2, new Set());
+    assert.equal(selected.length, 2);
+    assert.deepEqual(selected, ["T01", "T02"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("reactive dispatch falls back when graph is ambiguous (task without IO)", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-ambiguous-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Test",
+        "",
+        "**Goal:** Test",
+        "**Demo:** Test",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: A** `est:15m`",
+        "- [ ] **T02: B** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    // T01 has IO, T02 has NO IO sections → ambiguous
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: A\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: B\n\n## Description\n\nNo IO sections.\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+    assert.equal(isGraphAmbiguous(graph), true, "Graph should be ambiguous");
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("single ready task falls through to sequential", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-single-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Linear",
+        "",
+        "**Goal:** Linear chain",
+        "**Demo:** Sequential",
+        "",
+        "## Tasks",
+        "",
+        "- [ ] **T01: First** `est:15m`",
+        "- [ ] **T02: Second** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: First\n\n## Inputs\n\n- `src/config.json`\n\n## Expected Output\n\n- `src/a.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: Second\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+    const ready = getReadyTasks(graph, new Set(), new Set());
+    // Only T01 is ready (T02 depends on T01)
+    assert.equal(ready.length, 1);
+    assert.deepEqual(ready, ["T01"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+// ─── State Persistence ────────────────────────────────────────────────────
+
+test("saveReactiveState and loadReactiveState round-trip", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-state-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const state: ReactiveExecutionState = {
+      sliceId: "S01",
+      completed: ["T01", "T02"],
+      graphSnapshot: { taskCount: 4, edgeCount: 2, readySetSize: 1, ambiguous: false },
+      updatedAt: "2025-01-01T00:00:00Z",
+    };
+
+    saveReactiveState(repo, "M001", "S01", state);
+    const loaded = loadReactiveState(repo, "M001", "S01");
+    assert.deepEqual(loaded, state);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("clearReactiveState removes the file", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-clear-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const state: ReactiveExecutionState = {
+      sliceId: "S01",
+      completed: [],
+      graphSnapshot: { taskCount: 2, edgeCount: 0, readySetSize: 2, ambiguous: false },
+      updatedAt: "2025-01-01T00:00:00Z",
+    };
+
+    saveReactiveState(repo, "M001", "S01", state);
+    assert.ok(existsSync(join(repo, ".gsd", "runtime", "M001-S01-reactive.json")));
+
+    clearReactiveState(repo, "M001", "S01");
+    assert.ok(!existsSync(join(repo, ".gsd", "runtime", "M001-S01-reactive.json")));
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("loadReactiveState returns null when no file exists", () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-nofile-"));
+  mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+  try {
+    const loaded = loadReactiveState(repo, "M001", "S01");
+    assert.equal(loaded, null);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});
+
+test("completed tasks are not re-dispatched on next iteration", async () => {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-reactive-reentry-"));
+  try {
+    const gsd = join(repo, ".gsd", "milestones", "M001", "slices", "S01");
+    mkdirSync(join(gsd, "tasks"), { recursive: true });
+    mkdirSync(join(repo, ".gsd", "runtime"), { recursive: true });
+
+    writeFileSync(
+      join(gsd, "S01-PLAN.md"),
+      [
+        "# S01: Reentry Test",
+        "",
+        "**Goal:** Test re-entry",
+        "**Demo:** Correct resumption",
+        "",
+        "## Tasks",
+        "",
+        "- [x] **T01: Done** `est:15m`",
+        "- [ ] **T02: Pending** `est:15m`",
+        "- [ ] **T03: Also Pending** `est:15m`",
+        "",
+      ].join("\n"),
+    );
+
+    writeFileSync(
+      join(gsd, "tasks", "T01-PLAN.md"),
+      "# T01: Done\n\n## Inputs\n\n- `src/config.json`\n\n## Expected Output\n\n- `src/a.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T02-PLAN.md"),
+      "# T02: Pending\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/b.ts`\n",
+    );
+    writeFileSync(
+      join(gsd, "tasks", "T03-PLAN.md"),
+      "# T03: Also Pending\n\n## Inputs\n\n- `src/a.ts`\n\n## Expected Output\n\n- `src/c.ts`\n",
+    );
+
+    const taskIO = await loadSliceTaskIO(repo, "M001", "S01");
+    const graph = deriveTaskGraph(taskIO);
+
+    // T01 is done, T02 and T03 depend on T01
+    const completed = new Set(["T01"]);
+    const ready = getReadyTasks(graph, completed, new Set());
+    // Both T02 and T03 should be ready (T01 is complete)
+    assert.deepEqual(ready, ["T02", "T03"]);
+
+    // Simulate T02 completes, re-derive
+    completed.add("T02");
+    const ready2 = getReadyTasks(graph, completed, new Set());
+    // Only T03 should be ready
+    assert.deepEqual(ready2, ["T03"]);
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/reactive-graph.test.ts

@@ -0,0 +1,299 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  deriveTaskGraph,
+  getReadyTasks,
+  chooseNonConflictingSubset,
+  isGraphAmbiguous,
+  detectDeadlock,
+  graphMetrics,
+} from "../reactive-graph.ts";
+import { parseTaskPlanIO } from "../files.ts";
+import type { TaskIO, DerivedTaskNode } from "../types.ts";
+
+// ─── parseTaskPlanIO ──────────────────────────────────────────────────────
+
+test("parseTaskPlanIO extracts backtick-wrapped file paths from Inputs and Expected Output", () => {
+  const content = `---
+estimated_steps: 3
+estimated_files: 2
+---
+
+# T01: Setup Models
+
+**Slice:** S01 — Core Setup
+**Milestone:** M001
+
+## Description
+
+Create the core data models.
+
+## Steps
+
+1. Create types file
+2. Create models file
+
+## Must-Haves
+
+- [ ] Type definitions complete
+
+## Verification
+
+- Run type checker
+
+## Inputs
+
+- \`src/types.ts\` — Existing type definitions from prior work
+- \`src/config.json\` — Configuration schema
+
+## Expected Output
+
+- \`src/models.ts\` — New data model definitions
+- \`src/models.test.ts\` — Unit tests for models
+`;
+
+  const io = parseTaskPlanIO(content);
+  assert.deepEqual(io.inputFiles, ["src/types.ts", "src/config.json"]);
+  assert.deepEqual(io.outputFiles, ["src/models.ts", "src/models.test.ts"]);
+});
+
+test("parseTaskPlanIO returns empty arrays for missing sections", () => {
+  const content = `# T01: Something\n\n## Description\n\nNo IO sections here.\n`;
+  const io = parseTaskPlanIO(content);
+  assert.deepEqual(io.inputFiles, []);
+  assert.deepEqual(io.outputFiles, []);
+});
+
+test("parseTaskPlanIO ignores non-file-path backtick tokens", () => {
+  const content = `# T01: Test
+
+## Inputs
+
+- \`true\` — a boolean flag
+- \`src/index.ts\` — main entry
+- \`npm run test\` — a command, not a file
+
+## Expected Output
+
+- \`dist/bundle.js\` — compiled output
+- \`false\` — not a file
+`;
+
+  const io = parseTaskPlanIO(content);
+  assert.deepEqual(io.inputFiles, ["src/index.ts"]);
+  assert.deepEqual(io.outputFiles, ["dist/bundle.js"]);
+});
+
+test("parseTaskPlanIO handles multiple backtick tokens on one line", () => {
+  const content = `# T01: Multi
+
+## Inputs
+
+- \`src/a.ts\` and \`src/b.ts\` — both needed
+
+## Expected Output
+
+- \`src/c.ts\` — output
+`;
+  const io = parseTaskPlanIO(content);
+  assert.deepEqual(io.inputFiles, ["src/a.ts", "src/b.ts"]);
+  assert.deepEqual(io.outputFiles, ["src/c.ts"]);
+});
+
+// ─── deriveTaskGraph ──────────────────────────────────────────────────────
+
+test("deriveTaskGraph: linear chain T01→T02→T03", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "First", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "Second", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false },
+    { id: "T03", title: "Third", inputFiles: ["src/b.ts"], outputFiles: ["src/c.ts"], done: false },
+  ];
+
+  const graph = deriveTaskGraph(tasks);
+  assert.deepEqual(graph[0].dependsOn, []);
+  assert.deepEqual(graph[1].dependsOn, ["T01"]);
+  assert.deepEqual(graph[2].dependsOn, ["T02"]);
+});
+
+test("deriveTaskGraph: diamond dependency", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "Base", inputFiles: [], outputFiles: ["src/base.ts"], done: false },
+    { id: "T02", title: "Left", inputFiles: ["src/base.ts"], outputFiles: ["src/left.ts"], done: false },
+    { id: "T03", title: "Right", inputFiles: ["src/base.ts"], outputFiles: ["src/right.ts"], done: false },
+    { id: "T04", title: "Merge", inputFiles: ["src/left.ts", "src/right.ts"], outputFiles: ["src/final.ts"], done: false },
+  ];
+
+  const graph = deriveTaskGraph(tasks);
+  assert.deepEqual(graph[0].dependsOn, []);
+  assert.deepEqual(graph[1].dependsOn, ["T01"]);
+  assert.deepEqual(graph[2].dependsOn, ["T01"]);
+  assert.deepEqual(graph[3].dependsOn, ["T02", "T03"]);
+});
+
+test("deriveTaskGraph: fully independent tasks", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/b.ts"], done: false },
+    { id: "T03", title: "C", inputFiles: [], outputFiles: ["src/c.ts"], done: false },
+  ];
+
+  const graph = deriveTaskGraph(tasks);
+  assert.deepEqual(graph[0].dependsOn, []);
+  assert.deepEqual(graph[1].dependsOn, []);
+  assert.deepEqual(graph[2].dependsOn, []);
+});
+
+test("deriveTaskGraph: self-referencing output→input is excluded", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "Self", inputFiles: ["src/a.ts"], outputFiles: ["src/a.ts"], done: false },
+  ];
+
+  const graph = deriveTaskGraph(tasks);
+  assert.deepEqual(graph[0].dependsOn, []);
+});
+
+// ─── getReadyTasks ────────────────────────────────────────────────────────
+
+test("getReadyTasks: partially completed graph", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "Base", inputFiles: [], outputFiles: ["src/a.ts"], done: true },
+    { id: "T02", title: "Dep", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false },
+    { id: "T03", title: "Blocked", inputFiles: ["src/b.ts"], outputFiles: ["src/c.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const ready = getReadyTasks(graph, new Set(["T01"]), new Set());
+  assert.deepEqual(ready, ["T02"]);
+});
+
+test("getReadyTasks: nothing complete → only root tasks ready", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "Root", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "Dep", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const ready = getReadyTasks(graph, new Set(), new Set());
+  assert.deepEqual(ready, ["T01"]);
+});
+
+test("getReadyTasks: all complete → empty", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "Done", inputFiles: [], outputFiles: ["src/a.ts"], done: true },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const ready = getReadyTasks(graph, new Set(["T01"]), new Set());
+  assert.deepEqual(ready, []);
+});
+
+test("getReadyTasks: in-flight tasks excluded", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/b.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const ready = getReadyTasks(graph, new Set(), new Set(["T01"]));
+  assert.deepEqual(ready, ["T02"]);
+});
+
+// ─── chooseNonConflictingSubset ───────────────────────────────────────────
+
+test("chooseNonConflictingSubset: output conflicts", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/shared.ts"], done: false },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/shared.ts"], done: false },
+    { id: "T03", title: "C", inputFiles: [], outputFiles: ["src/other.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const selected = chooseNonConflictingSubset(["T01", "T02", "T03"], graph, 3, new Set());
+  // T01 claims shared.ts, T02 conflicts, T03 is fine
+  assert.deepEqual(selected, ["T01", "T03"]);
+});
+
+test("chooseNonConflictingSubset: respects maxParallel", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/b.ts"], done: false },
+    { id: "T03", title: "C", inputFiles: [], outputFiles: ["src/c.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const selected = chooseNonConflictingSubset(["T01", "T02", "T03"], graph, 2, new Set());
+  assert.deepEqual(selected, ["T01", "T02"]);
+});
+
+test("chooseNonConflictingSubset: respects inFlightOutputs", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/b.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const selected = chooseNonConflictingSubset(["T01", "T02"], graph, 4, new Set(["src/a.ts"]));
+  assert.deepEqual(selected, ["T02"]);
+});
+
+// ─── isGraphAmbiguous ─────────────────────────────────────────────────────
+
+test("isGraphAmbiguous: task with no IO → ambiguous", () => {
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: [], done: false, dependsOn: [] },
+    { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: [] },
+  ];
+  assert.equal(isGraphAmbiguous(graph), true);
+});
+
+test("isGraphAmbiguous: all tasks have IO → not ambiguous", () => {
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false, dependsOn: [] },
+    { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: ["T01"] },
+  ];
+  assert.equal(isGraphAmbiguous(graph), false);
+});
+
+test("isGraphAmbiguous: done tasks with no IO are ignored", () => {
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: [], done: true, dependsOn: [] },
+    { id: "T02", title: "B", inputFiles: [], outputFiles: ["src/b.ts"], done: false, dependsOn: [] },
+  ];
+  assert.equal(isGraphAmbiguous(graph), false);
+});
+
+// ─── detectDeadlock ───────────────────────────────────────────────────────
+
+test("detectDeadlock: circular dependency detected", () => {
+  // T01 depends on T02, T02 depends on T01 — deadlock
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: ["src/b.ts"], outputFiles: ["src/a.ts"], done: false, dependsOn: ["T02"] },
+    { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: ["T01"] },
+  ];
+  assert.equal(detectDeadlock(graph, new Set(), new Set()), true);
+});
+
+test("detectDeadlock: normal blocked-waiting-for-in-flight → not deadlock", () => {
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: false, dependsOn: [] },
+    { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false, dependsOn: ["T01"] },
+  ];
+  // T01 is in-flight, T02 is waiting → not deadlock
+  assert.equal(detectDeadlock(graph, new Set(), new Set(["T01"])), false);
+});
+
+test("detectDeadlock: all complete → not deadlock", () => {
+  const graph: DerivedTaskNode[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: true, dependsOn: [] },
+  ];
+  assert.equal(detectDeadlock(graph, new Set(["T01"]), new Set()), false);
+});
+
+// ─── graphMetrics ─────────────────────────────────────────────────────────
+
+test("graphMetrics computes correct values", () => {
+  const tasks: TaskIO[] = [
+    { id: "T01", title: "A", inputFiles: [], outputFiles: ["src/a.ts"], done: true },
+    { id: "T02", title: "B", inputFiles: ["src/a.ts"], outputFiles: ["src/b.ts"], done: false },
+    { id: "T03", title: "C", inputFiles: [], outputFiles: ["src/c.ts"], done: false },
+  ];
+  const graph = deriveTaskGraph(tasks);
+  const metrics = graphMetrics(graph);
+  assert.equal(metrics.taskCount, 3);
+  assert.equal(metrics.edgeCount, 1); // T02 depends on T01
+  assert.equal(metrics.readySetSize, 2); // T02 (T01 done) and T03 (no deps)
+  assert.equal(metrics.ambiguous, false);
+});