@nanobpm/nano-workforce 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.61.0](https://github.com/nanobpm/nano-workforce/compare/v0.60.0...v0.61.0) (2026-08-13)
+
+
+### Features
+
+* prompts as linked resources (bindingType: latest) — live mid-epic updates ([#198](https://github.com/nanobpm/nano-workforce/issues/198)) ([#203](https://github.com/nanobpm/nano-workforce/issues/203)) ([24a83e0](https://github.com/nanobpm/nano-workforce/commit/24a83e01f7e7b4f6e5296ce90c63fa44105aa058)), closes [#169](https://github.com/nanobpm/nano-workforce/issues/169) [#169](https://github.com/nanobpm/nano-workforce/issues/169)
+
 # [0.60.0](https://github.com/nanobpm/nano-workforce/compare/v0.59.0...v0.60.0) (2026-08-13)
 
 

package/README.md

@@ -156,7 +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` template tells the agent how
+  `job.variables`) to stdin; the relevant `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.
@@ -280,10 +281,18 @@ The `senior:*` tasks are serviced by **external** workers — they are **not** i
 manifest `workers[]`. Point a `c8ctl nano work` daemon (or any Zeebe-style worker) at
 the task types; each job carries its variables (e.g. `senior:pr-review` gets `{prUrl,
 repo, prNumber, round, answer?}` and returns `{status, summary, question?}`). An
-agent's base prompt is **not** in the job payload — it is delivered via a model
-**template header** (`{{review-round}}`, `{{plan}}`, `{{feature}}`, `{{fix-ci}}`, …)
-substituted at deploy time from `prompts/*.md` (`models.templates` in `nano.app.json`);
-per-instance context (e.g. a human's escalation answer) is appended by the harness.
+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"/>
+```
+
+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.
 
 ---
 

package/SPEC.md

@@ -86,11 +86,11 @@ known at submit time, carried as a process variable and stored on the DB row.
       │
       ▼
 [Register PR]  (script/handler)   → insert DB row; round = 1
-      │                              (base prompt delivered via the {{review-round}} model
-      │                               template header, not a process variable)
+      │                              (base prompt delivered via the review-round.md
+      │                               linked resource, not a process variable)
       ▼
 ┌──▶ [Review round]  (service task, taskType: senior:pr-review)
-│         in : prUrl, repo, prNumber, round, answer?   (prompt via task header)
+│         in : prUrl, repo, prNumber, round, answer?   (prompt via linked resource)
 │         out: status, summary, question?
 │         │
 │         ▼
@@ -153,10 +153,11 @@ Notes:
 | `round` | int | 1-based round counter |
 | `answer` | string? | present only when resuming from an escalation |
 
-The base instructions are **not** a job variable: they are delivered as a model
-**template header** on the `senior:pr-review` task — header key
-`io.nanobpm.agentTask.task.prompt` with value `{{review-round}}`, substituted with
-`prompts/review-round.md` at deploy time.
+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
+activation.
 
 **Output** (job result variables):
 | var | type | notes |
@@ -292,24 +293,54 @@ tracked row to `abandoned` via the `instanceTracking` `onTerminated.set` patch.
 `deno task purge` wipes and re-migrates the app db (used
 when the engine data is purged, to keep app state and engine state consistent).
 
-## 9. Prompt delivery — model-authored template headers
+## 9. Prompt delivery — linked resources (`bindingType: latest`)
 
-Each agent task's base prompt lives **only** in its `prompts/*.md` side-car and is
-authored **into the model** as a deploy-time `{{stem}}` template. `nano.app.json`
-declares `models.templates: ["prompts/*.md"]`, and each agent service task carries a
-`io.nanobpm.agentTask.task.prompt = {{stem}}` task header (`{{review-round}}`,
-`{{plan}}`, `{{plan-review}}`, `{{feature}}`, `{{fix-ci}}`). At deploy the template
-substitutes the file content into the header, so the host no longer reads prompt
-assets or carries them as process variables.
+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`
+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:
 
-Per-instance dynamic context rides **`appendPrompt`**: an ioMapping sets a job-local
-`appendPrompt` string (a plan's rejection findings, a feature task's brief, the
-failing-check list) which the agent harness concatenates **verbatim** onto the header
-base — the model owns any separator, and a null/empty append leaves the base
+```xml
+<zeebe:linkedResources>
+  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" 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
+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
+> `resourceId` (`deployment`/`versionTag` bindings degrade to latest — no pinning yet).
+> We accept `latest` (ideal for active debugging) and rely on the harness recording the
+> resolved `resourceKey` per job for "which prompt did this run use?". True
+> `deployment`-binding pinning for reproducible production epics is an engine follow-up,
+> not part of #169.
+
+> **The engine silently omits an unresolvable link.** A typo'd or undeployed
+> `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 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.
+
+Per-instance dynamic context still rides **`appendPrompt`** (unchanged): an ioMapping
+sets a job-local `appendPrompt` string (a plan's rejection findings, a feature task's
+brief, the failing-check list) which the agent harness concatenates **verbatim** onto
+the linked base — the model owns any separator, and a null/empty append leaves the base
 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 `@nanobpm/urban` with
-deploy-time template substitution.
+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
+`linkedResources` and fetches the resource by key.
 
 ## 10. Poller
 
@@ -365,7 +396,7 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
 
 - **CI auto-fix** — a `blocked` verdict means a **required check failed**
   (`classifyMergeability`). Rather than escalate immediately, the stage dispatches a
-  `senior:fix-ci` agent (base prompt via the `{{fix-ci}}` template header; the failing
+  `senior:fix-ci` agent (base prompt via the `fix-ci.md` linked resource; the failing
   check names ride `appendPrompt`) to green the checks on the branch, then re-arms the
   poller. It repeats while `ciFixRound < ciFixMax`
   (`NANO_PR_MAX_CI_FIX_ROUNDS`, default 3; `0` disables). Only when the budget is
@@ -432,7 +463,7 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
 ```
 
 - **`plan`** — service task, job type `senior:plan`. Its base prompt is delivered
-  via the `{{plan}}` model template header (`prompts/plan.md`); when a prior review
+  via the `plan.md` linked resource (`bindingType: latest`); when a prior review
   rejected the plan, the rejection findings ride `appendPrompt` (an ioMapping over
   `planFindings`) rather than being concatenated in FEEL. The agent reads the issue
   via `gh` and emits `tasks: [{ id, title, prompt }]`.
@@ -442,8 +473,8 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
   iterates the canonical list.
 - **`implement`** — service task, job type `senior:feature`, **parallel
   multi-instance** over `=tasks` (`inputElement="task"`,
-  `outputCollection="results"`). Its base prompt is delivered via the `{{feature}}`
-  model template header (`prompts/feature.md`); each child's per-task brief
+  `outputCollection="results"`). Its base prompt is delivered via the `feature.md`
+  linked resource (`bindingType: latest`); each child's per-task brief
   (`"\n\n---\n\n" + task.prompt`) rides `appendPrompt` — an input mapping evaluated
   **per child** (Zeebe parity: the inner activity keeps its own `zeebe:ioMapping`,
   applied on each inner-instance activation with `task`/`loopCounter` bound). Each

package/app/mergeRebaseArm.test.ts

@@ -62,9 +62,9 @@ test("rebase arm mirrors the fix-ci arm: budget gate → agent → result gate",
   assert(hasFlow("gw-rebase", "merge-esc-conflict"), "gw-rebase → merge-esc-conflict (budget exhausted) missing");
   assertStringIncludes(flat, "rebaseRound < rebaseMax");
 
-  // The agent is the senior:rebase fleet task, carrying its base prompt via the {{rebase}} header.
+  // The agent is the senior:rebase fleet task, carrying its base prompt via the rebase.md linked resource.
   assertStringIncludes(flat, 'type="senior:rebase"');
-  assertStringIncludes(flat, 'value="{{rebase}}"');
+  assertStringIncludes(flat, 'resourceId="rebase.md"');
 
   // Agent → result gate; the round counter advances so the budget can actually be exhausted.
   assert(hasFlow("rebase", "gw-rebase-result"), "rebase → gw-rebase-result missing");

package/app/plan.ts

@@ -31,11 +31,12 @@ 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 authored in the model as `{{plan}}` / `{{plan-review}}` /
-// `{{feature}}` deploy-time templates (see `models.templates` in nano.app.json) substituted into
-// each task's `io.nanobpm.agentTask.task.prompt` header. Per-instance dynamic context (a plan's
-// rejection findings, a task's brief) rides `appendPrompt`, which the harness concatenates onto
-// the header base. The host only carries runtime identity + `planFindings`.
+// `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
+// `<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
+// runtime identity + `planFindings`.
 
 export interface Plan {
   plan_key: string;

package/app/retro.ts

@@ -161,7 +161,7 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
 }
 
 /** Render the digest as the compact markdown brief handed to the retro agent (rides `appendPrompt`,
- * concatenated after the base `{{retro}}` prompt — so it owns its own leading separator). */
+ * concatenated after the base `retro.md` linked-resource prompt — so it owns its own leading separator). */
 export function renderRetroBrief(d: RetroDigest): string {
   const lines: string[] = [
     "",

package/app/service.ts

@@ -85,10 +85,11 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
   (process.env.NANO_PR_MERGE_ADMIN ?? "0").trim().toLowerCase(),
 );
 
-// The `senior:pr-review` agent prompt is no longer read by the host: it is authored in the
-// model as a `{{review-round}}` deploy-time template (see `models.templates` in nano.app.json)
-// substituted into the task's `io.nanobpm.agentTask.task.prompt` header. The host only carries
-// runtime PR identity + the round counter now.
+// 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
+// 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.
 
 const now = () => new Date().toISOString();
 

package/nano.app.json

@@ -6,13 +6,11 @@
   "codename": "nano-workforce",
   "models": {
     "processes": [
-      "resources/processes/*.bpmn"
+      "resources/processes/*.bpmn",
+      "prompts/*.md"
     ],
     "forms": [
       "resources/forms/*.form"
-    ],
-    "templates": [
-      "prompts/*.md"
     ]
   },
   "data": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "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/agent-guide.md

@@ -309,9 +309,17 @@ both live in the source repo, not in the job payload.
   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 model
-  **template header** (`{{review-round}}`, `{{plan}}`, …) substituted from these files
-  at deploy time. If an agent misbehaves systematically, the prompt is the first thing
+  agent's base prompt is **not** a job variable: it is delivered as a
+  **linked resource** (likewise `plan.md`, …):
+
+  ```xml
+  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" 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.
 - **Job contract:** `senior:pr-review` receives `{ prUrl, repo, prNumber, round,
   answer? }` and must return a flat result `{ status, summary, question? }` with

package/resources/processes/convergence-loop.bpmn

@@ -67,9 +67,9 @@
     <bpmn:serviceTask id="review-round" name="Review round (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:pr-review" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review-round}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrReviewRoundIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="PrReviewRoundOut" />

package/resources/processes/feature.bpmn

@@ -18,9 +18,9 @@
     <bpmn:serviceTask id="implement-task" name="Implement (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{feature}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="feature.md" bindingType="latest" 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)" target="appendPrompt" />
           <zeebe:output source="=status" target="status" />

package/resources/processes/merge-loop.bpmn

@@ -216,9 +216,9 @@
     <bpmn:serviceTask id="fix-ci" name="Fix CI (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:fix-ci" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{fix-ci}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="fix-ci.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="FixCiIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="FixCiOut" />
@@ -246,9 +246,9 @@
     <bpmn:serviceTask id="rebase" name="Rebase (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:rebase" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{rebase}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="rebase.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RebaseIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="RebaseOut" />

package/resources/processes/plan-fanout.bpmn

@@ -23,9 +23,9 @@
     <bpmn:serviceTask id="plan" name="Plan (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{plan}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="plan.md" bindingType="latest" 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" />
         </zeebe:ioMapping>
@@ -46,9 +46,9 @@
     <bpmn:serviceTask id="review-plan" name="Review plan (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:plan-review" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{plan-review}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="plan-review.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toReviewPlan</bpmn:incoming>
       <bpmn:outgoing>f_toRecordPlanReview</bpmn:outgoing>
@@ -121,9 +121,9 @@
       <bpmn:serviceTask id="implement-task" name="Implement (agent)">
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:feature" />
-          <zeebe:taskHeaders>
-            <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{feature}}" />
-          </zeebe:taskHeaders>
+          <zeebe:linkedResources>
+            <zeebe:linkedResource resourceId="feature.md" bindingType="latest" 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)" target="appendPrompt" />
             <zeebe:output source="=status" target="status" />
@@ -192,9 +192,9 @@
     <bpmn:serviceTask id="trial-merge" name="Trial merge (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:trial-merge" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{trial-merge}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="trial-merge.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=null" target="result" />
           <zeebe:input source="=null" target="conflicts" />

package/resources/processes/retro.bpmn

@@ -14,9 +14,9 @@
     <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:retro" />
-        <zeebe:taskHeaders>
-          <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{retro}}" />
-        </zeebe:taskHeaders>
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="retro.md" bindingType="latest" linkName="prompt" />
+        </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=retroDigest" target="appendPrompt" />
         </zeebe:ioMapping>

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

@@ -1,9 +1,12 @@
 // Red/green coverage for the agent-prompt deploy guard (scripts/check-agent-prompts.ts).
 //
-// The guard exists because a `{{token}}` header that resolves to a missing/blank template — or a
-// blank agent-prompt header — ships an effectively prompt-less agent (the root of the empty
-// "(no question provided)" escalations on Magikcraft/nano-bpm #597/#599). These cases assert it
-// fails on each of those shapes and passes on a well-formed app.
+// 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
+// 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
+// shape and passes on a well-formed app.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
@@ -11,12 +14,18 @@ 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).
 const MANIFEST = JSON.stringify({
-  models: { processes: ["resources/processes/*.bpmn"], templates: ["prompts/*.md"] },
+  models: { processes: ["resources/processes/*.bpmn", "prompts/*.md"] },
 });
 
-function header(value: string): string {
-  return `<zeebe:header key="io.nanobpm.agentTask.task.prompt" value="${value}" />`;
+function link(resourceId: string, bindingType = "latest"): string {
+  return `<zeebe:linkedResource resourceId="${resourceId}" bindingType="${bindingType}" linkName="prompt" />`;
+}
+
+function serviceTask(inner: string): string {
+  return `<bpmn:serviceTask id="t"><bpmn:extensionElements>${inner}</bpmn:extensionElements></bpmn:serviceTask>`;
 }
 
 // Build a throwaway app tree and return its root. Each entry maps a repo-relative path to content.
@@ -30,10 +39,10 @@ function fixture(files: Record<string, string>): string {
   return root;
 }
 
-test("passes when every {{token}} resolves to a non-blank template that emits a result", async () => {
-  const root = await fixture({
+test("passes when every prompt link resolves to a deployed, non-blank, result-emitting resource", () => {
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
     "prompts/review-round.md": "# Round\nDo the thing, then write your result to `$AGENT_RESULT_FILE`.",
   });
   const res = checkAgentPrompts(root);
@@ -42,72 +51,169 @@ test("passes when every {{token}} resolves to a non-blank template that emits a
   assertEquals(res.resolved, ["review-round"]);
 });
 
-test("fails when a header references an undeclared template", async () => {
-  const root = await fixture({
+test("fails when a prompt link references a resourceId with no deployed file", () => {
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header("{{does-not-exist}}"),
-    "prompts/review-round.md": "# Round",
+    "resources/processes/loop.bpmn": serviceTask(link("does-not-exist.md")),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
   });
   const res = checkAgentPrompts(root);
   assert(!res.ok);
-  assert(res.errors.some((e) => e.includes("{{does-not-exist}}") && e.includes("no such template")));
+  assert(res.errors.some((e) => e.includes("does-not-exist.md") && e.includes("no deployed resource")));
 });
 
-test("fails when the referenced template file is blank (would substitute to nothing)", async () => {
-  const root = await fixture({
+test("fails when the prompt exists on disk but is not wired into a deploy glob", () => {
+  // The classic migration mistake: the prompt is left in the retired `models.templates` (which is
+  // substituted, never deployed) instead of a deploy glob, so the engine never receives it.
+  const root = fixture({
+    "nano.app.json": JSON.stringify({
+      models: { processes: ["resources/processes/*.bpmn"], templates: ["prompts/*.md"] },
+    }),
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("review-round.md") && e.includes("no deployed resource")));
+});
+
+test("fails when the linked prompt resource is blank (would run prompt-less)", () => {
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
     "prompts/review-round.md": "   \n  \n",
   });
   const res = checkAgentPrompts(root);
   assert(!res.ok);
-  assert(res.errors.some((e) => e.includes("empty") && e.includes("review-round")));
+  assert(res.errors.some((e) => e.includes("empty") && e.includes("review-round.md")));
 });
 
-test("fails when a reserved agent-prompt header is blank", async () => {
-  const root = await fixture({
+test("fails when a linkName=prompt link has an empty resourceId", () => {
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header(""),
-    "prompts/review-round.md": "# Round",
+    "resources/processes/loop.bpmn": serviceTask(link("")),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
   });
   const res = checkAgentPrompts(root);
   assert(!res.ok);
-  assert(res.errors.some((e) => e.includes("is empty")));
+  assert(res.errors.some((e) => e.includes("empty resourceId")));
 });
 
-test("fails when an agent-prompt template omits the machine-readable result mechanism", async () => {
+test("fails when the retired baked prompt header is still present", () => {
+  // The deploy no longer substitutes {{token}} templates, so a surviving baked header ships a
+  // literal placeholder as the prompt.
+  const root = fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": serviceTask(
+      '<zeebe:taskHeaders><zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review-round}}" /></zeebe:taskHeaders>',
+    ),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("retired") && e.includes("linkedResource")));
+});
+
+test("fails when the retired baked prompt header survives with reordered attributes", () => {
+  // XML attribute order is not significant: a retired header with `value` before `key` must still be
+  // caught. The guard used to anchor `key` immediately after `<zeebe:header`, so a reordered header
+  // would slip through and ship a literal placeholder as the prompt.
+  const root = fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": serviceTask(
+      '<zeebe:taskHeaders><zeebe:header value="{{review-round}}" key="io.nanobpm.agentTask.task.prompt" /></zeebe:taskHeaders>',
+    ),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("retired") && e.includes("linkedResource")));
+});
+
+test("fails when a linked prompt resource omits the machine-readable result mechanism", () => {
   // A prompt wired as an agent's base prompt must tell it to write $AGENT_RESULT_FILE (or use the
   // ::nano:result:: fallback). Without it the agent finishes with prose only, `status` comes back
   // blank, and the status gateway escalates/stalls — the fix-ci/rebase gap behind #746's stuck merge.
-  const root = await fixture({
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
     "prompts/review-round.md": "# Round\nReturn status: converged. (but never says how to emit it)",
   });
   const res = checkAgentPrompts(root);
   assert(!res.ok);
-  assert(res.errors.some((e) => e.includes("{{review-round}}") && e.includes("AGENT_RESULT_FILE")));
+  assert(res.errors.some((e) => e.includes("review-round.md") && e.includes("AGENT_RESULT_FILE")));
 });
 
-test("passes when an agent-prompt template emits via the ::nano:result:: fallback", async () => {
-  const root = await fixture({
+test("passes when a linked prompt resource emits via the ::nano:result:: fallback", () => {
+  const root = fixture({
     "nano.app.json": MANIFEST,
-    "resources/processes/loop.bpmn": header("{{review-round}}"),
-    "prompts/review-round.md": "# Round\nEmit `::nano:result:: {\"status\":\"converged\"}` at the end.",
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    "prompts/review-round.md": '# Round\nEmit `::nano:result:: {"status":"converged"}` at the end.',
   });
   const res = checkAgentPrompts(root);
   assertEquals(res.errors, []);
   assert(res.ok);
 });
 
-test("checks the real repo: all committed agent prompts resolve", () => {
+test("fails when a prompt link uses a bindingType other than latest", () => {
+  const root = fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md", "deployment")),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("review-round.md") && e.includes('bindingType="deployment"')));
+});
+
+test("fails when a prompt link omits bindingType entirely", () => {
+  const root = fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": serviceTask(
+      '<zeebe:linkedResource resourceId="review-round.md" linkName="prompt" />',
+    ),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("review-round.md") && e.includes("(absent)")));
+});
+
+test("fails when no prompt link is wired at all", () => {
+  const root = fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": serviceTask('<zeebe:taskDefinition type="pr.noop" />'),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("unwired")));
+});
+
+test("fails when two deploy globs match files sharing a basename (ambiguous resource name)", () => {
+  // Two deployed files with the same basename would silently overwrite in the resourceId lookup, so
+  // a linkName="prompt" resourceId could resolve to the wrong file. The guard must fail fast.
+  const root = fixture({
+    "nano.app.json": JSON.stringify({
+      models: { processes: ["resources/processes/*.bpmn", "prompts/*.md", "extra/*.md"] },
+    }),
+    "resources/processes/loop.bpmn": serviceTask(link("review-round.md")),
+    "prompts/review-round.md": "# Round\nWrite `$AGENT_RESULT_FILE`.",
+    "extra/review-round.md": "# Duplicate\nWrite `$AGENT_RESULT_FILE`.",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("duplicate deployed resource name") && e.includes("review-round.md")));
+});
+
+test("checks the real repo: all committed agent prompts link to deployed resources", () => {
   // The guard must be green against the actual app it protects — this is the case CI relies on.
   const repoRoot = decodeURIComponent(new URL("../", import.meta.url).pathname);
   const res = checkAgentPrompts(repoRoot);
   assertEquals(res.errors, []);
   assert(res.ok);
-  // Every senior:* agent prompt header in the three processes must have resolved.
+  // Every senior:* agent prompt across the processes must resolve to a deployed prompt resource.
   for (const t of ["review-round", "fix-ci", "plan", "plan-review", "feature", "trial-merge", "rebase", "retro"]) {
-    assert(res.resolved.includes(t), `expected template ${t} to resolve`);
+    assert(res.resolved.includes(t), `expected prompt ${t} to resolve`);
   }
 });

