@nanobpm/nano-workforce 0.194.0 → 0.195.0

package/db/migrations/116_feature_runs_human_approval.sql

@@ -0,0 +1,51 @@
+-- Issue #826: optional human approval before merge. 1 ⇒ the converged PR parks at the
+-- `merge-approval` user task in convergence-loop.bpmn before the merge-loop runs. Additive (expand).
+ALTER TABLE feature_runs ADD COLUMN human_approval INTEGER NOT NULL DEFAULT 0;
+
+-- Mirror the new column through the `delivery_units` aggregate so the `feature_runs__units` compat VIEW
+-- stays row-for-row equal to `feature_runs` (ADR 0006, parity-tested in app/deliveryUnit.test.ts): the
+-- Feature sync triggers (089) and VIEW (091) are re-created verbatim plus `human_approval`.
+ALTER TABLE delivery_units ADD COLUMN human_approval INTEGER;
+UPDATE delivery_units SET human_approval = 0 WHERE kind = 'feature';
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.human_approval AS human_approval,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';

package/e2e/feature-run.e2e.ts

@@ -62,6 +62,7 @@ interface FeatureRow {
 }
 interface PrRow {
   pr_key: string;
+  process_key: string | null;
 }
 
 describe("single-issue feature run (#172 — feature.bpmn)", () => {
@@ -184,6 +185,23 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     );
   });
 
+  test("raise + converge + human approval: the enrolled convergence loop carries the approval gate (issue #826)", async () => {
+    await withApp(
+      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#103", summary: "built it" }) },
+      { baseBranch: "epic/e2e", converge: true, autoMerge: true, humanApproval: true },
+      async ({ app }) => {
+        // The flag must survive the real handoff: feature.bpmn → converge-cell callActivity →
+        // pr.converge-feature → submitPr → the live loop instance (still ACTIVE, so its vars are readable).
+        const pr = await app.db.table<PrRow>("pull_requests", "pr_key").findOne({ pr_key: "owner/repo#103" });
+        assert.ok(pr?.process_key, "converge enrolled the raised PR into a live convergence loop");
+        const instances = app.snapshot().instances;
+        assert.ok(Array.isArray(instances), "snapshot.instances is an array of instance rows");
+        const loop = instances.find((i) => i?.key === pr.process_key);
+        assert.equal(loop?.variables?.humanApproval, true, "the convergence loop was seeded with humanApproval");
+      },
+    );
+  });
+
   test("blocked: parks at the operators' user task (non-terminal), never enrolls a PR, settles on ack", async () => {
     await withApp(
       { "senior:feature": () => ({ status: "blocked", summary: "could not proceed" }) },

package/openapi.yaml

@@ -3442,6 +3442,12 @@ components:
             When true (and `converge` is true), drive the merge-loop after convergence only when
             `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`.
             Moot when `converge` is false.
+        humanApproval:
+          type: boolean
+          description: >-
+            When true (with `autoMerge`), the converged PR waits in Tasks for a human to approve the
+            merge or request changes; the agent applies them to the same PR and convergence re-runs.
+            Moot when the run does not merge (see `autoMerge`).
         confirmDefaultBase:
           type: boolean
           description: >-
@@ -3513,6 +3519,9 @@ components:
         autoMerge:
           type: boolean
           description: When true (with `converge`), drive the merge-loop. See `FeatureStartByIssue.autoMerge`.
+        humanApproval:
+          type: boolean
+          description: When true (with `autoMerge`), a human approves the merge. See `FeatureStartByIssue.humanApproval`.
         confirmDefaultBase:
           type: boolean
           description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.
@@ -6181,6 +6190,9 @@ paths:
                     autoMerge:
                       type: boolean
                       description: When true (and `converge` is true), drive the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`. Moot when `converge` is false.
+                    humanApproval:
+                      type: boolean
+                      description: When true (with `autoMerge`), the converged PR waits in Tasks for a human to approve the merge or request changes; the agent applies them to the same PR and convergence re-runs. Moot when the run does not merge (see `autoMerge`).
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge that `baseBranch` is the repository default branch (the PR would target it directly). See `PlanStartByIssue.confirmDefaultBase`.
@@ -6326,6 +6338,9 @@ paths:
                     autoMerge:
                       type: boolean
                       description: When true (with `converge`), drive the merge-loop. See `FeatureStartByIssue.autoMerge`.
+                    humanApproval:
+                      type: boolean
+                      description: When true (with `autoMerge`), a human approves the merge. See `FeatureStartByIssue.humanApproval`.
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.

package/operations/startFeature.readiness.integration.test.ts

@@ -193,3 +193,17 @@ test("malformed readiness descriptor → 400 at the edge (never a 500)", async (
     assertEquals(started.length, 0);
   });
 });
+
+// ── human approval before merge (issue #826): threaded through the edge, pinned off without autoMerge ─
+
+test("humanApproval reaches the run only together with autoMerge", async () => {
+  await withGithub(REPO, async () => {
+    for (const [autoMerge, expected] of [[true, true], [false, false]] as const) {
+      const { app, started } = makeApp();
+      const body = { issue: `${REPO}#577`, ...GATED_BASE, converge: true, autoMerge, humanApproval: true };
+      const res = (await startFeature(input(body), app)) as any;
+      assertEquals(res.status, 202);
+      assertEquals(started[0].variables?.humanApproval, expected);
+    }
+  });
+});

