@nanobpm/nano-workforce 0.45.0 → 0.46.0

package/operations/answerPlanEscalation.ts

@@ -0,0 +1,41 @@
+// POST /app/api/hooks/plan-answer → operationId `answerPlanEscalation`. Answers a plan-review
+// cap escalation out of band. The process is parked on `plan-escalation-answered`, correlated by
+// planKey; the answer records the human directive and resumes the plan.
+import {
+  answerPlanEscalation as answerPlanEscalationState,
+  parsePlanEscalationDirective,
+} from "../app/plan.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const WEBHOOK_SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("answerPlanEscalation", async ({ req, body }, app) => {
+  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
+    app.log.warn("plan-answer rejected: missing/invalid shared secret");
+    return { status: 401, body: { ok: false, error: "unauthorized" } };
+  }
+  if (!body || typeof body !== "object") {
+    app.log.warn("plan-answer rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "plan and directive are required" } };
+  }
+
+  const planKey = str(body.plan);
+  const directive = parsePlanEscalationDirective(body.directive);
+  const note = str(body.note);
+  if (!planKey) {
+    app.log.warn("plan-answer rejected: missing plan");
+    return { status: 400, body: { ok: false, error: "plan is required" } };
+  }
+  if (!directive) {
+    app.log.warn("plan-answer rejected: invalid directive", { directive: str(body.directive) });
+    return { status: 400, body: { ok: false, error: "directive must be proceed or revise" } };
+  }
+
+  const r = await answerPlanEscalationState(app.data, app.engine, planKey, directive, note);
+  if (r.ok) app.log.info("plan escalation answered", { planKey, directive });
+  else app.log.warn("plan-answer: no open plan escalation to answer", { planKey });
+  return { status: r.ok ? 200 : 404, body: r };
+});

package/operations/postMessage.ts

@@ -1,15 +1,21 @@
 // POST /app/api/actions/message → operationId `postMessage` (ADR 0058, base /app/api).
 // Replaces the hand-rolled action that overrode the generic publishMessage action. For the
-// `escalation-answered` message we run the review answer flow, and for `feature-escalation-answered`
-// (issue #25) the implementation-phase (per-task) answer flow: record the answer, resume the parked
-// token, then re-surface the next open escalation. Any other message falls back to a plain
-// publishMessage.
+// `escalation-answered` message we run the review answer flow, for `feature-escalation-answered`
+// (issue #25) the implementation-phase (per-task) answer flow, and for
+// `plan-escalation-answered` the plan-review cap answer flow. Any other message falls back to a
+// plain publishMessage.
 //
 // The runtime validates the body against openapi.yaml (`name` is required, so a missing name is a 400
 // for free); this delegate keeps the message-name dispatch — the discriminator + downstream behavior
 // is app logic, not something the JSON schema can express.
 
-import { answerTaskEscalation, FEATURE_ESCALATION_MESSAGE } from "../app/plan.ts";
+import {
+  answerPlanEscalation,
+  answerTaskEscalation,
+  FEATURE_ESCALATION_MESSAGE,
+  PLAN_ESCALATION_MESSAGE,
+  parsePlanEscalationDirective,
+} from "../app/plan.ts";
 import { answerEscalation } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