package/scripts/check-agent-prompts.ts

@@ -1,33 +1,53 @@
-// check-agent-prompts — deploy-safety gate for the model-authored `{{template}}` agent prompts.
+// check-agent-prompts — deploy-safety gate for the agent prompts, now authored as *linked
+// resources* (issue #169) rather than baked `{{token}}` templates.
 //
-// Since #31 (v0.11.0) each agent's prompt is authored in the BPMN as a deploy-time template
-// header, e.g. `<zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{review-round}}" />`.
-// `@nanobpm/urban` substitutes `{{token}}` with `prompts/<token>.md` (nano.app.json
-// `models.templates`) at deploy time; the harness (`c8ctl nano work`) does NO substitution and
-// relays whatever header ships. So a token that resolves to a missing/blank template — or a blank
-// agent-prompt header — runs the agent effectively prompt-less. For `senior:pr-review` that makes
-// it improvise as a "reviewer" and escalate with no question (Magikcraft/nano-bpm #597/#599).
+// 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:
 //
-// urban's deploy only *warns* on an unresolved placeholder and ships the resource with the raw
-// token in place — and this project does not tolerate warnings. This guard runs urban's OWN
-// substitution (`applyTemplates`, the single source of truth for token scanning/escaping) exactly
-// as deploy does and turns any surviving placeholder into a hard failure, plus flags a blank
-// template or a blank agent-prompt header (which substitute to an empty prompt without being
-// "unresolved"). Importing from `@nanobpm/urban/runtime` also asserts the installed urban is new
-// enough to substitute at all (the capability was added in the 0.22 / nano-ide #106 release).
+//   <zeebe:linkedResources>
+//     <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt" />
+//   </zeebe:linkedResources>
+//
+// The engine resolves the LATEST deployed key for that `resourceId` when the job activates and hands
+// the content to the harness in the `linkedResources` activation header. Crucially, the engine
+// *silently omits* an unresolvable link (a typo'd or undeployed `resourceId`) from the header — no
+// incident — so a mistake yields a blank base prompt at runtime, exactly the prompt-less-agent
+// failure that produced the empty "(no question provided)" escalations (Magikcraft/nano-bpm
+// #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).
+//   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
+//      Magikcraft/nano-bpm#746's stuck merge).
+//   3. No service task may still carry the retired baked `io.nanobpm.agentTask.task.prompt` header:
+//      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 { applyTemplates } from "@nanobpm/urban/runtime";
 
