@nanobpm/nano-workforce 0.115.0 → 0.116.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.116.0](https://github.com/nanobpm/nano-workforce/compare/v0.115.0...v0.116.0) (2026-08-20)
+
+
+### Features
+
+* replace deterministic scope regex with a scope-integrity agent classifier ([#403](https://github.com/nanobpm/nano-workforce/issues/403)) ([588b869](https://github.com/nanobpm/nano-workforce/commit/588b8699ea738ff0772f23d68bc051e8ff417d49)), closes [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [398/#399](https://github.com/nanobpm/nano-workforce/issues/399) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395) [#395](https://github.com/nanobpm/nano-workforce/issues/395)
+
 # [0.115.0](https://github.com/nanobpm/nano-workforce/compare/v0.114.1...v0.115.0) (2026-08-20)
 
 

package/app/convergeGate.test.ts

@@ -217,15 +217,9 @@ test("pickLatestCopilotReviewBody: FAILS CLOSED (null) when the reviews read was
 async function makeUnderTest(deps: {
   readThreads: (repo: string, n: number) => Promise<ReviewThread[] | null>;
   readReviewBody: (repo: string, n: number) => Promise<string | null>;
-  readPrBody?: (repo: string, n: number) => Promise<string | null>;
-  readHeadSha?: (repo: string, n: number) => Promise<string | null>;
 }) {
   const { makeHandler } = await import("../workers/converge-gate/worker.ts");
-  // Default the scope-guard PR-body read to a verified-empty description so the comment-gate tests
-  // below exercise only the review-comment dimension; scope-guard tests pass an explicit body. The
-  // HEAD read defaults to null (unreadable) so a scope block stays blocked unless a test opts into
-  // the #395 override door with an explicit HEAD — see workers/converge-gate/worker.test.ts.
-  return makeHandler({ readPrBody: async () => "", readHeadSha: async () => null, ...deps });
+  return makeHandler(deps);
 }
 
 test("converge-gate: a clean PR is allowed to converge", async () => {
@@ -348,82 +342,6 @@ test("converge-gate: resolves repo/prNumber from the prKey when the vars are abs
   assertEquals(seen, ["o/r", 7]);
 });
 
-// ── The scope-integrity guard through the worker (#313) ─────────────────────
-
-test("converge-gate: a partial delivery that Closes a broader-scoped parent blocks convergence", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () =>
-      "Delivers the nested ad-hoc half.\n\n## Scope\nEmbedded SUB_PROCESS tools remain the deferred refinement.\n\nCloses #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "Scope integrity blocked");
-  assertStringIncludes(out.convergeBlockReason ?? "", "#631");
-});
-
-test("converge-gate: a deferral with a filed follow-up issue and a non-closing ref converges", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () =>
-      "Delivers the nested ad-hoc half.\n\n## Scope\nEmbedded SUB_PROCESS tools are deferred.\nTracked-in: #872\n\nRefs #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
-});
-
-test("converge-gate: a full-scope Closes PR with no deferral prose converges", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [],
-    readReviewBody: async () => "",
-    readPrBody: async () => "Implements the feature end to end.\n\nCloses #313",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
-});
-
-test("converge-gate: a scope block and a comment block are reported together", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: false, path: "a.ts", bodies: ["please fix"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => "Ships one half.\n\nDeferred: the rest.\n\nCloses #631",
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "unresolved review thread");
-  assertStringIncludes(out.convergeBlockReason ?? "", "Scope integrity blocked");
-});
-
-test("converge-gate: FAILS CLOSED when the PR-body read returns null (no transport)", async () => {
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => null,
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "could not read the PR description");
-});
-
-test("converge-gate: FAILS CLOSED with the SCOPE reason when the PR-body read throws", async () => {
-  // A transport failure while reading/parsing the PR body is a scope-integrity read failure, not a
-  // review-comment verification failure: it must surface BLOCK_UNVERIFIABLE_BODY, not the generic
-  // review-comment BLOCK_UNVERIFIABLE — otherwise the human escalation is pointed at review threads
-  // when the real problem is the PR description could not be read.
-  const handler = await makeUnderTest({
-    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
-    readReviewBody: async () => "",
-    readPrBody: async () => {
-      throw new Error("boom");
-    },
-  });
-  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out.convergeBlocked, true);
-  assertStringIncludes(out.convergeBlockReason ?? "", "could not read the PR description");
-});
-
 // ── Structural guard over the committed BPMN (no engine) ─────────────────────
 
 const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
@@ -460,16 +378,108 @@ test("gw-converge-gate blocks on an explicit convergeBlocked = true condition",
   assertStringIncludes(f, "convergeBlocked = true");
 });
 
