@nanobpm/nano-workforce 0.109.0 → 0.111.0

package/app/readiness.ts

@@ -18,14 +18,28 @@
 // any credential is read at execution time from the typed env-contract (`credentialEnv` names a
 // declared {@link EnvKey}; ADR 0004 pinned decision 2) and is redacted from every log line.
 import { isEnvKey, readEnv, readEnvOr } from "./contracts.ts";
+import { allCheckNames, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
 import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
 
 /** The built-in readiness sources. `command` is the escape hatch that subsumes the long tail
  * (`gh`, `curl`, `docker manifest inspect`, a custom probe) — adding a first-class kind later is
  * an additive matcher, not a schema change. `capability` is the first such additive kind (#274):
  * it resolves "which published version first carries capability C?" from the publish-provenance
- * substrate and binds the discovered `pkg@version` back through the gate (see {@link matchCapability}). */
-export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capability";
+ * substrate and binds the discovered `pkg@version` back through the gate (see {@link matchCapability}).
+ * `pr` (ADR 0005 §2) is the merge-state kind: it lifts the PR-liveness/mergeability READ out of the
+ * merge loop (`app/mergeProtocol.ts` / `app/github.ts`) into a first-class probe so "watch an
+ * in-flight PR reach a declared state" is a graph edge, not logic buried in the merge-loop node
+ * body — the ACTION (landing the PR) stays in that node body; this kind only OBSERVES. */
+export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capability" | "pr";
+
+/** The declared PR state a `pr` probe waits for (ADR 0005 §2). Each is a discovered fact about an
+ * in-flight PR, read from its live GitHub state and evaluated by {@link matchPr}:
+ *   • `ready`        — the PR is out of draft (the draft→ready transition is observable).
+ *   • `merged`       — the PR has landed; binds `mergedSha` (the merge commit) as an output.
+ *   • `mergeable`    — GitHub reports the PR as landable now ({@link classifyMergeability} `ready`:
+ *                      CLEAN/HAS_HOOKS/UNSTABLE/BEHIND — required review + checks satisfied).
+ *   • `checks-green` — every head check run is complete with none failing (required checks green). */
+export type PrCondition = "ready" | "merged" | "mergeable" | "checks-green";
 
 /** What the gate does when the bounded wait times out (the engine timer arm fires). */
 export type OnTimeout = "escalate" | "fail" | "continue";
@@ -33,9 +47,10 @@ 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"];
+const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr"];
 const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
 const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
+const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
 
 /** 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). */
@@ -66,6 +81,9 @@ export interface ProbeMatch {
    * unset, the capability edge is deterministic-only. The resolved `pkg@version` and bare version
    * are exposed to the command as `RESOLVED_ARTIFACT` / `RESOLVED_VERSION`. */
   readonly verifyCommand?: string;
+  /** pr: the declared PR state the probe waits for (default `merged`). One of {@link PrCondition} —
+   * `ready` (out of draft), `merged`, `mergeable`, or `checks-green`. */
+  readonly prState?: PrCondition;
 }
 
 /** The poll cadence: how often to re-probe, how long to keep trying, and the backoff shape. */
@@ -207,6 +225,13 @@ export function parseProbe(raw: unknown): ReadinessProbe {
       throw new Error("readiness probe (capability): 'match.package' is required (provenance is per-package scoped)");
     }
   }
+  // A pr edge whose target names no numeric PR id can never resolve — fail loudly at parse (mirroring
+  // the capability ref guard) rather than surface it as a timeout much later. `owner/repo#123`.
+  if (kind === "pr" && !parsePrTarget(target)) {
+    throw new Error(
+      `readiness probe (pr): 'target' ('${target}') must be an 'owner/repo#<number>' PR reference (e.g. 'nanobpm/nano-workforce#377')`,
+    );
+  }
   const poll = isRecord(raw.poll) ? parsePoll(raw.poll) : undefined;
   const credentialEnv = str(raw.credentialEnv).trim() || undefined;
   if (credentialEnv !== undefined && !isEnvKey(credentialEnv)) {
@@ -259,9 +284,27 @@ function parseMatch(raw: Record<string, unknown>): ProbeMatch {
     capabilityRef: str(raw.capabilityRef).trim() || undefined,
     package: str(raw.package).trim() || undefined,
     verifyCommand: str(raw.verifyCommand).trim() || undefined,
+    prState: parsePrCondition(raw.prState),
   };
 }
 