-// The reserved header carrying an agent's base prompt. A blank value here means the agent gets no
-// instructions — the exact failure mode we guard against.
-const AGENT_PROMPT_HEADER = "io.nanobpm.agentTask.task.prompt";
+// 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.
+const RETIRED_PROMPT_HEADER = "io.nanobpm.agentTask.task.prompt";
+
+// The `linkName` that designates a linked resource as an agent's base prompt. Other link names (if
+// any are ever added) are not agent prompts and are ignored by this guard.
+const PROMPT_LINK_NAME = "prompt";
+
+// A prompt link MUST bind `latest` — this whole migration (#169) is about live mid-epic prompt
+// updates, which only work when the engine resolves the latest deployed key at activation. A
+// missing or different `bindingType` would silently pin/omit the prompt, so the guard fails it.
+const PROMPT_BINDING_TYPE = "latest";
 
 interface AppManifest {
   models?: { processes?: string[]; decisions?: string[]; forms?: string[]; templates?: string[] };
 }
 
-// Mirror urban deploy's `contentTypeFor`: only the escapable model types are substituted.
+// Only the escapable model types are XML we scan for `<zeebe:linkedResource>` links.
 function contentTypeFor(path: string): string {
   if (path.endsWith(".bpmn") || path.endsWith(".dmn")) return "text/xml";
   if (path.endsWith(".form")) return "application/json";
@@ -48,53 +68,47 @@ function expandGlob(root: string, pattern: string): string[] {
     .map((f) => join(dir, f));
 }
 
-// The `name -> content` template map urban substitutes from (array source: name = file stem).
-function templateMap(root: string, patterns: string[]): Record<string, string> {
-  const map: Record<string, string> = {};
-  for (const pattern of patterns) {
-    for (const rel of expandGlob(root, pattern)) {
-      const stem = basename(rel).replace(/\.[^.]+$/, "");
-      map[stem] = readFileSync(join(root, rel), "utf8");
-    }
-  }
-  return map;
+interface PromptLink {
+  resourceId: string;
+  bindingType: string | null;
 }
 
-// Blank reserved agent-prompt headers in a BPMN source — the one blank case urban's `unresolved`
-// signal can't see (an empty value carries no `{{token}}` to be unresolved).
-function hasBlankAgentPromptHeader(bpmn: string): boolean {
-  const re = /<zeebe:header\s+key="([^"]*)"\s+value="([^"]*)"\s*\/?>/g;
+// Extract the `<zeebe:linkedResource linkName="prompt" …>` links from a BPMN source. Each agent
+// service task carries exactly one; a process may host several tasks.
+function promptLinks(bpmn: string): PromptLink[] {
+  const links: PromptLink[] = [];
+  const re = /<zeebe:linkedResource\b([^>]*?)\/?>/g;
   let m = re.exec(bpmn);
   while (m !== null) {
-    if (m[1] === AGENT_PROMPT_HEADER && m[2].trim() === "") return true;
+    const attrs = m[1];
+    const linkName = /\blinkName="([^"]*)"/.exec(attrs)?.[1];
+    if (linkName === PROMPT_LINK_NAME) {
+      const resourceId = /\bresourceId="([^"]*)"/.exec(attrs)?.[1] ?? "";
+      const bindingType = /\bbindingType="([^"]*)"/.exec(attrs)?.[1] ?? null;
+      links.push({ resourceId, bindingType });
+    }
     m = re.exec(bpmn);
   }
