@nanobpm/nano-workforce 0.110.0 → 0.111.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.111.0](https://github.com/nanobpm/nano-workforce/compare/v0.110.0...v0.111.0) (2026-08-20)
+
+
+### Features
+
+* **readiness:** add pr/merge-state ReadinessProbe kind (ADR 0005 S2) ([#385](https://github.com/nanobpm/nano-workforce/issues/385)) ([860e031](https://github.com/nanobpm/nano-workforce/commit/860e03134b428c73426621acb14ccd9a3ab94149)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258) [owner/repo#N](https://github.com/owner/repo/issues/N) [#377](https://github.com/nanobpm/nano-workforce/issues/377) [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 # [0.110.0](https://github.com/nanobpm/nano-workforce/compare/v0.109.0...v0.110.0) (2026-08-20)
 
 

package/app/github.ts

@@ -597,6 +597,28 @@ export function failingCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** Names of checks that are still in flight — queued or in progress, i.e. NOT yet complete and not a
+ * hard failure. Covers the CheckRun shape (`status` QUEUED/IN_PROGRESS/PENDING/WAITING/… anything but
+ * COMPLETED) and the legacy StatusContext shape (`state` PENDING/EXPECTED). Derived over the newest
+ * run per check (`latestRunPerCheck`) like {@link failingCheckNames}, so a superseded run doesn't
+ * linger as pending. A `checks-green` gate MUST count these so it never reports green while a run has
+ * not yet concluded (a pending run has no failing conclusion, so it would otherwise slip through). */
+export function pendingCheckNames(rollup: RollupEntry[]): string[] {
+  const names: string[] = [];
+  for (const c of latestRunPerCheck(rollup)) {
+    const status = (c.status || "").toUpperCase();
+    if (status !== "") {
+      // CheckRun: anything other than COMPLETED is still running/queued.
+      if (status !== "COMPLETED") names.push(checkKey(c));
+    } else {
+      // Legacy StatusContext: PENDING/EXPECTED are not-yet-concluded.
+      const state = (c.state || "").toUpperCase();
+      if (state === "PENDING" || state === "EXPECTED") names.push(checkKey(c));
+    }
+  }
+  return names;
+}
+
 /** Names of every head check present, regardless of state. Covers both the CheckRun shape
  * (`name`/`workflowName`) and the legacy StatusContext shape (`context`). Used to test whether a
  * repo's *required* checks are present on the head — so an unrelated always-on check (e.g.

package/app/readiness.test.ts

@@ -21,17 +21,22 @@ import {
   matchGithubCheck,
   matchHttp,
   matchNpm,
+  matchPr,
   msToIsoDuration,
   newestPublishedVersion,
   nextDelay,
   normalizePoll,
   parseProbe,
+  parsePrTarget,
+  parsePrView,
   parseReleases,
   parseReleasesTarget,
   parseRepoRef,
   probeBudgetMs,
   probeOnce,
   type ProbeExec,
+  type PrObservation,
+  prViewCommand,
   readinessTimeout,
   readinessTimeoutMs,
   redactString,
@@ -375,6 +380,161 @@ test("probeOnce github-check: a failed gh api call is not-ready (never throws)",
   assert(!res.ready);
 });
 
+// ── parseProbe: pr kind (ADR 0005 §2 — owner/repo#N target + validated prState) ──────────────────
+test("parseProbe: accepts an owner/repo#N pr probe and defaults onTimeout to escalate (timeout → escalate)", () => {
+  const p = parseProbe({ kind: "pr", target: "nanobpm/nano-workforce#377" });
+  assertEquals(p.kind, "pr");
+  assertEquals(p.onTimeout, "escalate");
+});
+
+test("parseProbe: a pr probe whose target carries no numeric PR id throws (never resolvable)", () => {
+  assertThrows(() => parseProbe({ kind: "pr", target: "nanobpm/nano-workforce" }), Error, "owner/repo#<number>");
+});
+
+test("parseProbe: a pr probe with an unknown match.prState throws (mistyped state fails loudly)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "pr", target: "o/r#1", match: { prState: "landed" } }),
+    Error,
+    "invalid match.prState",
+  );
+});
+
+test("parseProbe: a valid pr probe round-trips its prState", () => {
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "mergeable" } });
+  assertEquals(p.match?.prState, "mergeable");
+});
+
+// ── matchPr (pure — operates on an already-fetched PR observation) ────────────────────────────────
+function prObs(over: Partial<PrObservation> = {}): PrObservation {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "UNKNOWN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    totalChecks: 0,
+    presentCheckNames: [],
+    isDraft: false,
+    headRefOid: "abc123",
+    mergedSha: null,
+    pendingChecks: 0,
+    ...over,
+  };
+}
+
+test("matchPr: prState 'ready' is the draft→ready transition (a non-draft PR is ready)", () => {
+  assert(!matchPr({ prState: "ready" }, prObs({ isDraft: true })).ready);
+  assert(matchPr({ prState: "ready" }, prObs({ isDraft: false })).ready);
+});
+
+test("matchPr: prState 'merged' waits for the merge and binds mergedSha (mirrors resolvedArtifact)", () => {
+  assert(!matchPr({ prState: "merged" }, prObs({ merged: false })).ready);
+  const res = matchPr({ prState: "merged" }, prObs({ merged: true, state: "merged", mergedSha: "deadbeef" }));
+  assert(res.ready);
+  assertEquals(res.bind?.mergedSha, "deadbeef");
+});
+
+test("matchPr: 'merged' is the default when no prState is declared", () => {
+  assert(!matchPr(undefined, prObs({ merged: false })).ready);
+  assert(matchPr(undefined, prObs({ merged: true, state: "merged" })).ready);
+});
+
+test("matchPr: prState 'mergeable' reuses classifyMergeability (CLEAN is ready, BLOCKED is not)", () => {
+  assert(matchPr({ prState: "mergeable" }, prObs({ mergeStateStatus: "CLEAN" })).ready);
+  assert(!matchPr({ prState: "mergeable" }, prObs({ mergeStateStatus: "BLOCKED", failingChecks: 1 })).ready);
+});
+
+test("matchPr: prState 'checks-green' needs a present, non-failing, non-pending head run", () => {
+  assert(matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 0 })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 1 })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 0, failingChecks: 0 })).ready);
+  // A run still queued/in-progress (no failing conclusion yet) must NOT read as green.
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 0, pendingChecks: 1 })).ready);
+  // token mode (checks unenumerable, totalChecks < 0) stays conservative — never falsely green.
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: -1, failingChecks: -1 })).ready);
+});
+
+test("matchPr: a not-yet-satisfied state is not-ready — the bounded gate keeps waiting → timeout escalates", () => {
+  // Every un-reached state resolves to ready:false, which is exactly what the engine timer arm bounds
+  // (onTimeout defaults to 'escalate'): a PR that never lands is never falsely resolved.
+  assert(!matchPr({ prState: "merged" }, prObs({ merged: false })).ready);
+  assert(!matchPr({ prState: "ready" }, prObs({ isDraft: true })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 1, failingChecks: 1 })).ready);
+});
+
+// ── parsePrView + probeOnce pr dispatch (injected exec — no I/O) ─────────────────────────────────
+test("parsePrView: reduces a gh pr view payload and collapses the check rollup", () => {
+  const obs = parsePrView({
+    state: "OPEN",
+    mergeStateStatus: "clean",
+    isDraft: false,
+    headRefOid: "sha1",
+    statusCheckRollup: [
+      { name: "build", status: "COMPLETED", conclusion: "SUCCESS" },
+      { name: "lint", status: "COMPLETED", conclusion: "FAILURE" },
+    ],
+  });
+  assertEquals(obs.merged, false);
+  assertEquals(obs.mergeStateStatus, "CLEAN");
+  assertEquals(obs.totalChecks, 2);
+  assertEquals(obs.failingCheckNames, ["lint"]);
+});
+
+test("parsePrView: an in-flight run is counted as pending (so checks-green stays not-green)", () => {
+  const obs = parsePrView({
+    state: "OPEN",
+    statusCheckRollup: [
+      { name: "build", status: "COMPLETED", conclusion: "SUCCESS" },
+      { name: "e2e", status: "IN_PROGRESS" },
+    ],
+  });
+  assertEquals(obs.failingChecks, 0);
+  assertEquals(obs.pendingChecks, 1);
+  assert(!matchPr({ prState: "checks-green" }, obs).ready);
+});
+
+test("parsePrView: a merged PR carries its merge commit oid", () => {
+  const obs = parsePrView({ state: "MERGED", mergedAt: "2026-08-20T00:00:00Z", mergeCommit: { oid: "cafe" } });
+  assertEquals(obs.merged, true);
+  assertEquals(obs.state, "merged");
+  assertEquals(obs.mergedSha, "cafe");
+});
+
+test("parsePrView: a garbled payload degrades to an all-open, no-checks observation (never throws)", () => {
+  const obs = parsePrView(null);
+  assertEquals(obs.merged, false);
+  assertEquals(obs.totalChecks, 0);
+});
+
+test("probeOnce pr: builds a quoted `gh pr view` command and matches merged, binding mergedSha", async () => {
+  const cap: { cmd?: string } = {};
+  const exec = stubExec({
+    command: { code: 0, stdout: JSON.stringify({ state: "MERGED", mergeCommit: { oid: "abc" } }), stderr: "" },
+    capture: cap,
+  });
+  const res = await probeOnce(parseProbe({ kind: "pr", target: "nanobpm/nano-workforce#377" }), exec, {});
+  assert(res.ready);
+  assertEquals(res.bind?.mergedSha, "abc");
+  assertStringIncludes(cap.cmd ?? "", "gh pr view '377' --repo 'nanobpm/nano-workforce'");
+});
+
+test("probeOnce pr: a failed gh pr view call is not-ready (never throws)", async () => {
+  const exec = stubExec({ command: { code: 1, stdout: "", stderr: "no pr" } });
+  const res = await probeOnce(parseProbe({ kind: "pr", target: "o/r#1" }), exec, {});
+  assert(!res.ready);
+});
+
+test("parsePrTarget: parses owner/repo#N, rejects @N and a bare repo", () => {
+  assertEquals(parsePrTarget("o/r#12"), { repo: "o/r", number: "12" });
+  // `@N` is deliberately NOT a PR handle — it's the repo-ref syntax, so it must not parse as a PR.
+  assertEquals(parsePrTarget("o/r@34"), null);
+  assertEquals(parsePrTarget("o/r"), null);
+});
+
+test("prViewCommand: single-quote-escapes its args", () => {
+  assertStringIncludes(prViewCommand("o/r", "9"), "gh pr view '9' --repo 'o/r'");
+});
+
 // ── backoff + poll normalisation ──────────────────────────────────────────────────────────────
 test("normalizePoll: fills defaults and clamps everyMs to the ceiling", () => {
   const d = normalizePoll(undefined);

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

package/package.json

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