@nanobpm/nano-workforce 0.96.1 → 0.97.1

package/AGENTS.md

@@ -236,6 +236,17 @@ silently — cheap to avoid, annoying to debug after the fact.
   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.)
 
+### The top nav has a single source of truth — edit `pages/_nav.json`
+
+The `nav` node (the top-bar item list, including the **Tasks** live open-tasks
+count badge) is **not** authored per page. It lives once in `pages/_nav.json` and
+is materialised into every `pages/*.page.json` by `scripts/sync-nav.ts`. To change
+a nav item or badge, edit `pages/_nav.json` then run **`npm run sync:nav`** — never
+hand-edit the `nav` node in a page file. `scripts/sync-nav.test.ts` (run under
+`npm test`) fails if any page's nav node drifts from the canonical source, and
+`npm run sync:nav:check` is the CI-friendly verify. This is the "no drift surfaces"
+rule applied to the nav that was previously copy-pasted across every page.
+
 ## The poller owns liveness/reconciliation
 
 `main.ts` runs a **self-scheduling** poll loop (`pollOnce` in `app/service.ts`),

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.97.1](https://github.com/nanobpm/nano-workforce/compare/v0.97.0...v0.97.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **merge-loop:** give merge-blocked escalation a question + gw-escalated guard ([#329](https://github.com/nanobpm/nano-workforce/issues/329)) ([#331](https://github.com/nanobpm/nano-workforce/issues/331)) ([abb2952](https://github.com/nanobpm/nano-workforce/commit/abb2952b5ff5874ff928085167f4a0fd5f0580e5))
+
+# [0.97.0](https://github.com/nanobpm/nano-workforce/compare/v0.96.1...v0.97.0) (2026-08-19)
+
+
+### Features
+
+* **nav:** live open-tasks count badge on the Tasks nav item ([#306](https://github.com/nanobpm/nano-workforce/issues/306)) ([#330](https://github.com/nanobpm/nano-workforce/issues/330)) ([10aa55a](https://github.com/nanobpm/nano-workforce/commit/10aa55af9a3d5c60f13391f9e17361b6b33ac653)), closes [nano-ide#338](https://github.com/nano-ide/issues/338) [nano-ide#342](https://github.com/nano-ide/issues/342)
+
 ## [0.96.1](https://github.com/nanobpm/nano-workforce/compare/v0.96.0...v0.96.1) (2026-08-19)
 
 

package/app/mergeEscalationQuestion.test.ts

@@ -0,0 +1,140 @@
+// Regression guard for the question-less merge escalation defect (issue #329).
+//
+// The merge loop (`resources/processes/merge-loop.bpmn`) raised escalations with NO question
+// whenever a PR was blocked by anything other than a merge conflict: `merge-esc-attempt` called
+// `pr.persist-escalation` with no `question`/`status` ioMapping, and its output flowed
+// UNCONDITIONALLY into `wait-merge-answer`. Two coupled defects fell out of that:
+//
+//   1. A blank question surfaced on the merge-driving inbox — the human was asked to answer but
+//      told nothing (observed live on nano-ide PR #354).
+//   2. Per ADR 0002 §1 a blank question is a NON-escalation: `pr.persist-escalation` opens no row
+//      and returns `escalated:false`. The convergence loop honours this via a `gw-escalated`
+//      branch; the merge loop had none, so a question-less job still parked a dead
+//      `wait-merge-answer` with nothing for a human to answer.
+//
+// The fix (mirroring the convergence loop): give `merge-esc-attempt` a human-actionable
+// `status`/`question` that distinguishes its four trigger conditions, and add a `gw-merge-escalated`
+// guard so a `persist-escalation` returning `escalated:false` re-enters the loop (re-arms the
+// poller) instead of parking a dead wait.
+//
+// These are pure text assertions over the committed BPMN (no engine), matching the repo's
+// lightweight model-guard style (see mergeRebaseArm.test.ts, mergeEscalationUserTask.test.ts).
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+function flowHasId(id: string, source: string, target: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*(?:/>|>)`));
+  if (!m) return false;
+  const tag = m[0];
+  return tag.includes(`sourceRef="${source}"`) && tag.includes(`targetRef="${target}"`);
+}
+
+function gatewayDefault(id: string, def: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:exclusiveGateway\\b[^>]*\\bid="${id}"[^>]*>`));
+  if (!m) return false;
+  return m[0].includes(`default="${def}"`);
+}
+
+// The <serviceTask> element for merge-esc-attempt, including its ioMapping. Unescape XML entities so
+// FEEL string literals (authored as `&#34;ready&#34;` inside the attribute) read naturally here.
+const escAttemptRaw = flat.match(/<bpmn:serviceTask\b[^>]*\bid="merge-esc-attempt"[\s\S]*?<\/bpmn:serviceTask>/);
+const escAttempt = escAttemptRaw
+  ? [escAttemptRaw[0].replace(/&#34;/g, '"').replace(/&amp;/g, "&").replace(/&#10;/g, "\n")]
+  : null;
+
+test("merge-esc-attempt carries a non-blank, human-actionable status + question", () => {
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  // Mirror the merge-esc-conflict mapping style: an explicit `blocked` status…
+  assertStringIncludes(el, "<zeebe:ioMapping", "merge-esc-attempt must set an ioMapping (was absent — the #329 defect)");
+  assertStringIncludes(el, 'target="status"', "merge-esc-attempt must set a `status`");
+  assertStringIncludes(el, 'target="question"', "merge-esc-attempt must set a non-blank `question`");
+  // Tighten: assert the explicit `status` INPUT MAPPING sets blocked, not merely the substring
+  // `="blocked"` (which the FEEL question's `agentVerdict = "blocked"` comparison would also satisfy
+  // even if the status mapping were removed/changed). Match tolerant of attribute order/spacing: the
+  // file is XML and a formatter could reorder `source`/`target` within the tag.
+  const escInputs = el.match(/<zeebe:input\b[^>]*\/>/g) ?? [];
+  const setsBlockedStatus = escInputs.some(
+    (t) => t.includes('target="status"') && t.includes('source="="blocked""'),
+  );
+  assert(setsBlockedStatus, "the explicit `status` input mapping must set `blocked`");
+});
+
+test("arm-merge clears the prior verdict `status` so a stale `blocked` cannot misclassify the CI-fix SLA escalation", () => {
+  // merge-esc-attempt captures `agentVerdict = status` to split its CI could-not-fix vs SLA question
+  // arms. On the SLA boundary path (`f_ci_sla`) no worker sets a fresh `status`, and every escalation
+  // task overwrites `status = "blocked"` (merge-esc-attempt line 194, merge-esc-conflict line 174).
+  // Without a reset, a retry after any prior escalation re-enters fix-ci with `status` still
+  // "blocked", so an SLA timeout would render the wrong ("could not fix") question. arm-merge is the
+  // single loop hub every fix-ci entry passes through, so clearing `status` there (to null) each
+  // iteration guarantees a genuine SLA reads no stale verdict. Nothing between arm-merge and the next
+  // verdict-setter (fix-ci/rebase) reads `status`, so the reset is safe.
+  const armRaw = flat.match(/<bpmn:serviceTask\b[^>]*\bid="arm-merge"[\s\S]*?<\/bpmn:serviceTask>/);
+  assert(armRaw, "arm-merge service task must exist");
+  const armOutputs = armRaw![0].match(/<zeebe:output\b[^>]*\/>/g) ?? [];
+  const clearsStatus = armOutputs.some(
+    (t) => t.includes('target="status"') && t.includes('source="=null"'),
+  );
+  assert(clearsStatus, "arm-merge must reset `status` to null each loop iteration so a stale `blocked` cannot misclassify the SLA escalation");
+});
+
+test("the question distinguishes all four blocked/SLA triggers rather than a single generic string", () => {
+  // Four flows route into merge-esc-attempt — the gate `blocked` default, CI could-not-fix,
+  // rebase could-not-resolve, and the CI-fix SLA. Each is a legitimately different escalation and
+  // the question must explain which one fired.
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  // gate blocked (gw-merge default): distinguishes on the `ready` mergeState + surfaces mergeStatus.
+  assertStringIncludes(el, 'mergeState = "ready"', "must branch on the gate-blocked (ready) trigger");
+  assertStringIncludes(el, "mergeStatus", "the gate-blocked question must surface the merge result");
+  // rebase could-not-resolve (conflict arm).
+  assertStringIncludes(el, 'mergeState = "conflict"', "must branch on the rebase (conflict) trigger");
+  // CI could-not-fix vs CI SLA both arrive with mergeState = blocked — split on the agent verdict,
+  // captured into a dedicated `agentVerdict` binding so the escalation-classification `status =
+  // "blocked"` override in the SAME ioMapping cannot make the SLA branch unreachable (issue #329
+  // review). Assert the question branches on that binding, not on the overwritten `status`.
+  assertStringIncludes(el, "agentVerdict", "must capture the agent verdict into a dedicated binding");
+  assertStringIncludes(el, 'agentVerdict = "blocked"', "must branch CI could-not-fix vs SLA on the agent verdict binding, not the overwritten status");
+});
+
+test("a gw-merge-escalated guard honours persist-escalation's escalated:false (mirrors the convergence loop)", () => {
+  // The escalation output no longer flows UNCONDITIONALLY into the durable answer wait: it passes
+  // through a gateway that reads the worker's `escalated` output.
+  assert(
+    flowHasId("f_m_escA", "merge-esc-attempt", "gw-merge-escalated"),
+    "merge-esc-attempt must route through gw-merge-escalated, not straight to wait-merge-answer",
+  );
+  // escalated:true → park the native user task for a human to answer.
+  assert(
+    flowHasId("f_m_escWait", "gw-merge-escalated", "wait-merge-answer"),
+    "gw-merge-escalated → wait-merge-answer (escalated) missing",
+  );
+  const escWait = flat.match(/<bpmn:sequenceFlow[^>]*id="f_m_escWait"[\s\S]*?<\/bpmn:sequenceFlow>/);
+  assert(escWait, "f_m_escWait flow missing");
+  assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
+  // escalated:false (a non-escalation, e.g. a blank question) → re-enter the loop, NOT a dead wait.
+  assert(
+    gatewayDefault("gw-merge-escalated", "f_m_escReenter"),
+    "gw-merge-escalated must default to f_m_escReenter (re-enter, not park)",
+  );
+  assert(
+    flowHasId("f_m_escReenter", "gw-merge-escalated", "arm-merge"),
+    "f_m_escReenter must re-arm the merge poller instead of parking a dead wait-merge-answer",
+  );
+});
+
+test("regression: a question-less escalation can no longer park a dead wait-merge-answer", () => {
+  // The exact #329 wedge: `merge-esc-attempt → wait-merge-answer` as a direct, unconditional edge.
+  // It must be gone — the only path into the answer wait from the attempt arm is now guarded by
+  // `escalated = true`.
+  assert(
+    !flowHasId("f_m_escA", "merge-esc-attempt", "wait-merge-answer"),
+    "merge-esc-attempt must NOT flow directly into wait-merge-answer (the #329 dead-wait defect)",
+  );
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.96.1",
+  "version": "0.97.1",
   "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",
@@ -43,6 +43,8 @@
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
+    "sync:nav": "node --experimental-strip-types scripts/sync-nav.ts",
+    "sync:nav:check": "node --experimental-strip-types scripts/sync-nav.ts --check",
     "dev": "urban dev",
     "pretest": "urban gen",
     "test": "node --experimental-strip-types --test",
@@ -53,7 +55,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.59.0"
+    "@nanobpm/urban": "^0.61.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/pages/_nav.json

@@ -0,0 +1,30 @@
+{
+  "type": "nav",
+  "id": "nav",
+  "props": {
+    "variant": "bar",
+    "title": "Nano Workforce",
+    "items": [
+      { "label": "Overview", "page": "overview" },
+      { "label": "Lineage", "page": "lineage" },
+      { "label": "Convergence", "page": "home" },
+      { "label": "Epics", "page": "epic" },
+      { "label": "Feature", "page": "feature" },
+      {
+        "label": "Tasks",
+        "page": "tasks",
+        "badge": {
+          "source": "app",
+          "table": "user_tasks",
+          "filter": [],
+          "tone": "danger",
+          "refreshMs": 5000,
+          "hideWhenZero": true
+        }
+      },
+      { "label": "Cockpit", "page": "cockpit" },
+      { "label": "Board", "page": "board" }
+    ],
+    "sticky": true
+  }
+}

package/pages/board.page.json

@@ -9,14 +9,46 @@
         "variant": "bar",
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
         ],
         "sticky": true
       }

package/pages/cockpit.page.json

@@ -9,14 +9,46 @@
         "variant": "bar",
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
         ],
         "sticky": true
       }

package/pages/epic-detail.page.json

@@ -7,18 +7,50 @@
       "id": "nav",
       "props": {
         "variant": "bar",
-        "sticky": true,
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
-        ]
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
+        ],
+        "sticky": true
       }
     },
     {

package/pages/epic.page.json

@@ -7,18 +7,50 @@
       "id": "nav",
       "props": {
         "variant": "bar",
-        "sticky": true,
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
-        ]
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
+        ],
+        "sticky": true
       }
     },
     {

package/pages/feature.page.json

@@ -7,18 +7,50 @@
       "id": "nav",
       "props": {
         "variant": "bar",
-        "sticky": true,
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
-        ]
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
+        ],
+        "sticky": true
       }
     },
     {

package/pages/home.page.json

@@ -31,7 +31,15 @@
           },
           {
             "label": "Tasks",
-            "page": "tasks"
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
           },
           {
             "label": "Cockpit",

package/pages/lineage.page.json

@@ -9,14 +9,46 @@
         "variant": "bar",
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
         ],
         "sticky": true
       }

