@nanobpm/nano-workforce 0.115.0 → 0.117.0

package/app/scopeGuard.ts

@@ -1,165 +0,0 @@
-// 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("; ")}.`,
-  };
-}
-
-// A recorded human answer to a scope-integrity escalation, bound to the PR HEAD it was raised
-// against (issue #395). This is the override door the deterministic scope gate lacked: without it,
-// the gate re-derives `scopeBlocked` from the PR body every round and re-escalates the identical
-// question, so a legitimate human override ("this fully delivers the issue — keep the closing
-// keyword") is unresolvable through the escalation the loop itself opens (infinite loop).
-export interface ScopeEscalationAnswer {
-  /** The escalation row id, for the audit trail. */
-  escalationId?: number;
-  /** The PR HEAD sha this scope escalation was raised against (`escalations.head_sha`). */
-  headSha: string | null | undefined;
-  /** The operator's recorded answer/rationale (`escalations.answer`), surfaced in the audit. */
-  answer: string | null | undefined;
-}
-
-/** Decide whether a recorded human answer overrides the scope-integrity block for the commit
- * currently under review. The override is honoured ONLY when the human answered a scope-integrity
- * escalation that was raised against the SAME HEAD sha now being checked — binding the override to
- * the reviewed commit so a later push (a different HEAD) re-opens the gate instead of silently
- * carrying the override forward. Pure and total: a missing/blank current HEAD or a missing/blank
- * recorded HEAD never matches, so an unverifiable HEAD fails closed (no override) rather than
- * waving the gate through. The answer TEXT is not parsed for intent: on an unchanged HEAD the human
- * completing the escalation IS the explicit approval (had they wanted a real fix, the servicing
- * agent would have pushed a new commit, moving the HEAD and side-stepping this override). */
-export function isScopeOverridden(
-  currentHeadSha: string | null | undefined,
-  answered: ScopeEscalationAnswer | null | undefined,
-): boolean {
-  if (!answered) return false;
-  const current = typeof currentHeadSha === "string" ? currentHeadSha.trim() : "";
-  const recorded = typeof answered.headSha === "string" ? answered.headSha.trim() : "";
-  if (current === "" || recorded === "") return false;
-  return current === recorded;
-}

package/workers/converge-gate/worker.test.ts

