@nanobpm/nano-workforce 0.162.0 → 0.162.1

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,9 @@
+## [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/package.json

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

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" />

package/resources/processes/plan-fanout.bpmn

@@ -266,7 +266,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="plan.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/plan.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=(if (planFindings = null or planFindings = &#34;&#34;) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;A prior review REJECTED your last plan. Address every point, then re-emit the full plan:&#10;&#10;&#34; + planFindings)" target="appendPrompt" />
@@ -292,7 +292,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan-review" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="plan-review.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/plan-review.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toReviewPlan</bpmn:incoming>
@@ -419,7 +419,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 (blackboardBrief = null) then &#34;&#34; else blackboardBrief) + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (resolvedDepsBrief = null) then &#34;&#34; else resolvedDepsBrief) + (if (resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound producer capabilities (inter-epic gate).** This epic depends on capabilities another epic in the set just published. Build/install/clone against EXACTLY these published versions (the ones first carrying the awaited capability), never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;)))" target="appendPrompt" />
@@ -518,7 +518,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/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" });
   },