package/pages/overview.page.json

@@ -7,18 +7,50 @@
       "id": "nav",
       "props": {
         "variant": "bar",
-        "sticky": true,
         "title": "Nano Workforce",
         "items": [
-          { "label": "Overview", "page": "overview" },
-          { "label": "Lineage", "page": "lineage" },
-          { "label": "Convergence", "page": "home" },
-          { "label": "Epics", "page": "epic" },
-          { "label": "Feature", "page": "feature" },
-          { "label": "Tasks", "page": "tasks" },
-          { "label": "Cockpit", "page": "cockpit" },
-          { "label": "Board", "page": "board" }
-        ]
+          {
+            "label": "Overview",
+            "page": "overview"
+          },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
+          {
+            "label": "Convergence",
+            "page": "home"
+          },
+          {
+            "label": "Epics",
+            "page": "epic"
+          },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
+          {
+            "label": "Tasks",
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
+          },
+          {
+            "label": "Cockpit",
+            "page": "cockpit"
+          },
+          {
+            "label": "Board",
+            "page": "board"
+          }
+        ],
+        "sticky": true
       }
     },
     {

package/pages/tasks.page.json

@@ -31,7 +31,15 @@
           },
           {
             "label": "Tasks",
-            "page": "tasks"
+            "page": "tasks",
+            "badge": {
+              "source": "app",
+              "table": "user_tasks",
+              "filter": [],
+              "tone": "danger",
+              "refreshMs": 5000,
+              "hideWhenZero": true
+            }
           },
           {
             "label": "Cockpit",
@@ -41,7 +49,8 @@
             "label": "Board",
             "page": "board"
           }
