@nanobpm/nano-workforce 0.161.0 → 0.162.1

package/docs/agent-guide.md

@@ -326,7 +326,7 @@ both live in the source repo, not in the job payload.
   prompt-modularity path:
 
   ```xml
-  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
+  <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>
   ```
 
   that the engine
@@ -706,6 +706,17 @@ ways to name the target PR:
 `senior:feature` already returns the PR it opened, so declaring `emits: [{ "name": "pr", "type": "pr" }]`
 on the agent node is all it takes to publish it (issue #548).
 
+> **Don't hand-author this shape — generate it.** When your intent is simply "sequence these
+> issues, each implemented → converged → merged (optionally behind a gate)", call the
+> **`sequenceIssues`** door instead of assembling the nodes/edges by hand. Its body is the intent
+> `{ "issues": ["owner/repo#A", "owner/repo#B", …] }` with an optional leading `"behind": "owner/repo#NN"`
+> gate, and it GENERATES
+> exactly the canonical chain above — for each issue `agent` (`senior:feature`, emits `pr`) →
+> `connector[converge-merge]` → `wait[pr, merged]` with a realistic `poll.timeoutMs`, threading the
+> `pr` fact, plus an optional leading `wait[epic]` gate (§9.5) when `behind` is given — then STAGES it
+> through the same compile+stage path as `compileDeliveryGraph` (it never dispatches). The issues run
+> in **sequence**: each issue's implementation starts once the prior issue has merged.
+
 ### 9.5 Gate a graph on an epic reaching "fully merged" (`wait[epic]`)
 
 Sometimes the thing you must wait for is not one PR but a **whole epic** — an nwf

package/e2e/sequenceIssues.e2e.ts

@@ -0,0 +1,94 @@
+// `sequenceIssues` intent-door regression net (epic #605 slice S4, issue #610).
+//
+// PINS the acceptance guarantees over the REAL runtime-served `/app/mcp` surface:
+//   • the door is PROJECTED as an MCP tool whose input schema is self-contained ($ref-free, explicit
+//     type) — an agent can discover + call it from a standard client (S0 invariant);
+//   • an object-body intent arrives AS AN OBJECT (not stringified), stages a delivery graph, and the
+//     staged digest is immediately visible via `listStagedProposals` (compile+stage reuse, S2);
+//   • the response carries NO dispatch handle — the door STAGES, never dispatches (operator-only);
+//   • invalid input (empty `issues`, an unparseable ref) is rejected with `issues[{path,message}]`.
+//
+// It is RUNNABLE VIA THE SLICE S1 HARNESS (`e2e/support/mcp-harness.ts`): it imports `bootMcpHarness`
+// and the shared assertion helpers and drives the exact client handshake an agent uses — it does NOT
+// re-implement the transport (see the harness module header's EXTENSION SEAM).
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+  assertObjectBodyAccepted,
+  assertSchemaSelfContained,
+  assertValidationIssues,
+  bootMcpHarness,
+  type McpHarness,
+} from "./support/mcp-harness.ts";
+
+const TOOL = "sequenceIssues";
+
+interface ListBody { count: number; proposals: Array<{ digest: string; title: string | null }> }
+
+/** The current live staged list, read over the SAME MCP surface. */
+async function listStaged(h: McpHarness): Promise<ListBody> {
+  const res = await h.callTool("listStagedProposals", {});
+  assert.ok(!res.isError, `listStagedProposals must not error: ${res.text}`);
+  const json = res.json as ListBody | undefined;
+  assert.ok(json && Array.isArray(json.proposals), `listStagedProposals must return a proposals array: ${res.text}`);
+  return json;
+}
+
+describe("S4 — sequenceIssues generates + stages the canonical chain over MCP (#610)", () => {
+  let h: McpHarness;
+  before(async () => { h = await bootMcpHarness(); });
+  after(async () => { await h.stop(); });
+
+  test("the tool is projected with a self-contained ($ref-free, typed) input schema", async () => {
+    const tools = await h.listTools();
+    const tool = tools.find((t) => t.name === TOOL);
+    assert.ok(tool, `${TOOL} must be projected onto the MCP surface`);
+    assertSchemaSelfContained(tool.inputSchema, TOOL);
+    // Dispatch is operator-only — the dispatch door must NOT be projected.
+    assert.ok(!tools.some((t) => t.name === "dispatchDeliveryGraph"), "dispatch stays off the agent surface");
+  });
+
+  test("a valid intent object stages the canonical graph — the staged digest is immediately listed", async () => {
+    const res = await h.callTool(TOOL, {
+      body: { behind: "acme/repo#100", issues: ["acme/repo#1", "acme/repo#2", "acme/repo#3"] },
+    });
+    assertObjectBodyAccepted(res, TOOL); // the object argument arrived as an object, not a string
+    assert.ok(!res.isError, `${TOOL} must stage a valid intent: ${res.text}`);
+    const json = res.json as { status?: string; digest?: string; preview?: unknown } | undefined;
+    assert.equal(json?.status, "ready", `${TOOL} must report status:"ready": ${res.text}`);
+    assert.ok(typeof json?.digest === "string" && json.digest.length > 0, `a staged digest is required: ${res.text}`);
+    assert.ok(json?.preview && typeof json.preview === "object", `a preview is required: ${res.text}`);
+
+    // Read-after-write: the staged digest is visible immediately (shared compile+stage path, S2).
+    const list = await listStaged(h);
+    assert.ok(
+      list.proposals.some((p) => p.digest === json.digest),
+      `the staged digest ${json.digest} must appear in listStagedProposals immediately (got ${JSON.stringify(list.proposals.map((p) => p.digest))})`,
+    );
+
+    // The door STAGES, never dispatches — no run handle in the response.
+    for (const forbidden of ["runKey", "token", "approvalToken", "processInstanceKey", "processKey", "dispatchUrl"]) {
+      assert.ok(!(forbidden in (json as Record<string, unknown>)), `response must not carry a dispatch handle (${forbidden})`);
+    }
+  });
+
+  test("empty issues is rejected with the uniform issues[{path,message}] contract — nothing staged", async () => {
+    const before = (await listStaged(h)).proposals.length;
+    const res = await h.callTool(TOOL, { body: { issues: [] } });
+    // A tool-level door 4xx: the object arrived (not stringified) AND carries issues[{path,message}].
+    assertValidationIssues(res, TOOL);
+    assert.equal((await listStaged(h)).proposals.length, before, "a rejected intent must stage nothing");
+  });
+
+  test("an unparseable issue ref is rejected at the offending path", async () => {
+    const res = await h.callTool(TOOL, { body: { issues: ["acme/repo#1", "not-an-issue"] } });
+    assertValidationIssues(res, TOOL);
+    const json = res.json as { issues?: Array<{ path?: string }> };
+    assert.ok(
+      json.issues?.some((i) => i.path === "issues[1]"),
+      `the offending index must be path-qualified (got ${JSON.stringify(json.issues)})`,
+    );
+  });
+});