@@ -1,116 +0,0 @@
-// pr.converge-gate — the human-override door for the scope-integrity block (issue #395).
-//
-// The scope-integrity gate re-derives `scopeBlocked` from the PR body every converged round. Before
-// this fix, answering its escalation re-entered the loop, the gate re-blocked identically, and the
-// operator was trapped in an infinite escalation (a fresh escalationId each cycle) — the only escape
-// was mangling the PR body into a non-closing ref. These tests pin the override door: an escalation
-// answer bound to the SAME reviewed HEAD satisfies the gate (audited), a different HEAD (a new push)
-// re-opens it, and an unreadable HEAD keeps the block (fail closed).
-import { test } from "node:test";
-import { assert, assertEquals } from "#test-assert";
-import { noopLog } from "../../test/log.ts";
-import { makeHandler } from "./worker.ts";
-
-// A PR body that trips the scope-integrity guard: it defers scope (`## Scope`) yet closes a
-// broader-scoped parent (`Closes #631`) and links no filed follow-up.
-const SCOPE_BLOCKING_BODY =
-  "Delivers the first half.\n\n## Scope\nThe embedded tools remain the deferred refinement.\n\nCloses #631";
-
-// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors persist-escalation.test
-function fakeApp(escalations: Record<string, unknown>[]): any {
-  const stores: Record<string, Record<string, unknown>[]> = { escalations };
-  return {
-    stores,
-    data: {
-      table(name: string, key: string) {
-        const store = (stores[name] ??= []);
-        return {
-          // biome-ignore lint/suspicious/noExplicitAny: test double
-          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
-        };
-      },
-    },
-    log: noopLog(),
-  };
-}
-
-function deps(overrides: {
-  headSha?: string | null;
-  prBody?: string;
-  headThrows?: boolean;
-}) {
-  const headSha = "headSha" in overrides ? (overrides.headSha ?? null) : "HEAD1";
-  return {
-    readThreads: () => Promise.resolve([]),
-    readReviewBody: () => Promise.resolve(""),
-    readPrBody: () => Promise.resolve(overrides.prBody ?? SCOPE_BLOCKING_BODY),
-    readHeadSha: () => (overrides.headThrows ? Promise.reject(new Error("gh down")) : Promise.resolve(headSha)),
-  };
-}
-
-const job = { variables: { prKey: "o/r#5", repo: "o/r", prNumber: 5 } } as never;
-
-test("scope blocks with no answered escalation → blocked, and surfaces the reviewed HEAD to bind the escalation", async () => {
-  const app = fakeApp([]);
-  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
-  assertEquals(out.convergeBlocked, true);
-  assertEquals(out.scopeBlocked, true);
-  assertEquals(out.headSha, "HEAD1", "the reviewed HEAD is returned so persist-escalation can bind it");
-});
-
-test("scope blocks but a human answered the escalation for the SAME HEAD → override honoured (loop broken)", async () => {
-  const app = fakeApp([
-    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "Full delivery — keep Closes." },
-  ]);
-  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
-  assertEquals(out.convergeBlocked, false, "the same-HEAD human answer satisfies the scope gate");
-  assertEquals(out.convergeBlockReason, "");
-  // A cleared scope block routes to finalize, so the block-only binding fields are not emitted.
-  assertEquals(out.scopeBlocked, undefined);
-});
-
-test("scope blocks and the answer was for a DIFFERENT HEAD (a new push) → still blocked", async () => {
-  const app = fakeApp([
-    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "OLDHEAD", answer: "Full delivery." },
-  ]);
-  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
-  assertEquals(out.convergeBlocked, true, "a stale override never carries across a new push");
-  assertEquals(out.scopeBlocked, true);
-});
-
-test("scope blocks and an answered NON-scope escalation sits at the same HEAD → not an override", async () => {
-  const app = fakeApp([
-    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 0, head_sha: "HEAD1", answer: "unrelated" },
-  ]);
-  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
-  assertEquals(out.convergeBlocked, true, "only a scope-integrity escalation opens the scope override door");
-});
-
-test("scope blocks but the reviewed HEAD is unreadable → keep the block (fail closed)", async () => {
-  const app = fakeApp([
-    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "override" },
-  ]);
-  const nullHead = (await makeHandler(deps({ headSha: null }))(job, app)) as Record<string, unknown>;
-  assertEquals(nullHead.convergeBlocked, true, "cannot verify an override against an unknown HEAD");
-  const throwHead = (await makeHandler(deps({ headThrows: true }))(job, app)) as Record<string, unknown>;
-  assertEquals(throwHead.convergeBlocked, true, "a HEAD read error keeps the block");
-});
-
-test("scope passes → not blocked, and no override lookup is needed", async () => {
-  const app = fakeApp([]);
-  const out = (await makeHandler(deps({ prBody: "Implements the whole thing.\n\nCloses #631" }))(job, app)) as Record<
-    string,
-    unknown
-  >;
-  assertEquals(out.convergeBlocked, false);
-  assertEquals(out.scopeBlocked, undefined);
-});
-
-test("newest answered scope escalation wins when a re-escalation was answered again at the same HEAD", async () => {
-  const app = fakeApp([
-    { id: 7, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "first" },
-    { id: 9, pr_key: "o/r#5", status: "answered", scope_block: 1, head_sha: "HEAD1", answer: "latest" },
-  ]);
-  const out = (await makeHandler(deps({ headSha: "HEAD1" }))(job, app)) as Record<string, unknown>;
-  assertEquals(out.convergeBlocked, false, "a re-answered override at the unchanged HEAD is honoured");
-});