@nanobpm/nano-workforce 0.110.0 → 0.111.1

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, checkConclusions, 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,118 @@ 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),
+    pendingCheckNames: pending,
+    checkConclusions: checkConclusions(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 +675,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/app/service.ts

@@ -1150,7 +1150,11 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
       // (#342/#350). Reuse the `st` we just read so we don't double-fetch. This is the proven terminal
       // path the whole class (#368) now shares.
       if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
-      const verdict = classifyMergeability(st);
+      // Load the repo's merge protocol ONCE per PR iteration and pass it into the classifier so the
+      // protocol-aware backstop (#392) can gate a red DECLARED-required check even when GitHub reports
+      // the PR as UNSTABLE. The same handle is reused by the frugal-CI fresh-head-run branch below.
+      const protocol = await loadMergeProtocol(repo, token).catch(() => null);
+      const verdict = classifyMergeability(st, protocol ?? undefined);
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh
         // head run and the PR has NO required head run yet, review has converged but the last push
@@ -1161,7 +1165,6 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         // `pull_request` run once per head (mark ready / close+reopen); rebases change
         // `headRefOid`, so downstream merge-train PRs get a new nudge after every post-rebase
         // landing attempt.
-        const protocol = await loadMergeProtocol(repo, token).catch(() => null);
         if (protocol) {
           const action = freshHeadRunAction(protocol, verdict, headRunPresenceCount(protocol, st), st.isDraft, {
             headRefOid: st.headRefOid,

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
@@ -1497,6 +1498,221 @@ components:
           type: string
           minLength: 1
           description: The dependent node's id — proceeds once `from` is observed.
+    DeliveryCompileError:
+      description: >-
+        One semantic-validation or compile failure, path-qualified at the offending input
+        (`nodes[2].kind`, `edges[1].from`, …). Mirrors a `validateDeliveryGraph` (`app/deliveryGraph.ts`)
+        error stripped to the wire pair `{ path, message }` (the stable `code` stays server-side).
+      type: object
+      additionalProperties: false
+      required:
+        - path
+        - message
+      properties:
+        path:
+          type: string
+          description: JSON-path pointer at the offending node/edge/fact.
+        message:
+          type: string
+          description: Human-actionable description of the failure.
+    ResolvedDeliveryNode:
+      description: >-
+        A normalised node in the compiled graph (ADR 0005 slice S1) — its `id`, `kind`, the
+        deterministic BPMN `element` id it compiled to, the engine-native `calledElement` body it
+        delegates to (Decision 2 — absent for a `human` user task), its typed `emits[]`, and the
+        upstream node ids it `dependsOn` (sorted).
+      type: object
+      additionalProperties: false
+      required:
+        - id
+        - kind
+        - element
+        - emits
+        - dependsOn
+      properties:
+        id:
+          type: string
+          description: The author's node id (unique across the graph).
+        kind:
+          type: string
+          enum: [agent, wait, human, connector]
+          description: The node's kind from the closed allowlist (the trust boundary).
+        element:
+          type: string
+          description: The deterministic BPMN element id this node compiled to (e.g. `n0`).
+        calledElement:
+          type: string
+          description: >-
+            The engine-native sub-process/call-activity target this node delegates to (Decision 2).
+            Absent for a `human` node (a native user task, not a call activity).
+        emits:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryFact"
+          description: The node's typed emitted facts (empty when it emits nothing).
+        dependsOn:
+          type: array
+          items:
+            type: string
+          description: The ids of the upstream nodes this node depends on, sorted for determinism.
+    ResolvedDeliveryEdge:
+      description: >-
+        A resolved dependency edge — the author's `from`/`to` plus the resolved upstream `fromNode`
+        and, when the `from` was qualified (`<nodeId>.<fact>`), the referenced `fromFact`.
+      type: object
+      additionalProperties: false
+      required:
+        - from
+        - to
+        - fromNode
+      properties:
+        from:
+          type: string
+          description: The author's `from` endpoint verbatim (`<nodeId>` or `<nodeId>.<fact>`).
+        to:
+          type: string
+          description: The dependent node's id.
+        fromNode:
+          type: string
+          description: The resolved upstream node id.
+        fromFact:
+          type: string
+          description: The referenced emitted fact, when the edge `from` was qualified.
+    ResolvedDeliveryGraph:
+      description: >-
+        The normalised graph the compiler resolved from the input (ADR 0005 slice S1) — nodes and
+        edges sorted deterministically so the same JSON always yields the same preview.
+      type: object
+      additionalProperties: false
+      required:
+        - nodes
+        - edges
+      properties:
+        name:
+          type: string
+          description: The graph's optional human-readable label, echoed from the input.
+        nodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/ResolvedDeliveryNode"
+          description: The normalised nodes, sorted by id.
+        edges:
+          type: array
+          items:
+            $ref: "#/components/schemas/ResolvedDeliveryEdge"
+          description: The resolved edges, sorted deterministically.
+    DeliveryHumanStop:
+      description: >-
+        A `human` node extracted for the preview — a point where the graph STOPS for a person (or an
+        agent answering on their behalf). Carries the instruction, the optional attached form, and the
+        typed facts the node will emit on completion.
+      type: object
+      additionalProperties: false
+      required:
+        - nodeId
+        - emits
+      properties:
+        nodeId:
+          type: string
+          description: The human node's id.
+        prompt:
+          type: string
+          description: The instruction shown to the human/agent ("now do X"), when declared.
+        formKey:
+          type: string
+          description: The explicitly-attached form key, when declared.
+        emits:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryFact"
+          description: The typed facts this human node will hand forward (empty for a "click done" stop).
+    DeliverySideEffect:
+      description: >-
+        A side-effecting action the compiled graph WILL perform (ADR 0005 slice S1 preview) — an
+        `agent` job run or a `connector` outbound action. Read-only `wait` gates and `human` stops are
+        NOT side effects (they are surfaced separately). Lets a human see "what it will do" before
+        approving (Decision 7).
+      type: object
+      additionalProperties: false
+      required:
+        - nodeId
+        - kind
+        - description
+      properties:
+        nodeId:
+          type: string
+          description: The id of the node that performs the side effect.
+        kind:
+          type: string
+          enum: [agent, connector]
+          description: The side-effecting node kind.
+        description:
+          type: string
+          description: Human-readable summary of the effect (e.g. "runs agent job `senior:feature`").
+        dedupeKey:
+          type: string
+          description: The connector's idempotency key, when declared (at-least-once safety, Decision 7).
+    CompileDeliveryGraphResult:
+      description: >-
+        A successful compile (ADR 0005 slice S1) — the PURE, side-effect-free preview a co-designing
+        agent iterates against. Carries the compiled one-shot `bpmn` (compile-to-native artifact), a
+        human-readable `diagram` (mermaid), the `resolved` normalised graph, and the extracted
+        `humanNodes[]` (where it stops for a person) and `sideEffects[]` (what it will do). NOTHING is
+        deployed — `compile` and `start` are separate doors (Decision 5/7).
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - diagram
+        - bpmn
+        - resolved
+        - humanNodes
+        - sideEffects
+      properties:
+        ok:
+          type: boolean
+          enum: [true]
+          description: Discriminant — `true` for a successful compile.
+        diagram:
+          type: string
+          description: A human-readable mermaid `flowchart` of the resolved graph.
+        bpmn:
+          type: string
+          description: >-
+            The compiled one-shot BPMN process definition (compile-to-native). Deterministic — the same
+            input graph always produces byte-identical XML. Not deployed here (S4 owns deployment).
+        resolved:
+          $ref: "#/components/schemas/ResolvedDeliveryGraph"
+        humanNodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryHumanStop"
+          description: The human stop-points, sorted by node id.
+        sideEffects:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliverySideEffect"
+          description: The side-effecting actions the graph will perform, sorted by node id.
+    CompileDeliveryGraphErrors:
+      description: >-
+        A rejected compile (ADR 0005 slice S1) — the graph failed shape or semantic validation. Every
+        error is path-qualified so the co-designing agent can fix the exact offending input and
+        re-compile. Nothing was compiled or deployed.
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - errors
+      properties:
+        ok:
+          type: boolean
+          enum: [false]
+          description: Discriminant — `false` for a rejected compile.
+        errors:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryCompileError"
+          description: The path-qualified validation/compile failures (at least one).
     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
@@ -2246,6 +2462,39 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/compile-delivery-graph:
+    post:
+      operationId: compileDeliveryGraph
+      summary: Validate + compile a delivery graph into a preview (PURE — never deploys). (ADR 0005 slice S1)
+      description: >-
+        The fast, safe inner loop of the delivery-graph workflow (ADR 0005 Decision 5/6). Given an
+        agent-authored `DeliveryGraph` (the closed `agent`/`wait`/`human`/`connector` node vocabulary —
+        the trust boundary), it runs the pure `validateDeliveryGraph` semantic check and then the
+        deterministic, human-written compiler, returning a preview: the compiled one-shot BPMN
+        (compile-to-native), a mermaid diagram, the resolved/normalised graph, and the extracted human
+        stop-points and side effects. It is PURE and side-effect-free — it validates and compiles but
+        NEVER deploys or dispatches, so an agent can call it repeatedly while iterating. Deployment is a
+        separate door (`startDeliveryGraph`, a later slice) — there is deliberately no `dryRun` flag on
+        the start door (Decision 5/7). A malformed graph is a 400 carrying path-qualified errors.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeliveryGraph"
+      responses:
+        "200":
+          description: The graph validated and compiled — the pure preview (nothing deployed).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileDeliveryGraphResult"
+        "400":
+          description: The graph failed shape or semantic validation — path-qualified errors, nothing compiled.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileDeliveryGraphErrors"
   /actions/start/feature:
     post:
       operationId: startFeature

package/operations/compileDeliveryGraph.test.ts

@@ -0,0 +1,60 @@
+// Tests for the POST /app/api/actions/compile-delivery-graph operation `compileDeliveryGraph`
+// (ADR 0005 slice S1). The delegate is a thin, PURE mapping of the compiler's discriminated result
+// onto the HTTP status: a well-formed graph → 200 { ok:true, … preview }, a malformed one → 400
+// { ok:false, errors }. It touches no data layer and has zero side effects, so the same body compiled
+// twice returns the identical response (callable repeatedly). These tests assert that status mapping.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./compileDeliveryGraph.ts";
+
+const app = { log: noopLog() } as unknown as AppApi;
+
+async function call(body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+const GOOD = {
+  name: "runbook",
+  nodes: [
+    { id: "a", kind: "agent", agent: { jobType: "senior:feature" } },
+    { id: "b", kind: "human", human: { prompt: "do X" } },
+  ],
+  edges: [{ from: "a", to: "b" }],
+};
+
+test("compile-delivery-graph: a well-formed graph → 200 with the pure preview", async () => {
+  const res = await call(GOOD);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assert(typeof res.body.bpmn === "string" && res.body.bpmn.length > 0);
+  assert(typeof res.body.diagram === "string" && res.body.diagram.length > 0);
+  assertEquals(res.body.resolved.nodes.length, 2);
+  assertEquals(res.body.humanNodes.length, 1);
+});
+
+test("compile-delivery-graph: a malformed graph → 400 with path-qualified errors", async () => {
+  const res = await call({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "j" } }],
+    edges: [{ from: "a", to: "ghost" }],
+  });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+  assert(Array.isArray(res.body.errors) && res.body.errors.length > 0);
+  assert(res.body.errors.every((e: { path: string; message: string }) => typeof e.path === "string"));
+});
+
+test("compile-delivery-graph: is side-effect-free — repeated calls return identical responses", async () => {
+  const a = await call(GOOD);
+  const b = await call(GOOD);
+  assertEquals(a.status, b.status);
+  assertEquals(a.body.bpmn, b.body.bpmn);
+  assertEquals(JSON.stringify(a.body.resolved), JSON.stringify(b.body.resolved));
+});
+
+test("compile-delivery-graph: a missing/empty body → 400, never a 500", async () => {
+  const res = await call(undefined);
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});

package/operations/compileDeliveryGraph.ts

@@ -0,0 +1,35 @@
+// POST /app/api/actions/compile-delivery-graph → operationId `compileDeliveryGraph` (ADR 0005,
+// slice S1). The PURE, side-effect-free compile door: the fast, safe inner loop a co-designing agent
+// hammers while authoring a `DeliveryGraph`. It VALIDATES (the pure `validateDeliveryGraph` semantic
+// check, run inside the compiler) and COMPILES the graph into a preview — the compiled one-shot BPMN
+// (compile-to-native), a mermaid diagram, the resolved/normalised graph, and the extracted human
+// stop-points + side effects — but NEVER deploys, dispatches, or mutates anything (Decision 5/6:
+// `compile` and `start` are SEPARATE doors, and there is deliberately no `dryRun` flag on the start
+// door). Because it has zero side effects, an agent may call it repeatedly: JSON → compile → fix.
+//
+// A well-formed graph is `200 { ok:true, diagram, bpmn, resolved, humanNodes, sideEffects }`; a
+// malformed one is `400 { ok:false, errors:[{ path, message }] }`, every error path-qualified so the
+// author can fix the exact offending input. The compiler is the single source of both truths — this
+// delegate just maps its discriminated result onto the HTTP status.
+
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("compileDeliveryGraph", async ({ body }, app) => {
+  // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the compiler adds
+  // the SEMANTIC checks (acyclicity, edge integrity, fact resolution) the schema cannot express. A
+  // directly-invoked delegate could still pass `undefined` — the compiler reads its input as
+  // `unknown` and maps that to a clean `ok:false`, never a 500.
+  const result = compileDeliveryGraph(body);
+  if (!result.ok) {
+    app.log.warn("compile-delivery-graph rejected", { errors: result.errors.length });
+    return { status: 400, body: result };
+  }
+  app.log.info("compile-delivery-graph compiled", {
+    nodes: result.resolved.nodes.length,
+    edges: result.resolved.edges.length,
+    humanNodes: result.humanNodes.length,
+    sideEffects: result.sideEffects.length,
+  });
+  return { status: 200, body: result };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.110.0",
+  "version": "0.111.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

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>