@nanobpm/nano-workforce 0.91.0 → 0.93.0

package/operations/startEpicSet.ts

@@ -0,0 +1,217 @@
+// POST /app/api/actions/start/epic-set → operationId `startEpicSet` (issue #292, slice S2). The
+// set/batch admission door: it admits a WHOLE set of epics plus the inter-epic dependency edges
+// between them in ONE all-or-nothing call, whereas `startPlanFanout` admits exactly one issue.
+//
+// The door is transactional at the durable layer: it VALIDATES the entire submission before it
+// persists anything. The order is load-bearing so a bad set fails "at the offending edge with nothing
+// half-started":
+//   1. Parse every epic reference and collect the submitted set's plan keys (400 on an unparseable
+//      reference, or on EXACTLY-ONE-of issue|url being violated).
+//   2. Pure, side-effect-free set validation (`validateEpicSet`): reference integrity (every edge
+//      connects two epics IN the set), no self-edge, non-blank capability descriptor, and an acyclic
+//      DAG. This runs BEFORE any `admitPlan` call, so a cycle / dangling edge is a clean 400 with no
+//      base branch created and no edge written.
+//   3. Run the existing `admitPlan` gate PER epic (base-branch rules + shared-base guard), PLUS an
+//      in-request intra-set shared-base guard (two members of the same set cannot silently grab the
+//      same custom base, which admitPlan's durable-only rule 4 would miss). The first failure maps to
+//      its 4xx (400/409) via the shared `admitPlanErrorResponse`, before anything is persisted.
+//   4. Only once every epic admits: STAGE the admitted set — each epic into `admitted_epics` and each
+//      validated edge into `admitted_plan_deps` — then return the admitted epics, the roots, and the
+//      staged edges.
+//
+// This slice deliberately does NOT start any epic or seed any readiness gate, and — per the #292
+// design decision — it MATERIALIZES neither a `plans` row nor a `plan_deps` edge. Both are owned by
+// slice S3 (planner lowering: schedule roots, seed the capability gate, bind the resolved version),
+// which reads this staging and creates `plans` + `plan_deps` when it schedules roots — where the
+// `plan_deps.plan_key REFERENCES plans(plan_key)` FK is satisfied by construction. S2 persists into
+// its OWN FK-FREE staging tables instead, so a first-time set submission can never FK-fail here.
+// Re-submitting the identical set is a no-op (admitPlan is idempotent on an already-created base + an
+// inactive plan; the staging records collapse a duplicate epic/edge).
+
+import { fetchDefaultBranch } from "../app/github.ts";
+import {
+  admitPlan,
+  admitPlanErrorResponse,
+  EpicSetValidationError,
+  type ParsedIssue,
+  parseIssue,
+  recordAdmittedEpic,
+  recordAdmittedPlanDep,
+  SharedBaseError,
+  validateEpicSet,
+} from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+/** One parsed, admission-ready epic member: its parsed issue reference plus the per-epic admission
+ * inputs (`baseBranch` and the two opt-in acknowledgements) `admitPlan` consumes. */
+interface EpicMember {
+  parsed: ParsedIssue;
+  baseBranch: string;
+  allowSharedBase: boolean;
+  confirmDefaultBase: boolean;
+}
+
+export default defineOperation("startEpicSet", async ({ body }, app) => {
+  // A directly-invoked delegate (or a missing body) leaves `body` undefined — guard so that is a 400,
+  // not a 500 from destructuring. The runtime validates a well-formed body against openapi.yaml.
+  if (!body || typeof body !== "object" || !Array.isArray(body.epics)) {
+    app.log.warn("start-epic-set rejected: missing or malformed request body");
+    return { status: 400, body: { error: "request body is required: { epics: [...], deps?: [...] }" } };
+  }
+  // `deps` is optional, but when provided it MUST be an array. A non-array `deps` (e.g. `deps: {…}`)
+  // would otherwise be silently coerced to `[]` — admitting the set while dropping every declared
+  // edge — so reject it with a clean 400 rather than losing the caller's intent.
+  if (body.deps != null && !Array.isArray(body.deps)) {
+    app.log.warn("start-epic-set rejected: deps is not an array");
+    return { status: 400, body: { error: "deps must be an array of dependency edges when provided" } };
+  }
+  const depsRaw = Array.isArray(body.deps) ? body.deps : [];
+
+  // ── Step 1: parse every epic reference into an admission-ready member ───────────────────────────
+  const members: EpicMember[] = [];
+  const planKeys: string[] = [];
+  for (const m of body.epics) {
+    if (!m || typeof m !== "object") {
+      app.log.warn("start-epic-set rejected: malformed epic entry");
+      return { status: 400, body: { error: "each epic must be an object with issue|url and baseBranch" } };
+    }
+    // Enforce EXACTLY-ONE-of issue|url (the operation contract + the error message below). Read each
+    // field through `in`-narrowing and validate it is a NON-BLANK STRING, so a key that is present
+    // but null/blank (e.g. `{ issue: null, url: "…" }`) does NOT count as provided — it falls through
+    // to the other field instead of bare key-presence silently winning.
+    const issueVal = "issue" in m ? m.issue : undefined;
+    const urlVal = "url" in m ? m.url : undefined;
+    const hasIssue = typeof issueVal === "string" && issueVal.trim().length > 0;
+    const hasUrl = typeof urlVal === "string" && urlVal.trim().length > 0;
+    if (hasIssue && hasUrl) {
+      app.log.warn("start-epic-set rejected: epic names both issue and url");
+      return { status: 400, body: { error: "each epic needs exactly one of issue or url, not both" } };
+    }
+    const ref = hasIssue ? issueVal : hasUrl ? urlVal : undefined;
+    if (typeof ref !== "string" || ref.trim().length === 0) {
+      app.log.warn("start-epic-set rejected: epic missing issue/url");
+      return { status: 400, body: { error: "each epic needs exactly one of issue or url (owner/repo#123 or an issue URL)" } };
+    }
+    const parsed = parseIssue(ref.trim());
+    if (!parsed) {
+      app.log.warn("start-epic-set rejected: unparseable epic reference", { ref });
+      return { status: 400, body: { error: `could not parse epic "${ref}" (use owner/repo#123 or an issue URL)` } };
+    }
+    members.push({
+      parsed,
+      baseBranch: typeof m.baseBranch === "string" ? m.baseBranch : "",
+      allowSharedBase: m.allowSharedBase === true,
+      confirmDefaultBase: m.confirmDefaultBase === true,
+    });
+    planKeys.push(parsed.planKey);
+  }
+
+  // ── Step 2: pure set validation (reference integrity + DAG) — BEFORE any admitPlan side effect ──
+  let edges: ReturnType<typeof validateEpicSet>;
+  try {
+    edges = validateEpicSet(planKeys, depsRaw);
+  } catch (err) {
+    if (err instanceof EpicSetValidationError) {
+      app.log.warn("start-epic-set rejected: invalid set", { status: err.status, error: err.message });
+      return { status: err.status, body: { error: err.message } };
+    }
+    throw err;
+  }
+
+  // ── Step 3: admit every epic through the existing gate (base rules + shared-base) ───────────────
+  // Nothing durable is written yet, so the first admission failure is a clean 4xx with no edge
+  // persisted. `selfPlanKey` excludes the epic's own active row so an idempotent re-submit does not
+  // 409 against itself.
+  const token = process.env.GITHUB_TOKEN ?? "";
+  const admitted: { parsed: ParsedIssue; baseBranch: string }[] = [];
+  // Intra-set shared-base guard: admitPlan's rule 4 only inspects DURABLE `plans` rows, and S2
+  // materializes none, so two members of THIS set reaching for the same custom integration branch
+  // would both slip past it and silently defeat ADR 0003 rule 4. Track each admitted member's
+  // custom (non-default) base per repo and reject a second, non-opted-in claim on it — mirroring the
+  // durable guard (the already-admitted member occupies the base regardless of its own flag; only a
+  // newcomer that sets `allowSharedBase: true` may stack on it). The default branch is exempt, just
+  // as it is in rule 4.
+  const claimedBases = new Map<string, Set<string>>();
+  for (const member of members) {
+    try {
+      const normalizedBase = await admitPlan(app.data, member.parsed.repo, member.baseBranch, token, {
+        allowSharedBase: member.allowSharedBase,
+        confirmDefaultBase: member.confirmDefaultBase,
+        selfPlanKey: member.parsed.planKey,
+      });
+      const defaultBranch = await fetchDefaultBranch(member.parsed.repo, token);
+      const isDefaultBase = defaultBranch !== null && normalizedBase === defaultBranch;
+      if (!isDefaultBase) {
+        const claimed = claimedBases.get(member.parsed.repo);
+        if (member.allowSharedBase !== true && claimed?.has(normalizedBase)) {
+          throw new SharedBaseError(member.parsed.repo, normalizedBase);
+        }
+        if (claimed) claimed.add(normalizedBase);
+        else claimedBases.set(member.parsed.repo, new Set([normalizedBase]));
+      }
+      admitted.push({ parsed: member.parsed, baseBranch: normalizedBase });
+    } catch (err) {
+      const mapped = admitPlanErrorResponse(err);
+      if (mapped) {
+        app.log.warn("start-epic-set rejected: epic admission gate", {
+          planKey: member.parsed.planKey,
+          status: mapped.status,
+          error: mapped.error,
+        });
+        return {
+          status: mapped.status,
+          body: { error: `epic ${member.parsed.planKey}: ${mapped.error}` },
+        };
+      }
+      throw err;
+    }
+  }
+
+  // ── Step 4: STAGE the admitted set + validated edges (idempotent). S2 is the admission DOOR only:
+  // per the #292 design decision it persists into ITS OWN FK-FREE staging tables and MATERIALIZES
+  // neither a `plans` row nor a `plan_deps` edge. Slice S3 (planner lowering) reads this staging and
+  // creates `plans` + `plan_deps` when it schedules roots — where the `plan_deps.plan_key REFERENCES
+  // plans(plan_key)` FK is satisfied by construction. Each admitted epic (INCLUDING roots) is staged
+  // so S3 can materialize its `plans` row; each validated edge is staged FK-free. Only reached once
+  // the WHOLE set admitted.
+  for (const a of admitted) {
+    await recordAdmittedEpic(app.data, {
+      plan_key: a.parsed.planKey,
+      repo: a.parsed.repo,
+      issue_number: a.parsed.number,
+      issue_url: a.parsed.url,
+      base_branch: a.baseBranch,
+    });
+  }
+  for (const edge of edges) {
+    await recordAdmittedPlanDep(app.data, {
+      plan_key: edge.consumer,
+      depends_on_plan_key: edge.producer,
+      package: edge.package,
+      capability_ref: edge.capabilityRef,
+    });
+  }
+
+  // Roots = admitted epics with no inbound edge — the ones S3 will start immediately.
+  const dependents = new Set(edges.map((e) => e.consumer));
+  const roots = admitted.map((a) => a.parsed.planKey).filter((k) => !dependents.has(k));
+
+  app.log.info("epic set admitted", {
+    epics: admitted.length,
+    edges: edges.length,
+    roots: roots.length,
+  });
+  return {
+    status: 202,
+    body: {
+      epics: admitted.map((a) => ({ planKey: a.parsed.planKey, baseBranch: a.baseBranch })),
+      roots,
+      edges: edges.map((e) => ({
+        consumer: e.consumer,
+        producer: e.producer,
+        package: e.package,
+        capabilityRef: e.capabilityRef,
+      })),
+    },
+  };
+});

