@nanobpm/nano-workforce 0.187.6 → 0.188.0

package/resources/processes/convergence-loop.bpmn

@@ -65,6 +65,7 @@
         <nano:shape id="PrConvergeGateOut" name="Converge gate — result">
           <nano:extend name="convergeBlocked" type="boolean" />
           <nano:extend name="convergeBlockReason" type="string" optional="true" />
+          <nano:extend name="convergeAckOnly" type="boolean" optional="true" />
           <nano:extend name="reviewStale" type="boolean" optional="true" />
         </nano:shape>
         <nano:shape id="EscalationIn" name="Record escalation — input">
@@ -145,6 +146,7 @@
       <bpmn:incoming>f_reviewLoop</bpmn:incoming>
       <bpmn:incoming>f_answerLoop</bpmn:incoming>
       <bpmn:incoming>f_huskRetry</bpmn:incoming>
+      <bpmn:incoming>f_ackRetry</bpmn:incoming>
       <bpmn:outgoing>f_capture</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-status" name="status?" default="f_addressed">
@@ -331,6 +333,9 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrConvergeGateIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="PrConvergeGateOut" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:output source="=if convergeBlocked = true and convergeAckOnly = true then ackRetryRound + 1 else ackRetryRound" target="ackRetryRound" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_converged</bpmn:incoming>
       <bpmn:outgoing>f_toConvergeGate</bpmn:outgoing>
@@ -341,6 +346,11 @@
       <bpmn:outgoing>f_convergeStale</bpmn:outgoing>
       <bpmn:outgoing>f_convergeOk</bpmn:outgoing>
     </bpmn:exclusiveGateway>
+    <bpmn:exclusiveGateway id="gw-ack-retry" name="auto-ack within budget?" default="f_ackEscalate">
+      <bpmn:incoming>f_convergeBlocked</bpmn:incoming>
+      <bpmn:outgoing>f_ackRetry</bpmn:outgoing>
+      <bpmn:outgoing>f_ackEscalate</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
     <bpmn:serviceTask id="persist-escalation-blockedcomments" name="Escalate: unaddressed comments">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.persist-escalation" />
@@ -354,7 +364,7 @@
           <zeebe:input source="=convergeBlockReason" target="question" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
-      <bpmn:incoming>f_convergeBlocked</bpmn:incoming>
+      <bpmn:incoming>f_ackEscalate</bpmn:incoming>
       <bpmn:outgoing>f_blockedGate</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="classify-scope" name="Scope classifier (agent)">
@@ -407,9 +417,13 @@
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "converged"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_toConvergeGate" sourceRef="check-converge" targetRef="gw-converge-gate" />
-    <bpmn:sequenceFlow id="f_convergeBlocked" name="unaddressed comments" sourceRef="gw-converge-gate" targetRef="persist-escalation-blockedcomments">
+    <bpmn:sequenceFlow id="f_convergeBlocked" name="unaddressed comments" sourceRef="gw-converge-gate" targetRef="gw-ack-retry">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=convergeBlocked = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_ackRetry" name="ack-only within budget" sourceRef="gw-ack-retry" targetRef="capture-head">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=convergeAckOnly = true and ackRetryRound &lt;= ackRetryMax</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_ackEscalate" name="threads / budget exhausted" sourceRef="gw-ack-retry" targetRef="persist-escalation-blockedcomments" />
     <bpmn:sequenceFlow id="f_convergeStale" name="review stale" sourceRef="gw-converge-gate" targetRef="persist-round">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=reviewStale = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -556,8 +570,14 @@
           <dc:Bounds x="954" y="62" width="74" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-ack-retry" bpmnElement="gw-ack-retry" isMarkerVisible="true">
+        <dc:Bounds x="1141" y="415" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1136" y="368" width="60" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-escalation-blockedcomments" bpmnElement="persist-escalation-blockedcomments">
-        <dc:Bounds x="1116" y="400" width="100" height="80" />
+        <dc:Bounds x="1316" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_classify-scope" bpmnElement="classify-scope">
         <dc:Bounds x="1116" y="80" width="100" height="80" />
