@nanobpm/nano-workforce 0.200.1 → 0.200.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.200.2](https://github.com/nanobpm/nano-workforce/compare/v0.200.1...v0.200.2) (2026-10-03)
+
+### Documentation
+
+* **agent-guide:** require repository on every delivery-graph agent node ([#851](https://github.com/nanobpm/nano-workforce/issues/851)) ([d6770ae](https://github.com/nanobpm/nano-workforce/commit/d6770ae2f6acc490e102aecaf0cab17ca5d10119)), closes [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#505](https://github.com/nanobpm/nano-workforce/issues/505) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [739/#776](https://github.com/739/nano-workforce/issues/776) [#505](https://github.com/nanobpm/nano-workforce/issues/505)
+
 ## [0.200.1](https://github.com/nanobpm/nano-workforce/compare/v0.200.0...v0.200.1) (2026-10-03)
 
 ### Performance Improvements

package/app/deliveryGraphVocabulary.test.ts

@@ -6,7 +6,9 @@
 // key sets are byte-identical to the closed sets in `app/deliveryGraph.ts` / `app/readiness.ts` /
 // `app/convergeTargets.ts` (AGENTS.md — "no drift surfaces").
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { test } from "node:test";
+import { parse as parseYaml } from "yaml";
 import { CONVERGE_MERGE_TARGET, CONVERGE_TARGET, isConvergeTarget, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
 import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
 import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
@@ -100,3 +102,80 @@ test("fact-threading rule names the unbound-pr rejection", () => {
   const vocab = deliveryGraphVocabulary();
   assert.match(vocab.factThreading.rule, /unbound-pr/);
 });
+
+// Resolve a node kind's per-kind CONFIG sub-schema (the authoritative OpenAPI contract for that
+// kind's body) from the parsed spec. `DeliveryNode<Kind>` is `allOf: [DeliveryNodeCommon, { properties:
+// { <configKey>: {…} } }]`, so find the allOf member carrying the `<configKey>` sub-schema and return
+// that member's `<configKey>` VALUE. For most kinds that value is the inline config object; for the
+// `wait` kind it is the `{ $ref: "#/components/schemas/ReadinessProbe" }` object (the config is
+// referenced, not inlined), which this helper returns AS-IS — the caller follows the reference itself.
+// Returns null only when the kind's node schema has NO inline `<configKey>` member at all (which the
+// caller's assert.ok rejects), never for the `wait` kind.
+function nodeConfigSchema(
+  spec: Record<string, any>,
+  nodeSchemaName: string,
+  configKey: string,
+): Record<string, any> | null {
+  const schema = spec?.components?.schemas?.[nodeSchemaName];
+  if (!schema) return null;
+  const sub = (schema.allOf as Array<Record<string, any>> | undefined)?.map((m) => m?.properties?.[configKey]).find(Boolean);
+  return sub ?? null;
+}
+
+/** Derive the (sorted) required + optional field sets from a config sub-schema's own `required`/`properties`. */
+function fieldSets(configSchema: Record<string, any>): { required: string[]; optional: string[] } {
+  const required = [...((configSchema.required as string[] | undefined) ?? [])].sort();
+  const optional = Object.keys((configSchema.properties as Record<string, unknown>) ?? {})
+    .filter((k) => !required.includes(k))
+    .sort();
+  return { required, optional };
+}
+
+test("every node-kind entry's field sets are DERIVED from its OpenAPI DeliveryNode<Kind>.<configKey> contract (#739/#850)", () => {
+  // The #850 failure mode is drift between a `DeliveryNode<Kind>.<configKey>` (the authoritative
+  // OpenAPI contract) and this vocabulary surface. A literal field list duplicated here would NOT
+  // catch it: if OpenAPI adds or removes a config property, a hand-copied list stays green while the
+  // surface lies. So derive the required/optional sets from the PARSED spec and compare the sets
+  // directly — the vocabulary cannot silently drift from the contract it claims to mirror. This
+  // guards EVERY kind, not just `agent`: the connector entry omitting the real `timeout` field
+  // (PR #851 review) is the same drift class the agent-only guard missed.
+  const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+  const spec = parseYaml(readFileSync(`${ROOT}openapi.yaml`, "utf8")) as Record<string, any>;
+
+  const vocab = deliveryGraphVocabulary();
+  for (const entry of vocab.nodeKinds) {
+    const nodeSchemaName = `DeliveryNode${entry.kind[0]!.toUpperCase()}${entry.kind.slice(1)}`;
+    let configSchema = nodeConfigSchema(spec, nodeSchemaName, entry.configKey);
+    assert.ok(
+      configSchema,
+      `openapi.yaml components.schemas.${nodeSchemaName} must carry an inline '${entry.configKey}' config sub-schema`,
+    );
+    // The `wait` kind's config is `$ref: "#/components/schemas/ReadinessProbe"` — follow the reference.
+    if (typeof configSchema!.$ref === "string") {
+      const refName = configSchema!.$ref.replace(/^#\/components\/schemas\//, "");
+      configSchema = spec?.components?.schemas?.[refName];
+      assert.ok(configSchema?.properties, `${refName} (the wait config contract) must declare its properties`);
+    }
+    const { required, optional } = fieldSets(configSchema!);
+    assert.deepEqual(
+      [...entry.requiredFields].sort(),
+      required,
+      `${entry.kind}.requiredFields drifted from ${nodeSchemaName}.${entry.configKey}.required in openapi.yaml`,
+    );
+    assert.deepEqual(
+      [...entry.optionalFields].sort(),
+      optional,
+      `${entry.kind}.optionalFields drifted from ${nodeSchemaName}.${entry.configKey}'s optional properties in openapi.yaml`,
+    );
+  }
+
+  // The non-obvious rules an authoring agent must learn from the surface prose: an ABSENT repository
+  // is not compile-rejected (a run-level fallback can satisfy it) — it fails at the OPERATOR's
+  // Dispatch; and the per-node SLA timeout override exists.
+  const agent = vocab.nodeKinds.find((n) => n.kind === "agent");
+  assert.ok(agent, "agent node-kind entry must exist");
+  assert.match(agent.summary, /resolve to no repository/, "names the dispatch-time failure the author must pre-empt");
+  assert.match(agent.summary, /invalid-node-repository/, "names the compile-time validation for a present value");
+  assert.match(agent.summary, /repoless/, "names the checkout-less opt-out");
+  assert.match(agent.summary, /per-node ISO-8601 `timeout`/, "names the per-node SLA timeout override (#505)");
+});

package/app/deliveryGraphVocabulary.ts

@@ -105,13 +105,29 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   agent: {
     configKey: "agent",
     requiredFields: ["jobType"],
-    optionalFields: ["prompt", "converge", "merge"],
+    optionalFields: ["repository", "baseBranch", "prompt", "converge", "merge", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
-      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`). First-class " +
+      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`) in an isolated " +
+      "checkout. Per-node provisioning (#739/#776): declare `repository` (`owner/repo`, no `.git`/URL) " +
+      "on EVERY agent node — the harness clones it at `baseBranch` (omit it to use the run-level " +
+      "dispatch `baseBranch`, else the repo's default branch) and cuts `feat/<node.id>` off it " +
+      "(when that derived ref is a valid Git branch name; an id like `a..b`/`a.lock` yields an " +
+      "ill-formed ref, so the harness omits `branch.create` and the agent cuts its own branch). A node " +
+      "with no `repository` can only be satisfied by the run-level dispatch fallback, so COMPILE " +
+      "stages it without a warning; at Dispatch it resolves to the run-level `repository` + `baseBranch` " +
+      "fallback when the operator supplies one, and the Dispatch fails with `N agent node(s) " +
+      "resolve to no repository (…)` ONLY when neither the node nor the run supplies a repository " +
+      "(a present value IS compile-validated: `invalid-node-repository`/" +
+      "`invalid-node-base-branch`); a genuinely checkout-less graph must be dispatched `repoless: true`, " +
+      "which strips isolation from every node. First-class " +
       "`converge?`/`merge?` cell-policy flags declare review-convergence / landing intent (`merge` " +
       "requires `converge`); a raw `senior:converge`/`senior:merge` jobType is rejected (`raw-converge-node`). " +
+      "An optional per-node ISO-8601 `timeout` (#505) overrides the run-level `nodeTimeout` (and the " +
+      "`PT1H` default) for THIS node's bounded-timeout → escalate boundary, so a legitimately-long node " +
+      "(e.g. a full `senior:feature`) outlasts a quick gate without a spurious escalation; absent → the " +
+      "run/default value. " +
       "An `agent` that opens a PR emits it as a `pr`-typed fact so downstream connector/wait nodes late-bind it.",
   },
   wait: {
@@ -138,14 +154,16 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   connector: {
     configKey: "connector",
     requiredFields: ["target"],
-    optionalFields: ["dedupeKey", "payload"],
+    optionalFields: ["dedupeKey", "payload", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
       "An automated, side-effecting outbound action. `payload` for a converge target is " +
       "`{ pr, autoMerge?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
       "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
-      "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
+      "(at-least-once safe). An optional per-node ISO-8601 `timeout` (#505) overrides the run-level " +
+      "`nodeTimeout` (and the `PT1H` default) for THIS node's bounded-timeout → escalate boundary; " +
+      "absent → the run/default value. See connectorTargets for which targets are real vs. forward-declared.",
   },
 };
 

package/docs/agent-guide.md

@@ -564,10 +564,33 @@ layer schedules, it does not re-implement execution):
 
 | kind | config | what it does | may `emits`? |
 |---|---|---|---|
-| `agent` | `agent: { jobType, prompt?, converge?, merge? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. | yes |
+| `agent` | `agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }` | a worker runs an agent job type (the fan-out body) in a fresh checkout of its `repository` (see *Provision every agent node* below). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. **`timeout?`** is an OPTIONAL per-node ISO-8601 SLA (#505) that overrides the run-level `nodeTimeout` (and the `PT1H` default) for this node's bounded-timeout → escalate boundary, so a legitimately-long node outlasts a quick gate without a spurious escalation. | yes |
 | `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. | yes |
+| `connector` | `connector: { target, dedupeKey?, payload?, timeout? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. **`timeout?`** — a per-node ISO-8601 SLA (#505), same semantics as the `agent` row. | yes |
+
+> **Provision every `agent` node with a repository — compile will NOT catch it.** Each `agent` cell
+> runs in an isolated checkout: the harness clones the node's **`repository`** (`owner/repo`, no
+> `.git`/URL) at **`baseBranch`** and cuts `feat/<node.id>` off it (#739/#776). `baseBranch` resolves
+> **per field** — the node's own, else the **run-level dispatch `baseBranch`**, else the repo default
+> (an id yielding an ill-formed ref like `a..b`/`a.lock` makes the harness skip `branch.create`, so
+> the agent cuts its own branch). A node with **no `repository`** is staged by compile **without a
+> warning**, then — absent a **run-level fallback** supplied *at dispatch* — Dispatch fails with
+> `N agent node(s) resolve to no repository (…)`. So:
+>
+> - **Declare `repository` on EVERY `agent` node** (and `baseBranch` when it is neither the run-level
+>   base nor the default): a single-repo graph repeats one value; a cross-repo graph names each node's
+>   own repo. Every repo a node's prompt changes must be that node's `repository`.
+> - **`repoless` is a RUN-WIDE mode, not a per-node escape hatch** — it strips isolation from *every*
+>   node. Use it only when **every** `agent` node is checkout-less (pure research/comment work); if
+>   even one needs a checkout, provision repositories instead.
+> - **Self-check before handing over the digest:** every `"kind": "agent"` node has a `repository`;
+>   if you leave some unset, tell the operator which, and that they must pick the run-level
+>   **repository + base-branch fallback** in the Dispatch form (the default mode rejects the graph).
+>
+> A **present** `repository`/`baseBranch` is validated at compile (`invalid-node-repository` /
+> `invalid-node-base-branch`); an **absent `repository`** defers to dispatch (and can fail there); an
+> **absent `baseBranch` is always valid** — it inherits the run-level base, else the repo default.
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
@@ -720,12 +743,12 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
       "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } },
     { "id": "undraft-merge-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-2", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
     { "id": "manual-publish", "kind": "human",
       "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
       "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
     { "id": "open-pr-c", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-3", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
     { "id": "merge-c", "kind": "wait",
       "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
@@ -804,7 +827,7 @@ author never knows the PR number at compose time, so reference it by fact:
   "name": "open → converge+merge → wait merged",
   "nodes": [
     { "id": "open", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement the change in acme/repo and open a PR." },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo", "prompt": "Implement the change in acme/repo and open a PR." },
       "emits": [ { "name": "pr", "type": "pr" } ] },
     { "id": "land", "kind": "connector",
       "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
@@ -870,7 +893,7 @@ babysitting a `confirm` gate.
                 "onTimeout": "escalate" },
       "emits": [ { "name": "prCount", "type": "number" } ] },
     { "id": "start-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
+      "agent": { "jobType": "senior:feature", "repository": "nanobpm/nano-workforce", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
   ],
   "edges": [ { "from": "gate-epic", "to": "start-b" } ]
 }

package/openapi.yaml

@@ -2025,6 +2025,7 @@ components:
             kind: agent
             agent:
               jobType: senior:feature
+              repository: nanobpm/nano-workforce
               prompt: Implement nanobpm/nano-workforce#567 and open a PR.
         edges:
           - { from: gate-epic, to: start-b }
@@ -2406,7 +2407,7 @@ components:
       # cockpit paste). `previewDeliveryGraph` takes `{ "graphJson": "<serialized DeliveryGraph>" }`.
       example:
         graphJson: >-
-          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
+          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
       required:
         - graphJson
       properties:
@@ -5016,6 +5017,7 @@ paths:
                     kind: agent
                     agent:
                       jobType: senior:feature
+                      repository: nanobpm/nano-workforce
                       prompt: Implement nanobpm/nano-workforce#567 and open a PR.
                 edges:
                   - from: gate-epic
@@ -5467,7 +5469,7 @@ paths:
               type: object
               additionalProperties: false
               example:
-                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
+                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
               required:
                 - graphJson
               properties:
@@ -5876,10 +5878,10 @@ paths:
                     - kind: agent
                       configKey: agent
                       requiredFields: [jobType]
-                      optionalFields: [prompt, converge, merge]
+                      optionalFields: [repository, baseBranch, prompt, converge, merge, timeout]
                       sideEffecting: true
                       mayEmit: true
-                      summary: "A worker runs an agent job type; an agent that opens a PR emits it as a `pr` fact."
+                      summary: "A worker runs an agent job type in an isolated checkout; declare `repository` (`owner/repo`) on every agent node — the harness clones it at `baseBranch` (else the run-level dispatch base, else the repo default). Optional per-node ISO-8601 `timeout`, plus `converge?`/`merge?` cell-policy flags. An agent that opens a PR emits it as a `pr` fact."
                     - kind: wait
                       configKey: wait
                       requiredFields: [kind, target]
@@ -5890,7 +5892,7 @@ paths:
                     - kind: connector
                       configKey: connector
                       requiredFields: [target]
-                      optionalFields: [dedupeKey, payload]
+                      optionalFields: [dedupeKey, payload, timeout]
                       sideEffecting: true
                       mayEmit: true
                       summary: "An automated outbound action; payload for a converge target is { pr, autoMerge?, dependsOn? }."

package/operations/getAgentInstructions.test.ts

@@ -61,10 +61,15 @@ test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
   // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
   // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
-  assert(md.includes("agent: { jobType, prompt?, converge?, merge? }"), "documents the agent node config");
+  assert(md.includes("agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }"), "documents the agent node config");
+  // Per-node repository provisioning is only enforced at DISPATCH (a run-level fallback can satisfy it),
+  // so compile stages an unprovisioned graph silently — the guide must tell the authoring agent to
+  // declare `repository` on every agent node, or the operator's Dispatch fails out of the agent's loop.
+  assert(md.includes("Provision every `agent` node with a repository"), "documents per-node repository provisioning");
+  assert(md.includes("resolve to no repository"), "quotes the dispatch-time failure the agent must pre-empt");
   assert(md.includes("wait: <ReadinessProbe>"), "documents the wait node config");
   assert(md.includes("human?: { formKey?, prompt? }"), "documents the human node config");
-  assert(md.includes("connector: { target, dedupeKey?, payload? }"), "documents the connector node config");
+  assert(md.includes("connector: { target, dedupeKey?, payload?, timeout? }"), "documents the connector node config");
   // The fact-edge syntax: an edge is `{ from, to }` and `from` may be a qualified `<nodeId>.<fact>`.
   assert(md.includes("each edge is `{ from, to }`"), "documents the edge shape");
   assert(md.includes("qualified `<nodeId>.<fact>`"), "documents the qualified fact-edge syntax");

package/package.json

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

package/test/deliveryGraphVocabulary-mcp.test.ts

@@ -60,3 +60,35 @@ test("the served payload matches the response schema's required keys (data ⇄ c
     assert(key in payload, `served vocabulary is missing required schema key '${key}'`);
   }
 });
+
+test("the worked example's nodeKind field contract cannot drift from the runtime vocabulary", () => {
+  // The spec's `example:` is a hand-authored YAML copy of the served payload (the runtime cannot be
+  // called from a static spec). It is a deliberately curated SUBSET (fewer kinds / terser summaries),
+  // but the per-kind FIELD CONTRACT it advertises is consumer-facing: a stale `optionalFields` makes
+  // agents author nodes that omit real fields (#739/#776 — `repository`/`baseBranch`/`timeout`), and a
+  // stale `configKey`/`sideEffecting`/`mayEmit` misleads them the same way. Guard the class, not one
+  // field: every nodeKind the example shows must carry EXACTLY the runtime kind's whole contract object
+  // — `kind`, `configKey`, `requiredFields`, `optionalFields`, `sideEffecting`, `mayEmit` — so no part
+  // of the two surfaces can drift apart again. Only `summary` is excluded: the example's is a
+  // deliberately terser curated paraphrase of the runtime's (see this block's preamble).
+  const doc = parseYaml(SPEC_TEXT) as Record<string, any>;
+  const exampleKinds = doc.paths["/delivery-graph/vocabulary"].get.responses["200"].content["application/json"].schema
+    .example?.nodeKinds as Array<Record<string, unknown>> | undefined;
+  assert(Array.isArray(exampleKinds) && exampleKinds.length > 0, "the worked example must list nodeKinds");
+
+  // Compare the full per-kind contract minus `summary` (the sole intentionally-divergent field).
+  const contract = ({ summary: _summary, ...rest }: Record<string, unknown>): Record<string, unknown> => rest;
+
+  const runtimeByKind = new Map(
+    (deliveryGraphVocabulary().nodeKinds as Array<Record<string, unknown>>).map((k) => [k.kind, k]),
+  );
+  for (const shown of exampleKinds) {
+    const runtime = runtimeByKind.get(shown.kind);
+    assert(runtime, `example nodeKind '${String(shown.kind)}' is not a real runtime kind (stale/removed)`);
+    assert.deepEqual(
+      contract(shown),
+      contract(runtime!),
+      `example nodeKind '${String(shown.kind)}' field contract (configKey/requiredFields/optionalFields/sideEffecting/mayEmit) drifted from runtime`,
+    );
+  }
+});