@nanobpm/nano-workforce 0.92.0 → 0.93.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.93.0](https://github.com/nanobpm/nano-workforce/compare/v0.92.0...v0.93.0) (2026-08-19)
+
+
+### Features
+
+* enforce scope-integrity guards in the review-convergence loop ([#314](https://github.com/nanobpm/nano-workforce/issues/314)) ([0a2a012](https://github.com/nanobpm/nano-workforce/commit/0a2a012b5d11e129de27633f1ef8508bc0fb457b)), closes [#631](https://github.com/nanobpm/nano-workforce/issues/631) [#863](https://github.com/nanobpm/nano-workforce/issues/863) [#872](https://github.com/nanobpm/nano-workforce/issues/872) [#N](https://github.com/nanobpm/nano-workforce/issues/N) [#N](https://github.com/nanobpm/nano-workforce/issues/N) [#N](https://github.com/nanobpm/nano-workforce/issues/N) [#313](https://github.com/nanobpm/nano-workforce/issues/313) [#N](https://github.com/nanobpm/nano-workforce/issues/N) [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 # [0.92.0](https://github.com/nanobpm/nano-workforce/compare/v0.91.0...v0.92.0) (2026-08-19)
 
 

package/app/convergeGate.test.ts

@@ -217,9 +217,12 @@ 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>;
 }) {
   const { makeHandler } = await import("../workers/converge-gate/worker.ts");
-  return makeHandler(deps);
+  // 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.
+  return makeHandler({ readPrBody: async () => "", ...deps });
 }
 
 test("converge-gate: a clean PR is allowed to converge", async () => {
@@ -342,6 +345,82 @@ 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");

package/app/scopeGuard.test.ts

@@ -0,0 +1,147 @@
+// Scope-integrity guard — unit tests for the canonical router (app/scopeGuard.ts) and its parsing
+// helpers.
+//
+// A parity slice can be silently under-delivered: an agent splits a large slice, ships one half,
+// then `Closes #N` a broader-scoped parent while recording the deferred remainder only in PR prose
+// (a `## Scope` section) with no filed follow-up issue. Magikcraft/nano-bpm#631 → PR #863 did
+// exactly this and the deferred half was lost until a human re-filed it as #872. These two guards
+// (#313) block that class: a partial delivery may not close-keyword a broader-scoped parent, and any
+// deferral must link a filed follow-up issue rather than live in prose.
+import { test } from "node:test";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import {
+  evaluateScopeGuard,
+  findClosingKeywordRefs,
+  hasDeferralMarker,
+  hasFollowupIssueRef,
+} from "./scopeGuard.ts";
+
+// ── The canonical router ────────────────────────────────────────────────────
+
+test("evaluateScopeGuard: a full-scope PR that Closes its parent, no deferral, is allowed", () => {
+  const r = evaluateScopeGuard({ prBody: "Implements the feature end to end.\n\nCloses #313" });
+  assertEquals(r.scopeBlocked, false);
+  assertEquals(r.scopeBlockReason, "");
+});
+
+test("evaluateScopeGuard: a plain PR with no closing keyword and no deferral is allowed", () => {
+  const r = evaluateScopeGuard({ prBody: "A small refactor. Refs #10" });
+  assertEquals(r.scopeBlocked, false);
+});
+
+test("evaluateScopeGuard: Closes a broader parent AND defers scope → blocked (guard 1)", () => {
+  const r = evaluateScopeGuard({
+    prBody:
+      "Delivers the nested ad-hoc half.\n\n## Scope\nEmbedded SUB_PROCESS tools remain the deferred refinement.\n\nCloses #631",
+  });
+  assertEquals(r.scopeBlocked, true);
+  assertStringIncludes(r.scopeBlockReason, "must not close a broader-scoped issue");
+  assertStringIncludes(r.scopeBlockReason, "#631");
+});
+
+test("evaluateScopeGuard: defers scope but links NO follow-up issue → blocked (guard 2)", () => {
+  const r = evaluateScopeGuard({
+    prBody: "Ships the first half.\n\n## Scope\nThe rest is deferred.\n\nRefs #631",
+  });
+  assertEquals(r.scopeBlocked, true);
+  assertStringIncludes(r.scopeBlockReason, "no filed follow-up issue");
+  // Guard 1 must NOT fire — this PR correctly used a non-closing ref.
+  assert(
+    !r.scopeBlockReason.includes("must not close"),
+    "a non-closing ref must not trip the closing-keyword guard",
+  );
+});
+
+test("evaluateScopeGuard: defers scope AND links a filed follow-up AND uses a non-closing ref → allowed", () => {
+  const r = evaluateScopeGuard({
+    prBody:
+      "Ships the first half.\n\n## Scope\nThe embedded SUB_PROCESS half is deferred.\nTracked-in: #872\n\nRefs #631",
+  });
+  assertEquals(r.scopeBlocked, false);
+  assertEquals(r.scopeBlockReason, "");
+});
+
+test("evaluateScopeGuard: the motivating incident (Closes #631 + ## Scope + no follow-up) trips BOTH guards", () => {
+  const r = evaluateScopeGuard({
+    prBody:
+      "## Summary\nNested ad-hoc / agent-of-agents delivered.\n\n## Scope\nembedded `SUB_PROCESS` tools whose multi-element body runs by token flow remain the deferred refinement.\n\nCloses #631",
+  });
+  assertEquals(r.scopeBlocked, true);
+  assertStringIncludes(r.scopeBlockReason, "must not close a broader-scoped issue");
+  assertStringIncludes(r.scopeBlockReason, "no filed follow-up issue");
+});
+
+test("evaluateScopeGuard: a follow-up link alone does not excuse a closing keyword on a split", () => {
+  // Even with the remainder tracked, closing the broader parent is still wrong — it reads as done.
+  const r = evaluateScopeGuard({
+    prBody: "Ships half.\n\nDeferred: the rest. Follow-up: #872\n\nCloses #631",
+  });
+  assertEquals(r.scopeBlocked, true);
+  assertStringIncludes(r.scopeBlockReason, "must not close a broader-scoped issue");
+  assert(!r.scopeBlockReason.includes("no filed follow-up issue"), "the follow-up was linked");
+});
+
+test("evaluateScopeGuard: tolerates null / empty bodies", () => {
+  assertEquals(evaluateScopeGuard({ prBody: null }).scopeBlocked, false);
+  assertEquals(evaluateScopeGuard({ prBody: undefined }).scopeBlocked, false);
+  assertEquals(evaluateScopeGuard({ prBody: "" }).scopeBlocked, false);
+});
+
+// ── The parsers ─────────────────────────────────────────────────────────────
+
+test("findClosingKeywordRefs: extracts bare, cross-repo, and URL closing refs; dedupes", () => {
+  const body = [
+    "Closes #12",
+    "fixes: owner/repo#34",
+    "Resolved https://github.com/owner/repo/issues/56",
+    "Closes #12", // duplicate
+  ].join("\n");
+  assertEquals(findClosingKeywordRefs(body), [
+    "#12",
+    "owner/repo#34",
+    "https://github.com/owner/repo/issues/56",
+  ]);
+});
+
+test("findClosingKeywordRefs: a non-closing ref (Refs / Part of) is not a closing keyword", () => {
+  assertEquals(findClosingKeywordRefs("Refs #12\nPart of #34\nDepends-on: #56"), []);
+});
+
+test("hasDeferralMarker: detects a ## Scope heading and deferral phrases; ignores clean prose", () => {
+  assert(hasDeferralMarker("## Scope\nfoo"), "a Scope heading defers");
+  assert(hasDeferralMarker("### scope of work"), "any heading level counts");
+  assert(hasDeferralMarker("The rest is deferred to later."), "'deferred' defers");
+  assert(hasDeferralMarker("This is out of scope for now."), "'out of scope' defers");
+  assert(hasDeferralMarker("The remainder is left for a follow-up."), "'remainder' defers");
+  assert(!hasDeferralMarker("Implements everything. Closes #1."), "clean prose does not defer");
+});
+
+test("hasDeferralMarker: a bare 'remain*' without deferral context is not a deferral", () => {
+  // "all done" phrasing must not be read as a scope deferral (Copilot advisory,
+  // app/scopeGuard.ts:48): a full-scope PR that merely reports nothing outstanding
+  // would otherwise be blocked from converging.
+  assert(!hasDeferralMarker("No issues remain.\n\nCloses #123"), "'No issues remain' is not a deferral");
+  assert(!hasDeferralMarker("All checks remain green."), "'remain green' is not a deferral");
+  assert(!hasDeferralMarker("No failing tests remaining. Closes #7"), "'remaining' alone is not a deferral");
+  // ...but a remainder mention near genuine deferral context still defers.
+  assert(hasDeferralMarker("The remaining scope is tracked separately."), "'remaining' near 'scope' defers");
+  assert(hasDeferralMarker("Remaining work is a follow-up."), "'remaining' near 'follow-up' defers");
+});
+
+test("hasFollowupIssueRef: only an explicit tracking marker + issue ref counts", () => {
+  assert(hasFollowupIssueRef("Deferred-to: #872"), "Deferred-to marker");
+  assert(hasFollowupIssueRef("Tracked-in: owner/repo#872"), "cross-repo tracking marker");
+  assert(hasFollowupIssueRef("Follow-up: #900"), "Follow-up marker");
+  assert(hasFollowupIssueRef("Follow up issue: #900"), "Follow up issue marker");
+  assert(!hasFollowupIssueRef("The rest is deferred."), "bare deferral prose is not a filed link");
+  assert(!hasFollowupIssueRef("Refs #631"), "a parent ref is not a remainder tracker");
+  // A full GitHub issue URL is a valid filed follow-up link, same as the closing-keyword parser accepts.
+  assert(
+    hasFollowupIssueRef("Deferred-to: https://github.com/owner/repo/issues/872"),
+    "Deferred-to marker with a full issue URL",
+  );
+  assert(
+    hasFollowupIssueRef("Follow-up issue: https://github.com/nanobpm/nano-workforce/issues/900"),
+    "Follow-up marker with a full issue URL",
+  );
+});

package/app/scopeGuard.ts

@@ -0,0 +1,131 @@
+// Scope-integrity gate for the review-convergence loop (issue #313).
+//
+// A parity slice can be silently under-delivered: an agent legitimately splits a large slice, ships
+// one half, but then (a) uses a `Closes #N` closing keyword on an issue whose stated scope was
+// broader than what shipped, and (b) records the deferred remainder only in PR/commit prose (a
+// `## Scope` section) rather than as a filed, tracked issue. The parent then reads as fully done —
+// `gh issue list` shows nothing outstanding — and downstream consumers trust "issue closed =
+// capability present". This is exactly how Magikcraft/nano-bpm#631 → PR #863 (`## Scope` deferral,
+// `Closes #631`, no follow-up) lost the deferred half until a human re-filed it by hand as #872.
+//
+// This pure router encodes the two guards proposed in #313, evaluated over the PR description body
+// so the deterministic converge-gate (`workers/converge-gate`) can block a partial delivery from
+// closing a broader-scoped parent, escalating to the human `wait-answer` task instead of merging:
+//
+//   1. Closing-keyword integrity — a PR may only carry `Closes/Fixes/Resolves #N` when it delivers
+//      #N's full stated scope. When the same body ALSO defers scope (a `## Scope` section /
+//      "deferred" / "out of scope" / "remains"), the closing keyword is flagged: the PR must instead
+//      use a non-closing ref (`Refs #N` / `Part of #N`) and leave #N open (or convert #N into a
+//      tracking issue).
+//   2. Deferred ⇒ filed issue, not prose — any PR that defers part of its scope must LINK a filed
+//      follow-up issue for the remainder (`Deferred-to: #N` / `Tracked-in: #N` / `Follow-up: #N`). A
+//      deferral that exists only in commit/ADR/PR text is a drift surface (invisible, unclaimable
+//      work); mirror the repo's "no drift surfaces" rule, applied to scope.
+//
+// Both guards fire only when the body actually DEFERS scope, so a full-scope `Closes #N` PR with no
+// deferral prose passes untouched.
+
+export interface ScopeGuardInput {
+  /** The PR description body (the text `gh pr create --body` set). */
+  prBody: string | null | undefined;
+}
+
+export interface ScopeGuardResult {
+  scopeBlocked: boolean;
+  scopeBlockReason: string;
+}
+
+// GitHub's closing keywords (close/closes/closed, fix/fixes/fixed, resolve/resolves/resolved)
+// followed by an issue ref: a bare `#123`, a cross-repo `owner/repo#123`, or a full issue URL. The
+// keyword and ref may be separated by whitespace and/or a colon (`Closes: #1`, `Closes #1`).
+const CLOSING_KEYWORD =
+  /\b(close[sd]?|fix(?:e[sd])?|resolve[sd]?)[\s:]+(?:https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/\d+|(?:[\w.-]+\/[\w.-]+)?#\d+)/gi;
+
+// A body DEFERS scope when it carries a `## Scope` (any heading level) section OR names a deferral in
+// prose. A bare `remain*`/`remainder` is deliberately NOT enough on its own — normal "all done"
+// phrasing ("No issues remain.", "no failing tests remaining") uses it without deferring any scope,
+// and flagging that would block a full-scope PR from converging. A remainder mention only defers when
+// a deferral-context term (scope / follow-up / later / to-do / tracking) sits near it; the incident's
+// honest deferral read "…remain the deferred refinement", which the explicit `defer*` branch catches.
+const DEFERRAL_HEADING = /^#{1,6}\s+scope\b/im;
+const DEFERRAL_PHRASE = /\bdefer(?:s|red|ral|ring)?\b|\bout[- ]of[- ]scope\b/i;
+const REMAINDER_WORD = /\bremain(?:s|der|ing)?\b/gi;
+const REMAINDER_CONTEXT = /\b(?:scope|follow[- ]?ups?|later|to[- ]?dos?|track(?:s|ed|ing)?|next[- ]steps?)\b/i;
+const REMAINDER_WINDOW = 48;
+
+// Whether any `remain*` mention sits within a short window of a deferral-context term.
+function remainderDefersScope(text: string): boolean {
+  for (const m of text.matchAll(REMAINDER_WORD)) {
+    const idx = m.index ?? 0;
+    const window = text.slice(Math.max(0, idx - REMAINDER_WINDOW), idx + m[0].length + REMAINDER_WINDOW);
+    if (REMAINDER_CONTEXT.test(window)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// A FILED follow-up issue link for the deferred remainder: an explicit tracking marker followed by
+// an issue ref — a bare `#123`, a cross-repo `owner/repo#123`, or a full issue URL (matching the
+// closing-keyword parser, so an explicit `https://github.com/<owner>/<repo>/issues/<n>` link counts
+// as a tracked follow-up rather than being mistaken for untracked prose). This is the
+// machine-checkable contract feature.md asks split slices to emit.
+const FOLLOWUP_MARKER =
+  /\b(?:deferred[- ]to|tracked[- ]in|tracking issue|follow[- ]?ups?(?:\s+issue)?)\b[\s:]*(?:https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/issues\/\d+|(?:[\w.-]+\/[\w.-]+)?#\d+)/i;
+
+/** The distinct issue refs a body closes via a GitHub closing keyword, in first-seen order. */
+export function findClosingKeywordRefs(body: string | null | undefined): string[] {
+  const text = body ?? "";
+  const refs: string[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(CLOSING_KEYWORD)) {
+    const ref = m[0].slice(m[1].length).replace(/^[\s:]+/, "").trim();
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      refs.push(ref);
+    }
+  }
+  return refs;
+}
+
+/** Whether the body defers part of its scope (a `## Scope` section or a deferral phrase). */
+export function hasDeferralMarker(body: string | null | undefined): boolean {
+  const text = body ?? "";
+  return DEFERRAL_HEADING.test(text) || DEFERRAL_PHRASE.test(text) || remainderDefersScope(text);
+}
+
+/** Whether the body links a filed follow-up issue for the deferred remainder. */
+export function hasFollowupIssueRef(body: string | null | undefined): boolean {
+  return FOLLOWUP_MARKER.test(body ?? "");
+}
+
+/** Decide whether a PR's scope framing is safe to converge/merge. Pure; the worker feeds it the
+ * live PR body and fails CLOSED (blocks) when that body cannot be read. */
+export function evaluateScopeGuard(input: ScopeGuardInput): ScopeGuardResult {
+  const body = input.prBody ?? "";
+  const defers = hasDeferralMarker(body);
+  const reasons: string[] = [];
+
+  if (defers) {
+    const closing = findClosingKeywordRefs(body);
+    if (closing.length > 0) {
+      const noun = closing.length === 1 ? "issue" : "issues";
+      reasons.push(
+        `this PR defers part of its scope yet closing-keywords ${noun} ${closing.join(", ")} — a partial delivery must not close a broader-scoped issue; use a non-closing ref (Refs #N / Part of #N) and leave it open (or convert it into a tracking issue)`,
+      );
+    }
+    if (!hasFollowupIssueRef(body)) {
+      reasons.push(
+        "this PR defers part of its scope but links no filed follow-up issue for the remainder — file a tracking issue for each deferred item and link it (Deferred-to: #N / Tracked-in: #N / Follow-up: #N) so the remainder is tracked, not left in PR prose",
+      );
+    }
+  }
+
+  if (reasons.length === 0) {
+    return { scopeBlocked: false, scopeBlockReason: "" };
+  }
+  return {
+    scopeBlocked: true,
+    scopeBlockReason: `Scope integrity blocked: ${reasons.join("; ")}.`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.92.0",
+  "version": "0.93.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/prompts/feature.md

@@ -80,9 +80,38 @@ against the wrong base will not be merged into the epic.
 3. Implement `task.prompt`. Keep the change scoped to this slice only.
 4. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the
    branch, and open a pull request with `gh pr create` describing the slice and
-   linking the parent issue (`Depends-on:`/`Closes` as appropriate).
+   linking the parent issue (`Depends-on:`/`Closes` as appropriate — but read the
+   scope-split rule below before you reach for `Closes`).
 5. Clean up any scratch clone/worktree you created outside the commit.
 
+## Closing keywords vs. scope splits — don't close a broader-scoped parent
+
+The convergence loop runs a deterministic **scope-integrity gate** on your PR
+before it can merge (`workers/converge-gate` → `app/scopeGuard.ts`). It exists
+because a parity slice was once silently under-delivered: an agent shipped one
+half, documented the deferred remainder honestly in a `## Scope` section, yet
+still `Closes #N`'d the broader parent and filed **no** follow-up. The issue read
+as done, `gh issue list` showed nothing outstanding, and a downstream consumer was
+blocked on exactly the deferred half. Two rules keep that from recurring — the
+gate **blocks and escalates to a human** if you break either:
+
+1. **A `Closes/Fixes/Resolves #N` closing keyword means you delivered #N's FULL
+   stated scope.** If you split scope — shipping only part and deferring the rest
+   — do **not** close-keyword the parent. Use a non-closing ref instead
+   (`Refs #N` / `Part of #N`) and **leave #N open** (or convert #N into a
+   tracking/umbrella issue for the remainder). The gate flags any PR that both
+   closes #N and also contains deferral prose (a `## Scope` section, "deferred",
+   "out of scope").
+2. **A deferred remainder must be a FILED, tracked issue — never just prose.** If
+   your PR defers part of its scope, **file a follow-up issue for each deferred
+   item** and link it in the PR body with an explicit tracking marker the gate can
+   see: `Deferred-to: #N`, `Tracked-in: #N`, or `Follow-up: #N`. A deferral that
+   lives only in commit/PR/ADR text is an invisible, unclaimable drift surface.
+
+So: deliver the whole thing → `Closes #N`. Split it → `Refs #N`, file the
+remainder, and link it with `Deferred-to: #<new-issue>`.
+
+
 > **Do not request the Copilot review yourself.** When you open a *ready* PR the
 > app enrolls it into the review-convergence loop and requests the initial
 > Copilot review for you. In particular, **never escalate because Copilot is

package/workers/converge-gate/worker.ts

@@ -11,6 +11,14 @@
 // 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 ALSO enforces the scope-integrity guards (#313) over the PR description, blocking handoff when
+// the PR under-delivers a broader-scoped parent:
+//   • a partial delivery that `Closes/Fixes/Resolves #N` while ALSO deferring scope (a `## Scope`
+//     section / "deferred" / "out of scope"), or
+//   • a deferral recorded only in PR prose with no filed follow-up issue linked for the remainder.
+// This is the enforcement backstop for the Magikcraft/nano-bpm#631 → PR #863 (`Closes #631`, `##
+// Scope` deferral, no follow-up → re-filed by hand as #872) failure class. See app/scopeGuard.ts.
+//
 // 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.
@@ -18,11 +26,13 @@ import type { AppJobHandler } from "@nanobpm/urban";
 import { type ConvergeGateResult, evaluateConvergeGate } from "../../app/convergeGate.ts";
 import {
   fetchLatestCopilotReviewBody,
+  fetchPrMeta,
   fetchReviewThreads,
   parseAckedAdvisories,
   parseSuppressedAdvisories,
   type ReviewThread,
 } from "../../app/github.ts";
+import { evaluateScopeGuard } from "../../app/scopeGuard.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -37,20 +47,31 @@ export type ThreadsReader = (repo: string, prNumber: number) => Promise<ReviewTh
 // 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>;
+// Reads the PR's own description body. `null` = no usable transport (unverifiable → fail closed);
+// `""` = transport usable but the PR has an empty description (verified: nothing to scope-check).
+export type PrBodyReader = (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 defaultReadPrBody: PrBodyReader = async (repo, prNumber) => {
+  const meta = await fetchPrMeta(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+  return meta ? meta.body : null;
+};
 
 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).";
 
+const BLOCK_UNVERIFIABLE_BODY =
+  "Convergence blocked: could not read the PR description from GitHub to verify scope integrity. A human must confirm this PR does not close a broader-scoped parent with an untracked deferred remainder before it 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;
+  readPrBody: PrBodyReader;
 }): AppJobHandler<In, Out> {
   return async (job) => {
     const { prKey, repo, prNumber } = job.variables;
@@ -64,6 +85,7 @@ export function makeHandler(deps: {
     }
 
     let result: ConvergeGateResult;
+    let scopeReason: string;
     try {
       const threads = await deps.readThreads(ghRepo, ghNumber);
       // A null threads read is an unverifiable gate — fail closed. (An empty ARRAY is a verified
@@ -87,9 +109,30 @@ export function makeHandler(deps: {
       return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
     }
 
+    // The scope-integrity guard (#313) reads/parses the PR description in its OWN try — a transport
+    // or parse failure here is a scope read failure, so it must surface BLOCK_UNVERIFIABLE_BODY, not
+    // the review-comment BLOCK_UNVERIFIABLE above. Sharing one catch would mislabel a description
+    // read failure as a review-thread verification failure and point the human escalation at the
+    // wrong place.
+    try {
+      // The PR description drives the scope-integrity guard (#313). A null read is unverifiable —
+      // fail closed with a scope-specific reason. (An empty STRING is a verified empty description:
+      // no closing keyword, no deferral, so the scope guard passes.)
+      const prBody = await deps.readPrBody(ghRepo, ghNumber);
+      if (prBody === null) {
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE_BODY };
+      }
+      scopeReason = evaluateScopeGuard({ prBody }).scopeBlockReason;
+    } catch {
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE_BODY };
+    }
+
+    // Both guards gate the same handoff to the merge loop: block if EITHER the review-comment gate
+    // or the scope-integrity gate blocks, joining their reasons so the human sees every cause.
+    const reason = [result.convergeBlockReason, scopeReason].filter((r) => r !== "").join(" ");
     return {
-      convergeBlocked: result.convergeBlocked,
-      convergeBlockReason: result.convergeBlockReason,
+      convergeBlocked: result.convergeBlocked || scopeReason !== "",
+      convergeBlockReason: reason,
     };
   };
 }
@@ -97,5 +140,6 @@ export function makeHandler(deps: {
 const handler = makeHandler({
   readThreads: defaultReadThreads,
   readReviewBody: defaultReadReviewBody,
+  readPrBody: defaultReadPrBody,
 });
 export default handler;