@nanobpm/nano-workforce 0.91.0 → 0.93.0

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/app/service.ts

@@ -33,7 +33,7 @@ import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
-import { planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
+import { backfillPlanBuckets, planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
@@ -1773,6 +1773,11 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
  * on every poll. */
 let featureStagesBackfilled = false;
 
+/** One-shot guard so the epic-bucket backfill (`backfillPlanBuckets`, #298) runs at most once per
+ * process, on the first `pollOnce` — re-projecting pre-migration-042 `plans` rows whose
+ * `list_bucket` is still NULL. The gateway keeps every future write fresh; idempotent regardless. */
+let planBucketsBackfilled = false;
+
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -1789,6 +1794,13 @@ export async function pollOnce(
     await backfillFeatureStages(data);
     featureStagesBackfilled = true;
   }
+  // One-shot: re-project any pre-#298 `plans` rows whose `list_bucket` is still NULL, so a legacy
+  // epic buckets correctly into Active/History from the first pass. Guard armed only after success so
+  // a transient failure retries next pass (mirrors the feature-stage backfill above).
+  if (!planBucketsBackfilled) {
+    await backfillPlanBuckets(data);
+    planBucketsBackfilled = true;
+  }
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);

package/db/migrations/044_plan_list_bucket.sql

@@ -0,0 +1,32 @@
+-- 044_plan_list_bucket.sql — issue #298: bucket EPICS on the derived `delivery` rollup, not raw
+-- `plan.status`, so a `done` epic whose slice PRs are still CONVERGING — or one that has fully LANDED
+-- but still needs its integration→main promotion PR — does NOT silently vanish from the Active epic
+-- lists the instant `status = done`. Mirrors the feature-run Active/History tick-off partition
+-- (038/039 `feature_runs`): reify the partition as a derived, write-time-projected column so the
+-- declarative epic/overview page tabs can filter with only stored `{"field":…}` `in` clauses (the
+-- dataGrid page DSL has no OR / IS NULL), and give epics the same operator "Dismiss" affordance
+-- feature runs already have.
+--
+-- Columns (all maintained by the `plans` gateway — app/plan.ts — from the pure `deriveEpicBucket` /
+-- `epicIsAcknowledgeable` helpers in app/delivery.ts on every write, never hand-derived in SQL, the
+-- page, or a poller):
+--   • acknowledged_at — NULL until an operator dismisses a RESOLVED epic (acknowledge-epic) — landed
+--                       or resolved-not-landed (`delivery=null`); only still-`converging` epics are
+--                       rejected. The twin of feature_runs.acknowledged_at (039).
+--   • list_bucket     — 'active' | 'history': deriveEpicBucket(status, delivery, acknowledged_at).
+--                       Active = live epics (planning/dispatched) + `done` epics not yet acknowledged
+--                       (still converging, landed-but-unpromoted, or resolved-not-landed); History =
+--                       acknowledged `done` epics and terminal failed/abandoned epics.
+--   • ack_open        — 1 | 0: 1 iff the epic is a RESOLVED (`done`, not `converging`) but
+--                       unacknowledged epic — the Active states that carry the Dismiss affordance — so
+--                       the page's `showWhenField` gates the button precisely. Mirrors
+--                       feature_runs.escalation_open (040).
+--
+-- Forward-only, additive (expand): all nullable with no default, so pre-#298 rows grandfather in as
+-- NULL and never gate control flow. `backfillPlanBuckets` (app/plan.ts) stamps legacy rows once at
+-- boot, and the gateway keeps every future write fresh. Numbered after the current highest prefix on
+-- origin/main (041); the runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+ALTER TABLE plans ADD COLUMN acknowledged_at TEXT;
+ALTER TABLE plans ADD COLUMN list_bucket TEXT;
+ALTER TABLE plans ADD COLUMN ack_open INTEGER;

package/db/migrations/045_epic_set_admission_staging.sql

@@ -0,0 +1,56 @@
+-- 045_epic_set_admission_staging.sql — issue #292 slice S2: durable ADMISSION STAGING for the
+-- set/batch door (`startEpicSet`).
+--
+-- S2 is the admission DOOR + DAG validator only; it deliberately does NOT start any epic and does
+-- NOT materialize the durable plan graph. Slice S3 (planner lowering: schedule roots, seed the
+-- capability gate, bind the resolved version) is the slice that actually CREATES `plans` rows and
+-- their `plan_deps` edges — so S3, not S2, is the correct owner of both.
+--
+-- That split leaves S2 needing to persist WHAT it admitted so a crash between admission and lowering
+-- does not lose the set. It cannot write `plan_deps` for that: `plan_deps.plan_key REFERENCES
+-- plans(plan_key)` (041), but S2 has not created any `plans` row, so a first-time set submission
+-- would FK-fail (500). Nor should it pre-create a `plans` row — a non-terminal `plans` row reads as
+-- `alreadyRunning` to the canonical `startPlan`, which would wedge S3 from ever starting it.
+--
+-- So S2 stages into its OWN, FK-FREE structure here, and S3 reads it during lowering to materialize
+-- `plans` + `plan_deps` when it schedules roots (where the FK is satisfied by construction). Neither
+-- staging table references `plans` — that is the whole point: the staging is writable BEFORE any
+-- plan graph exists.
+--
+--   • admitted_epics — one row per admitted epic in the set (INCLUDING roots, which carry no edge).
+--     `plan_key` is the epic's canonical key; the rest is what S3 needs to materialize the `plans`
+--     row (repo, issue number/url, the normalized integration base branch). PRIMARY KEY (plan_key)
+--     makes a re-submitted set idempotent (one staged row per epic).
+--   • admitted_plan_deps — the FK-FREE staging twin of `plan_deps`: one row per validated inter-epic
+--     edge (`plan_key` waits for `depends_on_plan_key`, gated by { package, capability_ref }).
+--     Constraints MIRROR plan_deps EXCEPT the FK: PRIMARY KEY (plan_key, depends_on_plan_key) so a
+--     re-submitted set cannot duplicate an edge, CHECK (plan_key <> depends_on_plan_key) so no
+--     self-edge — but NO `REFERENCES plans(...)`, since neither endpoint's plan row exists yet. The
+--     set validator (S2) is what guarantees every endpoint names a submitted epic.
+--
+-- Numbered after the current highest prefix on origin/main (042_plan_promotion.sql) — the branch
+-- forks at 041 while main advanced to 042, so this MUST be 043 to avoid a merge-time prefix
+-- collision. The runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+
+CREATE TABLE admitted_epics (
+  plan_key     TEXT NOT NULL PRIMARY KEY,  -- the admitted epic's canonical key (owner/repo#123)
+  repo         TEXT NOT NULL,              -- owner/repo the epic issue lives in
+  issue_number INTEGER NOT NULL,           -- the epic issue number
+  issue_url    TEXT NOT NULL,              -- canonical issue URL (for S3 to materialize the plans row)
+  base_branch  TEXT NOT NULL,              -- normalized integration base branch admitPlan resolved
+  created_at   TEXT NOT NULL
+);
+
+CREATE TABLE admitted_plan_deps (
+  plan_key            TEXT NOT NULL,  -- dependent/consumer epic that waits (FK-free: plans may not exist yet)
+  depends_on_plan_key TEXT NOT NULL,  -- producer epic it waits for
+  package             TEXT NOT NULL,  -- producer's published package name
+  capability_ref      TEXT NOT NULL,  -- producer epic issue handle → pkg@version
+  created_at          TEXT NOT NULL,
+  PRIMARY KEY (plan_key, depends_on_plan_key),
+  CHECK (plan_key <> depends_on_plan_key)
+);
+
+CREATE INDEX idx_admitted_plan_deps_plan ON admitted_plan_deps(plan_key);
+CREATE INDEX idx_admitted_plan_deps_producer ON admitted_plan_deps(depends_on_plan_key);

package/e2e/support/engine-client.ts

@@ -1,17 +1,33 @@
 import type { EngineClient } from "@nanobpm/urban";
 import type { TestApp } from "@nanobpm/urban-testkit";
 
-// urban 0.49.0 (ADR 0062) added `EngineClient.getForm`, but the published
-// @nanobpm/urban-testkit (0.4.0) predates it, so its `WasmEngineClient` neither
-// declares nor implements the method. These hermetic e2e flows drive user-task
-// completion directly (`completeUserTask`) and never resolve a form schema, so we
-// complete the contract with a null-returning `getForm` — the documented "no
-// matching form" path — until a testkit release catches up with urban's engine
-// seam. Scoped to the test harness; production adapters implement `getForm` for real.
+// `@nanobpm/urban-testkit`'s `WasmEngineClient` has historically lagged urban's `EngineClient`
+// interface: a method lands on the real seam a release or two before the testkit fake grows it. Both
+// guards below defensively COMPLETE the contract for any method the *installed* testkit hasn't
+// implemented yet — each is an idempotent `if (typeof … !== "function")`, so it no-ops the moment a
+// testkit release ships the real method (no version pins to drift). Scoped to the test harness;
+// production adapters (`SdkEngineClient`) implement both for real.
+//
+//  - `getForm` (urban 0.49.0, ADR 0062): the original instance of this lag. Now implemented by the
+//    currently pinned testkit, so this guard is a no-op there; kept as defence against version skew.
+//    These hermetic flows drive completion directly and never resolve a form schema, so the fallback
+//    returns `null` — the documented "no matching form" path.
+//  - `openUserTasks` (issue #294 moved the pollers onto it): the CURRENT gap — the pinned testkit has
+//    `searchUserTasks` but not the open-task-scoped `openUserTasks`, so a poller call throws
+//    `not a function` (swallowed by the poller's try/catch) and the read-model denormalisation
+//    silently no-ops. Polyfill it as `searchUserTasks({ state: "CREATED" })` — byte-for-byte what
+//    urban's real `SdkEngineClient.openUserTasks` does, so the two cannot drift. Fix: nano-workforce
+//    #309; categorical (testkit) fix upstream in nanobpm/nano-ide#341.
 export function asEngineClient(engine: TestApp["engine"]): EngineClient {
-  const e = engine as unknown as EngineClient & { getForm?: EngineClient["getForm"] };
+  const e = engine as unknown as EngineClient & {
+    getForm?: EngineClient["getForm"];
+    openUserTasks?: EngineClient["openUserTasks"];
+  };
   if (typeof e.getForm !== "function") {
     e.getForm = async () => null;
   }
+  if (typeof e.openUserTasks !== "function") {
+    e.openUserTasks = (filter) => e.searchUserTasks({ ...filter, state: "CREATED" });
+  }
   return e;
 }