+/** Narrow a raw `match.prState` to a {@link PrCondition}, throwing on a non-empty unknown value so a
+ * mistyped state (`"landed"` for `"merged"`) fails loudly at parse rather than waiting forever. An
+ * absent/blank value yields undefined — `matchPr` then applies the `merged` default. */
+function parsePrCondition(raw: unknown): PrCondition | undefined {
+  const s = str(raw).trim();
+  if (s === "") return undefined;
+  if (!isPrCondition(s)) {
+    throw new Error(`readiness probe (pr): invalid match.prState '${s}' (expected one of ${PR_CONDITIONS.join(", ")})`);
+  }
+  return s;
+}
+
+function isPrCondition(v: string): v is PrCondition {
+  for (const c of PR_CONDITIONS) if (c === v) return true;
+  return false;
+}
+
 function parsePoll(raw: Record<string, unknown>): ProbePoll {
   const backoffRaw = str(raw.backoff).trim();
   if (backoffRaw !== "" && !isBackoff(backoffRaw)) {
@@ -485,6 +528,116 @@ export function githubReleasesCommand(repo: string): string {
   return `gh api --paginate --slurp ${shellQuote(`repos/${repo}/releases?per_page=100`)} -H ${shellQuote("Accept: application/vnd.github+json")}`;
 }
 
+// ── PR / merge-state probe (ADR 0005 §2 — lift the merge-loop READ into a first-class probe) ─────
+
+/** A live PR observation, reduced to the fields {@link matchPr} reads. It extends the shared
+ * {@link PrState} (so `classifyMergeability` and the merge loop's liveness vocabulary are reused
+ * verbatim, never re-derived) and adds `mergedSha`, the merge commit oid a `merged` match binds
+ * downstream. Kept separate from I/O — {@link parsePrView} builds it from an already-fetched
+ * `gh pr view --json …` payload — so the matcher stays pure/unit-testable, exactly like
+ * {@link GithubRelease}. */
+export interface PrObservation extends PrState {
+  /** The merge commit oid once landed (`gh pr view --json mergeCommit`), else null. */
+  readonly mergedSha: string | null;
+  /** Count of head checks still in flight (queued/in progress), so a `checks-green` gate never
+   * reports green while a run hasn't concluded. Derived via `pendingCheckNames`. */
+  readonly pendingChecks: number;
+}
+
+/** Parse a raw `gh pr view --json state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,mergeCommit`
+ * payload (already JSON-decoded) into a {@link PrObservation}. Reuses the SAME check-rollup readers
+ * as `fetchPrState` (`failingCheckNames`/`allCheckNames`) so a superseded/cancelled run is collapsed
+ * identically. Tolerant: a malformed/empty payload yields an all-open, no-checks observation, so a
+ * transient read degrades to "not ready" (keep waiting), never a throw. */
+export function parsePrView(payload: unknown): PrObservation {
+  const j = isRecord(payload) ? payload : {};
+  const rollup = Array.isArray(j.statusCheckRollup) ? j.statusCheckRollup : [];
+  const names = failingCheckNames(rollup);
+  const pending = pendingCheckNames(rollup);
+  const merged = str(j.state).toUpperCase() === "MERGED" || str(j.mergedAt).trim() !== "";
+  const mergeCommit = isRecord(j.mergeCommit) ? j.mergeCommit : undefined;
+  const mergedSha = mergeCommit && str(mergeCommit.oid).trim() !== "" ? str(mergeCommit.oid).trim() : null;
+  return {
+    merged,
+    state: merged ? "merged" : str(j.state).toUpperCase() === "CLOSED" ? "closed" : "open",
+    mergeStateStatus: (str(j.mergeStateStatus) || "UNKNOWN").toUpperCase(),
+    failingChecks: names.length,
+    failingCheckNames: names,
+    totalChecks: rollup.length,
+    presentCheckNames: allCheckNames(rollup),
+    isDraft: j.isDraft === true,
+    headRefOid: str(j.headRefOid).trim() || null,
+    mergedSha,
+    pendingChecks: pending.length,
+  };
+}
+
+/** pr readiness (ADR 0005 §2): does the observed PR satisfy the declared `match.prState`
+ * (default `merged`)? PURE — it operates on an already-fetched {@link PrObservation} and NEVER
+ * throws, so a transient/garbled read is simply "not ready yet". A `merged` match binds the merge
+ * commit as `{ mergedSha }` (mirroring the `capability` kind's `resolvedArtifact` bind) so a
+ * downstream edge can pin the exact landed commit. The merge ACTION stays in the merge-loop node
+ * body — this kind only OBSERVES. */
+export function matchPr(match: ProbeMatch | undefined, pr: PrObservation): ProbeResult {
+  const want: PrCondition = match?.prState ?? "merged";
+  switch (want) {
+    case "ready": {
+      // draft→ready: a non-draft PR (already-merged PRs are non-draft too, so they also satisfy it).
+      const ready = !pr.isDraft;
+      return { ready, detail: `pr ${ready ? "ready (not draft)" : "still draft"}` };
+    }
+    case "merged": {
+      if (!pr.merged) return { ready: false, detail: "pr not merged yet" };
+      const bind = pr.mergedSha ? { mergedSha: pr.mergedSha } : undefined;
+      return { ready: true, detail: `pr merged${pr.mergedSha ? ` (${pr.mergedSha})` : ""}`, bind };
+    }
+    case "mergeable": {
+      const m = classifyMergeability(pr);
+      const ready = m === "ready";
+      return { ready, detail: `pr mergeability ${m}` };
+    }
+    case "checks-green": {
+      // Required checks green: at least one head run exists, none failing, AND none still in flight.
+      // A queued/in-progress run has no failing conclusion, so counting only `failingChecks` would
+      // report green while checks are still running — `pendingChecks` closes that gap. `failingChecks
+      // < 0` is token mode (checks unenumerable) — stay conservative (not ready), never falsely green.
+      const ready = pr.failingChecks === 0 && pr.pendingChecks === 0 && pr.totalChecks > 0;
+      const detail =
+        pr.totalChecks < 0
+          ? "pr checks unenumerable (not ready)"
+          : pr.totalChecks === 0
+            ? "pr no checks yet"
+            : pr.failingChecks > 0
+              ? `pr checks ${pr.failingChecks} failing`
+              : pr.pendingChecks > 0
+                ? `pr checks ${pr.pendingChecks} pending`
+                : "pr checks green";
+      return { ready, detail };
+    }
+  }
+}
+
+/** Split an `owner/repo#123` PR reference into its repo + numeric PR number, or `null` when it
+ * carries no numeric id (so `parseProbe` can reject a never-resolvable target loudly). The `#`
+ * separator is the canonical — and only — PR handle: an `@N` form is deliberately NOT accepted, as
+ * `owner/repo@<ref>` is the repo-ref syntax used elsewhere (`parseRepoRef`), so a numeric `@N` there
+ * would ambiguously mis-parse a git ref as a PR number. Matches the OpenAPI contract + `parseProbe`
+ * error, both of which document `owner/repo#N` only. */
+export function parsePrTarget(target: string): { repo: string; number: string } | null {
+  const t = target.trim();
+  const m = t.match(/^(.+?)#(\d+)$/);
+  if (!m) return null;
+  const repo = m[1].trim();
+  if (repo === "") return null;
+  return { repo, number: m[2] };
+}
+
+/** Build the `gh pr view` command that reads a PR's merge-state fields. `gh` reads its token from the
+ * ambient env (like `github-check`/`capability`) — no `credentialEnv`. */
+export function prViewCommand(repo: string, number: string): string {
+  return `gh pr view ${shellQuote(number)} --repo ${shellQuote(repo)} --json ${shellQuote("state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,mergeCommit")}`;
+}
+
 
 // ── Single probe attempt (does I/O via the injected {@link ProbeExec}) ──────────────────────────
 
@@ -520,6 +673,13 @@ export async function probeOnce(
       if (out.code !== 0) return { ready: false, detail: "capability: gh api failed (not ready)" };
       return matchCapability(probe.match, parseReleases(parseJson(out.stdout)));
     }
+    case "pr": {
+      const ref = parsePrTarget(probe.target);
+      if (!ref) return { ready: false, detail: "pr: unparseable target (not ready)" };
+      const out = await exec.run(prViewCommand(ref.repo, ref.number), env);
+      if (out.code !== 0) return { ready: false, detail: "pr: gh pr view failed (not ready)" };
+      return matchPr(probe.match, parsePrView(parseJson(out.stdout)));
+    }
   }
 }
 

package/openapi.yaml

@@ -1217,12 +1217,12 @@ components:
       properties:
         kind:
           type: string
-          enum: [http, command, npm, github-check, capability]
-          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge.
+          enum: [http, command, npm, github-check, capability, pr]
+          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge; `pr` watches an in-flight PR's merge state (ADR 0005 §2).
         target:
           type: string
           minLength: 1
-          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, or `github-releases:owner/repo`).
+          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, or an `owner/repo#123` PR reference for the `pr` kind).
         onTimeout:
           type: string
           enum: [escalate, fail, continue]