-test("gw-converge-gate default arm finalizes with no condition", () => {
+test("gw-converge-gate default arm routes to the scope classifier (not straight to finalize)", () => {
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-converge-gate"[^>]*>/);
   assert(gw, "gw-converge-gate gateway missing");
   assertStringIncludes(gw[0], 'default="f_convergeOk"');
   const ok = flowElement("f_convergeOk");
   assert(ok, "f_convergeOk flow missing");
+  assertStringIncludes(ok, 'targetRef="classify-scope"');
+  assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+});
+
+// ── The scope classifier (agent task) replaces the deterministic scope regex ──
+
+test("classify-scope is an agent task servicing senior:scope-classify with a linked prompt", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="classify-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "classify-scope service task missing");
+  assertStringIncludes(task[0], 'type="senior:scope-classify"');
+  assertStringIncludes(task[0], 'resourceId="scope-classify.md"');
+  assertStringIncludes(task[0], 'linkName="prompt"');
+  // After honouring (or ignoring) the human's scope answer, it clears the one-shot
+  // scopeAnswer so a later round does not re-honour a stale decision.
+  assertStringIncludes(task[0], 'source="=null" target="scopeAnswer"');
+});
+
+// ── The scope-answer plumbing (#395 loop-defect fix) ─────────────────────────
+// review-round clears `answer` on every round, so a human's scope answer cannot reach
+// the downstream classify-scope via `answer`. A dedicated `scopeAnswer` variable, gated
+// by a `scopePending` marker, carries the decision across the review round without being
+// confused with answers to other escalation kinds.
+
+test("PrScopeClassifyIn feeds the classifier the surviving scopeAnswer, not the cleared answer", () => {
+  const shape = flat.match(/<nano:shape\b[^>]*\bid="PrScopeClassifyIn"[^>]*>.*?<\/nano:shape>/);
+  assert(shape, "PrScopeClassifyIn envelope missing");
+  assertStringIncludes(shape[0], 'name="scopeAnswer"');
+  assert(!/name="answer"/.test(shape[0]), "classifier must read scopeAnswer, not the shared answer");
+});
+
+test("PrScopeClassifyOut.scopeBlockReason is required (always emitted, empty when not blocked)", () => {
+  const shape = flat.match(/<nano:shape\b[^>]*\bid="PrScopeClassifyOut"[^>]*>.*?<\/nano:shape>/);
+  assert(shape, "PrScopeClassifyOut envelope missing");
+  assert(
+    /name="scopeBlockReason"(?![^>]*optional)/.test(shape[0]),
+    "scopeBlockReason must not be optional — the wire contract requires it always present",
+  );
+});
+
+test("persist-escalation-scope marks the open escalation as scope-kind (scopePending = true)", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-escalation-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "persist-escalation-scope task missing");
+  assertStringIncludes(task[0], 'source="=true" target="scopePending"');
+});
+
+test("record-answer captures a scope answer into scopeAnswer only while scopePending", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="record-answer"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "record-answer task missing");
+  // Capture is gated on scopePending so an answer to a *different* escalation is not
+  // mis-read as a scope override; otherwise scopeAnswer is preserved.
+  assertStringIncludes(
+    task[0],
+    'source="=(if scopePending = true then answer else scopeAnswer)" target="scopeAnswer"',
+  );
+});
+
+test("review-round resets the scopePending marker after record-answer has consumed it", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="review-round"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "review-round task missing");
+  assertStringIncludes(task[0], 'source="=false" target="scopePending"');
+});
+
+test("classify-scope feeds gw-scope-gate, which blocks on scopeBlocked = true", () => {
+  const toGate = flowElement("f_toScopeGate");
+  assert(toGate, "f_toScopeGate flow missing");
+  assertStringIncludes(toGate, 'sourceRef="classify-scope"');
+  assertStringIncludes(toGate, 'targetRef="gw-scope-gate"');
+  const blocked = flowElement("f_scopeBlocked");
+  assert(blocked, "f_scopeBlocked flow missing");
+  assertStringIncludes(blocked, 'targetRef="persist-escalation-scope"');
+  assertStringIncludes(blocked, "scopeBlocked = true");
+});
+
+test("gw-scope-gate default arm finalizes (scope ok → persist-converged)", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-scope-gate"[^>]*>/);
+  assert(gw, "gw-scope-gate gateway missing");
+  assertStringIncludes(gw[0], 'default="f_scopeOk"');
+  const ok = flowElement("f_scopeOk");
+  assert(ok, "f_scopeOk flow missing");
   assertStringIncludes(ok, 'targetRef="persist-converged"');
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
 });
 
