@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/operations/startPlanFanout.ts

@@ -10,7 +10,16 @@
 // 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 { InvalidBaseBranchError, normalizeBaseBranch, parseIssue, startPlan } from "../app/plan.ts";
+import { BaseBranchMustExistError } from "../app/github.ts";
+import {
+  admitPlan,
+  DefaultBaseNotConfirmedError,
+  InvalidBaseBranchError,
+  MissingBaseBranchError,
+  parseIssue,
+  SharedBaseError,
+  startPlan,
+} from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
@@ -26,16 +35,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)" } };
   }
-  // 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;
+  // Epic base branch (ADR 0003): admit the launch through the fail-fast `admitPlan` gate BEFORE any
+  // fan-out. It composes the four ordered admission rules — required+explicit, create-if-missing
+  // (epic/* guard, run synchronously so a typo is a clean edge 400), confirm-default, and
+  // shared-base — and returns the normalized base. Errors map to specific HTTP statuses at the edge.
+  const rawBase = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
+  const allowSharedBase = "allowSharedBase" in body && body.allowSharedBase === true;
+  const confirmDefaultBase = "confirmDefaultBase" in body && body.confirmDefaultBase === true;
+  const token = process.env.GITHUB_TOKEN ?? "";
+  let normalizedBase: string;
   try {
-    normalizedBase = normalizeBaseBranch(baseBranch);
+    normalizedBase = await admitPlan(app.data, parsed.repo, rawBase, token, {
+      allowSharedBase,
+      confirmDefaultBase,
+      selfPlanKey: parsed.planKey,
+    });
   } catch (err) {
+    if (err instanceof MissingBaseBranchError) {
+      app.log.warn("start-plan rejected: missing base branch");
+      return {
+        status: 400,
+        body: { error: "baseBranch is required (name the integration branch, e.g. epic/agent-protocol)" },
+      };
+    }
     if (err instanceof InvalidBaseBranchError) {
       app.log.warn("start-plan rejected: invalid base branch", { baseBranch: err.value });
       return {
@@ -43,13 +65,50 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
         body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)" },
       };
     }
+    if (err instanceof BaseBranchMustExistError) {
+      app.log.warn("start-plan rejected: base branch does not exist", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" does not exist and is not an epic/* branch, so it is not ` +
+            `auto-created — create it first, or use the epic/* convention`,
+        },
+      };
+    }
+    if (err instanceof DefaultBaseNotConfirmedError) {
+      app.log.warn("start-plan rejected: default base not confirmed", { baseBranch: err.branch });
+      return {
+        status: 400,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is the repository default branch — every task would land ` +
+            `directly on it with no integration branch. Re-submit with confirmDefaultBase: true to proceed`,
+        },
+      };
+    }
+    if (err instanceof SharedBaseError) {
+      app.log.warn("start-plan rejected: shared base branch", { baseBranch: err.branch });
+      return {
+        status: 409,
+        body: {
+          error:
+            `baseBranch "${err.branch}" is already in use by another active epic. Re-submit with ` +
+            `allowSharedBase: true to stack on it, or name a distinct epic/* branch`,
+        },
+      };
+    }
     throw err;
   }
   const result = await startPlan(app.data, app.engine, parsed, normalizedBase);
+  const alreadyRunning = "alreadyRunning" in result && result.alreadyRunning === true;
   app.log.info("plan fan-out started", {
     planKey: parsed.planKey,
-    baseBranch: normalizedBase ?? "(default branch)",
-    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+    // The base the caller requested. When `alreadyRunning`, `startPlan` short-circuits before this
+    // base takes effect (it may not match the in-flight plan's persisted base), so name it as the
+    // request — not the effective base — to keep the log honest.
+    requestedBaseBranch: normalizedBase,
+    alreadyRunning,
   });
   return { status: 202, body: result };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.56.0",
+  "version": "0.58.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",
@@ -35,12 +35,15 @@
     "typecheck": "tsc --noEmit",
     "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
+    "check:migrations": "node --experimental-strip-types scripts/check-migrations.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "dev": "urban dev",
+    "pretest": "urban gen",
     "test": "node --experimental-strip-types --test",
+    "pree2e": "urban gen",
     "e2e": "node --experimental-strip-types --test \"e2e/**/*.e2e.ts\"",
     "lint": "biome check app operations workers pages components scripts e2e main.ts",
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"

package/pages/cockpit.page.json

@@ -11,6 +11,7 @@
         "items": [
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
           { "label": "Cockpit", "page": "cockpit" }
         ],
         "sticky": true

package/pages/epic-detail.page.json

@@ -12,6 +12,7 @@
         "items": [
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }
@@ -29,6 +30,14 @@
         "variant": "sub"
       }
     },
