@nanobpm/nano-workforce 0.70.0 → 0.70.1

package/workers/converge-gate/worker.ts

@@ -0,0 +1,101 @@
+// pr.converge-gate — the deterministic review-comment gate for the convergence loop.
+//
+// The loop declares convergence on the review-round AGENT's self-reported `status = "converged"`.
+// That trusts the agent to only converge once every Copilot comment is addressed — which failed on
+// Magikcraft/nano-bpm#770 (20 rounds, a suppressed advisory never applied, then auto-merged with
+// the comment unaddressed). This step runs on the converged path, BEFORE pr.finalize hands off to
+// the merge loop, and blocks handoff while GitHub still shows unaddressed comments:
+//   • any review THREAD is still unresolved (GraphQL `isResolved = false`), or
+//   • any SUPPRESSED advisory in the latest Copilot review body lacks a matching RESOLVED ack
+//     thread (a `nano-ack: <path>:<line>` marker copied from Copilot's `**path:line**` header).
+// A blocked gate returns `convergeBlocked = true`; the model's `gw-converge-gate` gateway routes to
+// the human `wait-answer` escalation (recoverable), never a hard wedge.
+//
+// It FAILS CLOSED: if the live GitHub state cannot be read, it blocks (escalates) rather than
+// letting an unverifiable "converged" through — the opposite of the no-progress guard, because a
+// merge-gating check must escalate-on-uncertainty so #770 cannot recur.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { type ConvergeGateResult, evaluateConvergeGate } from "../../app/convergeGate.ts";
+import {
+  fetchLatestCopilotReviewBody,
+  fetchReviewThreads,
+  parseAckedAdvisories,
+  parseSuppressedAdvisories,
+  type ReviewThread,
+} from "../../app/github.ts";
+import { parsePr } from "../../app/service.ts";
+import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input/output typed off the model data envelopes (`PrConvergeGateIn` / `PrConvergeGateOut` in
+// convergence-loop.bpmn), the single source of truth for this worker's wire contract (ADR 0040).
+type In = WorkerInputs["pr.converge-gate"];
+type Out = WorkerOutputs["pr.converge-gate"];
+
+// Reads a PR's review threads. `null` = no usable transport (treated as an unverifiable read →
+// fail closed). Throws propagate to the fail-closed catch below.
+export type ThreadsReader = (repo: string, prNumber: number) => Promise<ReviewThread[] | null>;
+// Reads the latest Copilot review body. `null` = no usable transport (unverifiable → fail closed);
+// `""` = transport usable but no Copilot review yet (verified: no suppressed advisories).
+export type ReviewBodyReader = (repo: string, prNumber: number) => Promise<string | null>;
+
+const defaultReadThreads: ThreadsReader = (repo, prNumber) =>
+  fetchReviewThreads(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+const defaultReadReviewBody: ReviewBodyReader = (repo, prNumber) =>
+  fetchLatestCopilotReviewBody(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+
+const BLOCK_UNVERIFIABLE =
+  "Convergence blocked: could not verify the PR's review comments against GitHub. A human must confirm every Copilot review thread is resolved and every suppressed advisory acknowledged before this PR converges (reply to resume the loop).";
+
+/** Build the handler with injectable GitHub readers. The default export binds the real readers;
+ * tests inject stubs. Fails CLOSED — any unreadable/errored state blocks convergence. */
+export function makeHandler(deps: {
+  readThreads: ThreadsReader;
+  readReviewBody: ReviewBodyReader;
+}): AppJobHandler<In, Out> {
+  return async (job) => {
+    const { prKey, repo, prNumber } = job.variables;
+    // `parsePr` is total on any input (fails closed to `null` on a missing/non-string prKey), so
+    // pass it straight through — a malformed prKey degrades to the fail-closed target check below.
+    const parsed = parsePr(prKey);
+    const ghRepo = repo ?? parsed?.repo;
+    const ghNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
+    if (!ghRepo || typeof ghNumber !== "number") {
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+    }
+
+    let result: ConvergeGateResult;
+    try {
+      const threads = await deps.readThreads(ghRepo, ghNumber);
+      // A null threads read is an unverifiable gate — fail closed. (An empty ARRAY is a verified
+      // "no threads" and is fine.)
+      if (threads === null) {
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      }
+      const reviewBody = await deps.readReviewBody(ghRepo, ghNumber);
+      // A null review body is an unverifiable read (no usable transport) — fail closed, same as a
+      // null threads read. (An empty STRING is a verified "no Copilot review / no advisories".)
+      if (reviewBody === null) {
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      }
+      const unresolvedThreadCount = threads.filter((t) => !t.isResolved).length;
+      result = evaluateConvergeGate({
+        unresolvedThreadCount,
+        suppressedKeys: parseSuppressedAdvisories(reviewBody),
+        acknowledgedKeys: parseAckedAdvisories(threads),
+      });
+    } catch {
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+    }
+
+    return {
+      convergeBlocked: result.convergeBlocked,
+      convergeBlockReason: result.convergeBlockReason,
+    };
+  };
+}
+
+const handler = makeHandler({
+  readThreads: defaultReadThreads,
+  readReviewBody: defaultReadReviewBody,
+});
+export default handler;

package/workers/progress-check/worker.ts

@@ -0,0 +1,77 @@
+// pr.progress-check — the deterministic no-progress guard for the convergence loop.
+//
+// After a round is recorded (pr.persist-round), this step reads the PR's current head SHA and
+// compares it to the head observed at the previous recorded round. An `addressed` round whose head
+// did NOT advance pushed no commit, so requesting another Copilot review would loop on
+// byte-identical code — the same comments, round after round, until the round cap escalates. It
+// returns `progressed:false`, and the model's `gw-progress` gateway escalates to the human
+// `wait-answer` task instead of soliciting another review.
+//
+// Every other case returns `progressed:true` (continue): a `waiting` round (round 1, awaiting the
+// first review) legitimately has no push; an advanced head means real work landed; and a head we
+// could not read fails OPEN — the round cap and the review-wait timeout stay the safety nets so a
+// transient GitHub hiccup can never fabricate a no-progress escalation. The routing decision lives
+// in app/roundProgress.ts, the single source of truth this worker and `gw-progress` both mirror.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { fetchPrHead } from "../../app/github.ts";
+import { isAddressedStatus, routeProgress } from "../../app/roundProgress.ts";
+import { parsePr } from "../../app/service.ts";
+import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input/output typed off the model data envelopes (`PrProgressCheckIn` / `PrProgressCheckOut` in
+// convergence-loop.bpmn), the single source of truth for this worker's wire contract (ADR 0040).
+type In = WorkerInputs["pr.progress-check"];
+type Out = WorkerOutputs["pr.progress-check"];
+
+// Reads a PR's current head SHA. Injectable so unit tests never touch git/network; the default
+// binds the real GitHub reader (the shared gh | token transport) and swallows any failure to
+// `null` so the guard fails OPEN.
+export type HeadReader = (repo: string, prNumber: number) => Promise<string | null>;
+
+const defaultReadHead: HeadReader = async (repo, prNumber) => {
+  const token = process.env.GITHUB_TOKEN ?? "";
+  const head = await fetchPrHead(repo, prNumber, token).catch(() => null);
+  return head?.headSha ?? null;
+};
+
+/** Build the handler with an injectable head reader (see {@link HeadReader}). The default export
+ * binds the real GitHub reader; tests inject a stub. */
+export function makeHandler(deps: { readHead: HeadReader }): AppJobHandler<In, Out> {
+  return async (job, app) => {
+    const { prKey, status, repo, prNumber } = job.variables;
+
+    // Only an `addressed` round claims a push, so only it can be a no-progress round — and a
+    // blank/unknown status counts as `addressed` here (gw-status defaults it down the addressed
+    // arm and pr.persist-round records a missing status as `addressed`), so it is the safe-default
+    // trap this guard exists for. Skip the GitHub read entirely only for an explicitly recognized
+    // non-addressed status — a `waiting` round costs nothing and continues.
+    if (!isAddressedStatus(status)) return { progressed: true };
+
+    // Prefer the carried repo/prNumber; fall back to parsing the canonical `owner/repo#N` prKey so
+    // an older in-flight instance (or a process-variable regression) still resolves a target. If
+    // neither yields one, fail open rather than guess.
+    const parsed = parsePr(prKey);
+    const ghRepo = repo ?? parsed?.repo;
+    const ghNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
+    if (!ghRepo || typeof ghNumber !== "number") return { progressed: true };
+
+    const currentHead = await deps.readHead(ghRepo, ghNumber).catch(() => null);
+    const prs = app.data.table<{ pr_key: string; last_round_head: string | null }>(
+      "pull_requests",
+      "pr_key",
+    );
+    const row = await prs.get(prKey);
+    const previousHead = row?.last_round_head ?? null;
+
+    // Record the observed head as the baseline for the next round's comparison — but only when we
+    // actually read one, so a null (unreadable) head never clobbers a good baseline.
+    if (currentHead) {
+      await prs.update(prKey, { last_round_head: currentHead });
+    }
+
+    return { progressed: routeProgress(status, previousHead, currentHead) === "continue" };
+  };
+}
+
+const handler = makeHandler({ readHead: defaultReadHead });
+export default handler;