@nanobpm/nano-workforce 0.159.1 → 0.160.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.160.0](https://github.com/nanobpm/nano-workforce/compare/v0.159.1...v0.160.0) (2026-08-29)
+
+### Features
+
+* **delivery-graph:** getDeliveryGraphVocabulary read tool — closed vocabulary + wait semantics as structured data (S3) ([#616](https://github.com/nanobpm/nano-workforce/issues/616)) ([8d3e90a](https://github.com/nanobpm/nano-workforce/commit/8d3e90a294f9ed195c5cc1b7a30cffb1799a053a)), closes [nanobpm/nano-workforce#605](https://github.com/nanobpm/nano-workforce/issues/605) [#609](https://github.com/nanobpm/nano-workforce/issues/609)
+
 ## [0.159.1](https://github.com/nanobpm/nano-workforce/compare/v0.159.0...v0.159.1) (2026-08-29)
 
 ### Bug Fixes

package/app/deliveryGraphVocabulary.test.ts

@@ -0,0 +1,102 @@
+// app/deliveryGraphVocabulary.test.ts — the DRIFT GUARD for the delivery-graph vocabulary surface
+// (epic nano-workforce#605, S3/#609). The vocabulary (`getDeliveryGraphVocabulary`) exists so agents
+// discover the closed node/probe/connector vocabulary from the surface instead of reading source; if
+// a new probe kind or connector target lands in the compiler WITHOUT a matching vocabulary entry, the
+// surface silently lies. These tests fail the build in exactly that case: they assert the vocabulary's
+// 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 { test } from "node:test";
+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";
+import {
+  DEFAULT_EVERY_MS,
+  DEFAULT_TIMEOUT_MS,
+  EPIC_CONDITIONS,
+  ON_TIMEOUTS,
+  PR_CONDITIONS,
+  PROBE_KINDS,
+} from "./readiness.ts";
+
+const sorted = (xs: readonly string[]): string[] => [...xs].sort();
+
+test("node kinds cover exactly DELIVERY_NODE_KINDS (add a kind to the compiler ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(
+    sorted(vocab.nodeKinds.map((n) => n.kind)),
+    sorted(DELIVERY_NODE_KINDS),
+    "vocabulary node kinds drifted from DELIVERY_NODE_KINDS — extend NODE_KIND_DETAIL",
+  );
+});
+
+test("wait probe kinds cover exactly PROBE_KINDS (add a probe kind ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(
+    sorted(vocab.waitProbeKinds.map((p) => p.kind)),
+    sorted(PROBE_KINDS),
+    "vocabulary wait probe kinds drifted from PROBE_KINDS — extend WAIT_PROBE_DETAIL",
+  );
+});
+
+test("pr / epic probe conditions match the closed PR_CONDITIONS / EPIC_CONDITIONS", () => {
+  const vocab = deliveryGraphVocabulary();
+  const pr = vocab.waitProbeKinds.find((p) => p.kind === "pr");
+  const epic = vocab.waitProbeKinds.find((p) => p.kind === "epic");
+  assert.ok(pr && epic, "pr and epic probe entries must exist");
+  assert.deepEqual(sorted(pr.conditions ?? []), sorted(PR_CONDITIONS), "pr conditions drifted from PR_CONDITIONS");
+  assert.deepEqual(sorted(epic.conditions ?? []), sorted(EPIC_CONDITIONS), "epic conditions drifted from EPIC_CONDITIONS");
+});
+
+test("every real converge-enrollment target has a real vocab entry (add a target ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  const realTargets = vocab.connectorTargets.filter((t) => t.status === "real").map((t) => t.target);
+  for (const target of [CONVERGE_TARGET, CONVERGE_MERGE_TARGET, MERGE_MAIN_TARGET]) {
+    assert.ok(
+      realTargets.includes(target),
+      `converge target '${target}' is missing a 'real' vocabulary entry — extend REAL_CONNECTOR_TARGETS`,
+    );
+    // Guard the classification too: a target the compiler treats as converge-enrollment must be marked real.
+    assert.ok(isConvergeTarget(target), `sanity: '${target}' must be an isConvergeTarget`);
+  }
+  // Exactly the converge set is "real"; nothing else is claimed real, and the stub sentinel is present.
+  assert.deepEqual(sorted(realTargets), sorted([CONVERGE_TARGET, CONVERGE_MERGE_TARGET, MERGE_MAIN_TARGET]));
+  assert.ok(
+    vocab.connectorTargets.some((t) => t.status === "forward-declared"),
+    "the forward-declared stub sentinel must be present so agents learn the real-vs-stub split",
+  );
+});
+
+test("onTimeout options match the closed ON_TIMEOUTS", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(sorted(vocab.onTimeout.map((o) => o.value)), sorted(ON_TIMEOUTS), "onTimeout options drifted from ON_TIMEOUTS");
+});
+
+test("fact types + guard scalar types are derived verbatim", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(vocab.factTypes, [...DELIVERY_FACT_TYPES]);
+  assert.deepEqual(vocab.guardScalarTypes, [...DELIVERY_GUARD_SCALAR_TYPES]);
+});
+
+test("poll-budget carries the real defaults and names the 30-minute trap", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.equal(vocab.pollBudget.defaultTimeoutMs, DEFAULT_TIMEOUT_MS);
+  assert.equal(vocab.pollBudget.defaultEveryMs, DEFAULT_EVERY_MS);
+  assert.match(vocab.pollBudget.rule, /poll\.timeoutMs/);
+  assert.match(vocab.pollBudget.rule, /30 minutes|1800000/);
+});
+
+test("the epic probe states the FEATURE-RUN observation semantics (the #605 evidence gap)", () => {
+  const vocab = deliveryGraphVocabulary();
+  const epic = vocab.waitProbeKinds.find((p) => p.kind === "epic");
+  assert.ok(epic, "epic probe entry must exist");
+  assert.match(epic.observes, /rootRequestKey/i);
+  assert.match(epic.observes, /regardless of/i);
+  assert.match(epic.observes, /feature/i);
+  assert.match(epic.ready, /stage:"merged"|stage:\\"merged\\"|merged.*active:false/);
+});
+
+test("fact-threading rule names the unbound-pr rejection", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.match(vocab.factThreading.rule, /unbound-pr/);
+});

