@nanobpm/nano-workforce 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.59.0](https://github.com/nanobpm/nano-workforce/compare/v0.58.1...v0.59.0) (2026-08-13)
+
+
+### Features
+
+* derive epic delivery signal (converging vs landed) ([#197](https://github.com/nanobpm/nano-workforce/issues/197)) ([39ab5f1](https://github.com/nanobpm/nano-workforce/commit/39ab5f1b2628aadd350e9043ab0114103a24a1e2)), closes [#171](https://github.com/nanobpm/nano-workforce/issues/171) [#171](https://github.com/nanobpm/nano-workforce/issues/171)
+
+## [0.58.1](https://github.com/nanobpm/nano-workforce/compare/v0.58.0...v0.58.1) (2026-08-13)
+
+
+### Bug Fixes
+
+* regenerate nano-generated/ before start (prestart: urban gen) ([#195](https://github.com/nanobpm/nano-workforce/issues/195)) ([d45fe22](https://github.com/nanobpm/nano-workforce/commit/d45fe22de58766730721f51cbcb7e97d6f4f06c8)), closes [#192](https://github.com/nanobpm/nano-workforce/issues/192)
+
 # [0.58.0](https://github.com/nanobpm/nano-workforce/compare/v0.57.0...v0.58.0) (2026-08-13)
 
 

package/app/delivery.test.ts

@@ -0,0 +1,174 @@
+// Read-model derivation test for the epic delivery signal (issue #171). `deriveDelivery` is the
+// single source of truth for the denormalised `plans.delivery` / `plans.delivery_label` columns the
+// poller projects. It must cleanly distinguish an epic whose fan-out is `done` but whose slices are
+// still CONVERGING from one where every slice PR has LANDED, and count abandoned/converged PRs as
+// resolved-not-landed (never `landed`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { deriveDelivery, pollDelivery, TERMINAL_STATUSES } from "./service.ts";
+
+// A tiny in-memory record gateway (all/find/update/insert), mirroring the fake-app style used
+// across the app tests (see app/taskDelta.test.ts), enough to exercise the `pollDelivery` projection.
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+test("all slice PRs merged -> landed", () => {
+  const r = deriveDelivery("done", ["merged", "merged", "merged"]);
+  assertEquals(r.delivery, "landed");
+  assertEquals(r.prsOpened, 3);
+  assertEquals(r.prsMerged, 3);
+  assertEquals(r.prsInFlight, 0);
+  assertEquals(r.label, "3/3 slices merged");
+});
+
+test("one slice PR still in flight -> converging", () => {
+  const r = deriveDelivery("done", ["merged", "converging", "merged"]);
+  assertEquals(r.delivery, "converging");
+  assertEquals(r.prsOpened, 3);
+  assertEquals(r.prsMerged, 2);
+  assertEquals(r.prsInFlight, 1);
+  assertEquals(r.label, "2/3 slices merged, 1 converging");
+});
+
+test("mixed merged/abandoned (all terminal, not all merged) -> resolved-not-landed (null)", () => {
+  const r = deriveDelivery("done", ["merged", "abandoned", "merged"]);
+  assertEquals(r.delivery, null);
+  assertEquals(r.label, null);
+  assertEquals(r.prsOpened, 3);
+  assertEquals(r.prsMerged, 2);
+  // abandoned is terminal, so it is NOT counted as in flight.
+  assertEquals(r.prsInFlight, 0);
+});
+
+test("a converged (review-only, unmerged) slice keeps the epic out of landed", () => {
+  // `converged` is terminal but not `merged`: resolved-not-landed, like abandoned.
+  const r = deriveDelivery("done", ["merged", "converged"]);
+  assertEquals(r.delivery, null);
+  assertEquals(r.prsInFlight, 0);
+  assertEquals(r.prsMerged, 1);
+});
+
+test("plan not yet done -> no delivery signal even with slice PRs", () => {
+  for (const status of ["planning", "dispatched"]) {
+    const r = deriveDelivery(status, ["merged", "converging"]);
+    assertEquals(r.delivery, null, `status=${status}`);
+    assertEquals(r.label, null, `status=${status}`);
+  }
+});
+
+test("done but zero slice PRs -> no delivery signal", () => {
+  const r = deriveDelivery("done", []);
+  assertEquals(r.delivery, null);
+  assertEquals(r.prsOpened, 0);
+});
+
+test("a single in-flight slice on a done plan is converging, not landed", () => {
+  const r = deriveDelivery("done", ["waiting_review"]);
+  assertEquals(r.delivery, "converging");
+  assertEquals(r.label, "0/1 slices merged, 1 converging");
+});
+
+test("every non-terminal status counts as in flight", () => {
+  const inFlight = ["converging", "waiting_review", "escalated", "queued", "open", "opened"];
+  for (const s of inFlight) {
+    assert(!TERMINAL_STATUSES.includes(s), `${s} must not be terminal`);
+    const r = deriveDelivery("done", [s]);
+    assertEquals(r.delivery, "converging", `status ${s}`);
+    assertEquals(r.prsInFlight, 1, `status ${s}`);
+  }
+});
+
+test("pollDelivery: a dangling pr_key (missing PR row) counts as in-flight, never false-landed", async () => {
+  const { data, stores } = memData();
+  stores.plans = [
+    { plan_key: "epic-1", status: "done", delivery: null, delivery_label: null },
+  ];
+  stores.plan_tasks = [
+    { id: 1, plan_key: "epic-1", pr_key: "o/r#1" },
+    { id: 2, plan_key: "epic-1", pr_key: "o/r#2" }, // no matching pull_requests row (DB desync)
+  ];
+  stores.pull_requests = [{ pr_key: "o/r#1", status: "merged" }];
+
+  await pollDelivery(data);
+
+  // Without the dangling PR being treated as in-flight, this would wrongly become `landed` (1/1).
+  assertEquals(stores.plans[0].delivery, "converging");
+  assertEquals(stores.plans[0].delivery_label, "1/2 slices merged, 1 converging");
+});
+
+test("pollDelivery: all slice PR rows present and merged -> landed", async () => {
+  const { data, stores } = memData();
+  stores.plans = [
+    { plan_key: "epic-2", status: "done", delivery: null, delivery_label: null },
+  ];
+  stores.plan_tasks = [
+    { id: 1, plan_key: "epic-2", pr_key: "o/r#10" },
+    { id: 2, plan_key: "epic-2", pr_key: "o/r#11" },
+  ];
+  stores.pull_requests = [
+    { pr_key: "o/r#10", status: "merged" },
+    { pr_key: "o/r#11", status: "merged" },
+  ];
+
+  await pollDelivery(data);
+
+  assertEquals(stores.plans[0].delivery, "landed");
+  assertEquals(stores.plans[0].delivery_label, "2/2 slices merged");
+});
+
+test("pollDelivery: a non-done plan is skipped and any stale projection is cleared", async () => {
+  const { data, stores } = memData();
+  stores.plans = [
+    // Regressed out of `done` while carrying a stale `converging` projection.
+    { plan_key: "epic-3", status: "in_progress", delivery: "converging", delivery_label: "1/2 slices merged, 1 converging" },
+  ];
+  // A task join here would be wasted work for a non-done plan; assert it is never consulted.
+  let taskLookups = 0;
+  stores.plan_tasks = [{ id: 1, plan_key: "epic-3", pr_key: "o/r#20" }];
+  stores.pull_requests = [{ pr_key: "o/r#20", status: "merged" }];
+  const origTable = (data as any).table.bind(data);
+  (data as any).table = (n: string, pk?: string) => {
+    const t = origTable(n, pk);
+    if (n === "plan_tasks") {
+      const origFind = t.find.bind(t);
+      t.find = async (where: any) => {
+        taskLookups++;
+        return origFind(where);
+      };
+    }
+    return t;
+  };
+
+  await pollDelivery(data);
+
+  assertEquals(stores.plans[0].delivery, null);
+  assertEquals(stores.plans[0].delivery_label, null);
+  assertEquals(taskLookups, 0);
+});

package/app/plan.ts

@@ -72,6 +72,13 @@ export interface Plan {
   // admission); the column stays NULLABLE ONLY to grandfather pre-ADR-0003 / in-flight rows that
   // carry NULL — those must remain readable, so do NOT add a NOT NULL migration.
   base_branch: string | null;
+  // Derived epic delivery signal (029_plan_delivery.sql, #171): separates "fan-out dispatched to
+  // convergence" (status=done) from "all slice PRs actually merged". Recomputed idempotently by the
+  // poller's `pollDelivery` pass by joining each plan_tasks.pr_key → pull_requests.status — never
+  // written by the plan lifecycle. `delivery` is 'converging' | 'landed' | NULL (see deriveDelivery
+  // in app/service.ts); `delivery_label` is the human rollup for the epic detail view. Display-only.
+  delivery: string | null;
+  delivery_label: string | null;
   created_at: string;
   updated_at: string;
 }

package/app/service.ts

@@ -99,6 +99,70 @@ const now = () => new Date().toISOString();
  * guard both key off this set. */
 export const TERMINAL_STATUSES: readonly string[] = ["converged", "merged", "abandoned"];
 
+/** The derived epic delivery signal (issue #171). Distinct from `plan.status`: `status = done`
+ * means "the fan-out finished and ≥1 slice opened a PR, dispatched to convergence" (record-results
+ * sets it as soon as one PR opened — other slices may be blocked/skipped), which conflates hand-off
+ * with landing. `delivery` reports whether those slice PRs have actually MERGED. */
+export type Delivery = "converging" | "landed";
+
+/** Rollup of a plan's slice-PR landing state, derived by joining `plan_tasks.pr_key` →
+ * `pull_requests.status`. Pure and read-only — the single source of truth for the denormalised
+ * `plans.delivery` / `plans.delivery_label` columns the poller projects. */
+export interface DeliveryRollup {
+  delivery: Delivery | null;
+  label: string | null;
+  prsOpened: number;
+  prsMerged: number;
+  prsInFlight: number;
+}
+
+/** Derive the delivery signal for one plan from its status and the statuses of its slice PRs.
+ *
+ * - `converging` — the plan is `done` but ≥1 slice PR is still non-terminal (in flight).
+ * - `landed` — every slice PR merged: `prsInFlight == 0 && prsMerged == prsOpened && prsOpened > 0`.
+ * - `null` — no positive signal yet: the plan isn't `done`, it opened no PRs, or every PR is
+ *   terminal but not all merged (some `abandoned`/`converged` — resolved-not-landed, per the issue).
+ *
+ * A slice's PR status is "in flight" iff it is NOT in `TERMINAL_STATUSES`; `abandoned`/`converged`
+ * count as resolved-not-landed (terminal but not merged), so they never make an epic `landed`. */
+export function deriveDelivery(
+  planStatus: string,
+  prStatuses: readonly string[],
+): DeliveryRollup {
+  const prsOpened = prStatuses.length;
+  let prsMerged = 0;
+  let prsInFlight = 0;
+  for (const s of prStatuses) {
+    if (s === "merged") prsMerged++;
+    else if (!TERMINAL_STATUSES.includes(s)) prsInFlight++;
+  }
+  // `delivery` is only meaningful once the fan-out has been dispatched (`status = done`) and at
+  // least one slice PR exists; otherwise there is nothing to have landed yet.
+  if (planStatus !== "done" || prsOpened === 0) {
+    return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
+  }
+  if (prsInFlight > 0) {
+    return {
+      delivery: "converging",
+      label: `${prsMerged}/${prsOpened} slices merged, ${prsInFlight} converging`,
+      prsOpened,
+      prsMerged,
+      prsInFlight,
+    };
+  }
+  if (prsMerged === prsOpened) {
+    return {
+      delivery: "landed",
+      label: `${prsOpened}/${prsOpened} slices merged`,
+      prsOpened,
+      prsMerged,
+      prsInFlight,
+    };
+  }
+  // Every slice PR is terminal but not all merged (some abandoned/converged): resolved, not landed.
+  return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
+}
+
 interface PullRequest {
   pr_key: string;
   repo: string;
@@ -1132,6 +1196,58 @@ async function pollWaveGates(data: DataLayer, engine: EngineClient, token: strin
   }
 }
 
+/** Idempotent read-model pass: recompute each plan's derived `delivery` signal (issue #171) by
+ * joining its slice tasks' `pr_key` → `pull_requests.status`, and denormalise it onto the `plans`
+ * row so the epics overview / detail views can read it as a flat column (Urban's datasource can't
+ * read a SQL VIEW). Never touches `plan.status` — additive/derived only. Writes only when the
+ * projection actually changes, so a steady-state pass is a no-op. */
+/** Sentinel status fed to `deriveDelivery` for a `plan_tasks.pr_key` whose `pull_requests` row is
+ * missing (DB desync). It is deliberately non-terminal and not `merged`, so a dangling PR counts as
+ * in-flight — never a false-positive `landed` from a silently-dropped slice. */
+const MISSING_PR_STATUS = "missing";
+
+export async function pollDelivery(data: DataLayer) {
+  // Preload every PR status once per pass into a pr_key→status map (avoids the prior N+1
+  // `prs(data).get` per task; mirrors how `activePrs` reads `prs(data).all()` once).
+  const statusByPrKey = new Map<string, string>();
+  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  for (const plan of await plans(data).all()) {
+    try {
+      // `deriveDelivery` always yields `{null, null}` for a non-`done` plan, so skip the per-plan
+      // task join for those — but still clear any stale projection defensively (e.g. a plan that
+      // regressed out of `done`) so the read model never keeps a phantom `converging`/`landed`.
+      if (plan.status !== "done") {
+        if (plan.delivery !== null || plan.delivery_label !== null) {
+          await plans(data).update(plan.plan_key, {
+            delivery: null,
+            delivery_label: null,
+            updated_at: now(),
+          });
+        }
+        continue;
+      }
+      const tasks = await planTasks(data).find({ plan_key: plan.plan_key });
+      const prStatuses: string[] = [];
+      for (const t of tasks) {
+        if (!t.pr_key) continue;
+        // A dangling pr_key (row missing) is treated as in-flight, not dropped, so a DB desync
+        // can never wrongly promote an epic to `landed`.
+        prStatuses.push(statusByPrKey.get(t.pr_key) ?? MISSING_PR_STATUS);
+      }
+      const { delivery, label } = deriveDelivery(plan.status, prStatuses);
+      if (plan.delivery !== delivery || plan.delivery_label !== label) {
+        await plans(data).update(plan.plan_key, {
+          delivery,
+          delivery_label: label,
+          updated_at: now(),
+        });
+      }
+    } catch (err) {
+      console.error(`[poller] delivery ${plan.plan_key}: ${err}`);
+    }
+  }
+}
+
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
  * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
@@ -1144,6 +1260,7 @@ export async function pollOnce(
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollWaveGates(data, engine, token);
+  await pollDelivery(data);
   if (engineRest) {
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);

package/db/migrations/029_plan_delivery.sql

@@ -0,0 +1,29 @@
+-- Derived epic delivery signal: separate "fan-out dispatched to convergence" from "all slice
+-- PRs actually merged" (issue #171).
+--
+-- `plans.status = done` means "the fan-out finished and ≥1 slice opened a PR and was handed off to
+-- convergence" (record-results marks it as soon as one PR opened — other slices may be
+-- blocked/skipped), NOT "every PR merged". Convergence + merge
+-- then run as separate async per-PR processes, so a `done` epic can still have slice PRs in
+-- flight. That conflation is misleading on the epics overview.
+--
+-- We leave `plans.status` untouched (automation depends on `done` == dispatched) and add a
+-- DERIVED delivery signal, computed by joining each `plan_tasks.pr_key` → `pull_requests.status`.
+-- Urban's datasource cannot read a SQL VIEW (gateway.ts schema() whitelists only type='table'),
+-- so — following the codebase convention for read-model projections onto `plans` (wave_label,
+-- gate_wave, …) — the poller denormalises two flat columns, recomputed idempotently each pass:
+--
+--   • delivery       — the derived signal, one of:
+--                        'converging' — plan `done` but ≥1 slice PR still non-terminal.
+--                        'landed'     — every slice PR merged (prs_in_flight == 0 &&
+--                                       prs_merged == prs_opened && prs_opened > 0).
+--                      NULL when there is no positive signal yet: the plan is not `done`, it
+--                      opened no PRs, or every PR is terminal but not all merged (some
+--                      abandoned/converged — resolved-not-landed). `landed` is the honest
+--                      "epic delivered" state and the precondition for ready-to-promote (#160).
+--   • delivery_label — the human rollup for the epic detail view, e.g.
+--                      "4/5 slices merged, 1 converging". NULL when delivery is NULL.
+--
+-- Additive/derived only: no new writes to the plan lifecycle (`status`).
+ALTER TABLE plans ADD COLUMN delivery TEXT;
+ALTER TABLE plans ADD COLUMN delivery_label TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -28,6 +28,7 @@
     "access": "public"
   },
   "scripts": {
+    "prestart": "urban gen",
     "start": "node --experimental-strip-types main.ts",
     "purge": "node --experimental-strip-types scripts/purge-db.ts",
     "upgrade": "node --experimental-strip-types scripts/upgrade-from-pack.ts",

package/pages/epic-detail.page.json

@@ -55,6 +55,7 @@
         "columns": [
           { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "delivery", "header": "Delivery" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
           { "field": "updated_at", "header": "Updated" }
@@ -65,6 +66,7 @@
             { "field": "repo", "label": "Repository" },
             { "field": "issue_number", "label": "Issue number" },
             { "field": "base_branch", "label": "Base branch (blank = repo default)" },
+            { "field": "delivery_label", "label": "Delivery rollup (slices merged / converging)" },
             { "field": "outcome", "label": "Outcome" }
           ]
         }

package/pages/epic.page.json

@@ -73,6 +73,7 @@
         "columns": [
           { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "delivery", "header": "Delivery" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },

package/prompts/feature.md

@@ -142,3 +142,12 @@ inside its slice. Use:
 - `constraint` — a constraint you discovered that changes another task's direction.
 
 This is advisory context, not an escalation — it never blocks you or anyone else.
+
+If the repo has an **append-ordered namespace** — files chosen by "the next"
+monotonic value (DB migration prefixes, ADR numbers, changelog fragments,
+ordered fixtures) — `file-claim` your intended slot on the coordination
+blackboard *before* authoring, and read existing claims first. Parallel siblings
+otherwise pick the same value and collide silently (names don't textually
+conflict, so git merges both). This is advisory best-effort; the repo's own CI
+gate, if any, remains the guarantee. Check the repo's AGENTS.md for which
+namespaces are ordered.