@nanobpm/nano-workforce 0.115.0 → 0.116.0

package/resources/prompts/scope-classify.md

@@ -0,0 +1,142 @@
+# Scope-integrity classifier — one verdict per converged PR
+
+You are an autonomous engineer acting as a **scope-integrity classifier** for a
+GitHub pull request that has just passed the deterministic review-comment gate
+(every Copilot thread resolved, every advisory acknowledged). Your one job this
+activation is to decide **whether this PR is safe to converge on scope grounds**,
+then return a structured verdict. You do **not** review code, run tests, or push
+anything — you read, judge, and report.
+
+## Why you exist (replaces a regex)
+
+A previous version of this gate was a regex: it blocked any PR whose body carried a
+`Closes/Fixes/Resolves #N` **and** any deferral word (`deferred`, `out of scope`, a
+`## Scope` section) without a linked follow-up issue. That regex could not read the
+closed issue, so it false-positived on PRs that merely *mention* deferral (an ADR
+non-goal that says "deferred", or a PR whose subject is scope tooling) and forced
+needless human escalations. You replace it with a real judgment: **read the closed
+issue's stated scope and compare it against what the PR delivers.**
+
+## The failure class you protect against
+
+A partial delivery silently under-delivers a broader-scoped parent: an agent splits a
+large slice, ships one half, `Closes #N` an issue whose stated scope was broader than
+what shipped, and records the deferred remainder only in PR/commit prose (never 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". That lost work is what you must catch.
+
+## Job input (`job.variables`)
+
+| var        | meaning                                                             |
+|------------|---------------------------------------------------------------------|
+| `prUrl`    | canonical PR URL                                                    |
+| `repo`     | `owner/name`                                                        |
+| `prNumber` | PR number                                                           |
+| `scopeAnswer` | present only when resuming from a scope escalation you raised — a human's decision |
+| `prompt`   | this document                                                       |
+
+## Abort if the run was cancelled
+
+A human can **cancel** this run while you work. An **"Abort if this run was
+cancelled"** protocol with a status URL is appended below. You produce no side
+effects (no push, no PR edit), so a cancel is cheap — but still **stop immediately**
+if the status check fails or reports `"abandoned": true`, and do not bother writing a
+result.
+
+## What to do
+
+1. **Read the PR body.** `gh pr view <prNumber> --repo <repo> --json body,title`.
+   Extract every issue the body **closes with a GitHub closing keyword** —
+   `close/closes/closed`, `fix/fixes/fixed`, `resolve/resolves/resolved` followed by
+   `#N`, `owner/repo#N`, or a full issue URL. A **non-closing** reference (`Refs #N`,
+   `Part of #N`, `Depends-on #N`, `Follow-up: #N`) does **not** close an issue —
+   ignore those for the closing-scope check (but note the follow-up links; see below).
+
+2. **If there are no closing-keyword issues, the PR closes nothing** — there is no
+   broader-scoped parent to under-deliver. Return **`scopeBlocked: false`** and stop.
+
+3. **For each closed issue, read its stated scope.**
+   `gh issue view <N> --repo <repo> --json title,body`. Read its acceptance
+   criteria / definition of done. If the issue lives in another repo
+   (`owner/repo#N`), pass that repo.
+
+4. **Judge under-delivery.** For each closed issue, decide: **does this PR actually
+   deliver that issue's full stated scope?** Compare the issue's acceptance criteria
+   against what the PR's diff and body demonstrably deliver (`gh pr view --json files`,
+   `gh pr diff` if you need to confirm). Block **only** when the PR genuinely leaves
+   part of a *closed* issue's stated scope undelivered, with that remainder **not**
+   tracked by a filed, linked follow-up issue.
+
+   Explicitly **do NOT block** on any of these — they are the false positives that
+   motivated this classifier:
+   - The PR **fully delivers** the closed issue's acceptance, even if the body
+     discusses future work, sibling slices, or an epic. Full delivery + a `Closes` is
+     exactly correct.
+   - The deferred thing is an **explicit non-goal** of the issue/ADR (e.g. "real I/O
+     deferred per ADR non-goals") — a declared boundary the issue never promised, not
+     under-delivery.
+   - The deferred remainder **is** tracked: the body links a filed follow-up
+     (`Follow-up: #M`, `Tracked-in: #M`, `Deferred-to: #M`) or names sibling slice
+     issues that are themselves filed and open/closed.
+   - The body merely **mentions or describes** deferral/scope as its subject matter
+     (e.g. a PR that changes scope tooling) without the PR itself deferring a closed
+     issue's scope.
+
+5. **Honor a human decision.** If `scopeAnswer` is present, a human already ruled on a
+   scope escalation you raised. Treat their decision as authoritative: unless the PR
+   *now* clearly still under-delivers a closed issue with an untracked remainder (e.g.
+   they told you to proceed but the closing keyword and gap are both still there and
+   they did not say to close it manually), return **`scopeBlocked: false`** and record
+   in `scopeBlockReason`/summary that you deferred to the human. Do **not** re-raise
+   the identical escalation a human already answered — that is the loop defect (#395)
+   you must not reproduce.
+
+## Verdict (job result variables)
+
+Return **exactly** these two variables:
+
+| var               | type    | meaning                                                    |
+|-------------------|---------|------------------------------------------------------------|
+| `scopeBlocked`    | boolean | `true` only when a closed issue is genuinely under-delivered with an untracked remainder |
+| `scopeBlockReason`| string  | when blocked: the **specific** finding — which issue, which acceptance criteria are unmet, and what the human should do (file+link a tracker and downgrade `Closes #N`→`Part of #N`, or reword). Empty string when not blocked. |
+
+Make `scopeBlockReason` **actionable and specific** — name the issue number, quote or
+paraphrase the unmet acceptance criterion, and state the fix. Never emit the old
+generic "this PR defers part of its scope"; that opacity is the whole reason you
+exist.
+
+### How to return it (the wire mechanism)
+
+Your result only reaches the process through the harness's result channel — prose in
+your output is **not** parsed. Emit a machine-readable result one of two ways:
+
+1. **Write a flat JSON object to `$AGENT_RESULT_FILE`** (an env var the harness sets),
+   once, at the very end. Example (not blocked):
+
+   ```sh
+   printf '%s' '{"scopeBlocked":false,"scopeBlockReason":""}' > "$AGENT_RESULT_FILE"
+   ```
+
+   Blocked example:
+
+   ```sh
+   printf '%s' '{"scopeBlocked":true,"scopeBlockReason":"#412 requires both the read AND write projection (acceptance criteria 2 + 3); this PR ships only the read side and defers the write projection with no filed tracker. File a follow-up issue for the write projection, link it (Follow-up: #N), and downgrade Closes #412 -> Part of #412 (close #412 by hand only when the write side lands)."}' > "$AGENT_RESULT_FILE"
+   ```
+
+2. **Fallback** (only if you cannot write the file): print a single last line to
+   stdout of the form `::nano:result:: {json}` — e.g.
+
+   ```
+   ::nano:result:: {"scopeBlocked":false,"scopeBlockReason":""}
+   ```
+
+   The harness reads the **last** such line; a trailing fenced JSON block is a last
+   resort.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** Exit `0` on every path (a non-zero exit means a crash and the job is
+retried). If you are genuinely unable to reach a confident verdict, prefer
+**`scopeBlocked: false`** with a `scopeBlockReason` explaining the uncertainty:
+convergence here is recoverable (a human still reviews the merge), whereas a
+false block re-introduces exactly the needless escalation this classifier removes.

package/test/derivation-parity/derivation-parity.test.ts

@@ -122,8 +122,8 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
   assertEquals(between("review-round", "serviceTask", "incoming"), 3, "review-round should merge 3 flows on the task itself");
   // (b) a single exclusive gateway forks FOUR heterogeneous-condition out-edges.
   assertEquals(between("gw-status", "exclusiveGateway", "outgoing"), 4, "gw-status should be a 4-way exclusive gateway");
-  // (c) a single exclusive gateway is at once a 5-way merge and a 2-way split.
-  assertEquals(between("gw-escalated", "exclusiveGateway", "incoming"), 5, "gw-escalated should merge 5 flows");
+  // (c) a single exclusive gateway is at once a 6-way merge and a 2-way split.
+  assertEquals(between("gw-escalated", "exclusiveGateway", "incoming"), 6, "gw-escalated should merge 6 flows");
   assertEquals(between("gw-escalated", "exclusiveGateway", "outgoing"), 2, "gw-escalated should also split 2 ways");
 });
 