package/app/deliveryGraphVocabulary.ts

@@ -0,0 +1,319 @@
+// app/deliveryGraphVocabulary.ts — the delivery-graph vocabulary + wait-probe semantics as
+// STRUCTURED DATA (epic nano-workforce#605, S3/#609). Served by GET /app/api/delivery-graph/vocabulary
+// (operationId `getDeliveryGraphVocabulary`, a read tool projected onto the MCP surface like
+// `getAgentInstructions`), so an agent can DISCOVER the closed node/probe/connector vocabulary and the
+// non-obvious wait semantics from the surface instead of reading source (the evidence session in #605:
+// an agent had to grep `app/readiness.ts` to learn `wait[epic]` also gates a feature run).
+//
+// Derivation over duplication (AGENTS.md — "no drift surfaces"). Everything that has a closed,
+// compiler-enforced source of truth is DERIVED from it, never re-typed:
+//   • node kinds        ← `DELIVERY_NODE_KINDS`      (app/deliveryGraph.ts — the trust boundary)
+//   • fact types        ← `DELIVERY_FACT_TYPES`      (app/deliveryGraph.ts)
+//   • guardable scalars ← `DELIVERY_GUARD_SCALAR_TYPES`
+//   • wait probe kinds  ← `PROBE_KINDS`              (app/readiness.ts — what `parseProbe` accepts)
+//   • pr conditions     ← `PR_CONDITIONS`            (app/readiness.ts)
+//   • epic conditions   ← `EPIC_CONDITIONS`          (app/readiness.ts)
+//   • onTimeout options ← `ON_TIMEOUTS`              (app/readiness.ts)
+//   • poll defaults     ← `DEFAULT_TIMEOUT_MS`/`DEFAULT_EVERY_MS`/`DEFAULT_READINESS_TIMEOUT`
+//   • real connector targets ← `converge`/`converge-merge`/`merge-main` (app/convergeTargets.ts)
+// The prose (body contracts, what each probe OBSERVES, the poll-budget trap, fact-threading) is
+// co-located here; `app/deliveryGraphVocabulary.test.ts` is the drift guard — it fails the build if a
+// probe kind / connector target / node kind is added to the compiler without a vocabulary entry.
+import {
+  CONVERGE_MERGE_TARGET,
+  CONVERGE_TARGET,
+  convergeOnlyForTarget,
+  MERGE_MAIN_TARGET,
+} from "./convergeTargets.ts";
+import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
+import {
+  DEFAULT_EVERY_MS,
+  DEFAULT_READINESS_TIMEOUT,
+  DEFAULT_TIMEOUT_MS,
+  EPIC_CONDITIONS,
+  ON_TIMEOUTS,
+  PR_CONDITIONS,
+  PROBE_KINDS,
+} from "./readiness.ts";
+
+/** A node-kind entry: the closed `kind`, its per-kind config key + required/optional body fields, and
+ * whether it is side-effecting / may emit facts. `body` names the executable engine-native surface the
+ * graph layer schedules onto (the graph layer does NOT re-implement execution). */
+export interface NodeKindEntry {
+  kind: string;
+  configKey: string;
+  requiredFields: string[];
+  optionalFields: string[];
+  sideEffecting: boolean;
+  mayEmit: boolean;
+  summary: string;
+}
+
+/** A wait-probe entry: the closed `kind`, the `match` fields it reads, and — crucially — WHAT it
+ * OBSERVES (the read that decides readiness) and WHEN it is ready. */
+export interface WaitProbeEntry {
+  kind: string;
+  target: string;
+  matchFields: string[];
+  conditions?: string[];
+  observes: string;
+  ready: string;
+  binds?: string[];
+}
+
+/** A connector target: whether it is a REAL side-effecting target (a converge-enrollment target that
+ * dispatches through `submitPr`) or a FORWARD-DECLARED stub (the connector I/O surface is an ADR 0005
+ * non-goal — an unrecognised target returns a deterministic acknowledgement and performs no I/O). */
+export interface ConnectorTargetEntry {
+  target: string;
+  status: "real" | "forward-declared";
+  convergeOnlyDefault?: boolean;
+  summary: string;
+}
+
+/** An `onTimeout` option: what the bounded wait does when the engine timer arm fires. */
+export interface OnTimeoutEntry {
+  value: string;
+  meaning: string;
+}
+
+/** The whole structured vocabulary the read tool returns. */
+export interface DeliveryGraphVocabulary {
+  adr: string;
+  summary: string;
+  nodeKinds: NodeKindEntry[];
+  factTypes: string[];
+  guardScalarTypes: string[];
+  waitProbeKinds: WaitProbeEntry[];
+  connectorTargets: ConnectorTargetEntry[];
+  onTimeout: OnTimeoutEntry[];
+  pollBudget: {
+    defaultTimeoutMs: number;
+    defaultTimeoutIso: string;
+    defaultEveryMs: number;
+    rule: string;
+  };
+  factThreading: {
+    rule: string;
+    details: string[];
+  };
+  guideSection: string;
+}
+
+// ── Node kinds (DERIVED from DELIVERY_NODE_KINDS — the closed allowlist / trust boundary) ─────────
+const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
+  agent: {
+    configKey: "agent",
+    requiredFields: ["jobType"],
+    optionalFields: ["prompt", "converge", "merge"],
+    sideEffecting: true,
+    mayEmit: true,
+    summary:
+      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`). 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 `agent` that opens a PR emits it as a `pr`-typed fact so downstream connector/wait nodes late-bind it.",
+  },
+  wait: {
+    configKey: "wait",
+    requiredFields: ["kind", "target"],
+    optionalFields: ["match", "poll", "onTimeout", "credentialEnv"],
+    sideEffecting: false,
+    mayEmit: true,
+    summary:
+      "A durable, bounded, read-only readiness probe (a `ReadinessProbe` verbatim). `wait.kind` selects " +
+      "the probe (see waitProbeKinds); `poll` is `{ everyMs?, timeoutMs?, backoff? }`. Binds observed " +
+      "facts (e.g. a merged `pr` binds `mergedSha`).",
+  },
+  human: {
+    configKey: "human",
+    requiredFields: [],
+    optionalFields: ["formKey", "prompt"],
+    sideEffecting: false,
+    mayEmit: true,
+    summary:
+      "A scheduled user task + form (the Tasks inbox). Blocks dependents, SLA-bounded, answerable by a " +
+      "human OR an agent. Config is optional (no required field).",
+  },
+  connector: {
+    configKey: "connector",
+    requiredFields: ["target"],
+    optionalFields: ["dedupeKey", "payload"],
+    sideEffecting: true,
+    mayEmit: true,
+    summary:
+      "An automated, side-effecting outbound action. `payload` for a converge target is " +
+      "`{ pr, convergeOnly?, 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.",
+  },
+};
+
+// ── Wait probe kinds (DERIVED from PROBE_KINDS — what `parseProbe` accepts) ───────────────────────
+const WAIT_PROBE_DETAIL: Record<string, Omit<WaitProbeEntry, "kind">> = {
+  http: {
+    target: "a URL",
+    matchFields: ["status", "bodyIncludes"],
+    observes: "an HTTP GET against `target` (optional `credentialEnv` supplies an Authorization credential by env-key name).",
+    ready: "the response status matches `match.status` (default: any 2xx) and the body contains `match.bodyIncludes` if set.",
+  },
+  command: {
+    target: "a shell command",
+    matchFields: ["exitCode", "stdoutIncludes"],
+    observes: "running `target` as a subprocess (the escape hatch for the long tail — `gh`, `curl`, `docker manifest inspect`).",
+    ready: "the exit code matches `match.exitCode` (default 0) and stdout contains `match.stdoutIncludes` if set.",
+  },
+  npm: {
+    target: "a `pkg@version` (or bare `pkg`)",
+    matchFields: ["version", "stdoutIncludes"],
+    observes: "the npm registry for a published version of the package.",
+    ready: "`match.version` (default: the version in `pkg@version`) is published.",
+  },
+  "github-check": {
+    target: "an `owner/repo@ref`",
+    matchFields: ["conclusion", "checkName"],
+    observes: "the GitHub check runs on `ref`.",
+    ready: "the check run's conclusion matches `match.conclusion` (default `success`), restricted to `match.checkName` if set.",
+  },
+  capability: {
+    target: "a package/context handle",
+    matchFields: ["capabilityRef", "package", "verifyCommand"],
+    observes:
+      "the publish-provenance substrate: which published `package` version first carries the `capabilityRef` " +
+      "issue/PR — an optional `verifyCommand` runs once at the poll-budget boundary as a gated empirical fallback.",
+    ready: "a published version of `match.package` carries `match.capabilityRef` in its provenance.",
+    binds: ["resolvedArtifact"],
+  },
+  pr: {
+    target: "an `owner/repo#N` PR (or a `<node>.pr` fact reference the compiler late-binds at dispatch)",
+    matchFields: ["prState"],
+    conditions: [...PR_CONDITIONS],
+    observes:
+      "the live GitHub state of a single in-flight PR. The ACTION (landing it) stays in a connector/merge " +
+      "node body; this kind only OBSERVES, so it is level-triggered (no missed edge).",
+    ready: "the PR reaches `match.prState` (default `merged`; one of the pr conditions).",
+    binds: ["mergedSha"],
+  },
+  epic: {
+    target:
+      "the epic's durable `planKey` — `owner/repo#NN`, the epic ISSUE, not the engine processInstanceKey, " +
+      "so a resubmit/replay still resolves (may also be a `<node>.fact` late-binding reference)",
+    matchFields: ["epicState"],
+    conditions: [...EPIC_CONDITIONS],
+    observes:
+      "the app's OWN lineage read-model (`/lineage?root=<planKey>`), resolved by `parseEpicLineage` to the " +
+      "thread whose `rootRequestKey` matches the planKey — REGARDLESS OF the thread's `kind` (feature | epic | " +
+      "pr | delivery). Because `app/lineage.ts` lands a FEATURE thread on `stage:\"merged\"` once its PR merges, " +
+      "`wait[epic]` gates a single-PR FEATURE RUN just as well as a plan-fanout epic: point `target` at the " +
+      "feature/epic root issue and it observes that thread's aggregate frontier. A failed/abandoned/mixed epic " +
+      "settles on another terminal (`abandoned`/`resolved`/`converged`) and never reports merged, so it never " +
+      "falsely releases the gate — the bounded wait routes via `onTimeout` instead of hanging.",
+    ready: "the lineage thread reaches `stage:\"merged\" && active:false` (every opened slice/PR landed). `match.epicState` (default `merged`; `done` is a synonym) both mean \"fully merged\".",
+    binds: ["prCount"],
+  },
+};
+
+// ── Connector targets (real = the converge-enrollment set from convergeTargets.ts) ────────────────
+const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
+  {
+    target: CONVERGE_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_TARGET),
+    summary: "Converge-only: drive review convergence and STOP at `converged`, never handing off to the merge loop.",
+  },
+  {
+    target: CONVERGE_MERGE_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
+    summary:
+      "Unit-level land: drive review convergence AND the merge loop, landing the PR onto its OWN base branch " +
+      "(for a unit inside an epic that base is the epic integration branch, never `main` directly).",
+  },
+  {
+    target: MERGE_MAIN_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(MERGE_MAIN_TARGET),
+    summary:
+      "Graph-level top-level land (two-level merge, ADR 0006 §3): land the graph/epic INTEGRATION PR onto `main`. " +
+      "Dispatch-identical to `converge-merge`; the distinction is the LEVEL, kept a first-class literal.",
+  },
+];
+
+/** The sentinel that describes ANY non-converge target: the connector I/O surface is forward-declared
+ * (ADR 0005 non-goal), so an unrecognised `target` hits the default stub action and performs no real
+ * side effect. Included so a caller learns the real-vs-stub split without reading `deliveryConnector.ts`. */
+const FORWARD_DECLARED_ENTRY: ConnectorTargetEntry = {
+  target: "<any other target>",
+  status: "forward-declared",
+  summary:
+    "Forward-declared stub: the concrete connector I/O scheme is an ADR 0005 non-goal. A target outside the " +
+    "converge-enrollment set returns a deterministic acknowledgement (`connector stub — I/O surface " +
+    "forward-declared`) and fires NO real side effect until a real action is injected.",
+};
+
+const ON_TIMEOUT_DETAIL: Record<string, string> = {
+  escalate: "park a human-in-the-loop escalation (the Tasks inbox) when the bounded wait elapses; a human/agent decides whether to extend the budget or abandon.",
+  fail: "terminate the gate as failed. NOTE: not yet supported on a `wait` node (blocked on engine terminate-end wiring); the compiler rejects `onTimeout: fail` on a wait.",
+  continue: "proceed as if ready when the wait elapses — use ONLY when downstream can tolerate a not-yet-ready upstream (a soft gate).",
+};
+
+/** Build the structured delivery-graph vocabulary. Pure — no I/O; every closed set is imported from
+ * its owning module so this can never silently drift from what the compiler/runner actually accept. */
+export function deliveryGraphVocabulary(): DeliveryGraphVocabulary {
+  const nodeKinds: NodeKindEntry[] = DELIVERY_NODE_KINDS.map((kind) => {
+    const detail = NODE_KIND_DETAIL[kind];
+    if (!detail) throw new Error(`deliveryGraphVocabulary: no detail for node kind '${kind}' (drift — extend NODE_KIND_DETAIL)`);
+    return { kind, ...detail };
+  });
+
+  const waitProbeKinds: WaitProbeEntry[] = PROBE_KINDS.map((kind) => {
+    const detail = WAIT_PROBE_DETAIL[kind];
+    if (!detail) throw new Error(`deliveryGraphVocabulary: no detail for wait probe kind '${kind}' (drift — extend WAIT_PROBE_DETAIL)`);
+    return { kind, ...detail };
+  });
+
+  return {
+    adr: "ADR 0005 — agent-authored delivery graphs",
+    summary:
+      "A delivery graph is a JSON DAG `{ name?, nodes[], edges[] }` an agent authors as DATA (never BPMN/code — " +
+      "the closed node vocabulary is the trust boundary). The agent surface ends at propose → compile → stage; " +
+      "DISPATCH is an operator-only cockpit action. This tool surfaces the closed vocabulary + the non-obvious " +
+      "wait/poll/fact-threading semantics so they are discoverable, not source-only.",
+    nodeKinds,
+    factTypes: [...DELIVERY_FACT_TYPES],
+    guardScalarTypes: [...DELIVERY_GUARD_SCALAR_TYPES],
+    waitProbeKinds,
+    connectorTargets: [...REAL_CONNECTOR_TARGETS, FORWARD_DECLARED_ENTRY],
+    onTimeout: ON_TIMEOUTS.map((value) => {
+      const meaning = ON_TIMEOUT_DETAIL[value];
+      if (!meaning) throw new Error(`deliveryGraphVocabulary: no meaning for onTimeout '${value}' (drift — extend ON_TIMEOUT_DETAIL)`);
+      return { value, meaning };
+    }),
+    pollBudget: {
+      defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+      defaultTimeoutIso: DEFAULT_READINESS_TIMEOUT,
+      defaultEveryMs: DEFAULT_EVERY_MS,
+      rule:
+        `POLL-BUDGET TRAP: an omitted \`poll\`/\`poll.timeoutMs\` inherits the built-in default budget of ` +
+        `${DEFAULT_READINESS_TIMEOUT} (${DEFAULT_TIMEOUT_MS} ms), re-probing every ${DEFAULT_EVERY_MS} ms. ` +
+        `That default is right for "is the package published yet" but badly wrong for \`wait[pr, merged]\` / ` +
+        `\`wait[epic]\`, which routinely wait hours or days — such a gate would escalate after 30 minutes for ` +
+        `no visible reason (neither compile nor preview surfaces the effective bound). ALWAYS set a realistic ` +
+        `\`poll.timeoutMs\` explicitly on any merge or epic gate.`,
+    },
+    factThreading: {
+      rule:
+        "A node's emitted `fact` is carried to a consumer ONLY by an EDGE. An edge `from` is either a bare " +
+        "`<nodeId>` (the node's completion fact) or a qualified `<nodeId>.<fact>` referencing a declared `emits`. " +
+        "A node that references a fact (e.g. a connector/`wait[pr]` late-binding `open.pr`) MUST have an incoming " +
+        "edge threading that fact from every producer — an unthreaded reference is rejected (`unbound-pr`).",
+      details: [
+        "The referenced fact must be declared in the producer's `emits[]` with the right `type` (a `pr` reference must be `pr`-typed).",
+        "A connector `payload` may OMIT `pr` to auto-bind the SINGLE incoming `pr` fact; with two `pr` facts flowing in you must name one.",
+        "Only scalar facts (`string`/`number`/`boolean`) may be referenced by an edge `when` guard; `artifact`/`version`/`url`/`pr` are not guardable.",
+        "The whole edge set must be a DAG; a self-edge or cycle is rejected.",
+      ],
+    },
+    guideSection: "docs/agent-guide.md §9 (Author and run a delivery graph)",
+  };
+}