+    {
+      "type": "text",
+      "id": "escalations-pointer",
+      "props": {
+        "text": "Escalations (task, plan-review, trial-merge) are native user tasks — answer them from the Task inbox at /tasks: list the open tasks, pick the one for this epic, and submit the typed decision. There is no separate answer form on this page.",
+        "variant": "sub"
+      }
+    },
     {
       "type": "dataGrid",
       "id": "epic-plan",
@@ -48,51 +57,16 @@
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "wave_label", "header": "Wave" },
           { "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 epic 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}}" }
-              }
-            }
-          }
+            { "field": "outcome", "label": "Outcome" }
+          ]
         }
       }
     },

package/pages/epic.page.json

@@ -12,6 +12,7 @@
         "items": [
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
           { "label": "Cockpit", "page": "cockpit" }
         ]
       }
@@ -38,7 +39,9 @@
         "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": "baseBranch", "label": "Base branch (blank = repo default; e.g. epic/agent-protocol to land the whole epic on an integration branch)", "type": "text" }
+          { "key": "baseBranch", "label": "Base branch (REQUIRED; e.g. epic/agent-protocol to land the whole epic on an integration branch). A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text" },
+          { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default (every task lands directly on it, with any merge-to-default side effect firing per task)", "type": "checkbox" },
+          { "key": "allowSharedBase", "label": "Allow sharing a custom integration branch with another active epic \u2014 required only when another in-flight epic already targets this same custom base", "type": "checkbox" }
         ]
       }
     },
@@ -70,9 +73,9 @@
         "columns": [
           { "field": "plan_key", "header": "Epic", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "base_branch", "header": "Base branch" },
           { "field": "wave_label", "header": "Wave" },
           { "field": "task_count", "header": "Tasks" },
-          { "field": "open_plan_findings", "header": "Attention", "badge": { "tone": "danger", "label": "!" } },
           { "field": "issue_number", "header": "Issue", "linkField": "issue_url" },
           { "field": "updated_at", "header": "Updated" }
         ]

package/pages/feature.page.json

@@ -0,0 +1,82 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Feature Run",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "sticky": true,
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
+          { "label": "Cockpit", "page": "cockpit" }
+        ]
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Single-issue feature run", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "Hand one issue to a single implementation agent — it raises exactly one PR. Optionally converge (review rounds) and auto-merge as follow-on steps. The missing middle between Epics (many PRs) and PR convergence (an already-open PR).",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "actionForm",
+      "id": "feature-submit",
+      "props": {
+        "title": "Implement one issue",
+        "submitLabel": "Implement & raise PR",
+        "action": { "path": "/app/api/actions/start/feature", "body": "{{form}}" },
+        "fields": [
+          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" },
+          { "key": "baseBranch", "label": "Base branch (REQUIRED; the branch the PR targets, e.g. main). A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text" },
+          { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
+          { "key": "autoMerge", "label": "Auto-merge \u2014 after convergence, drive the merge-loop (only applies when Converge is on)", "type": "checkbox" },
+          { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default", "type": "checkbox" },
+          { "key": "allowSharedBase", "label": "Allow sharing a custom integration branch with another active epic", "type": "checkbox" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "feature-runs",
+      "props": {
+        "title": "Feature runs",
+        "rowKey": "feature_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "feature_runs",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "status", "in": ["running"] }]
+        },
+        "tabs": [
+          { "label": "Active", "filter": [{ "field": "status", "in": ["running"] }] },
+          { "label": "History", "filter": [{ "field": "status", "in": ["opened", "converging", "blocked", "skipped", "failed", "abandoned"] }] },
+          { "label": "All", "filter": [] }
+        ],
+        "columns": [
+          { "field": "feature_key", "header": "Feature", "linkField": "issue_url" },
+          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "base_branch", "header": "Base branch" },
+          { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
+          { "field": "converge", "header": "Converge" },
+          { "field": "auto_merge", "header": "Auto-merge" },
+          { "field": "outcome", "header": "Outcome" },
+          { "field": "updated_at", "header": "Updated" }
+        ]
+      }
+    }
+  ]
+}

package/pages/home.page.json

@@ -17,6 +17,10 @@
             "label": "Epics",
             "page": "epic"
           },
