@nanobpm/nano-workforce 0.201.2 → 0.201.4

package/app/plan.test.ts

@@ -244,10 +244,13 @@ test("startPlan pins the base branch: persisted on the row + seeded as baseBranc
   // Host-git provisioning (#684): the whole-epic repository envelope so each slice's implementation
   // agent gets an isolated clone. The epic seed checks out the BASE branch (`ref`) — each slice's
   // `feat/<task.id>` branch differs per MI child, so NO `branch.create` here (the agent branches).
-  const repo = seen["io.nanobpm.agentTask"].repository;
+  const ns = seen["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.url, "https://github.com/owner/repo.git");
   assertEquals(repo.ref, "epic/agent-protocol");
-  assertEquals("branch" in repo, false);
+  // No isolation branch on the epic seed — `branch` is a top-level sibling of `repository` (#882),
+  // and it is omitted entirely here.
+  assertEquals("branch" in ns, false);
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
 });

package/app/repoEnvelope.test.ts

@@ -0,0 +1,139 @@
+// Contract test for the agent-task repository envelope (issue #882): the producer
+// (`app/repoEnvelope.ts`) and the consumer (the c8ctl nano worker harness's
+// `normalizeTaskEnvelope`, c8ctl-plugin.js) must agree on WHERE the deterministic
+// `branch.create` lives. The harness reads it from the TOP LEVEL of the envelope
+// (`raw.branch`), NOT nested under `repository`. The producer once nested it under
+// `repository.branch` — a shape the consumer never reads — so `branch.create`
+// silently never took effect (retries couldn't resume their WIP checkpoint, pushes
+// were refused off the work branch; nanobpm/nano-bpm#1344). This is the
+// two-sides-of-one-contract drift #227 guards against, so this test round-trips the
+// emitted envelope through a faithful mirror of the harness's normalizer shape and
+// asserts the consumer actually recovers `branch.create` — pinning producer and
+// consumer together so they cannot drift again.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, repoEnvelopeVars } from "./repoEnvelope.ts";
+
+// ─── A faithful mirror of the harness's consumer shape ───────────────────────────────
+// These mirror the EXACT semantics of c8ctl-plugin-nano `normalizeTaskEnvelope`
+// (c8ctl-plugin.js): `collectEnvelopeFrom` reassembles the reserved
+// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened
+// dotpath keys, `deepMerge`s the two sources, and `normalizeTaskEnvelope` then reads
+// `branch` from the TOP LEVEL of the merged envelope (`isPlainObject(raw.branch)`),
+// NOT from `raw.repository.branch`. Keeping this mirror in lock-step with the harness
+// is the point of the test: if the producer emits a shape the consumer doesn't read,
+// the round-trip below drops `branch.create` and fails.
+const AGENT_TASK_NS = "io.nanobpm.agentTask";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+function deepMerge(base: unknown, over: unknown): unknown {
+  if (!isPlainObject(base)) return isPlainObject(over) ? deepMerge({}, over) : over;
+  const out: Record<string, unknown> = { ...base };
+  if (!isPlainObject(over)) return out;
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function setPath(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  let cur = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const k = path[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k] as Record<string, unknown>;
+  }
+  cur[path[path.length - 1]] = value;
+}
+
+/** Mirror of the harness's `collectEnvelopeFrom`: reassemble the reserved namespace from a
+ * whole-object/JSON value AND flattened dotpath keys (element templates / task headers emit the
+ * latter). */
+function collectEnvelopeFrom(source: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!isPlainObject(source)) return out;
+  const whole = source[AGENT_TASK_NS];
+  if (whole != null) {
+    let val: unknown = whole;
+    if (typeof whole === "string") {
+      try {
+        val = JSON.parse(whole);
+      } catch {
+        val = undefined;
+      }
+    }
+    if (isPlainObject(val)) Object.assign(out, deepMerge(out, val));
+  }
+  const prefix = `${AGENT_TASK_NS}.`;
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!rest) continue;
+    setPath(out, rest.split("."), value);
+  }
+  return out;
+}
+
+/** Mirror of the harness's `normalizeTaskEnvelope` branch slice: it reads `branch` from the TOP
+ * LEVEL of the merged envelope — `isPlainObject(raw.branch) ? raw.branch : {}` — never from
+ * `raw.repository.branch`. Returns the consumer's recovered `branch.create` (undefined when the
+ * producer put it somewhere the consumer doesn't look). */
+function harnessReadsBranchCreate(customHeaders: Record<string, unknown>, variables: Record<string, unknown>): string | undefined {
+  const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables)) as Record<string, unknown>;
+  const branch = isPlainObject(raw.branch) ? raw.branch : {};
+  const create = branch.create;
+  return create == null ? undefined : String(create);
+}
+
+// ─── The round-trip contract ──────────────────────────────────────────────────────────
+
+test("contract: repoEnvelopeVars emits branch.create where the harness reads it (envelope TOP LEVEL, not repository.branch) (#882)", () => {
+  // The pre-PR implementation path: a deterministic feat/<task.id> branch the harness must cut.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7");
+  // Round-trip the emitted PROCESS-VARIABLE envelope through the harness normalizer shape.
+  const recovered = harnessReadsBranchCreate({}, vars);
+  assertEquals(
+    recovered,
+    "feat/issue-7",
+    "the harness reads branch.create from the envelope top level — nesting it under repository.branch drops it",
+  );
+});
+
+test("contract: repoEnvelopeVars PR path (ref == create == head) round-trips branch.create to the harness (#882/#231)", () => {
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/issue-12");
+});
+
+test("contract: agentNodeRepoEnvelope round-trips the deterministic per-node branch through the harness (#882/#776)", () => {
+  const vars = agentNodeRepoEnvelope("acme/one", "main", "feat/n1");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/n1");
+});
+
+test("contract: the FLATTENED per-cell task headers round-trip branch.create to the harness (#882/#739)", () => {
+  // The delivery-graph path delivers the envelope as FLAT dotted task headers, which the harness
+  // reassembles via collectEnvelopeFrom's dotpath branch. Round-trip the flattened headers through
+  // the same normalizer shape so the header channel can't drift from the consumer either.
+  const envelope = agentNodeRepoEnvelope("acme/one", "main", "feat/open-b");
+  const flat = flattenAgentTaskEnvelope(envelope);
+  // The flattened key must be the TOP-LEVEL `branch.create`, NOT `repository.branch.create`.
+  assert(
+    "io.nanobpm.agentTask.branch.create" in flat,
+    `expected a top-level io.nanobpm.agentTask.branch.create header, got ${JSON.stringify(Object.keys(flat))}`,
+  );
+  assert(
+    !("io.nanobpm.agentTask.repository.branch.create" in flat),
+    "branch.create must NOT be nested under repository — the harness never reads it there",
+  );
+  const recovered = harnessReadsBranchCreate(flat, {});
+  assertEquals(recovered, "feat/open-b", "the harness reassembles the flattened header into branch.create");
+});
+
+test("contract: an envelope with NO branch round-trips to undefined (the consumer's default), never a bogus value (#882)", () => {
+  // A blank branchCreate omits the key entirely; the harness must then see no branch.create.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, null);
+  assertEquals(harnessReadsBranchCreate({}, vars), undefined);
+});

