@nanobpm/nano-workforce 0.60.0 → 0.61.1

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(", ")})`);
 }

package/workers/record-blocked-ack/worker.test.ts

@@ -0,0 +1,49 @@
+// Unit coverage for pr.record-blocked-ack — the operator acknowledged a blocked feature run.
+// It must settle the parked (non-terminal `awaiting_operator`) row at terminal `blocked` and record
+// the operator's disposition note into `delivery_label` so the same issue can be re-dispatched.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp(rows: Record<string, unknown>[]) {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  } as any;
+}
+
+test("record-blocked-ack: settles the parked run at terminal blocked and records the operator note", async () => {
+  const rows = [{ feature_key: "owner/repo#7", status: "awaiting_operator", delivery_label: null }];
+  const app = fakeApp(rows);
+  const out = await handler({ variables: { featureKey: "owner/repo#7", note: "reassigned to a human" } } as any, app);
+  assertEquals(out, {});
+  assertEquals(rows[0].status, "blocked");
+  assertEquals(rows[0].delivery_label, "operator: reassigned to a human");
+});
+
+test("record-blocked-ack: a blank note falls back to an 'acknowledged' label", async () => {
+  const rows = [{ feature_key: "owner/repo#8", status: "awaiting_operator", delivery_label: null }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#8", note: "   " } } as any, app);
+  assertEquals(rows[0].status, "blocked");
+  assertEquals(rows[0].delivery_label, "acknowledged");
+});