package/test/derivation-parity/flows.ts

@@ -171,7 +171,7 @@ export const PORTS: readonly PortEntry[] = [
       "directly (in=3), but loop() always inserts an exclusive-gateway head " +
       "(task stays in=1); `gw-status` is one gateway with 4 heterogeneous-" +
       "condition out-edges (no switch/branch emits that); `gw-escalated` is one " +
-      "gateway that is at once a 5-way merge and a 2-way split. Awaits an " +
+      "gateway that is at once a 6-way merge and a 2-way split. Awaits an " +
       "arbitrary-graph / explicit-join (named-target) builder upstream in " +
       "@nanobpm/workflow (nano-ide) — a superset of the multi-start/end gap.",
   },

package/workers/converge-gate/worker.ts

@@ -3,30 +3,22 @@
 // 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:
+// the comment unaddressed). This step runs on the converged path, BEFORE the scope classifier and
+// pr.finalize hand 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 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.
-//
-// The scope-integrity block also carries a HUMAN-OVERRIDE door (#395): before it re-blocks, it
-// reads the commit now under review and consults the `escalations` answer bound to that SAME HEAD.
-// An operator who answered the scope question for this exact commit ("this fully delivers the issue
-// — keep the closing keyword") has explicitly overridden it, so the gate honours that answer
-// (audited) instead of re-deriving `scopeBlocked` from the PR body and re-escalating the identical
-// question forever. Binding to the HEAD sha keeps the override from carrying across a new push, and
-// (via `PrConvergeGateOut.headSha`/`scopeBlocked`) lets `persist-escalation-blockedcomments` stamp
-// the escalation with the reviewed commit so the door can open on the next round.
+// Scope integrity is NO LONGER judged here. A deterministic regex over the PR description could not
+// read the closed issue's acceptance criteria, so it false-positived on any body that merely
+// *mentioned* deferral (an ADR non-goal, a PR whose subject is scope tooling) and forced needless
+// human escalations. That judgment now lives in the `classify-scope` agent task (job type
+// `senior:scope-classify`, prompt `resources/prompts/scope-classify.md`), which runs immediately
+// after this gate on the converged path and reads each closed issue's stated scope. This worker's
+// sole responsibility is the review-comment gate.
 //
 // 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