package/app/repoEnvelope.ts

@@ -187,19 +187,25 @@ export function repoEnvelopeVars(
         // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
         // when the PR has no durable push-checkpoint yet.
         ...(isCommitSha(commitSha) ? { sha: commitSha } : {}),
-        // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
-        // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
-        // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
-        // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
-        // hand — making the isolated clone land on the right branch deterministically across a resume.
-        // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
-        // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
-        // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
-        // head branch. Only a blank/omitted value drops the key.
-        ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
-          ? { branch: { create: branchCreate.trim() } }
-          : {}),
       },
+      // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
+      // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
+      // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
+      // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
+      // hand — making the isolated clone land on the right branch deterministically across a resume.
+      // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
+      // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
+      // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
+      // head branch. Only a blank/omitted value drops the key.
+      //
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root (`isPlainObject(raw.branch)`), NOT from
+      // `repository.branch`. Nesting it under `repository` was the two-sides-of-one-contract drift
+      // (#227) that left `branch.create` silently unread (retries couldn't resume, pushes were
+      // refused — nanobpm/nano-bpm#1344).
+      ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
+        ? { branch: { create: branchCreate.trim() } }
+        : {}),
       // Repo-provisioning auth gate (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the
       // git credential (GITHUB_TOKEN, or the `gh` default when it's absent) for repository
       // provisioning when `task.allowPr` is truthy — `resolveJobSecrets` pulls the token behind that
@@ -251,10 +257,13 @@ export function agentNodeRepoEnvelope(repo: string, base: string | null, branchC
         // A per-node base (declared, or defaulted from the run level) — the branch the harness cuts its
         // `feat/<node.id>` off. Omitted when unknown so the harness clones the repo's default branch.
         ...(ref ? { ref, baseRef: ref } : {}),
-        // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
-        // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
-        ...(create ? { branch: { create } } : {}),
       },
+      // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
+      // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root, NOT from `repository.branch`, so the
+      // flattened per-cell header is `io.nanobpm.agentTask.branch.create` (not `…repository.branch.create`).
+      ...(create ? { branch: { create } } : {}),
       // Repo-provisioning auth gate (issue #770): as in `repoEnvelopeVars`, a repo-backed cell must
       // opt the harness into git-credential resolution (`task.allowPr`) or the clone fails with
       // `unable to get password from user`. Emitted on every resolved cell (past the `owner/repo`

package/app/service.test.ts

@@ -1415,27 +1415,30 @@ test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` ke
 // to `ref`) so the harness commits/pushes to the PR head branch instead of cutting a throwaway
 // `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see the PR-path test below.
 test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#684)", () => {