package/operations/startFeature.ts

@@ -116,6 +116,8 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
+  // Human approval gates the merge-loop, so it is moot (pinned off) without auto-merge (issue #826).
+  const humanApproval = autoMerge && "humanApproval" in body && body.humanApproval === true;
   // Optional operator steering threaded to the implementation agent's prompt. Empty/whitespace is
   // normalized to null downstream (startFeature) so it never appends an empty instruction block.
   const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
@@ -176,12 +178,14 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     autoMerge,
     customInstructions,
     { probes: readiness.probes, probeTimeout: readiness.probeTimeout, probePollEvery: readiness.probePollEvery },
+    humanApproval,
   );
   app.log.info("feature run intake", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
+    humanApproval,
     hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
     readinessProbes: readiness.probes.length,
     outcome: result.outcome,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.194.0",
+  "version": "0.195.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/feature.page.json

@@ -90,6 +90,7 @@
           { "key": "baseBranch", "label": "Base branch: 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", "required": true, "requiredMessage": "Name the branch the PR targets (e.g. main or epic/agent-protocol)" },
           { "key": "customInstructions", "label": "Custom instructions (optional) \u2014 extra steering appended to the implementation agent's prompt, e.g. \u201cprefer Deno; keep the diff small; add integration tests\u201d", "type": "text" },
           { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
+          { "key": "humanApproval", "label": "Human approval before merge \u2014 a converged PR waits in Tasks for you to approve the merge or request changes (only applies when Auto-merge is on)", "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" }

package/resources/forms/merge-approval.form

@@ -0,0 +1,36 @@
+{
+  "id": "merge-approval",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "label": "Approve merge",
+      "text": "This PR passed review convergence. Approve it to hand it to the merge loop, or request changes: your guidance goes to the review agent, which updates this same PR. Convergence then re-runs and approval is asked again."
+    },
+    {
+      "type": "select",
+      "key": "mergeDecision",
+      "label": "Decision",
+      "values": [
+        { "label": "Approve — merge the PR", "value": "approve" },
+        { "label": "Request changes — send guidance to the agent", "value": "revise" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "answer",
+      "label": "Guidance for the agent",
+      "description": "What should change before this PR merges? The agent implements it on the same PR.",
+      "validate": {
+        "required": true
+      },
+      "conditional": {
+        "hide": "=mergeDecision != \"revise\""
+      }
+    }
+  ]
+}