@nanobpm/nano-workforce 0.26.0

package/app/taskDelta.test.ts

@@ -0,0 +1,144 @@
+// Unit tests for the structured scope/impl-change report (D5, issue #55 / #49).
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  aggregateEpicDeltas,
+  clearTaskDeltas,
+  parseTaskDelta,
+  readTaskDeltas,
+  recordTaskDelta,
+} from "./taskDelta.ts";
+
+// A tiny in-memory stand-in for the record gateway (insert/find/findOne/update/delete), mirroring
+// the fake-app style used across the app tests (see app/blackboard.test.ts).
+// deno-lint-ignore no-explicit-any
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  // deno-lint-ignore no-explicit-any
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  function tbl(name: string, pk = "id") {
+    // deno-lint-ignore no-explicit-any
+    const rows = (stores[name] ??= [] as any[]);
+    // deno-lint-ignore no-explicit-any
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      // deno-lint-ignore no-explicit-any require-await
+      async insert(row: any) {
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push(pk === "id" ? { id, ...row } : { ...row });
+        return pk === "id" ? id : row[pk];
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      // deno-lint-ignore no-explicit-any require-await
+      async delete(id: any) {
+        const i = rows.findIndex((row) => row[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+    };
+  }
+  // deno-lint-ignore no-explicit-any
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+Deno.test("parseTaskDelta: trims, dedupes arrays, and drops empties", () => {
+  const d = parseTaskDelta({
+    contractChange: "  new signature  ",
+    newlyTouches: ["a.rs", " a.rs ", "", "b.rs"],
+    affectsTasks: ["gap-8", "gap-8"],
+    constraint: "",
+  });
+  assert(d);
+  assertEquals(d.contractChange, "new signature");
+  assertEquals(d.newlyTouches, ["a.rs", "b.rs"], "trimmed + de-duplicated");
+  assertEquals(d.affectsTasks, ["gap-8"]);
+  assertEquals(d.constraint, undefined, "a blank constraint is dropped");
+});
+
+Deno.test("parseTaskDelta: a delta with nothing actionable is null", () => {
+  assertEquals(parseTaskDelta(undefined), null);
+  assertEquals(parseTaskDelta({}), null);
+  assertEquals(parseTaskDelta({ newlyTouches: [], affectsTasks: [], contractChange: "  " }), null);
+  assertEquals(parseTaskDelta("not an object"), null);
+});
+
+Deno.test("recordTaskDelta: upserts per (plan, task) — a resume overwrites, not duplicates", async () => {
+  const { data, stores } = memData();
+  const first = await recordTaskDelta(data, "o/r#1", "gap-2", {
+    newlyTouches: ["a.rs"],
+    affectsTasks: [],
+    contractChange: "v1",
+  }, { wave: 0 });
+  assertEquals(first.inserted, true);
+
+  const second = await recordTaskDelta(data, "o/r#1", "gap-2", {
+    newlyTouches: ["a.rs", "b.rs"],
+    affectsTasks: ["gap-9"],
+    constraint: "seeded",
+  }, { wave: 1 });
+  assertEquals(second.inserted, false, "same (plan, task) → update in place");
+  assertEquals(second.id, first.id);
+  assertEquals(stores["plan_task_deltas"].length, 1, "exactly one row");
+
+  const [entry] = await readTaskDeltas(data, "o/r#1");
+  assertEquals(entry.newlyTouches, ["a.rs", "b.rs"], "latest report wins");
+  assertEquals(entry.constraint, "seeded");
+  assertEquals(entry.contractChange, undefined, "cleared when the new report omits it");
+  assertEquals(entry.wave, 1);
+});
+
+Deno.test("readTaskDeltas: scoped to a plan, in write order, arrays decoded", async () => {
+  const { data } = memData();
+  await recordTaskDelta(data, "o/r#1", "gap-2", { newlyTouches: ["a.rs"], affectsTasks: [] });
+  await recordTaskDelta(data, "o/r#1", "gap-8", { newlyTouches: [], affectsTasks: ["gap-2"], constraint: "x" });
+  await recordTaskDelta(data, "o/r#2", "gap-1", { newlyTouches: ["z.rs"], affectsTasks: [] }); // other plan
+
+  const entries = await readTaskDeltas(data, "o/r#1");
+  assertEquals(entries.map((e) => e.taskId), ["gap-2", "gap-8"], "write order, scoped to plan");
+  assertEquals(entries[0].newlyTouches, ["a.rs"]);
+  assertEquals(entries[1].affectsTasks, ["gap-2"]);
+});
+
+Deno.test("aggregateEpicDeltas: unions touched files + affected tasks, lists changes/constraints", async () => {
+  const { data } = memData();
+  await recordTaskDelta(data, "p", "gap-2", {
+    newlyTouches: ["engine/state.rs"],
+    affectsTasks: ["gap-8"],
+    contractChange: "restructured complete_adhoc_tool",
+  });
+  await recordTaskDelta(data, "p", "gap-8", {
+    newlyTouches: ["engine/state.rs", "engine/tests.rs"],
+    affectsTasks: ["gap-2", "gap-4"],
+    constraint: "results:[] seed",
+  });
+
+  const report = await aggregateEpicDeltas(data, "p");
+  assertEquals(report.touchedFiles, ["engine/state.rs", "engine/tests.rs"], "union, sorted, de-duplicated");
+  assertEquals(report.affectedTasks, ["gap-2", "gap-4", "gap-8"]);
+  assertEquals(report.contractChanges, [{ taskId: "gap-2", change: "restructured complete_adhoc_tool" }]);
+  assertEquals(report.constraints, [{ taskId: "gap-8", constraint: "results:[] seed" }]);
+  assertEquals(report.deltas.length, 2);
+});
+
+Deno.test("clearTaskDeltas: drops a plan's whole set (re-plan cleanup), leaving other plans intact", async () => {
+  const { data, stores } = memData();
+  await recordTaskDelta(data, "p", "gap-2", { newlyTouches: ["a.rs"], affectsTasks: [] });
+  await recordTaskDelta(data, "p", "gap-8", { newlyTouches: ["b.rs"], affectsTasks: [] });
+  await recordTaskDelta(data, "other", "gap-1", { newlyTouches: ["z.rs"], affectsTasks: [] });
+
+  await clearTaskDeltas(data, "p");
+  assertEquals((await readTaskDeltas(data, "p")).length, 0);
+  assertEquals(stores["plan_task_deltas"].length, 1, "the other plan's delta survives");
+});

package/app/taskDelta.ts

@@ -0,0 +1,175 @@
+// nano-workforce — structured scope/impl-change report from implementers (D5, issue #55 / #49).
+//
+// The implementer result contract (prompts/feature.md) can carry an optional `delta`: a machine-
+// readable record of how a slice's implementation diverged from its brief — a changed contract, a
+// discovered constraint, files it now touches beyond its slice, or other tasks it affects. Before
+// this, that information lived only in PR prose: invisible to the planner, to sibling agents, and
+// to any later merge-planning (D6). Here we parse it, persist one row per (plan, task), aggregate
+// a plan into a single epic-level report, and (in record-wave) auto-broadcast the file/constraint
+// facts onto the D4 coordination blackboard.
+//
+// Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
+// app/plan.ts and app/blackboard.ts.
+import type { DataLayer } from "@nanobpm/urban";
+
+const now = () => new Date().toISOString();
+
+/** The stored row shape. `newly_touches`/`affects_tasks` are JSON-encoded string arrays or NULL. */
+export interface TaskDeltaRow {
+  id: number;
+  plan_key: string;
+  task_id: string;
+  wave: number | null;
+  contract_change: string | null;
+  newly_touches: string | null;
+  affects_tasks: string | null;
+  constraint_note: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/** The parsed, structured delta an implementer reports (all fields optional). */
+export interface TaskDelta {
+  contractChange?: string;
+  newlyTouches: string[];
+  affectsTasks: string[];
+  constraint?: string;
+}
+
+/** The agent-facing view of a persisted delta (arrays decoded, keyed to its task). */
+export interface TaskDeltaEntry extends TaskDelta {
+  taskId: string;
+  wave: number | null;
+  updatedAt: string;
+}
+
+function trimStr(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+function strArray(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  const seen = new Set<string>();
+  for (const raw of v) {
+    const s = typeof raw === "string" ? raw.trim() : "";
+    if (s !== "") seen.add(s);
+  }
+  return [...seen];
+}
+
+function decodeArray(raw: string | null): string[] {
+  if (!raw) return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Coerce an arbitrary result-`delta` payload into a {@link TaskDelta}, or `null` when it carries
+ * nothing actionable (so callers persist/broadcast only real deltas, never empty noise). */
+export function parseTaskDelta(raw: unknown): TaskDelta | null {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw as Record<string, unknown>;
+  const delta: TaskDelta = {
+    contractChange: trimStr(o.contractChange),
+    newlyTouches: strArray(o.newlyTouches),
+    affectsTasks: strArray(o.affectsTasks),
+    constraint: trimStr(o.constraint),
+  };
+  const empty = !delta.contractChange && !delta.constraint &&
+    delta.newlyTouches.length === 0 && delta.affectsTasks.length === 0;
+  return empty ? null : delta;
+}
+
+const deltaTable = (data: DataLayer) => data.table<TaskDeltaRow>("plan_task_deltas", "id");
+
+function toEntry(r: TaskDeltaRow): TaskDeltaEntry {
+  return {
+    taskId: r.task_id,
+    wave: r.wave,
+    contractChange: r.contract_change ?? undefined,
+    newlyTouches: decodeArray(r.newly_touches),
+    affectsTasks: decodeArray(r.affects_tasks),
+    constraint: r.constraint_note ?? undefined,
+    updatedAt: r.updated_at,
+  };
+}
+
+/** Upsert the delta for one (plan, task). A worker retry or a post-escalation resume overwrites the
+ * prior report in place (idempotent), rather than appending a duplicate. */
+export async function recordTaskDelta(
+  data: DataLayer,
+  planKey: string,
+  taskId: string,
+  delta: TaskDelta,
+  opts: { wave?: number | null } = {},
+): Promise<{ inserted: boolean; id: number | bigint }> {
+  const table = deltaTable(data);
+  const ts = now();
+  const fields = {
+    wave: opts.wave ?? null,
+    contract_change: delta.contractChange ?? null,
+    newly_touches: delta.newlyTouches.length ? JSON.stringify(delta.newlyTouches) : null,
+    affects_tasks: delta.affectsTasks.length ? JSON.stringify(delta.affectsTasks) : null,
+    constraint_note: delta.constraint ?? null,
+    updated_at: ts,
+  };
+  const existing = await table.findOne({ plan_key: planKey, task_id: taskId });
+  if (existing) {
+    await table.update(existing.id, fields);
+    return { inserted: false, id: existing.id };
+  }
+  const id = await table.insert({ plan_key: planKey, task_id: taskId, created_at: ts, ...fields });
+  return { inserted: true, id };
+}
+
+/** A plan's per-task deltas in write order. */
+export async function readTaskDeltas(data: DataLayer, planKey: string): Promise<TaskDeltaEntry[]> {
+  const rows = await deltaTable(data).find({ plan_key: planKey });
+  return rows.slice().sort((a, b) => a.id - b.id).map(toEntry);
+}
+
+/** Delete a plan's whole delta set (called on re-plan, alongside the other plan-scoped tables). */
+export async function clearTaskDeltas(data: DataLayer, planKey: string): Promise<void> {
+  for (const r of await deltaTable(data).find({ plan_key: planKey })) {
+    await deltaTable(data).delete(r.id);
+  }
+}
+
+/** The single epic-level report: every per-task delta plus cross-task rollups (the union of
+ * newly-touched files and affected tasks, and the list of contract changes / constraints). The
+ * rollups are what a coordinator (D10) and merge-planning (D6) read; `touchedFiles`/`affectedTasks`
+ * are the seed for D2's conflict graph. */
+export interface EpicDeltaReport {
+  deltas: TaskDeltaEntry[];
+  touchedFiles: string[];
+  affectedTasks: string[];
+  contractChanges: { taskId: string; change: string }[];
+  constraints: { taskId: string; constraint: string }[];
+}
+
+export async function aggregateEpicDeltas(
+  data: DataLayer,
+  planKey: string,
+): Promise<EpicDeltaReport> {
+  const deltas = await readTaskDeltas(data, planKey);
+  const files = new Set<string>();
+  const affected = new Set<string>();
+  const contractChanges: { taskId: string; change: string }[] = [];
+  const constraints: { taskId: string; constraint: string }[] = [];
+  for (const d of deltas) {
+    for (const f of d.newlyTouches) files.add(f);
+    for (const t of d.affectsTasks) affected.add(t);
+    if (d.contractChange) contractChanges.push({ taskId: d.taskId, change: d.contractChange });
+    if (d.constraint) constraints.push({ taskId: d.taskId, constraint: d.constraint });
+  }
+  return {
+    deltas,
+    touchedFiles: [...files].sort(),
+    affectedTasks: [...affected].sort(),
+    contractChanges,
+    constraints,
+  };
+}

package/app/trialMerge.test.ts

@@ -0,0 +1,15 @@
+import { assertEquals } from "jsr:@std/assert@1";
+import { shouldRunTrialMerge, trialMergeDecision } from "./trialMerge.ts";
+
+Deno.test("trialMergeDecision only escalates clean-merge suite failures", () => {
+  assertEquals(trialMergeDecision("clean"), "proceed");
+  assertEquals(trialMergeDecision("merge-conflict"), "proceed");
+  assertEquals(trialMergeDecision("suite-failed"), "escalate");
+});
+
+Deno.test("shouldRunTrialMerge skips lone heads and mergify queues", () => {
+  assertEquals(shouldRunTrialMerge(0, { land: { method: "gh-merge" } }), false);
+  assertEquals(shouldRunTrialMerge(1, { land: { method: "gh-merge" } }), false);
+  assertEquals(shouldRunTrialMerge(2, { land: { method: "mergify-queue" } }), false);
+  assertEquals(shouldRunTrialMerge(2, { land: { method: "gh-merge" } }), true);
+});

package/app/trialMerge.ts

@@ -0,0 +1,102 @@
+// Trial-merge integration gate (D3, issue #69).
+//
+// D3 catches semantic conflicts between concurrently-open PR heads: if they merge cleanly but the
+// target repo's combined suite fails, a human/agent design decision is required. Textual merge
+// conflicts are explicitly pass-through because D2/D6 own merge-exclusion and merge-train ordering.
+import type { DataLayer } from "@nanobpm/urban";
+import type { MergeProtocol } from "./mergeProtocol.ts";
+
+const now = () => new Date().toISOString();
+
+export type TrialMergeResult = "clean" | "merge-conflict" | "suite-failed";
+export type TrialMergeDecision = "proceed" | "escalate";
+
+export interface TrialMergeHead {
+  repo: string;
+  prNumber: number | string;
+  headRef?: string;
+  headSha?: string;
+}
+
+export interface TrialMergeAuditRow {
+  id: number;
+  plan_key: string;
+  wave: number;
+  result: TrialMergeResult;
+  heads: string | null;
+  conflicts: string | null;
+  failing: string | null;
+  summary: string | null;
+  job_key: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export const TRIAL_MERGE_TASK_PREFIX = "trial-merge-wave-";
+
+export function trialMergeDecision(result: TrialMergeResult): TrialMergeDecision {
+  return result === "suite-failed" ? "escalate" : "proceed";
+}
+
+export function shouldRunTrialMerge(headCount: number, protocol: Pick<MergeProtocol, "land">): boolean {
+  return headCount >= 2 && protocol.land.method !== "mergify-queue";
+}
+
+export function trialMergeTaskId(wave: number): string {
+  return `${TRIAL_MERGE_TASK_PREFIX}${Math.max(0, Math.trunc(wave))}`;
+}
+
+const auditTable = (data: DataLayer) => data.table<TrialMergeAuditRow>("plan_trial_merges", "id");
+
+function jsonOrNull(v: unknown): string | null {
+  if (v == null) return null;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return JSON.stringify(String(v));
+  }
+}
+
+export async function recordTrialMergeAudit(
+  data: DataLayer,
+  row: {
+    planKey: string;
+    wave: number;
+    result: TrialMergeResult;
+    heads?: unknown;
+    conflicts?: unknown;
+    failing?: unknown;
+    summary?: string | null;
+    jobKey?: string | null;
+  },
+): Promise<number> {
+  const ts = now();
+  const table = auditTable(data);
+  const jobKey = row.jobKey ?? null;
+  if (jobKey) {
+    const existing = (await table.find({ plan_key: row.planKey, job_key: jobKey })).sort((a, b) => b.id - a.id)[0];
+    if (existing) {
+      await table.update(existing.id, {
+        result: row.result,
+        heads: jsonOrNull(row.heads),
+        conflicts: jsonOrNull(row.conflicts),
+        failing: jsonOrNull(row.failing),
+        summary: row.summary ?? null,
+        updated_at: ts,
+      });
+      return existing.id;
+    }
+  }
+  return Number(await table.insert({
+    plan_key: row.planKey,
+    wave: row.wave,
+    result: row.result,
+    heads: jsonOrNull(row.heads),
+    conflicts: jsonOrNull(row.conflicts),
+    failing: jsonOrNull(row.failing),
+    summary: row.summary ?? null,
+    job_key: jobKey,
+    created_at: ts,
+    updated_at: ts,
+  }));
+}

package/app/waves.test.ts

@@ -0,0 +1,128 @@
+// Red/green regression for the plan levelizer (issue #20). Run with `deno test`.
+//
+// One `Deno.test` = one named property of computeWaves. These encode the wave
+// contract: independent tasks share wave 0 (all-parallel), a chain steps 0,1,2…
+// (all-sequential), a diamond re-converges, and a malformed graph is rejected
+// rather than silently mis-levelized.
+import { assertEquals, assertThrows } from "jsr:@std/assert@1";
+import { computeWaves, WaveError, type WaveGateTask, type WaveTask, waveMergeTargets } from "./waves.ts";
+
+Deno.test("no dependencies → every task in wave 0 (fully parallel)", () => {
+  const tasks: WaveTask[] = [{ id: "a" }, { id: "b" }, { id: "c" }];
+  const { waves, waveCount } = computeWaves(tasks);
+  assertEquals(waveCount, 1);
+  assertEquals(waves, [["a", "b", "c"]]);
+});
+
+Deno.test("linear chain → one task per wave (fully sequential)", () => {
+  const tasks: WaveTask[] = [
+    { id: "a" },
+    { id: "b", dependsOn: ["a"] },
+    { id: "c", dependsOn: ["b"] },
+  ];
+  const { waves, waveCount, waveOf } = computeWaves(tasks);
+  assertEquals(waveCount, 3);
+  assertEquals(waves, [["a"], ["b"], ["c"]]);
+  assertEquals([waveOf.get("a"), waveOf.get("b"), waveOf.get("c")], [0, 1, 2]);
+});
+
+Deno.test("diamond → longest-path level; join waits for both arms", () => {
+  const tasks: WaveTask[] = [
+    { id: "a" },
+    { id: "b", dependsOn: ["a"] },
+    { id: "c", dependsOn: ["a"] },
+    { id: "d", dependsOn: ["b", "c"] },
+  ];
+  const { waves, waveCount } = computeWaves(tasks);
+  assertEquals(waveCount, 3);
+  assertEquals(waves, [["a"], ["b", "c"], ["d"]]);
+});
+
+Deno.test("mixed graph → level is 1 + max(dep level), not 1 + min", () => {
+  // e depends on a (wave 0) and d (wave 2) → must land in wave 3, behind the deeper dep.
+  const tasks: WaveTask[] = [
+    { id: "a" },
+    { id: "b", dependsOn: ["a"] },
+    { id: "c", dependsOn: ["b"] },
+    { id: "d", dependsOn: ["c"] },
+    { id: "e", dependsOn: ["a", "d"] },
+  ];
+  const { waveOf, waveCount } = computeWaves(tasks);
+  assertEquals(waveCount, 5);
+  assertEquals(waveOf.get("e"), 4);
+});
+
+Deno.test("empty plan → zero waves", () => {
+  const { waves, waveCount } = computeWaves([]);
+  assertEquals(waveCount, 0);
+  assertEquals(waves, []);
+});
+
+Deno.test("blank / whitespace dependsOn entries are ignored", () => {
+  const tasks: WaveTask[] = [{ id: "a", dependsOn: ["", "  "] }];
+  const { waves, waveCount } = computeWaves(tasks);
+  assertEquals(waveCount, 1);
+  assertEquals(waves, [["a"]]);
+});
+
+Deno.test("dependency cycle → WaveError", () => {
+  const tasks: WaveTask[] = [
+    { id: "a", dependsOn: ["b"] },
+    { id: "b", dependsOn: ["a"] },
+  ];
+  assertThrows(() => computeWaves(tasks), WaveError, "cycle");
+});
+
+Deno.test("self-dependency → WaveError", () => {
+  assertThrows(() => computeWaves([{ id: "a", dependsOn: ["a"] }]), WaveError, "itself");
+});
+
+Deno.test("unknown dependency id → WaveError", () => {
+  assertThrows(
+    () => computeWaves([{ id: "a", dependsOn: ["ghost"] }]),
+    WaveError,
+    "unknown task",
+  );
+});
+
+Deno.test("duplicate task id → WaveError", () => {
+  assertThrows(
+    () => computeWaves([{ id: "a" }, { id: "a" }]),
+    WaveError,
+    "duplicate",
+  );
+});
+
+// --- Wave-merge barrier: which PRs must merge for a wave to clear? ---
+// `waveMergeTargets` drives the poller's `wave-merged` gate. It must select exactly the
+// opened/waiting-with-a-PR tasks of the gate wave, ignore other waves, and treat blocked/skipped
+// and keyless tasks as nothing-to-wait-on so no non-mergeable PR state can wedge the barrier.
+
+Deno.test("waveMergeTargets → only opened PRs of the gate wave", () => {
+  const tasks: WaveGateTask[] = [
+    { wave: 0, status: "opened", pr_key: "o/r#1" },
+    { wave: 0, status: "opened", pr_key: "o/r#2" },
+    { wave: 1, status: "opened", pr_key: "o/r#9" }, // a later wave — not this gate
+  ];
+  assertEquals(waveMergeTargets(tasks, 0), ["o/r#1", "o/r#2"]);
+});
+
+Deno.test("waveMergeTargets → mergeable waiting tasks are waited on; failed/keyless tasks are not", () => {
+  const tasks: WaveGateTask[] = [
+    { wave: 0, status: "opened", pr_key: "o/r#1" },
+    { wave: 0, status: "blocked", pr_key: null },
+    { wave: 0, status: "skipped", pr_key: null },
+    { wave: 0, status: "waiting-for-lane", pr_key: "o/r#2" },
+    { wave: 0, status: "waiting-for-lane", pr_key: null },
+    { wave: 0, status: "opened", pr_key: null }, // opened but no PR key → nothing to merge
+  ];
+  assertEquals(waveMergeTargets(tasks, 0), ["o/r#1", "o/r#2"]);
+});
+
+Deno.test("waveMergeTargets → a wave with no opened PRs clears vacuously (empty)", () => {
+  const tasks: WaveGateTask[] = [
+    { wave: 0, status: "blocked", pr_key: null },
+    { wave: 0, status: "skipped", pr_key: null },
+  ];
+  assertEquals(waveMergeTargets(tasks, 0), []);
+});

package/app/waves.ts

@@ -0,0 +1,116 @@
+// nano-workforce — plan levelizer (issue #20).
+//
+// The planner may emit tasks with an optional `dependsOn: [taskId, ...]` DAG.
+// This module turns that DAG into ordered **waves**: `wave(t) = 0` if the task has
+// no dependencies, else `1 + max(wave(dep))` (the longest-path level). The
+// `plan-fanout` process then runs its parallel multi-instance `implement` activity
+// once per wave, in order — so independent tasks in the same wave run in parallel,
+// while a dependent task waits for the wave containing all its dependencies.
+//
+// Pure and side-effect free: it does no I/O and is the red/green regression target
+// (app/waves.test.ts). The workers (record-plan) call it to assign `plan_tasks.wave`.
+
+/** A task as seen by the levelizer: a stable id and its (optional) dependency ids. */
+export interface WaveTask {
+  id: string;
+  dependsOn?: readonly string[];
+}
+
+export interface WaveResult {
+  /** 0-based wave index per task id (longest-path level). */
+  waveOf: Map<string, number>;
+  /** Task ids grouped by wave, in wave order; input order preserved within a wave. */
+  waves: string[][];
+  /** Number of waves (0 for an empty plan). */
+  waveCount: number;
+}
+
+/** Thrown when the task graph is not a valid DAG (self-loop, cycle, dangling dep, or
+ *  a duplicate task id) — the plan cannot be levelized and must be rejected. */
+export class WaveError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WaveError";
+  }
+}
+
+/**
+ * Levelize a task DAG into ordered waves. Throws {@link WaveError} on a duplicate
+ * task id, an unknown dependency id, a self-dependency, or a dependency cycle.
+ */
+export function computeWaves(tasks: readonly WaveTask[]): WaveResult {
+  const ids = new Set<string>();
+  for (const t of tasks) {
+    if (ids.has(t.id)) throw new WaveError(`duplicate task id "${t.id}"`);
+    ids.add(t.id);
+  }
+
+  const depsOf = new Map<string, string[]>();
+  for (const t of tasks) {
+    const deps: string[] = [];
+    for (const raw of t.dependsOn ?? []) {
+      const d = raw.trim();
+      if (d === "") continue;
+      if (d === t.id) throw new WaveError(`task "${t.id}" depends on itself`);
+      if (!ids.has(d)) throw new WaveError(`task "${t.id}" depends on unknown task "${d}"`);
+      deps.push(d);
+    }
+    depsOf.set(t.id, deps);
+  }
+
+  const waveOf = new Map<string, number>();
+  const visiting = new Set<string>();
+  const level = (id: string): number => {
+    const cached = waveOf.get(id);
+    if (cached !== undefined) return cached;
+    if (visiting.has(id)) throw new WaveError(`dependency cycle detected at task "${id}"`);
+    visiting.add(id);
+    let lvl = 0;
+    for (const dep of depsOf.get(id) ?? []) lvl = Math.max(lvl, level(dep) + 1);
+    visiting.delete(id);
+    waveOf.set(id, lvl);
+    return lvl;
+  };
+  for (const t of tasks) level(t.id);
+
+  let waveCount = 0;
+  for (const lvl of waveOf.values()) waveCount = Math.max(waveCount, lvl + 1);
+
+  const waves: string[][] = [];
+  for (let i = 0; i < waveCount; i++) waves.push([]);
+  for (const t of tasks) {
+    const w = waveOf.get(t.id) ?? 0;
+    waves[w].push(t.id);
+  }
+
+  return { waveOf, waves, waveCount };
+}
+
+/** A `plan_tasks` row as seen by the wave-merge barrier: its levelized wave, its dispatch
+ * status, and the PR it produced (if any). Structurally a subset of `PlanTask` (app/plan.ts). */
+export interface WaveGateTask {
+  wave: number | null;
+  status: string;
+  pr_key: string | null;
+}
+
+/** The PR keys that must MERGE for `gateWave` to clear the wave-merge barrier: the PRs opened by
+ * that wave's tasks. `opened` tasks and `waiting-for-lane` tasks with PR keys produced a PR to
+ * wait on — `blocked`/`skipped` tasks can never merge and must not wedge the barrier, and keyless
+ * tasks are treated as having nothing to wait on.
+ *
+ * Pure and side-effect free (like {@link computeWaves}) so the poller's gate decision is a
+ * red/green regression target: the poller releases the next wave iff every key returned here has
+ * merged. An empty result means the wave clears vacuously (nothing to merge). */
+export function waveMergeTargets(
+  tasks: readonly WaveGateTask[],
+  gateWave: number,
+): string[] {
+  const keys: string[] = [];
+  for (const t of tasks) {
+    if (t.wave !== gateWave) continue;
+    if ((t.status !== "opened" && t.status !== "waiting-for-lane") || !t.pr_key) continue;
+    keys.push(t.pr_key);
+  }
+  return keys;
+}