@nanobpm/nano-workforce 0.97.0 → 0.98.0

package/resources/prompts/plan.md

@@ -204,7 +204,14 @@ Write a JSON object of **result variables** to the file named by the
       "id": "short-stable-slug",
       "title": "One-line summary of the slice",
       "prompt": "Full, self-contained instructions for the implementing agent: what to build, where, acceptance criteria.",
-      "dependsOn": ["id-of-a-task-this-one-builds-on"]
+      "dependsOn": ["id-of-a-task-this-one-builds-on"],
+      "needs": [
+        {
+          "capabilityRef": "owner/repo#274",
+          "package": "@nanobpm/urban",
+          "verifyCommand": "optional shell probe, exit 0 == capability present"
+        }
+      ]
     }
   ]
 }
@@ -223,6 +230,27 @@ Rules:
   sub-issue tasks (Step 0), derive `dependsOn` from any `Depends-on: #N` /
   `Blocked by #N` directive in the sub-issue body (mapping each prerequisite `#M`
   to `issue-M`) — otherwise leave it empty.
+- `needs` — an optional array of **cross-repo capability edges**. Use it (and only
+  it) when a slice consumes an upstream capability that ships as a **published
+  package version from another repo** — e.g. it needs a new `@nanobpm/urban` API
+  that lands in some future release. This is different from `dependsOn` (which
+  orders slices *within this epic*): `needs` blocks the task until the capability
+  is **published**, then late-binds and pins the exact `package@version` into the
+  agent's prompt automatically. Each entry:
+  - `capabilityRef` — the **stable upstream handle**, never a version: the
+    issue/PR that introduces the capability, written as **`owner/repo#NNN`** (the
+    `owner/repo` names the repo whose GitHub Releases the gate polls for publish
+    provenance). Only set this when the sub-issue text explicitly references such
+    an upstream capability (a `Needs:`/`Consumes:` line, a "requires
+    `@pkg` ≥ the release carrying #NNN" note). **Do not** invent one, and **do not**
+    put a version here.
+  - `package` — the npm package whose releases carry that provenance (e.g.
+    `@nanobpm/urban`).
+  - `verifyCommand` — OPTIONAL. A shell probe (exit 0 == capability present) used
+    only as a gated empirical fallback when provenance is inconclusive; omit it for
+    the common deterministic case.
+  Omit `needs` entirely for the overwhelmingly common case of a slice with no
+  cross-repo capability dependency.
 - `prompt` — must stand alone: the implementing agent sees only this prompt plus
   the issue reference, not your reasoning.
 - Emit `{ "tasks": [] }` if the issue needs no code (and say why in a

package/workers/caps-prepare/worker.test.ts

@@ -0,0 +1,62 @@
+// Unit coverage for `pr.caps-prepare` (issue #289). The worker derives the per-task capability
+// barrier key + gate flag from the MI child's `task` (surfaced as `planKey`/`taskId`/`needs` job
+// vars), which the model hoists into the child scope so the following gateway + catch can read them.
+// The key MUST equal `capabilityTaskBarrierKey` (the host publishes `caps-resolved` on it), and the
+// flag MUST reflect whether any VALID need survives the tolerant parse.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { capabilityTaskBarrierKey } from "../../app/capabilityNeed.ts";
+import handler from "./worker.ts";
+
+test("caps-prepare: a task with needs yields the barrier key and hasNeeds=true", async () => {
+  const out = await handler(
+    {
+      variables: {
+        planKey: "owner/repo#7",
+        taskId: "gap-a",
+        needs: [{ capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban" }],
+      },
+    } as any,
+    {} as any,
+  );
+  assertEquals(out.capsGateKey, capabilityTaskBarrierKey("owner/repo#7", "gap-a"));
+  assertEquals(out.capsGateKey, "owner/repo#7:gap-a");
+  assertEquals(out.hasNeeds, true);
+});
+
+test("caps-prepare: a task with no needs yields hasNeeds=false (takes the no-needs shortcut)", async () => {
+  const out = await handler(
+    { variables: { planKey: "owner/repo#7", taskId: "gap-b", needs: [] } } as any,
+    {} as any,
+  );
+  assertEquals(out.capsGateKey, "owner/repo#7:gap-b");
+  assertEquals(out.hasNeeds, false);
+});
+
+test("caps-prepare: a missing/undefined needs list is treated as no needs", async () => {
+  const out = await handler(
+    { variables: { planKey: "owner/repo#7", taskId: "gap-c" } } as any,
+    {} as any,
+  );
+  assertEquals(out.hasNeeds, false);
+});
+
+test("caps-prepare: a malformed need is dropped — only a valid remainder gates the task", async () => {
+  const onlyBad = await handler(
+    { variables: { planKey: "p", taskId: "t", needs: [{ capabilityRef: "", package: "" }] } } as any,
+    {} as any,
+  );
+  assertEquals(onlyBad.hasNeeds, false, "a wholly-malformed need must not gate the fan-out");
+
+  const mixed = await handler(
+    {
+      variables: {
+        planKey: "p",
+        taskId: "t",
+        needs: [{ capabilityRef: "", package: "" }, { capabilityRef: "o/r#1", package: "pkg" }],
+      },
+    } as any,
+    {} as any,
+  );
+  assertEquals(mixed.hasNeeds, true, "a valid need still gates even alongside a malformed one");
+});

package/workers/caps-prepare/worker.ts

@@ -0,0 +1,38 @@
+// pr.caps-prepare — hoist a task's capability-barrier key + gate flag into the MI-child scope
+// (issue #289).
+//
+// The `implement` multi-instance subprocess must decide, PER child, whether the task declared
+// cross-repo capability `needs` and — if so — park at the `wait-caps-resolved` message barrier keyed
+// on a per-task correlation key. The MI `inputElement` `task` is only readable inside a *service
+// task's* ioMapping in the WASM testkit (an in-subprocess gateway / catch reads a stale/empty value
+// — see AGENTS.md "Testing flows against the testkit"). So this worker runs first in the subprocess,
+// derives the barrier key + the boolean from `task`, and RETURNS them; the model hoists both into the
+// child scope with `zeebe:output source="=var" target="var"` so the following gateway (`w_gw_needs`)
+// and the catch event's `correlationKey=capsGateKey` can read them reliably.
+//
+// PURE: no I/O. `capsGateKey` MUST equal `capabilityTaskBarrierKey(planKey, taskId)` — the same key
+// the host reconciler (`pollCapabilityGatesImpl`) publishes `caps-resolved` on — or the barrier never
+// releases.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { capabilityTaskBarrierKey, parseCapabilityNeeds } from "../../app/capabilityNeed.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+type In = WorkerInputs["pr.caps-prepare"];
+interface Out extends Record<string, unknown> {
+  capsGateKey: string;
+  hasNeeds: boolean;
+}
+
+const handler: AppJobHandler<In, Out> = async (job) => {
+  const planKey = String(job.variables.planKey ?? "");
+  const taskId = String(job.variables.taskId ?? "");
+  // Tolerant re-parse: `needs` arrives as the modelled CapabilityNeed[] but a malformed entry must
+  // never wedge the fan-out — drop it and gate only on the valid remainder (mirrors record-plan).
+  const needs = parseCapabilityNeeds(job.variables.needs);
+  return {
+    capsGateKey: capabilityTaskBarrierKey(planKey, taskId),
+    hasNeeds: needs.length > 0,
+  };
+};
+
+export default handler;

package/workers/record-plan/worker.test.ts

@@ -17,6 +17,7 @@ interface Row extends Record<string, unknown> {
 function fakeApp() {
   const planTasks: Row[] = [];
   const planTaskDeps: Row[] = [];
+  const planTaskNeeds: Row[] = [];
   const plans: Row[] = [{ plan_key: "owner/repo#137" }];
   let nextId = 1;
   const app = {
@@ -27,6 +28,8 @@ function fakeApp() {
           ? planTasks
           : name === "plan_task_deps"
           ? planTaskDeps
+          : name === "plan_task_needs"
+          ? planTaskNeeds
           : plans;
         return {
           get: (k: unknown) => Promise.resolve(store.find((r) => r[key] === k)),
@@ -53,7 +56,7 @@ function fakeApp() {
       },
     },
   } as any;
-  return { app, plans, planTasks };
+  return { app, plans, planTasks, planTaskNeeds };
 }
 
 test("record-plan initializes wave progress fields for a taskful plan", async () => {
@@ -88,3 +91,32 @@ test("record-plan leaves all three wave progress fields NULL for a taskless plan
   assertEquals(plans[0].current_wave, null);
   assertEquals(plans[0].wave_label, null);
 });
+
+test("record-plan persists per-task capability needs into plan_task_needs (issue #289)", async () => {
+  const { app, planTaskNeeds } = fakeApp();
+  await handler(
+    {
+      variables: {
+        planKey: "owner/repo#137",
+        tasks: [
+          {
+            id: "a",
+            prompt: "do A",
+            needs: [
+              { capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban", verifyCommand: "v.sh" },
+              { capabilityRef: "  ", package: "dropme" }, // malformed -> dropped by parse
+            ],
+          },
+          { id: "b", prompt: "do B", dependsOn: ["a"] }, // no needs
+        ],
+      },
+    } as any,
+    app,
+  );
+  assertEquals(planTaskNeeds.length, 1);
+  assertEquals(planTaskNeeds[0].plan_key, "owner/repo#137");
+  assertEquals(planTaskNeeds[0].task_id, "a");
+  assertEquals(planTaskNeeds[0].capability_ref, "nanobpm/nano-ide#274");
+  assertEquals(planTaskNeeds[0].package, "@nanobpm/urban");
+  assertEquals(planTaskNeeds[0].verify_command, "v.sh");
+});

package/workers/record-plan/worker.ts

@@ -16,8 +16,9 @@
 // warning; the ordering is lost but every task still runs. No `plan_task_deps` are recorded
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { type CapabilityNeed, parseCapabilityNeeds } from "../../app/capabilityNeed.ts";
 import { deriveEpicPhase } from "../../app/epicPhase.ts";
-import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
+import { plans, planTaskDeps, planTaskNeeds, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -30,6 +31,10 @@ interface NormalTask {
   title: string;
   prompt: string;
   dependsOn: string[];
+  // Cross-repo capability edges declared on the task (issue #289). Normalised + de-duped; empty when
+  // the task consumes no upstream capability. Levelized into `plan_task_needs`, NOT the wave DAG —
+  // a capability edge gates a task on an EXTERNAL publish, never on a sibling task's wave.
+  needs: CapabilityNeed[];
 }
 interface Out extends Record<string, unknown> {
   currentWave: number;
@@ -54,6 +59,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       // Dedupe: a planner-emitted `["a","a"]` would otherwise violate the
       // `plan_task_deps` PK on the second edge insert and fail the job.
       dependsOn: [...new Set(strList(t?.dependsOn))],
+      // Cross-repo capability edges (issue #289): tolerant-parse + de-dupe; a malformed need is
+      // dropped, never fatal. Independent of the wave DAG — these gate on an external publish.
+      needs: parseCapabilityNeeds(t?.needs),
     };
   });
 
@@ -90,6 +98,10 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // `plan_task_deps` is keyed on `plan_key`, so one delete clears the plan's whole edge set.
   const depTable = planTaskDeps(app.data);
   await depTable.delete(planKey);
+  // `plan_task_needs` is likewise keyed on `plan_key` — one delete clears the plan's capability
+  // edges before rewrite (issue #289). Independent of the DAG-degrade path below.
+  const needTable = planTaskNeeds(app.data);
+  await needTable.delete(planKey);
 
   for (let i = 0; i < tasks.length; i++) {
     const t = tasks[i];
@@ -113,6 +125,17 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
         });
       }
     }
+    // Capability edges persist regardless of `depsValid` — they gate on an external publish, not on
+    // the (possibly malformed) intra-epic DAG. The PK dedupes a task listing the same edge twice.
+    for (const need of t.needs) {
+      await needTable.insert({
+        plan_key: planKey,
+        task_id: t.id,
+        capability_ref: need.capabilityRef,
+        package: need.package,
+        verify_command: need.verifyCommand ?? null,
+      });
+    }
   }
 
   const patch: Record<string, unknown> = {

package/workers/select-wave/worker.test.ts

@@ -25,12 +25,18 @@ interface DepRow {
   depends_on_task_id: string;
 }
 
-function fakeApp(rows: Row[], deps: DepRow[], plans: Record<string, unknown>[] = []) {
+function fakeApp(rows: Row[], deps: DepRow[], plans: Record<string, unknown>[] = [], needs: Record<string, unknown>[] = []) {
   return {
     log: { error() {}, info() {}, warn() {} },
     data: {
       table(name: string, key: string) {
-        const store = name === "plan_tasks" ? rows : name === "plans" ? plans : deps;
+        const store = name === "plan_tasks"
+          ? rows
+          : name === "plans"
+          ? plans
+          : name === "plan_task_needs"
+          ? needs
+          : deps;
         return {
           find: (q: any) =>
             Promise.resolve(
@@ -196,3 +202,29 @@ test("select-wave still skips dependents behind failed or otherwise non-open dep
     });
   }
 });
+
+test("select-wave attaches each dispatched task's capability needs, [] when none (issue #289)", async () => {
+  const rows: Row[] = [
+    { id: 1, plan_key: "owner/repo#63", task_id: "a", title: "A", prompt: "do A", status: "pending", wave: 1 },
+    { id: 2, plan_key: "owner/repo#63", task_id: "b", title: "B", prompt: "do B", status: "pending", wave: 1 },
+  ];
+  const needs: Record<string, unknown>[] = [
+    {
+      plan_key: "owner/repo#63",
+      task_id: "a",
+      capability_ref: "nanobpm/nano-ide#274",
+      package: "@nanobpm/urban",
+      verify_command: "verify.sh",
+    },
+  ];
+  const out = await handler(
+    { variables: { planKey: "owner/repo#63", currentWave: 1 } } as any,
+    fakeApp(rows, [], [], needs),
+  );
+  const waveTasks = (out as { waveTasks: any[] }).waveTasks;
+  const byId = new Map(waveTasks.map((t) => [t.id, t]));
+  assertEquals(byId.get("a").needs, [
+    { capabilityRef: "nanobpm/nano-ide#274", package: "@nanobpm/urban", verifyCommand: "verify.sh" },
+  ]);
+  assertEquals(byId.get("b").needs, []);
+});

package/workers/select-wave/worker.ts

@@ -15,8 +15,9 @@
 // Emitting an empty `waveTasks` is fine: the MI activity over an empty collection completes
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
+import type { CapabilityNeed } from "../../app/capabilityNeed.ts";
 import { deriveEpicPhase } from "../../app/epicPhase.ts";
-import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
+import { plans, planTaskDeps, planTaskNeeds, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
 // Input typed off the model data envelope (`SelectWaveIn` in plan-fanout.bpmn) — ADR 0040.
@@ -25,6 +26,10 @@ interface WaveTaskOut {
   id: string;
   title: string;
   prompt: string;
+  // Cross-repo capability edges to gate this task on before its agent starts (issue #289). Empty
+  // for a task with no upstream capability dependency; carried through so the fan-out can gate on
+  // each need (readiness-gate) and late-bind the resolved `pkg@version` into the agent's prompt.
+  needs: CapabilityNeed[];
 }
 interface Out extends Record<string, unknown> {
   waveTasks: WaveTaskOut[];
@@ -96,6 +101,20 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     depsByTask.set(d.task_id, list);
   }
 
+  // Cross-repo capability edges (issue #289): loaded once and grouped per task so each dispatched
+  // wave task carries its `needs[]` for the fan-out to gate on. A task with no needs gets [].
+  const needRows = await planTaskNeeds(app.data).find({ plan_key: planKey });
+  const needsByTask = new Map<string, CapabilityNeed[]>();
+  for (const n of needRows) {
+    const list = needsByTask.get(n.task_id) ?? [];
+    list.push({
+      capabilityRef: n.capability_ref,
+      package: n.package,
+      ...(n.verify_command ? { verifyCommand: n.verify_command } : {}),
+    });
+    needsByTask.set(n.task_id, list);
+  }
+
   const waveTasks: WaveTaskOut[] = [];
   for (const r of rows) {
     if ((r.wave ?? 0) !== currentWave) continue;
@@ -116,7 +135,12 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       continue;
     }
     if (depIds.some((d) => statusById.get(d) === "waiting-for-lane")) continue;
-    waveTasks.push({ id: r.task_id, title: r.title ?? r.task_id, prompt: r.prompt ?? "" });
+    waveTasks.push({
+      id: r.task_id,
+      title: r.title ?? r.task_id,
+      prompt: r.prompt ?? "",
+      needs: needsByTask.get(r.task_id) ?? [],
+    });
   }
 
   return { waveTasks };