@nanobpm/nano-workforce 0.201.3 → 0.201.4

package/.github/workflows/ci.yml

@@ -58,6 +58,17 @@ jobs:
       - name: Check agent prompt templates
         run: npm run check:prompts
 
+      # Agent-definition gate (issue #884): every `senior:*` agent service task the app deploys —
+      # hand-authored in resources/processes/*.bpmn OR produced by the delivery-graph compiler — must
+      # carry `<zeebe:agentDefinition agentType="external"/>`, or the engine refuses to mint an
+      # AgentInstance for it and the run persists no durable agentic transcript (the 269 failed
+      # creates on omarchy). Compiled agent cells are deliberately prompt-LESS (the resolved #884
+      # "Decide", Option (a)): the compiler emits the marker on EVERY agent cell unconditionally, and
+      # the gate keys agent-ness on the `<rank>:<task>` colon-form type (the type-keyed scanner), so a
+      # compiled cell that drops the marker fails here, not silently at runtime.
+      - name: Check agent task definitions (external marker)
+        run: npm run check:agent-definitions
+
       # Merge-safety gate: migrations are applied in numeric-prefix order, but each fan-out branch
       # picks "the next" prefix independently, so parallel siblings silently collide on one slot
       # (the historical 004/005/006/007 pairs; recurred on epic #142). This fails the build on any

package/AGENTS.md

