@nanobpm/nano-workforce 0.70.2 → 0.72.0

package/operations/completeUserTask.test.ts

@@ -0,0 +1,146 @@
+// Tests for the POST /app/api/actions/complete-user-task operation `completeUserTask` (issue #236).
+// The nwf Tasks page's decision affordance for the plan-review / trial-merge / PR `wait-answer`
+// escalations: it routes the typed form variables through the canonical human completer
+// (completeEscalationAsHuman → completeUserTaskAttributed), resuming the process exactly as the task
+// inbox would, and drops the answered task's read-model row so the grid stops offering a decision.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./completeUserTask.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: in-memory doubles, mirrors acknowledgeBlocked.test.ts
+function memApp(openTasks: { userTaskKey: string; elementId?: string }[]): {
+  app: AppApi;
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  stores: Record<string, any[]>;
+  completed: { userTaskKey: string; variables: Record<string, unknown> }[];
+} {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = {};
+  const completed: { userTaskKey: string; variables: Record<string, unknown> }[] = [];
+  function tbl(name: string, pk: string) {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(row: any) {
+        rows.push({ ...row });
+        return rows.length;
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async find(where: any = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const engine = {
+    searchUserTasks: async () => openTasks,
+    completeUserTask: async (userTaskKey: string, variables: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+    },
+  };
+  const app = {
+    data: { table: (n: string, pk: string) => tbl(n, pk) },
+    engine,
+    log: noopLog(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return { app, stores, completed };
+}
+
+async function call(app: AppApi, body: unknown) {
+  // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("complete-user-task: completes a plan-review escalation and drops its read-model row", async () => {
+  const { app, stores, completed } = memApp([{ userTaskKey: "ut-1", elementId: "plan-review-decision" }]);
+  stores.user_tasks = [{ user_task_key: "ut-1", element_id: "plan-review-decision" }];
+
+  const res = await call(app, { userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.elementId, "plan-review-decision");
+  assertEquals(completed, [{ userTaskKey: "ut-1", variables: { directive: "revise", notes: "narrow scope" } }]);
+  assertEquals(stores.user_tasks, []);
+  // Attribution recorded as a human completion.
+  assertEquals(stores.task_completions.length, 1);
+  assertEquals(stores.task_completions[0].actor_kind, "human");
+});
+
+test("complete-user-task: completes a trial-merge escalation with the typed action variable", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-2", elementId: "trial-merge-decision" }]);
+
+  const res = await call(app, { userTaskKey: "ut-2", variables: { action: "rebase" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(completed, [{ userTaskKey: "ut-2", variables: { action: "rebase" } }]);
+});
+
+test("complete-user-task: a missing userTaskKey is a 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { variables: { answer: "x" } });
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});
+
+test("complete-user-task: non-object variables are rejected 400", async () => {
+  const { app } = memApp([{ userTaskKey: "ut-3", elementId: "wait-answer" }]);
+  const res = await call(app, { userTaskKey: "ut-3", variables: "nope" });
+  assertEquals(res.status, 400);
+});
+
+test("complete-user-task: an unknown key is a 404 (no open escalation task)", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { userTaskKey: "ghost", variables: { answer: "x" } });
+  assertEquals(res.status, 404);
+});
+
+test("complete-user-task: refuses a non-escalation user task (400)", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-4", elementId: "feature-blocked" }]);
+  const res = await call(app, { userTaskKey: "ut-4", variables: { note: "x" } });
+  assertEquals(res.status, 400);
+  assertEquals(completed, []);
+});
+
+test("complete-user-task: a read-model cleanup failure does not mask a resumed completion (200)", async () => {
+  const { app, completed } = memApp([{ userTaskKey: "ut-5", elementId: "plan-review-decision" }]);
+  // The engine has already resumed the process; a transient delete failure on the latency-optimising
+  // read-model cleanup must not surface as a 5xx for a task that IS completed (poller reconciles).
+  const realTable = app.data.table.bind(app.data);
+  // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  (app.data as any).table = (name: string, pk: string) => {
+    const t = realTable(name, pk);
+    if (name === "user_tasks") {
+      return {
+        ...t,
+        delete: async () => {
+          throw new Error("transient DB error");
+        },
+      };
+    }
+    return t;
+  };
+
+  const res = await call(app, { userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope" } });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(completed, [{ userTaskKey: "ut-5", variables: { directive: "revise", notes: "narrow scope" } }]);
+});

package/operations/completeUserTask.ts

@@ -0,0 +1,72 @@
+// POST /app/api/actions/complete-user-task → operationId `completeUserTask` (issue #236).
+//
+// The nwf **Tasks** page's decision affordance for the epic/PR native escalations that had no
+// app-side completion path — `plan-review-decision`, `trial-merge-decision`, and the PR review-loop
+// `wait-answer`. An operator submits the parked task's typed `.form` variables (e.g. a plan-review
+// `{ directive, notes }`, a trial-merge `{ action, notes }`, or a PR `{ answer }`) directly from the
+// Tasks inbox instead of only from Urban's read-only task-inbox stub.
+//
+// It routes through the ONE canonical human completer (`completeEscalationAsHuman` →
+// `completeUserTaskAttributed`), so the completion uses the exact same typed variables and engine
+// resume path a human drives from the task inbox — no parallel completion — while recording WHO
+// answered in the `task_completions` ledger. That completer refuses any user task that is not one of
+// the migrated escalation elements (`ESCALATION_TASK_ELEMENTS`), so this generic door can never
+// complete an arbitrary internal user task. The feature-run kinds keep their own reconcile-bearing
+// operations (`answer-escalation` / `acknowledge-blocked`); this door is for the escalation kinds
+// whose completion is a straight typed pass-through.
+//
+// On success it removes the answered task's `user_tasks` read-model row so the Tasks grid stops
+// offering a decision for a task that is now completed, without waiting a poll cycle; the poller
+// (`pollUserTasks`) is the durable source of truth and will re-derive the exact same empty state.
+// That read-model cleanup is best-effort — a transient delete failure is logged and swallowed rather
+// than masking a completion the engine has already resumed with a spurious 5xx.
+//
+// The runtime validates the body against openapi.yaml (`userTaskKey` + `variables` required); this
+// delegate narrows the validated shape and applies the shared human-completion contract.
+
+import { completeEscalationAsHuman } from "../app/agentCompletion.ts";
+import { userTasks } from "../app/userTasks.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("completeUserTask", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("complete-user-task rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "userTaskKey and variables are required" } };
+  }
+
+  const userTaskKey = str(body.userTaskKey);
+  if (!userTaskKey) return { status: 400, body: { ok: false, error: "userTaskKey is required" } };
+
+  const variables = body.variables;
+  if (!variables || typeof variables !== "object" || Array.isArray(variables)) {
+    return { status: 400, body: { ok: false, error: "variables must be an object" } };
+  }
+
+  // The completing operator, for the attribution ledger. Optional — the UI has no per-operator auth,
+  // so default to a generic handle rather than blocking the completion.
+  const operatorId = str(body.operator) || "operator";
+
+  const r = await completeEscalationAsHuman(app.data, app.engine, { userTaskKey, operatorId, variables });
+  if (r.ok) {
+    // Reconcile this operation's OWN action immediately: drop the read-model row so the Tasks page
+    // stops offering a decision for a task that is now completed. The poller re-derives the same
+    // state, so this is a latency optimisation, not the source of truth — make it best-effort so a
+    // transient cleanup failure never masks a completion the engine has already resumed (which would
+    // return a spurious 5xx to the UI for a task that IS done). The poller re-derives the empty state.
+    try {
+      await userTasks(app.data).delete(userTaskKey);
+    } catch (err) {
+      app.log.warn("complete-user-task: read-model cleanup failed (poller will reconcile)", {
+        userTaskKey,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    app.log.info("operator completed user task", { userTaskKey, elementId: r.elementId });
+    return { status: 200, body: { ok: true, completionId: r.completionId, elementId: r.elementId } };
+  }
+  const status = r.reason === "no open escalation task" ? 404 : 400;
+  app.log.warn("complete-user-task: not completed", { userTaskKey, reason: r.reason });
+  return { status, body: { ok: false, error: r.reason } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.70.2",
+  "version": "0.72.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",
@@ -37,6 +37,8 @@
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
     "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
+    "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
+    "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",

package/pages/cockpit.page.json

@@ -13,6 +13,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ],
         "sticky": true

package/pages/epic-detail.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/epic.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/feature.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/home.page.json

@@ -25,6 +25,10 @@
             "label": "Feature",
             "page": "feature"
           },
+          {
+            "label": "Tasks",
+            "page": "tasks"
+          },
           {
             "label": "Cockpit",
             "page": "cockpit"

package/pages/overview.page.json

@@ -14,6 +14,7 @@
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }

package/pages/tasks.page.json

@@ -0,0 +1,297 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Tasks",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "sticky": true,
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Overview", "page": "overview" },
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
+          { "label": "Cockpit", "page": "cockpit" }
+        ]
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Tasks", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "Open native user-task escalations awaiting a human decision \u2014 across feature runs, epics, and PR review loops. Each row parks a process on your decision; submit one and the process resumes on the same canonical path Urban's task inbox uses. Rows disappear once completed (here, via the inbox, or out-of-band).",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "feature-escalations",
+      "props": {
+        "title": "Feature escalations",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "user_task_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "element_id", "in": ["feature-escalation"] }]
+        },
+        "columns": [
+          { "field": "subject_key", "header": "Feature", "link": { "kind": "page", "page": "feature", "keyField": "subject_key" } },
+          { "field": "question", "header": "Question" },
+          { "field": "subject_url", "header": "Issue", "linkField": "subject_url" },
+          { "field": "process_key", "header": "Process", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "rowActions": [
+          {
+            "label": "Abandon",
+            "confirm": "Abandon this escalated task? The run gives up on it (no PR).",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "body": { "userTaskKey": "{{row.user_task_key}}", "resolution": "abandon" }
+            }
+          }
+        ],
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [{ "field": "question", "label": "Escalation question" }],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Answer escalation",
+            "promptField": "question",
+            "inputKey": "answer",
+            "inputLabel": "Guidance for the implementation agent",
+            "submitLabel": "Answer & re-dispatch",
+            "action": {
+              "path": "/app/api/actions/answer-escalation",
+              "successLabel": "Answered \u2014 the agent will resume",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "resolution": "answer",
+                "answer": "{{form.answer}}"
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "plan-reviews",
+      "props": {
+        "title": "Plan-review decisions",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "user_task_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "element_id", "in": ["plan-review-decision"] }]
+        },
+        "columns": [
+          { "field": "subject_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "subject_key" } },
+          { "field": "question", "header": "Findings" },
+          { "field": "subject_url", "header": "Issue", "linkField": "subject_url" },
+          { "field": "process_key", "header": "Process", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "rowActions": [
+          {
+            "label": "Proceed",
+            "confirm": "Proceed \u2014 dispatch the current plan as-is?",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "body": { "userTaskKey": "{{row.user_task_key}}", "variables": { "directive": "proceed" } }
+            }
+          }
+        ],
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [{ "field": "question", "label": "Review findings" }],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Send the plan back for revision",
+            "promptField": "question",
+            "inputKey": "notes",
+            "inputLabel": "Revision guidance for the planner",
+            "submitLabel": "Revise \u2014 re-plan",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "successLabel": "Sent back \u2014 the planner will revise",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "variables": { "directive": "revise", "notes": "{{form.notes}}" }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "trial-merges",
+      "props": {
+        "title": "Trial-merge decisions",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "user_task_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "element_id", "in": ["trial-merge-decision"] }]
+        },
+        "columns": [
+          { "field": "subject_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "subject_key" } },
+          { "field": "question", "header": "Trial merge" },
+          { "field": "subject_url", "header": "Issue", "linkField": "subject_url" },
+          { "field": "process_key", "header": "Process", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "rowActions": [
+          {
+            "label": "Proceed",
+            "confirm": "Proceed \u2014 accept the red trial merge and continue?",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "body": { "userTaskKey": "{{row.user_task_key}}", "variables": { "action": "proceed" } }
+            }
+          },
+          {
+            "label": "Rebase",
+            "confirm": "Rebase \u2014 re-run the trial merge?",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "body": { "userTaskKey": "{{row.user_task_key}}", "variables": { "action": "rebase" } }
+            }
+          },
+          {
+            "label": "Abandon",
+            "confirm": "Abandon \u2014 stop and finalize the plan?",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "body": { "userTaskKey": "{{row.user_task_key}}", "variables": { "action": "abandon" } }
+            }
+          }
+        ],
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [{ "field": "question", "label": "Trial merge" }]
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "pr-reviews",
+      "props": {
+        "title": "PR review escalations",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "user_task_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "element_id", "in": ["wait-answer"] }]
+        },
+        "columns": [
+          { "field": "subject_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "subject_key" } },
+          { "field": "question", "header": "Question" },
+          { "field": "subject_url", "header": "PR link", "linkField": "subject_url" },
+          { "field": "process_key", "header": "Process", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [{ "field": "question", "label": "Escalation question" }],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Answer the review escalation",
+            "promptField": "question",
+            "inputKey": "answer",
+            "inputLabel": "Your answer (resumes the review loop, handed to the next round)",
+            "submitLabel": "Answer \u2014 resume review",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "successLabel": "Answered \u2014 the review loop will resume",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "variables": { "answer": "{{form.answer}}" }
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "blocked-runs",
+      "props": {
+        "title": "Blocked feature runs",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "user_task_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "element_id", "in": ["feature-blocked"] }]
+        },
+        "columns": [
+          { "field": "subject_key", "header": "Feature", "link": { "kind": "page", "page": "feature", "keyField": "subject_key" } },
+          { "field": "question", "header": "Disposition" },
+          { "field": "subject_url", "header": "Issue", "linkField": "subject_url" },
+          { "field": "process_key", "header": "Process", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "rowActions": [
+          {
+            "label": "Acknowledge blocked",
+            "confirm": "Acknowledge this blocked run? It settles to terminal blocked (the agent could not open a PR).",
+            "showWhenField": "user_task_key",
+            "action": {
+              "path": "/app/api/actions/acknowledge-blocked",
+              "body": { "userTaskKey": "{{row.user_task_key}}" }
+            }
+          }
+        ],
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [{ "field": "question", "label": "Disposition" }]
+        }
+      }
+    }
+  ]
+}

package/scripts/check-contracts.test.ts

@@ -0,0 +1,58 @@
+// Coverage for the config-key SCAN in the contract gate (scripts/check-contracts.ts, PR #229).
+//
+// The gate is only as strong as the read patterns it recognises. Before this fix it matched only
+// dot-access (`process.env.KEY`), so a config-family key smuggled in through the `envVar("KEY")`
+// helper or string-literal bracket-access silently bypassed the "must be declared" invariant — which
+// is how NANO_PR_WEBHOOK_SECRET / NANO_AGENTIC* stayed undeclared while `check:contracts` passed
+// green. These assert `envKeyReads` sees all three patterns so the gate can hold them to the registry.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { envKeyReads, EXPLICIT_CONFIG_KEYS, toPosixRel } from "./check-contracts.ts";
+import { ENV_CONTRACTS } from "../app/contracts.ts";
+
+test("envKeyReads: dot-access is recognised", () => {
+  assertEquals(envKeyReads("const x = process.env.NANO_PR_POLL_MS;"), ["NANO_PR_POLL_MS"]);
+});
+
+test("envKeyReads: string-literal bracket-access is recognised (double and single quote)", () => {
+  assert(envKeyReads('process.env["NANO_PR_WEBHOOK_SECRET"]').includes("NANO_PR_WEBHOOK_SECRET"));
+  assert(envKeyReads("process.env['NANO_AGENTIC']").includes("NANO_AGENTIC"));
+});
+
+test("envKeyReads: the envVar(\"KEY\") helper is recognised", () => {
+  assert(envKeyReads('const s = envVar("NANO_AGENTIC_SECRET") ?? "";').includes("NANO_AGENTIC_SECRET"));
+  assert(envKeyReads('envVar( "NANO_WORKFORCE_GIT_SHA" )').includes("NANO_WORKFORCE_GIT_SHA"));
+});
+
+test("envKeyReads: catches keys across all patterns in one source", () => {
+  const src = [
+    "const a = process.env.CAMUNDA_TRANSPORT;",
+    'const b = process.env["NANOBPMN_BASE_URL"];',
+    'const c = envVar("NANO_WORKFORCE_GIT_SHA");',
+  ].join("\n");
+  const keys = new Set(envKeyReads(src));
+  assert(keys.has("CAMUNDA_TRANSPORT"));
+  assert(keys.has("NANOBPMN_BASE_URL"));
+  assert(keys.has("NANO_WORKFORCE_GIT_SHA"));
+});
+
+test("envKeyReads: a dynamic (non-literal) read is NOT matched", () => {
+  // `process.env[name]` (a variable) can't be resolved statically, so it isn't reported.
+  assertEquals(envKeyReads("const v = process.env[name];"), []);
+});
+
+test("GITHUB_TOKEN is enforced by the gate and declared in the registry (PR #229 suppressed advisory)", () => {
+  // GITHUB_TOKEN is read in production outside the config families (app/service.ts,
+  // operations/startPlanFanout.ts). Pin it into the enforced set so the gate holds it to its
+  // registry declaration — a future removal from ENV_CONTRACTS while code still reads it must fail.
+  assert(EXPLICIT_CONFIG_KEYS.has("GITHUB_TOKEN"), "GITHUB_TOKEN must be an enforced config key");
+  assert("GITHUB_TOKEN" in ENV_CONTRACTS, "GITHUB_TOKEN must be declared in ENV_CONTRACTS");
+});
+
+test("toPosixRel: normalises Windows backslashes so EXEMPT_FILES matches cross-platform (PR #229 suppressed advisory)", () => {
+  // On Windows `join` yields backslashes, so `scripts\check-contracts.ts` would never match the
+  // POSIX-style EXEMPT_FILES entry and the checker would self-scan and explode. Normalise them.
+  assertEquals(toPosixRel("C:\\repo\\scripts\\check-contracts.ts", "C:\\repo"), "scripts/check-contracts.ts");
+  // POSIX paths are already correct and pass through unchanged.
+  assertEquals(toPosixRel("/repo/scripts/check-contracts.ts", "/repo"), "scripts/check-contracts.ts");
+});