package/openapi.yaml

@@ -2460,6 +2460,71 @@ components:
           description: >-
             A NAVIGATIONAL cockpit deep-link to the staged proposal (helps the agent hand the human a
             link). It is a pointer only — NOT a dispatch handle; nothing in this response can start a run.
+    SequenceIssuesIntent:
+      description: >-
+        The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES
+        the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead
+        of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to
+        sequence (each issue's implementation starts once the PRIOR issue has merged) and an OPTIONAL
+        leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The
+        door GENERATES, then STAGES the graph through the same compile+stage flow as
+        `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR
+        0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) →
+        `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
+        `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an
+        unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.
+      type: object
+      additionalProperties: false
+      example:
+        behind: nanobpm/nano-ide#488
+        issues:
+          - nanobpm/nano-workforce#567
+          - nanobpm/nano-workforce#568
+      required:
+        - issues
+      properties:
+        behind:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: >-
+            OPTIONAL gate — an `owner/repo#NN` issue/epic/feature reference. When present, a leading
+            `wait[epic]` node gates the whole sequence on that reference reaching "fully merged" (every
+            opened slice/PR landed, §9.5) before the first issue's implementation starts.
+        issues:
+          type: array
+          minItems: 1
+          maxItems: 64
+          items:
+            type: string
+            minLength: 1
+            maxLength: 255
+            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+          description: >-
+            The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens
+            a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once
+            the prior issue has merged. At least one; at most 64 (keeps the generated graph within the
+            compiler's node ceiling).
+    SequenceIssuesRejected:
+      description: >-
+        A rejected `sequenceIssues` intent — the input failed validation (empty/oversized `issues`, an
+        unparseable `owner/repo#N` reference, or an unknown target/probe per the delivery-graph
+        vocabulary). Every failure is path-qualified so the caller can fix the exact offending input.
+        Nothing was generated or staged.
+      type: object
+      additionalProperties: false
+      required:
+        - error
+        - issues
+      properties:
+        error:
+          type: string
+          description: A human-readable summary of why the intent was rejected.
+        issues:
+          type: array
+          items:
+            $ref: "#/components/schemas/DeliveryCompileError"
+          description: The path-qualified validation failures (at least one).
     FeatureStart:
       description: The start-feature request body — a SINGLE-issue feature run. Names the target issue
         by EXACTLY ONE of `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a
@@ -3492,6 +3557,83 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/start/sequence-issues:
+    post:
+      operationId: sequenceIssues
+      summary: Generate + STAGE the canonical "implement issue → converge → merge" delivery graph from a high-level intent (never dispatches). (epic #605 / S4)
+      description: >-
+        An INTENT-SHAPED door (epic nano-workforce#605, S4). ADR 0005's delivery graph is a closed
+        vocabulary and operator-guide §9.4 already names the canonical shape for "implement issue →
+        converge → merge", but an agent still had to hand-author the full node/edge JSON — sequencing
+        four issues behind a gate meant constructing 13 nodes and 12 edges by hand. This door takes the
+        high-level intent `{ behind?, issues[] }` and GENERATES that canonical graph, then STAGES it
+        through the SAME compile+stage flow the raw `compileDeliveryGraph` door uses (one compiler, one
+        staging path — idempotency + digest inherited, not re-implemented). It returns a preview and a
+        navigational `reviewUrl` and NOTHING that can trigger a run: dispatch is an OPERATOR action in
+        the cockpit (ADR 0005 Decision 7 / issue #460).
+
+
+        For each issue it emits the canonical chain — `agent` (`senior:feature`, emits a typed `pr`
+        fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
+        `poll.timeoutMs`) — and threads the `pr` fact along fact-qualified edges (§9.4). The issues run
+        in SEQUENCE: each issue's implementation starts once the PRIOR issue has merged. When `behind`
+        is given, a leading `wait[epic]` gate (§9.5) makes the whole sequence wait for that reference to
+        be fully merged first.
+
+
+        INPUT — the intent OBJECT `{ "issues": ["owner/repo#A", …] }` with an OPTIONAL
+        `"behind": "owner/repo#NN"` gate (this is the object-body door). SIDE EFFECTS — impure: a valid intent is STAGED as a proposal.
+        IDEMPOTENCY — content-addressed by the compiled `digest` (an identical intent re-stages the same
+        digest). VALIDATION — invalid input (empty `issues`, an unparseable `owner/repo#N` reference, an
+        unknown target/probe per the S3 vocabulary) is a `400` with `issues: [{ path, message }]`;
+        nothing is staged. NEXT — surface the returned `reviewUrl` to the operator; poll
+        `listStagedProposals` to see the staged digest.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              # BEGIN generated:mcp-body source=#/components/schemas/SequenceIssuesIntent (scripts/inline-mcp-bodies.ts — do not hand-edit)
+              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
+              type: object
+              additionalProperties: false
+              example:
+                behind: nanobpm/nano-ide#488
+                issues:
+                  - nanobpm/nano-workforce#567
+                  - nanobpm/nano-workforce#568
+              required:
+                - issues
+              properties:
+                behind:
+                  type: string
+                  minLength: 1
+                  maxLength: 255
+                  description: OPTIONAL gate — an `owner/repo#NN` issue/epic/feature reference. When present, a leading `wait[epic]` node gates the whole sequence on that reference reaching "fully merged" (every opened slice/PR landed, §9.5) before the first issue's implementation starts.
+                issues:
+                  type: array
+                  minItems: 1
+                  maxItems: 64
+                  items:
+                    type: string
+                    minLength: 1
+                    maxLength: 255
+                    description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+                  description: The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged. At least one; at most 64 (keeps the generated graph within the compiler's node ceiling).
+              # END generated:mcp-body
+      responses:
+        "200":
+          description: The intent generated a valid delivery graph — it compiled and is STAGED for operator review; the response carries a preview and a navigational reviewUrl (no dispatch handle).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileDeliveryGraphStaged"
+        "400":
+          description: The intent was invalid (empty/oversized issues, an unparseable reference, or an unknown target/probe) — path-qualified issues, nothing generated or staged.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SequenceIssuesRejected"
   /actions/compile-delivery-graph:
     post:
       operationId: compileDeliveryGraph

package/operations/compileDeliveryGraph.ts

@@ -12,74 +12,36 @@
 // cockpit; the response tells the agent its role ends here, turning the boundary into a self-documenting
 // protocol. A malformed graph is a 400 carrying path-qualified errors; nothing is staged.
 
-import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
-import {
-  buildProposalPreview,
-  buildProposalRow,
-  proposalLogicalKey,
-  proposalReviewUrl,
-  stageProposal,
-} from "../app/deliveryGraphProposals.ts";
-import { deliveryGraphDigest } from "../app/deliveryRunner.ts";
+import { compileAndStageDeliveryGraph } from "../app/deliveryGraphStage.ts";
 import { resolvePublicOrigin } from "../app/resolveApiBase.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
-const STAGED_MESSAGE =
-  "The graph compiled and is staged for operator review. Ask the operator to preview and approve — or request modifications — in the cockpit. Dispatch is an operator action; there is no start endpoint.";
-
 export default defineOperation("compileDeliveryGraph", async ({ body, req }, app) => {
-  // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the compiler adds
-  // the SEMANTIC checks (acyclicity, edge integrity, fact resolution). A directly-invoked delegate
-  // could still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
-  // `ok:false`, never a 500.
-  const result = await compileDeliveryGraph(body);
-  if (!result.ok) {
-    app.log.warn("compile-delivery-graph rejected", { errors: result.errors.length });
-    return { status: 400, body: result };
-  }
-
-  // Persist the compiled graph as a `staged` proposal — the agent's surface ends here. Superseded by
-  // logical key + TTL inside `stageProposal`.
-  const digest = deliveryGraphDigest(result.bpmn);
-  const name =
-    typeof result.resolved.name === "string" && result.resolved.name.trim() !== ""
-      ? result.resolved.name.trim()
-      : null;
-  const preview = buildProposalPreview(result);
-  await stageProposal(
+  // The runtime validates the body's SHAPE against `DeliveryGraph` before we run; the shared
+  // compile+stage flow adds the SEMANTIC checks (acyclicity, edge integrity, fact resolution) and,
+  // when valid, persists the compiled graph as a `staged` proposal. A directly-invoked delegate could
+  // still pass `undefined` — the compiler reads its input as `unknown` and maps that to a clean
+  // `ok:false`, never a 500. The navigational `reviewUrl` is keyed to the ORIGIN this request arrived
+  // on (tunnel, proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the
+  // operator driving this instance can actually open it (#577).
+  const staged = await compileAndStageDeliveryGraph(
     app.data,
-    buildProposalRow({
-      digest,
-      logicalKey: proposalLogicalKey(name, digest),
-      title: name,
-      graphJson: JSON.stringify(body),
-      preview,
-      nodeCount: result.resolved.nodes.length,
-      humanNodeCount: result.humanNodes.length,
-      sideEffectCount: result.sideEffects.length,
-      sideEffecting: result.sideEffects.length > 0,
-    }),
+    body,
+    JSON.stringify(body),
+    resolvePublicOrigin(req),
   );
+  if (!staged.ok) {
+    app.log.warn("compile-delivery-graph rejected", { errors: staged.body.errors.length });
+    return { status: 400, body: staged.body };
+  }
 
   app.log.info("compile-delivery-graph staged", {
-    digest,
-    nodes: result.resolved.nodes.length,
-    humanNodes: result.humanNodes.length,
-    sideEffects: result.sideEffects.length,
+    digest: staged.digest,
+    nodes: staged.nodeCount,
+    humanNodes: staged.humanNodeCount,
+    sideEffects: staged.sideEffectCount,
   });
 
   // The response carries a preview + a navigational pointer and NO dispatch handle (issue #460).
-  return {
-    status: 200,
-    body: {
-      status: "ready",
-      message: STAGED_MESSAGE,
-      digest,
-      preview,
-      // Navigational, human-facing link → keyed to the ORIGIN this request arrived on (tunnel,
-      // proxy prefix, …), not the static deployment-wide NANO_WORKFORCE_BASE_URL, so the operator
-      // driving this instance can actually open it (#577).
-      reviewUrl: proposalReviewUrl(digest, resolvePublicOrigin(req)),
-    },
-  };
+  return { status: staged.status, body: staged.body };
 });

package/operations/sequenceIssues.test.ts

@@ -0,0 +1,101 @@
+// Tests for the POST /app/api/actions/start/sequence-issues operation `sequenceIssues` (epic
+// nano-workforce#605, S4/#610). The intent-shaped door GENERATES the canonical delivery graph and
+// STAGES it through the SAME compile+stage flow as `compileDeliveryGraph` — the response carries only
+// a preview + a navigational `reviewUrl` (no dispatch handle); dispatch stays an operator action.
+// Invalid input is a 400 with `issues[{path,message}]` and nothing is staged.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi, DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphProposals, listStagedProposals } from "../app/deliveryGraphProposals.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./sequenceIssues.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withApp(fn: (app: AppApi, data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-seqissues-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    const edge = { data: app.db, log: noopLog() } as unknown as AppApi;
+    await fn(edge, app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function call(app: AppApi, body: unknown, headers: Record<string, string> = {}) {
+  const req = { path: "/app/api/actions/start/sequence-issues", headers: new Headers(headers) };
+  return (await handler({ req: req as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("sequence-issues: a valid intent → 200 ready, staged as a proposal, with the preview", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { behind: "acme/repo#100", issues: ["acme/repo#1", "acme/repo#2"] });
+    assertEquals(res.status, 200);
+    assertEquals(res.body.status, "ready");
+    assert(typeof res.body.digest === "string" && res.body.digest.length > 0);
+    assert(typeof res.body.preview === "object" && res.body.preview !== null);
+    assert(typeof res.body.preview.diagram === "string" && res.body.preview.diagram.length > 0);
+    // Staged through the SAME path as compileDeliveryGraph — visible immediately (read-after-write).
+    const row = await deliveryGraphProposals(data).get(res.body.digest);
+    assert(row, "the generated graph is staged for operator dispatch");
+    assertEquals(row?.status, "staged");
+    const live = await listStagedProposals(data);
+    assert(live.some((p) => p.digest === res.body.digest), "the staged digest is listed");
+  });
+});
+
+test("sequence-issues: the response exposes NO dispatch handle — the door stages, never dispatches", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, { issues: ["acme/repo#1"] });
+    assertEquals(res.status, 200);
+    const keys = Object.keys(res.body);
+    for (const forbidden of ["runKey", "token", "approvalToken", "processInstanceKey", "processKey", "dispatchUrl"]) {
+      assert(!keys.includes(forbidden), `response must not carry a dispatch handle (${forbidden})`);
+    }
+  });
+});
+
+test("sequence-issues: an identical intent re-stages the SAME digest (idempotent), not a duplicate", async () => {
+  await withApp(async (app, data) => {
+    const a = await call(app, { issues: ["acme/repo#1", "acme/repo#2"] });
+    const b = await call(app, { issues: ["acme/repo#1", "acme/repo#2"] });
+    assertEquals(a.body.digest, b.body.digest);
+    const live = await listStagedProposals(data);
+    assertEquals(live.filter((p) => p.digest === a.body.digest).length, 1);
+  });
+});
+
+test("sequence-issues: empty issues → 400 with issues[{path,message}], nothing staged", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { issues: [] });
+    assertEquals(res.status, 400);
+    assert(Array.isArray(res.body.issues) && res.body.issues.length > 0);
+    for (const iss of res.body.issues) {
+      assert(typeof iss.path === "string" && typeof iss.message === "string");
+    }
+    assertEquals((await listStagedProposals(data)).length, 0);
+  });
+});
+
+test("sequence-issues: an unparseable issue ref → 400 at the offending path, nothing staged", async () => {
+  await withApp(async (app, data) => {
+    const res = await call(app, { issues: ["acme/repo#1", "garbage"] });
+    assertEquals(res.status, 400);
+    assert(res.body.issues.some((i: any) => i.path === "issues[1]"));
+    assertEquals((await listStagedProposals(data)).length, 0);
+  });
+});
+
+test("sequence-issues: a missing body folds into the same 400 contract (not a 500)", async () => {
+  await withApp(async (app) => {
+    const res = await call(app, undefined);
+    assertEquals(res.status, 400);
+    assert(Array.isArray(res.body.issues) && res.body.issues.length > 0);
+  });
+});

