@nanobpm/nano-workforce 0.107.2 → 0.108.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.108.0](https://github.com/nanobpm/nano-workforce/compare/v0.107.2...v0.108.0) (2026-08-20)
+
+
+### Features
+
+* **derivation-parity:** un-park retro to full whole-model parity ([#372](https://github.com/nanobpm/nano-workforce/issues/372)) ([1320838](https://github.com/nanobpm/nano-workforce/commit/1320838251646258ec2151a547ed2b5573ce1168)), closes [nano-ide#405](https://github.com/nano-ide/issues/405) [355/#356](https://github.com/nanobpm/nano-workforce/issues/356) [#371](https://github.com/nanobpm/nano-workforce/issues/371)
+
 ## [0.107.2](https://github.com/nanobpm/nano-workforce/compare/v0.107.1...v0.107.2) (2026-08-20)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.107.2",
+  "version": "0.108.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",
@@ -64,7 +64,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
     "@nanobpm/urban-testkit": "^0.5.0",
-    "@nanobpm/workflow": "^0.12.0",
+    "@nanobpm/workflow": "^0.13.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

package/scripts/check-derivation-parity.ts

@@ -15,19 +15,20 @@
 //
 // Any structural drift (b) OR deploy rejection (c) fails the build.
 //
-// PARKED MODELS ARE ACCOUNTED FOR, NOT IGNORED. The corpus is currently fully parked behind
-// upstream `@nanobpm/workflow` constructs (see test/derivation-parity/flows.ts for the three blocker
-// classes). Each parked model must carry a documented `blockedReason`; a model that is neither
-// ported nor documented fails this gate, so the corpus can never silently lose coverage. As each
-// parked model flips to a real `flow` upstream, it is automatically pulled into the full
-// derive → diff → deploy loop here with NO change to this script.
+// PARKED MODELS ARE ACCOUNTED FOR, NOT IGNORED. `retro` is a green whole-model parity port; the
+// remaining corpus is parked behind upstream `@nanobpm/workflow` constructs (see
+// test/derivation-parity/flows.ts for the two blocker classes). Each parked model must carry a
+// documented `blockedReason`; a model that is neither ported nor documented fails this gate, so the
+// corpus can never silently lose coverage. As each parked model flips to a real `flow` upstream, it
+// is automatically pulled into the full derive → diff → deploy loop here with NO change to this
+// script.
 //
-// SELF-PROVING CANARY. Because the corpus is (today) all-parked, a gate that merely iterated it
-// would be a vacuous green — it could rot without anyone noticing. So before touching the corpus we
-// run a CANARY that proves the oracle's RED path genuinely fires: a faithful derived flow deploys
-// green and diffs green, a drifted derivation is CAUGHT by the diff, and a corrupted model is
-// REJECTED by the engine. If any red path fails to fire (the diff misses drift, or the engine
-// accepts garbage), the gate fails — the oracle must be able to say no.
+// SELF-PROVING CANARY. To keep the gate honest even while most of the corpus is parked, a gate that
+// merely iterated it could be a near-vacuous green — it could rot without anyone noticing. So before
+// touching the corpus we run a CANARY that proves the oracle's RED path genuinely fires: a faithful
+// derived flow deploys green and diffs green, a drifted derivation is CAUGHT by the diff, and a
+// corrupted model is REJECTED by the engine. If any red path fails to fire (the diff misses drift,
+// or the engine accepts garbage), the gate fails — the oracle must be able to say no.
 
 import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";

package/test/derivation-parity/README.md

@@ -26,7 +26,7 @@ behind an upstream construct, and do **not** relax to node-surface parity_:
 
 | Model              | Top-level start/end | Status |
 | ------------------ | ------------------- | ------ |
-| `retro`            | 1 / 1               | ⛔ parked — class 3 (general service-task ioMapping) |
+| `retro`            | 1 / 1               | ✅ green — whole-model parity |
 | `convergence-loop` | 1 / 1               | ⛔ parked — class 2 (arbitrary graph) |
 | `spine-demo`       | 1 / 2               | ⛔ parked — class 1 (multi start/end) |
 | `readiness-gate`   | 1 / 5               | ⛔ parked — class 1 (multi start/end) |
@@ -34,13 +34,17 @@ behind an upstream construct, and do **not** relax to node-surface parity_:
 | `merge-loop`       | 1 / 2               | ⛔ parked — class 1 (multi start/end) |
 | `plan-fanout`      | 3 / 3               | ⛔ parked — class 1 (multi start/end) |
 
-`retro` was a green full-parity port — a linear single-start/single-end agent
-pipeline — until the conformance work (#355/#356) added a conformance-escalation
-subgraph to its golden, which introduced a service task carrying a general
-`<zeebe:ioMapping>` the stock `task` builder cannot emit (class 3). All seven
-goldens are now parked, across **three** distinct blocker classes, each awaiting
-an upstream `@nanobpm/workflow` (nano-ide) construct + re-release (never a golden
-edit, never relaxed acceptance).
+`retro` is a green whole-model parity port — a single-start/single-end agent
+pipeline (gather → conformance → record-conformance) with a `deviations?`
+conformance-escalation subgraph (#355/#356) and a shared synthesize → record
+tail. Its `record-conformance-ack` service task carries a general
+`<zeebe:ioMapping>` that the stock `task` builder could not emit until
+`@nanobpm/workflow@0.13.0` landed the general service-task `io` construct
+(nano-ide#405); every other element was always expressible (`w.task`+prompt,
+`w.branch`, `w.human`, envelopes). The remaining six goldens are parked across
+**two** distinct blocker classes, each awaiting an upstream `@nanobpm/workflow`
+(nano-ide) construct + re-release (never a golden edit, never relaxed
+acceptance).
 
 ## The blockers
 
@@ -83,24 +87,6 @@ pinned by a diagnostic in `derivation-parity.test.ts`:
 The fix is an **arbitrary-graph / explicit-join (named-target)** builder upstream
 in `@nanobpm/workflow` — a **superset** of the class-1 gap.
 
-### Class 3 — general service-task ioMapping (`retro`)
-
-`retro` clears classes 1 and 2 (single start/end, structured topology), but its
-golden's `record-conformance-ack` service task carries a **general**
-`<zeebe:ioMapping>` — inputs `=planKey`→`planKey` and
-`=if (is defined(note)) then note else null`→`note`. `@nanobpm/workflow@0.12.0`'s
-`task` builder only emits an ioMapping as a side effect of a `prompt.append` (a
-single `appendPrompt` input); there is no way to declare arbitrary input/output
-mappings on a service task. Every other element of the golden IS expressible
-(`w.task`+prompt, `w.branch` for the `deviations?` gateway, `w.human` for the
-`conformance-escalation` userTask, envelopes) — this one service-task ioMapping
-is the sole gap. The `retro golden needs a general service-task ioMapping the
-stock builder cannot emit` diagnostic pins both halves (the golden needs it; the
-stock builder cannot produce it).
-
-The fix is a general `io: { input?, output? }` on the external `task`/`run`
-builder upstream in `@nanobpm/workflow` (**nano-ide#405**).
-
 ## Resuming this slice
 
 The follow-up upstream slices (opened in **nanobpm/nano-ide** per decision path
@@ -108,8 +94,11 @@ The follow-up upstream slices (opened in **nanobpm/nano-ide** per decision path
 
 - a terminal / explicit-end (+ multi-start) construct (unblocks class 1), **and**
 - an arbitrary-graph / explicit-join (named-target) builder (unblocks class 2 —
-  `convergence-loop`), **and**
-- a general service-task `io` mapping (unblocks class 3 — `retro`; nano-ide#405).
+  `convergence-loop`).
+
+(The class-3 general service-task `io` mapping has already landed —
+`@nanobpm/workflow@0.13.0`, nano-ide#405 — unparking `retro` to whole-model
+parity.)
 
 Then, on a resumed run here:
 
@@ -140,7 +129,7 @@ documented `blockedReason`, so the corpus can never silently lose coverage; a
 parked model flips into the full derive → diff → deploy loop automatically the
 moment its `flow` lands — no change to the gate.
 
-Because the corpus is (currently) fully parked, the gate runs a **self-proving
+Because most of the corpus is (currently) parked, the gate runs a **self-proving
 canary** first: it proves a faithful derivation deploys and diffs green, a
 drifted derivation is caught by the diff, and a corrupted model is rejected by
 the engine — so the oracle's red path can never rot into a vacuous green. The

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

@@ -85,8 +85,8 @@ test("class-1 blocked goldens genuinely have multiple top-level start/end events
   }
 
   // The two single-start/single-end goldens (retro, convergence-loop) clear
-  // class 1; retro is class-3 blocked (a general service-task ioMapping),
-  // convergence-loop is class-2 blocked — both below.
+  // class 1; retro is a GREEN whole-model parity port (it runs through
+  // `assertDerivationParity` above), convergence-loop is class-2 blocked (below).
   for (const model of ["retro", "convergence-loop"]) {
     const xml = readFileSync(goldenPath(model), "utf8");
     assertEquals(countTag(xml, "startEvent"), 1, `${model} should have one start event`);
@@ -94,37 +94,6 @@ test("class-1 blocked goldens genuinely have multiple top-level start/end events
   }
 });
 
-// CLASS 3 — retro clears classes 1 & 2 (single start/end, structured topology)
-// but its golden carries a service task with a GENERAL <zeebe:ioMapping> — inputs
-// whose target is NOT `appendPrompt` — which @nanobpm/workflow@0.12.0's `task`
-// builder cannot emit (it only produces an ioMapping via a `prompt.append`, i.e.
-// a lone `appendPrompt` input). Prove both halves: the golden needs it, and the
-// stock builder cannot produce it (awaits nano-ide#405).
-test("retro golden needs a general service-task ioMapping the stock builder cannot emit", () => {
-  const xml = readFileSync(goldenPath("retro"), "utf8");
-  // (a) The golden has a service task carrying an ioMapping input to a non-prompt
-  //     target (`record-conformance-ack`: =planKey→planKey, note→note).
-  assert(
-    /target="planKey"/.test(xml) && /target="note"/.test(xml),
-    "retro golden should carry general ioMapping inputs (planKey, note) on record-conformance-ack",
-  );
-  // (b) The stock `task` builder only ever emits `appendPrompt` as an ioMapping
-  //     target — never a general input like `note` — so the golden is not
-  //     derivable until the upstream `io` construct lands.
-  const probe = defineFlow("io-probe", (w) => {
-    w.task("agent", {
-      jobType: "senior:retro",
-      prompt: { resourceId: "retro.md", bindingType: "latest", append: "=retroDigest" },
-    });
-  });
-  const derived = declarativeToBpmn(probe);
-  assert(/target="appendPrompt"/.test(derived), "prompt.append should emit an appendPrompt ioMapping input");
-  assert(
-    !/target="note"/.test(derived) && !/target="planKey"/.test(derived),
-    "the stock task builder cannot emit a general (non-appendPrompt) ioMapping input",
-  );
-});
-
 // CLASS 2 — convergence-loop has a single start/end (clears class 1) but an
 // ARBITRARY control-flow graph the structured-only builder cannot emit. Prove
 // the three specific features against the golden itself.

package/test/derivation-parity/flows.ts

@@ -9,12 +9,13 @@
 // the structurally-derivable goldens at full whole-model parity, park the rest
 // pending an upstream construct, and do NOT relax to node-surface parity):
 //
-//   • All seven goldens are currently `blockedReason`-parked, in THREE distinct
-//     classes, each awaiting an upstream `@nanobpm/workflow` (nano-ide) construct
-//     + re-release — never a golden edit and never relaxed acceptance:
+//   • `retro` is a GREEN whole-model parity port (see below). The remaining six
+//     goldens are `blockedReason`-parked, in TWO distinct classes, each awaiting
+//     an upstream `@nanobpm/workflow` (nano-ide) construct + re-release — never a
+//     golden edit and never relaxed acceptance:
 //
 //     (1) MULTI top-level start/end (spine-demo, readiness-gate, feature,
-//         merge-loop, plan-fanout). `@nanobpm/workflow@0.12.0` derives EXACTLY
+//         merge-loop, plan-fanout). `@nanobpm/workflow` derives EXACTLY
 //         ONE `<bpmn:startEvent id="Start">` + ONE `<bpmn:endEvent id="End">`,
 //         converging every dangler into that single end (see `Compiler.compile`
 //         in the package's `declarative.ts`). Needs a terminal/explicit-end
@@ -34,23 +35,10 @@
 //         arbitrary-graph / explicit-join (named-target) builder — a SUPERSET of
 //         the class-(1) gap.
 //
-//     (3) GENERAL service-task ioMapping (retro). retro WAS a green full-parity
-//         port (a linear gather → synthesize → record agent pipeline) until the
-//         conformance work (nano-workforce #355/#356) added a conformance-
-//         escalation subgraph to its golden. Every new element ports with the
-//         stock builder (`w.branch` for the `deviations?` gateway, `w.human` for
-//         the `conformance-escalation` userTask, `w.task`+prompt/envelopes for
-//         the service tasks) EXCEPT `record-conformance-ack`: a service task with
-//         a general <zeebe:ioMapping> (inputs `=planKey`→planKey and
-//         `=if (is defined(note)) then note else null`→note). @nanobpm/workflow@
-//         0.12.0's `task` builder only emits an ioMapping via a `prompt.append`
-//         (a single `appendPrompt` input), so this task is not derivable. Needs a
-//         general `io` on the task/run builder upstream (nano-ide#405).
-//
 // A resumed run flips any parked model to a real `flow` once the corresponding
-// upstream construct lands and `@nanobpm/workflow` is bumped past 0.12.0.
+// upstream construct lands and `@nanobpm/workflow` is bumped to carry it.
 
-import type { DeclarativeFlow } from "@nanobpm/workflow";
+import { type DeclarativeFlow, defineFlow, envelope } from "@nanobpm/workflow";
 
 /** One model's port entry: the golden basename plus EITHER the derived flow
  *  (when it can be reproduced) OR the reason it is blocked — never both and never
@@ -72,38 +60,87 @@ export type PortEntry =
       readonly blockedReason: string;
     };
 
-// ── retro (PARKED — class 3) ─────────────────────────────────────────────────
-// retro WAS a green full-parity port — a linear gather → synthesize → record
-// agent pipeline. The conformance work (nano-workforce #355/#356) then added a
-// conformance-escalation subgraph to the golden: a `deviations?` exclusive
-// gateway, a `conformance-escalation` userTask, and `senior:conformance` /
-// `pr.conformance-record` / `pr.conformance-ack` service tasks. All of those ARE
-// expressible with the stock builder (`w.branch`, `w.human`, `w.task`+prompt,
-// envelopes) EXCEPT `record-conformance-ack`: it carries a general
+// ── retro (GREEN — whole-model parity) ───────────────────────────────────────
+// retro is a single-start/single-end model: a linear gather → conformance →
+// record-conformance agent pipeline, a `deviations?` exclusive gateway guarding a
+// conformance-escalation subgraph (nano-workforce #355/#356), then a shared
+// synthesize → record tail. Every element ports with the stock builder:
+// `w.task`+envelopes for the data-envelope service tasks, `w.task`+prompt for the
+// two agent tasks (`senior:conformance`, `senior:retro`), `w.branch` for the
+// `deviations?` gateway, `w.human` for the `conformance-escalation` userTask, and
+// — since @nanobpm/workflow@0.13.0 landed the general service-task `io` construct
+// (nano-ide#405) — `w.task`+`io` for `record-conformance-ack`'s general
 // <zeebe:ioMapping> (inputs `=planKey`→planKey and
-// `=if (is defined(note)) then note else null`→note), which
-// @nanobpm/workflow@0.12.0's `task` builder cannot emit — it only produces an
-// ioMapping via a `prompt.append` (a single `appendPrompt` input). So retro
-// regresses to a parked model pending the upstream construct: a general `io` on
-// the external `task`/`run` builder (nano-ide#405). It flips back to a green
-// port once that lands and @nanobpm/workflow is bumped past 0.12.0.
+// `=if (is defined(note)) then note else null`→note).
+
+/** The typed data envelopes retro's non-agent service tasks lift into the model
+ *  (`nano:shape` + `io.nanobpm.dataEnvelope.in`), matching the golden's shapes. */
+const RetroGatherIn = envelope("RetroGatherIn", { planKey: "string" });
+const RetroRecordIn = envelope("RetroRecordIn", {
+  planKey: "string",
+  retroLearnings: { type: "integer", optional: true },
+  status: { type: "string", optional: true },
+  pr: { type: "string", optional: true },
+  summary: { type: "string", optional: true },
+});
+const ConformanceRecordIn = envelope("ConformanceRecordIn", {
+  planKey: "string",
+  status: { type: "string", optional: true },
+  commentUrl: { type: "string", optional: true },
+  slicesMet: { type: "integer", optional: true },
+  slicesReduced: { type: "integer", optional: true },
+  slicesNotVerified: { type: "integer", optional: true },
+  deviationsRaised: { type: "integer", optional: true },
+  deviationsUnraised: { type: "integer", optional: true },
+  hasDeviations: { type: "boolean", optional: true },
+  summary: { type: "string", optional: true },
+});
 
-const RETRO_IO_BLOCK =
-  "blocked (general service-task ioMapping): retro's golden gained a " +
-  "conformance-escalation subgraph whose `record-conformance-ack` service task " +
-  "carries a general <zeebe:ioMapping> (inputs =planKey→planKey and " +
-  "=if (is defined(note)) then note else null→note). @nanobpm/workflow@0.12.0's " +
-  "`task` builder only emits an ioMapping via a `prompt.append` (a single " +
-  "appendPrompt input), so this task is not derivable. Every other element of " +
-  "the golden IS expressible (w.task+prompt, w.branch, w.human, envelopes). " +
-  "Awaits a general `io` on the task/run builder upstream in @nanobpm/workflow " +
-  "(nano-ide#405).";
+/** The code-first port of `resources/processes/retro.bpmn`. */
+const retroFlow: DeclarativeFlow = defineFlow(
+  "retro",
+  {
+    gather: { in: RetroGatherIn },
+    "record-conformance": { in: ConformanceRecordIn },
+    record: { in: RetroRecordIn },
+  },
+  (w) => {
+    w.task("gather", { jobType: "pr.retro-gather" });
+    w.task("conformance", {
+      jobType: "senior:conformance",
+      prompt: { resourceId: "conformance.md", bindingType: "latest", append: "=conformanceDigest" },
+    });
+    w.task("record-conformance", { jobType: "pr.conformance-record" });
+    w.branch("hasDeviations = true", {
+      then: (b) => {
+        b.human("conformance-escalation", {
+          form: "conformance-escalation",
+          candidateGroups: "operators",
+        });
+        b.task("record-conformance-ack", {
+          jobType: "pr.conformance-ack",
+          io: {
+            input: [
+              { source: "=planKey", target: "planKey" },
+              { source: "=if (is defined(note)) then note else null", target: "note" },
+            ],
+          },
+        });
+      },
+    });
+    w.task("synthesize", {
+      jobType: "senior:retro",
+      prompt: { resourceId: "retro.md", bindingType: "latest", append: "=retroDigest" },
+    });
+    w.task("record", { jobType: "pr.retro-record" });
+  },
+);
 
 /** The single-top-level-end/start compiler limitation, reused as the
  *  `blockedReason` for every golden that has more than one top-level start
  *  and/or end event. */
 const MULTI_START_END_BLOCK =
-  "blocked: @nanobpm/workflow@0.12.0 derives a single top-level start/end and " +
+  "blocked: the published @nanobpm/workflow compiler derives a single top-level start/end and " +
   "converges all danglers into one <endEvent id=\"End\">; this golden has " +
   "multiple top-level start and/or end events, which the published compiler " +
   "cannot reproduce. Awaits an upstream terminal/explicit-end (+ multi-start) " +
@@ -111,7 +148,7 @@ const MULTI_START_END_BLOCK =
 
 /** All seven ports, keyed by model, in the epic's stated authoring order. */
 export const PORTS: readonly PortEntry[] = [
-  { model: "retro", blockedReason: RETRO_IO_BLOCK },
+  { model: "retro", flow: retroFlow },
   {
     model: "spine-demo",
     blockedReason: `${MULTI_START_END_BLOCK} (spine-demo: 1 start, 2 ends)`,
@@ -128,7 +165,7 @@ export const PORTS: readonly PortEntry[] = [
     model: "convergence-loop",
     blockedReason:
       "blocked (arbitrary control-flow graph): single top-level start/end, but " +
-      "its topology is not expressible with @nanobpm/workflow@0.12.0's " +
+      "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 3 back-edges " +
       "directly (in=3), but loop() always inserts an exclusive-gateway head " +