@@ -46,6 +52,20 @@ export default defineOperation("postMessage", async ({ body }, app) => {
     return { status: r.ok ? 200 : 404, body: r };
   }
 
+  if (name === PLAN_ESCALATION_MESSAGE) {
+    const planKey = String(b.correlationKey ?? "");
+    const directive = parsePlanEscalationDirective(b.variables?.directive ?? "revise");
+    const note = String(b.variables?.note ?? b.variables?.answer ?? "").trim();
+    if (!planKey) return { status: 400, body: { error: "correlationKey is required" } };
+    if (!directive) {
+      return { status: 400, body: { error: "directive must be proceed or revise" } };
+    }
+    const r = await answerPlanEscalation(app.data, app.engine, planKey, directive, note);
+    if (r.ok) app.log.info("plan escalation answered", { name, planKey, directive });
+    else app.log.warn("postMessage: no open plan escalation to answer", { name, planKey });
+    return { status: r.ok ? 200 : 404, body: r };
+  }
+
   await app.engine.publishMessage({
     name,
     correlationKey: b.correlationKey != null ? String(b.correlationKey) : undefined,

package/operations/startAndMessage.test.ts

@@ -162,3 +162,61 @@ test("postMessage → 400 when escalation-answered lacks a correlationKey", asyn
   assertEquals(r.status, 400);
   assertEquals(r.body.error, "correlationKey is required");
 });
+
+function planEscalationMessageApp() {
+  const plans = [{ plan_key: "owner/repo#12", open_plan_escalation_id: 1 }];
+  const escalations = [{
+    id: 1,
+    plan_key: "owner/repo#12",
+    epoch: 0,
+    round: 2,
+    findings: "needs guidance",
+    status: "open",
+    directive: null,
+    note: null,
+  }];
+  const published: any[] = [];
+  const match = (r: Record<string, unknown>, q: Record<string, unknown>) =>
+    Object.entries(q).every(([f, v]) => r[f] === v);
+  const table = (rows: any[], key: string) => ({
+    find: (q: any) => Promise.resolve(rows.filter((r) => match(r, q))),
+    update: (id: any, patch: any) => {
+      const row = rows.find((r) => r[key] === id);
+      if (row) Object.assign(row, patch);
+      return Promise.resolve(row);
+    },
+  });
+  return {
+    app: {
+      data: {
+        table(name: string) {
+          return name === "plans" ? table(plans, "plan_key") : table(escalations, "id");
+        },
+      },
+      engine: {
+        publishMessage: (m: any) => {
+          published.push(m);
+          return Promise.resolve();
+        },
+      },
+      log: noopLog(),
+    } as any as AppApi,
+    escalations,
+    published,
+  };
+}
+
+test("postMessage accepts mixed-case plan escalation directive like the dedicated hook", async () => {
+  const { app: msgApp, escalations, published } = planEscalationMessageApp();
+  const res = await postMessage(input({
+    name: "plan-escalation-answered",
+    correlationKey: "owner/repo#12",
+    variables: { directive: "PrOcEeD", note: "ship it" },
+  }), msgApp);
+  const r = res as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.ok, true);
+  assertEquals(r.body.directive, "proceed");
+  assertEquals(escalations[0].directive, "proceed");
+  assertEquals(published[0].variables.planEscalationDirective, "proceed");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.45.0",
+  "version": "0.46.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

@@ -70,8 +70,24 @@
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "task_count", "header": "Tasks" },
           { "field": "open_task_id", "header": "Open escalation" },
+          { "field": "open_plan_round", "header": "Plan escalation round" },
           { "field": "updated_at", "header": "Updated" }
         ],
+        "rowActions": [
+          {
+            "label": "Proceed with plan",
+            "confirm": "Dispatch the current unapproved plan as a human override?",
+            "showWhenField": "open_plan_escalation_id",
+            "action": {
+              "path": "/app/api/actions/message",
+              "body": {
+                "name": "plan-escalation-answered",
+                "correlationKey": "{{row.plan_key}}",
+                "variables": { "directive": "proceed", "note": "Proceed override from the plans page." }
+              }
+            }
+          }
+        ],
         "detail": {
           "linkField": "issue_url",
           "fields": [
@@ -79,8 +95,25 @@
             { "field": "issue_number", "label": "Issue number" },
             { "field": "base_branch", "label": "Base branch (blank = repo default)" },
             { "field": "outcome", "label": "Outcome" },
+            { "field": "open_plan_findings", "label": "Open plan-review findings" },
             { "field": "open_task_question", "label": "Open escalation question" }
-          ]
+          ],
+          "form": {
+            "showWhenField": "open_plan_escalation_id",
+            "title": "Answer the open plan-review escalation",
+            "promptField": "open_plan_findings",
+            "inputKey": "note",
+            "inputLabel": "Revision directive note for the planner",
+            "submitLabel": "Revise plan",
+            "action": {
+              "path": "/app/api/actions/message",
+              "body": {
+                "name": "plan-escalation-answered",
+                "correlationKey": "{{row.plan_key}}",
+                "variables": { "directive": "revise", "note": "{{form.note}}" }
+              }
+            }
+          }
         }
       }
     },