package/operations/startPlanFanout.ts

@@ -10,16 +10,7 @@
 // ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
 // narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
-import { BaseBranchMustExistError } from "../app/github.ts";
-import {
-  admitPlan,
-  DefaultBaseNotConfirmedError,
-  InvalidBaseBranchError,
-  MissingBaseBranchError,
-  parseIssue,
-  SharedBaseError,
-  startPlan,
-} from "../app/plan.ts";
+import { admitPlan, admitPlanErrorResponse, parseIssue, startPlan } from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
@@ -51,52 +42,10 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
       selfPlanKey: parsed.planKey,
     });
   } catch (err) {
-    if (err instanceof MissingBaseBranchError) {
-      app.log.warn("start-plan rejected: missing base branch");
-      return {
-        status: 400,
-        body: { error: "baseBranch is required (name the integration branch, e.g. epic/agent-protocol)" },
-      };
-    }
-    if (err instanceof InvalidBaseBranchError) {
-      app.log.warn("start-plan rejected: invalid base branch", { baseBranch: err.value });
-      return {
-        status: 400,
-        body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)" },
-      };
-    }
-    if (err instanceof BaseBranchMustExistError) {
-      app.log.warn("start-plan rejected: base branch does not exist", { baseBranch: err.branch });
-      return {
-        status: 400,
-        body: {
-          error:
-            `baseBranch "${err.branch}" does not exist and is not an epic/* branch, so it is not ` +
-            `auto-created — create it first, or use the epic/* convention`,
-        },
-      };
-    }
-    if (err instanceof DefaultBaseNotConfirmedError) {
-      app.log.warn("start-plan rejected: default base not confirmed", { baseBranch: err.branch });
-      return {
-        status: 400,
-        body: {
-          error:
-            `baseBranch "${err.branch}" is the repository default branch — every task would land ` +
-            `directly on it with no integration branch. Re-submit with confirmDefaultBase: true to proceed`,
-        },
-      };
-    }
-    if (err instanceof SharedBaseError) {
-      app.log.warn("start-plan rejected: shared base branch", { baseBranch: err.branch });
-      return {
-        status: 409,
-        body: {
-          error:
-            `baseBranch "${err.branch}" is already in use by another active epic. Re-submit with ` +
-            `allowSharedBase: true to stack on it, or name a distinct epic/* branch`,
-        },
-      };
+    const mapped = admitPlanErrorResponse(err);
+    if (mapped) {
+      app.log.warn("start-plan rejected: admission gate", { status: mapped.status, error: mapped.error });
+      return { status: mapped.status, body: { error: mapped.error } };
     }
     throw err;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.91.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/pages/epic.page.json

@@ -61,16 +61,16 @@
           "source": "app",
           "table": "plans",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
+          "filter": [{ "field": "list_bucket", "in": ["active"] }]
         },
         "tabs": [
           {
             "label": "Active",
-            "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
+            "filter": [{ "field": "list_bucket", "in": ["active"] }]
           },
           {
             "label": "History",
-            "filter": [{ "field": "status", "in": ["done", "failed", "abandoned"] }]
+            "filter": [{ "field": "list_bucket", "in": ["history"] }]
           },
           { "label": "All", "filter": [] }
         ],
