@nanobpm/nano-workforce 0.95.0 → 0.96.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.96.0](https://github.com/nanobpm/nano-workforce/compare/v0.95.0...v0.96.0) (2026-08-19)
+
+
+### Features
+
+* **escalations:** consolidate on native user_tasks — expand half (issue [#305](https://github.com/nanobpm/nano-workforce/issues/305)) ([#310](https://github.com/nanobpm/nano-workforce/issues/310)) ([fc5f4d4](https://github.com/nanobpm/nano-workforce/commit/fc5f4d4680223d0c7ca4572a7f883ce4257a26a5)), closes [nano-ide#333](https://github.com/nano-ide/issues/333)
+
 # [0.95.0](https://github.com/nanobpm/nano-workforce/compare/v0.94.0...v0.95.0) (2026-08-19)
 
 

package/app/agentic/vocab/crew-vocab.test.ts

@@ -29,11 +29,23 @@ test("it ships the crew's leaf tokens", () => {
     "implementation.reviewer",
     "ci.runner",
     "decide",
+    "senior",
   ]) {
     assert(tokens.includes(expected), `expected token ${expected}`);
   }
 });
 
+test("a representative senior worker resolves the rank-gated `senior` role (any cognition, weight>=4)", () => {
+  const implementation = crewResolver().resolve({ cognition: "implementation", weight: 5, family: "frontier" });
+  const planning = crewResolver().resolve({ cognition: "planning", weight: 4, family: "kimi" });
+  assert(implementation.tokens.includes("senior"), "an implementation senior serves `senior`");
+  assert(planning.tokens.includes("senior"), "a planning senior serves `senior` (rank, not cognition)");
+});
+
+test("a junior-weight worker does not resolve the `senior` rank role", () => {
+  assert(!crewResolver().resolve({ cognition: "implementation", weight: 2, family: "kimi" }).tokens.includes("senior"));
+});
+
 test("the spar role carries two distinct-family named seats", () => {
   const spar = crewResolver().roleForToken("planning.spar");
   assert(spar !== undefined);

package/app/agentic/vocab/crew-vocab.ts

@@ -17,6 +17,8 @@
 //   - implementation.senior / .junior / .reviewer — the build crew (reviewer is red/blue).
 //   - ci.runner       — the CI runner.
 //   - decide          — the bare decision role.
+//   - senior          — the bare seniority-rank role the deployed fleet agent job types (`senior:*`)
+//                       derive onto (issue #323); rank-gated (weight≥4), cognition-agnostic.
 //
 // Capability (cognition / weight / family / host) is an ENROLMENT attribute, never a routing token
 // (ADR 0056 invariant 3): each role's `requires` gate — not the token — decides WHO may fill it.
@@ -132,6 +134,22 @@ export const CREW_VOCAB: VocabDocument = deepFreeze({
         },
       },
     },
+    // The deployed fleet agent tasks are colon-form job types `senior:<task>` (`senior:feature`,
+    // `senior:retro`, `senior:rebase`, …). The `senior` prefix is a SENIORITY rank, not a cognition —
+    // one senior worker serves every `senior:*` task — so it maps to a single bare `senior` routing
+    // role gated purely on rank (weight≥4), cognition-agnostic. Any suitably-senior enrolled worker
+    // resolves it, so `app/agentic/vocab/job-types.ts`'s `senior:<task>` → `senior` derivation always
+    // lands on live supply (issue #323). Deliberately NOT one role per task: a per-task list here
+    // would duplicate the deployed models (issue #323 acceptance §3 — derivation over duplication).
+    senior: {
+      roles: {
+        senior: {
+          requires: ["weight>=4"],
+          weight: 5,
+          seats: 1,
+        },
+      },
+    },
   },
 });
 

package/app/agentic/vocab/demand-report.test.ts