package/app/readiness.ts

@@ -56,11 +56,16 @@ export type OnTimeout = "escalate" | "fail" | "continue";
 /** Backoff policy between poll attempts. */
 export type Backoff = "fixed" | "exponential";
 
-const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
-const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
-const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
-const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
-const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
+// The CLOSED per-field vocabularies `parseProbe` validates against — the single runtime source of
+// truth for "which probe kinds / onTimeout options / conditions are legal". Exported so the
+// delivery-graph vocabulary surface (`app/deliveryGraphVocabulary.ts`, S3/#609) DERIVES its
+// structured description from these exact arrays and a drift test fails the build if a kind/condition
+// is added here without a matching vocabulary entry (AGENTS.md: no drift surfaces).
+export const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
+export const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
+export const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
+export const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
+export const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
 
 /** The per-kind readiness predicate. Every field is optional; each kind reads only the ones it
  * understands and applies a sensible default when a field is absent (see the matchers below). */

package/docs/agent-guide.md

@@ -412,6 +412,15 @@ PR #202 → a human does a manual OTP publish → PR #303 consumes the just-publ
 **delivery graph** ([ADR 0005](https://github.com/nanobpm/nano-workforce/blob/main/docs/adr/0005-agent-authored-delivery-graphs.md))
 lets you compose exactly that as **data** and hand it to a generic runner.
 
+> **Discover the vocabulary from the surface.** Everything this section describes — the four
+> node kinds and their body contracts, every `wait` probe kind and **what it observes**, the
+> real-vs-stub connector targets, the `onTimeout` options, the poll-budget trap, and the
+> fact-threading rules — is also available as **structured JSON** from the read tool
+> **`getDeliveryGraphVocabulary`** (`GET __BASE__/delivery-graph/vocabulary`). It is derived
+> from the implementing code (a drift test fails the build if the two disagree), so prose and
+> data can never drift. Fetch it to author against the live vocabulary; this section is the
+> narrative companion.
+
 You author the graph as **JSON — never BPMN or code** (Decision 1: the agent must never
 author the executable artifact; the closed node vocabulary is the trust boundary). Your
 surface ends at **propose → compile → stage**: a single `compile` door validates the JSON,
@@ -741,3 +750,9 @@ Semantics:
   B before its dependency merged. Size `timeoutMs` to how long the epic realistically takes.
 - On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
   output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).
+- **It also gates a single-PR *feature run*, not just a plan-fanout epic.** The gate resolves the
+  lineage thread whose **`rootRequestKey`** matches `target` **regardless of the thread's `kind`**
+  (`feature` | `epic` | `pr` | `delivery`), and `app/lineage.ts` lands a *feature* thread on
+  `stage:"merged"` once its PR merges. So `wait[epic]` targeting a feature/epic **root issue**
+  observes that thread's aggregate frontier and releases on `stage:"merged" && active:false` either
+  way — see `getDeliveryGraphVocabulary` (the `epic` probe entry) for the structured contract.

package/openapi.yaml

@@ -4064,6 +4064,262 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /delivery-graph/vocabulary:
+    get:
+      operationId: getDeliveryGraphVocabulary
+      summary: The closed delivery-graph vocabulary + wait-probe semantics as structured JSON (ADR 0005).
+      description: >-
+        Read tool (projected onto the MCP surface like `getAgentInstructions`). Returns the CLOSED
+        delivery-graph vocabulary and the non-obvious wait/poll/fact-threading semantics as structured
+        JSON, so you can discover them from the surface instead of reading source. Covers: the four node
+        kinds (`agent`/`wait`/`human`/`connector`) with their per-kind body contracts; every wait probe
+        kind with its `match` fields and — crucially — WHAT it OBSERVES (e.g. `epic` resolves a lineage
+        thread by `rootRequestKey` REGARDLESS of the thread's kind, so it gates plan-fanout epics AND
+        single-PR feature runs alike, ready on `stage:"merged" && active:false`); which connector targets
+        are real (`converge`/`converge-merge`/`merge-main`) vs. forward-declared stubs; the `onTimeout`
+        options; the poll-budget rule (always set a realistic `poll.timeoutMs` on merge/epic gates — the
+        30-minute default is a trap); and the edge/fact-threading rules (a `node.fact` must be threaded by
+        an edge to every consumer, else `unbound-pr`). Derived from the implementing code (a drift test
+        fails the build if a probe kind / connector target is added without a vocabulary entry). Pure,
+        read-only, idempotent — no side effects. Pairs with `compileDeliveryGraph`/`previewDeliveryGraph`:
+        call this first to learn the vocabulary, then author a `DeliveryGraph` and compile it.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The full delivery-graph vocabulary.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                description: The closed delivery-graph vocabulary + wait-probe semantics, derived from the compiler/runner code.
+                required:
+                  - adr
+                  - summary
+                  - nodeKinds
+                  - factTypes
+                  - guardScalarTypes
+                  - waitProbeKinds
+                  - connectorTargets
+                  - onTimeout
+                  - pollBudget
+                  - factThreading
+                properties:
+                  adr:
+                    type: string
+                    description: The governing ADR (agent-authored delivery graphs).
+                  summary:
+                    type: string
+                    description: One-paragraph orientation on the graph shape and the propose→compile→stage surface.
+                  nodeKinds:
+                    type: array
+                    description: The closed node-kind allowlist with each kind's config key and body contract.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [kind, configKey, requiredFields, optionalFields, sideEffecting, mayEmit, summary]
+                      properties:
+                        kind:
+                          type: string
+                          description: The node kind (one of agent | wait | human | connector).
+                        configKey:
+                          type: string
+                          description: The per-kind config object key the node must carry.
+                        requiredFields:
+                          type: array
+                          items: { type: string }
+                          description: Required non-empty fields inside the per-kind config.
+                        optionalFields:
+                          type: array
+                          items: { type: string }
+                          description: Optional fields inside the per-kind config.
+                        sideEffecting:
+                          type: boolean
+                          description: Whether the node performs a side effect (agent/connector) vs. read-only (wait/human).
+                        mayEmit:
+                          type: boolean
+                          description: Whether the node may declare typed emits.
+                        summary:
+                          type: string
+                          description: The body contract / semantics of the kind.
+                  factTypes:
+                    type: array
+                    items: { type: string }
+                    description: The closed emitted-fact type allowlist.
+                  guardScalarTypes:
+                    type: array
+                    items: { type: string }
+                    description: The scalar fact types an edge `when` guard may reference.
+                  waitProbeKinds:
+                    type: array
+                    description: Every wait probe kind, its match fields, and what it observes / when it is ready.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [kind, target, matchFields, observes, ready]
+                      properties:
+                        kind:
+                          type: string
+                          description: The probe kind (http | command | npm | github-check | capability | pr | epic).
+                        target:
+                          type: string
+                          description: What the probe's `target` names.
+                        matchFields:
+                          type: array
+                          items: { type: string }
+                          description: The `match` fields this kind reads.
+                        conditions:
+                          type: array
+                          items: { type: string }
+                          description: The closed condition set for pr/epic kinds (else absent).
+                        observes:
+                          type: string
+                          description: The read that decides readiness (what the probe actually observes).
+                        ready:
+                          type: string
+                          description: The condition under which the probe reports ready.
+                        binds:
+                          type: array
+                          items: { type: string }
+                          description: Output facts the probe binds on a ready match.
+                  connectorTargets:
+                    type: array
+                    description: Which connector targets are real (converge-enrollment) vs. forward-declared stubs.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [target, status, summary]
+                      properties:
+                        target:
+                          type: string
+                          description: The connector target literal (or a sentinel for any other target).
+                        status:
+                          type: string
+                          enum: [real, forward-declared]
+                          description: real ⇒ dispatches a real side effect; forward-declared ⇒ a no-op stub.
+                        convergeOnlyDefault:
+                          type: boolean
+                          description: The default `convergeOnly` for a real converge target.
+                        summary:
+                          type: string
+                          description: What the target does.
+                  onTimeout:
+                    type: array
+                    description: The `onTimeout` options for a bounded wait and what each does.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [value, meaning]
+                      properties:
+                        value: { type: string }
+                        meaning: { type: string }
+                  pollBudget:
+                    type: object
+                    additionalProperties: false
+                    required: [defaultTimeoutMs, defaultTimeoutIso, defaultEveryMs, rule]
+                    description: The poll-budget defaults and the "always set poll.timeoutMs on merge/epic gates" rule.
+                    properties:
+                      defaultTimeoutMs: { type: number }
+                      defaultTimeoutIso: { type: string }
+                      defaultEveryMs: { type: number }
+                      rule: { type: string }
+                  factThreading:
+                    type: object
+                    additionalProperties: false
+                    required: [rule, details]
+                    description: The edge/fact-threading rules — a node.fact reaches a consumer only via an edge.
+                    properties:
+                      rule: { type: string }
+                      details:
+                        type: array
+                        items: { type: string }
+                  guideSection:
+                    type: string
+                    description: The operator-guide section this data mirrors (docs/agent-guide.md §9).
+                example:
+                  adr: "ADR 0005 — agent-authored delivery graphs"
+                  summary: "A delivery graph is a JSON DAG an agent authors as DATA; the surface ends at propose → compile → stage."
+                  nodeKinds:
+                    - kind: agent
+                      configKey: agent
+                      requiredFields: [jobType]
+                      optionalFields: [prompt, converge, merge]
+                      sideEffecting: true
+                      mayEmit: true
+                      summary: "A worker runs an agent job type; an agent that opens a PR emits it as a `pr` fact."
+                    - kind: wait
+                      configKey: wait
+                      requiredFields: [kind, target]
+                      optionalFields: [match, poll, onTimeout, credentialEnv]
+                      sideEffecting: false
+                      mayEmit: true
+                      summary: "A durable, bounded, read-only readiness probe (a ReadinessProbe verbatim)."
+                    - kind: connector
+                      configKey: connector
+                      requiredFields: [target]
+                      optionalFields: [dedupeKey, payload]
+                      sideEffecting: true
+                      mayEmit: true
+                      summary: "An automated outbound action; payload for a converge target is { pr, convergeOnly?, dependsOn? }."
+                  factTypes: [string, number, boolean, artifact, version, url, pr]
+                  guardScalarTypes: [string, number, boolean]
+                  waitProbeKinds:
+                    - kind: pr
+                      target: "an owner/repo#N PR (or a <node>.pr fact reference)"
+                      matchFields: [prState]
+                      conditions: [ready, merged, mergeable, checks-green]
+                      observes: "the live GitHub state of one in-flight PR; only OBSERVES, level-triggered."
+                      ready: "the PR reaches match.prState (default merged)."
+                      binds: [mergedSha]
+                    - kind: epic
+                      target: "the epic's durable planKey (owner/repo#NN, the epic issue)"
+                      matchFields: [epicState]
+                      conditions: [merged, done]
+                      observes: "the app's lineage read-model, resolved by rootRequestKey REGARDLESS of thread kind (feature | epic | pr | delivery) — so it gates a single-PR FEATURE RUN just as well as a plan-fanout epic."
+                      ready: 'the lineage thread reaches stage:"merged" && active:false (every opened slice/PR landed).'
+                      binds: [prCount]
+                  connectorTargets:
+                    - target: converge
+                      status: real
+                      convergeOnlyDefault: true
+                      summary: "Converge-only: drive review convergence and stop at converged."
+                    - target: converge-merge
+                      status: real
+                      convergeOnlyDefault: false
+                      summary: "Unit-level land: converge AND merge onto the PR's own base branch."
+                    - target: merge-main
+                      status: real
+                      convergeOnlyDefault: false
+                      summary: "Graph-level top-level land onto main (two-level merge)."
+                    - target: "<any other target>"
+                      status: forward-declared
+                      summary: "Forward-declared stub — returns a deterministic acknowledgement, fires no real I/O."
+                  onTimeout:
+                    - value: escalate
+                      meaning: "park a human escalation when the bounded wait elapses."
+                    - value: fail
+                      meaning: "terminate the gate as failed (NOT yet supported on a wait node — rejected by the compiler)."
+                    - value: continue
+                      meaning: "proceed as if ready when the wait elapses (a soft gate)."
+                  pollBudget:
+                    defaultTimeoutMs: 1800000
+                    defaultTimeoutIso: PT30M
+                    defaultEveryMs: 15000
+                    rule: "An omitted poll.timeoutMs inherits the 30-minute default — a trap for wait[pr, merged]/wait[epic] which wait hours/days. Always set poll.timeoutMs explicitly on a merge/epic gate."
+                  factThreading:
+                    rule: "A node's emitted fact reaches a consumer ONLY via an edge (<nodeId>.<fact>); an unthreaded reference is rejected (unbound-pr)."
+                    details:
+                      - "The referenced fact must be declared in the producer's emits[] with the right type."
+                      - "A connector payload may omit pr to auto-bind the single incoming pr fact."
+                  guideSection: "docs/agent-guide.md §9 (Author and run a delivery graph)"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/delivery-graph/library/save:
     post:
       operationId: saveToLibrary

package/operations/getDeliveryGraphVocabulary.ts

@@ -0,0 +1,25 @@
+// GET /app/api/delivery-graph/vocabulary → operationId `getDeliveryGraphVocabulary` (epic
+// nano-workforce#605, S3/#609). A read tool — projected onto the MCP surface like
+// `getAgentInstructions` — that returns the closed delivery-graph vocabulary + wait-probe semantics
+// as STRUCTURED JSON, so an agent can discover the node/probe/connector vocabulary and the non-obvious
+// wait/poll/fact-threading rules from the surface instead of reading source (ADR 0005).
+//
+// The payload is derived from the implementing code (`app/deliveryGraphVocabulary.ts`) — every closed
+// set is imported from its owning module, and a drift test fails the build if a probe kind / connector
+// target lands in the compiler without a vocabulary entry. Cross-linked from docs/agent-guide.md §9.
+//
+// Read-only. The optional shared-secret guard mirrors /agent and /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+import { deliveryGraphVocabulary } from "../app/deliveryGraphVocabulary.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getDeliveryGraphVocabulary", ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getDeliveryGraphVocabulary rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  return { status: 200, body: deliveryGraphVocabulary() };
+});