@@ -80,11 +80,23 @@
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "promotion_state", "header": "Promotion" },
+          { "field": "delivery_label", "header": "Landing" },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
           { "field": "issue_number", "header": "Issue", "linkField": "issue_url" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
+        ],
+        "rowActions": [
+          {
+            "label": "Dismiss",
+            "confirm": "Dismiss this resolved epic? Its slices have all reached a terminal state \u2014 it acknowledges the epic and files it under History (if all slices landed, raise the integration\u2192main promotion PR first).",
+            "showWhenField": "ack_open",
+            "action": {
+              "path": "/app/api/actions/acknowledge-epic",
+              "body": { "plan_key": "{{row.plan_key}}" }
+            }
+          }
         ]
       }
     }

package/pages/overview.page.json

@@ -88,13 +88,25 @@
           "source": "app",
           "table": "plans",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
+          "filter": [{ "field": "list_bucket", "in": ["active"] }]
         },
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "delivery_label", "header": "Landing" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
+        ],
+        "rowActions": [
+          {
+            "label": "Dismiss",
+            "confirm": "Dismiss this resolved epic? Its slices have all reached a terminal state \u2014 it acknowledges the epic and files it under History.",
+            "showWhenField": "ack_open",
+            "action": {
+              "path": "/app/api/actions/acknowledge-epic",
+              "body": { "plan_key": "{{row.plan_key}}" }
+            }
+          }
         ]
       }
     },

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/scripts/pages-contract.test.ts