package/operations/sequenceIssues.ts

@@ -0,0 +1,55 @@
+// POST /app/api/actions/start/sequence-issues → operationId `sequenceIssues` (epic
+// nano-workforce#605, S4/#610). An INTENT-SHAPED door: instead of making an agent hand-author the
+// full canonical node/edge JSON for "implement issue → converge → merge" (§9.4 — 13 nodes + 12 edges
+// for four gated issues, in the evidence session), it takes the high-level intent
+// `{ behind?, issues[] }` and GENERATES that canonical delivery graph, then hands it to the SAME
+// compile+stage flow the raw `compileDeliveryGraph` door uses. It STAGES for operator review and
+// returns a navigational `reviewUrl` and NOTHING that can trigger a run — dispatch stays an
+// operator-only cockpit action (ADR 0005 Decision 7 / issue #460). No new runner, no second staging
+// path: the generator only produces the `DeliveryGraph` (`buildSequenceGraph`) and delegates.
+//
+// Invalid input (empty `issues`, an unparseable `owner/repo#N` ref, an unknown target/probe per the
+// S3 vocabulary) is a 400 carrying the uniform `issues[{path,message}]` contract; nothing is staged.
+import { compileAndStageDeliveryGraph } from "../app/deliveryGraphStage.ts";
+import { resolvePublicOrigin } from "../app/resolveApiBase.ts";
+import { buildSequenceGraph } from "../app/sequenceIssues.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+export default defineOperation("sequenceIssues", async ({ body, req }, app) => {
+  // Build the canonical graph from the intent. Input validation (shape, ref format, vocabulary drift)
+  // lives in the pure `buildSequenceGraph` and returns the uniform `issues[{path,message}]` contract —
+  // a directly-invoked delegate passing `undefined` folds into the same clean rejection.
+  const built = buildSequenceGraph(body);
+  if (!built.ok) {
+    app.log.warn("sequence-issues rejected", { issues: built.issues.length });
+    return { status: 400, body: { error: "invalid sequenceIssues intent", issues: built.issues } };
+  }
+
+  // Hand the CONSTRUCTED graph to the shared compile+stage flow — one compiler, one staging path,
+  // idempotency/digest inherited (AGENTS.md "no drift surfaces"). `reviewUrl` keys to the origin this
+  // request arrived on (tunnel/proxy prefix), not the static deployment-wide base (#577).
+  const staged = await compileAndStageDeliveryGraph(
+    app.data,
+    built.graph,
+    JSON.stringify(built.graph),
+    resolvePublicOrigin(req),
+  );
+  if (!staged.ok) {
+    // A generated graph is well-formed by construction; a compile failure here is a generator defect,
+    // surfaced through the SAME `issues[{path,message}]` contract (mapped from the compiler's
+    // path-qualified `errors`) rather than a 500.
+    app.log.error("sequence-issues compile failed on a generated graph", { errors: staged.body.errors.length });
+    return {
+      status: 400,
+      body: { error: "generated delivery graph failed to compile", issues: staged.body.errors },
+    };
+  }
+
+  app.log.info("sequence-issues staged", {
+    digest: staged.digest,
+    nodes: staged.nodeCount,
+    humanNodes: staged.humanNodeCount,
+    sideEffects: staged.sideEffectCount,
+  });
+  return { status: staged.status, body: staged.body };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.161.0",
+  "version": "0.162.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/resources/processes/convergence-loop.bpmn

