@nanobpm/nano-workforce 0.157.0 → 0.158.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.158.0](https://github.com/nanobpm/nano-workforce/compare/v0.157.0...v0.158.0) (2026-08-29)
+
+### Features
+
+* **delivery-graph:** converge?/merge? as first-class edge-gated node policy; two-level merge (ADR 0006 S5) ([#604](https://github.com/nanobpm/nano-workforce/issues/604)) ([a880bac](https://github.com/nanobpm/nano-workforce/commit/a880baca513328af01e57cc9bcb5c1c6371a858c)), closes [#592](https://github.com/nanobpm/nano-workforce/issues/592)
+
 ## [0.157.0](https://github.com/nanobpm/nano-workforce/compare/v0.156.0...v0.157.0) (2026-08-29)
 
 ### Features

package/app/convergeTargets.ts

@@ -10,21 +10,31 @@
 export const CONVERGE_TARGET = "converge";
 
 /** The converge-AND-merge target: enrolls a PR into the shared convergence loop and drives the merge
- * loop too (the canonical `agent → connector[converge-merge] → wait[pr, merged]` land shape). */
+ * loop too (the canonical `agent → connector[converge-merge] → wait[pr, merged]` land shape). This is
+ * the UNIT-level land (ADR 0006 §3 two-level merge): a unit PR lands onto its own base branch — for a
+ * unit inside an epic that base is the epic integration branch, never `main` directly. */
 export const CONVERGE_MERGE_TARGET = "converge-merge";
 
-/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge`)? The single
- * predicate the connector worker branches on to route a dispatch into `submitPr`, and the validator
- * branches on to require a bound/literal PR (issue #548). */
+/** The GRAPH-level top-level merge target (ADR 0006 §3 / S5 two-level merge). Enrolls the graph/epic
+ * INTEGRATION PR into the shared convergence+merge doors like {@link CONVERGE_MERGE_TARGET}, but names
+ * the second, top-of-graph level whose base branch IS `main`. Behaviourally identical to
+ * `converge-merge` in dispatch (both `submitPr` with `convergeOnly=false`, landing to the PR's own
+ * base); the distinction is the LEVEL — kept a first-class literal so the two-level merge (unit → base;
+ * graph → `main`, ADR 0003 base-branch admission) is authored/enforced explicitly, not left emergent. */
+export const MERGE_MAIN_TARGET = "merge-main";
+
+/** Is `target` one of the converge-enrollment targets (`converge` / `converge-merge` / `merge-main`)?
+ * The single predicate the connector worker branches on to route a dispatch into `submitPr`, and the
+ * validator branches on to require a bound/literal PR (issue #548). */
 export function isConvergeTarget(target: string): boolean {
-  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET;
+  return target === CONVERGE_TARGET || target === CONVERGE_MERGE_TARGET || target === MERGE_MAIN_TARGET;
 }
 
 /** The DEFAULT `convergeOnly` for a converge target: `converge` is review-only (`true` — stop at
- * `converged`), `converge-merge` drives the merge loop too (`false`). Maps directly onto `submitPr`'s
- * `convergeOnly` argument. An author may still override it per-dispatch via the connector payload's
- * `convergeOnly`. Only ever consulted behind `isConvergeTarget`, so a non-converge target's `false`
- * is unreachable. */
+ * `converged`), `converge-merge` and `merge-main` drive the merge loop too (`false`). Maps directly
+ * onto `submitPr`'s `convergeOnly` argument. An author may still override it per-dispatch via the
+ * connector payload's `convergeOnly`. Only ever consulted behind `isConvergeTarget`, so a non-converge
+ * target's `false` is unreachable. */
 export function convergeOnlyForTarget(target: string): boolean {
   return target === CONVERGE_TARGET;
 }

package/app/deliveryConnector.test.ts

@@ -17,6 +17,7 @@ import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
 import {
   CONVERGE_MERGE_TARGET,
   CONVERGE_TARGET,
+  MERGE_MAIN_TARGET,
   connectorDedupeKey,
   convergeOnlyForTarget,
   type DeliveryConnectorDispatchRow,
@@ -103,6 +104,14 @@ test("converge targets: `converge`/`converge-merge` are the enrollment targets;
   assertEquals(convergeOnlyForTarget("converge-merge"), false);
 });
 
+test("two-level merge: `merge-main` is the graph-level enrollment target that drives the merge loop (S5)", () => {
+  assertEquals(MERGE_MAIN_TARGET, "merge-main");
+  // The graph-level top-level merge (graph → main) enrolls via `submitPr` like `converge-merge`.
+  assert(isConvergeTarget("merge-main"));
+  // It drives the merge loop (not review-only), so its `convergeOnly` default is false.
+  assertEquals(convergeOnlyForTarget("merge-main"), false);
+});
+
 test("first dispatch delivers exactly once; a redelivery on the same key dedupes and never re-acts", async () => {
   await withApp(async (app) => {
     const at = "2025-01-01T00:00:00.000Z";

package/app/deliveryConnector.ts

@@ -33,12 +33,13 @@ export const DELIVERY_CONNECTOR_TASK_TYPE = "pr.delivery-connector";
 export const OUTCOME_CLAIMED = "claimed";
 export const OUTCOME_DELIVERED = "delivered";
 
-/** The two connector `target`s that enroll an agent-opened PR into the app's SHARED convergence /
+/** The three connector `target`s that enroll an agent-opened PR into the app's SHARED convergence /
  * merge doors via `submitPr` (issue #500) — the delivery-graph side of the exact seam the feature
- * cell reuses (`workers/converge-feature`), no duplicated machinery. `converge-merge` drives review
- * convergence AND the merge loop; `converge` stops at `converged` (converge-only). This is the "real
+ * cell reuses (`workers/converge-feature`), no duplicated machinery. `converge-merge` (unit-level) and
+ * `merge-main` (graph-level, ADR 0006 §3 two-level merge) drive review convergence AND the merge loop;
+ * `converge` stops at `converged` (converge-only). This is the "real
  * target dispatch" ADR 0005 deferred as a later slice for the connector I/O surface: a `converge`/
- * `converge-merge` connector IS the "automated, side-effecting outbound action" a connector is
+ * `converge-merge`/`merge-main` connector IS the "automated, side-effecting outbound action" a connector is
  * defined to be. The converge-target vocabulary lives in the dependency-free {@link ./convergeTargets.ts}
  * so the pure validator can share it; re-exported here for the worker's existing import surface. */
 export {
@@ -46,6 +47,7 @@ export {
   CONVERGE_TARGET,
   convergeOnlyForTarget,
   isConvergeTarget,
+  MERGE_MAIN_TARGET,
 } from "./convergeTargets.ts";
 
 /** One durable dispatch-claim row — the at-most-once ledger entry a connector writes before it acts. */

package/app/deliveryGraph.test.ts

@@ -311,6 +311,67 @@ test("a human node may omit its config (generic-fallback resolution lands in S3)
   assertEquals(validateDeliveryGraph({ nodes: [{ id: "done", kind: "human" }] }), []);
 });
 
+test("raw-converge-node: a raw `senior:converge`/`senior:merge` agent job is not expressible (S5)", () => {
+  for (const jobType of ["senior:converge", "senior:merge", "converge", "merge"]) {
+    const errors = validateDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType } }] });
+    const err = hasCode(errors, "raw-converge-node");
+    assertEquals(err.path, "nodes[0].agent.jobType");
+  }
+});
+
+test("raw-converge-node: `senior:trial-merge` (the merge-cell body) is NOT swept up (exact-verb)", () => {
+  assertEquals(
+    validateDeliveryGraph({ nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:trial-merge" } }] }),
+    [],
+  );
+});
+
+test("a cell node may carry first-class `converge`/`merge` policy (S5)", () => {
+  assertEquals(
+    validateDeliveryGraph({
+      nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", converge: true, merge: true } }],
+    }),
+    [],
+  );
+  // converge-only (stop at green) is legal on its own.
+  assertEquals(
+    validateDeliveryGraph({
+      nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", converge: true } }],
+    }),
+    [],
+  );
+});
+
+test("converge-merge-type: `agent.converge`/`agent.merge` must be boolean when present (S5 trust boundary)", () => {
+  // `validateDeliveryGraph` is the trust boundary before `as DeliveryGraph`, so a graph that bypassed
+  // OpenAPI validation must not be able to smuggle a non-boolean `converge`/`merge` past the S5 policy
+  // checks (which compare `=== true`) — a truthy `"true"`/`1` would silently evade merge-requires-converge.
+  for (const bad of ["true", 1, 0, null] as const) {
+    const cErr = hasCode(
+      validateDeliveryGraph({
+        nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", converge: bad } }],
+      }),
+      "converge-merge-type",
+    );
+    assertEquals(cErr.path, "nodes[0].agent.converge");
+    const mErr = hasCode(
+      validateDeliveryGraph({
+        nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", converge: true, merge: bad } }],
+      }),
+      "converge-merge-type",
+    );
+    assertEquals(mErr.path, "nodes[0].agent.merge");
+  }
+});
+
+test("merge-requires-converge: `agent.merge` without `agent.converge` is rejected (S5 edge-gate)", () => {
+  const errors = validateDeliveryGraph({
+    nodes: [{ id: "a", kind: "agent", agent: { jobType: "senior:feature", merge: true } }],
+  });
+  const err = hasCode(errors, "merge-requires-converge");
+  assertEquals(err.path, "nodes[0].agent.merge");
+});
+
 test("duplicate-fact: two emits sharing a name on one node is rejected", () => {
   const errors = validateDeliveryGraph({
     nodes: [

package/app/deliveryGraph.ts

@@ -20,6 +20,7 @@
 // caller can point the author straight at the offending input.
 
 import { isConvergeTarget } from "./convergeTargets.ts";
+import { isRawConvergeMergeJobType, NODE_COMPLETION_POLICIES } from "./nodePolicy.ts";
 
 /** The CLOSED node-kind allowlist (ADR 0005 Decision 2) — the trust boundary. Extensible only by a
  * deliberate ADR/PR (add the openapi variant + a case here), never by a graph author. Kept as the
@@ -90,6 +91,9 @@ export type DeliveryGraphErrorCode =
   | "non-exhaustive-split"
   | "exclusive-merge-parity"
   | "unsupported-on-timeout"
+  | "raw-converge-node"
+  | "merge-requires-converge"
+  | "converge-merge-type"
   | "unbound-pr";
 
 /** A single semantic validation failure. `path` is a JSON-path-qualified pointer at the offending
@@ -377,6 +381,53 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
             code: "unsupported-on-timeout",
           });
         }
+        // S5 (ADR 0006 §3): converge/merge are first-class, edge-gated CELL POLICY, not raw nodes.
+        // A raw converge/merge agent job (`senior:converge`, `senior:merge`, or a bare `converge`/
+        // `merge` verb) is retired as user-facing vocabulary — reject it at compile so "a raw converge
+        // node is not expressible" (issue #592). The author expresses convergence/landing via the
+        // cell's `converge?`/`merge?` policy instead. `senior:trial-merge` (the merge-cell's internal
+        // trial body) and every other verb are unaffected (exact-verb match).
+        if (kind === "agent" && typeof config.jobType === "string" && isRawConvergeMergeJobType(config.jobType)) {
+          errors.push({
+            path: `${path}.${configKey}.jobType`,
+            message:
+              `raw converge/merge agent job "${config.jobType}" is not expressible — converge and merge ` +
+              "are first-class cell policy (set `agent.converge`/`agent.merge`), not a raw agent node " +
+              "(ADR 0006 §3 / S5)",
+            code: "raw-converge-node",
+          });
+        }
+        // S5 trust boundary: `validateDeliveryGraph` is the gate before `dispatchDeliveryGraphRun`
+        // narrows `graph: unknown` with `as DeliveryGraph`, so a graph that bypassed OpenAPI validation
+        // must not smuggle a non-boolean `converge`/`merge` past the policy checks below (which compare
+        // `=== true`). A truthy `"true"`/`1` would otherwise silently evade merge-requires-converge and
+        // the S5 cell policy. Reject any present-but-non-boolean value path-qualified.
+        if (kind === "agent") {
+          for (const flag of NODE_COMPLETION_POLICIES) {
+            const value = config[flag];
+            if (value !== undefined && typeof value !== "boolean") {
+              errors.push({
+                path: `${path}.${configKey}.${flag}`,
+                message:
+                  `\`agent.${flag}\`, when present, must be a boolean — got ${JSON.stringify(value)} ` +
+                  "(the S5 cell policy is edge-gated on strict `true`/`false`, not a truthy value)",
+                code: "converge-merge-type",
+              });
+            }
+          }
+        }
+        // S5 edge-gate: `merge` presupposes `converge`. Landing a PR you have not driven to green is
+        // incoherent (the two are separable phases, but merge REQUIRES converge). Reject `merge: true`
+        // without `converge: true` so the enforced policy can't express "land without converging".
+        if (kind === "agent" && config.merge === true && config.converge !== true) {
+          errors.push({
+            path: `${path}.${configKey}.merge`,
+            message:
+              "`agent.merge` requires `agent.converge` — a PR cannot be landed before it is driven to " +
+              "green (ADR 0006 §3 two separable-but-ordered phases / S5)",
+            code: "merge-requires-converge",
+          });
+        }
         // #548: register a converge-connector / pr-wait as a PR-binding consumer (pass 4 validates the
         // binding once edges are resolved). Only when the id is usable so pass 4 can key by node id.
         if (typeof id === "string" && id.length > 0) {

package/app/nodePolicy.test.ts

@@ -0,0 +1,84 @@
+// Unit coverage for the pure node completion-policy vocabulary `app/nodePolicy.ts` (ADR 0006 §3,
+// slice S5). Exercises the two ideas S5 promotes to first-class, enforced policy — with no engine and
+// no side effects:
+//   • the RAW converge/merge retirement predicate (`isRawConvergeMergeJobType`) that makes "a raw
+//     converge node not expressible" (issue #592 acceptance #1) while leaving every legitimate verb —
+//     crucially `senior:trial-merge`, the merge-cell's own internal body — untouched, and
+//   • the TWO-LEVEL merge mapping (`mergeLevelForTarget` / `mergeBranchForLevel`): a unit lands onto
+//     its base branch, the graph lands onto `main`, and a unit can NEVER silently collapse onto `main`
+//     (issue #592 acceptance #2, ADR 0003 base-branch admission).
+import { test } from "node:test";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+import { CONVERGE_MERGE_TARGET, CONVERGE_TARGET, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
+import {
+  GRAPH_MERGE_BRANCH,
+  isRawConvergeMergeJobType,
+  jobTypeVerb,
+  MERGE_LEVEL_TARGET,
+  mergeBranchForLevel,
+  mergeLevelForTarget,
+  NODE_COMPLETION_POLICIES,
+  RAW_CONVERGE_MERGE_VERBS,
+} from "./nodePolicy.ts";
+
+test("RAW_CONVERGE_MERGE_VERBS is derived from NODE_COMPLETION_POLICIES (single source of truth, no drift)", () => {
+  assertEquals([...RAW_CONVERGE_MERGE_VERBS], [...NODE_COMPLETION_POLICIES]);
+});
+
+test("jobTypeVerb extracts the task verb after the last colon, trimmed + lower-cased", () => {
+  assertEquals(jobTypeVerb("senior:feature"), "feature");
+  assertEquals(jobTypeVerb("senior:trial-merge"), "trial-merge");
+  assertEquals(jobTypeVerb("converge"), "converge");
+  assertEquals(jobTypeVerb("staff:Merge"), "merge");
+  assertEquals(jobTypeVerb("a:b:merge "), "merge");
+});
+
+test("isRawConvergeMergeJobType retires raw converge/merge agent jobs (any rank, bare, mixed case)", () => {
+  assert(isRawConvergeMergeJobType("senior:converge"));
+  assert(isRawConvergeMergeJobType("senior:merge"));
+  assert(isRawConvergeMergeJobType("converge"));
+  assert(isRawConvergeMergeJobType("merge"));
+  assert(isRawConvergeMergeJobType("staff:Merge"));
+});
+
+test("isRawConvergeMergeJobType leaves legitimate verbs untouched (exact-verb match, not substring)", () => {
+  // `senior:trial-merge` is the merge-cell's own internal trial body — it must NOT be swept up.
+  assert(!isRawConvergeMergeJobType("senior:trial-merge"));
+  assert(!isRawConvergeMergeJobType("senior:feature"));
+  assert(!isRawConvergeMergeJobType("senior:fix"));
+  assert(!isRawConvergeMergeJobType("j"));
+  assert(!isRawConvergeMergeJobType("merge-cell"));
+});
+
+test("MERGE_LEVEL_TARGET pairs each level with its converge-enrollment target", () => {
+  assertEquals(MERGE_LEVEL_TARGET.unit, CONVERGE_MERGE_TARGET);
+  assertEquals(MERGE_LEVEL_TARGET.graph, MERGE_MAIN_TARGET);
+});
+
+test("mergeLevelForTarget maps the two-level merge targets, null for non-landing/other targets", () => {
+  assertEquals(mergeLevelForTarget(CONVERGE_MERGE_TARGET), "unit");
+  assertEquals(mergeLevelForTarget(MERGE_MAIN_TARGET), "graph");
+  // `converge` is review-only (non-landing) → not a merge level.
+  assertEquals(mergeLevelForTarget(CONVERGE_TARGET), null);
+  assertEquals(mergeLevelForTarget("slack:#x"), null);
+});
+
+test("mergeBranchForLevel: two-level merge — unit lands on its base branch, graph lands on main", () => {
+  assertEquals(mergeBranchForLevel("unit", { baseBranch: "epic/some-epic" }), "epic/some-epic");
+  assertEquals(mergeBranchForLevel("graph", { baseBranch: "epic/some-epic" }), GRAPH_MERGE_BRANCH);
+  assertEquals(GRAPH_MERGE_BRANCH, "main");
+  // The graph level ignores any supplied base — it ALWAYS targets main.
+  assertEquals(mergeBranchForLevel("graph", { baseBranch: null }), "main");
+});
+
+test("mergeBranchForLevel: a unit can NEVER silently collapse onto main — missing base throws", () => {
+  assertThrows(() => mergeBranchForLevel("unit", { baseBranch: null }));
+  assertThrows(() => mergeBranchForLevel("unit", { baseBranch: "   " }));
+  assertThrows(() => mergeBranchForLevel("unit", {}));
+});
+
+test("mergeBranchForLevel: a unit can NEVER target main directly — explicit main base throws", () => {
+  assertThrows(() => mergeBranchForLevel("unit", { baseBranch: "main" }));
+  assertThrows(() => mergeBranchForLevel("unit", { baseBranch: "  main  " }));
+  assertThrows(() => mergeBranchForLevel("unit", { baseBranch: GRAPH_MERGE_BRANCH }));
+});

package/app/nodePolicy.ts

@@ -0,0 +1,113 @@
+// nano-workforce — the first-class NODE COMPLETION-POLICY vocabulary for an agent-authored delivery
+// graph (ADR 0006 §3, slice S5). The pure, dependency-free source of truth for two ideas the ADR
+// promotes from EMERGENT behaviour / smuggled prompt prose to explicit, EDGE-GATED, compiler-enforced
+// policy:
+//
+//   1. `converge?` / `merge?` are first-class completion-policy FLAGS on a cell (`agent`) node, NOT
+//      raw nodes. "get to green, then land" used to live in a gateway inside `feature.bpmn`
+//      (`gw-converge` + the `autoMerge` boolean) and, for a delivery-graph `agent` node, in FREE TEXT
+//      in a prompt ("un-draft + merge #B"). This module gives the validator/compiler the predicate
+//      that RETIRES a raw converge/merge agent job (`senior:converge`, `senior:merge`) — converge and
+//      merge survive only as the `converge`/`merge` policy on a cell, so "a raw converge node is not
+//      expressible in the authored vocabulary" (issue #592 acceptance #1).
+//
+//   2. `merge` is TWO-LEVEL (ADR 0003 base-branch admission, ADR 0006 §3): a UNIT's merge lands onto
+//      its epic/graph BASE branch, never `main` directly; the GRAPH's final merge-to-`main` is a
+//      separate top-level step. This module maps each level to its converge-enrollment target
+//      (`converge-merge` = unit → base, `merge-main` = graph → main) and resolves the branch a level
+//      lands on, so the two levels are authored/enforced explicitly rather than collapsed.
+//
+// Kept import-light (only the dependency-free `convergeTargets.ts` literals) so the pure semantic
+// validator (`deliveryGraph.ts`) can share these predicates WITHOUT pulling in the connector module's
+// urban/data-layer deps.
+
+import { CONVERGE_MERGE_TARGET, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
+
+/** The first-class node completion-policy flags a cell (`agent`) node may carry (ADR 0006 §3). Both
+ * are separable phases: `converge` drives the PR through its review-convergence loop to green;
+ * `merge` lands it. Kept as the single source of truth so the validator, the openapi shape, and any
+ * future compiler agree on the closed policy set. */
+export const NODE_COMPLETION_POLICIES = ["converge", "merge"] as const;
+
+/** A node completion policy, narrowed to the closed set. */
+export type NodeCompletionPolicy = (typeof NODE_COMPLETION_POLICIES)[number];
+
+/** The reserved task VERBS that name a converge/merge phase. An `agent` node's `jobType` is
+ * `<rank>:<task>` (e.g. `senior:feature`), or a bare `<task>`; its task verb is the segment after the
+ * last `:`. A jobType whose verb is exactly `converge` or `merge` is a RAW converge/merge node — the
+ * exact thing S5 retires: converge/merge are cell POLICY (`converge?`/`merge?`), never a raw agent
+ * job. Matched by exact verb equality (case-insensitive) so a legitimately-different verb that merely
+ * CONTAINS the word — e.g. `senior:trial-merge` (verb `trial-merge`), the real merge-cell body — is
+ * NOT swept up. Derived from {@link NODE_COMPLETION_POLICIES} so the reserved-verb vocabulary and the
+ * cell policy set cannot drift (they are the same closed set, seen from two angles). */
+export const RAW_CONVERGE_MERGE_VERBS: readonly string[] = NODE_COMPLETION_POLICIES;
+
+/** Extract the task verb from an agent `jobType`: the segment after the LAST `:` (`senior:feature` →
+ * `feature`), or the whole string when unqualified. Trimmed and lower-cased for a stable compare. */
+export function jobTypeVerb(jobType: string): string {
+  const colon = jobType.lastIndexOf(":");
+  const verb = colon >= 0 ? jobType.slice(colon + 1) : jobType;
+  return verb.trim().toLowerCase();
+}
+
+/** True when `jobType` names a RAW converge/merge node — an agent job whose task verb is exactly
+ * `converge` or `merge`. These are retired as user-facing vocabulary (issue #592): the author must
+ * express convergence/landing via the cell's first-class `converge?` / `merge?` policy, not a raw
+ * agent job. `senior:trial-merge` (the merge-cell's internal trial body) and every non-converge verb
+ * are unaffected. */
+export function isRawConvergeMergeJobType(jobType: string): boolean {
+  const verb = jobTypeVerb(jobType);
+  for (const raw of RAW_CONVERGE_MERGE_VERBS) if (raw === verb) return true;
+  return false;
+}
+
+/** The two levels a `merge` lands at (ADR 0006 §3 two-level merge). `unit` = a delivery UNIT (a
+ * feature/slice PR) landing onto its epic/graph base branch; `graph` = the top-of-graph integration
+ * landing onto `main`. */
+export const MERGE_LEVELS = ["unit", "graph"] as const;
+
+/** A merge level, narrowed to the closed set. */
+export type MergeLevel = (typeof MERGE_LEVELS)[number];
+
+/** The converge-enrollment connector target each merge level dispatches through: a UNIT merge lands
+ * via `converge-merge` (onto its own base branch), the GRAPH's top-level merge via `merge-main` (onto
+ * `main`). The single source of truth pairing the two-level policy with the connector vocabulary. */
+export const MERGE_LEVEL_TARGET: Record<MergeLevel, string> = {
+  unit: CONVERGE_MERGE_TARGET,
+  graph: MERGE_MAIN_TARGET,
+};
+
+/** Reverse of {@link MERGE_LEVEL_TARGET}: the merge level a converge-enrollment `target` names, or
+ * `null` when the target is not a two-level merge target (`converge` is review-only, non-landing).
+ * Lets the validator/compiler decide which branch a merge cell lands on from the authored target. */
+export function mergeLevelForTarget(target: string): MergeLevel | null {
+  if (target === CONVERGE_MERGE_TARGET) return "unit";
+  if (target === MERGE_MAIN_TARGET) return "graph";
+  return null;
+}
+
+/** Resolve the branch a merge LEVEL lands on (ADR 0003 base-branch admission). A `unit` merge lands on
+ * the supplied `baseBranch` (the epic/graph integration branch the unit PR targets); a `graph` merge
+ * lands on `main`. The two-level invariant in one place: a unit NEVER lands on `main` directly, and
+ * the graph's top-level merge ALWAYS targets `main`. `baseBranch` is required for a unit level (its
+ * whole point is "not main"); an absent/empty base for a unit — or an explicit `main` base — is a
+ * caller error surfaced as a throw so a unit can never silently collapse onto `main`. */
+export const GRAPH_MERGE_BRANCH = "main";
+
+export function mergeBranchForLevel(level: MergeLevel, opts: { baseBranch?: string | null }): string {
+  if (level === "graph") return GRAPH_MERGE_BRANCH;
+  const base = opts.baseBranch?.trim();
+  if (!base) {
+    throw new Error(
+      "unit-level merge requires a base branch (ADR 0003 two-level merge: a unit lands onto its " +
+        "epic/graph base branch, never `main` directly)",
+    );
+  }
+  if (base === GRAPH_MERGE_BRANCH) {
+    throw new Error(
+      "unit-level merge must not target `main` directly (ADR 0003 two-level merge: a unit lands onto " +
+        "its epic/graph base branch; the graph's top-level `merge-main` is the only path to `main`)",
+    );
+  }
+  return base;
+}

package/docs/agent-guide.md

@@ -438,10 +438,10 @@ layer schedules, it does not re-implement execution):
 
 | kind | config | what it does | may `emits`? |
 |---|---|---|---|
-| `agent` | `agent: { jobType, prompt? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** | yes |
+| `agent` | `agent: { jobType, prompt?, converge?, merge? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. | yes |
 | `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Two **real targets** ship today — **`converge`** and **`converge-merge`** (§9.4); other targets are a forward-declared stub. | yes |
+| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. | yes |
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
@@ -578,7 +578,7 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
       "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } },
     { "id": "undraft-merge-b", "kind": "agent",
-      "agent": { "jobType": "senior:merge", "prompt": "Take draft PR acme/repo-2#202 out of draft and merge it once its required checks are green." } },
+      "agent": { "jobType": "senior:feature", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
     { "id": "manual-publish", "kind": "human",
       "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
       "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
@@ -621,19 +621,31 @@ the consumer a `wait` node with `kind: "capability"` (resolving *which published
 `pkg@version` first carries the change*) fed by the same `manual-publish.publishedVersion`
 fact — the fact-edge syntax is identical.
 
-### 9.4 Connector targets — drive a PR to convergence + merge (`converge` / `converge-merge`)
+### 9.4 Connector targets — drive a PR to convergence + merge (`converge` / `converge-merge` / `merge-main`)
 
-A `connector` node with **`target: "converge-merge"`** (or **`"converge"`**) enrolls an
-agent-opened PR into the app's **shared convergence loop** — the *same* enrollment §1 (a
+A `connector` node with **`target: "converge-merge"`** (or **`"converge"`** / **`"merge-main"`**)
+enrolls an agent-opened PR into the app's **shared convergence loop** — the *same* enrollment §1 (a
 standalone submit) and a feature run use (`submitPr`), no duplicated machinery. This replaces
 the old habit of bridging an `agent`-opened PR to review with a **human `land-*` gate** whose
 only job was "go run convergence yourself".
 
-- **`converge-merge`** — drive review convergence **and then the merge loop** (the PR merges
-  once converged + green). Equivalent to a submit with `convergeOnly: false`.
+- **`converge-merge`** — the **unit-level** land: drive review convergence **and then the merge
+  loop**, landing the PR onto **its own base branch** (for a unit inside an epic that base is the
+  epic integration branch, never `main` directly — ADR 0003 base-branch admission). Equivalent to a
+  submit with `convergeOnly: false`.
+- **`merge-main`** — the **graph-level** top-level land: the second level of the two-level merge
+  (ADR 0006 §3), landing the graph/epic **integration** PR onto **`main`**. Dispatch-identical to
+  `converge-merge` (both enroll + merge); the distinction is the *level*, kept a first-class literal
+  so the two levels are authored explicitly rather than left emergent.
 - **`converge`** — **converge-only**: drive review convergence and stop at `converged`, never
   handing off to the merge loop (equivalent to `convergeOnly: true`).
 
+> **converge/merge are cell POLICY, not raw nodes.** A raw `senior:converge` / `senior:merge`
+> **agent** job is **not expressible** — the compiler rejects it (`raw-converge-node`). Express
+> "get to green, then land" via a cell node's first-class **`agent.converge` / `agent.merge`**
+> policy flags (`merge` requires `converge`), or, for enrolling an already-open PR, the
+> `connector` targets above (ADR 0006 §3 / S5).
+
 **Payload:** `{ pr: "owner/repo#123", convergeOnly?: boolean, dependsOn?: string[] }`. `pr` is
 required (a literal `owner/repo#N`, identical to how a `wait: pr` node targets a known PR).
 `convergeOnly` defaults from the target and may be overridden per-node; `dependsOn` is unioned

package/openapi.yaml

@@ -1430,6 +1430,29 @@ components:
                   type: string
                   maxLength: 20000
                   description: OPTIONAL steering prompt appended to the node's job brief.
+                converge:
+                  type: boolean
+                  description: >-
+                    OPTIONAL first-class CONVERGE policy (ADR 0006 §3 / S5) — a DECLARED, compiler-
+                    validated completion-policy flag on this cell node. It declares that the node's
+                    opened PR is to be driven through the review-convergence loop to green as an
+                    edge-gated completion policy; this slice adds and validates the flag, with the
+                    delivery-graph execution wiring that consumes it landing in a follow-up slice.
+                    It supersedes (in intent) the emergent `feature.bpmn` `gw-converge` gateway and
+                    the "un-draft + merge #B" prompt prose a delivery-graph `agent` node used to
+                    smuggle. Converge and merge are SEPARABLE phases; a node may converge without
+                    merging (stop at green and gate the landing behind a downstream node).
+                merge:
+                  type: boolean
+                  description: >-
+                    OPTIONAL first-class MERGE (land) policy (ADR 0006 §3 / S5) — a DECLARED,
+                    compiler-validated flag. When set it declares that the cell lands its PR.
+                    REQUIRES `converge: true` — you cannot land a PR you have not driven to green
+                    (the validator rejects `merge` without `converge`). This slice adds and validates
+                    the flag; the execution wiring that consumes it lands in a follow-up slice.
+                    TWO-LEVEL (ADR 0003 base-branch admission): a UNIT node lands onto its epic/graph
+                    base branch, never `main` directly; the graph's final merge-to-`main` is a
+                    separate top-level step.
                 timeout:
                   type: string
                   pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'

package/operations/getAgentInstructions.test.ts

@@ -60,7 +60,7 @@ test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
   // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
   // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
-  assert(md.includes("agent: { jobType, prompt? }"), "documents the agent node config");
+  assert(md.includes("agent: { jobType, prompt?, converge?, merge? }"), "documents the agent node config");
   assert(md.includes("wait: <ReadinessProbe>"), "documents the wait node config");
   assert(md.includes("human?: { formKey?, prompt? }"), "documents the human node config");
   assert(md.includes("connector: { target, dedupeKey?, payload? }"), "documents the connector node config");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.157.0",
+  "version": "0.158.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/workers/delivery-connector/worker.test.ts

@@ -132,6 +132,17 @@ test("readConvergeInput: parses pr; convergeOnly defaults from the target; depen
   assertEquals(conv.convergeOnly, true);
 });
 
+test("readConvergeInput: `merge-main` (graph-level two-level merge, S5) parses pr and defaults convergeOnly false", () => {
+  // The graph-level top-level enrollment target drives the merge loop like `converge-merge`,
+  // so its worker-level `readConvergeInput` default must also be `convergeOnly=false`.
+  const mm = readConvergeInput("merge-main", { pr: "owner/repo#7" }, null);
+  assertEquals(mm.parsed.prKey, "owner/repo#7");
+  assertEquals(mm.convergeOnly, false);
+  assertEquals(mm.dependsOn, []);
+  // An explicit payload override still wins over the target default.
+  assertEquals(readConvergeInput("merge-main", { pr: "owner/repo#7", convergeOnly: true }, null).convergeOnly, true);
+});
+
 test("readConvergeInput: an explicit payload.convergeOnly overrides the target default; dependsOn threads through", () => {
   const r = readConvergeInput("converge-merge", { pr: "owner/repo#7", convergeOnly: true, dependsOn: ["owner/repo#5", 42] as unknown as string[] }, null);
   assertEquals(r.convergeOnly, true, "the explicit boolean wins over the target default");

package/workers/delivery-connector/worker.ts

@@ -77,9 +77,9 @@ export function safeStringify(value: unknown): string {
 }
 
 /** Parse + validate the converge connector's payload (`{ pr, convergeOnly?, dependsOn? }`) for a
- * `converge` / `converge-merge` target. `pr` is REQUIRED and must parse to a canonical `owner/repo#N`
+ * `converge` / `converge-merge` / `merge-main` target. `pr` is REQUIRED and must parse to a canonical `owner/repo#N`
  * (fail CLOSED — a converge connector with no target PR is meaningless and could never enroll).
- * `convergeOnly` DEFAULTS from the target (`converge` → review-only `true`; `converge-merge` → drive
+ * `convergeOnly` DEFAULTS from the target (`converge` → review-only `true`; `converge-merge`/`merge-main` → drive
  * the merge loop `false`) and may be overridden per-dispatch by an explicit boolean. `dependsOn` is an
  * optional list of PR refs unioned into the enrolled PR's merge-stage dependency set (only non-string
  * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage.