@nanobpm/nano-workforce 0.44.1 → 0.46.0

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

@@ -271,6 +271,15 @@ components:
         issue:
           type: string
           description: "Issue reference: owner/repo#123."
+        baseBranch:
+          type: string
+          description: >-
+            Optional target branch the fleet branches off and opens every PR against, instead of the
+            repository's default branch. Use this to land an entire epic on a long-lived integration
+            branch (e.g. `epic/agent-protocol`) so nothing reaches the default branch — and any
+            merge-to-default side effect, such as auto-publishing a package — until you deliberately
+            merge the integration branch. Blank/omitted keeps the current behaviour (the repo
+            default branch).
     PlanStartByUrl:
       type: object
       additionalProperties: false
@@ -280,6 +289,11 @@ components:
         url:
           type: string
           description: A bare issue URL, when no `owner/repo#123` reference is supplied.
+        baseBranch:
+          type: string
+          description: >-
+            Optional target branch the fleet branches off and opens every PR against, instead of the
+            repository's default branch. See `PlanStartByIssue.baseBranch`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message
@@ -331,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
@@ -564,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:
@@ -589,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).
@@ -647,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

@@ -121,6 +121,18 @@ test("startPlanFanout → 400 (not 500) on a missing request body", async () =>
   assertEquals(typeof r.body.error, "string");
 });
 
+test("startPlanFanout → 400 on an invalid baseBranch (not persisted/rendered)", async () => {
+  // A non-blank baseBranch that isn't a plausible git branch name (shell metacharacters here)
+  // must be rejected at the edge as a 400 — never persisted or interpolated into the agent prompt.
+  const res = await startPlanFanout(
+    input({ issue: "owner/repo#123", baseBranch: "epic/agent; rm -rf /" }),
+    app,
+  );
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
 test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () => {
   await withGithubOff(async () => {
     const { app: capApp } = captureApp();
@@ -150,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/operations/startPlanFanout.ts

@@ -10,7 +10,7 @@
 // ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
 // narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
-import { parseIssue, startPlan } from "../app/plan.ts";
+import { InvalidBaseBranchError, normalizeBaseBranch, parseIssue, startPlan } from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
@@ -26,9 +26,29 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
     app.log.warn("start-plan rejected: unparseable issue reference", { raw });
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
   }
-  const result = await startPlan(app.data, app.engine, parsed);
+  // Optional epic base branch: the branch the fleet branches off and opens every PR against instead
+  // of the repo default. Present on both oneOf variants; blank/absent keeps the default-branch
+  // behaviour. It is later interpolated into the authoritative implementer prompt (with `git`/`gh`
+  // shell snippets), so validate/normalise it HERE — a non-blank value that isn't a plausible git
+  // branch name is a 400 at the edge, never persisted or rendered. `normalizeBaseBranch` blank → null.
+  const baseBranch = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
+  let normalizedBase: string | null;
+  try {
+    normalizedBase = normalizeBaseBranch(baseBranch);
+  } catch (err) {
+    if (err instanceof InvalidBaseBranchError) {
+      app.log.warn("start-plan rejected: invalid base branch", { baseBranch: err.value });
+      return {
+        status: 400,
+        body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)" },
+      };
+    }
+    throw err;
+  }
+  const result = await startPlan(app.data, app.engine, parsed, normalizedBase);
   app.log.info("plan fan-out started", {
     planKey: parsed.planKey,
+    baseBranch: normalizedBase ?? "(default branch)",
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

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

@@ -35,7 +35,8 @@
         "submitLabel": "Plan & implement",
         "action": { "path": "/app/api/actions/start/plan-fanout", "body": "{{form}}" },
         "fields": [
-          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" }
+          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" },
+          { "key": "baseBranch", "label": "Base branch (blank = repo default; e.g. epic/agent-protocol to land the whole epic on an integration branch)", "type": "text" }
         ]
       }
     },
@@ -69,16 +70,50 @@
           { "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": [
             { "field": "repo", "label": "Repository" },
             { "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}}" }
+              }
+            }
+          }
         }
       }
     },
@@ -97,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/feature.md

@@ -26,14 +26,26 @@ process with no memory of your last run, the branch name MUST be derivable from
 (`git ls-remote --heads origin feat/<task.id>` or
 `gh pr list --head feat/<task.id> --state all`):
 
-- **It does not exist** → this is a first run. Branch off the default branch.
+- **It does not exist** → this is a first run. Branch off the base branch (see
+  the note below — usually the repository default branch, but an epic may pin an
+  integration branch in your appended task context).
 - **It exists** → this is a **resume**. `git fetch` and check it out, read its diff
   and any open (draft) PR, and **continue from there** — do not restart from
   scratch. Fold in `variables.answer` as the guidance you were waiting on.
 
+## Your base branch (default branch, unless the epic pins one)
+
+Branch off — and open your PR against — the repository's **default branch**,
+UNLESS your appended task context carries a **"Base branch (authoritative)"**
+note pinning an epic integration branch. When it does, that branch wins
+everywhere below: branch off `origin/<that branch>`, read the epic's latest
+landed state there, and pass `gh pr create --base <that branch>`. A PR opened
+against the wrong base will not be merged into the epic.
+
 ## What to do
 
-1. Clone / check out the repository's default branch (first run) or your existing
+1. Clone / check out your base branch (first run — the default branch, or the
+   pinned epic branch if your context names one) or your existing
    `feat/<task.id>` branch (resume — see above).
 2. Implement `task.prompt`. Keep the change scoped to this slice only.
 3. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the