@@ -101,7 +101,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:pr-review" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrReviewRoundIn" />
@@ -321,7 +321,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:scope-classify" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="scope-classify.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/scope-classify.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:properties>
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="PrScopeClassifyIn" />

package/resources/processes/feature.bpmn

@@ -173,7 +173,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness (intake gate).** This feature was scheduled to wait until an upstream landed and published. Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />

package/resources/processes/implement-cell.bpmn

@@ -8,7 +8,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:feature" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (is defined(baseBranchBrief) and baseBranchBrief != null) then baseBranchBrief else &#34;&#34;) + (if (is defined(blackboardBrief) and blackboardBrief != null) then blackboardBrief else &#34;&#34;) + (if (is defined(resolvedDepsBrief) and resolvedDepsBrief != null) then resolvedDepsBrief else &#34;&#34;) + (if (is defined(resolvedArtifacts) = false or resolvedArtifacts = null or count(resolvedArtifacts[item != null]) = 0) then &#34;&#34; else (&#34;&#10;&#10;---&#10;&#10;**Bound upstream readiness.** Build/install/clone against EXACTLY these resolved published versions (the ones first carrying the awaited capability), and bump the consumer dependency to them — never merely the newest:&#10;&#10;&#34; + string join(resolvedArtifacts[item != null], &#34;&#10;&#34;))) + (if (is defined(customInstructions) = false or customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />

package/resources/processes/merge-cell.bpmn

@@ -8,7 +8,7 @@
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="senior:trial-merge" />
         <zeebe:linkedResources>
-          <zeebe:linkedResource resourceId="trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+          <zeebe:linkedResource resourceId="prompts/trial-merge.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
           <zeebe:input source="=null" target="result" />

package/resources/processes/merge-loop.bpmn

@@ -293,7 +293,7 @@
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:fix-ci" />
           <zeebe:linkedResources>
-            <zeebe:linkedResource resourceId="fix-ci.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+            <zeebe:linkedResource resourceId="prompts/fix-ci.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>
           <zeebe:properties>
             <zeebe:property name="io.nanobpm.dataEnvelope.in" value="FixCiIn" />
@@ -450,7 +450,7 @@
         <bpmn:extensionElements>
           <zeebe:taskDefinition type="senior:rebase" />
           <zeebe:linkedResources>
-            <zeebe:linkedResource resourceId="rebase.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+            <zeebe:linkedResource resourceId="prompts/rebase.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
           </zeebe:linkedResources>
           <zeebe:properties>
             <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RebaseIn" />