-  return false;
+  return links;
 }
 
-// The template tokens a model wires as an agent's base prompt, e.g. the `fix-ci` in
-// `value="{{fix-ci}}"` on an `io.nanobpm.agentTask.task.prompt` header. These templates *drive an
-// agent*, so each must teach it to emit a machine-readable result (see agentPromptEmitsResult).
-function agentPromptTokens(bpmn: string): string[] {
-  const tokens: string[] = [];
-  const re = /<zeebe:header\s+key="([^"]*)"\s+value="([^"]*)"\s*\/?>/g;
-  let m = re.exec(bpmn);
-  while (m !== null) {
-    if (m[1] === AGENT_PROMPT_HEADER) {
-      const tok = /^\{\{\s*([^}]+?)\s*\}\}$/.exec(m[2].trim());
-      if (tok) tokens.push(tok[1]);
-    }
-    m = re.exec(bpmn);
-  }
-  return tokens;
+// Escape a literal string for safe embedding in a RegExp — the header key contains dots that would
+// otherwise act as wildcards and match unintended header keys.
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// Any surviving retired baked-prompt header — a migration regression. XML attribute order is not
+// significant, so match the `key` attribute anywhere within the opening `<zeebe:header …>` tag (not
+// only immediately after the element name) — otherwise a reordered header would bypass the guard.
+function hasRetiredPromptHeader(bpmn: string): boolean {
+  return new RegExp(`<zeebe:header\\s[^>]*\\bkey="${escapeRegExp(RETIRED_PROMPT_HEADER)}"`).test(bpmn);
 }
 
 // A prompt that drives an agent must tell it how to return a machine-readable result — the
 // `$AGENT_RESULT_FILE` write (or the `::nano:result::` stdout fallback). Without it the agent can
 // finish with prose only, its `status` variable comes back empty, the status gateway falls through
-// to its default escalation arm, and the run parks a human escalation / stalls the merge (the
-// fix-ci/rebase gap behind Magikcraft/nano-bpm#746's stuck merge). Prose is never parsed, so this
-// instruction is load-bearing, not documentation.
+// to its default escalation arm, and the run parks a human escalation / stalls the merge.
 function agentPromptEmitsResult(body: string): boolean {
   return body.includes("AGENT_RESULT_FILE") || body.includes("::nano:result::");
 }
@@ -102,14 +116,13 @@ function agentPromptEmitsResult(body: string): boolean {
 export interface CheckResult {
   ok: boolean;
   errors: string[];
-  /** template names successfully substituted into a model — surfaced for the CLI summary line. */
+  /** prompt resource ids (file stems) successfully linked — surfaced for the CLI summary line. */
   resolved: string[];
 }
 
 export function checkAgentPrompts(root: string): CheckResult {
   const errors: string[] = [];
   const resolved = new Set<string>();
-  const agentTokens = new Set<string>();
 
   const manifestPath = join(root, "nano.app.json");
   if (!existsSync(manifestPath)) {
@@ -118,57 +131,96 @@ 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 ?? {};
-  const templates = templateMap(root, models.templates ?? []);
-
-  // A declared-but-blank template substitutes to an empty prompt without being "unresolved" —
-  // catch it up front (urban would silently produce a blank prompt).
-  for (const [name, body] of Object.entries(templates)) {
-    if (body.trim() === "") errors.push(`template {{${name}}} is empty — it would substitute to a blank prompt`);
-  }
 
-  const modelFiles = [
+  // 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 ?? []),
-  ].flatMap((p) => expandGlob(root, p));
-  if (modelFiles.length === 0) {
-    errors.push(`no model files matched ${JSON.stringify(models.processes ?? [])}`);
+  ];
+  // 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.
+  const deployedFiles = new Map<string, string>();
+  for (const rel of deployGlobs.flatMap((p) => expandGlob(root, p))) {
+    const name = basename(rel);
+    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`,
+      );
+      continue;
+    }
+    deployedFiles.set(name, rel);
   }
 
-  for (const rel of modelFiles) {
-    const contentType = contentTypeFor(rel);
-    if (contentType === "application/octet-stream") continue; // urban does not substitute these
+  // 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");
+  if (xmlModelFiles.length === 0) {
+    errors.push(`no BPMN/DMN model files matched ${JSON.stringify(deployGlobs)}`);
+  }
+
+  let linkCount = 0;
+  for (const rel of xmlModelFiles) {
     const content = readFileSync(join(root, rel), "utf8");
 
-    // Run urban's canonical substitution — the same call deploy makes — and fail on any token it
-    // leaves unresolved (deploy only warns, which we don't tolerate).
-    const applied = applyTemplates(content, contentType, templates);
-    for (const name of applied.unresolved) {
+    if (hasRetiredPromptHeader(content)) {
       errors.push(
-        `${rel}: unresolved template {{${name}}} — no such template is declared in models.templates`,
+        `${rel}: a retired "${RETIRED_PROMPT_HEADER}" header is still present — migrate it to a ` +
+          `<zeebe:linkedResource … linkName="prompt"/> (the deploy no longer substitutes {{token}} templates)`,
       );
     }
-    for (const name of Object.keys(templates)) {
-      if (content.includes(`{{${name}}}`)) resolved.add(name);
-    }
 
-    if (hasBlankAgentPromptHeader(content)) {
-      errors.push(`${rel}: a reserved "${AGENT_PROMPT_HEADER}" header is empty (agent would run prompt-less)`);
+    for (const link of promptLinks(content)) {
+      linkCount++;
+      if (link.resourceId.trim() === "") {
+        errors.push(`${rel}: a linkName="prompt" linkedResource has an empty resourceId`);
+        continue;
+      }
+      if (link.bindingType !== PROMPT_BINDING_TYPE) {
+        errors.push(
+          `${rel}: linkName="prompt" resourceId="${link.resourceId}" has ` +
+            `bindingType=${link.bindingType == null ? "(absent)" : `"${link.bindingType}"`} — it must be ` +
+            `bindingType="${PROMPT_BINDING_TYPE}" so the engine resolves the latest deployed prompt at ` +
+            `activation (mid-epic prompt updates rely on it); any other value silently alters runtime ` +
+            `prompt resolution`,
+        );
+      }
+      const deployedRel = deployedFiles.get(link.resourceId);
+      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`,
+        );
+        continue;
+      }
+      const body = readFileSync(join(root, deployedRel), "utf8");
+      const stem = basename(deployedRel).replace(/\.[^.]+$/, "");
+      if (body.trim() === "") {
+        errors.push(`prompt resource "${link.resourceId}" is empty — the agent would run prompt-less`);
+      } else if (!agentPromptEmitsResult(body)) {
+        errors.push(
+          `prompt resource "${link.resourceId}" drives an agent but never tells it to write ` +
+            `$AGENT_RESULT_FILE (or the ::nano:result:: fallback) — the agent can finish with prose ` +
+            `only, leaving its status blank so the process escalates/stalls`,
+        );
+      }
+      resolved.add(stem);
     }
-    for (const tok of agentPromptTokens(content)) agentTokens.add(tok);
   }
 
-  // Every template wired as an agent's base prompt must teach the agent to emit a machine-readable
-  // result; a prose-only agent leaves `status` blank and the process escalates/stalls.
-  for (const tok of [...agentTokens].sort()) {
-    const body = templates[tok];
-    if (body != null && body.trim() !== "" && !agentPromptEmitsResult(body)) {
-      errors.push(
-        `template {{${tok}}} drives an agent but never tells it to write $AGENT_RESULT_FILE ` +
-          `(or the ::nano:result:: fallback) — the agent can finish with prose only, leaving its ` +
-          `status blank so the process escalates/stalls`,
-      );
-    }
+  if (linkCount === 0 && errors.length === 0) {
+    errors.push("no linkName=\"prompt\" linkedResource found in any model — agent prompts are unwired");
   }
 
   return { ok: errors.length === 0, errors, resolved: [...resolved].sort() };
@@ -183,5 +235,5 @@ if (import.meta.main) {
     for (const e of errors) console.error(`  - ${e}`);
     process.exit(1);
   }
-  console.log(`✔ agent prompt templates resolve (${resolved.length}: ${resolved.join(", ")})`);
+  console.log(`✔ agent prompts link to deployed resources (${resolved.length}: ${resolved.join(", ")})`);
 }