@nanobpm/nano-workforce 0.45.0 → 0.46.1

package/db/migrations/020_plan_review_escalation.sql

@@ -0,0 +1,51 @@
+-- Plan-review cap escalation. When the adversarial review loop exhausts its per-epoch budget
+-- without approval, the plan-fanout process parks for a human directive instead of raising an
+-- unhandled PLAN_REJECTED incident. A `revise` answer starts a new review epoch; a `proceed`
+-- answer explicitly dispatches the current plan as-is.
+--
+-- `plan_reviews.round` remains derived from the append-only review log, but now within the current
+-- epoch. SQLite cannot alter the existing PRIMARY KEY (plan_key, round), so recreate the table with
+-- (plan_key, epoch, round) and backfill existing rows into epoch 0.
+
+ALTER TABLE plan_reviews ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0;
+
+CREATE TABLE plan_reviews_new (
+  plan_key    TEXT NOT NULL REFERENCES plans(plan_key),
+  epoch       INTEGER NOT NULL DEFAULT 0,
+  round       INTEGER NOT NULL,
+  approved    INTEGER NOT NULL,
+  findings    TEXT,
+  created_at  TEXT NOT NULL,
+  job_key     TEXT,
+  PRIMARY KEY (plan_key, epoch, round)
+);
+
+INSERT INTO plan_reviews_new (plan_key, epoch, round, approved, findings, created_at, job_key)
+SELECT plan_key, epoch, round, approved, findings, created_at, job_key
+FROM plan_reviews;
+
+DROP TABLE plan_reviews;
+ALTER TABLE plan_reviews_new RENAME TO plan_reviews;
+
+CREATE INDEX idx_plan_reviews_plan ON plan_reviews(plan_key);
+CREATE UNIQUE INDEX idx_plan_reviews_job ON plan_reviews(plan_key, job_key);
+
+CREATE TABLE plan_review_escalations (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  plan_key     TEXT NOT NULL REFERENCES plans(plan_key),
+  epoch        INTEGER NOT NULL,
+  round        INTEGER NOT NULL,
+  findings     TEXT,
+  status       TEXT NOT NULL,              -- open | answered
+  directive    TEXT,                       -- proceed | revise (answered rows only)
+  note         TEXT,
+  asked_at     TEXT NOT NULL,
+  answered_at  TEXT
+);
+
+CREATE INDEX idx_plan_review_escalations_plan ON plan_review_escalations(plan_key);
+CREATE INDEX idx_plan_review_escalations_open ON plan_review_escalations(plan_key, status);
+
+ALTER TABLE plans ADD COLUMN open_plan_escalation_id INTEGER;
+ALTER TABLE plans ADD COLUMN open_plan_findings TEXT;
+ALTER TABLE plans ADD COLUMN open_plan_round INTEGER;

package/db/migrations/021_trial_merge_resolved.sql