package/package.json

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

@@ -0,0 +1,62 @@
+// test/deliveryGraphVocabulary-mcp.test.ts — S3/#609 surface guard.
+//
+// Verifies the `getDeliveryGraphVocabulary` READ tool is actually VISIBLE to agents over MCP (the
+// Urban runtime projects `openapi.yaml` into MCP tools, ADR 0067 — zero MCP server code in nwf) and
+// that its operation conforms to S0's self-contained convention: a `$ref`-free `200` response schema
+// with an explicit `type: object` and a worked `example`. Drives the REAL projector (`collectOperations`
+// from `@nanobpm/urban/toolkit`) over the checked-in spec, exactly like `test/mcp-tool-schemas.test.ts`,
+// so a regression (the op excluded, or a re-leaked `$ref`/dropped example) fails the build.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { collectOperations, parseSpec } from "@nanobpm/urban/toolkit";
+import { parse as parseYaml } from "yaml";
+import assert from "node:assert/strict";
+import { deliveryGraphVocabulary } from "../app/deliveryGraphVocabulary.ts";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+const SPEC_TEXT = readFileSync(`${ROOT}openapi.yaml`, "utf8");
+const SPEC = parseSpec(SPEC_TEXT);
+const OP_ID = "getDeliveryGraphVocabulary";
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Every `$ref` reachable in a schema, JSON-path-qualified for the failure message. */
+function findRefs(node: unknown, path: string, out: string[]): void {
+  if (Array.isArray(node)) {
+    node.forEach((n, i) => findRefs(n, `${path}[${i}]`, out));
+    return;
+  }
+  if (!isRecord(node)) return;
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "$ref" && typeof v === "string") out.push(`${path}.$ref -> ${v}`);
+    else findRefs(v, `${path}.${k}`, out);
+  }
+}
+
+test("getDeliveryGraphVocabulary is projected onto the MCP tool surface (not excluded)", () => {
+  const op = collectOperations(SPEC).find((o) => o.operationId === OP_ID);
+  assert(op, `${OP_ID} must be a declared operation the projector can see`);
+  assert(!op!.mcpExcluded, `${OP_ID} must be visible over MCP (no x-mcp exclusion)`);
+});
+
+test("the getDeliveryGraphVocabulary 200 response schema is $ref-free with an explicit type + example", () => {
+  const doc = parseYaml(SPEC_TEXT) as Record<string, any>;
+  const schema = doc?.paths?.["/delivery-graph/vocabulary"]?.get?.responses?.["200"]?.content?.["application/json"]?.schema;
+  assert(isRecord(schema), "the 200 response must carry an inline application/json schema");
+  assert.equal(schema.type, "object", "the response schema must declare an explicit type: object");
+  assert("example" in schema, "the response schema must embed a worked example (S0 self-contained convention)");
+  const refs: string[] = [];
+  findRefs(schema, `${OP_ID}.responses.200`, refs);
+  assert(refs.length === 0, `${OP_ID}: 200 response schema leaks $ref(s): ${refs.join(", ")}`);
+});
+
+test("the served payload matches the response schema's required keys (data ⇄ contract)", () => {
+  const doc = parseYaml(SPEC_TEXT) as Record<string, any>;
+  const schema = doc.paths["/delivery-graph/vocabulary"].get.responses["200"].content["application/json"].schema;
+  const required: string[] = schema.required ?? [];
+  const payload = deliveryGraphVocabulary() as Record<string, unknown>;
+  for (const key of required) {
+    assert(key in payload, `served vocabulary is missing required schema key '${key}'`);
+  }
+});