@nanobpm/nano-workforce 0.201.3 → 0.201.5

package/resources/processes/merge-loop.bpmn

@@ -362,7 +362,46 @@
           </zeebe:properties>
           <zeebe:ioMapping>
             <zeebe:input source="=(if (failingChecksList = null or failingChecksList = &#34;&#34;) then &#34;&#34; else &#34;&#10;&#10;Failing checks to make green:&#10;&#34; + failingChecksList) + (if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
-            <zeebe:output source="=ciFixRound + 1" target="ciFixRound" />
+            <zeebe:input source="=ciFixRound" target="guardCiFixRound" />
+            <zeebe:input source="=ciFixMax" target="guardCiFixMax" />
+            <zeebe:input source="=rebaseRound" target="guardRebaseRound" />
+            <zeebe:input source="=rebaseMax" target="guardRebaseMax" />
+            <zeebe:input source="=mergeRetryRound" target="guardMergeRetryRound" />
+            <zeebe:input source="=mergeRetryMax" target="guardMergeRetryMax" />
+            <zeebe:input source="=mergeStallRounds" target="guardMergeStallRounds" />
+            <zeebe:input source="=mergeStallMax" target="guardMergeStallMax" />
+            <zeebe:input source="=prKey" target="guardPrKey" />
+            <zeebe:input source="=repo" target="guardRepo" />
+            <zeebe:input source="=prNumber" target="guardPrNumber" />
+            <zeebe:input source="=prUrl" target="guardPrUrl" />
+            <zeebe:input source="=ciBlockedReconciled" target="guardCiBlockedReconciled" />
+            <zeebe:input source="=agentSlaTimeout" target="guardAgentSlaTimeout" />
+            <zeebe:input source="=landedWaitTimeout" target="guardLandedWaitTimeout" />
+            <zeebe:input source="=mergeableWaitTimeout" target="guardMergeableWaitTimeout" />
+            <zeebe:input source="=mergeableRepollInterval" target="guardMergeableRepollInterval" />
+            <zeebe:input source="=round" target="guardRound" />
+            <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
+            <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
+            <zeebe:output source="=guardCiFixRound + 1" target="ciFixRound" />
+            <zeebe:output source="=guardCiFixMax" target="ciFixMax" />
+            <zeebe:output source="=guardRebaseRound" target="rebaseRound" />
+            <zeebe:output source="=guardRebaseMax" target="rebaseMax" />
+            <zeebe:output source="=guardMergeRetryRound" target="mergeRetryRound" />
+            <zeebe:output source="=guardMergeRetryMax" target="mergeRetryMax" />
+            <zeebe:output source="=guardMergeStallRounds" target="mergeStallRounds" />
+            <zeebe:output source="=guardMergeStallMax" target="mergeStallMax" />
+            <zeebe:output source="=guardPrKey" target="prKey" />
+            <zeebe:output source="=guardRepo" target="repo" />
+            <zeebe:output source="=guardPrNumber" target="prNumber" />
+            <zeebe:output source="=guardPrUrl" target="prUrl" />
+            <zeebe:output source="=guardCiBlockedReconciled" target="ciBlockedReconciled" />
+            <zeebe:output source="=guardAgentSlaTimeout" target="agentSlaTimeout" />
+            <zeebe:output source="=guardLandedWaitTimeout" target="landedWaitTimeout" />
+            <zeebe:output source="=guardMergeableWaitTimeout" target="mergeableWaitTimeout" />
+            <zeebe:output source="=guardMergeableRepollInterval" target="mergeableRepollInterval" />
+            <zeebe:output source="=guardRound" target="round" />
+            <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
+            <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
           </zeebe:ioMapping>
         </bpmn:extensionElements>
         <bpmn:incoming>f_ci_s0</bpmn:incoming>
@@ -524,7 +563,46 @@
           </zeebe:properties>
           <zeebe:ioMapping>
             <zeebe:input source="=(if (abandonBrief = null) then &#34;&#34; else abandonBrief)" target="appendPrompt" />
-            <zeebe:output source="=rebaseRound + 1" target="rebaseRound" />
+            <zeebe:input source="=ciFixRound" target="guardCiFixRound" />
+            <zeebe:input source="=ciFixMax" target="guardCiFixMax" />
+            <zeebe:input source="=rebaseRound" target="guardRebaseRound" />
+            <zeebe:input source="=rebaseMax" target="guardRebaseMax" />
+            <zeebe:input source="=mergeRetryRound" target="guardMergeRetryRound" />
+            <zeebe:input source="=mergeRetryMax" target="guardMergeRetryMax" />
+            <zeebe:input source="=mergeStallRounds" target="guardMergeStallRounds" />
+            <zeebe:input source="=mergeStallMax" target="guardMergeStallMax" />
+            <zeebe:input source="=prKey" target="guardPrKey" />
+            <zeebe:input source="=repo" target="guardRepo" />
+            <zeebe:input source="=prNumber" target="guardPrNumber" />
+            <zeebe:input source="=prUrl" target="guardPrUrl" />
+            <zeebe:input source="=ciBlockedReconciled" target="guardCiBlockedReconciled" />
+            <zeebe:input source="=agentSlaTimeout" target="guardAgentSlaTimeout" />
+            <zeebe:input source="=landedWaitTimeout" target="guardLandedWaitTimeout" />
+            <zeebe:input source="=mergeableWaitTimeout" target="guardMergeableWaitTimeout" />
+            <zeebe:input source="=mergeableRepollInterval" target="guardMergeableRepollInterval" />
+            <zeebe:input source="=round" target="guardRound" />
+            <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
+            <zeebe:input source="=abandonBrief" target="guardAbandonBrief" />
+            <zeebe:output source="=guardRebaseRound + 1" target="rebaseRound" />
+            <zeebe:output source="=guardCiFixRound" target="ciFixRound" />
+            <zeebe:output source="=guardCiFixMax" target="ciFixMax" />
+            <zeebe:output source="=guardRebaseMax" target="rebaseMax" />
+            <zeebe:output source="=guardMergeRetryRound" target="mergeRetryRound" />
+            <zeebe:output source="=guardMergeRetryMax" target="mergeRetryMax" />
+            <zeebe:output source="=guardMergeStallRounds" target="mergeStallRounds" />
+            <zeebe:output source="=guardMergeStallMax" target="mergeStallMax" />
+            <zeebe:output source="=guardPrKey" target="prKey" />
+            <zeebe:output source="=guardRepo" target="repo" />
+            <zeebe:output source="=guardPrNumber" target="prNumber" />
+            <zeebe:output source="=guardPrUrl" target="prUrl" />
+            <zeebe:output source="=guardCiBlockedReconciled" target="ciBlockedReconciled" />
+            <zeebe:output source="=guardAgentSlaTimeout" target="agentSlaTimeout" />
+            <zeebe:output source="=guardLandedWaitTimeout" target="landedWaitTimeout" />
+            <zeebe:output source="=guardMergeableWaitTimeout" target="mergeableWaitTimeout" />
+            <zeebe:output source="=guardMergeableRepollInterval" target="mergeableRepollInterval" />
+            <zeebe:output source="=guardRound" target="round" />
+            <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
+            <zeebe:output source="=guardAbandonBrief" target="abandonBrief" />
           </zeebe:ioMapping>
         </bpmn:extensionElements>
         <bpmn:incoming>f_reb_s0</bpmn:incoming>

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();
+}