-        ]
+        ],
+        "sticky": true
       }
     },
     {

package/resources/processes/merge-loop.bpmn

@@ -96,12 +96,16 @@
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="MergeArmIn" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:output source="=null" target="status" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_deps</bpmn:incoming>
       <bpmn:incoming>f_m_answer</bpmn:incoming>
       <bpmn:incoming>f_ci_fixed</bpmn:incoming>
       <bpmn:incoming>f_reb_rebased</bpmn:incoming>
       <bpmn:incoming>f_m_evicted</bpmn:incoming>
+      <bpmn:incoming>f_m_escReenter</bpmn:incoming>
       <bpmn:outgoing>f_m_arm</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:intermediateCatchEvent id="wait-mergeable" name="Wait: mergeable">
@@ -187,6 +191,11 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="EscalationIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="EscalationOut" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=status" target="agentVerdict" />
+          <zeebe:input source="=&#34;This PR cannot be merged and needs a human decision. &#34; + (if mergeState = &#34;conflict&#34; then &#34;The automated rebase agent could not resolve the merge conflicts on this branch. Resolve them manually (or reply with guidance), then reply to retry.&#34; else if mergeState = &#34;ready&#34; then &#34;The merge attempt did not land (merge result: &#34; + mergeStatus + &#34;). Investigate why GitHub refused the merge, then reply to retry.&#34; else if agentVerdict = &#34;blocked&#34; then &#34;The automated CI-fix agent could not make the required checks green. Fix the failing checks on the branch (or reply with guidance), then reply to retry.&#34; else &#34;The automated CI-fix agent exceeded its time budget (SLA) before the required checks went green. Check its progress or intervene, then reply to retry.&#34;)" target="question" />
+          <zeebe:input source="=&#34;blocked&#34;" target="status" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_gBlocked</bpmn:incoming>
       <bpmn:incoming>f_ci_blocked</bpmn:incoming>
@@ -194,6 +203,11 @@
       <bpmn:incoming>f_ci_sla</bpmn:incoming>
       <bpmn:outgoing>f_m_escA</bpmn:outgoing>
     </bpmn:serviceTask>
+    <bpmn:exclusiveGateway id="gw-merge-escalated" name="escalation opened?" default="f_m_escReenter">
+      <bpmn:incoming>f_m_escA</bpmn:incoming>
+      <bpmn:outgoing>f_m_escWait</bpmn:outgoing>
+      <bpmn:outgoing>f_m_escReenter</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
     <bpmn:userTask id="wait-merge-answer" name="Answer escalation">
       <bpmn:extensionElements>
         <zeebe:formDefinition formId="pr-escalation" />
@@ -204,7 +218,7 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_escC</bpmn:incoming>
-      <bpmn:incoming>f_m_escA</bpmn:incoming>
+      <bpmn:incoming>f_m_escWait</bpmn:incoming>
       <bpmn:outgoing>f_m_answerRecord</bpmn:outgoing>
     </bpmn:userTask>
     <bpmn:serviceTask id="record-merge-answer" name="Record answer">
@@ -363,7 +377,11 @@
     <bpmn:sequenceFlow id="f_m_landed" sourceRef="wait-landed" targetRef="mark-merged" />
     <bpmn:sequenceFlow id="f_m_done" sourceRef="mark-merged" targetRef="MergeEnd" />
     <bpmn:sequenceFlow id="f_m_escC" sourceRef="merge-esc-conflict" targetRef="wait-merge-answer" />
-    <bpmn:sequenceFlow id="f_m_escA" sourceRef="merge-esc-attempt" targetRef="wait-merge-answer" />
+    <bpmn:sequenceFlow id="f_m_escA" sourceRef="merge-esc-attempt" targetRef="gw-merge-escalated" />
+    <bpmn:sequenceFlow id="f_m_escWait" sourceRef="gw-merge-escalated" targetRef="wait-merge-answer">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=escalated = true</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_m_escReenter" name="no escalation opened" sourceRef="gw-merge-escalated" targetRef="arm-merge" />
     <bpmn:sequenceFlow id="f_m_answerRecord" sourceRef="wait-merge-answer" targetRef="record-merge-answer" />
     <bpmn:sequenceFlow id="f_m_answer" sourceRef="record-merge-answer" targetRef="arm-merge" />
     <bpmn:sequenceFlow id="f_reb_sla" name="agent SLA elapsed" sourceRef="be_rebase_sla" targetRef="merge-esc-conflict" />
@@ -440,11 +458,17 @@
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-attempt" bpmnElement="merge-esc-attempt">
         <dc:Bounds x="1438" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-merge-escalated" bpmnElement="gw-merge-escalated" isMarkerVisible="true">
+        <dc:Bounds x="1663" y="1055" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1651" y="1022" width="74" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-merge-answer" bpmnElement="wait-merge-answer">
-        <dc:Bounds x="1638" y="1040" width="100" height="80" />
+        <dc:Bounds x="1838" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-merge-answer" bpmnElement="record-merge-answer">
-        <dc:Bounds x="1838" y="1040" width="100" height="80" />
+        <dc:Bounds x="2038" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-ci-fix" bpmnElement="gw-ci-fix" isMarkerVisible="true">
         <dc:Bounds x="863" y="1535" width="50" height="50" />
@@ -577,16 +601,25 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escC" bpmnElement="f_m_escC">
         <di:waypoint x="1338" y="1560" />
-        <di:waypoint x="1688" y="1560" />
-        <di:waypoint x="1688" y="1120" />
+        <di:waypoint x="1888" y="1560" />
+        <di:waypoint x="1888" y="1120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escReenter" bpmnElement="f_m_escReenter">
+        <di:waypoint x="1688" y="1105" />
+        <di:waypoint x="1688" y="1140" />
+        <di:waypoint x="402" y="1140" />
+        <di:waypoint x="402" y="160" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1008" y="1093" width="74" height="42" />
+        </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answerRecord" bpmnElement="f_m_answerRecord">
-        <di:waypoint x="1738" y="1080" />
-        <di:waypoint x="1838" y="1080" />
+        <di:waypoint x="1938" y="1080" />
+        <di:waypoint x="2038" y="1080" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answer" bpmnElement="f_m_answer">
-        <di:waypoint x="1888" y="1120" />
-        <di:waypoint x="1888" y="1140" />
+        <di:waypoint x="2088" y="1120" />
+        <di:waypoint x="2088" y="1140" />
         <di:waypoint x="402" y="1140" />
         <di:waypoint x="402" y="160" />
       </bpmndi:BPMNEdge>
@@ -626,13 +659,13 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_go" bpmnElement="f_ci_go">
         <di:waypoint x="888" y="1585" />
         <di:waypoint x="888" y="1605" />
-        <di:waypoint x="1958" y="1605" />
-        <di:waypoint x="1958" y="555" />
+        <di:waypoint x="2158" y="1605" />
+        <di:waypoint x="2158" y="555" />
         <di:waypoint x="1018" y="555" />
         <di:waypoint x="1018" y="580" />
         <di:waypoint x="1038" y="580" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1963" y="1066" width="49" height="28" />
+          <dc:Bounds x="2163" y="1066" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_blocked" bpmnElement="f_ci_blocked">
@@ -657,14 +690,14 @@
         <di:waypoint x="933" y="280" />
         <di:waypoint x="933" y="305" />
         <di:waypoint x="1558" y="305" />
-        <di:waypoint x="1558" y="1500" />
-        <di:waypoint x="1418" y="1500" />
+        <di:waypoint x="1558" y="1125" />
+        <di:waypoint x="1418" y="1125" />
         <di:waypoint x="1418" y="875" />
         <di:waypoint x="1018" y="875" />
         <di:waypoint x="1018" y="900" />
         <di:waypoint x="1038" y="900" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1464" y="1467" width="49" height="28" />
+          <dc:Bounds x="1563" y="701" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_blocked" bpmnElement="f_reb_blocked">
@@ -718,7 +751,11 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escA" bpmnElement="f_m_escA">
         <di:waypoint x="1538" y="1080" />
-        <di:waypoint x="1638" y="1080" />
+        <di:waypoint x="1663" y="1080" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escWait" bpmnElement="f_m_escWait">
+        <di:waypoint x="1713" y="1080" />
+        <di:waypoint x="1838" y="1080" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_sla" bpmnElement="f_reb_sla">
         <di:waypoint x="1088" y="978" />

package/scripts/sync-nav.test.ts

@@ -0,0 +1,87 @@
+// Drift guard for the single-source-of-truth nav (issue #306).
+//
+// `pages/_nav.json` is the ONE place the top-nav item list (and the Tasks
+// open-tasks count badge) is defined; `scripts/sync-nav.ts` materialises it into
+// every `pages/*.page.json`. This test fails if any page's nav node diverges from
+// the canonical source, so the eight copies can never silently drift apart again
+// (AGENTS.md: "Derivation over duplication: no drift surfaces"). Run `npm run
+// sync:nav` to reconcile.
+import { readdirSync, readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert } from "#test-assert";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+
+type Json = any;
+
+// Deterministic, key-sorted serialization: compare nav nodes by value, not by
+// authored key order or whitespace.
+function stable(value: Json): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function navNodeOf(page: Json): Json {
+  const nav = (page.nodes ?? []).find((n: Json) => n?.type === "nav");
+  assert(nav, "page has no nav node");
+  return nav;
+}
+
+function pageFiles(): string[] {
+  return readdirSync(`${ROOT}pages`)
+    .filter((n) => n.endsWith(".page.json"))
+    .sort();
+}
+
+test("issue #306: every page's nav node matches the canonical pages/_nav.json", () => {
+  const canon = JSON.parse(readFileSync(`${ROOT}pages/_nav.json`, "utf8"));
+  const want = stable(canon);
+  const files = pageFiles();
+  assert(files.length > 0, "no page files found");
+  for (const name of files) {
+    const page = JSON.parse(readFileSync(`${ROOT}pages/${name}`, "utf8"));
+    const nav = navNodeOf(page);
+    assert(
+      stable(nav) === want,
+      `${name}: nav node has drifted from pages/_nav.json — run \`npm run sync:nav\``,
+    );
+  }
+});
+
+test("issue #306: the Tasks nav item carries the live open-tasks count badge", () => {
+  const canon = JSON.parse(readFileSync(`${ROOT}pages/_nav.json`, "utf8"));
+  const items = canon?.props?.items ?? [];
+  const tasks = items.find((i: Json) => i?.page === "tasks");
+  assert(tasks, "canonical nav has no Tasks item");
+  const badge = tasks.badge;
+  assert(badge, "Tasks nav item must declare a live count badge");
+  // The badge counts the single open-escalation projection (user_tasks) with no
+  // filter, so count(user_tasks) is exactly "decisions awaiting a human"; danger
+  // tone, 5s refresh, hidden at zero to keep a quiet nav clean.
+  assert(badge.source === "app", "badge.source must be \"app\"");
+  assert(badge.table === "user_tasks", "badge.table must be \"user_tasks\"");
+  assert(Array.isArray(badge.filter) && badge.filter.length === 0, "badge.filter must be []");
+  assert(badge.tone === "danger", "badge.tone must be \"danger\"");
+  assert(badge.refreshMs === 5000, "badge.refreshMs must be 5000");
+  assert(badge.hideWhenZero === true, "badge.hideWhenZero must be true");
+});
+
+test("issue #306: the badge's user_tasks table is defined by the migrations", () => {
+  // The runtime whitelists the badge's datasource table against the live schema; a
+  // table the migrations never created would 400 the count fetch. Guard it here so
+  // a rename fails CI, mirroring scripts/pages-contract.test.ts.
+  let sql = "";
+  for (const e of readdirSync(`${ROOT}db/migrations`, { withFileTypes: true })) {
+    if (e.isFile() && e.name.endsWith(".sql")) {
+      sql += readFileSync(`${ROOT}db/migrations/${e.name}`, "utf8");
+    }
+  }
+  assert(
+    /CREATE\s+(?:TABLE|VIEW)\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?user_tasks["`]?/i.test(sql),
+    "badge table \"user_tasks\" must be created (TABLE or VIEW) by db/migrations/*.sql",
+  );
+});

package/scripts/sync-nav.ts

@@ -0,0 +1,126 @@
+// Single source of truth for the pages' top nav (issue #306).
+//
+// The `nav` node was copy-pasted verbatim into all `pages/*.page.json` files — a
+// classic drift surface (AGENTS.md: "Derivation over duplication"). Adding the
+// live open-tasks count badge to the Tasks item would have meant editing it in
+// eight places. Instead the nav node is authored ONCE in `pages/_nav.json` and
+// materialised into every page by this script; `scripts/sync-nav.test.ts` (run
+// under `npm test`) is the CI drift guard that fails if any page's nav node
+// diverges from the canonical source.
+//
+//   node --experimental-strip-types scripts/sync-nav.ts          # write pages
+//   node --experimental-strip-types scripts/sync-nav.ts --check  # verify (CI)
+//
+// Mirrors the repo's other derive/verify pairs (layout-bpmn --check,
+// check-contracts / reconcile-contracts).
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+const PAGES_DIR = `${ROOT}pages`;
+const CANON_PATH = `${PAGES_DIR}/_nav.json`;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+
+function isRecord(v: unknown): v is Record<string, JsonValue> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// Deterministic, key-sorted serialization so two nav nodes are compared by value,
+// not by authored key order or whitespace.
+function stable(value: JsonValue): string {
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`;
+  if (isRecord(value)) {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function readJson(path: string): JsonValue {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+// Locate the character span of the sole `nav` node object inside a page's raw
+// text, so it can be replaced in place without reformatting the rest of the file.
+function findNavSpan(text: string, file: string): { start: number; end: number } {
+  const marker = text.indexOf('"type": "nav"');
+  if (marker < 0) throw new Error(`${file}: no nav node found`);
+  const start = text.lastIndexOf("{", marker);
+  if (start < 0) throw new Error(`${file}: malformed nav node (no opening brace)`);
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return { start, end: i + 1 };
+    }
+  }
+  throw new Error(`${file}: unbalanced nav node braces`);
+}
+
+// The canonical node rendered at the indentation a page's `nodes[]` element sits
+// at (its opening brace is already indented by 4 spaces in the file, so only the
+// following lines are prefixed).
+function renderNavBlock(canon: JsonValue): string {
+  const lines = JSON.stringify(canon, null, 2).split("\n");
+  return lines.map((line, i) => (i === 0 ? line : `    ${line}`)).join("\n");
+}
+
+function pageFiles(): string[] {
+  return readdirSync(PAGES_DIR)
+    .filter((n) => n.endsWith(".page.json"))
+    .sort();
+}
+
+function main(): void {
+  const check = process.argv.includes("--check");
+  const canon = readJson(CANON_PATH);
+  const wantStable = stable(canon);
+  const block = renderNavBlock(canon);
+
+  const drifted: string[] = [];
+  let changed = 0;
+
+  for (const name of pageFiles()) {
+    const path = `${PAGES_DIR}/${name}`;
+    const text = readFileSync(path, "utf8");
+    const span = findNavSpan(text, name);
+    const currentText = text.slice(span.start, span.end);
+    const current: JsonValue = JSON.parse(currentText);
+    if (stable(current) === wantStable) continue;
+
+    if (check) {
+      drifted.push(name);
+      continue;
+    }
+    const next = `${text.slice(0, span.start)}${block}${text.slice(span.end)}`;
+    writeFileSync(path, next);
+    changed++;
+    process.stdout.write(`synced nav → pages/${name}\n`);
+  }
+
+  if (check) {
+    if (drifted.length > 0) {
+      process.stderr.write(
+        `nav drift in: ${drifted.join(", ")}\nFix with: npm run sync:nav (source of truth: pages/_nav.json)\n`,
+      );
+      process.exit(1);
+    }
+    process.stdout.write("nav is in sync across all pages\n");
+    return;
+  }
+  process.stdout.write(changed === 0 ? "nav already in sync\n" : `synced ${changed} page(s)\n`);
+}
+
+main();