@nanobpm/nano-workforce 0.98.1 → 0.99.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.99.0](https://github.com/nanobpm/nano-workforce/compare/v0.98.1...v0.99.0) (2026-08-19)
+
+
+### Features
+
+* **review-loop:** re-express the review-ready wait on the ReadinessProbe gate ([#259](https://github.com/nanobpm/nano-workforce/issues/259)) ([#338](https://github.com/nanobpm/nano-workforce/issues/338)) ([4d86509](https://github.com/nanobpm/nano-workforce/commit/4d86509f1f55dd9b31417add323e04da5b574b3d)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258) [#258](https://github.com/nanobpm/nano-workforce/issues/258)
+
 ## [0.98.1](https://github.com/nanobpm/nano-workforce/compare/v0.98.0...v0.98.1) (2026-08-19)
 
 

package/SPEC.md

@@ -29,7 +29,7 @@ surface are proposed and open for adjustment.
           submit (form / webhook)
                      │
                      ▼
-            ┌───────────────────┐        review-ready (msg)      ┌──────────┐
+            ┌───────────────────┐      readiness-ready (msg)     ┌──────────┐
             │  convergence-loop │◀───────────────────────────────│  poller  │
             │      (BPMN)       │                                 └────┬─────┘
             └─────────┬─────────┘◀───────────────┐                    │ polls
@@ -48,8 +48,10 @@ surface are proposed and open for adjustment.
   agent worker slots and job timeouts are never held hostage to Copilot's reply
   latency.
 - **Poller**: an in-app background loop that watches waiting PRs and publishes
-  the `review-ready` message when a new review lands (no GitHub webhook needed;
-  works behind NAT).
+  the canonical `readiness-ready` wait-gate message (ADR 0001 §2) when a new
+  review lands — the "out-of-band poller-correlated shape" the review-ready wait
+  is re-expressed on (#259), so there is one "wait for the world" mechanism (no
+  GitHub webhook needed; works behind NAT).
 
 ## 3. Repository layout
 
@@ -100,7 +102,7 @@ known at submit time, carried as a process variable and stored on the DB row.
 │      ├── converged  → [Mark converged] → (end: converged)
 │      │
 │      ├── addressed  → [Record round] → <event-based gateway: review ready or timeout?>
-│      │                     ├── review-ready (msg catch, key = prKey) → round++ ─────┐
+│      │                     ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
 │      │                     └── =reviewWaitTimeout (timer catch)                     │
 │      │                          → [Escalate: review stalled] (blocked)              │
 │      │                          → [Wait: wait-answer userTask] ─────────────────────┤
@@ -127,8 +129,9 @@ Guard: before each Review round, if round > MAX_ROUNDS → force an escalation
 ```
 
 Notes:
-- On `addressed`, the loop parks at an **event-based gateway** that races a
-  `review-ready` message (correlated by the poller when a fresh review lands)
+- On `addressed`, the loop parks at an **event-based gateway** that races the
+  canonical `readiness-ready` wait-gate message (ADR 0001 §2; correlated by the
+  poller when a fresh review lands)
   against a `=reviewWaitTimeout` timer (seeded at submit from
   `NANO_PR_REVIEW_WAIT_TIMEOUT`, default `PT20M`). Whichever fires first
   withdraws the other — the message arm advances `round`, the timer arm escalates
@@ -136,7 +139,8 @@ Notes:
   hanging forever. Because `persist-round` already recorded this `round` as
   `addressed` before the gateway, the timer arm opens the escalation **without
   re-recording the round** (it passes `recordRound=false`), so a single round is
-  never logged as both `addressed` and `blocked`. This replaced a bare
+  never logged as both `addressed` and `blocked`. This wait is re-expressed on the
+  ONE `ReadinessProbe` wait-gate primitive (#258, ADR 0001 §2); it replaced a bare
   `review-ready` catch that could hang
   indefinitely: Copilot won't re-review a round with no new commit and routinely
   dismisses a re-request, so with no timeout a review that never arrives wedged
@@ -210,7 +214,7 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 | message | correlationKey | published by | payload |
 |---|---|---|---|
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
-| `review-ready` | `prKey` | **poller** | `{reviewId, reviewState, submittedAt}` |
+| `readiness-ready` | `prKey` | **poller** | `{ready, detail?}` (ADR 0001 §2 wait-gate; the review-ready wait, re-expressed on the ReadinessProbe gate — #259) |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
 | `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
@@ -368,8 +372,8 @@ An in-app loop (interval `NANO_PR_POLL_MS`, default 60s):
 1. `SELECT pr_key, repo, number, waiting_since, last_review_id, last_nudge_at FROM pull_requests WHERE status = 'waiting_review'`.
 2. For each, GET the PR's reviews from GitHub; find the newest review submitted
    after `waiting_since` with id > `last_review_id`.
-3. If found → publish `review-ready` (key = `pr_key`, `{reviewId, ...}`) and set
-   `last_review_id`.
+3. If found → publish the canonical `readiness-ready` wait-gate message (key =
+   `pr_key`, `{ready, detail}`) and set `last_review_id`.
 4. If **not** found → ensure a review is in flight: unless Copilot is already a
    pending reviewer, **re-request** it (REST `requested_reviewers`, exact login
    `copilot-pull-request-reviewer[bot]`) and record `last_nudge_at`. This is
@@ -377,7 +381,7 @@ An in-app loop (interval `NANO_PR_POLL_MS`, default 60s):
    so a re-request Copilot dismisses is retried without hammering the API. A repo
    where Copilot isn't an assignable reviewer (HTTP 422) is left to the process's
    review-wait timer (§4). This closes the stall where Copilot won't spontaneously
-   re-review and silently dismisses a re-request, so no `review-ready` ever fires.
+   re-review and silently dismisses a re-request, so no `readiness-ready` ever fires.
 
 Requires a GitHub token (`GITHUB_TOKEN`) or the host `gh` CLI. One cheap API call
 per waiting PR per interval (plus at most one reviewer-state check + re-request per
@@ -644,7 +648,7 @@ but encode incompatible decisions about a shared contract** — a genuine design
   `baseRef`) that let large monorepos provision within the clone timeout (#287); the
   harness is PR-agnostic and provisions from that envelope. The worker stays a pure
   provisioner.
-- **review-ready via GitHub webhook** — same message, swappable faster trigger,
+- **readiness-ready via GitHub webhook** — same `readiness-ready` message, swappable faster trigger,
   when the app is publicly reachable. Deferred (poller-only for v1).
 - **Supervised vs external worker** — the agent runs as an external
   `c8ctl nano work` daemon by default; a supervised in-server mode is possible

package/app/github.ts

@@ -348,7 +348,7 @@ export async function hasPendingCopilotReviewer(
 }
 
 /** Request a fresh Copilot review on the PR (REST reviewers endpoint, exact `[bot]` login), so
- * the process's `review-ready` catch can eventually fire. Returns `"requested"` on success,
+ * the process's `readiness-ready` review wait-gate catch can eventually fire. Returns `"requested"` on success,
  * `"unavailable"` when Copilot is not an assignable reviewer on that repo (HTTP 422 — e.g.
  * Copilot review not enabled there), or `null` when no transport is usable. Never throws for the
  * 422 "not assignable" case; only a genuine transport failure propagates. */

package/app/readiness.ts

@@ -150,6 +150,14 @@ export const DEFAULT_ATTEMPT_TIMEOUT_MS = 60_000;
 /** Default gate timeout when neither the descriptor nor `NANO_READINESS_POLL_TIMEOUT` supplies one. */
 export const DEFAULT_READINESS_TIMEOUT = "PT30M";
 
+/** The ONE canonical readiness-signal message the wait-gate correlates on to release the wait
+ * (ADR 0001 §2) — the correlation key is per-caller (`=gateKey` for the in-flow probe worker,
+ * `=prKey` for the review-ready wait), not a single fixed key. Both the in-flow probe worker
+ * (`pr.readiness-probe`) and the out-of-band
+ * poller-correlated shape used by the review-ready migration (#259, per #258 pinned decision 3)
+ * publish under this ONE name — so there is a single "wait for the world" message, no bespoke twin. */
+export const READINESS_READY_MESSAGE = "readiness-ready";
+
 const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
 const num = (v: unknown): number | undefined =>
   typeof v === "number" && Number.isFinite(v) ? v : undefined;

package/app/reviewReadinessGate.test.ts

@@ -0,0 +1,92 @@
+// Structural guard for the review-ready wait re-expressed on the canonical ReadinessProbe
+// wait-gate contract (ADR 0001 §2, issue #259).
+//
+// #258 landed the generic durable wait-gate: an event-based gateway racing a canonical
+// `readiness-ready` signal against a bounded timer that escalates. #259 collapses nwf's bespoke
+// review-ready poll path onto that ONE primitive — so there is a single "wait for the world"
+// message, no drift-prone twin. The out-of-band poller-correlated shape (#258 pinned decision 3)
+// keeps the canonical self-scheduling poller (`pollReviews` in app/service.ts) publishing the
+// signal when a fresh review lands, while the convergence-loop parks on the canonical gate.
+//
+// These pure text assertions over the committed BPMN lock the migrated wait: it now catches the
+// canonical `readiness-ready` message (the bespoke `review-ready` message is GONE), and it stays
+// BOUNDED — the event-based gateway still races the signal against the `reviewWaitTimeout` timer,
+// whose arm escalates to a human. Matches the repo's model-guard style (see roundResultDefault.test.ts).
+
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { READINESS_READY_MESSAGE } from "./readiness.ts";
+
+const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+test("the review wait catches the canonical readiness-ready message, not a bespoke twin", () => {
+  // The one canonical wait-gate signal (#258), re-used here — no separate `review-ready` message.
+  const msg = flat.match(/<bpmn:message\b[^>]*\bname="readiness-ready"[\s\S]*?<\/bpmn:message>/);
+  assert(msg, "convergence-loop must declare the canonical readiness-ready message");
+  assertStringIncludes(msg![0], 'correlationKey="=prKey"', "correlation shape is preserved (=prKey)");
+
+  // The bespoke review-ready message/shape must be fully retired (one mechanism, no drift).
+  assert(!/name="review-ready"/.test(flat), "the bespoke review-ready message must be gone");
+  assert(!/id="Message_reviewReady"/.test(flat), "the bespoke Message_reviewReady must be gone");
+  assert(!/id="ReviewReady"/.test(flat), "the bespoke ReviewReady payload shape must be gone");
+
+  // And the constant the poller publishes under is the very same canonical name.
+  assert(new RegExp(`name="${READINESS_READY_MESSAGE}"`).test(flat), "message name matches the canonical constant");
+});
+
+test("the review-ready catch subscribes to the canonical readiness-ready message", () => {
+  const wait = flat.match(/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-review"[\s\S]*?<\/bpmn:intermediateCatchEvent>/);
+  assert(wait, "the wait-review catch event must exist");
+  assertStringIncludes(
+    wait![0],
+    'messageRef="Message_readinessReady"',
+    "wait-review must catch the canonical readiness-ready message",
+  );
+  // The round increment (forward progress) is preserved on the same catch.
+  assertStringIncludes(wait![0], 'target="round"', "wait-review still advances the round on a fresh signal");
+});
+
+test("the migrated wait stays bounded: an event-based gateway races the signal against a timer", () => {
+  // The gate shape from #258: an event-based gateway forks to the signal catch and a timer catch.
+  const gw = flat.match(/<bpmn:eventBasedGateway\b[^>]*\bid="gw-review-wait"[^>]*>/);
+  assert(gw, "the review wait must be an event-based gateway race (bounded gate)");
+
+  const timeout = flat.match(
+    /<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-review-timeout"[\s\S]*?<\/bpmn:intermediateCatchEvent>/,
+  );
+  assert(timeout, "the bounded timer arm (wait-review-timeout) must exist");
+  assertStringIncludes(timeout![0], "<bpmn:timerEventDefinition", "the timer arm bounds the wait");
+  assertStringIncludes(timeout![0], "=reviewWaitTimeout", "the timer is seeded with the review-wait timeout");
+
+  // The gateway forks to BOTH the signal catch and the timer catch (the race).
+  assert(
+    /sourceRef="gw-review-wait"[^>]*targetRef="wait-review"|targetRef="wait-review"[^>]*sourceRef="gw-review-wait"/.test(
+      flat,
+    ),
+    "the gateway races toward the readiness signal catch",
+  );
+  assert(
+    /sourceRef="gw-review-wait"[^>]*targetRef="wait-review-timeout"|targetRef="wait-review-timeout"[^>]*sourceRef="gw-review-wait"/.test(
+      flat,
+    ),
+    "the gateway races toward the bounded timer catch",
+  );
+});
+
+test("the timeout arm escalates to a human (the wait cannot hang forever)", () => {
+  // timer catch → persist-review-stalled (records the escalation) → wait-answer (native userTask).
+  assert(
+    /sourceRef="wait-review-timeout"[^>]*targetRef="persist-review-stalled"|targetRef="persist-review-stalled"[^>]*sourceRef="wait-review-timeout"/.test(
+      flat,
+    ),
+    "a timed-out review wait routes to the stalled-review escalation",
+  );
+  assert(
+    /sourceRef="persist-review-stalled"[^>]*targetRef="wait-answer"|targetRef="wait-answer"[^>]*sourceRef="persist-review-stalled"/.test(
+      flat,
+    ),
+    "the stalled-review escalation parks on the human answer userTask",
+  );
+});

package/app/reviewWait.ts

@@ -5,7 +5,7 @@
 //
 // Two knobs govern the review-wait watchdog:
 //   • the *timeout* — an ISO-8601 duration handed to the process's `wait-review-timeout` timer
-//     catch (the far side of the event-based-gateway race against `review-ready`). If no fresh
+//     catch (the far side of the event-based-gateway race against `readiness-ready`). If no fresh
 //     review arrives within it, the loop escalates to a human instead of hanging forever.
 //   • the *nudge cooldown* — how long the poller waits between automatic Copilot re-requests for
 //     one waiting PR, so a re-request that Copilot dismisses is retried without hammering the API.

package/app/service.ts

@@ -54,7 +54,14 @@ import {
   planTasks,
 } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
-import { defaultProbeExec, type ProbeExec, probeOnce, type ReadinessProbe, readinessTimeout } from "./readiness.ts";
+import {
+  defaultProbeExec,
+  type ProbeExec,
+  probeOnce,
+  READINESS_READY_MESSAGE,
+  type ReadinessProbe,
+  readinessTimeout,
+} from "./readiness.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -668,7 +675,17 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
 
 /** One review-ready poll pass (SPEC §10): for every PR waiting on a review, fetch its GitHub
  * reviews (via the host `gh` CLI or a token — see `app/github.ts`) and, on a fresh one,
- * correlate a `review-ready` message to resume the loop. */
+ * correlate the canonical `readiness-ready` message to resume the loop.
+ *
+ * This is the review-ready wait re-expressed on the ONE `ReadinessProbe` wait-gate contract
+ * (ADR 0001 §2, issue #259): the convergence-loop parks on the canonical `readiness-ready` gate
+ * (event-based gateway racing the signal against the bounded `reviewWaitTimeout` timer), and this
+ * canonical self-scheduling poller publishes that signal out-of-band when a fresh review lands —
+ * the "out-of-band poller-correlated shape" #258 pinned decision 3 reserved for exactly this
+ * migration. There is no bespoke `review-ready` message any more: one mechanism, no drift. The
+ * fresh-review detection + Copilot nudge below stay here because review freshness is inherently
+ * STATEFUL (keyed off `last_review_id`/`waiting_since`), which the stateless probe matchers cannot
+ * subsume — the poller owns the forward-progress guarantee, the gate owns the bounded wait. */
 async function pollReviews(data: DataLayer, engine: EngineClient, token: string) {
   const waiting = await prs(data).find({ status: "waiting_review" });
   for (const pr of waiting) {
@@ -692,9 +709,12 @@ async function pollReviews(data: DataLayer, engine: EngineClient, token: string)
       }
       await prs(data).update(prKey, { last_review_id: fresh.id, status: "converging", updated_at: now() });
       await engine.publishMessage({
-        name: "review-ready",
+        name: READINESS_READY_MESSAGE,
         correlationKey: prKey,
-        variables: { reviewId: fresh.id, reviewState: fresh.state, submittedAt: fresh.submitted_at },
+        // The canonical readiness-signal payload (`ReadinessReady` shape): the gate only needs to
+        // know the probe went green. The fresh review's id/state is bookkept above on the PR row,
+        // not carried on the message — the convergence-loop consumes only the round increment.
+        variables: { ready: true, detail: `review ${fresh.id} (${fresh.state})` },
       });
       console.log(`[poller] review ${fresh.id} (${fresh.state}) -> ${prKey}`);
     } catch (err) {

package/main.ts

@@ -9,7 +9,8 @@
 //     control endpoints plus the webhook operations under `/app/api/hooks/*` (ADR 0059).
 //
 // The only thing that isn't declarative is the review-ready poller: it does arbitrary GitHub
-// polling and then correlates a `review-ready` message. A cron trigger can only fire an engine
+// polling and then correlates the canonical `readiness-ready` wait-gate message (#259). A cron
+// trigger can only fire an engine
 // start/message action, not this custom I/O glue, so it stays app-side here — driving the same
 // engine client the runtime uses, over `app.data`.
 //
@@ -89,7 +90,7 @@ if (httpServer instanceof Server) {
 }
 
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
-// overlap two passes (which could double-signal `review-ready`); the next pass is scheduled
+// overlap two passes (which could double-signal `readiness-ready`); the next pass is scheduled
 // only after the previous one settles.
 let shuttingDown = false;
 let pollTimer: ReturnType<typeof setTimeout> | null = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.98.1",
+  "version": "0.99.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",

package/resources/processes/convergence-loop.bpmn

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce" targetNamespace="http://nanobpm.io/nano-workforce">
-  <bpmn:message id="Message_reviewReady" name="review-ready">
+  <bpmn:message id="Message_readinessReady" name="readiness-ready">
     <bpmn:extensionElements>
       <zeebe:subscription correlationKey="=prKey" />
       <zeebe:properties>
-        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReviewReady" />
+        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessReady" />
       </zeebe:properties>
     </bpmn:extensionElements>
   </bpmn:message>
@@ -82,11 +82,6 @@
           <nano:extend name="convergeOnly" type="boolean" optional="true" />
           <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
-        <nano:shape id="ReviewReady" name="review-ready message payload">
-          <nano:extend name="reviewId" type="integer" />
-          <nano:extend name="reviewState" type="string" />
-          <nano:extend name="submittedAt" type="datetime" optional="true" />
-        </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="PR submitted">
@@ -181,7 +176,7 @@
       </bpmn:extensionElements>
       <bpmn:incoming>f_toReviewWait</bpmn:incoming>
       <bpmn:outgoing>f_reviewLoop</bpmn:outgoing>
-      <bpmn:messageEventDefinition id="med_reviewReady" messageRef="Message_reviewReady" />
+      <bpmn:messageEventDefinition id="med_readinessReady" messageRef="Message_readinessReady" />
     </bpmn:intermediateCatchEvent>
     <bpmn:intermediateCatchEvent id="wait-review-timeout" name="Wait: review timeout">
       <bpmn:incoming>f_toReviewTimeout</bpmn:incoming>

package/workers/readiness-probe/worker.ts

@@ -25,6 +25,7 @@ import {
   parseProbe,
   probeBudgetMs,
   probeOnce,
+  READINESS_READY_MESSAGE,
   type ReadinessProbe,
   redactTarget,
 } from "../../app/readiness.ts";
@@ -36,8 +37,11 @@ import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io
 type In = WorkerInputs["pr.readiness-probe"];
 type Out = WorkerOutputs["pr.readiness-probe"];
 
-/** The message the gate's event-based gateway correlates on `=gateKey` to release the wait. */
-export const READINESS_READY_MESSAGE = "readiness-ready";
+/** The message the gate's event-based gateway correlates on `=gateKey` to release the wait.
+ * Re-exported from the canonical source (`app/readiness.ts`) so the worker and every out-of-band
+ * publisher (the review-ready poller, #259) share ONE message name — no drift-prone local twin.
+ * Re-exports the binding already imported above rather than re-referencing the module. */
+export { READINESS_READY_MESSAGE };
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));