@@ -99,12 +132,39 @@
         "columns": [
           { "field": "plan_key", "header": "Plan" },
           { "field": "round", "header": "Round" },
+          { "field": "epoch", "header": "Epoch" },
           { "field": "approved", "header": "Approved? (1/0)" },
           { "field": "findings", "header": "Reviewer findings" },
           { "field": "created_at", "header": "Recorded" }
         ]
       }
     },
+    {
+      "type": "dataGrid",
+      "id": "plan-review-escalations",
+      "props": {
+        "title": "Plan-review escalations",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_review_escalations",
+          "orderBy": { "field": "id", "dir": "desc" }
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "epoch", "header": "Epoch" },
+          { "field": "round", "header": "Round" },
+          { "field": "findings", "header": "Findings" },
+          { "field": "status", "header": "Status" },
+          { "field": "directive", "header": "Directive" },
+          { "field": "note", "header": "Human note" },
+          { "field": "asked_at", "header": "Asked" },
+          { "field": "answered_at", "header": "Answered" }
+        ]
+      }
+    },
     {
       "type": "dataGrid",
       "id": "wave-state",

package/prompts/plan.md

@@ -36,6 +36,17 @@ Before decomposing anything yourself, check whether the issue is an **epic that
 has already been split into sub-issues**. If it has, **do not invent a new
 breakdown** — adopt the existing one, one task per sub-issue. This keeps the
 fan-out faithful to the human's plan and links each PR back to its sub-issue.
+On the first pass this means adopting the open sub-issue set faithfully. On a
+rejected review, however, still keep the task set 1:1 with those open
+sub-issues while you revise each task's `prompt` and `dependsOn` to satisfy the
+findings. You MAY and SHOULD add a contract/seam deliverable to one existing
+sub-issue task's prompt (for example, a shared-surface registration seam), point
+sibling tasks at it, and create wave-0 ordering via an existing sub-issue — but
+never add, merge, re-split, or remove tasks, and never edit the GitHub issues. If
+a finding genuinely requires changing the sub-issue boundary (splitting,
+merging, adding, or removing a sub-issue) and cannot be expressed as a
+`prompt`/`dependsOn` revision, say that it requires a human decomposition change,
+then re-emit the best in-boundary plan you can.
 
 Detect existing children two ways (try both; union the results, de-duplicated):
 

package/resources/agent-guide.md

@@ -151,9 +151,19 @@ curl -sS -X POST __BASE__/hooks/feature-answer \
 
 If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
 
-Guidance for the human you assist: read the escalation `question` first (it is the
-exact blocker text the agent surfaced), decide the smallest unblocking answer, and
-answer it precisely — the answer becomes the agent's next-round context.
+**Answer a plan-review escalation** raised when the adversarial plan review cannot
+converge within its round budget. Use `revise` to send guidance back to the planner
+with a fresh review budget, or `proceed` to explicitly approve the current plan as-is:
+
+```bash
+curl -sS -X POST __BASE__/hooks/plan-answer \
+  -H 'content-type: application/json' \
+  -d '{ "plan": "owner/repo#123", "directive": "revise", "note": "Keep the sub-issues 1:1; make issue-7 the seam and point siblings at it." }'
+```
+
+Guidance for the human you assist: read the escalation `question` or plan-review
+`findings` first, decide the smallest unblocking answer, and answer it precisely —
+the answer becomes the agent's next-round context.
 
 ---