-  const repo = (repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any)["io.nanobpm.agentTask"]
-    .repository;
+  const envelope = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any;
+  const ns = envelope["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.ref, "main", "the pre-PR envelope checks out the BASE branch as its ref");
-  assertEquals(repo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the
+  // envelope root, NOT from `repository.branch`.
+  assertEquals(ns.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  assertEquals("branch" in repo, false, "branch must NOT be nested under repository — the harness never reads it there");
   // Still branch-scoped and blobless like the PR-based envelope.
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
   // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key entirely so the
   // PR-based paths (and any caller that doesn't pre-create a branch) are unaffected.
   assertEquals(
-    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"].repository
+    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"]
       .branch.create,
     "feat/issue-9",
   );
   for (const blank of [null, undefined, "", "   "]) {
-    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"]
-      .repository;
+    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"];
     assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
   }
   // The default (4-arg) PR-based call never emits a branch.create.
-  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository, false);
+  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"], false);
 });
 
 // PR-path provisioning (jwulf/c8ctl-plugin-nano#231): the review-round / fix-ci / rebase call sites
@@ -1445,11 +1448,13 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
 // `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
 // head branch itself.
 test("repoEnvelopeVars emits branch.create = head on the PR path (ref == create == head) (#231)", () => {
-  const repo = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
+  const ns = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
     "io.nanobpm.agentTask"
-  ].repository;
+  ];
+  const repo = ns.repository;
   assertEquals(repo.ref, "feat/issue-12", "the PR-path envelope checks out the head branch");
-  assertEquals(repo.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882), read by the harness from the root.
+  assertEquals(ns.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
   // Still branch-scoped and blobless, and the base tip stays reachable for the 3-dot diff.
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
@@ -1496,9 +1501,9 @@ test("submitPr threads the resolved PR head into the envelope branch.create (#23
       url: "https://github.com/owner/repo/pull/12",
       prKey: "owner/repo#12",
     });
-    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
-    assertEquals(repo?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
-    assertEquals(repo?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
   });
 });
 
@@ -1521,9 +1526,9 @@ test("startMerge threads the resolved PR head into the envelope branch.create (#
       prKey: "owner/repo#13",
       round: 2,
     });
-    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
-    assertEquals(repo?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
-    assertEquals(repo?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
   });
 });
 

package/e2e/feature-run.e2e.ts

@@ -133,11 +133,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     // carries — proof the implement-cell agent gets an ISOLATED clone (base branch + a harness-cut
     // `feat/<task.id>`) instead of inheriting the worker's launch dir. It rides the process variable
     // all the way down through feature.bpmn's `implement` callActivity into the cell's agent job.
-    let agentRepo: any = null;
+    let agentTask: any = null;
     await withApp(
       {
         "senior:feature": (job) => {
-          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
           return { status: "opened", pr: "owner/repo#101", summary: "built it" };
         },
       },
@@ -150,10 +150,12 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         );
         assert.ok(!flows.includes("gw-converge->converge"), "the converge hand-off branch was NOT taken");
 
-        assert.ok(agentRepo, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        assert.ok(agentTask, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        const agentRepo = agentTask.repository;
         assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
         assert.equal(agentRepo.ref, "epic/e2e", "a PRE-PR job checks out the BASE branch, not a head");
-        assert.equal(agentRepo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch");
+        // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the root.
+        assert.equal(agentTask.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch");
 
         const run = await featureRow(app, featureKey);
         assert.equal(run.status, "opened", "the run settled at opened");

package/e2e/plan-fanout.e2e.ts

@@ -131,22 +131,24 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     // rides down through the wave subprocess + `implement-cell-call` callActivity into each agent job.
     // The epic seed carries the BASE branch as `ref` but NO `branch.create` — each slice's
     // `feat/<task.id>` differs per MI child, so the agent cuts its own branch inside the clone.
-    let agentRepo: any = null;
+    let agentTask: any = null;
     await withApp(
       {
         "senior:plan": singleTaskPlan,
         "senior:plan-review": approveReview,
         "senior:feature": (job) => {
-          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
           return { status: "blocked", summary: "n/a" };
         },
       },
       async ({ app }) => {
         await app.settle();
-        assert.ok(agentRepo, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        assert.ok(agentTask, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        const agentRepo = agentTask.repository;
         assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
         assert.equal(agentRepo.ref, "epic/e2e", "the epic seed checks out the BASE (integration) branch");
-        assert.equal("branch" in agentRepo, false, "the epic seed omits branch.create — the agent branches per slice");
+        // `branch` is a top-level sibling of `repository` (#882); the epic seed omits it entirely.
+        assert.equal("branch" in agentTask, false, "the epic seed omits branch.create — the agent branches per slice");
         assert.equal(agentRepo.singleBranch, true, "the blobless/single-branch monorepo shaping rides along");
         assert.equal(agentRepo.filter, "blob:none");
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.201.2",
+  "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",
+  );
+});