@nanobpm/nano-workforce 0.162.0 → 0.162.2

package/AGENTS.md

@@ -120,7 +120,8 @@ GENERATED, never hand-edited.**
 ## Deploy by convention: `resources/` (ADR 0062)
 
 **Deployables live under `resources/` and deploy by convention — `nano.app.json`
-declares no `models`.** urban walks `resources/` (shallow, one level deep) and deploys
+declares no `models`.** urban walks `resources/` **recursively (every file at any depth)** and
+deploys
 every file: `resources/processes/*.bpmn`, `resources/forms/*.form`, and one prompt per
 task under `resources/prompts/*.md`.
 
@@ -131,15 +132,20 @@ task under `resources/prompts/*.md`.
 - **No `models` block.** Rely on the convention; add a `models` override *only* for a
   genuinely non-standard layout (nwf doesn't need one). An explicit `models` is used
   verbatim and skips the convention walk.
-- **Basenames must be unique across the deploy set** — the deploy dedupe key is the
-  filename only, so two files sharing a basename in different dirs collide. `npm run
-  check:prompts` fails loudly on that.
+- **Prompt ids are `resources/`-relative; basenames must be unique only within a
+  `models` override.** A convention resource's deploy id (`resourceId`) is its path
+  **relative to `resources/`** — `resources/prompts/plan.md` → `prompts/plan.md` — so files
+  sharing a basename in different sub-dirs deploy as distinct resources. Only a `models`
+  override keys by basename (and so must avoid basename collisions). `npm run check:prompts`
+  validates each prompt link against the actual deployed id and fails loudly on a mismatch.
 - **Agent prompts: linkedResource is the blessed *and only* path.** Each agent service
   task links its base prompt with
-  `<zeebe:linkedResource resourceId="<token>.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
+  `<zeebe:linkedResource resourceId="prompts/<token>.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
   which the engine resolves to the latest deployed `resources/prompts/<token>.md` at job
   activation, combined at runtime with the per-task `appendPrompt` FEEL. `bindingType="latest"`
-  lets a prompt update land mid-epic without a process redeploy.
+  lets a prompt update land mid-epic without a process redeploy. **The id is the
+  `resources/`-relative path (`prompts/<token>.md`), NOT the bare basename** — a bare id
+  resolves to nothing and the engine silently omits the link, so the agent runs prompt-less.
 - **Deploy-time `{{token}}` templating is removed — no back-compat.** To inject a per-run
   value (URL, flag) into an agent, pass it as a runtime job variable / `appendPrompt`
   FEEL; never bake it into a model at deploy time.

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.162.2](https://github.com/nanobpm/nano-workforce/compare/v0.162.1...v0.162.2) (2026-08-30)
+
+### Bug Fixes
+
+* **plan-fanout:** terminate empty plans before the review gate ([#623](https://github.com/nanobpm/nano-workforce/issues/623)) ([#625](https://github.com/nanobpm/nano-workforce/issues/625)) ([02dca9f](https://github.com/nanobpm/nano-workforce/commit/02dca9f02f817bc0c178255a50ef95308318502b)), closes [Magikcraft/nano-bpm#1067](https://github.com/Magikcraft/nano-bpm/issues/1067)
+
+## [0.162.1](https://github.com/nanobpm/nano-workforce/compare/v0.162.0...v0.162.1) (2026-08-30)
+
+### Bug Fixes
+
+* **prompts:** reference prompts by resources-relative id so agents get their base prompt ([#628](https://github.com/nanobpm/nano-workforce/issues/628)) ([084e8f8](https://github.com/nanobpm/nano-workforce/commit/084e8f8f4ad842cc9f9e92c25b4ef80d0b0b66e1)), closes [#241](https://github.com/nanobpm/nano-workforce/issues/241)
+
 ## [0.162.0](https://github.com/nanobpm/nano-workforce/compare/v0.161.0...v0.162.0) (2026-08-29)
 
 ### Features

package/README.md

@@ -499,7 +499,7 @@ agent's base prompt is **not** in the job payload — it is delivered as a
 **linked resource** (likewise `plan.md`, `feature.md`, `fix-ci.md`, …):
 
 ```xml
-<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
+<zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
 ```
 
 that the engine resolves to the latest deployed `resources/prompts/*.md` at job

package/SPEC.md

@@ -164,7 +164,7 @@ Notes:
 
 The base instructions are **not** a job variable: they are delivered as a
 **linked resource** on the `senior:pr-review` task —
-`<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
+`<zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
 which the engine resolves to the latest deployed `resources/prompts/review-round.md` at job
 activation.
 
@@ -319,14 +319,16 @@ when the engine data is purged, to keep app state and engine state consistent).
 Each agent task's base prompt lives **only** in its `resources/prompts/*.md` side-car,
 deployed as a **generic resource** and **linked** — not baked — into the model (issue
 #169). Under the ADR 0062 `resources/` deploy-by-convention layout, `nano.app.json`
-declares **no `models`**, so `@nanobpm/urban` walks `resources/` (shallow, one level) and
-deploys each file as an `application/octet-stream` resource whose deployed **name is
-the file's basename** (`resources/prompts/review-round.md` → resource `review-round.md`).
-Each agent service task links it:
+declares **no `models`**, so `@nanobpm/urban` walks `resources/` **recursively (every file at any
+depth)** and deploys each file as an
+`application/octet-stream` resource whose deployed **id is its path relative to `resources/`**
+(`resources/prompts/review-round.md` → resource `prompts/review-round.md`). Each agent service
+task links it by that `resources/`-relative id (a bare basename resolves to nothing and the
+engine silently omits the link, leaving the agent prompt-less):
 
 ```xml
 <zeebe:linkedResources>
-  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+  <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
 </zeebe:linkedResources>
 ```
 

package/app/convergeGate.test.ts

@@ -394,7 +394,7 @@ test("classify-scope is an agent task servicing senior:scope-classify with a lin
   const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="classify-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
   assert(task, "classify-scope service task missing");
   assertStringIncludes(task[0], 'type="senior:scope-classify"');
-  assertStringIncludes(task[0], 'resourceId="scope-classify.md"');
+  assertStringIncludes(task[0], 'resourceId="prompts/scope-classify.md"');
   assertStringIncludes(task[0], 'linkName="prompt"');
   // After honouring (or ignoring) the human's scope answer, it clears the one-shot
   // scopeAnswer so a later round does not re-honour a stale decision.

package/app/service.ts

@@ -193,7 +193,7 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
 // The `senior:pr-review` agent prompt is no longer read by the host: it is a generic resource
 // (`resources/prompts/review-round.md`, deployed under the `resources/` deploy-by-convention layout
 // — nano.app.json declares no `models`) linked into the task
-// as `<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>`
+// as `<zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" linkName="prompt"/>`
 // and resolved by the engine at job activation. The host only carries runtime PR identity + the
 // round counter now.
 

package/docs/agent-guide.md

@@ -326,7 +326,7 @@ both live in the source repo, not in the job payload.
   prompt-modularity path:
 
   ```xml
-  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
+  <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
   ```
 
   that the engine

package/e2e/plan-fanout.e2e.ts

@@ -241,6 +241,43 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     );
   });
 
+  // Empty-plan short-circuit (issue #623 — regression for Merlin instance-46 / epic #1067). A
+  // planner that legitimately emits `{tasks:[]}` (meta/tracking epic, or all sub-issues closed) must
+  // reach a terminal state WITHOUT entering the adversarial plan-review loop — feeding an empty plan
+  // into review caused a plan↔plan-review livelock (it can neither be approved nor produce findings).
+  test("empty plan short-circuits to the taskless-done end, never entering plan-review (issue #623)", async () => {
+    let reviewCalls = 0;
+    await withApp(
+      {
+        "senior:plan": () => ({ tasks: [], note: "all sub-issues closed" }),
+        // If this ever fires, the short-circuit failed and the empty plan entered the review loop.
+        "senior:plan-review": () => {
+          reviewCalls += 1;
+          return { approved: false, findings: "" };
+        },
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, planKey }) => {
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-plan-empty->EndTasklessDone"),
+          `empty plan routed to the taskless-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-plan-empty->review-plan"),
+          "the has-tasks flow into plan-review was NOT taken",
+        );
+        assert.equal(reviewCalls, 0, "the plan-review agent must never run for an empty plan");
+
+        const plan = await app.db
+          .table<{ plan_key: string; status: string; outcome: string | null }>("plans", "plan_key")
+          .findOne({ plan_key: planKey });
+        assert.equal(plan?.status, "done", "the empty plan reached a terminal done state");
+        assert.equal(plan?.outcome, "all sub-issues closed", "the planner note was recorded as the outcome");
+      },
+    );
+  });
+
   // A two-task wave whose PRs both open triggers the D3 trial-merge gate; a suite-failed trial
   // parks on the trial-merge decision user task.
   const twoTaskPlan: Stub = () => ({

package/package.json

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

package/resources/processes/convergence-loop.bpmn

@@ -101,7 +101,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:pr-review" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrReviewRoundIn" />
@@ -321,7 +321,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:scope-classify" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="scope-classify.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/scope-classify.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrScopeClassifyIn" />

package/resources/processes/feature.bpmn

@@ -173,7 +173,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness (intake gate).** This feature was scheduled to wait until an upstream landed and published. Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />

package/resources/processes/implement-cell.bpmn

@@ -8,7 +8,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (is defined(baseBranchBrief) and baseBranchBrief != null) then baseBranchBrief else &#34;&#34;) + (if (is defined(blackboardBrief) and blackboardBrief != null) then blackboardBrief else &#34;&#34;) + (if (is defined(resolvedDepsBrief) and resolvedDepsBrief != null) then resolvedDepsBrief else &#34;&#34;) + (if (is defined(resolvedArtifacts) = false or resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness.** Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />

package/resources/processes/merge-cell.bpmn

@@ -8,7 +8,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:trial-merge" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=null" target="result" />

package/resources/processes/merge-loop.bpmn

@@ -293,7 +293,7 @@
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:fix-ci" />
           <zeebe:linkedResources>
-            <zeebe:linkedResource resourceId="fix-ci.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+            <zeebe:linkedResource resourceId="prompts/fix-ci.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>
           <zeebe:properties>
             <zeebe:property name="io.nanobpm.dataEnvelope.in" value="FixCiIn" />
@@ -450,7 +450,7 @@
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:rebase" />
           <zeebe:linkedResources>
-            <zeebe:linkedResource resourceId="rebase.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+            <zeebe:linkedResource resourceId="prompts/rebase.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>
           <zeebe:properties>
             <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RebaseIn" />