@nanobpm/nano-workforce 0.138.1 → 0.138.3

package/AGENTS.md

@@ -211,6 +211,42 @@ Two different `nano:dataEnvelope` uses have different rules — don't conflate t
   deriving a worker's array inputs from the model this way over a hand-typed
   `interface In`; don't "fix" a modelled `list="true"` array back to a joined
   scalar.
+- **A service-task/worker `dataEnvelope.in` field is read from PROCESS scope, not
+  task-local `ioMapping`.** (This applies to service-task/worker job envelopes; a
+  `dataEnvelope.in` on a **message subscription** — e.g. `CapsResolved` at
+  `plan-fanout.bpmn:12` — is instead populated from the correlated **message
+  payload**, so this gotcha does not apply there.) At runtime the engine populates
+  each declared `.in` field *by name* from the process variables in scope — a
+  `<zeebe:ioMapping>` input that synthesises a **new** name with no backing process
+  variable is silently ignored, so the field arrives **blank**. The engine itself
+  raises no incident for that *omitted* field (an `.in` name with no backing
+  variable resolves to null and blanks) — but this is distinct from a FEEL
+  `ioMapping` that **errors**: on the pinned engine (`@nanobpm/engine-wasm` 0.8.1's
+  `IO_MAPPING_ERROR` fix — before it, a failed mapping silently blanked, e.g. a
+  blocked converge-gate's escalation *question*; see the `e2e/*escalation*.e2e.ts`
+  comments) a failed FEEL mapping now raises an **incident** rather than blanking
+  through. A consumer that fails fast on the blank value will also incident (e.g.
+  `pr.readiness-probe` once read an empty `gateKey`;
+  `readGateVars` in `workers/readiness-probe/worker.ts` now *throws* on a blank
+  `gateKey`, creating an incident). Tasks like `ensure-base-branch` work only because
+  `repo`/`baseBranch` already exist as process variables. Seed any field a task must
+  read — **that is not already created in the task's visible process scope** — as a
+  real process variable at plan start (e.g. in `startPlan`); don't rely on
+  `ioMapping` to synthesise it. (A field already materialised in scope by the
+  process — e.g. `ReadinessProbeIn.probe`, seeded per multi-instance child via
+  `inputElement="probe"` in `resources/processes/feature.bpmn` — needs no such
+  seeding.) A **constant/literal** ioMapping source is different again: a
+  `<zeebe:input source="=true" target="lastAttempt"/>` (the readiness-gate
+  boundary's last-attempt marker — `readiness-gate.bpmn:125`, `feature.bpmn:105`,
+  `plan-fanout.bpmn:198`, and the generated `deliveryGraphCompiler.ts:1011`) is
+  *evaluated* and materialised into the job's scope, so it needs **no** backing
+  process variable — its value is the literal, not a reference to an (absent)
+  variable. The "arrives blank" failure above is specific to a field whose value
+  must be *derived from a process variable that isn't in scope* (the `gateKey`
+  case). Do **not** "fix" a working literal marker like `lastAttempt` by seeding
+  it as a process variable: besides being unnecessary, seeding a var an
+  in-subprocess gateway reads re-introduces the multi-instance `=null`-shadow
+  gotcha above.
 
 ## Urban page runtime: rendering primitives are not JS-truthy
 
@@ -235,6 +271,21 @@ silently — cheap to avoid, annoying to debug after the fact.
   `showWhenField` is hidden for `0`/`null`/`""` alike — so a `0`-or-`NULL` flag
   correctly hides it either way. (This is why the same flag can need `NULL` for a
   badge yet work as `0` for a `showWhenField` button.)
+- **Renderer kinds are a version-pinned set — verify against the installed
+  package, not an issue reference.** The page renderers are a finite set fixed by
+  the pinned `@nanobpm/urban`; a version *range* only guarantees *some* matching
+  build is installed. Do **not** assume a primitive exists because an issue,
+  changelog, or *Links* section mentions it — `urban check` (a CI gate) rejects
+  unknown renderer kinds only *after* you've authored a page around a phantom one
+  (epic #254 bounced three review rounds asserting a page-level "stepper" that
+  never shipped). Confirm the kind against the installed `RENDERERS` map
+  (`node_modules/@nanobpm/urban/dist/runtime/core/modules/pages.js`) and the kinds
+  already used across `pages/*.page.json`. Note a **nano-ide issue can ship a data
+  read-model, not a page renderer** (nano-ide#254 shipped the lineage projection, a data
+  primitive) — read *what kind* of primitive it delivers. Build composite visuals
+  as a `dataGrid` column renderer over stored columns (e.g. the `"kind":
+  "pipeline"` column in `pages/feature.page.json`), not a page-level primitive,
+  unless you've verified that primitive exists in the installed build.
 
 ### The top nav has a single source of truth — edit `pages/_nav.json`
 
@@ -271,10 +322,24 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
 - Number a new migration after the current highest prefix (they apply in order).
   Check `origin/main`, not your branch point — a fan-out epic branch forks at one
   prefix while `main` keeps advancing, so the branch-local "next" number collides