@@ -13,6 +13,40 @@ const leaf = (taskType: string): TaskDefinitionLeaf => ({ taskType, process: "p"
 
 const plannerFrontier: RegisteredWorker = { instance: "w-front", capability: { cognition: "planning", weight: 5, family: "frontier" } };
 const plannerKimi: RegisteredWorker = { instance: "w-kimi", capability: { cognition: "planning", weight: 5, family: "kimi" } };
+const seniorImpl: RegisteredWorker = { instance: "w-senior", capability: { cognition: "implementation", weight: 5, family: "frontier" } };
+
+test("a deployed colon-form agent job type resolves to live supply from an enrolled senior worker (#323)", () => {
+  const report = buildRegistryReport({
+    taskDefinitions: [leaf("senior:feature"), leaf("senior:retro"), leaf("senior:rebase")],
+    workers: [seniorImpl],
+    now: NOW,
+  });
+  // All three colon-form agent job types bridge onto the bare `senior` routing role, which the senior
+  // worker supplies — so the board shows live supply, not a false RED, and nothing is nonAgentic.
+  assertEquals(report.missing, []);
+  assertEquals(report.nonAgentic, []);
+  const senior = report.networks.find((n) => n.network === "senior");
+  assert(senior !== undefined, "the `senior` network bucket is present");
+  const token = senior.tokens.find((t) => t.token === "senior");
+  assert(token !== undefined);
+  assertEquals(token.satisfied, true);
+  assertEquals(token.supply, 1);
+  assertEquals(token.instances, ["w-senior"]);
+});
+
+test("an agent job type with no enrolled senior worker is flagged missing, not nonAgentic (#323)", () => {
+  const report = buildRegistryReport({ taskDefinitions: [leaf("senior:feature")], workers: [], now: NOW });
+  assert(report.missing.includes("senior"), "senior demand with no supplier is missing (red)");
+  assertEquals(report.nonAgentic, []);
+  assertEquals(report.status, "red");
+});
+
+test("ordinary host jobs (pr.*) are not colon-form and pass through the bridge untouched", () => {
+  const report = buildRegistryReport({ taskDefinitions: [leaf("pr.finalize")], workers: [], now: NOW });
+  const pr = report.networks.find((n) => n.network === "pr");
+  assert(pr !== undefined, "pr.finalize stays a pr-network routing token");
+  assert(pr.tokens.some((t) => t.token === "pr.finalize"));
+});
 
 test("flags a demanded leaf with no supplier as missing (red) and a supplied leaf as satisfied", () => {
   const report = buildRegistryReport({

package/app/agentic/vocab/demand-report.ts

@@ -23,6 +23,7 @@ import type { RegistryReport as WireRegistryReport } from "../../../nano-generat
 import { envVar } from "../../version.ts";
 import { currentPresenceRegistry } from "../families/presence.family.ts";
 import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
+import { jobTypeToRoutingToken } from "./job-types.ts";
 
 /** The full registry report: the package's demand×supply model plus this app's version/provenance. */
 export interface RegistryReport extends DemandSupplyReport {
@@ -82,6 +83,25 @@ export interface BuildRegistryInput {
   readonly now?: Date;
 }
 
+/**
+ * Bridge the deployed fleet agent job types onto crew routing tokens so the demand×supply match can
+ * see live supply for them. The deployed AGENT tasks are colon-form job types (`senior:feature`,
+ * `senior:retro`, …) the crew vocab's dot-form SERVE tokens never string-match; each such leaf is
+ * rewritten to the routing token an enrolled worker resolves (`senior:<task>` → `senior`, the bare
+ * rank role) via {@link jobTypeToRoutingToken}. Ordinary host jobs (`pr.*`, already dot-form tokens)
+ * are not in colon form, so they pass through untouched. Element provenance is preserved. (Issue #323
+ * design choice 1b: an app-tier job-type → routing-token derivation, no parallel task-type list.)
+ */
+export function bridgeDemandLeaves(
+  taskDefinitions: readonly TaskDefinitionLeaf[] | undefined,
+): readonly TaskDefinitionLeaf[] | undefined {
+  if (taskDefinitions === undefined) return undefined;
+  return taskDefinitions.map((leaf) => {
+    const token = jobTypeToRoutingToken(leaf.taskType);
+    return token === undefined ? leaf : { ...leaf, taskType: token };
+  });
+}
+
 /**
  * Compute the registry report from demand + supply. Pure and deterministic (every list the package
  * emits is sorted), so it is safe to render straight into the board and diff frame-to-frame.
@@ -89,7 +109,7 @@ export interface BuildRegistryInput {
 export function buildRegistryReport(input: BuildRegistryInput): RegistryReport {
   const demandUnavailable = input.taskDefinitions === undefined;
   const report = computeDemandSupply({
-    taskDefinitions: input.taskDefinitions ?? [],
+    taskDefinitions: bridgeDemandLeaves(input.taskDefinitions) ?? [],
     workers: input.workers,
     resolver: crewResolver(),
   });

package/app/agentic/vocab/job-types.test.ts

@@ -0,0 +1,107 @@
+// Tests for the deployed-job-type ↔ crew-routing-token bridge (issue #323), including the
+// defect-class regression guard: every deployed prompt-bearing agent job type must resolve to a
+// SERVE token a representative enrolled senior worker can supply, so a newly-added agent task that is
+// not wired into the crew vocab fails CI instead of silently showing RED on the demand×supply board.
+import { readFileSync, readdirSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import type { Capability } from "@nanobpm/agentic/protocol";
+import { crewResolver } from "./crew-vocab.ts";
+import { jobTypeToRoutingToken, promptBearingTaskTypes } from "./job-types.ts";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
+
+/** Every prompt-bearing agent job type deployed across the BPMN models, distinct and sorted. */
+function deployedAgentJobTypes(): string[] {
+  const types = new Set<string>();
+  for (const file of readdirSync(PROCESSES_DIR)) {
+    if (!file.endsWith(".bpmn")) continue;
+    for (const type of promptBearingTaskTypes(readFileSync(join(PROCESSES_DIR, file), "utf8"))) {
+      types.add(type);
+    }
+  }
+  return [...types].sort();
+}
+
+// A representative enrolled senior worker — the staffing the board assumes when it reports supply.
+const seniorWorker: Capability = { cognition: "implementation", weight: 5, family: "frontier", host: "h1" };
+
+test("jobTypeToRoutingToken derives the bare rank token from a colon-form agent job type", () => {
+  assertEquals(jobTypeToRoutingToken("senior:feature"), "senior");
+  assertEquals(jobTypeToRoutingToken("senior:retro"), "senior");
+  assertEquals(jobTypeToRoutingToken("senior:plan-review"), "senior");
+  assertEquals(jobTypeToRoutingToken("senior:trial-merge"), "senior");
+});
+
+test("jobTypeToRoutingToken returns undefined for a non-agent (dot-form host) job type", () => {
+  assertEquals(jobTypeToRoutingToken("pr.finalize"), undefined);
+  assertEquals(jobTypeToRoutingToken("pr.record-plan"), undefined);
+});
+
+test("jobTypeToRoutingToken returns undefined for malformed / non-routing rank forms", () => {
+  assertEquals(jobTypeToRoutingToken(":feature"), undefined); // empty rank
+  assertEquals(jobTypeToRoutingToken("senior:"), undefined); // empty task
+  assertEquals(jobTypeToRoutingToken("senior"), undefined); // no colon at all
+  assertEquals(jobTypeToRoutingToken("Senior:feature"), undefined); // not a valid segment
+});
+
+test("jobTypeToRoutingToken rejects a dotted (multi-segment) rank prefix", () => {
+  // A dotted prefix is a multi-segment routing token, not a bare rank role — bridging it would
+  // distort demand/supply matching, so it must not derive.
+  assertEquals(jobTypeToRoutingToken("implementation.senior:feature"), undefined);
+  assertEquals(jobTypeToRoutingToken("planning.spar:plan"), undefined);
+});
+
+test("jobTypeToRoutingToken rejects a multi-colon job type (not `<rank>:<task>` form)", () => {
+  assertEquals(jobTypeToRoutingToken("senior:feature:extra"), undefined);
+});
+
+test("promptBearingTaskTypes picks a prompt-linked agent task and skips a plain host task", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="feature.md" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(promptBearingTaskTypes(xml), ["senior:feature"]);
+});
+
+test("a representative senior worker serves the bare `senior` routing role", () => {
+  assert(crewResolver().resolve(seniorWorker).tokens.includes("senior"), "senior worker serves `senior`");
+});
+
+test("retro and rebase specifically resolve to a supplying role", () => {
+  for (const jobType of ["senior:retro", "senior:rebase"]) {
+    const token = jobTypeToRoutingToken(jobType);
+    assert(token !== undefined, `${jobType} derives a routing token`);
+    assert(
+      crewResolver().resolve(seniorWorker).tokens.includes(token),
+      `${jobType} → ${token} is supplied by a senior worker`,
+    );
+  }
+});
+
+test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent job type resolves to a suppliable SERVE token", () => {
+  const jobTypes = deployedAgentJobTypes();
+  // Sanity: the models really do declare agent tasks (guard is not vacuously green).
+  assert(jobTypes.length > 0, "the deployed models declare prompt-bearing agent tasks");
+  const serve = new Set(crewResolver().resolve(seniorWorker).tokens);
+  for (const jobType of jobTypes) {
+    const token = jobTypeToRoutingToken(jobType);
+    assert(token !== undefined, `deployed agent job type ${jobType} is not in <rank>:<task> form`);
+    assert(
+      serve.has(token),
+      `deployed agent job type ${jobType} resolves to ${token}, which no enrolled senior worker supplies — wire it into the crew vocab`,
+    );
+  }
+});

package/app/agentic/vocab/job-types.ts

@@ -0,0 +1,70 @@
+// nano-workforce — the deployed-job-type ↔ crew-routing-token bridge (issue #323).
+//
+// The demand×supply board resolves live SUPPLY through the crew vocab, which emits dot-form routing
+// tokens (`implementation.senior`, `planning.spar`, …). But the deployed fleet agent tasks are
+// COLON-form job types (`senior:feature`, `senior:retro`, …) — the `<zeebe:taskDefinition type>` the
+// engine matches 1:1. The two never string-match, so an advertised agentic demand shows RED (no
+// supply) even when a suitably-capable senior worker is enrolled.
+//
+// This module is the app-tier bridge (design choice 1b): a pure DERIVATION from a deployed agent job
+// type to the crew routing token an enrolled worker resolves — NOT a hand-maintained parallel list of
+// task types (AGENTS.md: derivation over duplication; issue #323 acceptance §3). The colon in a fleet
+// job type is `<rank>:<task>`: the `rank` prefix is a seniority assertion the crew vocab models as a
+// bare rank role, and the `task` suffix is a job selector that does not change WHICH worker serves it
+// (one senior worker serves every `senior:*` task). So the derivation is: take the rank segment as the
+// bare routing token. `senior:retro` and `senior:feature` both derive to the `senior` role a
+// weight≥4 worker fills — no per-task role, no drift surface.
+//
+// The prompt-bearing scan identifies the deployed AGENT tasks (a `<zeebe:linkedResource … linkName=
+// "prompt">` on the service task) so a regression guard can enumerate the real demand corpus straight
+// from the models and assert every agent job type resolves to a suppliable token.
+
+import { isSegmentName } from "@nanobpm/agentic/protocol";
+
+/**
+ * Derive the crew routing token an enrolled worker resolves to for a deployed fleet agent job type,
+ * or `undefined` when the type is not an agent job type in `<rank>:<task>` colon form (e.g. an
+ * ordinary host job like `pr.finalize`, which is already a dot-form token and is left untouched).
+ *
+ * The rank segment is returned as the bare routing token: `senior:retro` → `senior`. The derivation
+ * is purely syntactic — it never enumerates task types — so a newly-added `senior:<task>` is covered
+ * automatically by the same rank role, while a new RANK (`principal:*`) that has no crew role surfaces
+ * as unsupplied and trips the regression guard.
+ */
+export function jobTypeToRoutingToken(jobType: string): string | undefined {
+  const colon = jobType.indexOf(":");
+  if (colon <= 0) return undefined;
+  const rank = jobType.slice(0, colon);
+  const task = jobType.slice(colon + 1);
+  if (task.length === 0) return undefined;
+  // The grammar is exactly `<rank>:<task>` with a SINGLE colon: a further colon (e.g.
+  // `senior:feature:extra`) is not this form, so reject it rather than silently deriving `senior`.
+  if (task.indexOf(":") !== -1) return undefined;
+  // The rank must be a bare SINGLE-SEGMENT routing token (a role like `senior`) — not a dotted,
+  // multi-segment token like `implementation.senior`, which would distort demand/supply matching.
+  // `isSegmentName` enforces the single-segment `[a-z][a-z0-9-]*` grammar (no dots, no seat marker).
+  return isSegmentName(rank) ? rank : undefined;
+}
+
+const SERVICE_TASK = /<(?:\w+:)?serviceTask\b[\s\S]*?<\/(?:\w+:)?serviceTask>/g;
+const TASK_DEFINITION_TYPE = /<(?:\w+:)?taskDefinition\b[^>]*\btype="([^"]*)"/;
+const PROMPT_LINK = /<(?:\w+:)?linkedResource\b[^>]*\blinkName="prompt"/;
+
+/**
+ * Scan one BPMN document for the job types of its PROMPT-BEARING service tasks — the deployed fleet
+ * AGENT tasks. A task is prompt-bearing iff it carries a `<zeebe:linkedResource … linkName="prompt">`
+ * (the base-prompt resource the engine delivers to the agent). Ordinary host jobs (no prompt link)
+ * are excluded. Returns the distinct task types in first-occurrence order.
+ */
+export function promptBearingTaskTypes(xml: string): string[] {
+  const seen = new Set<string>();
+  const types: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    if (!PROMPT_LINK.test(block)) continue;
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || type.length === 0 || seen.has(type)) continue;
+    seen.add(type);
+    types.push(type);
+  }
+  return types;
+}