@@ -622,6 +642,18 @@
         <di:waypoint x="1616" y="120" />
         <di:waypoint x="1723" y="120" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_ackEscalate" bpmnElement="f_ackEscalate">
+        <di:waypoint x="1191" y="440" />
+        <di:waypoint x="1316" y="440" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1220" y="393" width="67" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_blockedGate" bpmnElement="f_blockedGate">
+        <di:waypoint x="1416" y="440" />
+        <di:waypoint x="2427" y="440" />
+        <di:waypoint x="2427" y="305" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_guardOk" bpmnElement="f_guardOk">
         <di:waypoint x="1766" y="600" />
         <di:waypoint x="1891" y="600" />
@@ -672,15 +704,15 @@
         <di:waypoint x="1166" y="660" />
         <di:waypoint x="1166" y="640" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="2159" y="613" width="74" height="42" />
+          <dc:Bounds x="2219" y="613" width="74" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_convergeBlocked" bpmnElement="f_convergeBlocked">
         <di:waypoint x="991" y="145" />
         <di:waypoint x="991" y="440" />
-        <di:waypoint x="1116" y="440" />
+        <di:waypoint x="1141" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1013" y="407" width="81" height="28" />
+          <dc:Bounds x="1026" y="407" width="81" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_convergeStale" bpmnElement="f_convergeStale">
@@ -750,22 +782,16 @@
         <di:waypoint x="1616" y="280" />
         <di:waypoint x="2402" y="280" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_blockedGate" bpmnElement="f_blockedGate">
-        <di:waypoint x="1216" y="440" />
-        <di:waypoint x="1636" y="440" />
-        <di:waypoint x="1636" y="305" />
-        <di:waypoint x="2382" y="305" />
-        <di:waypoint x="2382" y="280" />
-        <di:waypoint x="2402" y="280" />
-      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reviewStalled" bpmnElement="f_reviewStalled">
         <di:waypoint x="2102" y="760" />
         <di:waypoint x="2202" y="760" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_stalledGate" bpmnElement="f_stalledGate">
-        <di:waypoint x="2252" y="720" />
-        <di:waypoint x="2252" y="280" />
-        <di:waypoint x="2402" y="280" />
+        <di:waypoint x="2302" y="760" />
+        <di:waypoint x="2472" y="760" />
+        <di:waypoint x="2472" y="305" />
+        <di:waypoint x="2472" y="280" />
+        <di:waypoint x="2452" y="280" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_escGate" bpmnElement="f_escGate">
         <di:waypoint x="866" y="1240" />
@@ -780,16 +806,24 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_maxGate" bpmnElement="f_maxGate">
         <di:waypoint x="1966" y="920" />
-        <di:waypoint x="2322" y="920" />
-        <di:waypoint x="2322" y="305" />
-        <di:waypoint x="2382" y="305" />
-        <di:waypoint x="2382" y="280" />
-        <di:waypoint x="2402" y="280" />
+        <di:waypoint x="2472" y="920" />
+        <di:waypoint x="2472" y="305" />
+        <di:waypoint x="2472" y="280" />
+        <di:waypoint x="2452" y="280" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_answerRecord" bpmnElement="f_answerRecord">
         <di:waypoint x="2652" y="280" />
         <di:waypoint x="2752" y="280" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_ackRetry" bpmnElement="f_ackRetry">
+        <di:waypoint x="1166" y="465" />
+        <di:waypoint x="1166" y="485" />
+        <di:waypoint x="266" y="485" />
+        <di:waypoint x="266" y="160" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="686" y="438" width="60" height="42" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_huskRetry" bpmnElement="f_huskRetry">
         <di:waypoint x="1741" y="1105" />
         <di:waypoint x="1741" y="1125" />

package/test/derivation-parity/README.md