+          {
+            "label": "Feature",
+            "page": "feature"
+          },
           {
             "label": "Cockpit",
             "page": "cockpit"
@@ -37,7 +41,7 @@
       "type": "text",
       "id": "subtitle",
       "props": {
-        "text": "Submit a pull request to run the autonomous review-convergence loop. Answer escalations inline; cancel a run at any time.",
+        "text": "Submit a pull request to run the autonomous review-convergence loop. Answer escalations from the Task inbox at /tasks; cancel a run at any time.",
         "variant": "sub"
       }
     },
@@ -329,23 +333,7 @@
                 }
               ]
             }
-          ],
-          "form": {
-            "showWhenField": "open_escalation_id",
-            "title": "Answer the open escalation",
-            "promptField": "open_escalation_question",
-            "inputKey": "answer",
-            "inputLabel": "Your answer",
-            "submitLabel": "Send answer",
-            "action": {
-              "path": "/app/api/actions/message",
-              "body": {
-                "name": "escalation-answered",
-                "correlationKey": "{{row.pr_key}}",
-                "variables": "{{form}}"
-              }
-            }
-          }
+          ]
         }
       }
     }

package/resources/agent-guide.md

@@ -97,13 +97,49 @@ PR is then enrolled into its own convergence loop (§1).
 ```bash
 curl -sS -X POST __BASE__/actions/start/plan-fanout \
   -H 'content-type: application/json' \
-  -d '{ "issue": "owner/repo#123" }'
+  -d '{ "issue": "owner/repo#123", "baseBranch": "epic/agent-protocol" }'
 ```
 
-The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL. Starting a
+The body is flat: `issue` (or `url`) — `owner/repo#123` or an issue URL — plus a REQUIRED
+`baseBranch` (ADR 0003), the branch the fleet branches off and opens every PR against; a
+blank/absent base is rejected with a 400. Starting a
 plan is idempotent on the plan key; an already-running plan short-circuits. The
 response (202) echoes the `planKey` and engine `processKey`.
 
+### Base-branch admission (ADR 0003)
+
+`startPlanFanout` admits the base through one fail-fast gate before any task fans out.
+Four ordered rules govern which base is accepted:
+
+1. **Required + explicit.** `baseBranch` is mandatory — a blank/absent value is a `400`
+   (`MissingBaseBranchError`), and an implausible name is a `400` (`InvalidBaseBranchError`).
+   There is no silent "land on the default branch" fallback.
+2. **Create-if-missing, `epic/*` only.** A missing `epic/*` base is **auto-created** off the
+   repository default branch's HEAD (idempotently — an existing branch is never reset). A
+   missing base that is **not** `epic/*` is a clean `400` (`BaseBranchMustExistError`): a typo
+   can't silently spawn a wrong-rooted branch, so any non-`epic/*` base must already exist.
+3. **Confirm-default.** Naming the repository **default branch** as the base requires
+   `confirmDefaultBase: true`, else `400` (`DefaultBaseNotConfirmedError`). This is a
+   deliberate acknowledgement that every task lands directly on the default branch with no
+   integration buffer, and any merge-to-default side effect fires per task.
+4. **Shared-base guard.** If another **active** epic (status not `done`/`failed`/`abandoned`)
+   already targets the **same repo + same custom base**, admission is a `409` (`SharedBaseError`)
+   unless you pass `allowSharedBase: true`. The default branch is exempt — many epics target it
+   concurrently without colliding.
+
+So the body may also carry two optional booleans — `confirmDefaultBase` and `allowSharedBase` —
+each a "warn you can't skip" for its rule:
+
+```bash
+curl -sS -X POST __BASE__/actions/start/plan-fanout \
+  -H 'content-type: application/json' \
+  -d '{ "issue": "owner/repo#123", "baseBranch": "main", "confirmDefaultBase": true }'
+```
+
+Grandfathered: in-flight plans launched before this admission gate (with a `null` base branch)
+keep running unchanged — the requirement is enforced at admission of **new** launches, not by a
+database constraint.
+
 Track a plan the same way you track PRs — its `process_key` is an engine instance you
 can inspect in §5, and the PRs it opens show up in `/status` as ordinary convergence
 loops.
@@ -124,43 +160,71 @@ curl -sS __BASE__/status | jq '.prs[] | select(.openEscalation != null)
   | { prKey, status, round, openEscalation }'
 ```
 
-**Answer a PR/merge escalation** (convergence-loop or merge-loop). Use the message
-name `escalation-answered`; correlate by the PR key:
+The four decision-required escalation kinds — **PR review-loop**, **implementation
+(feature) task**, **plan-review**, and **trial-merge** — are now native BPMN
+`userTask`s bearing a linked `.form`, all answered the same way through the **task
+inbox** surface. There is no bespoke per-kind webhook or answer page any more.
+
+**List the open escalation tasks.** Each task carries its context (e.g. `prKey` /
+`question` / `findings` / `task`) in its `variables`, and its kind in `elementId`:
 
 ```bash
-curl -sS -X POST __BASE__/actions/message \
-  -H 'content-type: application/json' \
-  -d '{
-        "name": "escalation-answered",
-        "correlationKey": "owner/repo#123",
-        "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
-      }'
+# Every parked escalation, across all kinds:
+curl -sS __BASE__/../../tasks/api/tasks | jq '.[] | { userTaskKey, elementId, variables }'
+
+# Filter to one kind (e.g. plan-review decisions) by elementId:
+curl -sS __BASE__/../../tasks/api/tasks \
+  | jq '[.[] | select(.elementId == "plan-review-decision")]'
 ```
 
-The answer is delivered to the agent as the `answer` variable on its next round, and
-the loop resumes.
+The inbox UI is also served at `__BASE__/../../tasks` for a human to browse, filter, and
+answer (assignee/candidate-group and age surface on each task once assignment lands).
 
-**Answer an implementation-phase (feature) task escalation** raised during a
-plan fan-out — a dedicated webhook operation:
+**Answer a task** by completing it with the typed variables its form expects — the
+completion resumes the parked process:
 
 ```bash
-curl -sS -X POST __BASE__/hooks/feature-answer \
-  -H 'content-type: application/json' \
-  -d '{ "correlationKey": "<task-or-pr-key>", "answer": "…" }'
+# PR review-loop (elementId `wait-answer`, pr-escalation form):
+curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
+  -d '{ "userTaskKey": "<key>", "variables": { "answer": "Cap retries at 5 and proceed." } }'
+
+# Implementation (feature) task (elementId `feature-escalation`):
+#   { "resolution": "answer", "answer": "…" }  to resume, or  { "resolution": "abandon" }
+curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
+  -d '{ "userTaskKey": "<key>", "variables": { "resolution": "answer", "answer": "Use v2." } }'
+
+# Plan-review (elementId `plan-review-decision`):
+#   { "directive": "revise", "notes": "…" }  (fresh review budget)  or  { "directive": "proceed" }
+curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
+  -d '{ "userTaskKey": "<key>", "variables": { "directive": "revise", "notes": "Make issue-7 the seam." } }'
+
+# Trial-merge (elementId `trial-merge-decision`):
+#   { "action": "proceed" | "rebase" | "abandon", "notes"?: "…" }
+curl -sS -X POST __BASE__/../../tasks/api/complete -H 'content-type: application/json' \
+  -d '{ "userTaskKey": "<key>", "variables": { "action": "rebase", "notes": "Re-run after the fix." } }'
 ```
 
-If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
-
-**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:
+**Answer a merge-loop escalation** (the one out-of-scope kind that still uses the
+durable message catch, not a user task). Use the message name `escalation-answered`,
+correlated by the PR key:
 
 ```bash
-curl -sS -X POST __BASE__/hooks/plan-answer \
+curl -sS -X POST __BASE__/actions/message \
   -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." }'
+  -d '{
+        "name": "escalation-answered",
+        "correlationKey": "owner/repo#123",
+        "variables": { "answer": "Yes — cap the retries at 5 and proceed." }
+      }'
 ```
 
+If `NANO_PR_WEBHOOK_SECRET` is set on the deployment, add `-H "x-hook-secret: <secret>"`.
+
+The answer is delivered to the agent as its next-round context (e.g. the `answer`,
+`directive`, or `action` variable), and the loop resumes. **Audit** is durable: the
+completed user tasks form the escalation history, and the review/merge loops' rows
+live in the `escalations` table (surfaced read-only per PR on the Convergence page).
+
 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.
@@ -173,7 +237,7 @@ the answer becomes the agent's next-round context.
  submit ──► convergence-loop
    round (senior:pr-review) ──► addressed ──► wait review-ready ─┐
                              ├─ converged  ──► finalize ──► merge-loop (unless convergeOnly)
-                             └─ needs_input/blocked ──► escalate ──► wait escalation-answered
+                             └─ needs_input/blocked ──► escalate ──► wait-answer userTask (task inbox)
  merge-loop: wait deps ─► arm merge ─► (queue-aware) merge / land
              blocked (CI red) ─► senior:fix-ci ─► retry     conflict ─► senior:rebase ─► retry
 ```

package/resources/forms/feature-escalation.form

@@ -0,0 +1,27 @@
+{
+  "id": "feature-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "select",
+      "key": "resolution",
+      "label": "Resolution",
+      "values": [
+        { "label": "Answer — re-dispatch the task with this guidance", "value": "answer" },
+        { "label": "Abandon — give up on this task", "value": "abandon" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "answer",
+      "label": "Answer / guidance for the implementation agent",
+      "conditional": {
+        "hide": "=resolution != \"answer\""
+      }
+    }
+  ]
+}

package/resources/forms/plan-review-decision.form

@@ -0,0 +1,27 @@
+{
+  "id": "plan-review-decision",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "select",
+      "key": "directive",
+      "label": "Directive",
+      "values": [
+        { "label": "Proceed — dispatch the current plan as-is", "value": "proceed" },
+        { "label": "Revise — send the plan back to the planner", "value": "revise" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "notes",
+      "label": "Revision guidance for the planner",
+      "conditional": {
+        "hide": "=directive != \"revise\""
+      }
+    }
+  ]
+}

package/resources/forms/pr-escalation.form

@@ -0,0 +1,23 @@
+{
+  "id": "pr-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "textarea",
+      "key": "question",
+      "label": "Escalation question",
+      "description": "A human decision is needed to resume the PR review-convergence loop.",
+      "readonly": true
+    },
+    {
+      "type": "textarea",
+      "key": "answer",
+      "label": "Your answer",
+      "description": "Your reply resumes the review loop and is handed to the next review round.",
+      "validate": {
+        "required": true
+      }
+    }
+  ]
+}

package/resources/forms/spine-demo.form

@@ -0,0 +1,15 @@
+{
+  "id": "spine-demo",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "textfield",
+      "key": "decision",
+      "label": "Decision",
+      "validate": {
+        "required": true
+      }
+    }
+  ]
+}