+test("the scope escalation routes through gw-escalated with the classifier's specific reason", () => {
+  const f = flowElement("f_scopeEscGate");
+  assert(f, "f_scopeEscGate flow missing");
+  assertStringIncludes(f, 'sourceRef="persist-escalation-scope"');
+  assertStringIncludes(f, 'targetRef="gw-escalated"');
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="persist-escalation-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "persist-escalation-scope task missing");
+  assertStringIncludes(task[0], 'type="pr.persist-escalation"');
+  assertStringIncludes(task[0], 'target="question"');
+  // The human sees the classifier's specific finding, not a generic boilerplate reason.
+  assertStringIncludes(task[0], "scopeBlockReason");
+});
+
 test("the blocked-comments escalation routes through gw-escalated toward an answerable wait-answer", () => {
   // #333: previously this flowed UNCONDITIONALLY into wait-answer, so a blank convergeBlockReason
   // (the question is mapped from that OPTIONAL variable) opened no escalation yet still parked a

package/app/persist-escalation.test.ts

@@ -212,36 +212,3 @@ test("a control-flow arm with a blank question opens nothing so gw-escalated re-
   assertEquals(inserts.escalations.length, 0, "no dead escalation is fabricated");
   assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
 });
-
-// The scope-integrity arm (persist-escalation-blockedcomments) binds the escalation to the reviewed
-// commit (issue #395): it stamps `head_sha` and marks `scope_block` so the converge-gate can honour
-// a same-HEAD human answer as an override instead of re-deriving the block and re-escalating forever.
-test("persist-escalation binds a scope-integrity escalation to the reviewed HEAD (head_sha + scope_block)", async () => {
-  const { app, inserts } = fakeApp();
-  const job = {
-    variables: {
-      prKey: "o/r#5",
-      round: 2,
-      status: "blocked",
-      question: "Scope integrity blocked: ...",
-      recordRound: false,
-      headSha: "HEAD1",
-      scopeBlock: true,
-    },
-  };
-  await handler(job as any, app as any);
-  assertEquals(inserts.escalations.length, 1);
-  assertEquals((inserts.escalations[0] as any).head_sha, "HEAD1", "the escalation carries the reviewed commit");
-  assertEquals((inserts.escalations[0] as any).scope_block, 1, "flagged as a scope-integrity block");
-});
-
-// Every other escalation arm (agent verdict, no-progress, max-rounds, stalled) omits the scope
-// binding: head_sha stays absent and scope_block defaults to 0, so the override door opens ONLY for
-// the block a human can actually answer.
-test("persist-escalation: a non-scope escalation records no HEAD binding and scope_block 0", async () => {
-  const { app, inserts } = fakeApp();
-  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
-  await handler(job as any, app as any);
-  assertEquals((inserts.escalations[0] as any).head_sha, undefined, "no reviewed HEAD to bind");
-  assertEquals((inserts.escalations[0] as any).scope_block, 0, "not a scope-integrity block");
-});

package/db/migrations/057_drop_escalation_head_override.sql

@@ -0,0 +1,16 @@
+-- Contract phase for the escalation scope-override columns (migration 056, issue #395).
+--
+-- Migration 056 added `escalations.head_sha` + `escalations.scope_block` to give the DETERMINISTIC
+-- scope-integrity gate a human-override door: it bound a scope escalation to the reviewed HEAD so a
+-- same-HEAD human answer could override the block instead of re-escalating forever. That whole
+-- deterministic gate has since been replaced by the `senior:scope-classify` AGENT classifier, which
+-- reads each closed issue's acceptance criteria and honours the recorded human `answer` directly —
+-- so nothing writes or reads these two columns any more. They are dead schema (a drift surface with
+-- no source of truth behind them), so drop them.
+--
+-- 056 is forward-only and immutable (its ledger row stays), so this is the standard expand→contract
+-- follow-up rather than an edit to 056. Both drops are safe: the columns were nullable/defaulted and
+-- have no remaining writer or reader. Numbered after the current highest prefix (056); the runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE escalations DROP COLUMN scope_block;
+ALTER TABLE escalations DROP COLUMN head_sha;

package/e2e/convergence-escalation.e2e.ts

@@ -87,6 +87,12 @@ describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
       capturedAnswer = (job.variables as Record<string, unknown>).answer;
       return { status: "converged", summary: "resolved after the human answer" };
     });
+    // `senior:scope-classify` is likewise an externalTaskType (no app worker): the converged round
+    // routes through it before finalizing. Stub it as "scope delivered" so the happy path reaches
+    // persist-converged rather than parking on an unserviced agent job.
+    await app.engine.registerWorker("senior:scope-classify", () => {
+      return { scopeBlocked: false, scopeBlockReason: "" };
+    });
   });
 
   after(async () => {

package/nano.app.json

@@ -214,7 +214,8 @@
     "senior:feature",
     "senior:trial-merge",
     "senior:retro",
-    "senior:conformance"
+    "senior:conformance",
+    "senior:scope-classify"
   ],
   "surfaces": {
     "taskInbox": {

package/package.json

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