@nanobpm/nano-workforce 0.111.1 → 0.112.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.112.0](https://github.com/nanobpm/nano-workforce/compare/v0.111.1...v0.112.0) (2026-08-20)
+
+
+### Features
+
+* **plan-fanout:** implement-stage escalation net + Tasks-inbox projection ([#358](https://github.com/nanobpm/nano-workforce/issues/358), [#360](https://github.com/nanobpm/nano-workforce/issues/360)) ([#387](https://github.com/nanobpm/nano-workforce/issues/387)) ([c884074](https://github.com/nanobpm/nano-workforce/commit/c884074ca9266d5a17c44d3a1286bb667b43a73a))
+
 ## [0.111.1](https://github.com/nanobpm/nano-workforce/compare/v0.111.0...v0.111.1) (2026-08-20)
 
 

package/app/escalationTaxonomy.test.ts

@@ -80,7 +80,7 @@ test("merge-protocol: only a `ui` land method is decision-required; the rest are
   }
 });
 
-// --- task (plan-fanout w_gw "escalated?") ---
+// --- task (plan-fanout w_gw "clean terminal?" — the implement-stage escalation net, #360) ---
 
 test("task: status=escalated with an answerable question is decision-required; blank is none", () => {
   assertEquals(classifyEscalation({ kind: "task", question: "which approach?" }), "decision-required");

package/app/escalationTaxonomy.ts

@@ -39,8 +39,10 @@ export type EscalationKind =
   | "dead-end-base"
   // `mergeProtocol` (app/mergeProtocol.ts) — the repo's declared land method.
   | "merge-protocol"
-  // plan-fanout `w_gw` "escalated?" gateway — an implementation agent reported
-  // `status = "escalated"` with a question.
+  // plan-fanout `w_gw` "clean terminal?" gateway — the implement-stage escalation net (issue #360).
+  // Any non-clean-terminal slice outcome routes through the `record-wave-escalation` worker, which
+  // classifies with this kind: the agent's own answerable question passes through, and a no-machine-
+  // readable result (or a blank-question `escalated`) is synthesised into an answerable one.
   | "task";
 
 /** Everything the classifier may need from any raise site. Each field is consumed only by the

package/app/planFanoutCleanTerminal.test.ts

@@ -0,0 +1,40 @@
+// Structural guard for the wave subprocess's "clean terminal?" gateway (w_gw) — the implement-stage
+// escalation net (#358/#360). The whole point of the net is that a slice with NO clean terminal
+// status escalates to a human. The no-result case (implement-task completes with `status`
+// missing/undefined) is EXACTLY what must escalate, so the gateway must not depend on a `not(...)`
+// negation that FEEL leaves `null` for a missing `status` (a null condition takes NO flow and would
+// fall through to the default). We eliminate that failure mode categorically: ESCALATE is the
+// DEFAULT flow and DONE is gated on the closed set of clean terminal statuses — so anything that is
+// not a recognised clean terminal (including a missing/undefined status) escalates, regardless of
+// how the engine evaluates equality against null.
+//
+// Pure text assertions over the committed BPMN (no engine), matching the repo's model-guard style.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+
+const bpmn = readFileSync("resources/processes/plan-fanout.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="w_gw"[^>]*>/)?.[0] ?? "";
+const wDone = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="w_done"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="w_done"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
+const wEscalate = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="w_escalate"[^>]*\/>|<bpmn:sequenceFlow\b[^>]*\bid="w_escalate"[\s\S]*?<\/bpmn:sequenceFlow>/)?.[0] ?? "";
+
+test("w_gw: ESCALATE is the default flow, so a missing/undefined status can never fall through to done", () => {
+  assert(gw, "w_gw gateway must exist");
+  assertStringIncludes(gw, 'default="w_escalate"', "escalate must be the default — the no-result case escalates, never silently completes");
+});
+
+test("w_gw: DONE is gated on the closed set of clean terminal statuses (not a fragile not(...) negation)", () => {
+  assert(wDone, "w_done flow must exist");
+  assertStringIncludes(wDone, "conditionExpression", "the done flow must be conditional, not the default");
+  assertStringIncludes(wDone, 'status = "opened"', "done requires a recognised clean terminal status");
+  assertStringIncludes(wDone, 'status = "blocked"', "done requires a recognised clean terminal status");
+  assertStringIncludes(wDone, 'status = "skipped"', "done requires a recognised clean terminal status");
+});
+
+test("w_gw: the escalate flow carries no condition — it is the unconditional default sink", () => {
+  assert(wEscalate, "w_escalate flow must exist");
+  assert(!wEscalate.includes("conditionExpression"), "escalate is the default flow and must carry no condition");
+  assert(!wEscalate.includes("not("), "escalate must not depend on a not(...) negation that FEEL leaves null for a missing status");
+});

package/app/pollUserTasks.test.ts

@@ -131,6 +131,36 @@ test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait esca
   assertEquals(byKey["ut-pr"].subject_title, "Resolve the reviews");
 });
 
+test("pollUserTasks: projects a feature-escalation that lands on a plan-fanout plan instance (issue #358)", async () => {
+  // plan-fanout embeds each wave slice as a multi-instance `implement` subprocess, so a slice that
+  // escalates parks on the `feature-escalation` user task on the PLAN-ROOT process instance — never on
+  // a standalone `feature_runs` instance. The feature scan above only walks `feature_runs`, so before
+  // #358 the plan scan's hardcoded {plan-review, trial-merge} whitelist silently dropped it and the
+  // escalation was invisible in the Tasks inbox (the instance-19153 orphan). The plan scan must project
+  // EVERY open user-task element in the canonical registry, keyed to the epic (plan) subject, sourcing
+  // the question from the `feature_escalations` audit log the escalate arm writes (keyed by plan_key).
+  const { data, stores } = memData({
+    plans: [
+      { plan_key: "o/r#64", status: "dispatched", process_key: "pp-64", issue_url: "https://github.com/o/r/issues/64", title: "Learn BPMN scaffold" },
+    ],
+    feature_escalations: [
+      { id: 1, feature_key: "o/r#64", question: "the agent returned no machine-readable result — enrol the PR?", created_at: "2025-01-01T00:00:00.000Z", job_key: "j1" },
+    ],
+  });
+  const engine = fakeEngine({ "pp-64": [{ userTaskKey: "ut-embedded-feat", elementId: "feature-escalation" }] });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["ut-embedded-feat"]);
+  assertEquals(byKey["ut-embedded-feat"].element_id, "feature-escalation");
+  assertEquals(byKey["ut-embedded-feat"].kind_label, "Feature escalation");
+  assertEquals(byKey["ut-embedded-feat"].subject_type, "plan");
+  assertEquals(byKey["ut-embedded-feat"].subject_key, "o/r#64");
+  assertEquals(byKey["ut-embedded-feat"].subject_title, "Learn BPMN scaffold");
+  assertEquals(byKey["ut-embedded-feat"].question, "the agent returned no machine-readable result — enrol the PR?");
+});
+
 test("pollUserTasks: projects a merge-loop wait-merge-answer escalation into user_tasks as \"PR merge\"", async () => {
   // During the merge phase a PR's process_key points at its merge-loop instance; the merge escalation
   // parks on a native `wait-merge-answer` userTask (#256) and writes the SAME `escalations` row the
@@ -328,3 +358,181 @@ test("pollUserTasks: an instance whose only task is COMPLETED surfaces no row",
 
   assertEquals(stores.user_tasks ?? [], []);
 });
+
+// ── Engine-first sweep (issue #358) ────────────────────────────────────────────────────────────────
+// When the raw-REST surface is available (production always supplies it), the projection's source of
+// truth for WHICH escalations are open is the ENGINE, not the tracked subject set: every open escalation
+// the engine reports is surfaced — even on an instance NO tracked subject row references (an
+// orphaned/untracked instance, the reported 19153 case) — enriched by a subject row when one exists and
+// by a per-kind fallback when it does not. These drive the sweep over a stubbed Camunda-8
+// `/v2/user-tasks/search`, the raw surface that (unlike the typed `openUserTasks` seam) carries each
+// task's `processInstanceKey`.
+
+/** A single task as the raw Camunda-8 `/v2/user-tasks/search` reports it — carries `processInstanceKey`
+ *  (the typed seam omits it) so the sweep can map a task back to its subject for enrichment. */
+type RawTask = { userTaskKey: string; elementId?: string; processInstanceKey?: string; state?: string };
+
+/** Stub `globalThis.fetch` so `pollUserTasks`' engine-first sweep reads its open tasks from `tasks`.
+ *  Honours the `page.from`/`page.limit` pagination the sweep drives, and 404s any other path so a stray
+ *  call is loud. Returns a restore fn. */
+function stubUserTaskSearch(tasks: RawTask[]): () => void {
+  const orig = globalThis.fetch;
+  // biome-ignore lint/suspicious/noExplicitAny: minimal fetch double for the raw-REST search surface
+  globalThis.fetch = (async (url: string | URL, init?: any) => {
+    const u = String(url);
+    if (!u.endsWith("/user-tasks/search")) return new Response("not found", { status: 404 });
+    const body = JSON.parse(init?.body ?? "{}");
+    const from: number = body?.page?.from ?? 0;
+    const limit: number = body?.page?.limit ?? 100;
+    return new Response(JSON.stringify({ items: tasks.slice(from, from + limit) }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+  return () => {
+    globalThis.fetch = orig;
+  };
+}
+
+const REST = { restAddress: "http://engine.test/v2" };
+
+test("pollUserTasks (engine-first): surfaces an escalation on an UNTRACKED/orphaned instance — the 19153 case (issue #358)", async () => {
+  // No `feature_runs`/`plans`/`pull_requests` row references instance 19153, yet the engine reports its
+  // `feature-escalation` (key 27337) open. Before #358 the subject-tracking-gated scan dropped it and the
+  // operator could never see nor answer it. The engine-first sweep surfaces it, keyed to a stable
+  // non-blank fallback subject (the instance) so the row renders and stays answerable.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "27337", elementId: "feature-escalation", processInstanceKey: "19153", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey), ["27337"]);
+  assertEquals(byKey["27337"].element_id, "feature-escalation");
+  assertEquals(byKey["27337"].kind_label, "Feature escalation");
+  assertEquals(byKey["27337"].subject_type, "feature");
+  assertEquals(byKey["27337"].subject_key, "19153"); // fallback to the instance — non-blank so it renders
+  assertEquals(byKey["27337"].subject_title, "19153");
+  assertEquals(byKey["27337"].question, null); // no tracked audit source for an orphan → null, still listed
+});
+
+test("pollUserTasks (engine-first): orphaned plan-review and PR-wait escalations are surfaced too (issue #358)", async () => {
+  // Same failure class across aggregates: a `plan-review-decision` with no `plans` row and a `wait-answer`
+  // with no `pull_requests` row are each surfaced, bucketed to the aggregate their kind implies.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-orphan-plan", elementId: "plan-review-decision", processInstanceKey: "pi-1", state: "CREATED" },
+    { userTaskKey: "ut-orphan-pr", elementId: "wait-answer", processInstanceKey: "pi-2", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey).sort(), ["ut-orphan-plan", "ut-orphan-pr"]);
+  assertEquals(byKey["ut-orphan-plan"].subject_type, "plan");
+  assertEquals(byKey["ut-orphan-plan"].subject_key, "pi-1");
+  assertEquals(byKey["ut-orphan-pr"].subject_type, "pr");
+  assertEquals(byKey["ut-orphan-pr"].kind_label, "PR review");
+});
+
+test("pollUserTasks (engine-first): a TRACKED task is still fully enriched from its subject row (no regression)", async () => {
+  // Enrich, don't gate: when a subject row DOES reference the task's instance, title/url/question come
+  // from it exactly as the per-subject scan produced — the sweep maps by `processInstanceKey`.
+  const { data, stores } = memData({
+    feature_runs: [
+      { feature_key: "o/r#10", status: "escalated", process_key: "fp-10", issue_url: "https://github.com/o/r/issues/10", title: "Add the framework selector", delivery_label: null },
+    ],
+    feature_escalations: [
+      { id: 1, feature_key: "o/r#10", question: "which framework?", created_at: "2025-01-01T00:00:00.000Z", job_key: "j1" },
+    ],
+    plans: [
+      { plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: "https://github.com/o/r/issues/20", title: "Broaden the epic scope" },
+    ],
+    plan_reviews: [
+      { plan_key: "o/r#20", epoch: 0, round: 1, approved: 0, findings: "scope too broad", created_at: "2025-01-02T00:00:00.000Z" },
+    ],
+  });
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-feat", elementId: "feature-escalation", processInstanceKey: "fp-10", state: "CREATED" },
+    { userTaskKey: "ut-plan", elementId: "plan-review-decision", processInstanceKey: "pp-20", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey).sort(), ["ut-feat", "ut-plan"]);
+  assertEquals(byKey["ut-feat"].subject_key, "o/r#10");
+  assertEquals(byKey["ut-feat"].subject_title, "Add the framework selector");
+  assertEquals(byKey["ut-feat"].question, "which framework?");
+  assertEquals(byKey["ut-plan"].subject_title, "Broaden the epic scope");
+  assertEquals(byKey["ut-plan"].question, "scope too broad");
+});
+
+test("pollUserTasks (engine-first): never leaks a non-escalation element nor a non-CREATED task", async () => {
+  // The `USER_TASK_KIND_LABELS` gate keeps an arbitrary internal user task out of the inbox, and the
+  // defensive state re-filter drops a lagging COMPLETED/CANCELED read (a dead affordance, #294) even if
+  // the wire `state` filter is ignored.
+  const { data, stores } = memData({});
+  const restore = stubUserTaskSearch([
+    { userTaskKey: "ut-internal", elementId: "some-internal-task", processInstanceKey: "pi-9", state: "CREATED" },
+    { userTaskKey: "ut-done", elementId: "feature-escalation", processInstanceKey: "pi-8", state: "COMPLETED" },
+    { userTaskKey: "ut-live", elementId: "feature-escalation", processInstanceKey: "pi-7", state: "CREATED" },
+  ]);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  const keys = (stores.user_tasks ?? []).map((r) => r.user_task_key);
+  assertEquals(keys, ["ut-live"]);
+});
+
+test("pollUserTasks (engine-first): an answered task (no longer open) is deleted on the next pass", async () => {
+  // Feed the engine-derived desired set to the unchanged reconcile: a persisted row whose task the engine
+  // no longer reports open is deleted, so `showCount` tracks live work — identical to the scan path.
+  const { data, stores } = memData({
+    user_tasks: [
+      { user_task_key: "ut-gone", element_id: "wait-answer", kind_label: "PR review", subject_type: "pr", subject_key: "o/r#30", subject_url: null, question: null, process_key: "rp-30", created_at: "2025-01-01T00:00:00.000Z", updated_at: "2025-01-01T00:00:00.000Z" },
+    ],
+  });
+  const restore = stubUserTaskSearch([]); // engine reports nothing open
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  assertEquals(stores.user_tasks, []);
+});
+
+test("pollUserTasks (engine-first): pages through a large open set (no first-page truncation)", async () => {
+  // Open escalations are normally few, but the sweep must page defensively so a large set is not silently
+  // truncated to the first page. 150 open escalations across a 100-item page size → all 150 projected.
+  const { data, stores } = memData({});
+  const tasks: RawTask[] = Array.from({ length: 150 }, (_, i) => ({
+    userTaskKey: `ut-${i}`,
+    elementId: "feature-escalation",
+    processInstanceKey: `pi-${i}`,
+    state: "CREATED",
+  }));
+  const restore = stubUserTaskSearch(tasks);
+  try {
+    await pollUserTasks(data, fakeEngine({}), REST);
+  } finally {
+    restore();
+  }
+
+  assertEquals((stores.user_tasks ?? []).length, 150);
+});