@@ -270,31 +270,30 @@ test("issue #205: overview is the landing page and first nav item", async () =>
   }
 
   // Three collapsible active-work sections, one per dispatch surface, each with a
-  // live count in its header (showCount) and a persisted collapse toggle (collapsible).
-  const expected: Record<string, string[]> = {
-    pull_requests: [
-      "converging",
-      "waiting_review",
-      "escalated",
-      "waiting_deps",
-      "waiting_merge",
-      "queued",
-      "merging",
-    ],
-    plans: ["planning", "dispatched"],
-    feature_runs: ["running", "escalated", "awaiting_operator"],
+  // live count in its header (showCount) and a persisted collapse toggle (collapsible). Each filters
+  // its Active list on a `{field, in:[...]}` predicate: the PR / feature surfaces on `status`, but the
+  // EPIC surface buckets on the DERIVED `list_bucket` (issue #298) — NOT raw `status` — so a `done`
+  // epic still converging, or landed-but-unpromoted, does not vanish from the in-flight Epics section
+  // the instant `status=done`. Guarding the field here is the regression guard for that defect class.
+  const expected: Record<string, { field: string; in: string[] }> = {
+    pull_requests: {
+      field: "status",
+      in: ["converging", "waiting_review", "escalated", "waiting_deps", "waiting_merge", "queued", "merging"],
+    },
+    plans: { field: "list_bucket", in: ["active"] },
+    feature_runs: { field: "status", in: ["running", "escalated", "awaiting_operator"] },
   };
   const grids = (overview.nodes ?? []).filter((n: Json) => n.type === "dataGrid");
-  for (const [table, statuses] of Object.entries(expected)) {
+  for (const [table, { field, in: values }] of Object.entries(expected)) {
     const grid = grids.find((g: Json) => g.props?.data?.table === table);
     assert(grid, `overview.page.json must have a section bound to "${table}"`);
     assert(grid.props.collapsible === true, `overview "${table}" section must be collapsible`);
     assert(grid.props.showCount === true, `overview "${table}" section must show a live count`);
-    const filter = grid.props?.data?.filter?.find((f: Json) => f.field === "status");
-    assert(filter, `overview "${table}" section must filter on status`);
+    const filter = grid.props?.data?.filter?.find((f: Json) => f.field === field);
+    assert(filter, `overview "${table}" section must filter on ${field}`);
     assert(
-      JSON.stringify([...filter.in].sort()) === JSON.stringify([...statuses].sort()),
-      `overview "${table}" section must filter to the active statuses ${JSON.stringify(statuses)}`,
+      JSON.stringify([...filter.in].sort()) === JSON.stringify([...values].sort()),
+      `overview "${table}" section must filter ${field} to ${JSON.stringify(values)}`,
     );
   }
 });

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;