@@ -0,0 +1,44 @@
+-- Durable "needs attention" resolution for the trial-merge audit log (issue: the
+-- epic page's "Needs attention" tab never cleared).
+--
+-- `plan_trial_merges` is an append-only audit trail: a re-run after a suite
+-- failure INSERTs a fresh row but never supersedes the old red one, so a
+-- `merge-conflict`/`suite-failed` row stayed in "Needs attention" forever even
+-- after the escalation was answered and the wave re-run clean. Add an explicit
+-- `resolved` flag so the page can hide history, and backfill it for existing
+-- rows. Going forward `recordTrialMergeAudit` marks prior same-(plan,wave) rows
+-- resolved on each new insert (supersede-on-insert).
+--
+-- NB: the migration runner wraps each file in its own transaction — this file
+-- must NOT contain BEGIN/COMMIT.
+
+ALTER TABLE plan_trial_merges ADD COLUMN resolved INTEGER NOT NULL DEFAULT 0;
+
+-- Backfill 1 (supersede): any audit row that has a NEWER row (higher id) for the
+-- same (plan_key, wave) is superseded history — resolve it. The newest row per
+-- wave stays unresolved so a still-red latest attempt keeps showing.
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE EXISTS (
+  SELECT 1 FROM plan_trial_merges AS newer
+  WHERE newer.plan_key = plan_trial_merges.plan_key
+    AND newer.wave = plan_trial_merges.wave
+    AND newer.id > plan_trial_merges.id
+);
+
+-- Backfill 2 (answered): a red (needs-attention) row whose trial escalation has
+-- already been answered is resolved — even if no re-run row was ever recorded
+-- (e.g. the operator answered "proceed"/override). The trial escalation's
+-- task_id is 'trial-merge-wave-<wave>' (see app/trialMerge.ts trialMergeTaskId).
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE result IN ('merge-conflict', 'suite-failed')
+  AND EXISTS (
+    SELECT 1 FROM plan_escalations AS e
+    WHERE e.plan_key = plan_trial_merges.plan_key
+      AND e.task_id = 'trial-merge-wave-' || plan_trial_merges.wave
+      AND e.status = 'answered'
+  );
+
+CREATE INDEX IF NOT EXISTS idx_plan_trial_merges_attention
+  ON plan_trial_merges(plan_key, resolved, result);

package/nano.app.json

@@ -119,6 +119,10 @@
       "taskType": "pr.persist-task-escalation",
       "handler": "workers/persist-task-escalation/worker.ts"
     },
