@nanobpm/nano-workforce 0.162.1 → 0.163.0

package/test/reconcileDb.ts

@@ -0,0 +1,61 @@
+// A test-only DataLayer over a real in-memory `node:sqlite` db with the WHOLE migration set applied,
+// for exercising the engine-reset reconciliation surface (`app/reconcile.ts`, issue #622) and its
+// operator-command delegate (`operations/reconcileEngineState.ts`) against the REAL shipping schema —
+// so the tables/columns/indexes reconcile reads and writes are exactly what deploys, not a fake.
+//
+// Canonical harness shared by `app/reconcile.test.ts` and `operations/reconcileEngineState.test.ts`
+// (derivation over duplication: one in-memory DataLayer builder, not two divergent copies).
+import { readdirSync, readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach } from "node:test";
+import { fileURLToPath } from "node:url";
+import { type DataLayer, makeGateway, type SqliteDb } from "@nanobpm/urban";
+import { applyMigrationSet } from "#test-migrations";
+
+const MIGRATIONS_DIR = fileURLToPath(new URL("../db/migrations", import.meta.url));
+
+// Every raw handle `freshData()` opens is tracked here and released after each test, so call sites
+// (all of them) don't leak native SQLite handles across the run. Mirrors `test/worldDb.ts` and
+// `test/blackboardDb.ts` (derivation over duplication: the same auto-close idiom, not a new one).
+const openDbs = new Set<DatabaseSync>();
+afterEach(() => {
+  for (const raw of openDbs) {
+    if (openDbs.delete(raw)) raw.close();
+  }
+});
+
+/** Adapt a raw `node:sqlite` handle to urban's tiny `SqliteDb` seam so `makeGateway` yields the real
+ *  record-oriented `DataSource` reconcile binds to (no fakes — the shipping gateway). */
+export function sqliteDb(raw: DatabaseSync): SqliteDb {
+  return {
+    exec: (sql) => raw.exec(sql),
+    run: (sql, params = []) => {
+      const r = raw.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      raw.prepare(sql).all(...(params as never[])) as T[],
+    close: () => raw.close(),
+  };
+}
+
+export function readMigrationFiles(): { name: string; sql: string }[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((n) => n.endsWith(".sql"))
+    .map((name) => ({ name, sql: readFileSync(`${MIGRATIONS_DIR}/${name}`, "utf8") }));
+}
+
+/** A DataLayer over a fresh in-memory DB with the whole migration set applied. The raw handle is
+ *  tracked and auto-closed after each test (see `openDbs`), and FK enforcement is enabled so the
+ *  migrations are exercised under the real constraints they ship with. */
+export function freshData(): { data: DataLayer; raw: DatabaseSync } {
+  const raw = new DatabaseSync(":memory:");
+  openDbs.add(raw);
+  // SQLite disables FK enforcement by default; enable it so migrations with foreign keys are
+  // exercised (and any FK violations surface) exactly as they would on the shipping schema.
+  raw.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(raw, readMigrationFiles());
+  const gw = makeGateway(sqliteDb(raw));
+  const data = { open: () => gw } as unknown as DataLayer;
+  return { data, raw };
+}

package/workers/record-plan/worker.test.ts

@@ -61,7 +61,7 @@ function fakeApp() {
 
 test("record-plan dispatches a taskful plan and levelizes its tasks (wave progress is now VIEW-derived)", async () => {
   const { app, plans } = fakeApp();
-  await handler(
+  const out = await handler(
     {
       variables: {
         planKey: "owner/repo#137",
@@ -74,6 +74,8 @@ test("record-plan dispatches a taskful plan and levelizes its tasks (wave progre
     app,
   );
   assertEquals(plans[0].status, "dispatched");
+  // taskCount drives the plan-fanout gateway (`gw-plan-empty`): non-zero ⇒ proceed to review (#623).
+  assertEquals((out as any).taskCount, 2);
   // Wave progress (wave_count/current_wave/wave_label) was retired as a stored projection (epic
   // #412) — it is derived from `plan_tasks` by the plan_wave_label/plan_read_model VIEWs — so
   // record-plan no longer writes it onto the plans row.
@@ -84,11 +86,15 @@ test("record-plan dispatches a taskful plan and levelizes its tasks (wave progre
 
 test("record-plan marks a taskless plan done (no wave-progress columns written)", async () => {
   const { app, plans } = fakeApp();
-  await handler(
+  const out = await handler(
     { variables: { planKey: "owner/repo#137", tasks: [], note: "planner emitted no tasks" } } as any,
     app,
   );
   assertEquals(plans[0].status, "done");
+  // taskCount 0 routes the plan-fanout gateway (`gw-plan-empty`) to the terminal taskless-done arm,
+  // short-circuiting the adversarial plan-review loop that would otherwise livelock (issue #623).
+  assertEquals((out as any).taskCount, 0);
+  assertEquals(plans[0].outcome, "planner emitted no tasks");
   assertEquals(plans[0].wave_count, undefined);
   assertEquals(plans[0].current_wave, undefined);
   assertEquals(plans[0].wave_label, undefined);

package/workers/record-plan/worker.ts

@@ -38,6 +38,11 @@ interface NormalTask {
 interface Out extends Record<string, unknown> {
   currentWave: number;
   waveCount: number;
+  // Task count of the recorded plan. The plan-fanout gateway (`gw-plan-empty`) reads this to
+  // SHORT-CIRCUIT an intentionally-empty plan (`{tasks:[]}`) to a terminal taskless-done arm
+  // BEFORE the adversarial plan-review gate (issue #623). Feeding an empty plan into review
+  // caused a plan↔plan-review livelock — it can neither be approved nor produce findings.
+  taskCount: number;
 }
 
 const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
@@ -149,8 +154,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
   await plans(app.data).update(planKey, patch);
 
-  // Kick off the wave loop at wave 0.
-  return { currentWave: 0, waveCount };
+  // Kick off the wave loop at wave 0. `taskCount` lets the BPMN gateway terminate an empty plan
+  // before the review loop (issue #623).
+  return { currentWave: 0, waveCount, taskCount: tasks.length };
 };
 
 export default handler;

package/workers/record-plan-review/worker.test.ts

@@ -65,6 +65,24 @@ test("unapproved, non-final round revises (planApproved=false, no escalation)",
   assertEquals((out as any).planFindings, "fix X");
 });
 
+test("unapproved with EMPTY findings escalates immediately — contentless disapproval is malformed (issue #623)", async () => {
+  // First round of a 3-round cap: NOT the final round, so the old behaviour would revise and loop.
+  // A disapproval with no findings is malformed (findings are required per plan-review.md) and
+  // gives the planner nothing to act on — escalate to a human instead of spinning on re-plan.
+  const app = fakeApp(priorRounds("o/r#2b", 0));
+  const out = await call(app, { planKey: "o/r#2b", approved: false, findings: "" });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, true);
+  assertEquals((out as any).planReviewRound, 0);
+});
+
+test("unapproved with MISSING findings escalates immediately (issue #623)", async () => {
+  const app = fakeApp(priorRounds("o/r#2c", 0));
+  const out = await call(app, { planKey: "o/r#2c", approved: false });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, true);
+});
+
 test("unapproved FINAL round escalates instead of throwing or proceeding", async () => {
   // Seed cap-1 prior rounds so this job is the last permitted round; unapproved ⇒ human escalation.
   const app = fakeApp(priorRounds("o/r#3", MAX_PLAN_REVIEW_ROUNDS - 1));

package/workers/record-plan-review/worker.ts

@@ -17,6 +17,11 @@
 // unhandled incident. Proceeding used to dispatch an un-vetted plan and — when the plan was empty —
 // let the whole epic complete GREEN having done nothing. A missing/ambiguous `approved` is treated
 // as NOT approved (revise until the cap, then escalate).
+//
+// A disapproval with EMPTY findings is malformed (issue #623): plan-review.md REQUIRES findings when
+// `approved` is false. Re-planning against a contentless disapproval gives the planner nothing to
+// act on, so it re-emits the same plan and the loop spins (the plan↔plan-review livelock). This
+// worker escalates such a verdict to a human immediately instead of burning re-plan rounds.
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import {
@@ -109,9 +114,28 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     };
   }
 
-  // Not approved this round. Escalate once the per-epoch round cap is reached (issue #86):
-  // previously the fan-out PROCEEDED regardless, dispatching an un-vetted plan. The round is
-  // 0-based, so `round + 1 >= cap` is the last permitted round.
+  // Not approved this round. A disapproval with EMPTY findings is malformed (issue #623): per
+  // resources/prompts/plan-review.md, findings are REQUIRED when `approved` is false. Re-planning
+  // against a contentless disapproval gives the planner nothing to act on, so it re-emits the same
+  // plan and the loop spins (plan↔plan-review livelock, esp. for an empty plan). Escalate to a human
+  // immediately rather than burning re-plan rounds on a malformed verdict.
+  if (roundFindings === "") {
+    app.log.warn(`record-plan-review: ${planKey} not approved with EMPTY findings — malformed, escalating`, {
+      epoch: recordedEpoch,
+      round,
+    });
+    return {
+      planApproved: false,
+      planEscalated: true,
+      planFindings: roundFindings,
+      planReviewEpoch: recordedEpoch,
+      planReviewRound: round,
+    };
+  }
+
+  // Escalate once the per-epoch round cap is reached (issue #86): previously the fan-out PROCEEDED
+  // regardless, dispatching an un-vetted plan. The round is 0-based, so `round + 1 >= cap` is the
+  // last permitted round.
   if (round + 1 >= MAX_PLAN_REVIEW_ROUNDS) {
     app.log.warn(`record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
       epoch: recordedEpoch,