@@ -393,13 +393,15 @@ 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 linkedResource resolution
+npm run check:agent-definitions                       # every senior:* agent task (authored corpus + compiled delivery-graph output) carries the agentDefinition marker
 npm run check:migrations                              # migration prefixes + immutability (no rename/delete/edit of a merged migration)
 npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)
 ```
 
 CI (`.github/workflows/ci.yml`) gates lint, typecheck, `urban check`, `layout:check`,
-the prompt check, the migration-prefix check, the contract-registry check, and the Node test suite. Run `npm run layout <file.bpmn>` after
+the prompt check, the agent-definition check, the migration-prefix check, the
+contract-registry check, and the Node test suite. Run `npm run layout <file.bpmn>` after
 any BPMN flow change and commit the regenerated diagram — the `layout:check`
 gate fails the build otherwise.
 

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.201.4](https://github.com/nanobpm/nano-workforce/compare/v0.201.3...v0.201.4) (2026-10-11)
+
+### Bug Fixes
+
+* **delivery-graph:** emit zeebe:agentDefinition marker on every compiled agent cell (prompt-less, Option (a)) ([#886](https://github.com/nanobpm/nano-workforce/issues/886)) ([1e4fa4f](https://github.com/nanobpm/nano-workforce/commit/1e4fa4f46aad542b2e6fc175a3af0b46d0980f50)), closes [#464](https://github.com/nanobpm/nano-workforce/issues/464) [#745](https://github.com/nanobpm/nano-workforce/issues/745) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#776](https://github.com/nanobpm/nano-workforce/issues/776) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884)
+
 ## [0.201.3](https://github.com/nanobpm/nano-workforce/compare/v0.201.2...v0.201.3) (2026-10-10)
 
 ### Bug Fixes

package/SPEC.md

@@ -646,11 +646,25 @@ the app, which deploys on boot), and the next agent job of that type picks it up
 > marker is CI-enforced over the deployed `resources/` process models
 > (`agentTaskTypesMissingExternalMarker`,
 > `agent-marker.test.ts`), so no prompt-bearing agent task in those models relies on
-> prompt-link-only discovery. (The delivery-graph compiler's GENERATED agent BPMN —
-> deployed at run time by `runDeliveryGraph`, not authored under `resources/` — is a
-> separate deployed path NOT covered by this static guard; whether its generated cells
-> should also carry the marker/opt-out convention is tracked separately under issue #745,
-> not #779.) To **exclude** a task from `--auto` — one that must be served only by a
+> prompt-link-only discovery. The delivery-graph compiler's GENERATED agent BPMN —
+> deployed at run time by `runDeliveryGraph`, not authored under `resources/` — is the
+> second producer of agent service tasks, and it is covered too (issue #884): the
+> compiler emits the marker on **every** `agent` cell it compiles. Per the resolved
+> "Decide" half of #884 (Option (a), PR #886 review) a compiled cell carries **no**
+> base-prompt link — the hand-authored process prompts (`prompts/feature.md`, …) are
+> process-specific contracts that require process variables (`variables.task`/
+> `variables.issue`) and a `feat/<task.id>` branch the generic compiled cell never
+> supplies (it seeds only `{jobType, appendPrompt, timeout}` and the harness provisions
+> `feat/<node.id>`, #776), so linking one would hand the cell instructions referencing
+> missing inputs and a conflicting branch. The cell is deliberately prompt-less, steered
+> by its per-node `appendPrompt` alone; the marker alone fixes the #884
+> `createAgentInstance` failure. `npm run check:agent-definitions`
+> (CI gate `check:agent-definitions`, `scripts/check-agent-definitions.ts`) compiles a
+> representative graph — including a prompt-less probe cell — and scans the
+> output with both the prompt-keyed scanner and the prompt-link-independent
+> `externalAgentTaskTypesMissingMarker` (a task is an agent by its `<rank>:<task>`
+> colon-form type alone), so a compiler regression that drops the marker fails the
+> build rather than silently at runtime. To **exclude** a task from `--auto` — one that must be served only by a
 > worker that explicitly subscribes (`--job-type <type>` / a profile capability) — add
 > the inert opt-out property inside its `extensionElements`, nested in the
 > `<zeebe:properties>` wrapper the models and engine expect (as

package/app/agentic/vocab/agent-marker.test.ts

@@ -9,7 +9,8 @@ import { test } from "node:test";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
-import { agentTaskTypesMissingExternalMarker, promptBearingTaskTypes } from "./job-types.ts";
+import { compileDeliveryGraph } from "../../deliveryGraphCompiler.ts";
+import { agentTaskTypesMissingExternalMarker, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -72,3 +73,31 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent task carries the e
   // Sanity: the models really do declare agent tasks (guard is not vacuously green).
   assert(anyAgentTasks, "the deployed models declare prompt-bearing agent tasks");
 });
+
+test("DEFECT-CLASS GUARD (compiler output, issue #884): every COMPILED delivery-graph agent cell carries the marker", async () => {
+  // The hand-authored corpus above is only HALF the class — the delivery-graph COMPILER
+  // (`app/deliveryGraphCompiler.ts`) is the other producer of agent service tasks, and it emitted
+  // cells with NO `agentDefinition` until #884: every delivery-graph agent run failed AgentInstance
+  // creation (`… has no agentDefinition`) and persisted no durable transcript (269 failed creates on
+  // omarchy). Per the resolved "Decide" half of #884 (Option (a), PR #886 review) a compiled cell is
+  // prompt-LESS (no base-prompt link), so the prompt-keyed scanner cannot see it — it is the
+  // type-keyed half of the union scanner (`missingExternalMarkerAgentTaskTypes`, keyed by the
+  // `<rank>:<task>` colon-form type) that sees these cells. Apply the SAME union to the compiler's
+  // OUTPUT so a compiler regression that drops the marker fails here — not silently at runtime.
+  const r = await compileDeliveryGraph({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+    ],
+    edges: [{ from: "impl", to: "review" }],
+  });
+  assert(r.ok, `expected the graph to compile, got ${JSON.stringify(r)}`);
+  // The compiled agent cells are prompt-LESS (Option (a)), so the prompt-keyed scan sees none — the
+  // union's type-keyed half is what covers them.
+  assertEquals(promptBearingTaskTypes(r.bpmn), []);
+  const missing = missingExternalMarkerAgentTaskTypes(r.bpmn);
+  assert(
+    missing.length === 0,
+    `compiled delivery-graph agent cell(s) missing <zeebe:agentDefinition agentType="external" /> — ${missing.join(", ")}`,
+  );
+});

package/app/agentic/vocab/job-types.test.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { crewResolver } from "./crew-vocab.ts";
-import { jobTypeToRoutingToken, promptBearingTaskTypes } from "./job-types.ts";
+import { externalAgentTaskTypesMissingMarker, jobTypeToRoutingToken, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -105,3 +105,135 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent job type resolves
     );
   }
 });
+
+test("externalAgentTaskTypesMissingMarker flags an UNMAPPED (prompt-less) agent task with no marker", () => {
+  // The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) cannot see this block — it has no
+  // prompt link. The marker scan must key on the colon-form job type ALONE (issue #886 review): a
+  // compiled delivery-graph cell for a bespoke `senior:<task>` (no deployed base prompt, deliberately
+  // prompt-less) must still carry the marker or it runs transcript-less.
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker passes a marked prompt-less agent task and ignores a plain host task", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("externalAgentTaskTypesMissingMarker flags a marked-outside-extensionElements task (placement contract)", () => {
+  // A marker sitting OUTSIDE `<bpmn:extensionElements>` is ignored by the engine, so it must not
+  // "cover" the task here either (the same placement scope the prompt-keyed scanner enforces).
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <zeebe:agentDefinition agentType="external" />
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker ignores malformed/non-agent types (no false positives)", () => {
+  // Only a `<rank>:<task>` colon-form type (the `jobTypeToRoutingToken` grammar) keys a block as an
+  // agent task: a dot-form host job, a typeless block, and a malformed colon form are all out of
+  // scope — the scanner must not flag them as unmarked agents.
+  const xml = `
+    <bpmn:serviceTask id="host1">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host2">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature:extra" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host3">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host4">
+      <bpmn:extensionElements>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes unions BOTH scanners — catches a prompt-bearing AND a prompt-less unmarked agent task", () => {
+  // The single "every agent task carries the external marker" invariant (PR #886 review): a
+  // prompt-BEARING senior:* task that loses its marker is caught only by the prompt-keyed scanner,
+  // while a prompt-LESS senior:* task that loses its marker is caught only by the type-keyed scanner.
+  // Scanning by just one leaves the other's blind spot open, so the union must flag BOTH in one pass.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature", "senior:bespoke"]);
+});
+
+test("missingExternalMarkerAgentTaskTypes passes when every agent task is marked and ignores host tasks", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes de-duplicates a type caught by both scanners", () => {
+  // A prompt-bearing task missing its marker is seen by BOTH the prompt-keyed and the type-keyed
+  // scanner; the union must report it ONCE, not twice.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature"]);
+});