@@ -1245,6 +1245,7 @@ components:
             capabilityRef: { type: string, description: "capability: the upstream issue/PR handle the resolved version must carry." }
             package: { type: string, description: "capability: the package whose releases are scanned for provenance." }
             verifyCommand: { type: string, description: "capability: optional empirical verifier run once at the gate boundary." }
+            prState: { type: string, enum: [ready, merged, mergeable, checks-green], description: "pr: the declared PR state to wait for (default merged)." }
         poll:
           type: object
           additionalProperties: false
@@ -1253,6 +1254,250 @@ components:
             everyMs: { type: integer, description: Interval between poll attempts (ms). }
             timeoutMs: { type: integer, description: Bounded budget (ms) before the gate escalates. }
             backoff: { type: string, enum: [fixed, exponential], description: Backoff shape between attempts. }
+    DeliveryGraph:
+      description: >-
+        An agent-authored delivery graph (ADR 0005) — the SINGLE agent-facing artifact for a
+        heterogeneous, partly-human, cross-repo delivery runbook. It is DATA, never an executable
+        artifact: a JSON DAG whose nodes each name a `kind` from a CLOSED allowlist
+        (`agent`/`wait`/`human`/`connector` — Decision 1/2, the trust boundary) and whose `edges`
+        name DISCOVERED facts (Decision 3). Ingest validates the SHAPE here and the SEMANTICS
+        (acyclicity, edge integrity, fact resolution) in the pure `validateDeliveryGraph`
+        (`app/deliveryGraph.ts`). This slice (S0) defines the vocabulary + validation surface ONLY —
+        no compiler, dispatch, or execution (those land in later slices).
+      type: object
+      additionalProperties: false
+      required:
+        - nodes
+      properties:
+        name:
+          type: string
+          maxLength: 255
+          description: OPTIONAL human-readable label for the graph (shown in the rendered preview).
+        nodes:
+          type: array
+          minItems: 1
+          maxItems: 256
+          items:
+            $ref: "#/components/schemas/DeliveryNode"
+          description: >-
+            The graph's nodes. Each carries a unique `id` and a `kind` from the closed allowlist,
+            plus its per-kind config and its typed `emits[]` declaration. Node ids must be unique
+            across the graph (enforced by `validateDeliveryGraph`).
+        edges:
+          type: array
+          maxItems: 1024
+          items:
+            $ref: "#/components/schemas/DeliveryEdge"
+          description: >-
+            The dependency edges — the graph's discovered-fact topology (Decision 3). Each edge means
+            "`to` proceeds once fact `from` about the upstream node is observable". `from` is either a
+            bare `<nodeId>` (the degenerate "wait for the upstream node's completion" fact) or a
+            qualified `<nodeId>.<fact>` referencing one of that node's declared `emits`. Omit/`[]` for
+            a set of independent (root) nodes. The edge set must be a DAG.
+    DeliveryNode:
+      description: >-
+        One node in a delivery graph. A discriminated union on `kind` over the CLOSED allowlist; the
+        matching per-kind config object (`agent`/`wait`/`connector`) is REQUIRED and names the
+        engine-native body the node delegates to (Decision 2 — the graph schedules, it does not
+        re-implement execution). The `human` config is the sole exception — it is OPTIONAL (a bare
+        `human` node resolves to a generic emit-capturing form fallback in S3).
+      oneOf:
+        - $ref: "#/components/schemas/DeliveryNodeAgent"
+        - $ref: "#/components/schemas/DeliveryNodeWait"
+        - $ref: "#/components/schemas/DeliveryNodeHuman"
+        - $ref: "#/components/schemas/DeliveryNodeConnector"
+      discriminator:
+        propertyName: kind
+        mapping:
+          agent: "#/components/schemas/DeliveryNodeAgent"
+          wait: "#/components/schemas/DeliveryNodeWait"
+          human: "#/components/schemas/DeliveryNodeHuman"
+          connector: "#/components/schemas/DeliveryNodeConnector"
+    DeliveryFact:
+      description: >-
+        A typed output a node declares it will EMIT (ADR 0005 Decision 3/4 — emitted-fact typing).
+        A downstream edge references it as `from: "<nodeId>.<fact>"`, so a bind is validated against
+        this declaration, not stringly. A "click done" human node or a pass-through node declares no
+        facts (`emits` absent/empty) — the degenerate no-emit case.
+      type: object
+      additionalProperties: false
+      required:
+        - name
+        - type
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: '^[A-Za-z_][A-Za-z0-9_]*$'
+          description: The fact's identifier, referenced downstream as `<nodeId>.<name>`. Must be unique within the node.
+        type:
+          type: string
+          enum: [string, number, boolean, artifact, version, url]
+          description: >-
+            The fact's declared type. `artifact` is a `pkg@version` handle, `version` a bare version
+            string, `url` a location — mirrors the values `capability`/`pr` probes late-bind.
+        description:
+          type: string
+          maxLength: 512
+          description: OPTIONAL human note describing what the fact carries.
+    DeliveryNodeCommon:
+      type: object
+      properties:
+        id:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: '^[A-Za-z_][A-Za-z0-9_.-]*$'
+          description: The node's identifier, unique within the graph and referenced by edges.
+        emits:
+          type: array
+          maxItems: 32
+          items:
+            $ref: "#/components/schemas/DeliveryFact"
+          description: >-
+            The typed facts this node hands forward when it completes (Decision 3/4). Absent/empty for
+            a node that emits nothing. Downstream edges bind these via `from: "<nodeId>.<fact>"`.
+    DeliveryNodeAgent:
+      description: >-
+        An `agent` node — a worker executes an agent job type (the existing fan-out body). Bounded
+        (timeout → escalate) and resumable like every node.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - agent
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [agent] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            agent:
+              type: object
+              additionalProperties: false
+              required:
+                - jobType
+              properties:
+                jobType:
+                  type: string
+                  minLength: 1
+                  description: The agent job type a worker executes for this node (e.g. `senior:feature`).
+                prompt:
+                  type: string
+                  maxLength: 20000
+                  description: OPTIONAL steering prompt appended to the node's job brief.
+    DeliveryNodeWait:
+      description: >-
+        A `wait` node — a durable `ReadinessProbe` (ADR 0001 §2) watching an external fact. Reuses the
+        existing `ReadinessProbe` shape verbatim (Decision 3 — never a second wait loop); the `pr`
+        merge-state kind is added to that shape by slice S2 and flows in here automatically.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - wait
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [wait] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            wait:
+              $ref: "#/components/schemas/ReadinessProbe"
+    DeliveryNodeHuman:
+      description: >-
+        A `human` node — a scheduled user task + form (ADR 0002 machinery promoted from exception to
+        node, Decision 4). Surfaces "now do X" on the Tasks inbox, blocks dependents, is answerable by
+        a human OR an agent, is SLA-bounded, and can EMIT a typed fact its form captures.
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [human] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            human:
+              type: object
+              additionalProperties: false
+              description: >-
+                OPTIONAL human-node config. `formKey` explicitly attaches a form (else a form is
+                selected by node category, else a generic emit-capturing fallback — resolved in S3).
+                The node's typed output is declared via the node-level `emits[]`.
+              properties:
+                formKey:
+                  type: string
+                  minLength: 1
+                  description: OPTIONAL explicit form to attach at authoring time (specific-else-generic resolution, S3).
+                prompt:
+                  type: string
+                  maxLength: 20000
+                  description: OPTIONAL instruction shown to the human/agent completing the task ("now do X").
+    DeliveryNodeConnector:
+      description: >-
+        A `connector` node — an automated, side-effecting outbound action (the connector I/O surface).
+        Side-effecting, so it carries a `dedupeKey` and tolerates at-least-once execution. The
+        `payload` schema is a minimal forward-declared stub in this slice (ADR 0005 non-goal — the
+        concrete connector I/O lands later).
+      allOf:
+        - $ref: "#/components/schemas/DeliveryNodeCommon"
+        - type: object
+          additionalProperties: false
+          required:
+            - id
+            - kind
+            - connector
+          properties:
+            id: { type: string }
+            kind: { type: string, enum: [connector] }
+            emits: { type: array, items: { $ref: "#/components/schemas/DeliveryFact" } }
+            connector:
+              type: object
+              additionalProperties: false
+              required:
+                - target
+              properties:
+                target:
+                  type: string
+                  minLength: 1
+                  description: The connector action target (forward-declared — the concrete scheme lands in a later slice).
+                dedupeKey:
+                  type: string
+                  minLength: 1
+                  description: >-
+                    OPTIONAL idempotency key so an at-least-once resume cannot double-fire this
+                    side-effecting node (ADR 0005 Decision 7). Author-supplied or graph-derived.
+                payload:
+                  type: object
+                  additionalProperties: true
+                  description: Minimal forward-declared payload stub — the concrete connector payload schema is deferred (ADR non-goal).
+    DeliveryEdge:
+      description: >-
+        A dependency edge — "`to` proceeds once fact `from` is observable" (ADR 0005 Decision 3).
+        `from` is either a bare `<nodeId>` (wait for the upstream node's completion fact) or a
+        qualified `<nodeId>.<fact>` referencing a declared `emits` fact of that node. Both endpoints
+        must resolve to a node in the graph, the referenced fact must be declared, and the whole edge
+        set must be a DAG — all enforced by `validateDeliveryGraph`.
+      type: object
+      additionalProperties: false
+      required:
+        - from
+        - to
+      properties:
+        from:
+          type: string
+          minLength: 1
+          description: The upstream endpoint — `<nodeId>` (completion) or `<nodeId>.<fact>` (a declared emitted fact).
+        to:
+          type: string
+          minLength: 1
+          description: The dependent node's id — proceeds once `from` is observed.
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.109.0",
+  "version": "0.111.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/resources/processes/readiness-gate.bpmn

@@ -22,6 +22,7 @@
           <nano:extend name="capabilityRef" type="string" optional="true" />
           <nano:extend name="package" type="string" optional="true" />
           <nano:extend name="verifyCommand" type="string" optional="true" />
+          <nano:extend name="prState" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReadinessProbePoll" name="Readiness probe — poll policy">
           <nano:extend name="everyMs" type="integer" optional="true" />
@@ -46,11 +47,13 @@
           <nano:extend name="ready" type="boolean" />
           <nano:extend name="detail" type="string" optional="true" />
           <nano:extend name="resolvedArtifact" type="string" optional="true" />
+          <nano:extend name="mergedSha" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="ReadinessReady" name="readiness-ready message payload">
           <nano:extend name="ready" type="boolean" />
           <nano:extend name="detail" type="string" optional="true" />
           <nano:extend name="resolvedArtifact" type="string" optional="true" />
+          <nano:extend name="mergedSha" type="string" optional="true" />
         </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>