@nanobpm/nano-workforce 0.162.0 → 0.162.2

package/resources/processes/retro.bpmn

@@ -44,7 +44,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:conformance" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="conformance.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/conformance.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=conformanceDigest" target="appendPrompt" />
@@ -92,7 +92,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:retro" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/retro.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=retroDigest" target="appendPrompt" />

package/scripts/check-agent-prompts.test.ts

@@ -60,7 +60,9 @@ test("passes when every prompt link resolves to a deployed, non-blank, result-em
 test("discovers prompts by the resources/ convention when the manifest declares no models", () => {
   const root = fixture({
     "nano.app.json": MANIFEST_CONVENTION,
-    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    // Under ADR 0062 deploy-by-convention the resource id is the path relative to resources/, so the
+    // link must reference `prompts/review-round.md` — the exact id urban deploys and the engine resolves.
+    "resources/processes/loop.bpmn": serviceTask(link("prompts/review-round.md")),
     "resources/prompts/review-round.md": "# Round\nDo the thing, then write `$AGENT_RESULT_FILE`.",
     // Docs live OUTSIDE resources/ and must never be swept into the deploy set.
     "docs/agent-guide.md": "# Guide\nnot a deployable",
@@ -71,6 +73,23 @@ test("discovers prompts by the resources/ convention when the manifest declares
   assertEquals(res.resolved, ["review-round"]);
 });
 
+test("convention: a bare basename resourceId (pre-ADR-0062) fails — the id must be resources/-relative", () => {
+  // Regression guard for the #241 migration miss: the prompt WAS moved under resources/prompts/, so it
+  // deploys as `prompts/review-round.md`, but the link still names the bare `review-round.md`. The
+  // engine resolves ids exactly, omits the unresolvable link, and the agent runs prompt-less. The gate
+  // MUST catch this, not silently pass as it did before.
+  const root = fixture({
+    "nano.app.json": MANIFEST_CONVENTION,
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    "resources/prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(
+    res.errors.some((e) => e.includes('resourceId="review-round.md"') && e.includes("no deployed resource")),
+  );
+});
+
 test("convention walk flags a prompt link that has no deployed resource under resources/", () => {
   const root = fixture({
     "nano.app.json": MANIFEST_CONVENTION,
@@ -236,7 +255,7 @@ test("fails when two deploy globs match files sharing a basename (ambiguous reso
   });
   const res = checkAgentPrompts(root);
   assert(!res.ok);
-  assert(res.errors.some((e) => e.includes("duplicate deployed resource name") && e.includes("review-round.md")));
+  assert(res.errors.some((e) => e.includes("duplicate deployed resource id") && e.includes("review-round.md")));
 });
 
 test("checks the real repo: all committed agent prompts link to deployed resources", () => {

package/scripts/check-agent-prompts.ts

@@ -29,7 +29,7 @@
 //      the deploy no longer substitutes `{{token}}` templates, so such a header would ship a literal
 //      `{{token}}` (or stale frozen text) as the prompt.
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, relative, sep } from "node:path";
 
 // The retired header that used to carry an agent's baked base prompt. Its continued presence is a
 // migration regression (the deploy no longer substitutes templates), so we flag it.
@@ -69,33 +69,49 @@ function expandGlob(root: string, pattern: string): string[] {
     .map((f) => join(dir, f));
 }
 
-// The convention directory (ADR 0062): deploy-only, walked one level deep when the manifest declares
-// no `models`. Must stay in lock-step with urban's `RESOURCES_DIR`/`deployModels`.
+// The convention directory (ADR 0062): deploy-only, walked recursively (every file at any depth)
+// when the manifest declares no `models`. Must stay in lock-step with urban's
+// `RESOURCES_DIR`/`deployModels`.
 const RESOURCES_DIR = "resources";
 
 // Mirror urban's deploy-by-convention walk (ADR 0062): when the manifest declares no `models`, the
-// deployables are every file directly under `resources/` PLUS every file one directory deeper
-// (`resources/<subdir>/*`) — shallow, one level only. Deeper nesting is intentionally NOT swept in:
-// the deploy dedupe key is the basename, so a deep walk would reintroduce cross-directory basename
-// collision risk. Paths come back repo-relative (with `/`), matching `expandGlob`'s output so the
-// two discovery modes are interchangeable downstream.
+// deployables are every file under `resources/` at ANY depth (urban's deploy.js walks it
+// recursively). A convention resource is keyed by its path relative to `resources/`, so files
+// sharing a basename in different sub-directories deploy as distinct resources — no collision — and
+// a deep walk is safe. Paths come back repo-relative (with `/`), matching `expandGlob`'s output so
+// the two discovery modes are interchangeable downstream.
 function discoverResources(root: string): string[] {
   const base = join(root, RESOURCES_DIR);
   if (!existsSync(base)) return [];
   const out: string[] = [];
-  for (const entry of readdirSync(base, { withFileTypes: true })) {
-    if (entry.isFile()) {
-      out.push(join(RESOURCES_DIR, entry.name));
-    } else if (entry.isDirectory()) {
-      const sub = join(base, entry.name);
-      for (const f of readdirSync(sub, { withFileTypes: true })) {
-        if (f.isFile()) out.push(join(RESOURCES_DIR, entry.name, f.name));
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, entry.name);
+      if (entry.isFile()) {
+        out.push(join(RESOURCES_DIR, relative(base, abs)));
+      } else if (entry.isDirectory()) {
+        walk(abs);
       }
     }
-  }
+  };
+  walk(base);
   return out.sort();
 }
 
+// The deployed `resourceId` a `linkName="prompt"` link must reference. Kept in lock-step with
+// urban's deploy.js: a CONVENTION resource (no `models` block) is keyed by its path relative to
+// `resources/` (POSIX) — `resources/prompts/plan.md` → `prompts/plan.md`; a `models` OVERRIDE
+// resource is keyed by its basename. This is the exact string the engine matches a linkedResource
+// `resourceId` against at activation, so the gate must reason about it (not the bare basename) —
+// otherwise a prompt moved into a sub-directory deploys as `prompts/plan.md` while a stale bare
+// `resourceId="plan.md"` link resolves to nothing and the agent runs prompt-less.
+function deployResourceId(rel: string, byConvention: boolean): string {
+  if (!byConvention) return basename(rel);
+  const posix = rel.split(sep).join("/");
+  const prefix = `${RESOURCES_DIR}/`;
+  return posix.startsWith(prefix) ? posix.slice(prefix.length) : basename(rel);
+}
+
 interface PromptLink {
   resourceId: string;
   bindingType: string | null;
@@ -162,14 +178,16 @@ export function checkAgentPrompts(root: string): CheckResult {
   // The resources the app actually DEPLOYS. Under ADR 0062 deploy-by-convention this is derived the
   // SAME way urban's deployModels derives it, so this gate reasons about exactly the file set that
   // ships to the engine:
-  //   • no `models` block → discover by convention: every file under `resources/` (shallow, one
-  //     level deep). This is nwf's blessed layout — prompts live at `resources/prompts/*.md`.
+  //   • no `models` block → discover by convention: every file under `resources/` at any depth
+  //     (recursive, mirroring urban). This is nwf's blessed layout — prompts live at
+  //     `resources/prompts/*.md`.
   //   • `models` globs present → explicit override, used verbatim (the escape hatch for a
   //     non-convention layout). A declared-but-empty `models` is still an override, NOT a fallback
   //     to the convention walk — mirror deployModels, which keys convention off the block's absence.
-  // Either way a deployed resource's name is the file's basename — the same string a
-  // `linkedResource resourceId` must reference — which is what catches a prompt that exists on disk
-  // but is not actually deployed (so it never reaches the engine and the link resolves to nothing).
+  // Either way a deployed resource's id is what a `linkedResource resourceId` must reference — for a
+  // convention resource its path relative to `resources/` (`prompts/plan.md`), for a `models`
+  // override its basename (see deployResourceId) — which is what catches a prompt that exists on
+  // disk but is not actually deployed under the id the link names (so the link resolves to nothing).
   const byConvention = manifest.models === undefined;
   const deployedRels = byConvention
     ? discoverResources(root)
@@ -179,19 +197,20 @@ export function checkAgentPrompts(root: string): CheckResult {
         ...(manifest.models?.forms ?? []),
       ].flatMap((p) => expandGlob(root, p));
 
-  // Keyed by basename (the deployed resource name a `resourceId` references). Two deployables sharing
-  // a basename would silently overwrite here — and clobber each other at the engine — so a
+  // Keyed by the DEPLOYED resourceId a link references: the path relative to `resources/` for a
+  // convention resource, or the basename for a `models` override (see deployResourceId). Two
+  // deployables that would deploy under the same id clobber each other at the engine, so a
   // `resourceId` lookup could resolve to the wrong file (or mask a misconfiguration). Fail fast on
   // the collision so the lookup stays unambiguous.
   const deployedFiles = new Map<string, string>();
   for (const rel of deployedRels) {
-    const name = basename(rel);
+    const name = deployResourceId(rel, byConvention);
     const prior = deployedFiles.get(name);
     if (prior != null && prior !== rel) {
       errors.push(
-        `duplicate deployed resource name "${name}": both "${prior}" and "${rel}" deploy under the ` +
-          `same basename, so a linkName="prompt" resourceId="${name}" would resolve ambiguously — ` +
-          `rename one so deployed resource names stay unique`,
+        `duplicate deployed resource id "${name}": both "${prior}" and "${rel}" deploy under the ` +
+          `same id, so a linkName="prompt" resourceId="${name}" would resolve ambiguously — ` +
+          `rename one so deployed resource ids stay unique`,
       );
       continue;
     }

package/test/derivation-parity/flows.ts

@@ -108,7 +108,7 @@ const retroFlow: DeclarativeFlow = defineFlow(
     w.task("gather", { jobType: "pr.retro-gather" });
     w.task("conformance", {
       jobType: "senior:conformance",
-      prompt: { resourceId: "conformance.md", bindingType: "latest", append: "=conformanceDigest" },
+      prompt: { resourceId: "prompts/conformance.md", bindingType: "latest", append: "=conformanceDigest" },
     });
     w.task("record-conformance", { jobType: "pr.conformance-record" });
     w.branch("hasDeviations = true", {
@@ -130,7 +130,7 @@ const retroFlow: DeclarativeFlow = defineFlow(
     });
     w.task("synthesize", {
       jobType: "senior:retro",
-      prompt: { resourceId: "retro.md", bindingType: "latest", append: "=retroDigest" },
+      prompt: { resourceId: "prompts/retro.md", bindingType: "latest", append: "=retroDigest" },
     });
     w.task("record", { jobType: "pr.retro-record" });
   },

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

@@ -61,7 +61,7 @@ function fakeApp() {
 
 test("record-plan dispatches a taskful plan and levelizes its tasks (wave progress is now VIEW-derived)", async () => {
   const { app, plans } = fakeApp();
-  await handler(
+  const out = await handler(
     {
       variables: {
         planKey: "owner/repo#137",
@@ -74,6 +74,8 @@ test("record-plan dispatches a taskful plan and levelizes its tasks (wave progre
     app,
   );
   assertEquals(plans[0].status, "dispatched");
+  // taskCount drives the plan-fanout gateway (`gw-plan-empty`): non-zero ⇒ proceed to review (#623).
+  assertEquals((out as any).taskCount, 2);
   // Wave progress (wave_count/current_wave/wave_label) was retired as a stored projection (epic
   // #412) — it is derived from `plan_tasks` by the plan_wave_label/plan_read_model VIEWs — so
   // record-plan no longer writes it onto the plans row.
@@ -84,11 +86,15 @@ test("record-plan dispatches a taskful plan and levelizes its tasks (wave progre
 
 test("record-plan marks a taskless plan done (no wave-progress columns written)", async () => {
   const { app, plans } = fakeApp();
-  await handler(
+  const out = await handler(
     { variables: { planKey: "owner/repo#137", tasks: [], note: "planner emitted no tasks" } } as any,
     app,
   );
   assertEquals(plans[0].status, "done");
+  // taskCount 0 routes the plan-fanout gateway (`gw-plan-empty`) to the terminal taskless-done arm,
+  // short-circuiting the adversarial plan-review loop that would otherwise livelock (issue #623).
+  assertEquals((out as any).taskCount, 0);
+  assertEquals(plans[0].outcome, "planner emitted no tasks");
   assertEquals(plans[0].wave_count, undefined);
   assertEquals(plans[0].current_wave, undefined);
   assertEquals(plans[0].wave_label, undefined);

package/workers/record-plan/worker.ts

@@ -38,6 +38,11 @@ interface NormalTask {
 interface Out extends Record<string, unknown> {
   currentWave: number;
   waveCount: number;
+  // Task count of the recorded plan. The plan-fanout gateway (`gw-plan-empty`) reads this to
+  // SHORT-CIRCUIT an intentionally-empty plan (`{tasks:[]}`) to a terminal taskless-done arm
+  // BEFORE the adversarial plan-review gate (issue #623). Feeding an empty plan into review
+  // caused a plan↔plan-review livelock — it can neither be approved nor produce findings.
+  taskCount: number;
 }
 
 const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
@@ -149,8 +154,9 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
   await plans(app.data).update(planKey, patch);
 
-  // Kick off the wave loop at wave 0.
-  return { currentWave: 0, waveCount };
+  // Kick off the wave loop at wave 0. `taskCount` lets the BPMN gateway terminate an empty plan
+  // before the review loop (issue #623).
+  return { currentWave: 0, waveCount, taskCount: tasks.length };
 };
 
 export default handler;

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

@@ -65,6 +65,24 @@ test("unapproved, non-final round revises (planApproved=false, no escalation)",
   assertEquals((out as any).planFindings, "fix X");
 });
 
+test("unapproved with EMPTY findings escalates immediately — contentless disapproval is malformed (issue #623)", async () => {
+  // First round of a 3-round cap: NOT the final round, so the old behaviour would revise and loop.
+  // A disapproval with no findings is malformed (findings are required per plan-review.md) and
+  // gives the planner nothing to act on — escalate to a human instead of spinning on re-plan.
+  const app = fakeApp(priorRounds("o/r#2b", 0));
+  const out = await call(app, { planKey: "o/r#2b", approved: false, findings: "" });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, true);
+  assertEquals((out as any).planReviewRound, 0);
+});
+
+test("unapproved with MISSING findings escalates immediately (issue #623)", async () => {
+  const app = fakeApp(priorRounds("o/r#2c", 0));
+  const out = await call(app, { planKey: "o/r#2c", approved: false });
+  assertEquals((out as any).planApproved, false);
+  assertEquals((out as any).planEscalated, true);
+});
+
 test("unapproved FINAL round escalates instead of throwing or proceeding", async () => {
   // Seed cap-1 prior rounds so this job is the last permitted round; unapproved ⇒ human escalation.
   const app = fakeApp(priorRounds("o/r#3", MAX_PLAN_REVIEW_ROUNDS - 1));

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

@@ -17,6 +17,11 @@
 // unhandled incident. Proceeding used to dispatch an un-vetted plan and — when the plan was empty —
 // let the whole epic complete GREEN having done nothing. A missing/ambiguous `approved` is treated
 // as NOT approved (revise until the cap, then escalate).
+//
+// A disapproval with EMPTY findings is malformed (issue #623): plan-review.md REQUIRES findings when
+// `approved` is false. Re-planning against a contentless disapproval gives the planner nothing to
+// act on, so it re-emits the same plan and the loop spins (the plan↔plan-review livelock). This
+// worker escalates such a verdict to a human immediately instead of burning re-plan rounds.
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import {
@@ -109,9 +114,28 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     };
   }
 
-  // Not approved this round. Escalate once the per-epoch round cap is reached (issue #86):
-  // previously the fan-out PROCEEDED regardless, dispatching an un-vetted plan. The round is
-  // 0-based, so `round + 1 >= cap` is the last permitted round.
+  // Not approved this round. A disapproval with EMPTY findings is malformed (issue #623): per
+  // resources/prompts/plan-review.md, findings are REQUIRED when `approved` is false. Re-planning
+  // against a contentless disapproval gives the planner nothing to act on, so it re-emits the same
+  // plan and the loop spins (plan↔plan-review livelock, esp. for an empty plan). Escalate to a human
+  // immediately rather than burning re-plan rounds on a malformed verdict.
+  if (roundFindings === "") {
+    app.log.warn(`record-plan-review: ${planKey} not approved with EMPTY findings — malformed, escalating`, {
+      epoch: recordedEpoch,
+      round,
+    });
+    return {
+      planApproved: false,
+      planEscalated: true,
+      planFindings: roundFindings,
+      planReviewEpoch: recordedEpoch,
+      planReviewRound: round,
+    };
+  }
+
+  // Escalate once the per-epoch round cap is reached (issue #86): previously the fan-out PROCEEDED
+  // regardless, dispatching an un-vetted plan. The round is 0-based, so `round + 1 >= cap` is the
+  // last permitted round.
   if (round + 1 >= MAX_PLAN_REVIEW_ROUNDS) {
     app.log.warn(`record-plan-review: ${planKey} not approved after ${MAX_PLAN_REVIEW_ROUNDS} round(s)`, {
       epoch: recordedEpoch,