package/app/agentic/vocab/job-types.ts

@@ -140,6 +140,63 @@ export function agentTaskTypesMissingExternalMarker(xml: string): string[] {
   return missing;
 }
 
+/**
+ * Scan one BPMN document for the job types of agent service tasks — keyed by their `<rank>:<task>`
+ * colon-form `<zeebe:taskDefinition type>` ALONE, NOT by a prompt link — that are MISSING the
+ * engine-native AgentTask marker `<zeebe:agentDefinition agentType="external" />` (issue #884,
+ * PR #886 review). The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) is blind to a
+ * DELIBERATELY prompt-less agent task — and EVERY compiled delivery-graph cell is prompt-less (the
+ * resolved #884 "Decide", Option (a): the cell carries the marker alone and is steered by its
+ * per-node `appendPrompt`, never a linked base prompt) — so a marker regression on exactly those
+ * cells would pass that scan vacuously. This scan keys a service task as an AGENT by the same grammar
+ * the crew bridge uses (`jobTypeToRoutingToken`: a single-colon `<rank>:<task>` whose rank is a bare
+ * routing segment), which needs no prompt link, so EVERY agent task — prompt-bearing or not — is
+ * inspected for the marker independently of its prompt status. A dot-form host job (`pr.finalize`),
+ * a typeless block, and a malformed colon form (`senior:feature:extra`) are not agent job types and
+ * are ignored (no false positives). The marker check is scoped to the block's
+ * `<bpmn:extensionElements>` (the engine-honoured PLACEMENT scope, via `extensionElementsOf`) — a
+ * marker sitting outside `extensionElements` is ignored by the engine, so it must not "cover" a
+ * task here either. Returns the offending task types in first-occurrence order (empty when every
+ * agent task is marked).
+ */
+export function externalAgentTaskTypesMissingMarker(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || jobTypeToRoutingToken(type) === undefined) continue;
+    if (EXTERNAL_AGENT_MARKER.test(extensionElementsOf(block))) continue;
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
+/**
+ * The SINGLE "every agent service task carries the engine-native `<zeebe:agentDefinition
+ * agentType="external" />` marker" invariant (issue #745/#884, PR #886 review), as the UNION of both
+ * marker scanners. The two scanners each have a blind spot: `agentTaskTypesMissingExternalMarker` keys
+ * a task as an agent by its PROMPT link, so it cannot see a deliberately prompt-less agent cell;
+ * `externalAgentTaskTypesMissingMarker` keys it by its `<rank>:<task>` colon-form type, so it covers
+ * the prompt-less case but is the newer path. Scanning a corpus with only one leaves the other's blind
+ * spot open — a hand-authored (or compiled) `senior:*` task that loses BOTH its prompt link and its
+ * marker would pass a prompt-keyed-only gate. Every producer of agent tasks (the hand-authored corpus
+ * AND the delivery-graph compiler) is checked against THIS union, so neither half can regress through
+ * the other's blind spot. Returns the distinct offending task types in first-occurrence order (the
+ * prompt-keyed matches first, then any type-keyed-only ones), empty when every agent task is marked.
+ */
+export function missingExternalMarkerAgentTaskTypes(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const type of [...agentTaskTypesMissingExternalMarker(xml), ...externalAgentTaskTypesMissingMarker(xml)]) {
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
 /**
  * Scan one BPMN document for the job types of agent service tasks that OPT OUT of the harness
  * `--auto` reconciliation (issue #779) — those carrying `<zeebe:property

package/app/contracts.ts

@@ -538,9 +538,9 @@ export const WIRE_CONTRACTS = {
   "agentTask.agentDefinition": {
     category: "wire",
     name: "agentTask.agentDefinition",
-    owner: "resources/processes/*.bpmn",
+    owner: "resources/processes/*.bpmn + app/deliveryGraphCompiler.ts",
     semantics:
-      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
+      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. The class is EVERY agent service task the app generates (issue #884): the hand-authored corpus AND every delivery-graph-compiler `agent` cell. The compiler emits the marker on EVERY cell and — per the resolved \"Decide\" half of #884 (Option (a), PR #886 review) — NO base-prompt link: the hand-authored process prompts are process-specific contracts (they require process variables and a `feat/<task.id>` branch the generic compiled cell never supplies), so a compiled cell is deliberately prompt-LESS and steered by its per-node `appendPrompt` alone. `npm run check:agent-definitions` (scripts/check-agent-definitions.ts, in CI) gates BOTH producers: it scans the compiled output with the prompt-keyed `agentTaskTypesMissingExternalMarker` AND the prompt-link-independent `externalAgentTaskTypesMissingMarker` (an agent task is keyed by its `<rank>:<task>` colon-form type alone, so a marker regression on a prompt-less cell cannot hide). Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
   "agentTask.autoSubscribe": {

package/app/deliveryGraphCompiler.test.ts

@@ -14,6 +14,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { missingExternalMarkerAgentTaskTypes } from "./agentic/vocab/job-types.ts";
 import { compileDeliveryGraph, digestInvisibleRawValues, graphCarriesRedactedSecrets, nodeDisplay, redactFreeText, resumeValidVar } from "./deliveryGraphCompiler.ts";
 import { isDeliveryEscalationTwin } from "./deliveryHuman.ts";
 
@@ -158,6 +159,86 @@ test("trust bound: every node inlines an embedded subProcess delegating to an al
   assert(/<bpmn:userTask id="delivery-human-task__n\d+__esc"/.test(r.bpmn), "a bounded node inlines an escalation user task");
 });
 
+test("#884 agentDefinition: every compiled agent cell carries the engine-native AgentTask marker (durable transcript)", async () => {
+  // Issue #884: a compiled `agent` cell's service task carried NO
+  // `<zeebe:agentDefinition agentType="external"/>`, so the engine refused to attach an AgentInstance
+  // to it (`createAgentInstance failed — … has no agentDefinition`) and every delivery-graph agent run
+  // persisted NO durable agentic transcript. The hand-authored processes declare the marker on every
+  // `senior:*` task (issue #745); the compiler must emit it on every agent cell it generates — the
+  // defect CLASS is "every agent service task the app generates", so this guards the compiler output
+  // through the SAME canonical union scanner (`missingExternalMarkerAgentTaskTypes`, the one the
+  // repo-wide gate in `check-agent-definitions.ts` uses) rather than a second, driftable regex.
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // RELEASE_RUNBOOK has exactly one agent node (`open-b` → `senior:feature`); its compiled service
+  // task is `<el>_task`. A compiled agent cell is prompt-LESS (the resolved #884 "Decide", Option (a)),
+  // so it is the type-keyed half of the union scanner (keyed by the `<rank>:<task>` colon-form type)
+  // that sees it — and the marker must be present on THAT cell, not merely somewhere in the document
+  // (a stray marker on a DIFFERENT element would not make THIS cell eligible for AgentInstance minting).
+  const taskBlock = [...r.bpmn.matchAll(/<bpmn:serviceTask id="n\d+_task"[\s\S]*?<\/bpmn:serviceTask>/g)]
+    .map((m) => m[0])
+    .find((b) => b.includes('<zeebe:taskDefinition type="senior:feature" />')) ?? "";
+  assert(taskBlock !== "", "the agent node compiles to an inner senior:feature service task");
+  const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(taskBlock)?.[0] ?? "";
+  assert(
+    /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+    `the compiled agent cell carries <zeebe:agentDefinition agentType="external" /> inside its extensionElements, got:\n${taskBlock}`,
+  );
+  // The marker is a SIBLING of the dispatch verb, which stays (per #464): both must be present.
+  assert(/<zeebe:taskDefinition type="senior:feature" \/>/.test(ext), "the dispatch verb stays alongside the marker");
+  // And the CANONICAL union scanner — the one the repo-wide guard applies — finds NO unmarked agent
+  // task in the whole compiled document (it keys an agent by its colon-form type, which every compiled
+  // agent cell carries; a connector/wait/host task is not colon-form and is correctly ignored).
+  assertEquals(missingExternalMarkerAgentTaskTypes(r.bpmn), []);
+});
+
+test("#884 agentDefinition: EVERY agent cell in a multi-agent graph is marked (not just the first)", async () => {
+  // A marker emitted once (or only on a specific shape) would leave sibling agent cells transcript-less
+  // — the 269 failed creates on omarchy came from several processes. Compile a graph whose agent nodes
+  // differ (distinct job types, one with a repo spec + emits, one bare) and assert EVERY compiled
+  // `<el>_task` service task carries the marker inside its own extensionElements.
+  const r = await compileOk({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", repository: "nanobpm/nano-workforce", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+      { id: "ship", kind: "agent", agent: { jobType: "senior:trial-merge", prompt: "merge it" } },
+    ],
+    edges: [
+      { from: "impl", to: "review" },
+      { from: "review", to: "ship" },
+    ],
+  });
+  const taskBlocks = [...r.bpmn.matchAll(/<bpmn:serviceTask id="(n\d+_task)"[\s\S]*?<\/bpmn:serviceTask>/g)];
+  assertEquals(taskBlocks.length, 3, "all three agent nodes compile to an inner service task");
+  for (const [block, id] of taskBlocks) {
+    const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(block)?.[0] ?? "";
+    assert(
+      /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+      `agent cell ${id} is missing <zeebe:agentDefinition agentType="external" /> in its extensionElements`,
+    );
+  }
+});
+
+test("#884 prompt-less: a compiled agent cell carries NO base-prompt link (Option (a))", async () => {
+  // The resolved "Decide" half of #884 (Option (a), PR #886 review): a compiled agent cell is
+  // deliberately prompt-LESS. The hand-authored process prompts (`prompts/feature.md`, …) are
+  // process-specific contracts — they require process variables (`variables.task`/`variables.issue`)
+  // and a `feat/<task.id>` branch the generic compiled cell never supplies (it seeds only
+  // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776) — so linking
+  // one hands the cell instructions referencing missing inputs and a conflicting branch. The cell is
+  // steered by its per-node `appendPrompt` alone; the marker alone fixes the createAgentInstance
+  // failure. Pin that NO compiled agent cell emits a prompt `linkedResource` — for a mapped-looking
+  // type, a bespoke type, AND a prototype-chain jobType (which must never resolve to a bogus link).
+  for (const jobType of ["senior:feature", "senior:pr-review", "senior:no-such-prompt", "constructor", "__proto__", "toString"]) {
+    const r = await compileOk({ nodes: [{ id: "p", kind: "agent", agent: { jobType } }], edges: [] });
+    assert(
+      !r.bpmn.includes('linkName="prompt"'),
+      `compiled agent cell ${JSON.stringify(jobType)} must link NO base prompt (prompt-less, Option (a)), got:\n${
+        r.bpmn.split("\n").filter((l) => l.includes("linkedResource")).join("\n")
+      }`,
+    );
+  }
+});
+
 test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", async () => {
   const r = await compileOk(RELEASE_RUNBOOK);
   // `publish.resolvedArtifact -> consume`: the connector subProcess receives the human's emitted fact as

package/app/deliveryGraphCompiler.ts

@@ -1931,7 +1931,7 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>, displ
       // be a leak here), but the `descriptor` is embedded by `serviceBodyLines` into the operator-visible
       // timeout / producer-contract escalation FEEL `prompt` — so it takes the SAME display redaction
       // `nodeDisplay` applies, never the raw value (issue #778 review — thread deliveryGraphCompiler.ts:1606).
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits, undefined);
     }
     case "connector": {
       // TRIM the target before building the escalation descriptor — `nodeDisplay` and the connector
@@ -2113,6 +2113,27 @@ function serviceBodyLines(
   const taskExt = [
     "        <bpmn:extensionElements>",
     `          <zeebe:taskDefinition ${taskDefAttr} />`,
+    // Issue #884: an `agent` cell MUST carry the engine-native AgentTask marker
+    // (`<zeebe:agentDefinition agentType="external"/>`, the `agentTask.agentDefinition` contract —
+    // issue #745) INSIDE its extensionElements, as a sibling of the dispatch verb. Without it the
+    // engine refuses to attach an AgentInstance to the element (`createAgentInstance failed — … has
+    // no agentDefinition`), so every delivery-graph agent run persisted NO durable agentic
+    // transcript (269 failed creates on omarchy). The hand-authored `senior:*` tasks all declare it
+    // (guarded by `agent-marker.test.ts`); the compiler emits it on EVERY agent cell it generates —
+    // the defect class is "every agent service task the app generates". A `connector` delegates to a
+    // HOST worker (`pr.delivery-connector`), not an external agent, so it is NOT marked.
+    ...(kind === "agent" ? ['          <zeebe:agentDefinition agentType="external" />'] : []),
+    // Issue #884 (the "Decide" half — resolved Option (a), PR #886 review): an agent cell carries ONLY
+    // the marker above and NO base-prompt `linkedResource`. The hand-authored process prompts
+    // (`prompts/feature.md`, `prompts/review-round.md`, …) are PROCESS-specific contracts, not generic
+    // cell contracts — they require process variables (`variables.task`/`variables.issue`) and a branch
+    // (`feat/<task.id>`) the generic compiled cell never supplies (it seeds only
+    // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776). Linking one
+    // would hand every compiled cell instructions referencing missing inputs and a conflicting branch.
+    // The cell is therefore deliberately prompt-LESS: the per-node `appendPrompt` FEEL (runner-seeded
+    // from `node.agent.prompt` + the emit/producer contracts) is its sole steering channel, matching the
+    // historically-intentional design (`deliveryRunner.ts` — "the delivery agent node carries no
+    // base-prompt resource"). The marker alone is what fixes the #884 `createAgentInstance` failure.
     ...(taskProps.length > 0 ? ["          <zeebe:properties>", ...taskProps, "          </zeebe:properties>"] : []),
     ...taskHeaders,
     "          <zeebe:ioMapping>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.201.3",
+  "version": "0.201.4",
   "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",
@@ -37,6 +37,7 @@
     "typecheck": "tsc --noEmit",
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
+    "check:agent-definitions": "node --experimental-strip-types scripts/check-agent-definitions.ts",
     "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
     "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
     "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",

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

@@ -0,0 +1,126 @@
+// Red/green coverage for the agent-definition repo-wide guard (scripts/check-agent-definitions.ts,
+// issue #884). The gate fails the build when any `senior:*` agent service task — hand-authored in
+// `resources/processes/*.bpmn` OR produced by the delivery-graph compiler — lacks the engine-native
+// `<zeebe:agentDefinition agentType="external" />` marker (the omission that left every delivery-graph
+// agent run without a durable transcript). These cases assert the scanner wiring flags an unmarked
+// prompt-bearing task and that the gate's compiled-output half sees a real compiled agent cell.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import {
+  agentTaskTypesMissingExternalMarker,
+  externalAgentTaskTypesMissingMarker,
+} from "../app/agentic/vocab/job-types.ts";
+import { checkAuthoredProcesses, checkCompiledOutput } from "./check-agent-definitions.ts";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+test("check-agent-definitions: the canonical scanner flags an unmarked prompt-bearing senior:* task", () => {
+  // The gate's red path rests entirely on the canonical scanner — pin that wiring here so the gate
+  // can never rot into a vacuous green (a scanner that stopped flagging would pass every corpus).
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), ["senior:feature"]);
+});
+
+test("check-agent-definitions: the hand-authored corpus passes (every senior:* task is marked)", () => {
+  const r = checkAuthoredProcesses();
+  assert(r.ok, `expected the authored corpus to pass, got ${JSON.stringify(r.errors)}`);
+  // Sanity: the corpus really does declare agent tasks (the guard is not vacuously green).
+  assert(r.agentTypes.length > 0, "the authored corpus declares prompt-bearing senior:* agent tasks");
+  assert(r.agentTypes.includes("senior:feature"), "senior:feature is among the scanned agent types");
+});
+
+test("check-agent-definitions: the compiled-output half sees a real compiled agent cell and finds it marked", async () => {
+  const r = await checkCompiledOutput();
+  assert(r.ok, `expected the compiled output to pass, got ${JSON.stringify(r.errors)}`);
+  // Every compiled agent cell is prompt-LESS (Option (a)), so it is the type-keyed half of the union
+  // scanner (keyed by the `<rank>:<task>` colon-form type) that sees them. The probe's agent types are
+  // derived by that same grammar — assert the cells really compiled (the scan is not vacuously green).
+  assert(r.agentTypes.length > 0, "the compiled probe declares senior:* agent cells");
+  assert(r.agentTypes.includes("senior:feature"), "the compiled senior:feature cell is scanned");
+});
+
+test("check-agent-definitions: the compiled probe includes a prompt-LESS agent cell, and it is marked", async () => {
+  // Every compiled agent cell is deliberately prompt-less (the resolved #884 "Decide", Option (a)), so
+  // the prompt-keyed scanner never sees it — the gate must probe one and assert its marker with the
+  // type-keyed scan, or a compiler regression that drops the marker on exactly those cells reports ok
+  // (the false-negative path from the PR #886 review).
+  const r = await checkCompiledOutput();
+  assert(r.ok, `expected the compiled output to pass, got ${JSON.stringify(r.errors)}`);
+  assert(
+    r.agentTypes.includes("senior:bespoke-promptless"),
+    `the compiled probe includes a prompt-less agent cell, got [${r.agentTypes.join(", ")}]`,
+  );
+});
+
+test("check-agent-definitions: the type-keyed scanner flags a prompt-less compiled cell that lost its marker", () => {
+  // Pin the false-negative shape the review cited: a prompt-less agent task with NO marker. The
+  // prompt-keyed scan reports nothing (it cannot see the block); the type-keyed scan must flag it.
+  const xml = `
+    <bpmn:serviceTask id="n0_task">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke-promptless" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(agentTaskTypesMissingExternalMarker(xml), []);
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke-promptless"]);
+});
+
+test("check-agent-definitions: the authored half unions BOTH scanners — a prompt-less + marker-less senior:* task fails", () => {
+  // The authored-process half must hold the SAME "every senior:* task carries the marker" invariant
+  // the compiled half does (PR #886 review). A hand-authored senior:* task that loses BOTH its prompt
+  // link and its marker is invisible to the prompt-keyed scanner, so a prompt-keyed-only authored gate
+  // reports ok — the false-negative the compiled half already closes. Inject a doc with exactly that
+  // shape and assert the gate flags it (via the type-keyed half of the union).
+  const bad = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke-promptless" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  const r = checkAuthoredProcesses([{ file: "bad.bpmn", xml: bad }]);
+  assert(!r.ok, "a prompt-less + marker-less senior:* authored task must fail the gate");
+  assert(
+    r.errors.some((e) => e.includes("bad.bpmn") && e.includes("senior:bespoke-promptless")),
+    `the error names the unmarked prompt-less task, got ${JSON.stringify(r.errors)}`,
+  );
+});
+
+test("check-agent-definitions: the authored half still flags a prompt-BEARING task that lost its marker", () => {
+  const bad = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  const r = checkAuthoredProcesses([{ file: "bad.bpmn", xml: bad }]);
+  assert(!r.ok, "a prompt-bearing senior:* authored task without a marker must fail the gate");
+  assert(
+    r.errors.some((e) => e.includes("bad.bpmn") && e.includes("senior:feature")),
+    `the error names the unmarked prompt-bearing task, got ${JSON.stringify(r.errors)}`,
+  );
+});
+
+test("check-agent-definitions: AGENTS.md documents the check:agent-definitions CI gate", () => {
+  // Advisory (PR #886 review): adding the `check:agent-definitions` CI command left the contributor
+  // guide's "Runtime & CI gates" list stale — AGENTS.md tells contributors how to match CI locally
+  // but did not name the new gate. Pin the doc so the gate cannot silently drop out of the guide.
+  const agents = readFileSync(join(ROOT, "AGENTS.md"), "utf8");
+  assert(
+    agents.includes("check:agent-definitions"),
+    "AGENTS.md must document the check:agent-definitions gate in its Runtime & CI gates list",
+  );
+});

package/scripts/check-agent-definitions.ts

@@ -0,0 +1,191 @@
+// check-agent-definitions — repo-wide CI gate (issue #884) for the engine-native AgentTask marker:
+// EVERY `senior:*` agent service task the app deploys must carry
+// `<zeebe:agentDefinition agentType="external" />` INSIDE its `<bpmn:extensionElements>`, as a sibling
+// of its `<zeebe:taskDefinition type="senior:*"/>` dispatch verb. Without the marker the engine refuses
+// to attach an AgentInstance to the element (`createAgentInstance failed — … has no agentDefinition`),
+// so the agent run persists NO durable agentic transcript — the exact #884 failure (269 failed creates
+// on omarchy across three compiled delivery-graph processes).
+//
+// The defect CLASS is "every agent service task the app generates", and there are TWO producers.
+// Both are checked against the SAME union invariant `missingExternalMarkerAgentTaskTypes`
+// (`app/agentic/vocab/job-types.ts`) — the union of the two marker scanners, each of which alone has
+// a blind spot (PR #886 review):
+//
+//   • the prompt-keyed `agentTaskTypesMissingExternalMarker` keys a task as an AGENT by its
+//     `<zeebe:linkedResource … linkName="prompt">` (the base-prompt link a fleet agent task carries),
+//     so it cannot see a DELIBERATELY prompt-less agent cell; and
+//   • the type-keyed `externalAgentTaskTypesMissingMarker` keys it by its `<rank>:<task>` colon-form
+//     type ALONE, covering the prompt-less case.
+//
+// Scanning a corpus with only ONE leaves the other's blind spot open — a `senior:*` task that loses
+// BOTH its prompt link and its marker would pass a prompt-keyed-only gate. The union closes that for
+// every producer:
+//
+//   1. The HAND-AUTHORED corpus — `resources/processes/**.bpmn`. `checkAuthoredProcesses` runs the
+//      union over every deployed model. This is the SAME invariant the `agent-marker.test.ts` unit
+//      guard rests on — kept here as a standalone, fast CI gate (alongside `check:prompts`) so the
+//      corpus invariant is visible as its own check, not only inside the test suite.
+//
+//   2. The delivery-graph COMPILER (`app/deliveryGraphCompiler.ts`) — the producer #884 caught. Its
+//      compiled cells carried NO marker AND no prompt link, so they were invisible to the
+//      prompt-link-keyed scanner. The compiler now emits the marker on EVERY `agent` cell — and, per
+//      the resolved "Decide" half of #884 (Option (a), PR #886 review), NO base-prompt link: the
+//      hand-authored process prompts are process-specific contracts (they require process variables
+//      and a `feat/<task.id>` branch the generic compiled cell never supplies), so a compiled cell is
+//      deliberately prompt-LESS and steered by its per-node `appendPrompt` alone. This gate compiles a
+//      representative graph — including a prompt-less probe cell — and runs the SAME union over the
+//      OUTPUT, so a marker regression on a prompt-less cell cannot hide behind the prompt-keyed scan's
+//      blind spot.
+//
+// In the hand-authored corpus a `senior:*` task is identified by its prompt link OR its colon-form
+// type; a plain host job (`pr.finalize`, dot-form, no prompt link) is correctly out of scope. The
+// scanners are the ONE canonical implementations — this gate DERIVES all its halves from them rather
+// than re-implementing a second, driftable regex.
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  missingExternalMarkerAgentTaskTypes,
+  promptBearingTaskTypes,
+} from "../app/agentic/vocab/job-types.ts";
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PROCESSES_DIR = join(ROOT, "resources/processes");
+
+// The agent job type the compiled-output probe uses for a cell with NO base-prompt link (every
+// compiled agent cell is prompt-less per the resolved #884 "Decide" — Option (a)). It is colon-form
+// (`<rank>:<task>`) so the type-keyed marker scanner keys it as an agent — the exact prompt-less shape
+// the prompt-keyed scanner cannot see (PR #886 review).
+const PROMPTLESS_PROBE_JOB_TYPE = "senior:bespoke-promptless";
+
+// urban deploys `resources/` recursively (every file at any depth), so a process model added under a
+// subdirectory would still deploy — walk recursively here too, or the guard would miss it and let an
+// unmarked agent task slip through. Mirrors `agent-marker.test.ts`'s `bpmnFiles()`.
+function bpmnFiles(): string[] {
+  const walk = (dir: string): string[] =>
+    readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) return walk(full);
+      return entry.name.endsWith(".bpmn") ? [relative(PROCESSES_DIR, full)] : [];
+    });
+  return walk(PROCESSES_DIR).sort();
+}
+
+export interface AgentDefinitionCheckResult {
+  ok: boolean;
+  errors: string[];
+  /** prompt-bearing agent job types found across the hand-authored corpus (for the CLI summary). */
+  agentTypes: string[];
+}
+
+/** One hand-authored BPMN document to scan: its path (relative to `resources/processes`) and XML. */
+export interface AuthoredDoc {
+  file: string;
+  xml: string;
+}
+
+/** Read the hand-authored deployed corpus (`resources/processes/**.bpmn`) off disk. */
+function authoredDocs(): AuthoredDoc[] {
+  return bpmnFiles().map((file) => ({ file, xml: readFileSync(join(PROCESSES_DIR, file), "utf8") }));
+}
+
+/**
+ * Scan the HAND-AUTHORED deployed corpus (`resources/processes/**.bpmn`). `docs` is injectable so the
+ * red-path test can feed a drifting document without writing to the corpus; it defaults to the real
+ * on-disk corpus. Every agent task — prompt-bearing OR deliberately prompt-less — must carry the
+ * external marker, so this holds the SAME union invariant as the compiled half (PR #886 review).
+ */
+export function checkAuthoredProcesses(docs: readonly AuthoredDoc[] = authoredDocs()): AgentDefinitionCheckResult {
+  const errors: string[] = [];
+  const agentTypes = new Set<string>();
+  for (const { file, xml } of docs) {
+    for (const t of promptBearingTaskTypes(xml)) agentTypes.add(t);
+    const missing = missingExternalMarkerAgentTaskTypes(xml);
+    if (missing.length > 0) {
+      errors.push(
+        `resources/processes/${file}: agent task(s) missing <zeebe:agentDefinition agentType="external" /> — ` +
+          `${missing.join(", ")} (every senior:* agent task must carry the marker so the engine mints a ` +
+          `durable AgentInstance/transcript for it, issue #745/#884)`,
+      );
+    }
+  }
+  if (agentTypes.size === 0) {
+    errors.push("no prompt-bearing agent task found in resources/processes — the guard would be vacuously green");
+  }
+  return { ok: errors.length === 0, errors, agentTypes: [...agentTypes].sort() };
+}
+
+/** Scan the delivery-graph COMPILER's output — the second producer of agent service tasks (#884). */
+export async function checkCompiledOutput(): Promise<AgentDefinitionCheckResult> {
+  const errors: string[] = [];
+  const r = await compileDeliveryGraph({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+      // A prompt-LESS agent cell (every compiled agent cell is prompt-less per the resolved #884
+      // "Decide" — Option (a)). The prompt-keyed scanner never sees it, so probe the shape to keep the
+      // type-keyed marker scan below covering it (PR #886 review).
+      { id: "bespoke", kind: "agent", agent: { jobType: PROMPTLESS_PROBE_JOB_TYPE } },
+    ],
+    edges: [
+      { from: "impl", to: "review" },
+      { from: "review", to: "bespoke" },
+    ],
+  });
+  if (!r.ok) {
+    return { ok: false, errors: [`delivery-graph compiler rejected the probe graph: ${JSON.stringify(r.errors)}`], agentTypes: [] };
+  }
+  // Inspect EVERY generated agent service task for the marker via the single union invariant
+  // (`missingExternalMarkerAgentTaskTypes`). Every compiled agent cell is prompt-LESS (Option (a)), so
+  // it is the type-keyed half of the union (keyed by the `<rank>:<task>` colon-form type alone) that
+  // sees these cells — a compiler regression that drops the marker on a prompt-less cell cannot hide
+  // behind the prompt-keyed scan's blind spot (PR #886 review).
+  const missing = missingExternalMarkerAgentTaskTypes(r.bpmn);
+  if (missing.length > 0) {
+    errors.push(
+      `compiled delivery-graph agent cell(s) missing <zeebe:agentDefinition agentType="external" /> — ` +
+        `${missing.join(", ")} (the compiler must emit the marker on EVERY agent cell, including a ` +
+        "prompt-less one, issue #884)",
+    );
+  }
+  // Sanity: the prompt-less probe cell really compiled into the output (the type-keyed scan is not
+  // vacuously green over a graph that lost its prompt-less cell).
+  if (!r.bpmn.includes(`type="${PROMPTLESS_PROBE_JOB_TYPE}"`)) {
+    errors.push(
+      `the compiled probe graph lost its prompt-less agent cell ${PROMPTLESS_PROBE_JOB_TYPE} — ` +
+        "the type-keyed marker scan would be vacuously green over it",
+    );
+  }
+  // The agent job types this probe compiled (for the CLI summary) — derived by the SAME type-keyed
+  // grammar the marker scanner uses, since the cells are prompt-less (a prompt-keyed list is empty).
+  const agentTypes = [
+    ...new Set(
+      [...r.bpmn.matchAll(/<(?:\w+:)?taskDefinition\b[^>]*\btype="([^"]*)"/g)]
+        .map((m) => m[1])
+        .filter((t) => t.startsWith("senior:")),
+    ),
+  ];
+  return { ok: errors.length === 0, errors, agentTypes: agentTypes.sort() };
+}
+
+async function main(): Promise<void> {
+  const authored = checkAuthoredProcesses();
+  const compiled = await checkCompiledOutput();
+  const errors = [...authored.errors, ...compiled.errors];
+  if (errors.length > 0) {
+    console.error(`✖ agent-definition check failed (${errors.length} problem(s)):`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  console.log(
+    `✔ every senior:* agent service task carries <zeebe:agentDefinition agentType="external" /> ` +
+      `(authored: ${authored.agentTypes.length} type(s) [${authored.agentTypes.join(", ")}]; ` +
+      `compiled: ${compiled.agentTypes.length} type(s) [${compiled.agentTypes.join(", ")}])`,
+  );
+}
+
+// CLI: check the repo rooted at the package root. Exit non-zero (fail CI) on any problem.
+if (import.meta.main) {
+  await main();
+}