@nanobpm/nano-workforce 0.206.3 → 0.206.4

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.206.4](https://github.com/nanobpm/nano-workforce/compare/v0.206.3...v0.206.4) (2026-11-09)
+
+### Bug Fixes
+
+* **delivery:** accept affirmative-completion aliases as producer terminal-success statuses ([#934](https://github.com/nanobpm/nano-workforce/issues/934)) ([b8c5e4e](https://github.com/nanobpm/nano-workforce/commit/b8c5e4e5cb59ce42bb2d6573e107d1865393fa27)), closes [731/#760](https://github.com/731/nano-workforce/issues/760) [nano-bpm#1337](https://github.com/nanobpm/nano-bpm/issues/1337) [#1464](https://github.com/nanobpm/nano-workforce/issues/1464) [nano-bpm#1463](https://github.com/nanobpm/nano-bpm/issues/1463) [#1476](https://github.com/nanobpm/nano-workforce/issues/1476) [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#760](https://github.com/nanobpm/nano-workforce/issues/760) [#761](https://github.com/nanobpm/nano-workforce/issues/761)
+
 ## [0.206.3](https://github.com/nanobpm/nano-workforce/compare/v0.206.2...v0.206.3) (2026-11-09)
 
 ### Bug Fixes

package/SPEC.md

@@ -1289,7 +1289,9 @@ reserved — with **one exception**: an agent emitting `pr` (the canonical
 result field holds, and the retry reset correctly clears both — reserving them would
 forbid that flagship pattern. The exception is the agent completion-control **`status`**:
 the producer status gate reads that same node-local field as the node's completion status
-and accepts only `done`/`opened`/`skipped`, so an agent emit named `status` carrying any
+and accepts only the terminal-success vocabulary (`AGENT_TERMINAL_SUCCESS_STATUSES` — the
+canonical `done`/`opened`/`skipped` plus the issue-#932 affirmative-completion aliases
+`completed`/`succeeded`/`success`), so an agent emit named `status` carrying any
 other routing value (`approved`, …) always escalates, and `status="done"` can never take an
 `approved` branch — the emit contract and the gate conflict. `status` is therefore reserved
 for an **`agent`** (a connector has no producer status gate, so a connector `status` emit

package/app/deliveryGraph.test.ts

@@ -538,7 +538,7 @@ test("invalid-fact-name: an AGENT emit named `status` is reserved — the produc
   // Regression guard (PR #863 Copilot Medium "Previously missed", deliveryGraph.ts:418): the result-set
   // exemption was too broad for an agent emit named `status`. The producer status gate
   // (`agentContractProceedCondition`) interprets that same node-local field as the completion status and
-  // accepts only `done`/`opened`/`skipped`, while the emit contract may require a different routing
+  // accepts only the terminal-success vocabulary (`AGENT_TERMINAL_SUCCESS_STATUSES`), while the emit contract may require a different routing
   // value — `status="approved"` always escalates, and `status="done"` can never take an `approved`
   // branch. Unlike an aligned result fact such as `pr` (whose emit value and result field agree),
   // `status` is CONSTRAINED by the gate, so the two uses conflict. Reserve the agent completion-control

package/app/deliveryGraph.ts

@@ -458,7 +458,9 @@ export const DELIVERY_SCAFFOLDING_VARS = ["boundFacts", "nodeInputs", "nodeInput
  * correctly clears both. Reserving the whole set would forbid the flagship
  * `agent → connector[converge] → wait[pr]` pattern. The exception is the agent completion-control
  * `status`: the producer status gate reads that SAME node-local field as the node's completion status
- * and accepts only `done`/`opened`/`skipped`, so an agent emit named `status` whose routing value is
+ * and accepts only the terminal-success vocabulary (`AGENT_TERMINAL_SUCCESS_STATUSES` — the canonical
+ * `done`/`opened`/`skipped` plus the #932 affirmative-completion aliases), so an agent emit named
+ * `status` whose routing value is
  * anything else (`approved`, …) ALWAYS escalates, and `status="done"` can never take an `approved`
  * branch — the emit contract and the gate conflict. `status` is therefore reserved for an `agent`
  * (a connector has no producer status gate, so its `status` emit collides with nothing and stays

package/app/deliveryGraphCompiler.test.ts

@@ -15,7 +15,7 @@ import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 import { missingExternalMarkerAgentTaskTypes } from "./agentic/vocab/job-types.ts";
-import { compileDeliveryGraph, digestInvisibleRawValues, graphCarriesRedactedSecrets, nodeDisplay, redactFreeText, resumeValidVar } from "./deliveryGraphCompiler.ts";
+import { AGENT_TERMINAL_SUCCESS_STATUSES, compileDeliveryGraph, digestInvisibleRawValues, graphCarriesRedactedSecrets, nodeDisplay, redactFreeText, resumeValidVar } from "./deliveryGraphCompiler.ts";
 import { isDeliveryEscalationTwin } from "./deliveryHuman.ts";
 
 /** Compile and assert success, returning the narrowed ok-result. */
@@ -2131,7 +2131,11 @@ test("#731 producer status gate: an agent node inserts a post-completion contrac
   assert(g0, "the contract-met success flow exists");
   assert(g0![1].includes(`=${el}_contractMet = true`), "the success flow reads the node-unique contract decision");
   const cond = contractMetExpr(r.bpmn, el);
-  assert(cond.includes('list contains(["done", "opened", "skipped"], status)'), "the success flow gates on the terminal-success status allowlist");
+  // The gate's FEEL allowlist is DERIVED from the single source of truth (AGENT_TERMINAL_SUCCESS_STATUSES)
+  // — assert against the derived rendering, not a hand-copied literal, so this test can never drift from
+  // the vocabulary it guards (issue #932).
+  const derivedList = `[${AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => `"${s}"`).join(", ")}]`;
+  assert(cond.includes(`list contains(${derivedList}, status)`), `the success flow gates on the derived terminal-success status allowlist, got: ${cond}`);
   assert(cond.includes("not(is defined(status)) or status = null"), "an absent/null status is not itself the failure mode — it still proceeds");
   // The contract escalation's read-only context names the node and its reported status (#731).
   const esc = escBlockForNodeSuffix(r.bpmn, "open", "contract");
@@ -2139,6 +2143,49 @@ test("#731 producer status gate: an agent node inserts a post-completion contrac
   assert(esc.includes("Reported status="), "the context surfaces the actual reported status");
 });
 
+test("#932 producer status gate: the affirmative-completion synonyms agents actually report are allowlisted terminal-success statuses, derived from one source", () => {
+  // Issue #932: agents keep self-reporting `status: "completed"` (and other unambiguous success
+  // synonyms) after FULLY delivering — every required emit present — yet the #731 gate accepted only
+  // `done`/`opened`/`skipped`, so a fully-delivered node parked on a human "Continue" escalation as a
+  // contract violation (nano-bpm#1337 → PR #1464 escalation 584376; nano-bpm#1463 → PR #1476
+  // escalation 599960). The fix is the CLASS fix: the affirmative-completion aliases are
+  // terminal-success statuses in the ONE canonical vocabulary (AGENT_TERMINAL_SUCCESS_STATUSES), which
+  // the gate's FEEL AND the #760 prompt contract both derive from. Pin the vocabulary content so a
+  // future "tidy-up" cannot silently re-narrow it (a removed synonym re-introduces the escalation).
+  for (const synonym of ["completed", "success", "succeeded"]) {
+    assert(
+      AGENT_TERMINAL_SUCCESS_STATUSES.includes(synonym),
+      `"${synonym}" — an unambiguous affirmative-completion alias agents report — must be a terminal-success status (issue #932)`,
+    );
+  }
+  // The canonical statuses stay.
+  for (const canonical of ["done", "opened", "skipped"]) {
+    assert(AGENT_TERMINAL_SUCCESS_STATUSES.includes(canonical), `the canonical "${canonical}" status stays allowlisted`);
+  }
+  // And the vocabulary remains CLOSED to ambiguous non-success reports: a failure/give-up/in-progress
+  // self-report must NEVER be normalised to success (the gate stays fail-closed for those).
+  for (const nonSuccess of ["in_progress", "blocked", "failed", "escalated", "needs_input"]) {
+    assert(
+      !AGENT_TERMINAL_SUCCESS_STATUSES.includes(nonSuccess),
+      `"${nonSuccess}" is not a success claim — it must stay OFF the terminal-success allowlist`,
+    );
+  }
+});
+
+test("#932 producer status gate: the compiled contract gate accepts a `completed` report (the observed failure) as terminal-success", async () => {
+  // The compile-level half of the #932 regression guard: the gate's FEEL allowlist (derived from
+  // AGENT_TERMINAL_SUCCESS_STATUSES) must literally contain `completed`, so a fully-delivered node
+  // reporting it passes the producer gate instead of escalating (the e2e half, in
+  // e2e/delivery-graph.e2e.ts, proves the routing end-to-end).
+  const r = await compileOk(PRODUCER_GATE);
+  const el = elementForNode(r.bpmn, "open");
+  const cond = contractMetExpr(r.bpmn, el);
+  assert(cond.includes('"completed"'), `the gate's status allowlist contains "completed", got: ${cond}`);
+  // The escalation context line names the SAME derived vocabulary (never a stale hand-typed list).
+  const esc = escBlockForNodeSuffix(r.bpmn, "open", "contract");
+  assert(esc.includes("completed"), "the escalation context names the widened vocabulary");
+});
+
 test("#731 required-emit gate: a producer's declared emit consumed as a required data dependency adds a non-null gate clause and a resumable escalation NAMING the fact", async () => {
   const r = await compileOk(PRODUCER_GATE);
   const el = elementForNode(r.bpmn, "open");

package/app/deliveryGraphCompiler.ts

@@ -254,11 +254,22 @@ export function resumeValidVar(esc: string): string {
  * and escalates AT the node instead of threading an incomplete result into a downstream consumer. An
  * ABSENT/null status passes the gate (a status-less completion — an older fleet worker or a bare test
  * stub — is not itself the failure mode; the required-emit gate still catches a missing data fact).
+ *
+ * The list deliberately includes the unambiguous AFFIRMATIVE-COMPLETION aliases agents actually report
+ * — `completed`/`success`/`succeeded` (issue #932: agents kept reporting `status: "completed"` after
+ * FULLY delivering — every required emit present — and the narrow list parked that good work on a
+ * human "Continue" escalation as a contract violation; nano-bpm#1337 → PR #1464 escalation 584376,
+ * nano-bpm#1463 → PR #1476 escalation 599960). An affirmative alias is normalised to terminal-success
+ * AT THE GATE: it routes onward exactly like `done` — the required-emit clauses still gate it, so a
+ * `completed` WITHOUT its required emits still escalates. Only UNAMBIGUOUS success claims belong here:
+ * a failure / input-required / in-progress report (`failed`, `needs_input`, `in_progress`, …) is NOT a
+ * completion claim and must NEVER be added — the gate stays fail-closed for those.
+ *
  * Sorted for the compiler's byte-identical-output determinism. Exported as the SINGLE SOURCE OF TRUTH:
  * the compiler's contract gate reads it here, and the runner's `renderProducerContract` (#760) derives
  * the agent-facing status vocabulary from the SAME list — changing it changes both the gate and the
  * prompt at once, so the two representations of the producer contract can never drift. */
-export const AGENT_TERMINAL_SUCCESS_STATUSES: readonly string[] = ["done", "opened", "skipped"];
+export const AGENT_TERMINAL_SUCCESS_STATUSES: readonly string[] = ["completed", "done", "opened", "skipped", "succeeded", "success"];
 
 /** A never-reached exhaustiveness guard: `compileNode`'s `switch` covers every allowlisted kind, so
  * the closed union narrows to `never` here. If a future kind is added to the vocabulary without a

package/app/deliveryRunner.test.ts

@@ -279,6 +279,25 @@ test("producer contract semantics coverage (#761 follow-up): renderProducerContr
 });
 
 
+test("#932 producer contract prompt: the affirmative-completion synonyms agents actually report are listed AND documented, so the prompt and the gate accept the same vocabulary", () => {
+  // Issue #932: agents kept reporting `status: "completed"` (and synonyms) after fully delivering and
+  // were parked on a human escalation, because the #731 gate accepted only `done`/`opened`/`skipped`
+  // and the #760 prompt told agents the same narrow list. The class fix puts the synonyms in the ONE
+  // canonical vocabulary (AGENT_TERMINAL_SUCCESS_STATUSES); the prompt contract is DERIVED from it, so
+  // the agent is now TOLD these are valid — pin that the observed aliases surface with semantics.
+  const rendered = renderProducerContract([]);
+  for (const synonym of ["completed", "success", "succeeded"]) {
+    assert(
+      rendered.includes(`- \`${synonym}\` — `),
+      `the prompt documents the "${synonym}" alias with its semantics (issue #932), got: ${rendered}`,
+    );
+  }
+  // The "do not invent a status" warning must name the widened list too (derived, never hand-typed).
+  const list = AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => `\`${s}\``).join(", ");
+  assert(rendered.includes(`Any \`status\` OUTSIDE ${list}`), `the fail-closed warning names the derived allowlist, got: ${rendered}`);
+});
+
+
 test("agent node idempotency preflight (#551): every agent prompt leads with adopt-and-report guidance; non-agent nodes are untouched", async () => {
   // #551: a delivery agent node dispatches a raw retry-carrying `senior:feature` job with no
   // PR-existence guard, so a re-dispatch opened a DUPLICATE PR (instance 43077 n0 → #979/#980). The
@@ -754,3 +773,15 @@ test("the canonical `agent → converge-merge → wait[pr merged]` graph DISPATC
   assert(r.ok, `expected the canonical fact-bound wait[pr] graph to launch, got ${JSON.stringify(r)}`);
   assertEquals(r.handle.processInstanceKey, "555");
 });
+test("PR #934 producer contract prompt: no accepted status is ever cited as a forbidden example", () => {
+  // Class: the rejection sentence named `success` as invalid after it became an accepted alias, so every
+  // agent got contradictory instructions. Every accepted status must be absent from that sentence.
+  const rendered = renderProducerContract([]);
+  const rejectLine = rendered.split("\n").find((l) => l.includes("including a free-form"));
+  assert(rejectLine !== undefined, `the fail-closed warning carries rejection examples, got: ${rendered}`);
+  const examples = rejectLine.split("including a free-form")[1] ?? "";
+  for (const s of AGENT_TERMINAL_SUCCESS_STATUSES) {
+    assert(!examples.includes(`\`${s}\``), `accepted status "${s}" must not be cited as a rejected example: ${rejectLine}`);
+  }
+  assert(examples.includes("`in_progress`"), `a genuine out-of-vocabulary example remains: ${rejectLine}`);
+});

package/app/deliveryRunner.ts

@@ -495,6 +495,13 @@ const PRODUCER_STATUS_SEMANTICS: Readonly<Record<string, string>> = {
   opened: "you opened OR adopted a PR (return it in your `pr` emit if this node declares one)",
   done: "the work completed with no PR to open",
   skipped: "there was genuinely nothing to do",
+  // Issue #932: the unambiguous AFFIRMATIVE-COMPLETION aliases agents actually self-report. They are
+  // full terminal-success statuses (normalised at the gate), documented here so the prompt and the
+  // gate accept the SAME vocabulary — an agent told only `done`/`opened`/`skipped` keeps inventing
+  // `completed` and parking good work on a human escalation.
+  completed: "an alias of `done`/`opened` — the work fully completed (with its required emits populated)",
+  succeeded: "an alias of `done`/`opened` — the work fully succeeded (with its required emits populated)",
+  success: "an alias of `done`/`opened` — the work fully succeeded (with its required emits populated)",
 };
 
 /** Render the producer-completion contract auto-injected into EVERY `agent` node's `appendPrompt`
@@ -518,6 +525,11 @@ const PRODUCER_STATUS_SEMANTICS: Readonly<Record<string, string>> = {
  * contract already tells the agent to omit an undecidable routing fact. Listing every DECLARED emit
  * here instead would contradict that guidance and push agents to guess values that should stay
  * optional (#761). */
+/** Illustrative out-of-vocabulary statuses named in the producer contract's rejection sentence. Always
+ * filtered against `AGENT_TERMINAL_SUCCESS_STATUSES` at render time, so an example that later becomes an
+ * accepted alias silently drops out instead of contradicting the accepted list. */
+const PRODUCER_REJECTED_STATUS_EXAMPLES: readonly string[] = ["in_progress", "failed", "partial", "success"];
+
 export function renderProducerContract(requiredEmits: readonly DeliveryFact[]): string {
   const list = AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => `\`${s}\``).join(", ");
   const semantics = AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => {
@@ -530,6 +542,11 @@ export function renderProducerContract(requiredEmits: readonly DeliveryFact[]):
     }
     return `- \`${s}\` — ${doc}.`;
   });
+  // Rejection examples are FILTERED against the allowlist so the prompt can never present one status as
+  // both accepted and forbidden (PR #934 review: `success` became an alias but stayed an example).
+  const rejected = PRODUCER_REJECTED_STATUS_EXAMPLES.filter((s) => !AGENT_TERMINAL_SUCCESS_STATUSES.includes(s))
+    .map((s) => `\`${s}\``)
+    .join("/");
   const lines = [
     "",
     "",
@@ -543,7 +560,7 @@ export function renderProducerContract(requiredEmits: readonly DeliveryFact[]):
     "",
     ...semantics,
     "",
-    `Any \`status\` OUTSIDE ${list} — including a free-form \`success\`/\`in_progress\`/\`failed\` — parks the`,
+    `Any \`status\` OUTSIDE ${list} — including a free-form ${rejected} — parks the`,
     "run on a human escalation (the gate is fail-closed), EVEN when your underlying work was correct. So",
     "do not invent a status: report exactly one of the allowlisted values above.",
   ];

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.206.3",
-  "gitSha": "f731dc60dc0cb7480b425e88d1d216b95d63a5c1",
-  "gitTag": "v0.206.3",
-  "builtAt": "2026-11-09T21:25:41.376Z"
+  "version": "0.206.4",
+  "gitSha": "b8c5e4e5cb59ce42bb2d6573e107d1865393fa27",
+  "gitTag": "v0.206.4",
+  "builtAt": "2026-11-09T21:50:28.782Z"
 }

package/docs/agent-guide.md

@@ -359,7 +359,10 @@ instruction to the agent's prompt automatically when the node declares `emits`.
 omits the fact, the `default` branch is taken.
 
 **Result statuses are added automatically. Don't write them into your prompt.** Every agent
-node's prompt gets the allowed terminal statuses (`done` / `opened` / `skipped`). A completion
+node's prompt gets the allowed terminal statuses (`done` / `opened` / `skipped`, plus the
+unambiguous affirmative-completion aliases `completed` / `succeeded` / `success` — issue #932:
+a fully-delivered node reporting one of those is a terminal success, never a contract
+violation). A completion
 moves on only with one of those statuses and every required emit present. Anything else parks
 the run on a human `__contract` escalation — **except** an absent/null `status`, which a legacy
 worker that populates its required emits may still advance with (the status contract binds only

package/e2e/delivery-graph.e2e.ts

@@ -373,6 +373,66 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the satisfied producer's result reaches End");
   });
 
+  test("#932 producer contract: an agent reporting status=completed with all required emits routes onward and NEVER reaches a human escalation", async () => {
+    const app = track(await boot(freshDir()));
+
+    // Issue #932's observed failure (nano-bpm#1337 → PR #1464 escalation 584376; nano-bpm#1463 →
+    // PR #1476 escalation 599960): the agent FULLY delivered — required `pr` emit present, work done,
+    // PR later merged — but self-reported the affirmative-completion alias `status: "completed"`,
+    // which the #731 gate (accepting only `done`/`opened`/`skipped`) treated as a contract violation
+    // and parked on a human "Continue" escalation. With the synonym allowlisted in the ONE canonical
+    // vocabulary, the same result must sail through the gate: no __contract task, the downstream
+    // connector fires, the graph reaches End.
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return { status: "completed", pr: "owner/repo#100", summary: "Fully delivered; PR opened and green." };
+    });
+    let connectorFired = 0;
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        connectorFired++;
+        const vars = job.variables as Record<string, unknown>;
+        const { target, payload, boundFacts } = readConnectorInput(vars as Parameters<typeof readConnectorInput>[0]);
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        if (!dedupeKey) throw new Error("connector stub: no dedupe key (author-supplied or graph-derived) available");
+        return await dispatchConnector(app.db, { dedupeKey, target, payload, boundFacts }, new Date().toISOString());
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e producer gate completed synonym",
+      nodes: [
+        { id: "open", kind: "agent", agent: { jobType: "senior:demo" }, emits: [{ name: "pr", type: "pr" }] },
+        { id: "land", kind: "connector", connector: { target: "slack", payload: { pr: "open.pr" }, dedupeKey: "land-932" } },
+      ],
+      edges: [{ from: "open.pr", to: "land" }],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The `completed` report + all required emits is a terminal success: it routes ONWARD — no
+    // producer-contract escalation (and no escalation of any kind), the connector fired once on the
+    // real PR, and the graph reached End. A human is never in the loop.
+    assert.equal(agentFired, 1, "the agent node's job fired and completed");
+    const createdTasks = await app.engine.searchUserTasks({ state: "CREATED" });
+    assert.deepEqual(
+      createdTasks.map((t) => t.elementId),
+      [],
+      `a fully-delivered "completed" result must NEVER park a human task, got ${JSON.stringify(createdTasks.map((t) => t.elementId))}`,
+    );
+    assert.equal(connectorFired, 1, "the satisfied producer threads its result to the downstream connector");
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the completed producer's result reaches End");
+  });
+
   test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
     const app = track(await boot(freshDir()));
     // The connector fired once above's-style; here prove the idempotency directly against the ledger a

package/package.json

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