@@ -35,14 +27,11 @@ import type { AppJobHandler } from "@nanobpm/urban";
 import { type ConvergeGateResult, evaluateConvergeGate } from "../../app/convergeGate.ts";
 import {
   fetchLatestCopilotReviewBody,
-  fetchPrHead,
-  fetchPrMeta,
   fetchReviewThreads,
   parseAckedAdvisories,
   parseSuppressedAdvisories,
   type ReviewThread,
 } from "../../app/github.ts";
-import { evaluateScopeGuard, isScopeOverridden, type ScopeEscalationAnswer } from "../../app/scopeGuard.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -57,82 +46,22 @@ 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>;
-// Reads the PR's current HEAD sha (the commit under review). `null` = unreadable/no transport — the
-// scope override cannot be verified or bound to a commit, so the gate keeps blocking (fail closed).
-export type HeadShaReader = (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 defaultReadHeadSha: HeadShaReader = async (repo, prNumber) => {
-  const head = await fetchPrHead(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
-  return head ? head.headSha : 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).";
-
-// An `escalations` row as this worker reads it back when looking for a recorded human override.
-interface EscalationRow extends Record<string, unknown> {
-  id: number;
-  head_sha: string | null;
-  answer: string | null;
-  scope_block: number | boolean | null;
-}
-
-// Find the newest ANSWERED scope-integrity escalation for this PR whose recorded HEAD matches the
-// commit now under review (issue #395). This is the human-override door: `persist-escalation` binds
-// a scope block to the HEAD it was raised against, `answer-escalation` marks the row `answered`, and
-// here we honour that answer for the SAME HEAD so the gate stops re-deriving `scopeBlocked` from the
-// PR body and re-escalating the identical question forever. Newest-first so a re-escalated-then-
-// answered duplicate resolves to the operator's latest reply. Returns `null` on any read failure —
-// the caller then keeps the block (fail closed), never fabricates an override.
-async function findScopeOverride(
-  app: Parameters<AppJobHandler<In, Out>>[1],
-  prKey: string,
-  headSha: string,
-): Promise<ScopeEscalationAnswer | null> {
-  try {
-    // `scope_block` is a first-class column (persist-escalation writes it as 0/1), so filter on it
-    // in the query rather than reading every answered escalation and filtering in memory — a PR with
-    // many answered non-scope escalations no longer loads them all just to discard them.
-    const rows = await app.data.table<EscalationRow>("escalations", "id").find({
-      pr_key: prKey,
-      status: "answered",
-      scope_block: 1,
-    });
-    const scoped = rows
-      .map((r) => ({ escalationId: Number(r.id), headSha: r.head_sha ?? null, answer: r.answer ?? null }))
-      .sort((a, b) => (b.escalationId ?? 0) - (a.escalationId ?? 0));
-    for (const candidate of scoped) {
-      if (isScopeOverridden(headSha, candidate)) return candidate;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
 /** 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;
-  readHeadSha: HeadShaReader;
 }): AppJobHandler<In, Out> {
-  return async (job, app) => {
+  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.
@@ -142,12 +71,8 @@ export function makeHandler(deps: {
     if (!ghRepo || typeof ghNumber !== "number") {
       return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
     }
-    // The canonical escalations key. Prefer the carried prKey; fall back to the parsed identity so
-    // the override lookup still keys off `owner/repo#N` when only repo/prNumber survived.
-    const escPrKey = typeof prKey === "string" && prKey !== "" ? prKey : `${ghRepo}#${ghNumber}`;
 
     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
@@ -171,83 +96,15 @@ 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 };
-    }
-
-    // The human-override door for the scope-integrity block (issue #395). When the deterministic
-    // scope guard would re-block, read the commit now under review and consult the recorded
-    // escalation answer bound to that SAME HEAD: an operator who answered the scope question for
-    // this exact commit has explicitly overridden it ("this fully delivers the issue — keep the
-    // closing keyword"), so honour it (audited) instead of re-deriving the block from the body and
-    // re-escalating forever. Binding to the HEAD sha keeps the override from carrying across a new
-    // push (a different HEAD legitimately re-opens the gate); and if the human instead asked for a
-    // real split, the servicing agent pushes a fix — moving the HEAD so this stale override never
-    // fires. This is what turns the infinite escalation loop into a resolvable one.
-    let headSha: string | null = null;
-    let scopeBlocked = scopeReason !== "";
-    if (scopeBlocked) {
-      try {
-        headSha = await deps.readHeadSha(ghRepo, ghNumber);
-      } catch {
-        headSha = null;
-      }
-      if (headSha) {
-        const override = await findScopeOverride(app, escPrKey, headSha);
-        if (override) {
-          app.log.info("converge-gate: scope-integrity block overridden by human answer", {
-            prKey: escPrKey,
-            headSha,
-            escalationId: override.escalationId ?? null,
-            // The human answer is free-form operator input — never log it verbatim (it can carry
-            // sensitive content into application logs). Record only stable identifiers plus a
-            // minimal presence/length signal for debugging.
-            hasAnswer: override.answer != null && override.answer !== "",
-            answerLength: override.answer?.length ?? 0,
-          });
-          scopeReason = "";
-          scopeBlocked = false;
-        }
-      }
-    }
-
-    // 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(" ");
-    const out: Out = {
-      convergeBlocked: result.convergeBlocked || scopeBlocked,
-      convergeBlockReason: reason,
+    return {
+      convergeBlocked: result.convergeBlocked,
+      convergeBlockReason: result.convergeBlockReason,
     };
-    // Surface the reviewed HEAD and the scope-block flag ONLY when scope actually blocks — the
-    // `persist-escalation-blockedcomments` arm (which runs only on a blocked gate) binds the
-    // escalation to this commit with them, opening the override door on the next round. A clean
-    // converge keeps its original `{ convergeBlocked, convergeBlockReason }` shape.
-    if (scopeBlocked) {
-      out.scopeBlocked = true;
-      out.headSha = headSha ?? undefined;
-    }
-    return out;
   };
 }
 
 const handler = makeHandler({
   readThreads: defaultReadThreads,
   readReviewBody: defaultReadReviewBody,
-  readPrBody: defaultReadPrBody,
-  readHeadSha: defaultReadHeadSha,
 });
 export default handler;

package/workers/persist-escalation/worker.ts

@@ -50,7 +50,7 @@ function workerOf(vars: Record<string, unknown>): string | undefined {
 }
 
 const handler: AppJobHandler<In> = async (job, app) => {
-  const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl, headSha, scopeBlock } = job.variables;
+  const { prKey, round, summary, repo, prNumber, prUrl, abandonUrl } = job.variables;
   // `status` drives the escalation kind (control flow); a blank/absent status is an
   // unclassified escalation -> a question needing input. `question` is returned as a
   // process variable below so the downstream `wait-answer` userTask + `pr-escalation.form`
@@ -116,13 +116,6 @@ const handler: AppJobHandler<In> = async (job, app) => {
     worker,
     status: "open",
     asked_at: now,
-    // Bind a scope-integrity escalation to the reviewed commit (issue #395) so the converge-gate
-    // can honour a human answer as an override for THIS HEAD instead of re-deriving the block from
-    // the PR body and re-escalating forever. Only the scope-integrity arm passes these; every other
-    // arm leaves them absent (→ head_sha NULL, scope_block DEFAULT 0), so the override door opens
-    // exclusively for the block the human can actually answer.
-    head_sha: headSha,
-    scope_block: scopeBlock === true ? 1 : 0,
   });
   await app.data.table("pull_requests", "pr_key").update(prKey, {
     status: "escalated",

package/app/scopeGuard.test.ts

@@ -1,185 +0,0 @@
-// 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,
-  isScopeOverridden,
-} 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",
-  );
-});
-
-// ── The human-override door (#395) ──────────────────────────────────────────
-// The scope-integrity gate re-derives `scopeBlocked` from the PR body every round, so answering
-// its escalation used to re-block identically (an infinite loop). An answer bound to the SAME
-// reviewed HEAD is now honoured as an explicit override; a different HEAD (a new push) is not.
-
-test("isScopeOverridden: an answer bound to the same HEAD overrides the block", () => {
-  assert(
-    isScopeOverridden("abc123", { escalationId: 7, headSha: "abc123", answer: "Full delivery — keep Closes." }),
-    "same-HEAD answered escalation is an override",
-  );
-});
-
-test("isScopeOverridden: an answer for a DIFFERENT HEAD does not override (a new push re-opens)", () => {
-  assert(
-    !isScopeOverridden("newHEAD", { escalationId: 7, headSha: "oldHEAD", answer: "Full delivery." }),
-    "an override never carries across a new push",
-  );
-});
-
-test("isScopeOverridden: no recorded answer is never an override", () => {
-  assertEquals(isScopeOverridden("abc123", null), false);
-  assertEquals(isScopeOverridden("abc123", undefined), false);
-});
-
-test("isScopeOverridden: a missing/blank HEAD on either side fails closed (no override)", () => {
-  assertEquals(isScopeOverridden(null, { headSha: "abc123", answer: "x" }), false, "unreadable current HEAD");
-  assertEquals(isScopeOverridden("", { headSha: "abc123", answer: "x" }), false, "blank current HEAD");
-  assertEquals(isScopeOverridden("abc123", { headSha: null, answer: "x" }), false, "unrecorded escalation HEAD");
-  assertEquals(isScopeOverridden("abc123", { headSha: "  ", answer: "x" }), false, "blank escalation HEAD");
-});
-
-test("isScopeOverridden: the answer text is not parsed for intent — presence at the HEAD is the signal", () => {
-  // On an unchanged HEAD, the operator completing the escalation IS the explicit approval: had they
-  // wanted a real split, the servicing agent would have pushed a fix, moving the HEAD.
-  assert(isScopeOverridden("abc123", { headSha: "abc123", answer: null }), "a null answer at the HEAD still overrides");
-});