package/workers/record-plan/worker.test.ts

@@ -29,6 +29,7 @@ function fakeApp() {
           ? planTaskDeps
           : plans;
         return {
+          get: (k: unknown) => Promise.resolve(store.find((r) => r[key] === k)),
           find: (q: Record<string, unknown>) =>
             Promise.resolve(
               store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)),

package/workers/record-plan/worker.ts

@@ -17,7 +17,7 @@
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
 import { deriveEpicPhase } from "../../app/epicPhase.ts";
-import { planTaskDeps, planTasks } from "../../app/plan.ts";
+import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -134,7 +134,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const epicPhase = deriveEpicPhase(job.elementId);
   if (epicPhase) patch.epic_phase = epicPhase;
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
-  await app.data.table("plans", "plan_key").update(planKey, patch);
+  await plans(app.data).update(planKey, patch);
 
   // Kick off the wave loop at wave 0.
   return { currentWave: 0, waveCount };

package/workers/record-results/worker.test.ts

@@ -26,9 +26,23 @@ function fakeApp(rows: Row[]) {
     data: {
       table(name: string, key: string) {
         if (name === "plans") {
+          // A full in-memory table double so the real `plans` gateway proxy (which reads back the row
+          // to reproject `list_bucket`/`ack_open`) works: get/all/insert/update, update upserting so a
+          // worker that updates an as-yet-unseeded plan still lands a row (mirrors production, where
+          // startPlan inserted it first).
           return {
+            all: () => Promise.resolve(plans.slice()),
+            get: (k: any) => Promise.resolve(plans.find((p) => p[key] === k)),
+            find: (q: any) =>
+              Promise.resolve(plans.filter((p) => Object.entries(q).every(([f, v]) => p[f] === v))),
+            insert: (row: any) => {
+              plans.push({ ...row });
+              return Promise.resolve(row[key]);
+            },
             update: (k: any, patch: any) => {
-              plans.push({ [key]: k, ...patch });
+              const existing = plans.find((p) => p[key] === k);
+              if (existing) Object.assign(existing, patch);
+              else plans.push({ [key]: k, ...patch });
               return Promise.resolve(patch);
             },
           };
@@ -63,6 +77,8 @@ test("no opened PRs (empty plan) hard-fails with NO_WORK_DISPATCHED", async () =
   const plan = app._plans.at(-1) as Record<string, unknown>;
   assertEquals(plan.status, "failed");
   assertEquals(plan.outcome, "no work dispatched — the planner produced no tasks");
+  // The gateway projects the bucket: a failed epic settles to History (no tick-off needed).
+  assertEquals(plan.list_bucket, "history");
 });
 
 test("tasks present but none opened (all skipped/blocked) hard-fails", async () => {
@@ -86,4 +102,6 @@ test("at least one opened PR finalizes cleanly (no throw)", async () => {
   const plan = app._plans.at(-1) as Record<string, unknown>;
   assertEquals(plan.status, "done");
   assertEquals(plan.outcome, "1 PR(s) dispatched to convergence");
+  // A just-`done` epic (delivery not yet projected) stays in Active — it must not vanish (#298).
+  assertEquals(plan.list_bucket, "active");
 });