+    {
+      "taskType": "pr.persist-plan-escalation",
+      "handler": "workers/persist-plan-escalation/worker.ts"
+    },
     {
       "taskType": "pr.retro-gather",
       "handler": "workers/retro-gather/worker.ts"

package/openapi.yaml

@@ -345,6 +345,27 @@ components:
           type: string
           minLength: 1
           description: The operator's answer that resumes the parked implementation agent.
+    PlanAnswerRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - plan
+        - directive
+      properties:
+        plan:
+          type: string
+          description: Plan reference (owner/repo#N), also the message correlation key.
+        directive:
+          type: string
+          description: >-
+            One of `proceed` or `revise` (case-insensitive; normalized to lowercase and trimmed
+            server-side, see `parsePlanEscalationDirective`).
+            `proceed` dispatches the current unapproved plan as an explicit human override;
+            `revise` loops back to the planner with the note folded into planFindings and a fresh
+            review budget.
+        note:
+          type: string
+          description: Human guidance for the planner (used for `revise`; optional for `proceed`).
     BlackboardEntry:
       type: object
       additionalProperties: false
@@ -578,9 +599,9 @@ paths:
   /actions/message:
     post:
       operationId: postMessage
-      summary: Publish a message / answer an escalation. For escalation-answered and
-        feature-escalation-answered names, runs the corresponding answer flow; otherwise a plain
-        publishMessage.
+      summary: Publish a message / answer an escalation. For escalation-answered,
+        feature-escalation-answered, and plan-escalation-answered names, runs the corresponding
+        answer flow; otherwise a plain publishMessage.
       requestBody:
         required: true
         content:
@@ -603,6 +624,13 @@ paths:
                   properties:
                     answer:
                       type: string
+                    directive:
+                      type: string
+                      description: >-
+                        One of `proceed` or `revise` (case-insensitive; normalized to lowercase and
+                        trimmed server-side, see `parsePlanEscalationDirective`).
+                    note:
+                      type: string
       responses:
         "200":
           description: The message was published (or the escalation answered).
@@ -661,6 +689,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /hooks/plan-answer:
+    post:
+      operationId: answerPlanEscalation
+      summary: "Answer a plan-review cap escalation out of band. Optional shared-secret guard
+        (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is set."
+      security:
+        - hookSecret: []
+        - {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PlanAnswerRequest"
+      responses:
+        "200":
+          description: The escalation was answered and the parked plan resumed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field was missing (plan or directive).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No matching open plan escalation for the plan key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/blackboard:
     get:
       operationId: readBlackboard

package/operations/answerPlanEscalation.test.ts

@@ -0,0 +1,115 @@
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+
+const hadSecret = Object.prototype.hasOwnProperty.call(process.env, "NANO_PR_WEBHOOK_SECRET");
+const previousSecret = process.env.NANO_PR_WEBHOOK_SECRET;
+let answerPlanEscalation: typeof import("./answerPlanEscalation.ts").default;
+try {
+  process.env.NANO_PR_WEBHOOK_SECRET = " test-secret ";
+  answerPlanEscalation = (await import("./answerPlanEscalation.ts")).default;
+} finally {
+  if (hadSecret && previousSecret !== undefined) process.env.NANO_PR_WEBHOOK_SECRET = previousSecret;
+  else delete process.env.NANO_PR_WEBHOOK_SECRET;
+}
+
+function memTable(rows: any[], key: string) {
+  return {
+    find: (where: Record<string, unknown>) =>
+      Promise.resolve(rows.filter((row) => Object.entries(where).every(([field, value]) => row[field] === value))),
+    update: (value: unknown, patch: Record<string, unknown>) => {
+      const row = rows.find((candidate) => candidate[key] === value);
+      if (row) Object.assign(row, patch);
+      return Promise.resolve(row);
+    },
+  };
+}
+
+function memApp(escalations: any[] = []) {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: "owner/repo#9", open_plan_escalation_id: 1 }], key: "plan_key" },
+    plan_review_escalations: { rows: escalations, key: "id" },
+  };
+  const published: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    },
+    engine: {
+      publishMessage: (message: Record<string, unknown>) => {
+        published.push(message);
+        return Promise.resolve();
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, published, stores };
+}
+
+function input(body: Record<string, unknown>, secret?: string) {
+  const headers = new Headers();
+  if (secret !== undefined) headers.set("x-hook-secret", secret);
+  return {
+    req: {
+      method: "POST",
+      path: "/app/api/hooks/plan-answer",
+      query: new URLSearchParams(),
+      headers,
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+test("rejects a request without the configured hook secret", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(input({ plan: "owner/repo#9", directive: "revise" }), app) as any;
+  assertEquals(result.status, 401);
+  assertEquals(result.body, { ok: false, error: "unauthorized" });
+});
+
+test("answers an open plan escalation and publishes the plan correlation message", async () => {
+  const { app, published, stores } = memApp([{
+    id: 1,
+    plan_key: "owner/repo#9",
+    epoch: 0,
+    round: 2,
+    findings: "needs wave 0",
+    status: "open",
+  }]);
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#9", directive: "revise", note: " use issue-1 first " }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 200);
+  assertEquals(result.body.ok, true);
+  assertEquals(stores.plan_review_escalations.rows[0].status, "answered");
+  assertEquals(stores.plan_review_escalations.rows[0].directive, "revise");
+  assertEquals(stores.plan_review_escalations.rows[0].note, "use issue-1 first");
+  assertEquals(published[0]?.name, "plan-escalation-answered");
+  assertEquals(published[0]?.correlationKey, "owner/repo#9");
+  assertEquals((published[0]?.variables as Record<string, unknown>).planEscalationDirective, "revise");
+});
+
+test("maps an unmatched plan to 404", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#missing", directive: "revise" }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 404);
+  assertEquals(result.body.ok, false);
+});
+
+test("rejects an invalid directive with 400", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#9", directive: "ship-it" }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 400);
+  assertEquals(result.body.ok, false);
+});

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.1",
   "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",
@@ -213,12 +273,18 @@
           "source": "app",
           "table": "plan_trial_merges",
           "orderBy": { "field": "created_at", "dir": "desc" },
-          "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+          "filter": [
+            { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+            { "field": "resolved", "in": [0] }
+          ]
         },
         "tabs": [
           {
             "label": "Needs attention",
-            "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+            "filter": [
+              { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+              { "field": "resolved", "in": [0] }
+            ]
           },
           {
             "label": "Clean",

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.
 
 ---