package/app/feature.ts

@@ -180,6 +180,49 @@ export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryR
  * parks on when the agent escalates. `pollFeatureEscalations` reconciles it onto the read model. */
 export const FEATURE_ESCALATION_ELEMENT = "feature-escalation";
 
+/** One append-only audit row per `feature-escalation` ENTRY (issue #305). Mirrors the surviving
+ *  `plan_reviews` / `escalations` / `plan_trial_merges` audit logs: it is the canonical, poller-readable
+ *  source for a parked run's escalation `question`, so the denormalised `feature_runs.escalation_question`
+ *  column can be dropped in the later contract phase. `id` is an AUTOINCREMENT PK, so the newest row per
+ *  `feature_key` is the live question (`latestFeatureEscalationQuestion`). Never updated or deleted. */
+export interface FeatureEscalationRow {
+  id: number;
+  feature_key: string;
+  question: string | null;
+  created_at: string;
+  /** The engine `jobKey` that wrote the row — an idempotency guard so a `record-feature-escalation`
+   *  job retried after its insert (crash/timeout pre-completion) reuses its row instead of appending a
+   *  duplicate (mirrors `plan_reviews.job_key`). NULL only for migration-048 backfill rows. */
+  job_key: string | null;
+}
+
+/** Accessor for the append-only `feature_escalations` audit log (migration 048). Written by
+ *  `record-feature-escalation` (one row per escalation entry), read by `pollUserTasks` to enrich the
+ *  open `feature-escalation` task's question — the feature analogue of `plan_reviews` / `escalations`. */
+export const featureEscalations = (data: DataLayer) =>
+  data.table<FeatureEscalationRow>("feature_escalations", "id");
+
+/** Append one `feature_escalations` audit row capturing the agent's escalation `question` while it is
+ *  still in scope on the `record-feature-escalation` job. Append-only, so this is the canonical record
+ *  of what was asked — `pollUserTasks` reads the newest row per feature as the live question. The
+ *  `jobKey` is an idempotency guard: `record-feature-escalation` is at-least-once, so a retry after the
+ *  insert (crash/timeout pre-completion) re-runs with the SAME `jobKey` and must reuse the existing row
+ *  rather than append a duplicate (mirrors `record-plan-review` guarding `plan_reviews` by `job_key`). */
+export async function recordFeatureEscalation(
+  data: DataLayer,
+  entry: { featureKey: string; question: string | null; jobKey: string },
+): Promise<void> {
+  const table = featureEscalations(data);
+  // A prior attempt of THIS job already recorded its row — reuse it, don't append a duplicate.
+  if (await table.findOne({ feature_key: entry.featureKey, job_key: entry.jobKey })) return;
+  await table.insert({
+    feature_key: entry.featureKey,
+    question: entry.question,
+    created_at: new Date().toISOString(),
+    job_key: entry.jobKey,
+  });
+}
+
 /** The parked `feature-escalation` user task, as `pollFeatureEscalations` observes it via
  *  `openUserTasks` (the open-task-scoped query — issue #294): the completable user-task key the pages
  *  drive an attributed answer against. Scoping to `state:"CREATED"` is what keeps a looping run — which