-  on merge. Two files must never share a prefix; `npm run check:migrations`
+  on merge. **In a *simultaneous* fan-out wave, checking `origin/main` isn't
+  enough**: every sibling forks at the same commit, sees the same highest prefix,
+  and independently takes the same next number (main hasn't advanced yet), so the
+  planner must **pre-assign each slice a disjoint prefix block at decomposition
+  time** (e.g. give slice A `NNN`–`NNN+1`, slice B `NNN+2`–`NNN+3`, plus a separate
+  cleanup block — start the whole allocation *after* the current highest committed
+  prefix, never at fixed literals like `060`, which are long occupied) rather than
+  have each
+  agent compute "the next free" prefix. (This is the same "coarsen parallel work on
+  a shared surface" principle as the one-task-owns-each-`.bpmn` rule above — a
+  migration-prefix block is a shared numbering surface just like a `.bpmn`
+  diagram.) Two files must never share a prefix; `npm run check:migrations`
   (a CI gate) enforces this and fails the build on any new duplicate. Because a
-  prefix collision only exists in the *union* of two branches, this gate — like
-  `layout:check` and the generated-artifact `--check`s — is also re-run on the
+  **merge-skew** prefix collision only exists in the *union* of two branches (a
+  single branch that adds two same-prefix files is a self-collision
+  `check:migrations` already catches on the PR itself), this gate — like
+  `layout:check`, the navigation-index check (`sync:nav:check`), and a catch-all
+  committed-artifact backstop (`git diff --exit-code`) — is also re-run on the
   merge queue's **prospective merged commit** and on **push to `main`** by
   `.github/workflows/invariants.yml` (issue #366), so a merge-skew collision is
   blocked at merge time or fails a `main`-scoped build within minutes rather than

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.138.3](https://github.com/nanobpm/nano-workforce/compare/v0.138.2...v0.138.3) (2026-08-24)
+
+### Bug Fixes
+
+* **epic-detail:** derive plan_wave_tasks.status=merged so a landed slice isn't stranded at "opened" ([#530](https://github.com/nanobpm/nano-workforce/issues/530)) ([#531](https://github.com/nanobpm/nano-workforce/issues/531)) ([3893f7f](https://github.com/nanobpm/nano-workforce/commit/3893f7fe5534a1510b53a489a0aa83630c6207b9))
+
+## [0.138.2](https://github.com/nanobpm/nano-workforce/compare/v0.138.1...v0.138.2) (2026-08-24)
+
+### Documentation
+
+* **agents:** consolidate retro feedback ([#268](https://github.com/nanobpm/nano-workforce/issues/268), [#322](https://github.com/nanobpm/nano-workforce/issues/322), [#449](https://github.com/nanobpm/nano-workforce/issues/449)); drop stale [#415](https://github.com/nanobpm/nano-workforce/issues/415) ([#518](https://github.com/nanobpm/nano-workforce/issues/518)) ([3c47cb2](https://github.com/nanobpm/nano-workforce/commit/3c47cb21d079b6b9f5470abacb0190373208d0ca)), closes [#416](https://github.com/nanobpm/nano-workforce/issues/416) [#887](https://github.com/nanobpm/nano-workforce/issues/887) [#254](https://github.com/nanobpm/nano-workforce/issues/254) [#254](https://github.com/nanobpm/nano-workforce/issues/254) [nano-ide#254](https://github.com/nanobpm/nano-ide/issues/254)
+
 ## [0.138.1](https://github.com/nanobpm/nano-workforce/compare/v0.138.0...v0.138.1) (2026-08-24)
 
 ### Bug Fixes

package/app/planReadModel.test.ts

@@ -49,6 +49,7 @@ const MIGRATION_CHAIN = [
   "080_plan_read_model_derive_terminal.sql",
   ROLLUPS_MIGRATION,
   READ_MODEL_MIGRATION,
+  "084_plan_wave_tasks_effective_status.sql",
 ];
 
 // The base `plans` / `plan_tasks` / `pull_requests` shapes the VIEWs read, plus a stand-in for the
@@ -430,6 +431,28 @@ test("plan_wave_tasks carries each task's PR url + process_key link targets (unc
   assertEquals({ pr_url: rows[1].pr_url, process_key: rows[1].process_key }, { pr_url: null, process_key: null });
 });
 
+test("plan_wave_tasks derives status=merged from the PR (never strands a landed slice at 'opened') — matching the summary bar", () => {
+  // The reported defect (#530): a slice whose PR converged + merged kept reading Status "opened" in
+  // the wave-state grid, because nothing writes `plan_tasks.status='merged'` on merge and the VIEW
+  // exposed the raw task status. The fix DERIVES the displayed status the SAME way the count VIEWs
+  // bucket `merged` — `pull_requests__tracking.derived_status = 'merged'` overrides the raw status —
+  // so the per-task grid and the per-wave summary bar agree.
+  const db = viewDb();
+  addPlan(db, "o/r#eff", { status: "done" });
+  addTask(db, "o/r#eff", { status: "opened", wave: 0, prStatus: "merged" }); // landed slice, task row frozen at "opened"
+  addTask(db, "o/r#eff", { status: "opened", wave: 0, prStatus: "converging" }); // still converging → stays "opened"
+  addTask(db, "o/r#eff", { status: "blocked", wave: 0 }); // no PR → raw status untouched
+  // A DERIVE-ONLY merged edge (base PR status frozen, tracking recomputes to `merged`) also reads merged.
+  addTask(db, "o/r#eff", { status: "opened", wave: 1, prStatus: "converging", prDerivedOverride: "merged" });
+  const byWaveIdx = db
+    .prepare("SELECT wave, task_index, status FROM plan_wave_tasks WHERE plan_key = ? ORDER BY task_index")
+    .all("o/r#eff") as Array<Record<string, unknown>>;
+  assertEquals(byWaveIdx.map((r) => r.status), ["merged", "opened", "blocked", "merged"]);
+  // The count VIEW and the per-task grid now agree on the merged tally for wave 0 (3 slices, 1 merged).
+  const c = db.prepare("SELECT merged, total FROM plan_wave_counts WHERE plan_key = ? AND wave = 0").get("o/r#eff") as Record<string, unknown>;
+  assertEquals({ merged: Number(c.merged), total: Number(c.total) }, { merged: 1, total: 3 });
+});
+
 test("the operator pages bind the derived plan-family VIEWs (never the raw plans table)", () => {
   // Overview + Epic index + Epic detail all read the composite `plan_read_model`; the epic-detail
   // per-wave summary reads `plan_wave_summary` (the bar), and the wave-state grid `plan_wave_tasks`.

package/db/migrations/084_plan_wave_tasks_effective_status.sql

@@ -0,0 +1,51 @@
+-- Epic-detail wave-state: a merged slice must not read "opened" (drift with the summary bar).
+--
+-- `plan_wave_tasks` (059) is the per-task display VIEW the Epic-detail "Wave state" grid binds
+-- (pages/epic-detail.page.json → `wave-state`). Its `status` column exposed the RAW
+-- `plan_tasks.status` verbatim — but nothing writes `plan_tasks.status = 'merged'` when a slice's PR
+-- lands: the merge write-path flips `pull_requests.status` (and, for a close-without-merge, the
+-- `abandonClosedPr` self-heal flips the task terminal), yet a *merged* PR leaves its `plan_tasks` row
+-- frozen at `opened`. So a converged-and-merged slice kept showing Status "opened" in the grid, even
+-- as its sibling summary VIEWs (`plan_wave_counts`/`plan_wave_summary`) already counted it `merged`
+-- via the PR join. That is exactly the drift AGENTS.md forbids: two sibling VIEWs over the same join
+-- disagreeing on whether a slice is merged.
+--
+-- Fix by DERIVING the displayed status the SAME way the count VIEWs bucket `merged` (082): a task is
+-- `merged` iff its PR reached `pull_requests__tracking.derived_status = 'merged'` (the terminal-folded
+-- status the canonical runtime reads, ADR-0065), otherwise it falls through to its own
+-- `plan_tasks.status`. This keeps the per-task grid and the per-wave summary bar in exact agreement —
+-- a single notion of "effective task status", still fully DERIVED with no write-path. `pr_url` /
+-- `process_key` link targets are re-exported by the `pull_requests__tracking` VIEW (`p.*`), so the
+-- single join now sources both the effective status and the link targets. The "Active" tab filter
+-- (`status IN (pending,opened,escalated,waiting-for-lane,blocked)`) therefore drops a merged slice as
+-- intended instead of stranding it under "opened".
+--
+-- Forward-only VIEW redefinition (DROP then CREATE); a merged VIEW is not editable in place. The
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Kept a
+-- plain `CREATE VIEW … AS SELECT … FROM …` (no CTE / no select-list subquery) so the static
+-- pages↔schema contract guard (scripts/pages-contract.test.ts) still parses it. Numbered after 083.
+
+DROP VIEW IF EXISTS plan_wave_tasks;
+
+CREATE VIEW plan_wave_tasks AS
+SELECT
+  t.id AS id,
+  t.plan_key AS plan_key,
+  t.task_index AS task_index,
+  t.task_id AS task_id,
+  t.title AS title,
+  t.prompt AS prompt,
+  CASE WHEN p.derived_status = 'merged' THEN 'merged' ELSE t.status END AS status,
+  t.pr_key AS pr_key,
+  t.summary AS summary,
+  t.created_at AS created_at,
+  t.updated_at AS updated_at,
+  t.wave AS wave,
+  t.open_question AS open_question,
+  t.answer AS answer,
+  t.draft_pr_key AS draft_pr_key,
+  t.corr_key AS corr_key,
+  p.url AS pr_url,
+  p.process_key AS process_key
+FROM plan_tasks t
+LEFT JOIN pull_requests__tracking p ON p.pr_key = t.pr_key;

package/package.json

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