@@ -71,8 +71,11 @@ events` diagnostic pins this against the goldens themselves.
 sufficient_. Three golden features have no structured-builder derivation, each
 pinned by a diagnostic in `derivation-parity.test.ts`:
 
-1. **Task-level back-edge merge.** The loop head `review-round` is a
-   `serviceTask` that merges **four** back-edges directly (`in=4`). But `loop()`
+1. **Task-level back-edge merge.** The loop head `capture-head` is a
+   `serviceTask` that merges **five** back-edges directly (`in=5`: `f_start`,
+   `f_reviewLoop`, `f_answerLoop`, the #786 husk auto-retry `f_huskRetry`, and
+   the bounded auto-ack re-entry `f_ackRetry` added in #796); `review-round`
+   then takes its single `f_capture` in-edge. But `loop()`
    always inserts an exclusive-gateway loop head that absorbs the back-edge, so
    the body task stays `in=1` — empirically demonstrated by the `loop() inserts a
    gateway head` test.

package/test/derivation-parity/derivation-parity.test.ts

@@ -125,13 +125,14 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
     const body = rest.slice(0, close);
     return (body.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
   };
-  // (a) the loop head is a serviceTask that MERGES four back-edges directly — after #786/#789 the
+  // (a) the loop head is a serviceTask that MERGES its back-edges directly — after #786/#789 the
   // round-entry head capture (`capture-head`) is the loop head sitting BEFORE `review-round`, so it
-  // is `capture-head` that absorbs the four back-edges (the review loop, the answer resume, the
-  // escalation re-enter, and the #786 husk auto-retry); `review-round` then takes its single
-  // `f_capture` in-edge. A serviceTask merging four back-edges directly is the arbitrary-graph shape
-  // the structured builder cannot emit — the feature this asserts, now on `capture-head`.
-  assertEquals(between("capture-head", "serviceTask", "incoming"), 4, "capture-head should merge 4 flows on the task itself");
+  // is `capture-head` that absorbs the back-edges (f_start, the review loop, the answer resume, the
+  // #786 husk auto-retry, and the #796 bounded auto-ack re-entry f_ackRetry); `review-round` then
+  // takes its single `f_capture` in-edge. A serviceTask merging FIVE back-edges directly is the
+  // arbitrary-graph shape the structured builder cannot emit — the feature this asserts, now on
+  // `capture-head`.
+  assertEquals(between("capture-head", "serviceTask", "incoming"), 5, "capture-head should merge 5 flows on the task itself");
   assertEquals(between("review-round", "serviceTask", "incoming"), 1, "review-round now takes the single f_capture in-edge");
   // (b) a single exclusive gateway forks FOUR heterogeneous-condition out-edges.
   assertEquals(between("gw-status", "exclusiveGateway", "outgoing"), 4, "gw-status should be a 4-way exclusive gateway");
@@ -143,8 +144,9 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
 // CLASS 2, empirical — demonstrate WHY the structured builder cannot reproduce
 // (a): a `loop()` whose body starts with a task derives an exclusive-gateway
 // loop head that absorbs the back-edge (in>=2), leaving the task itself at
-// in=1. The golden instead merges its back-edges directly into `review-round`
-// (in=4) with no loop-head gateway — a shape the builder cannot express.
+// in=1. The golden instead merges its back-edges directly into `capture-head`
+// (capture-head in=5: f_start, f_reviewLoop, f_answerLoop, the #786 f_huskRetry, and the #796
+// f_ackRetry re-entry) with no loop-head gateway — a shape the builder cannot express.
 test("loop() inserts a gateway head, so back-edges cannot merge into a task", () => {
   const probe = defineFlow("loop-head-probe", (w) => {
     w.loop((b) => {

package/test/derivation-parity/flows.ts

@@ -23,8 +23,8 @@
 //     (2) ARBITRARY control-flow graph (convergence-loop). Single start/end —
 //         so it clears class (1) — but its topology is NOT expressible with the
 //         structured-only builder (`loop`/`switch`/`branch`), empirically proven
-//         (see `derivation-parity.test.ts`): its loop head `review-round` is a
-//         serviceTask that MERGES four back-edges directly (in=4), whereas
+//         (see `derivation-parity.test.ts`): its loop head `capture-head` is a
+//         serviceTask that MERGES five back-edges directly (in=5), whereas
 //         `loop()` always inserts an exclusive-gateway loop head (the task stays
 //         in=1); `gw-status` is a single exclusive gateway with FOUR
 //         heterogeneous-condition out-edges (two `=x = "v"`, one complex boolean,
@@ -207,8 +207,10 @@ export const PORTS: readonly PortEntry[] = [
       "blocked (arbitrary control-flow graph): single top-level start/end, but " +
       "its topology is not expressible with the published @nanobpm/workflow's " +
       "structured-only builder (loop/switch/branch). Proven in the test suite: " +
-      "the loop head `review-round` is a serviceTask that merges 4 back-edges " +
-      "directly (in=4), but loop() always inserts an exclusive-gateway head " +
+      "the loop head `capture-head` is a serviceTask that merges 5 back-edges " +
+      "directly (in=5: f_start, f_reviewLoop, f_answerLoop, the #786 husk " +
+      "auto-retry f_huskRetry, and the #796 bounded auto-ack re-entry " +
+      "f_ackRetry), but loop() always inserts an exclusive-gateway head " +
       "(task stays in=1); `gw-status` is one gateway with 4 heterogeneous-" +
       "condition out-edges (no switch/branch emits that); `gw-escalated` is one " +
       "gateway that is at once a 6-way merge and a 2-way split. Awaits an " +

package/workers/converge-gate/worker.ts

@@ -6,15 +6,28 @@
 // the comment unaddressed). This step runs on the converged path, BEFORE the scope classifier and
 // pr.finalize hand off to the merge loop, and blocks handoff while GitHub still shows unaddressed
 // comments:
-//   • any review THREAD is still unresolved (GraphQL `isResolved = false`), or
+//   • any SUBSTANTIVE review THREAD is still unresolved (GraphQL `isResolved = false`), or an
+//     unresolved `nano-ack:` ACK thread is open — an ack thread is a partially-completed
+//     acknowledgement the bounded #796 auto-ack retry can finish, so it still BLOCKS (a
+//     genuinely-open GitHub thread) but the block stays ack-only (recoverable) rather than escalating
+//     to a human; only a substantive open thread escalates, or
 //   • any SUPPRESSED advisory in the latest Copilot review body lacks a matching RESOLVED ack
 //     thread (a `nano-ack: <path> :: <verbatim advisory text>` marker whose line-stable prose
 //     fingerprint matches Copilot's advisory). The bare legacy `nano-ack: <path>:<line>` form is
 //     NOT honoured: keyed only on `path:line`, it is blind to the advisory prose and would let a
 //     resolved ack for one advisory silently acknowledge a genuinely new advisory re-emitted at
 //     that same line (a false-OPEN). Only the prose-keyed `<path> :: <text>` form acknowledges.
-// A blocked gate returns `convergeBlocked = true`; the model's `gw-converge-gate` gateway routes to
-// the human `wait-answer` escalation (recoverable), never a hard wedge.
+// A blocked gate returns `convergeBlocked = true` (recoverable, never a hard wedge); the route then
+// depends on WHY it blocked. An ack-only block (`convergeAckOnly = true` — sole cause is unacked
+// suppressed advisories and/or an unresolved `nano-ack:` ack thread) re-dispatches the `review-round`
+// agent first, bounded by `ackRetryMax`, and only reaches the human `wait-answer` escalation once
+// that budget is exhausted. A substantive unresolved thread routes to `wait-answer` immediately.
+//
+// STALE-REVIEW GUARD (issue #799): when the PR HEAD has advanced PAST the commit the latest Copilot
+// review was submitted against, that review's body describes code the head has moved past, so the
+// gate signals `reviewStale = true` (rather than blocking on the obsolete body) and the process
+// re-enters the review wait for a fresh review of the current HEAD. The head read fails OPEN, so a
+// transport hiccup can never fabricate a stale verdict.
 //
 // Scope integrity is NO LONGER judged here. A deterministic regex over the PR description could not
 // read the closed issue's acceptance criteria, so it false-positived on any body that merely
@@ -34,6 +47,7 @@ import {
   fetchLatestCopilotReview,
   fetchPrHead,
   fetchReviewThreads,
+  isAckThread,
   parseAckedAdvisories,
   parseSuppressedAdvisories,
   type ReviewThread,
@@ -85,23 +99,24 @@ export function makeHandler(deps: {
     const ghRepo = repo ?? parsed?.repo;
     const ghNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
     if (!ghRepo || typeof ghNumber !== "number") {
-      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, reviewStale: false };
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
     }
 
     let result: ConvergeGateResult;
     try {
       const threadsRead = await deps.readThreads(ghRepo, ghNumber);
       // A null threads read is an unverifiable gate — fail closed. (An empty ARRAY is a verified
-      // "no threads" and is fine.)
+      // "no threads" and is fine.) An unverifiable block is NOT ack-only: it needs a human to
+      // confirm GitHub state, so it must not enter the bounded agent auto-ack path (#796).
       if (threadsRead === null) {
-        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, reviewStale: false };
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
       }
       const review = await deps.readReview(ghRepo, ghNumber);
       // A null review read is an unverifiable read (no usable transport) — fail closed, same as a
       // null threads read. (A `{ body: "", commitId: null }` result is a verified "no Copilot
       // review / no advisories".)
       if (review === null) {
-        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, reviewStale: false };
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
       }
       // STALE-REVIEW GUARD (issue #799). When the PR HEAD has advanced PAST the commit the latest
       // Copilot review was submitted against, that review's suppressed advisories describe code the
@@ -113,22 +128,39 @@ export function makeHandler(deps: {
       // fabricate a stale verdict; the ordinary gate below still runs on a HEAD-current review.
       const headSha = await readHeadSha(ghRepo, ghNumber).catch(() => null);
       if (isReviewStale(review.commitId, headSha)) {
-        return { convergeBlocked: false, convergeBlockReason: "", reviewStale: true };
+        return { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: true };
       }
-      const unresolvedThreadCount = threadsRead.filter((t) => !t.isResolved).length;
+      // Split the unresolved threads into SUBSTANTIVE reviewer findings vs partially-completed
+      // `nano-ack:` ACK threads (root carries a canonical `nano-ack: <path> :: <text>` marker — see
+      // `isAckThread`). Neither is ever dropped from the gate: a substantive unresolved thread blocks
+      // and escalates to a human; an unresolved ack thread ALSO blocks (it is a genuinely-open GitHub
+      // thread), but the block stays ack-only (recoverable by the bounded #796 auto-ack retry, which
+      // re-posts/resolves it). Keeping the ack thread a BLOCKING condition — rather than filtering it
+      // away — is what makes the root-marker classifier fail-CLOSED: a mislabelled substantive thread
+      // still blocks (as ack-only) instead of finalizing with the finding open, and the bounded retry
+      // cannot ack a non-advisory, so it escalates to a human on exhaustion.
+      const unresolved = threadsRead.filter((t) => !t.isResolved);
+      const unresolvedAckThreadCount = unresolved.filter((t) => isAckThread(t)).length;
+      const unresolvedThreadCount = unresolved.length - unresolvedAckThreadCount;
       const advisories = parseSuppressedAdvisories(review.body);
       result = evaluateConvergeGate({
         unresolvedThreadCount,
+        unresolvedAckThreadCount,
         suppressedAdvisories: advisories.map((a) => ({ key: a.key, label: a.label })),
         acknowledgedKeys: parseAckedAdvisories(threadsRead),
       });
     } catch {
-      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, reviewStale: false };
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
     }
 
     return {
       convergeBlocked: result.convergeBlocked,
       convergeBlockReason: result.convergeBlockReason,
+      // Signals the bounded agent auto-ack path (#796): a block whose sole cause is recoverable —
+      // unacked suppressed advisories AND/OR a lone unresolved `nano-ack:` ack thread (a
+      // partially-completed acknowledgement), with NO substantive unresolved thread — re-dispatches
+      // the review-round agent before escalating to a human.
+      convergeAckOnly: result.ackOnly,
       reviewStale: false,
     };
   };