@nanobpm/nano-workforce 0.72.1 → 0.73.1

package/AGENTS.md

@@ -117,6 +117,33 @@ GENERATED, never hand-edited.**
   that touch a shared process file into one; do **not** paper the collision over
   with a `dependsOn` edge added purely to serialise otherwise-parallel work.
 
+## 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
+every file: `resources/processes/*.bpmn`, `resources/forms/*.form`, and one prompt per
+task under `resources/prompts/*.md`.
+
+- **`resources/` is deploy-only.** Anything under it ships to the engine; anything
+  **outside** it never does. Docs therefore live under `docs/` (e.g.
+  `docs/agent-guide.md`) — put a `.md` in `resources/` only if you actually want it
+  deployed.
+- **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.
+- **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"/>`,
+  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.
+- **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.
+
 ## Engine capabilities (Zeebe parity — use them, don't work around them)
 
 The nanobpmn engine (`~/workspace/nanobpmn` `engine-core`, deployed via the nano
@@ -247,7 +274,7 @@ npm run lint                                          # biome check (incl. ban-`
 npm run typecheck                                     # tsc --noEmit (Node)
 npm run check                                         # urban check (manifest validation)
 npm run layout:check                                  # BPMN diagram freshness (no drift)
-npm run check:prompts                                 # agent-prompt template resolution
+npm run check:prompts                                 # agent-prompt linkedResource resolution
 npm run check:migrations                              # migration prefixes (no collisions)
 npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.73.1](https://github.com/nanobpm/nano-workforce/compare/v0.73.0...v0.73.1) (2026-08-16)
+
+
+### Bug Fixes
+
+* **merge:** treat a Depends-on ref that is not a PR as non-blocking ([#246](https://github.com/nanobpm/nano-workforce/issues/246)) ([c800f81](https://github.com/nanobpm/nano-workforce/commit/c800f81b02b3a9a787d79552f4e5eef9971e3edf)), closes [Magikcraft/nano-bpm#806](https://github.com/Magikcraft/nano-bpm/issues/806)
+
+# [0.73.0](https://github.com/nanobpm/nano-workforce/compare/v0.72.1...v0.73.0) (2026-08-15)
+
+
+### Features
+
+* **deploy:** resources/ deploy-by-convention; drop models; docs→docs/ (ADR 0062 step 3) ([#241](https://github.com/nanobpm/nano-workforce/issues/241)) ([9f7f85c](https://github.com/nanobpm/nano-workforce/commit/9f7f85c1231ce228c4468ac8f5222dd14d84022b)), closes [nanobpm/nano-ide#244](https://github.com/nanobpm/nano-ide/issues/244) [#244](https://github.com/nanobpm/nano-workforce/issues/244) [#239](https://github.com/nanobpm/nano-workforce/issues/239) [nanobpm/nano-ide#244](https://github.com/nanobpm/nano-ide/issues/244) [nanobpm/nano-workforce#239](https://github.com/nanobpm/nano-workforce/issues/239)
+
 ## [0.72.1](https://github.com/nanobpm/nano-workforce/compare/v0.72.0...v0.72.1) (2026-08-15)
 
 

package/README.md

@@ -156,8 +156,8 @@ capability):
 
 - `--command 'copilot -p - --allow-all-tools'` starts the Copilot CLI reading its
   prompt from **stdin** (`-p -`). The harness pipes the whole job JSON (prompt +
-  `job.variables`) to stdin; the relevant `prompts/*.md` resource (linked into the task
-  and fetched by the harness at activation) tells the agent how
+  `job.variables`) to stdin; the relevant `resources/prompts/*.md` resource (linked into
+  the task and fetched by the harness at activation) tells the agent how
   to read it and where to write its result.
 - **`--allow-all-tools` is essential** for an unattended worker — without it Copilot
   pauses for permission before each tool call and the job stalls.
@@ -351,14 +351,15 @@ 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" linkName="prompt"/>
+<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
 ```
 
-that the engine resolves to the latest deployed `prompts/*.md` at job
-activation (the prompts deploy as generic resources via a `models` glob in
-`nano.app.json`); per-instance context (e.g. a human's escalation answer) is appended
-by the harness. Because the binding is `latest`, redeploying one `prompts/*.md` updates
-the prompt for the next activation in a **running** epic — see SPEC §9.
+that the engine resolves to the latest deployed `resources/prompts/*.md` at job
+activation (the prompts deploy as generic resources under the `resources/` deploy-by-
+convention layout — `nano.app.json` declares no `models`; ADR 0062); per-instance context
+(e.g. a human's escalation answer) is appended
+by the harness. Because the binding is `latest`, redeploying one `resources/prompts/*.md`
+updates the prompt for the next activation in a **running** epic — see SPEC §9.
 
 ---
 

package/SPEC.md

@@ -65,11 +65,13 @@ nano-workforce/
   resources/
     processes/
       convergence-loop.bpmn   # the durable convergence process
+    prompts/
+      review-round.md         # agent instructions asset (deployed by the resources/ convention)
   db/
     migrations/
       001_init.sql            # sqlite schema
-  prompts/
-    review-round.md           # agent instructions asset (injected into job data)
+  docs/
+    agent-guide.md            # operator guide (docs live OUTSIDE resources/ — never deployed)
   components/
     review-round.json         # Zeebe element template for the senior:pr-review service task
   SPEC.md                     # this document
@@ -155,8 +157,8 @@ 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" linkName="prompt"/>`,
-which the engine resolves to the latest deployed `prompts/review-round.md` at job
+`<zeebe:linkedResource resourceId="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.
 
 **Output** (job result variables):
@@ -178,7 +180,7 @@ gives **each job its own `mkdtemp` run-dir + fresh clone**, runs the agent with
 **reaps that run-dir when the job ends**. So multiple agents on one host do **not**
 collide even in host mode — the isolation lives below the agent.
 
-Consequences the prompt (`prompts/review-round.md`) encodes:
+Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 - The agent works only inside its provided `cwd`; it must **not** re-clone or create
   a separate `git worktree`, and must not touch global/host state.
 - The agent **cleans up anything it creates outside the commit** before returning
@@ -300,25 +302,26 @@ when the engine data is purged, to keep app state and engine state consistent).
 
 ## 9. Prompt delivery — linked resources (`bindingType: latest`)
 
-Each agent task's base prompt lives **only** in its `prompts/*.md` side-car, deployed
-as a **generic resource** and **linked** — not baked — into the model (issue #169).
-`nano.app.json` lists `prompts/*.md` in a `models` deploy glob, so `@nanobpm/urban`
+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** (`prompts/review-round.md` → resource `review-round.md`). Each
-agent service task links it:
+the file's basename** (`resources/prompts/review-round.md` → resource `review-round.md`).
+Each agent service task links it:
 
 ```xml
 <zeebe:linkedResources>
-  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt" />
+  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
 </zeebe:linkedResources>
 ```
 
 At **job activation** the engine resolves the *latest deployed* key for that
 `resourceId` and hands the content to the harness in the `linkedResources` activation
 header; the harness fetches by key and uses it as the base prompt. Because the binding
-is `latest`, **redeploying a single `prompts/*.md` changes the prompt for the next task
-activation in a running epic** — no process redeploy, no in-flight epic restart. This
-is the live-prompt debugging loop: edit one Markdown file, `urban deploy` (or restart
+is `latest`, **redeploying a single `resources/prompts/*.md` changes the prompt for the
+next task activation in a running epic** — no process redeploy, no in-flight epic restart.
+This is the live-prompt debugging loop: edit one Markdown file, `urban deploy` (or restart
 the app, which deploys on boot), and the next agent job of that type picks it up.
 
 > **Latest-for-now, audited.** The engine currently keeps only the latest version per
@@ -332,7 +335,8 @@ the app, which deploys on boot), and the next agent job of that type picks it up
 > `resourceId` is dropped from the activation header (no incident) — the agent would
 > then run prompt-less. `scripts/check-agent-prompts.ts` (CI gate `check:prompts`)
 > guards against this: every `linkName="prompt"` link's `resourceId` must match a
-> prompt file the app actually deploys (a file in a `models` deploy glob), each linked
+> prompt file the app actually deploys (a file under the `resources/` convention walk, or
+> a manifest `models` override glob), each linked
 > prompt must be non-blank and teach the agent to emit a machine-readable result
 > (`$AGENT_RESULT_FILE` / `::nano:result::`), and no task may still carry the retired
 > baked `io.nanobpm.agentTask.task.prompt` header.
@@ -344,7 +348,8 @@ the linked base — the model owns any separator, and a null/empty append leaves
 untouched. Base prompts can't be composed in FEEL (they are quote-heavy, and XML
 attribute escaping would corrupt a FEEL string literal), so composition happens via
 this append seam rather than inline in FEEL. Requires an `@nanobpm/urban` deploy that
-emits generic-resource deployments for `prompts/*.md` and a harness that consumes
+deploys the `resources/` convention (generic-resource deployments for
+`resources/prompts/*.md`) and a harness that consumes
 `linkedResources` and fetches the resource by key.
 
 ## 10. Poller
@@ -554,7 +559,7 @@ the loop runs one parallel `implement` MI fan-out per wave:
   its prerequisites have **landed on the base branch** — not merely opened. This lets
   a blocking prerequisite (e.g. app scaffolding) fully converge and merge before the
   next wave builds on it. `gate_wave` lives in `db/migrations/007_wave_gate.sql`.
-- **Adopting a decomposed epic** (`prompts/plan.md` Step 0): when adopting existing
+- **Adopting a decomposed epic** (`resources/prompts/plan.md` Step 0): when adopting existing
   sub-issues, the planner honours an explicit `Depends-on: #N` / `Blocked by #N`
   directive in a sub-issue body, mapping each prerequisite `#M` to `issue-M` in the
   adopted task's `dependsOn` — so a human-declared blocking order survives adoption.

package/app/agentGuide.ts

@@ -1,7 +1,8 @@
 // The agent operator guide served by GET /app/api/agent (operationId `getAgentInstructions`).
 //
-// The guide itself is authored as plain markdown in `resources/agent-guide.md` (kept out of
-// `prompts/` so it is NOT treated as a deployable agent template) and read from the checkout at
+// The guide itself is authored as plain markdown in `docs/agent-guide.md` (kept OUT of
+// `resources/` so the deploy-by-convention walk does NOT treat it as a deployable model — docs
+// live under `docs/`, ADR 0062) and read from the checkout at
 // module load — same "run the .ts sources directly, inspect the working tree at runtime" approach
 // as version.ts. Two placeholders are substituted per request/deployment so the embedded examples
 // are copy-pasteable against THIS instance:
@@ -15,7 +16,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
-const GUIDE_PATH = join(REPO_ROOT, "resources", "agent-guide.md");
+const GUIDE_PATH = join(REPO_ROOT, "docs", "agent-guide.md");
 
 // Read the raw guide once, at module load. Frozen for the life of the process.
 const RAW_GUIDE: string = (() => {

package/app/feature.ts

@@ -248,7 +248,7 @@ export function deriveFeatureBlockedPatch(
 export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
 
 /** The deterministic task id for a single-issue run — the implementation agent branches
- * `feat/<task.id>` (see prompts/feature.md), so it MUST be derivable from the issue alone
+ * `feat/<task.id>` (see resources/prompts/feature.md), so it MUST be derivable from the issue alone
  * and stable across a resume. The PR is opened on the target repo, so the issue number
  * alone is unambiguous within it. */
 export function featureTaskId(issueNumber: number): string {
@@ -321,7 +321,7 @@ export async function startFeature(
       issueNumber: parsed.number,
       issueUrl: parsed.url,
       // The single slice the implementation agent builds. `task.prompt` is its primary instruction
-      // (prompts/feature.md); `task.id` fixes its deterministic branch `feat/<task.id>` across a
+      // (resources/prompts/feature.md); `task.id` fixes its deterministic branch `feat/<task.id>` across a
       // resume. Unlike an epic, there is no planner — the whole issue IS the slice.
       task: {
         id: featureTaskId(parsed.number),
@@ -337,7 +337,7 @@ export async function startFeature(
       converge,
       autoMerge,
       // A single-issue feature run OWNS its issue (the whole issue is the slice), so the agent may
-      // claim it with a "starting work" comment on a first run (prompts/feature.md). Epic slices
+      // claim it with a "starting work" comment on a first run (resources/prompts/feature.md). Epic slices
       // (plan-fanout) deliberately DO NOT set this — their `issue` is the shared parent epic, which
       // must never be claimed per-slice.
       claimIssue: true,

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles } from "./github.ts";
+import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles, isNotAPullRequestError } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -236,3 +236,26 @@ test("ensureBaseBranch: missing non-epic/* branch throws BaseBranchMustExistErro
   // A rejected non-epic/* base must never spawn a wrong-rooted branch.
   assertEquals(state.creates.length, 0);
 });
+
+// A `Depends-on:` ref that resolves to an issue (or a non-existent number) can never merge, so the
+// merge-poller's dependency gate must treat it as non-blocking rather than wedging forever — the
+// exact wedge behind Magikcraft/nano-bpm#806 declaring `Depends-on:` its epic tracking *issue*
+// #796. `isNotAPullRequestError` is the discriminator: it must fire for both transports' "not a PR"
+// signals and stay false for transient failures (which must keep the dependency blocking).
+test("isNotAPullRequestError: gh GraphQL 'not a PullRequest' → true", () => {
+  const err = new Error(
+    "GraphQL: Could not resolve to a PullRequest with the number of 796. (repository.pullRequest)",
+  );
+  assertEquals(isNotAPullRequestError(err), true);
+});
+
+test("isNotAPullRequestError: token-mode 404 → true", () => {
+  assertEquals(isNotAPullRequestError(new Error("github 404 Not Found")), true);
+});
+
+test("isNotAPullRequestError: transient failures stay blocking (false)", () => {
+  assertEquals(isNotAPullRequestError(new Error("github 502 Bad Gateway")), false);
+  assertEquals(isNotAPullRequestError(new Error("API rate limit exceeded")), false);
+  assertEquals(isNotAPullRequestError(new Error("fetch failed")), false);
+  assertEquals(isNotAPullRequestError(null), false);
+});

package/app/github.ts

@@ -496,6 +496,20 @@ function allCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** True when `err` is GitHub reporting that a ref which parsed as `owner/repo#N` is not a pull
+ * request — either it's an issue (issues and PRs share GitHub's number space, so an issue number
+ * is indistinguishable from a PR number by shape alone) or the number does not exist. Both
+ * transports surface here: `gh` mode throws the GraphQL message "Could not resolve to a
+ * PullRequest with the number of N", and token mode throws `github 404 …` from
+ * `GET /repos/{repo}/pulls/{N}`. A ref that is not a pull request can never merge, so a caller
+ * gating a merge queue on it (see `isDepMerged`) must treat it as non-blocking instead of wedging
+ * forever. Transient failures (rate-limit, 5xx, network) deliberately return `false` so the caller
+ * keeps waiting/retrying rather than silently clearing a real dependency. */
+export function isNotAPullRequestError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /could not resolve to a pullrequest/i.test(msg) || /\bgithub 404\b/i.test(msg);
+}
+
 export async function fetchPrState(
   repo: string,
   number: number | string,

package/app/plan.ts

@@ -31,8 +31,10 @@ export const ESCALATION_SLA_TIMEOUT = escalationSlaTimeout(
 const now = () => new Date().toISOString();
 
 // Agent prompts are no longer read by the host. The `senior:plan`, `senior:plan-review`, and
-// `senior:feature` prompts are generic resources (`prompts/plan.md` / `prompts/plan-review.md` /
-// `prompts/feature.md`, deployed via a `models` glob in nano.app.json) linked into each task as
+// `senior:feature` prompts are generic resources (`resources/prompts/plan.md` /
+// `resources/prompts/plan-review.md` / `resources/prompts/feature.md`, deployed under the
+// `resources/` deploy-by-convention layout — nano.app.json declares no `models`) linked into each
+// task as
 // `<zeebe:linkedResource … bindingType="latest" linkName="prompt"/>` and resolved by the engine at
 // job activation. Per-instance dynamic context (a plan's rejection findings, a task's brief) rides
 // `appendPrompt`, which the harness concatenates onto the linked base. The host only carries
@@ -244,7 +246,7 @@ export function normalizeBaseBranch(input: string | null | undefined): string {
 
 /** The per-instance brief appended to an implementer agent's prompt when the plan pins a base
  * branch. It is authoritative over the static "branch off the default branch" wording in
- * prompts/feature.md, so the agent branches off — and opens its PR against — the integration
+ * resources/prompts/feature.md, so the agent branches off — and opens its PR against — the integration
  * branch, and reads the epic's latest landed state there rather than the repo default branch. */
 export function renderBaseBranchBrief(baseBranch: string): string {
   return [

package/app/service.ts

@@ -20,6 +20,7 @@ import {
   fetchPrReviews,
   fetchPrState,
   hasPendingCopilotReviewer,
+  isNotAPullRequestError,
   type MergeMethod,
   type PrState,
   requestCopilotReview,
@@ -111,7 +112,8 @@ 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
-// (`prompts/review-round.md`, deployed via a `models` glob in nano.app.json) linked into the task
+// (`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"/>`
 // and resolved by the engine at job activation. The host only carries runtime PR identity + the
 // round counter now.
@@ -737,8 +739,23 @@ async function isDepMerged(data: DataLayer, depKey: string, token: string): Prom
   if (tracked && tracked.status === "merged") return true;
   const parsed = parsePr(depKey);
   if (!parsed) return true; // unparseable dep can't be checked on GitHub → treat as cleared so it never wedges the PR
-  const st = await fetchPrState(parsed.repo, parsed.number, token);
-  return st?.merged ?? false;
+  try {
+    const st = await fetchPrState(parsed.repo, parsed.number, token);
+    return st?.merged ?? false;
+  } catch (err) {
+    // A ref that GitHub cannot resolve to a *pull request* — it's an issue (issues and PRs share
+    // GitHub's number space) or the number doesn't exist — can never merge, so it cannot gate a
+    // merge queue. Treat it as cleared (non-blocking) rather than wedging the run at `wait-deps`
+    // forever, as happened when a PR body declared `Depends-on:` its epic tracking *issue*
+    // (Magikcraft/nano-bpm#806 → #796). Transient failures rethrow so the poller logs and retries.
+    if (isNotAPullRequestError(err)) {
+      console.warn(
+        `[poller] dep ${depKey} is not a mergeable pull request (issue or missing) — treating as non-blocking`,
+      );
+      return true;
+    }
+    throw err;
+  }
 }
 
 /** Flip a PR into the transient `merging` status and publish the correlating message, reverting

package/app/taskDelta.ts

@@ -1,6 +1,6 @@
 // nano-workforce — structured scope/impl-change report from implementers (D5, issue #55 / #49).
 //
-// The implementer result contract (prompts/feature.md) can carry an optional `delta`: a machine-
+// The implementer result contract (resources/prompts/feature.md) can carry an optional `delta`: a machine-
 // readable record of how a slice's implementation diverged from its brief — a changed contract, a
 // discovered constraint, files it now touches beyond its slice, or other tasks it affects. Before
 // this, that information lived only in PR prose: invisible to the planner, to sibling agents, and

package/{resources → docs}/agent-guide.md

@@ -307,20 +307,29 @@ both live in the source repo, not in the job payload.
   `retro.bpmn`. These are the source of truth for routing. To understand *why* an
   instance went where it did, read the gateway conditions (FEEL expressions on the
   sequence flows) for the element it is parked on (§5).
-- **Prompts (agent base instructions):** `prompts/*.md` — `review-round.md`,
-  `plan.md`, `feature.md`, `fix-ci.md`, `rebase.md`, `trial-merge.md`, etc. An
-  agent's base prompt is **not** a job variable: it is delivered as a
-  **linked resource** (likewise `plan.md`, …):
+- **Prompts (agent base instructions):** `resources/prompts/*.md` — `review-round.md`,
+  `plan.md`, `feature.md`, `fix-ci.md`, `rebase.md`, `trial-merge.md`, etc. They live
+  under `resources/` so they deploy by convention (ADR 0062 — the app declares no
+  `models`; every file under `resources/` is deployed, one `.md` per task under
+  `resources/prompts/`). An agent's base prompt is **not** a job variable and is **not**
+  a deploy-time `{{token}}` substitution (that templating is removed — there is no
+  back-compat): it is delivered as a **linked resource**, the blessed **and only**
+  prompt-modularity path:
 
   ```xml
-  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>
+  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
   ```
 
   that the engine
-  resolves to the latest deployed prompt at job activation. Because the binding is
-  `latest`, redeploying one of these files updates the prompt mid-epic without a process
-  redeploy. If an agent misbehaves systematically, the prompt is the first thing
-  to inspect/fix.
+  resolves to the latest deployed prompt at job activation, combined at runtime with the
+  per-task `appendPrompt` FEEL (the task-specific slice appended to this base). Because
+  the binding is `latest`, redeploying one of these files updates the prompt mid-epic
+  without a process redeploy. If an agent misbehaves systematically, the prompt is the
+  first thing to inspect/fix.
+
+  > **Value-injection caveat:** never bake a per-run value (a URL, a flag) into a prompt
+  > at deploy time — that path is gone. Pass it as a runtime job variable / `appendPrompt`
+  > FEEL instead; deploy-time string substitution is not available.
 - **Job contract:** `senior:pr-review` receives `{ prUrl, repo, prNumber, round,
   answer? }` and must return a flat result `{ status, summary, question? }` with
   `status ∈ { converged, addressed, waiting, needs_input, blocked }`. A round that
@@ -329,7 +338,7 @@ both live in the source repo, not in the job payload.
   rather than escalating.
 
 To validate a model/prompt change locally: `npm run layout:check` (BPMN diagram
-freshness), `npm run check:prompts` (every template resolves), `npm run check`
+freshness), `npm run check:prompts` (every prompt link resolves), `npm run check`
 (manifest), `npm run typecheck`, `npm run lint`, `npm test`.
 
 ---

package/e2e/agent-answerable.e2e.ts

@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { asEngineClient } from "./support/engine-client.ts";
 import {
   completeEscalationAsAgent,
   latestCompletion,
@@ -138,7 +139,7 @@ describe("agent-answerable escalations (U6 — same form, agent completer, attri
 
         // Complete AS AN AGENT through the host-side completer — the same typed `{resolution, answer}`
         // a human submits through the inbox, only the caller differs.
-        const r = await completeEscalationAsAgent(app.db, app.engine, {
+        const r = await completeEscalationAsAgent(app.db, asEngineClient(app.engine), {
           userTaskKey: task.userTaskKey,
           agentId: "senior:answer-bot",
           variables: { resolution: "answer", answer: "use v2" },

package/e2e/feature-run.e2e.ts

@@ -22,6 +22,7 @@ import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+import { asEngineClient } from "./support/engine-client.ts";
 import { pollFeatureBlocked, pollFeatureEscalations } from "../app/service.ts";
 
 const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -192,7 +193,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         // The poller fills in the completable user-task key (which no service task can know — the task
         // doesn't exist yet when record-feature runs) so the pages can drive an attributed acknowledge.
-        await pollFeatureBlocked(app.db, app.engine);
+        await pollFeatureBlocked(app.db, asEngineClient(app.engine));
         const denorm = await featureRow(app, featureKey);
         assert.ok(denorm.blocked_user_task_key, "the poller denormalised the completable blocked user-task key");
         assert.equal(denorm.status, "awaiting_operator", "the run stays awaiting_operator while parked");
@@ -214,7 +215,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         assert.equal(settled.blocked_user_task_key, null, "the completable-task pointer was cleared on ack");
 
         // A further poll pass is an idempotent no-op — a terminal run is not a candidate.
-        await pollFeatureBlocked(app.db, app.engine);
+        await pollFeatureBlocked(app.db, asEngineClient(app.engine));
         assert.equal((await featureRow(app, featureKey)).status, "blocked");
       },
     );
@@ -297,7 +298,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
 
         // The poller fills in the completable user-task key (which the service task can't know — the
         // task doesn't exist yet when it runs) so the UI can drive an attributed answer.
-        await pollFeatureEscalations(app.db, app.engine);
+        await pollFeatureEscalations(app.db, asEngineClient(app.engine));
         const escalated = await featureRow(app, featureKey);
         assert.ok(escalated.escalation_user_task_key, "the poller denormalised the completable user-task key");
         assert.equal(escalated.status, "escalated", "the run stays escalated while parked");
@@ -324,7 +325,7 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         assert.equal(settled.escalation_question, null, "the surfaced question was cleared once resolved");
 
         // A further poll pass is an idempotent no-op — a terminal run is not a candidate.
-        await pollFeatureEscalations(app.db, app.engine);
+        await pollFeatureEscalations(app.db, asEngineClient(app.engine));
         assert.equal((await featureRow(app, featureKey)).status, "opened");
       },
     );

package/e2e/support/engine-client.ts

@@ -0,0 +1,17 @@
+import type { EngineClient } from "@nanobpm/urban";
+import type { TestApp } from "@nanobpm/urban-testkit";
+
+// urban 0.49.0 (ADR 0062) added `EngineClient.getForm`, but the published
+// @nanobpm/urban-testkit (0.4.0) predates it, so its `WasmEngineClient` neither
+// declares nor implements the method. These hermetic e2e flows drive user-task
+// completion directly (`completeUserTask`) and never resolve a form schema, so we
+// complete the contract with a null-returning `getForm` — the documented "no
+// matching form" path — until a testkit release catches up with urban's engine
+// seam. Scoped to the test harness; production adapters implement `getForm` for real.
+export function asEngineClient(engine: TestApp["engine"]): EngineClient {
+  const e = engine as unknown as EngineClient & { getForm?: EngineClient["getForm"] };
+  if (typeof e.getForm !== "function") {
+    e.getForm = async () => null;
+  }
+  return e;
+}

package/nano.app.json

@@ -4,15 +4,6 @@
   "id": "nano-workforce",
   "name": "Nano Workforce",
   "codename": "nano-workforce",
-  "models": {
-    "processes": [
-      "resources/processes/*.bpmn",
-      "prompts/*.md"
-    ],
-    "forms": [
-      "resources/forms/*.form"
-    ]
-  },
   "data": {
     "default": "app",
     "sources": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.72.1",
+  "version": "0.73.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",
@@ -53,11 +53,11 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.48.0"
+    "@nanobpm/urban": "^0.50.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.4.0",
+    "@nanobpm/urban-testkit": "^0.5.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

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

@@ -1,8 +1,10 @@
 // Red/green coverage for the agent-prompt deploy guard (scripts/check-agent-prompts.ts).
 //
-// Since #169 each agent's base prompt is a linked *resource*: `prompts/<token>.md` is deployed as a
-// generic resource (a `models` deploy glob) and each service task links it with
-// `<zeebe:linkedResource resourceId="<token>.md" bindingType="latest" linkName="prompt"/>`. The
+// Since #169 each agent's base prompt is a linked *resource*: `resources/prompts/<token>.md` is
+// deployed as a generic resource and each service task links it with
+// `<zeebe:linkedResource resourceId="<token>.md" bindingType="latest" linkName="prompt"/>`. Under
+// ADR 0062 the app declares no `models`, so the guard discovers deployables by the `resources/`
+// convention walk; a manifest with explicit `models` globs is still honoured as an override. The
 // engine silently OMITS an unresolvable link — a typo'd or undeployed `resourceId` yields a blank
 // base prompt at runtime (the prompt-less-agent root of the empty "(no question provided)"
 // escalations, Magikcraft/nano-bpm #597/#599). These cases assert the guard fails on each broken
@@ -14,12 +16,16 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { checkAgentPrompts } from "./check-agent-prompts.ts";
 
-// A manifest that deploys BPMN and the prompt resources (the migrated shape: prompts are a deploy
-// glob, not a `templates` substitution source).
+// A manifest that deploys BPMN and the prompt resources via an explicit `models` override (the
+// escape hatch — exercised here to prove overrides still work alongside the ADR 0062 convention).
 const MANIFEST = JSON.stringify({
   models: { processes: ["resources/processes/*.bpmn", "prompts/*.md"] },
 });
 
+// The blessed ADR 0062 shape: NO `models` block, so deployables are discovered by the `resources/`
+// convention walk (prompts live at `resources/prompts/*.md`).
+const MANIFEST_CONVENTION = JSON.stringify({ id: "app" });
+
 function link(resourceId: string, bindingType = "latest"): string {
   return `<zeebe:linkedResource resourceId="${resourceId}" bindingType="${bindingType}" linkName="prompt" />`;
 }
@@ -51,6 +57,33 @@ test("passes when every prompt link resolves to a deployed, non-blank, result-em
   assertEquals(res.resolved, ["review-round"]);
 });
 
+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")),
+    "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",
+  });
+  const res = checkAgentPrompts(root);
+  assertEquals(res.errors, []);
+  assert(res.ok);
+  assertEquals(res.resolved, ["review-round"]);
+});
+
+test("convention walk flags a prompt link that has no deployed resource under resources/", () => {
+  const root = fixture({
+    "nano.app.json": MANIFEST_CONVENTION,
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    // The prompt lives OUTSIDE resources/ (old top-level prompts/ layout) so convention never
+    // deploys it — the link would resolve to nothing at runtime.
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("no deployed resource has that name")));
+});
+
 test("fails when a prompt link references a resourceId with no deployed file", () => {
   const root = fixture({
     "nano.app.json": MANIFEST,

package/scripts/check-agent-prompts.ts

@@ -1,9 +1,10 @@
 // check-agent-prompts — deploy-safety gate for the agent prompts, now authored as *linked
 // resources* (issue #169) rather than baked `{{token}}` templates.
 //
-// Since #169 each agent's base prompt is a generic resource: `prompts/<token>.md` is deployed as
-// an `application/octet-stream` resource (via a `models` deploy glob — see nano.app.json) and each
-// agent service task links it at job-activation time:
+// Since #169 each agent's base prompt is a generic resource: `resources/prompts/<token>.md` is
+// deployed as an `application/octet-stream` resource (under the ADR 0062 `resources/` deploy-by-
+// convention layout — see nano.app.json, which declares no `models`) and each agent service task
+// links it at job-activation time:
 //
 //   <zeebe:linkedResources>
 //     <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt" />
@@ -17,9 +18,9 @@
 // #597/#599). This guard turns that silent runtime failure into a hard build failure:
 //
 //   1. Every `linkName="prompt"` link's `resourceId` MUST match a prompt file that the app actually
-//      deploys (a file matched by a `models` deploy glob). This catches both a typo'd `resourceId`
-//      and a prompt that exists on disk but is not wired into a deploy glob (so never reaches the
-//      engine — the link would resolve to nothing).
+//      deploys (a file under the `resources/` convention walk, or a manifest `models` override
+//      glob). This catches both a typo'd `resourceId` and a prompt that exists on disk but is not
+//      wired into the deploy set (so never reaches the engine — the link would resolve to nothing).
 //   2. Each linked prompt file must be non-blank and must teach the agent to emit a machine-readable
 //      result (`$AGENT_RESULT_FILE`, or the `::nano:result::` stdout fallback) — a prose-only agent
 //      leaves `status` blank and the status gateway escalates/stalls (the fix-ci/rebase gap behind
@@ -68,6 +69,33 @@ 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`.
+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.
+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));
+      }
+    }
+  }
+  return out.sort();
+}
+
 interface PromptLink {
   resourceId: string;
   bindingType: string | null;
@@ -130,24 +158,33 @@ export function checkAgentPrompts(root: string): CheckResult {
   }
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
   const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as AppManifest;
-  const models = manifest.models ?? {};
-
-  // The resources the app actually DEPLOYS: every file matched by a deploy glob (processes,
-  // decisions, forms). Its deployed resource name is the file's basename — the same string a
-  // `linkedResource resourceId` must reference. Building this from the deploy globs (not from the
-  // prompts/ directory) is what catches a prompt that exists on disk but is wired only into a
-  // non-deploying key (e.g. the retired `models.templates`), so it never reaches the engine.
-  const deployGlobs = [
-    ...(models.processes ?? []),
-    ...(models.decisions ?? []),
-    ...(models.forms ?? []),
-  ];
-  // Keyed by basename (the deployed resource name a `resourceId` references). Two deploy globs
-  // matching files with the same basename would silently overwrite here, so a `resourceId` lookup
-  // could resolve to the wrong file (or mask a misconfiguration). Fail fast on the collision so the
-  // lookup stays unambiguous.
+
+  // 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`.
+  //   • `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).
+  const byConvention = manifest.models === undefined;
+  const deployedRels = byConvention
+    ? discoverResources(root)
+    : [
+        ...(manifest.models?.processes ?? []),
+        ...(manifest.models?.decisions ?? []),
+        ...(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
+  // `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 deployGlobs.flatMap((p) => expandGlob(root, p))) {
+  for (const rel of deployedRels) {
     const name = basename(rel);
     const prior = deployedFiles.get(name);
     if (prior != null && prior !== rel) {
@@ -162,11 +199,13 @@ export function checkAgentPrompts(root: string): CheckResult {
   }
 
   // The model files whose XML we scan for `<zeebe:linkedResource>` links.
-  const xmlModelFiles = deployGlobs
-    .flatMap((p) => expandGlob(root, p))
-    .filter((rel) => contentTypeFor(rel) === "text/xml");
+  const xmlModelFiles = deployedRels.filter((rel) => contentTypeFor(rel) === "text/xml");
   if (xmlModelFiles.length === 0) {
-    errors.push(`no BPMN/DMN model files matched ${JSON.stringify(deployGlobs)}`);
+    errors.push(
+      byConvention
+        ? `no BPMN/DMN model files found under ${RESOURCES_DIR}/ by convention`
+        : "no BPMN/DMN model files matched the manifest's models globs",
+    );
   }
 
   let linkCount = 0;
@@ -199,8 +238,9 @@ export function checkAgentPrompts(root: string): CheckResult {
       if (deployedRel == null) {
         errors.push(
           `${rel}: linkName="prompt" resourceId="${link.resourceId}" has no deployed resource — ` +
-            `no file matched by a models deploy glob has that name, so the engine would omit the ` +
-            `link and the agent would run prompt-less`,
+            `no deployed resource has that name — no file under the app's deploy set (the ` +
+            `resources/ convention walk, or the manifest's models globs) matches it, so the engine ` +
+            `would omit the link and the agent would run prompt-less`,
         );
         continue;
       }

package/workers/record-dependency/worker.ts

@@ -6,7 +6,7 @@
 // merged. The process re-enters its existing `wait-deps` catch, so no human has to babysit an
 // ordering constraint the machinery already knows how to satisfy.
 //
-// `dependsOn` is whatever the agent returned (see prompts/fix-ci.md, prompts/rebase.md): a
+// `dependsOn` is whatever the agent returned (see resources/prompts/fix-ci.md, resources/prompts/rebase.md): a
 // string of one or more `owner/repo#N` refs (or PR URLs) separated by commas/whitespace/newlines,
 // or an array of such tokens. We parse each robustly (reusing `parsePr`), drop self-references and
 // duplicates, and insert missing edges idempotently — a worker retry never double-inserts, and an

package/workers/record-feature/worker.ts

@@ -1,6 +1,6 @@
 // pr.record-feature — the single-issue `implement` block has finished (issue #172).
 //
-// The `senior:feature` agent reported one of `opened` / `blocked` / `skipped` (prompts/feature.md);
+// The `senior:feature` agent reported one of `opened` / `blocked` / `skipped` (resources/prompts/feature.md);
 // anything else — including a missing status, or an `escalated` status that fell through to abandon
 // (the human abandoned or the SLA fired) — is treated as `blocked`: we must not assume a PR was
 // opened. This worker:

package/workers/record-wave/worker.ts

@@ -47,7 +47,7 @@ interface Out extends Record<string, unknown> {
 const str = (v: unknown): string | undefined =>
   typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
 
-// The implementation agent reports one of these (see prompts/feature.md). Anything else —
+// The implementation agent reports one of these (see resources/prompts/feature.md). Anything else —
 // including a missing status — is treated as `blocked`: we must not assume a PR was opened,
 // and we only hand off / persist a PR when the status is `opened`.
 type WaveResultStatus = Extract<PlanTaskStatus, "opened" | "blocked" | "skipped">;