@nanobpm/nano-workforce 0.184.1 → 0.185.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.185.1](https://github.com/nanobpm/nano-workforce/compare/v0.185.0...v0.185.1) (2026-09-08)
+
+### Bug Fixes
+
+* **agentic:** capability probe recognises single-package v-prefixed release tags ([#765](https://github.com/nanobpm/nano-workforce/issues/765)) ([79faa67](https://github.com/nanobpm/nano-workforce/commit/79faa676f46882d4e10f3ce0bb70080f40e3e757)), closes [#764](https://github.com/nanobpm/nano-workforce/issues/764)
+
+## [0.185.0](https://github.com/nanobpm/nano-workforce/compare/v0.184.1...v0.185.0) (2026-09-08)
+
+### Features
+
+* **delivery:** auto-inject the producer-completion contract into every agent node's prompt ([#761](https://github.com/nanobpm/nano-workforce/issues/761)) ([3eb90a3](https://github.com/nanobpm/nano-workforce/commit/3eb90a3ed3bca8a5fc8cb542716f9d19fa82a541)), closes [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#551](https://github.com/nanobpm/nano-workforce/issues/551) [#506](https://github.com/nanobpm/nano-workforce/issues/506) [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#760](https://github.com/nanobpm/nano-workforce/issues/760) [#731](https://github.com/nanobpm/nano-workforce/issues/731) [#731](https://github.com/nanobpm/nano-workforce/issues/731)
+
 ## [0.184.1](https://github.com/nanobpm/nano-workforce/compare/v0.184.0...v0.184.1) (2026-09-08)
 
 ### Bug Fixes

package/app/deliveryGraphCompiler.ts

@@ -119,8 +119,11 @@ function contractEscalationTaskElement(element: string): string {
  * and escalates AT the node instead of threading an incomplete result into a downstream consumer. An
  * ABSENT/null status passes the gate (a status-less completion — an older fleet worker or a bare test
  * stub — is not itself the failure mode; the required-emit gate still catches a missing data fact).
- * Sorted for the compiler's byte-identical-output determinism. */
-const AGENT_TERMINAL_SUCCESS_STATUSES: readonly string[] = ["done", "opened", "skipped"];
+ * Sorted for the compiler's byte-identical-output determinism. Exported as the SINGLE SOURCE OF TRUTH:
+ * the compiler's contract gate reads it here, and the runner's `renderProducerContract` (#760) derives
+ * the agent-facing status vocabulary from the SAME list — changing it changes both the gate and the
+ * prompt at once, so the two representations of the producer contract can never drift. */
+export const AGENT_TERMINAL_SUCCESS_STATUSES: readonly string[] = ["done", "opened", "skipped"];
 
 /** A never-reached exhaustiveness guard: `compileNode`'s `switch` covers every allowlisted kind, so
  * the closed union narrows to `never` here. If a future kind is added to the vocabulary without a

package/app/deliveryRunner.test.ts

@@ -11,7 +11,8 @@
 // proven end-to-end in `e2e/delivery-graph.e2e.ts`.
 import { test } from "node:test";
 import { assert, assertEquals, assertRejects } from "#test-assert";
-import { prepareDeliveryGraph, renderIdempotencyPreamble, runDeliveryGraph } from "./deliveryRunner.ts";
+import { AGENT_TERMINAL_SUCCESS_STATUSES } from "./deliveryGraphCompiler.ts";
+import { prepareDeliveryGraph, renderEmitContract, renderIdempotencyPreamble, renderProducerContract, runDeliveryGraph } from "./deliveryRunner.ts";
 import { RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
@@ -76,8 +77,9 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
 
   const agent = byField((v) => v.jobType === "senior:feature");
   // Every agent node's appendPrompt is prefixed with the idempotency preflight (#551), then the
-  // authored prompt (this node declares no emits, so the emit contract adds nothing).
-  assertEquals(agent, { jobType: "senior:feature", appendPrompt: renderIdempotencyPreamble() + "un-draft + merge #B", timeout: "PT10M" });
+  // authored prompt, then the (emit-less) producer completion contract (#760) — this node declares no
+  // emits, so the emit contract adds nothing but the status block still applies.
+  assertEquals(agent, { jobType: "senior:feature", appendPrompt: renderIdempotencyPreamble() + "un-draft + merge #B" + renderEmitContract([]) + renderProducerContract([]), timeout: "PT10M" });
 
   const wait = byField((v) => "gateKey" in v);
   assertEquals(wait?.gateKey, "run-7:n3");
@@ -156,9 +158,103 @@ test("agent node classifier-emit contract (#506): a declared `emits` threads the
   assert(adoptPrompt.includes("breaking | compatible"), "the fact's optional description rides the contract");
   assert(adoptPrompt.includes("AGENT_RESULT_FILE"), "the contract names the completion channel the fact rides");
 
-  // A node that declares NO facts still carries the preflight, then exactly the authored prompt — the
-  // emit contract contributes nothing.
-  assertEquals(plain?.appendPrompt, renderIdempotencyPreamble() + "just implement it");
+  // A node that declares NO facts still carries the preflight and the (emit-less) producer contract,
+  // then exactly the authored prompt — the emit contract contributes nothing.
+  assertEquals(plain?.appendPrompt, renderIdempotencyPreamble() + "just implement it" + renderEmitContract([]) + renderProducerContract([]));
+});
+
+test("agent node producer completion contract (#760): every agent prompt carries the terminal-status vocabulary derived from AGENT_TERMINAL_SUCCESS_STATUSES + required-emit names; a non-agent node never does", async () => {
+  // #760: the #731 producer gate's terminal-status vocabulary (AGENT_TERMINAL_SUCCESS_STATUSES) lived
+  // ONLY in the compiler's gate — nothing told the agent which statuses count as success, so a
+  // correctly-done agent that self-reported `status: "success"` was parked on a __contract escalation
+  // (instance 15697). Auto-inject the vocabulary into every agent node's appendPrompt, derived from the
+  // single source of truth so the list and the prompt can never drift.
+  const graph: DeliveryGraph = {
+    name: "producer contract",
+    nodes: [
+      { id: "emit", kind: "agent", agent: { jobType: "senior:feature", prompt: "do the thing" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "plain", kind: "agent", agent: { jobType: "senior:feature", prompt: "no emits here" } },
+      { id: "gate", kind: "wait", wait: { kind: "pr", target: "owner/repo#1", match: { prState: "merged" } } },
+    ],
+    edges: [{ from: "emit.pr", to: "plain" }, { from: "plain", to: "gate" }],
+  };
+  const p = await prepareOk(graph);
+  const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
+  assertEquals(agents.length, 2, "both agent nodes are seeded");
+
+  // Every agent node — emit-declaring OR not — carries the producer contract heading and the EXACT
+  // allowlist strings, derived from the single source of truth.
+  for (const a of agents) {
+    const prompt = String(a.appendPrompt);
+    assert(prompt.includes("Producer completion contract"), `every agent prompt carries the producer contract, got: ${prompt}`);
+    for (const status of AGENT_TERMINAL_SUCCESS_STATUSES) {
+      assert(prompt.includes(`\`${status}\``), `the allowlist status ${status} is surfaced verbatim, got: ${prompt}`);
+    }
+    assert(prompt.includes("escalation"), "it warns an out-of-vocabulary status parks a human escalation");
+  }
+
+  // The emit-declaring node names its required emit in the producer contract; the no-emit node carries
+  // the status block unchanged in every other respect (per #760 acceptance) but names no emit.
+  const emit = agents.find((v) => String(v.appendPrompt).includes("do the thing"));
+  const plain = agents.find((v) => String(v.appendPrompt).includes("no emits here"));
+  assert(String(emit?.appendPrompt).includes(renderProducerContract([{ name: "pr", type: "pr" }])), "the emit-declaring node's producer contract names its required emit");
+  assert(String(plain?.appendPrompt).includes(renderProducerContract([])), "the no-emit node still carries the status block");
+
+  // The vocabulary is AGENT-ONLY — a wait node's seed carries no prompt at all.
+  const wait = Object.values(p.nodeInputs).find((v) => "gateKey" in v) as Record<string, unknown> | undefined;
+  assert(wait, "the wait node is seeded");
+  assert(!("appendPrompt" in wait!), "a non-agent node never carries the producer completion contract");
+});
+
+
+test("producer contract required-emit subset (#761): a routing-only emit is NOT listed as a required field, but the classifier-emit contract still names it", async () => {
+  // #761: `renderProducerContract` was passed a node's FULL declared `emits`, so it told the agent to
+  // populate EVERY declared emit non-null — even a routing-only fact (named only in an edge `when`
+  // guard) that the #731 gate deliberately leaves optional. That contradicted the classifier-emit
+  // contract's "OMIT an undecidable routing fact (default branch)" guidance and pushed agents to guess.
+  // The producer contract must list ONLY the required-data-dependency subset (`from: "<node>.<fact>"`),
+  // while the emit contract still lists every declared fact.
+  const graph: DeliveryGraph = {
+    name: "routing-only producer",
+    nodes: [
+      { id: "classify", kind: "agent", agent: { jobType: "senior:feature", prompt: "classify it" }, emits: [{ name: "decision", type: "string" }] },
+      { id: "migrate", kind: "connector", connector: { target: "npm:install", dedupeKey: "m-1" } },
+      { id: "release", kind: "connector", connector: { target: "npm:publish", dedupeKey: "r-1" } },
+    ],
+    edges: [
+      { from: "classify", to: "migrate", when: "classify.decision", equals: "breaking" },
+      { from: "classify", to: "release", default: true },
+    ],
+  };
+  const p = await prepareOk(graph);
+  const classify = Object.values(p.nodeInputs).find((v) => "jobType" in v && String((v as Record<string, unknown>).appendPrompt).includes("classify it")) as Record<string, unknown> | undefined;
+  assert(classify, "the classify agent node is seeded");
+  const prompt = String(classify!.appendPrompt);
+  // The producer contract still gates on status but names NO required emit (routing-only ⇒ optional).
+  assert(prompt.includes("Producer completion contract"), "the producer contract is present");
+  assert(prompt.includes(renderProducerContract([])), "the producer contract lists no required emit for a purely routing-only producer");
+  assert(!prompt.includes("populate each of these top-level fields"), "no required-emit sentence is rendered when every emit is routing-only");
+  // The classifier-emit contract STILL tells the agent to return the routing fact (and omit if undecidable).
+  assert(prompt.includes("Classifier emit contract"), "the classifier-emit contract is present");
+  assert(prompt.includes("`decision`"), "the routing fact is still named by the classifier-emit contract");
+});
+
+
+test("producer contract semantics coverage (#761 follow-up): renderProducerContract emits a documented bullet for EVERY allowlisted status and fails fast on an undocumented one", () => {
+  // Copilot review follow-up: `renderProducerContract` previously FILTERED the allowlist against
+  // PRODUCER_STATUS_SEMANTICS, so adding a status to AGENT_TERMINAL_SUCCESS_STATUSES without documenting
+  // its semantics would silently render a prompt that LISTS the status in the vocabulary line yet gives
+  // no explanatory bullet — a quiet drift between the allowlist and the surfaced contract. It now emits
+  // a bullet for every allowlisted status and throws if any lacks semantics. Pin: every currently
+  // allowlisted status carries a documented `- \`<status>\` — …` bullet (so the throw path is
+  // unreachable for the shipped allowlist, and any future undocumented addition breaks the build).
+  const rendered = renderProducerContract([]);
+  for (const status of AGENT_TERMINAL_SUCCESS_STATUSES) {
+    assert(
+      rendered.includes(`- \`${status}\` — `),
+      `every allowlisted status carries a documented semantics bullet, missing: ${status}, got: ${rendered}`,
+    );
+  }
 });
 
 

package/app/deliveryRunner.ts

@@ -18,7 +18,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
-import { AGENT_REPO_SPEC_HEADER, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
+import { AGENT_REPO_SPEC_HEADER, AGENT_TERMINAL_SUCCESS_STATUSES, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, isResolvableRepo, RepoEnvelopeConflictError, RepoEnvelopeUnresolvedError } from "./repoEnvelope.ts";
 import { isoDuration } from "./reviewWait.ts";
@@ -100,6 +100,10 @@ const DEFAULTS: Required<Omit<DeliveryRunTimeouts, "escalationAssignee">> = {
   escalationSlaTimeout: "P1D",
 };
 
+/** Shared empty required-emit set for a node whose declared emits are all routing-only (or which
+ * declares none) — avoids allocating a throwaway `Set` per such node while seeding. */
+const EMPTY_REQUIRED_EMITS: ReadonlySet<string> = new Set<string>();
+
 /** The per-node config the compiled subProcess ioMappings read from `nodeInputs.<element>`. A closed
  * union mirrored by the compiler's `ioMappingLines` — the two must agree on field names (a drift here
  * silently seeds `null` into a node body), so both derive from the same node kinds. */
@@ -170,11 +174,22 @@ export async function prepareDeliveryGraph(
     escalationAssignee: options.escalationAssignee ?? null,
   };
   const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
+  // Required-emit subset per node (#761), derived from the SAME canonical `resolved.edges` the compiler's
+  // `requiredEmitsByElement` gate uses: a fact is a required data dependency exactly when some edge
+  // threads it as a fact-qualified `from: "<node>.<fact>"` (`fromFact` set). A routing-only fact (named
+  // only in a `when` guard) is deliberately absent, so the producer contract leaves it optional.
+  const requiredEmitsByNodeId = new Map<string, Set<string>>();
+  for (const edge of compiled.resolved.edges) {
+    if (edge.fromFact === undefined) continue;
+    const set = requiredEmitsByNodeId.get(edge.fromNode) ?? new Set<string>();
+    set.add(edge.fromFact);
+    requiredEmitsByNodeId.set(edge.fromNode, set);
+  }
   const nodeInputs: Record<string, NodeInput> = {};
   for (const node of graph.nodes) {
     const element = elementByNodeId.get(node.id);
     if (element === undefined) continue; // unreachable — resolved covers every node — but keep total.
-    nodeInputs[element] = buildNodeInput(node, { runKey, element, ...timeouts });
+    nodeInputs[element] = buildNodeInput(node, { runKey, element, ...timeouts, requiredEmits: requiredEmitsByNodeId.get(node.id) ?? EMPTY_REQUIRED_EMITS });
   }
   return { ok: true, prepared: { processDefinitionId, bpmn, nodeInputs } };
 }
@@ -419,11 +434,86 @@ export function renderEmitContract(emits: readonly DeliveryFact[]): string {
 }
 
 
+/** Per-status semantics for the producer-completion contract (#760). Keyed by the SAME status strings
+ * as {@link AGENT_TERMINAL_SUCCESS_STATUSES} so the rendered bullets are DERIVED from the single source
+ * of truth: {@link renderProducerContract} iterates the allowlist and emits a bullet for EVERY status,
+ * failing fast if any allowlisted status has no entry here. Removing a status from the allowlist drops
+ * its bullet; adding one WITHOUT documenting its semantics here is a build/boot-time error (not a
+ * silently under-explained prompt) — so the surfaced list and the allowlist can never drift. */
+const PRODUCER_STATUS_SEMANTICS: Readonly<Record<string, string>> = {
+  opened: "you opened OR adopted a PR (return it in your `pr` emit if this node declares one)",
+  done: "the work completed with no PR to open",
+  skipped: "there was genuinely nothing to do",
+};
+
+/** Render the producer-completion contract auto-injected into EVERY `agent` node's `appendPrompt`
+ * (issue #760) — the missing THIRD contract block alongside {@link renderIdempotencyPreamble} (#551)
+ * and {@link renderEmitContract} (#506). The #731 producer gate (`app/deliveryGraphCompiler.ts`) only
+ * routes a completion onward when its self-reported `status` is one of `AGENT_TERMINAL_SUCCESS_STATUSES`
+ * AND every required emit is non-null; before this block that vocabulary lived ONLY in the gate, so a
+ * correctly-finished agent that self-reported an out-of-vocabulary `status` (e.g. `"success"`) was
+ * parked on a `__contract` escalation despite good work (instance 15697). This block hands the agent the
+ * same vocabulary through its sole steering channel, DERIVED from `AGENT_TERMINAL_SUCCESS_STATUSES` (and
+ * the node's REQUIRED emits) so the gate and the prompt cannot drift — changing the allowlist changes
+ * this block. Deterministic: fixed wording, statuses + emit names in declared order, so identical graphs
+ * still compile+seed byte-identically. Unconditional — a no-emit node still gets the status block (the
+ * gate applies to it too); only the required-emit sentence is elided when there are none.
+ *
+ * `requiredEmits` is the subset of the node's declared `emits` the #731 gate actually gates on — those
+ * consumed downstream as a REQUIRED DATA DEPENDENCY (threaded on a fact-qualified `from: "<node>.<fact>"`
+ * edge), derived from the SAME `requiredEmitsByElement` source the compiler's proceed-condition uses
+ * (see `prepareDeliveryGraph`). It deliberately EXCLUDES a routing-only fact (named only in an edge
+ * `when` guard) — the gate leaves those optional (omit ⇒ default branch), and the classifier-emit
+ * contract already tells the agent to omit an undecidable routing fact. Listing every DECLARED emit
+ * here instead would contradict that guidance and push agents to guess values that should stay
+ * optional (#761). */
+export function renderProducerContract(requiredEmits: readonly DeliveryFact[]): string {
+  const list = AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => `\`${s}\``).join(", ");
+  const semantics = AGENT_TERMINAL_SUCCESS_STATUSES.map((s) => {
+    const doc = PRODUCER_STATUS_SEMANTICS[s];
+    if (doc === undefined) {
+      throw new Error(
+        `renderProducerContract: allowlisted status "${s}" has no PRODUCER_STATUS_SEMANTICS entry — ` +
+          "document its semantics so the producer-contract prompt and AGENT_TERMINAL_SUCCESS_STATUSES cannot drift.",
+      );
+    }
+    return `- \`${s}\` — ${doc}.`;
+  });
+  const lines = [
+    "",
+    "",
+    "---",
+    "",
+    "## Producer completion contract (delivery graph)",
+    "",
+    "This node is a PRODUCER in a delivery graph: a completion barrier gates your result before it can",
+    "route to a downstream consumer. The structured result you write to `AGENT_RESULT_FILE` MUST end",
+    `with a \`status\` field that is one of the terminal-success values ${list}:`,
+    "",
+    ...semantics,
+    "",
+    `Any \`status\` OUTSIDE ${list} — including a free-form \`success\`/\`in_progress\`/\`failed\` — parks the`,
+    "run on a human escalation (the gate is fail-closed), EVEN when your underlying work was correct. So",
+    "do not invent a status: report exactly one of the allowlisted values above.",
+  ];
+  if (requiredEmits.length > 0) {
+    lines.push(
+      "",
+      "AND every emit a downstream node requires must be populated non-null before your result routes",
+      "onward — populate each of these top-level fields:",
+      "",
+      ...requiredEmits.map((f) => `- \`${f.name}\``),
+    );
+  }
+  return lines.join("\n");
+}
+
+
 /** Build the `nodeInputs.<element>` seed for one node, per its kind — the exact fields the compiled
  * subProcess ioMapping pulls. Total over the closed kind set. */
 function buildNodeInput(
   node: DeliveryNode,
-  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; probePollEvery: string; escalationSlaTimeout: string; escalationAssignee: string | null },
+  ctx: { runKey: string; element: string; nodeTimeout: string; probeTimeout: string; probePollEvery: string; escalationSlaTimeout: string; escalationAssignee: string | null; requiredEmits: ReadonlySet<string> },
 ): NodeInput {
   switch (node.kind) {
     case "agent": {
@@ -439,7 +529,13 @@ function buildNodeInput(
       // truth. A no-emit node appends nothing, so a plain implementation node is unchanged.
       const basePrompt = node.agent.prompt ?? "";
       const emits = Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [];
-      return { jobType: node.agent.jobType, appendPrompt: renderIdempotencyPreamble() + basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+      // The classifier-emit contract lists ALL declared emits (the agent returns each fact it can, and
+      // OMITS an undecidable routing fact). The producer contract's required-emit sentence instead lists
+      // only the subset the #731 gate fails closed on — the facts consumed downstream as a required data
+      // dependency (`ctx.requiredEmits`) — so it never contradicts the emit contract by demanding a
+      // routing-only fact be non-null (#761).
+      const requiredEmits = emits.filter((f) => ctx.requiredEmits.has(f.name));
+      return { jobType: node.agent.jobType, appendPrompt: renderIdempotencyPreamble() + basePrompt + renderEmitContract(emits) + renderProducerContract(requiredEmits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     }
     case "wait": {
       const probe = parseProbe(node.wait, { allowLateBoundTarget: true });

package/app/readiness.test.ts

@@ -220,6 +220,57 @@ test("matchCapability: the bare '#274' ref form resolves identically to 'nano-id
   assertEquals(res.bind?.resolvedArtifact, "@nanobpm/urban@1.2.3");
 });
 
+// ── #764: single-package repos tag releases `v<version>` / bare `<version>` (semantic-release default) ──
+
+const c8Match = { capabilityRef: "c8ctl-plugin-nano#206", package: "c8ctl-plugin-nano" };
+
+test("#764 matchCapability: a `v<version>` release (body refs the cap) resolves in a single-package repo", () => {
+  // Red before the fix: `v1.58.0` never matched versionForPackage(tag, 'c8ctl-plugin-nano'),
+  // so the gate reported 'not published yet' though the npm package WAS published.
+  const res = matchCapability(c8Match, [rel("v1.58.0", [206])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "c8ctl-plugin-nano@1.58.0");
+});
+
+test("#764 matchCapability: a bare `<version>` release resolves the same way in a single-package repo", () => {
+  const res = matchCapability(c8Match, [rel("1.58.0", [206])]);
+  assert(res.ready);
+  assertEquals(res.bind?.resolvedArtifact, "c8ctl-plugin-nano@1.58.0");
+});
+
+test("#764 monorepo guard: a stray `v2.0.0` alongside package-scoped tags is NOT attributed to another package", () => {
+  // The repo emits package-scoped tags → it is a monorepo → bare `v` tags are ignored, so the stray
+  // v2.0.0 can never leak into @nanobpm/other's resolution.
+  const releases = [rel("@nanobpm/other@1.0.0", [200]), rel("v2.0.0", [274])];
+  const res = matchCapability({ capabilityRef: "nano-ide#274", package: "@nanobpm/other" }, releases);
+  assert(!res.ready, "the stray v2.0.0 must not resolve #274 for @nanobpm/other");
+});
+
+test("#764 summariseCapabilityCandidates: shows the extended `v`-tag candidate in a single-package repo", () => {
+  const summary = summariseCapabilityCandidates(c8Match, [rel("v1.58.0", [206]), rel("v1.57.0", [200])]);
+  assertStringIncludes(summary, "2 c8ctl-plugin-nano release(s) observed");
+  assertStringIncludes(summary, "c8ctl-plugin-nano@1.58.0 refs #206");
+  assertStringIncludes(summary, "c8ctl-plugin-nano@1.57.0 no #206");
+});
+
+test("#764 summariseCapabilityCandidates: in a monorepo a stray `v` tag is not summarised as another package's candidate", () => {
+  const summary = summariseCapabilityCandidates({ capabilityRef: "nano-ide#274", package: "@nanobpm/other" }, [
+    rel("@nanobpm/other@1.0.0", [200]),
+    rel("v2.0.0", [274]),
+  ]);
+  assertStringIncludes(summary, "1 @nanobpm/other release(s) observed");
+  assert(!summary.includes("2.0.0"), "the stray monorepo v2.0.0 is not a candidate for @nanobpm/other");
+});
+
+test("#764 newestPublishedVersion: resolves from `v`-tags under the single-package condition", () => {
+  assertEquals(newestPublishedVersion("c8ctl-plugin-nano", [rel("v1.57.0", []), rel("v1.58.0", [])]), "1.58.0");
+});
+
+test("#764 newestPublishedVersion: a stray `v` tag in a monorepo is ignored for a scoped package", () => {
+  const releases = [rel("@nanobpm/urban@0.9.0", []), rel("v9.9.9", [])];
+  assertEquals(newestPublishedVersion("@nanobpm/urban", releases), "0.9.0");
+});
+
 // ── #514 Defect A: the capability gate is self-diagnosing on escalation ──────────────────────────
 
 test("#514 Defect A summariseCapabilityCandidates: lists candidate releases (newest first) and whether each references the ref", () => {

package/app/readiness.ts

@@ -527,18 +527,58 @@ function bodyReferences(body: string, num: string): boolean {
   return new RegExp(`#${num}(?!\\d)`).test(body);
 }
 
-/** The `<version>` of a release tagged exactly `<package>@<version>` (numeric-dotted), or undefined
- * when the tag belongs to another package or is not a version tag. Per-package scoping is enforced
- * here: a sibling package's provenance can never leak into this package's resolution. */
-function versionForPackage(tag: string, pkg: string): string | undefined {
+/** A numeric-dotted SemVer-ish core, e.g. `1.58.0`. */
+const VERSION_CORE = /^\d+(\.\d+)*$/;
+
+/** Is `tag` a **package-scoped** version tag — `<anything>@<version>` (numeric-dotted), the monorepo
+ * convention (e.g. `@nanobpm/urban@0.54.0`, `c8ctl-plugin-nano@1.58.0`)? Used to decide whether a
+ * repo follows the single-package (`v1.58.0` / bare) convention: a repo is "single-package" only when
+ * it emits NO package-scoped tags at all. Anchored on the LAST `@` so scoped npm names (`@org/name@1.0.0`)
+ * are recognised. */
+function isPackageScopedVersionTag(tag: string): boolean {
+  const at = tag.lastIndexOf("@");
+  if (at <= 0) return false; // no `@`, or a leading `@` (scoped-name start) with nothing before it
+  return VERSION_CORE.test(tag.slice(at + 1).trim());
+}
+
+/** True when the repo's observed release set contains NO `<anything>@<version>`-prefixed package-scoped
+ * tags at all — i.e. it follows the single-package `v<version>` / bare `<version>` convention
+ * (semantic-release default), so a bare `v1.58.0` tag may be attributed to the sole package (#764).
+ * A repo using package-scoped tags is a monorepo: bare `v` tags are ignored there, keeping
+ * per-package provenance scoping airtight (a sibling package's provenance can never leak). */
+function repoIsSinglePackage(releases: readonly GithubRelease[]): boolean {
+  for (const rel of releases) {
+    if (rel && typeof rel.tag === "string" && isPackageScopedVersionTag(rel.tag)) return false;
+  }
+  return true;
+}
+
+/** The `<version>` a release tag carries for `pkg`, or undefined when it belongs to another package /
+ * is not a version tag. A tag is a candidate for `pkg` when **either**:
+ *
+ * 1. it is `<pkg>@<version>` (numeric-dotted) — the monorepo convention, per-package scoped so a
+ *    sibling package's provenance can never leak; **or**
+ * 2. `singlePackage` is true (the repo emits no package-scoped tags — see {@link repoIsSinglePackage})
+ *    AND the tag is `v<version>` or a bare `<version>` — the single-package / semantic-release-default
+ *    convention (#764). In a monorepo (`singlePackage` false) bare `v` tags are ignored, so scoping
+ *    stays airtight. */
+function versionForPackage(tag: string, pkg: string, singlePackage: boolean): string | undefined {
   const prefix = `${pkg}@`;
-  if (!tag.startsWith(prefix)) return undefined;
-  const v = tag.slice(prefix.length).trim();
-  return /^\d+(\.\d+)*$/.test(v) ? v : undefined;
+  if (tag.startsWith(prefix)) {
+    const v = tag.slice(prefix.length).trim();
+    return VERSION_CORE.test(v) ? v : undefined;
+  }
+  if (singlePackage) {
+    const v = (tag.startsWith("v") ? tag.slice(1) : tag).trim();
+    if (VERSION_CORE.test(v)) return v;
+  }
+  return undefined;
 }
 
 /** A compact, deterministic, BOUNDED summary of the capability candidate releases a probe observed
- * (issue #514 Defect A). Lists the releases tagged `<match.package>@<version>` (newest first) and,
+ * (issue #514 Defect A). Lists the releases carrying a resolvable `<match.package>` version — tagged
+ * `<match.package>@<version>`, or (for a single-package repo) a `v<version>`/bare `<version>` tag —
+ * newest first, and,
  * for each, whether its body referenced `match.capabilityRef` — so an escalated capability gate can
  * show a human/agent EXACTLY what the probe saw (a genuine "not published yet" vs. a transient
  * false-negative where a matching release was live but its provenance body was momentarily empty).
@@ -548,6 +588,7 @@ function versionForPackage(tag: string, pkg: string): string | undefined {
 export function summariseCapabilityCandidates(
   match: ProbeMatch | undefined,
   releases: readonly GithubRelease[],
+  singlePackage: boolean = repoIsSinglePackage(releases),
 ): string {
   const pkg = match?.package;
   const ref = match?.capabilityRef;
@@ -556,7 +597,7 @@ export function summariseCapabilityCandidates(
   const candidates: { version: string; refs: boolean }[] = [];
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     candidates.push({ version, refs: num !== undefined && bodyReferences(rel.body, num) });
   }
@@ -591,7 +632,8 @@ const CAPABILITY_SUMMARY_LIMIT = 8;
 export function matchCapability(match: ProbeMatch | undefined, releases: readonly GithubRelease[]): ProbeResult {
   const pkg = match?.package;
   const ref = match?.capabilityRef;
-  const observed = summariseCapabilityCandidates(match, releases);
+  const singlePackage = repoIsSinglePackage(releases);
+  const observed = summariseCapabilityCandidates(match, releases, singlePackage);
   if (!pkg || !ref) return { ready: false, detail: "capability: missing package/capabilityRef", observed };
   const num = capabilityNumber(ref);
   if (!num) return { ready: false, detail: "capability: unparseable capabilityRef (no #NNN)", observed };
@@ -599,7 +641,7 @@ export function matchCapability(match: ProbeMatch | undefined, releases: readonl
   let firstVersion: string | undefined;
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string" || typeof rel.body !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     if (!bodyReferences(rel.body, num)) continue;
     if (firstVersion === undefined || cmpVersion(version, firstVersion) < 0) firstVersion = version;
@@ -615,9 +657,10 @@ export function matchCapability(match: ProbeMatch | undefined, releases: readonl
 export function newestPublishedVersion(pkg: string | undefined, releases: readonly GithubRelease[]): string | undefined {
   if (!pkg) return undefined;
   let newest: string | undefined;
+  const singlePackage = repoIsSinglePackage(releases);
   for (const rel of releases) {
     if (!rel || typeof rel.tag !== "string") continue;
-    const version = versionForPackage(rel.tag, pkg);
+    const version = versionForPackage(rel.tag, pkg, singlePackage);
     if (!version) continue;
     if (newest === undefined || cmpVersion(version, newest) > 0) newest = version;
   }

package/docs/agent-guide.md

@@ -621,6 +621,22 @@ agent node and guard the downstream edge on `<node>.<name>`; a contract-followin
 **omits** it, and the split takes its `default` (else) branch — the deadlock-safe fallback. A
 node that declares no `emits` gets no contract text and behaves exactly as before.
 
+**Producer completion contract (auto-injected — do NOT hand-encode it).** Every `agent` node
+*also* has a **producer completion contract** appended to its prompt at dispatch, alongside the
+idempotency preflight and — only for a node that declares `emits` — the classifier emit contract.
+It hands the agent the terminal-status vocabulary
+the `#731` producer gate enforces: the injected text tells the agent it MUST end its result with
+one of `AGENT_TERMINAL_SUCCESS_STATUSES` (`done` / `opened` / `skipped`) — never omit `status` or
+invent one. The gate routes a completion onward only when its self-reported `status` is one of that
+allowlist **and** every required emit is non-null; any *explicitly non-terminal* status parks the
+run on a human `__contract` escalation (fail-closed). (As a backward-compat concession the gate
+*also* routes onward an **absent/null** status — for legacy workers / stubs that report none — but
+the injected contract never invites a real agent to lean on that: always return an allowlisted
+status.) The wording is **derived from that single allowlist** (changing the
+list changes the prompt — no second copy), so **authors must not hand-encode status vocabulary
+in a node's prompt.** Unlike the emit contract, a no-emit node still receives the status block
+(the gate applies to it too).
+
 ### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
 
 ```

package/e2e/delivery-graph.e2e.ts

@@ -209,7 +209,11 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
           processInstanceKey: job.processInstanceKey ?? null,
           elementId: job.elementId ?? null,
         });
-        return await dispatchConnector(app.db, { dedupeKey: dedupeKey ?? "x", target, payload, boundFacts }, new Date().toISOString());
+        // Mirror the real worker's fail-closed contract: an un-dedupable dispatch (no author key AND
+        // no engine identity) throws rather than papering over it with a hardcoded fallback that would
+        // mask a regression where the connector node stops seeding `dedupeKey`.
+        if (!dedupeKey) throw new Error("connector stub: no dedupe key (author-supplied or graph-derived) available");
+        return await dispatchConnector(app.db, { dedupeKey, target, payload, boundFacts }, new Date().toISOString());
       },
       { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
     );
@@ -246,6 +250,64 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the resumed producer's result reaches End");
   });
 
+  test("#760 producer contract satisfied: an agent completing with an allowlisted status + its required emit passes the gate with NO __contract escalation and threads onward", async () => {
+    const app = track(await boot(freshDir()));
+
+    // The instance-15697 failure mode: the agent DID the work correctly and returned its required emit,
+    // but self-reported an out-of-vocabulary `status` (e.g. "success") and so was wrongly parked on a
+    // __contract escalation — because the terminal-status vocabulary lived ONLY in the gate. With #760
+    // the vocabulary is auto-injected into the agent's appendPrompt (proven in the runner unit tests);
+    // here we prove the gate's happy path: a status FROM `AGENT_TERMINAL_SUCCESS_STATUSES` ("opened")
+    // WITH the required emit sails through — no escalation, the downstream connector fires.
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return { status: "opened", pr: "owner/repo#99", summary: "PR opened and green." };
+    });
+    let connectorFired = 0;
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        connectorFired++;
+        const vars = job.variables as Record<string, unknown>;
+        const { target, payload, boundFacts } = readConnectorInput(vars as Parameters<typeof readConnectorInput>[0]);
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        // Mirror the real worker's fail-closed contract: an un-dedupable dispatch (no author key AND
+        // no engine identity) throws rather than papering over it with a hardcoded fallback that would
+        // mask a regression where the connector node stops seeding `dedupeKey`.
+        if (!dedupeKey) throw new Error("connector stub: no dedupe key (author-supplied or graph-derived) available");
+        return await dispatchConnector(app.db, { dedupeKey, target, payload, boundFacts }, new Date().toISOString());
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e producer gate satisfied",
+      nodes: [
+        { id: "open", kind: "agent", agent: { jobType: "senior:demo" }, emits: [{ name: "pr", type: "pr" }] },
+        { id: "land", kind: "connector", connector: { target: "slack", payload: { pr: "open.pr" }, dedupeKey: "land-760" } },
+      ],
+      edges: [{ from: "open.pr", to: "land" }],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The producer satisfied its contract (allowlisted status + non-null required emit): NO __contract
+    // escalation was raised, the downstream connector fired once, and the graph reached End.
+    assert.equal(agentFired, 1, "the agent node's job fired and completed");
+    const createdTasks = await app.engine.searchUserTasks({ state: "CREATED" });
+    const contract = createdTasks.find((t) => t.elementId?.startsWith("delivery-human-task__") && t.elementId?.endsWith("__contract"));
+    assert.ok(!contract, `an allowlisted status + required emit must NOT escalate, got ${JSON.stringify(createdTasks.map((t) => t.elementId))}`);
+    assert.equal(connectorFired, 1, "the satisfied producer threads its result to the downstream connector");
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the satisfied producer's result reaches End");
+  });
+
   test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
     const app = track(await boot(freshDir()));
     // The connector fired once above's-style; here prove the idempotency directly against the ledger a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.184.1",
+  "version": "0.185.1",
   "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",