@nanobpm/nano-workforce 0.161.0 → 0.162.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.162.0](https://github.com/nanobpm/nano-workforce/compare/v0.161.0...v0.162.0) (2026-08-29)
+
+### Features
+
+* add sequenceIssues intent door for canonical delivery-graph chains ([#618](https://github.com/nanobpm/nano-workforce/issues/618)) ([698f4bf](https://github.com/nanobpm/nano-workforce/commit/698f4bf5b7e873bd1805ea4c671162db7037de5a)), closes [#605](https://github.com/nanobpm/nano-workforce/issues/605) [#610](https://github.com/nanobpm/nano-workforce/issues/610)
+
 ## [0.161.0](https://github.com/nanobpm/nano-workforce/compare/v0.160.0...v0.161.0) (2026-08-29)
 
 ### Features

package/app/deliveryGraphStage.ts

@@ -0,0 +1,108 @@
+// nano-workforce — the ONE compile-and-stage flow shared by every agent-facing door that stages a
+// delivery graph (epic nano-workforce#605). Extracted from `operations/compileDeliveryGraph.ts` (S0)
+// so the intent-shaped generator doors (S4 — `sequenceIssues`) hand their CONSTRUCTED graph to the
+// EXACT same deterministic compile → validate → stage path the raw `compileDeliveryGraph` door uses:
+// one compiler (`compileDeliveryGraph`), one staging path (`stageProposal`), one idempotency/digest
+// semantics (content-addressed by `deliveryGraphDigest`). Per AGENTS.md "Derivation over duplication:
+// no drift surfaces", a generator MUST NOT re-implement a second runner or a second staging path —
+// it only produces the `DeliveryGraph` and delegates here.
+//
+// The result mirrors the `compileDeliveryGraph` operation's wire contract exactly: a `200` carrying
+// the `CompileDeliveryGraphStaged` preview + navigational `reviewUrl` (NO dispatch handle — dispatch
+// stays an operator-only cockpit action, ADR 0005 Decision 7 / issue #460), or a `400` carrying the
+// `CompileDeliveryGraphErrors` `{ ok:false, errors:[{path,message}] }` when the graph fails shape or
+// semantic validation. Nothing is staged on a rejected compile.
+import type { DataLayer } from "@nanobpm/urban";
+import type { CompileDeliveryGraphErrors, CompileDeliveryGraphStaged } from "../nano-generated/api-io.d.ts";
+import { compileDeliveryGraph } from "./deliveryGraphCompiler.ts";
+import {
+  buildProposalPreview,
+  buildProposalRow,
+  proposalLogicalKey,
+  proposalReviewUrl,
+  stageProposal,
+} from "./deliveryGraphProposals.ts";
+import { deliveryGraphDigest } from "./deliveryRunner.ts";
+
+/** The human-readable instruction every staged compile hands back — the agent's surface ends here;
+ * dispatch is an operator action and there is no start endpoint (capability-by-absence, #460). */
+export 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.";
+
+/** A successful stage — the `CompileDeliveryGraphStaged` body plus the compiled `digest` and node
+ * counts, so a caller can log what it staged without re-deriving them. */
+export interface StagedResult {
+  ok: true;
+  status: 200;
+  body: CompileDeliveryGraphStaged;
+  digest: string;
+  nodeCount: number;
+  humanNodeCount: number;
+  sideEffectCount: number;
+}
+
+/** A rejected compile — the `CompileDeliveryGraphErrors` body, verbatim from the compiler. */
+export interface StageErrors {
+  ok: false;
+  status: 400;
+  body: CompileDeliveryGraphErrors;
+}
+
+/**
+ * Compile a `DeliveryGraph` and, when valid, persist it as a `staged` proposal — the single
+ * compile+stage flow (see the module header). `graph` is the structured `DeliveryGraph` object (an
+ * agent-authored one from `compileDeliveryGraph`, or a generator-CONSTRUCTED one from a `start/*`
+ * intent door); `graphJson` is the serialised form persisted on the proposal row for the cockpit
+ * dispatch to re-run (the caller supplies it so a generator can persist the SAME object it compiled,
+ * byte-for-byte). `origin` is the public origin the request arrived on, used to build the
+ * navigational `reviewUrl`. Never dispatches; never throws for a malformed graph (the compiler maps
+ * unknown input to a clean `ok:false`).
+ */
+export async function compileAndStageDeliveryGraph(
+  data: DataLayer,
+  graph: unknown,
+  graphJson: string,
+  origin: string,
+): Promise<StagedResult | StageErrors> {
+  const result = await compileDeliveryGraph(graph);
+  if (!result.ok) {
+    return { ok: false, status: 400, body: result };
+  }
+
+  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(
+    data,
+    buildProposalRow({
+      digest,
+      logicalKey: proposalLogicalKey(name, digest),
+      title: name,
+      graphJson,
+      preview,
+      nodeCount: result.resolved.nodes.length,
+      humanNodeCount: result.humanNodes.length,
+      sideEffectCount: result.sideEffects.length,
+      sideEffecting: result.sideEffects.length > 0,
+    }),
+  );
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      status: "ready",
+      message: STAGED_MESSAGE,
+      digest,
+      preview,
+      reviewUrl: proposalReviewUrl(digest, origin),
+    },
+    digest,
+    nodeCount: result.resolved.nodes.length,
+    humanNodeCount: result.humanNodes.length,
+    sideEffectCount: result.sideEffects.length,
+  };
+}

package/app/sequenceIssues.test.ts

@@ -0,0 +1,186 @@
+// Tests for the `sequenceIssues` intent → canonical delivery-graph GENERATOR (epic
+// nano-workforce#605, S4/#610). The core acceptance guard: the generated graph is EQUIVALENT to the
+// hand-authored canonical §9.4 chain for the same inputs — same node kinds, edges, and `pr`-fact
+// threading — so an agent never re-authors 13 nodes + 12 edges by hand. Also pins the input/vocabulary
+// validation contract (`issues[{path,message}]`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { compileDeliveryGraph } from "../app/deliveryGraphCompiler.ts";
+import { validateDeliveryGraph } from "../app/deliveryGraph.ts";
+import { buildSequenceGraph, MAX_SEQUENCE_ISSUES, MERGE_POLL } from "./sequenceIssues.ts";
+
+type AnyGraph = { name?: string; nodes: any[]; edges: any[] };
+
+function ok(intent: unknown): AnyGraph {
+  const res = buildSequenceGraph(intent);
+  assert(res.ok, `expected ok, got ${JSON.stringify(res)}`);
+  return res.graph as AnyGraph;
+}
+
+/** The hand-authored canonical chain for the SAME inputs — what §9.4 says an agent would build by
+ * hand. The generator must produce a structurally-equivalent graph. */
+function handAuthored(behind: string | null, issues: string[]): AnyGraph {
+  const nodes: any[] = [];
+  const edges: any[] = [];
+  if (behind) {
+    nodes.push({
+      id: "gate-epic",
+      kind: "wait",
+      wait: { kind: "epic", target: behind, match: { epicState: "merged" }, poll: { ...MERGE_POLL }, onTimeout: "escalate" },
+      emits: [{ name: "prCount", type: "number" }],
+    });
+  }
+  issues.forEach((issue, i) => {
+    const n = i + 1;
+    nodes.push({
+      id: `open-${n}`,
+      kind: "agent",
+      agent: { jobType: "senior:feature", prompt: `Implement ${issue} and open a PR.` },
+      emits: [{ name: "pr", type: "pr" }],
+    });
+    nodes.push({ id: `land-${n}`, kind: "connector", connector: { target: "converge-merge", payload: { pr: `open-${n}.pr` } } });
+    nodes.push({
+      id: `merged-${n}`,
+      kind: "wait",
+      wait: { kind: "pr", target: `open-${n}.pr`, match: { prState: "merged" }, poll: { ...MERGE_POLL }, onTimeout: "escalate" },
+    });
+    edges.push({ from: `open-${n}.pr`, to: `land-${n}` });
+    edges.push({ from: `open-${n}.pr`, to: `merged-${n}` });
+    if (i === 0) {
+      if (behind) edges.push({ from: "gate-epic", to: `open-${n}` });
+    } else {
+      edges.push({ from: `merged-${i}`, to: `open-${n}` });
+    }
+  });
+  return { nodes, edges };
+}
+
+/** Compare two graphs by their SEMANTIC content — node set (by id) and edge set — order-insensitive. */
+function assertEquivalent(actual: AnyGraph, expected: AnyGraph): void {
+  const byId = (g: AnyGraph) => new Map(g.nodes.map((n) => [n.id, n]));
+  const a = byId(actual);
+  const e = byId(expected);
+  assertEquals([...a.keys()].sort(), [...e.keys()].sort(), "same node ids");
+  for (const [id, node] of e) assertEquals(a.get(id), node, `node ${id} matches canonical`);
+  const edgeKey = (x: any) => JSON.stringify([x.from, x.to, x.when ?? null, x.equals ?? null, x.default ?? null]);
+  assertEquals(actual.edges.map(edgeKey).sort(), expected.edges.map(edgeKey).sort(), "same edge set");
+}
+
+test("sequenceIssues: four issues behind a gate → the exact 13-node / 12-edge canonical chain", () => {
+  const behind = "acme/repo#100";
+  const issues = ["acme/repo#1", "acme/repo#2", "acme/repo#3", "acme/repo#4"];
+  const graph = ok({ behind, issues });
+  // The evidence-session shape: 1 gate + 3 nodes/issue = 13 nodes; 8 fact edges + 1 gate edge + 3
+  // sequence edges = 12 edges.
+  assertEquals(graph.nodes.length, 13);
+  assertEquals(graph.edges.length, 12);
+  assertEquivalent(graph, handAuthored(behind, issues));
+});
+
+test("sequenceIssues: without `behind`, no leading epic gate and no gate edge", () => {
+  const issues = ["acme/repo#1", "acme/repo#2"];
+  const graph = ok({ issues });
+  assertEquals(graph.nodes.length, 6);
+  assertEquals(graph.edges.length, 5); // 2 fact edges/issue (4) + 1 sequence edge
+  assert(!graph.nodes.some((n) => n.id === "gate-epic"), "no epic gate without `behind`");
+  assertEquivalent(graph, handAuthored(null, issues));
+});
+
+test("sequenceIssues: each issue emits agent(senior:feature,emits pr) → connector(converge-merge) → wait[pr,merged]", () => {
+  const graph = ok({ issues: ["acme/repo#7"] });
+  const open = graph.nodes.find((n) => n.id === "open-1");
+  const land = graph.nodes.find((n) => n.id === "land-1");
+  const merged = graph.nodes.find((n) => n.id === "merged-1");
+  assertEquals(open.kind, "agent");
+  assertEquals(open.agent.jobType, "senior:feature");
+  assertEquals(open.emits, [{ name: "pr", type: "pr" }]);
+  assertEquals(land.kind, "connector");
+  assertEquals(land.connector.target, "converge-merge");
+  assertEquals(land.connector.payload, { pr: "open-1.pr" });
+  assertEquals(merged.kind, "wait");
+  assertEquals(merged.wait.kind, "pr");
+  assertEquals(merged.wait.target, "open-1.pr");
+  assertEquals(merged.wait.match, { prState: "merged" });
+  // The pr fact is threaded to BOTH consumers by fact-qualified edges (§9.4).
+  assert(graph.edges.some((e) => e.from === "open-1.pr" && e.to === "land-1"));
+  assert(graph.edges.some((e) => e.from === "open-1.pr" && e.to === "merged-1"));
+});
+
+test("sequenceIssues: merge/epic gates carry a realistic poll budget (not the 30-min default trap)", () => {
+  const graph = ok({ behind: "acme/repo#9", issues: ["acme/repo#1"] });
+  const gate = graph.nodes.find((n) => n.id === "gate-epic");
+  const merged = graph.nodes.find((n) => n.id === "merged-1");
+  assertEquals(gate.wait.poll, { everyMs: 300_000, timeoutMs: 259_200_000 });
+  assertEquals(merged.wait.poll, { everyMs: 300_000, timeoutMs: 259_200_000 });
+  assert(merged.wait.poll.timeoutMs > 30 * 60 * 1000, "budget must exceed the 30-minute default");
+});
+
+test("sequenceIssues: the generated graph passes validateDeliveryGraph AND compiles", async () => {
+  const graph = ok({ behind: "acme/repo#100", issues: ["acme/repo#1", "acme/repo#2", "acme/repo#3", "acme/repo#4"] });
+  assertEquals(validateDeliveryGraph(graph), []);
+  const compiled = await compileDeliveryGraph(graph);
+  assert(compiled.ok, `expected the generated graph to compile, got ${JSON.stringify(compiled)}`);
+});
+
+test("sequenceIssues: an issue URL is accepted and normalised to owner/repo#N", () => {
+  const graph = ok({ issues: ["https://github.com/acme/repo/issues/42"] });
+  const open = graph.nodes.find((n) => n.id === "open-1");
+  assertEquals(open.agent.prompt, "Implement acme/repo#42 and open a PR.");
+});
+
+// ── Validation: the uniform issues[{path,message}] contract ─────────────────────────────────────
+function rejects(intent: unknown): Array<{ path: string; message: string }> {
+  const res = buildSequenceGraph(intent);
+  assert(!res.ok, `expected rejection, got ${JSON.stringify(res)}`);
+  assert(Array.isArray(res.issues) && res.issues.length > 0, "issues[] must be non-empty");
+  for (const iss of res.issues) {
+    assert(typeof iss.path === "string" && typeof iss.message === "string", `bad issue ${JSON.stringify(iss)}`);
+  }
+  return res.issues;
+}
+
+test("sequenceIssues: empty issues → rejected with issues[{path,message}]", () => {
+  const issues = rejects({ issues: [] });
+  assert(issues.some((i) => i.path === "issues"));
+});
+
+test("sequenceIssues: missing issues → rejected", () => {
+  const issues = rejects({});
+  assert(issues.some((i) => i.path === "issues"));
+});
+
+test("sequenceIssues: an unparseable issue ref → rejected at the offending index", () => {
+  const issues = rejects({ issues: ["acme/repo#1", "not-an-issue"] });
+  assert(issues.some((i) => i.path === "issues[1]"), `expected issues[1] path, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: an unparseable `behind` ref → rejected at behind", () => {
+  const issues = rejects({ behind: "nope", issues: ["acme/repo#1"] });
+  assert(issues.some((i) => i.path === "behind"));
+});
+
+test("sequenceIssues: an empty-string `behind` → rejected at behind (not silently ungated)", () => {
+  const issues = rejects({ behind: "", issues: ["acme/repo#1"] });
+  assert(issues.some((i) => i.path === "behind"), `expected behind path, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: a non-positive issue number (`#0`) → rejected at the offending index", () => {
+  const issues = rejects({ issues: ["acme/repo#0"] });
+  assert(issues.some((i) => i.path === "issues[0]"), `expected issues[0] path, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: an unsafe-integer issue number → rejected at the offending index", () => {
+  const issues = rejects({ issues: ["acme/repo#1", "acme/repo#99999999999999999999"] });
+  assert(issues.some((i) => i.path === "issues[1]"), `expected issues[1] path, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: a non-positive `behind` number (`#0`) → rejected at behind", () => {
+  const issues = rejects({ behind: "acme/repo#0", issues: ["acme/repo#1"] });
+  assert(issues.some((i) => i.path === "behind"), `expected behind path, got ${JSON.stringify(issues)}`);
+});
+
+test("sequenceIssues: more than the max issues → rejected", () => {
+  const many = Array.from({ length: MAX_SEQUENCE_ISSUES + 1 }, (_, i) => `acme/repo#${i + 1}`);
+  const issues = rejects({ issues: many });
+  assert(issues.some((i) => i.path === "issues"));
+});

package/app/sequenceIssues.ts

@@ -0,0 +1,236 @@
+// nano-workforce — the `sequenceIssues` intent → canonical delivery-graph GENERATOR (epic
+// nano-workforce#605, S4/#610). ADR 0005's delivery graph is a closed vocabulary, and §9.4 of the
+// operator guide already names the canonical shape for "implement issue → converge → merge". But an
+// agent still had to hand-author the full node/edge JSON: in the evidence session, sequencing four
+// issues behind a gate meant constructing 13 nodes and 12 edges by hand. This module produces that
+// exact shape from a high-level INTENT instead.
+//
+// The intent is `{ behind?: "owner/repo#NN", issues: ["owner/repo#A", …] }`. For each issue it emits
+// the canonical chain — `agent` (`senior:feature`, emits a `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 per §9.4. The issues run in SEQUENCE: each issue's agent starts once
+// the PRIOR issue has merged. An optional leading `wait[epic]` gate (when `behind` is given) makes the
+// whole sequence wait for that issue/epic/feature to be fully merged first (§9.5).
+//
+// It is a PURE builder: no I/O, no staging. The operation (`operations/sequenceIssues.ts`) hands the
+// constructed `DeliveryGraph` to the SAME `compileAndStageDeliveryGraph` flow the raw
+// `compileDeliveryGraph` door uses (one compiler, one staging path — AGENTS.md "no drift surfaces").
+// The generated graph is authored to pass `validateDeliveryGraph` by construction: unique node ids,
+// `pr`-typed emits, threaded fact edges, a DAG. It is validated against the S3 vocabulary
+// (`deliveryGraphVocabulary`) so an unknown connector target / probe kind is rejected at the door with
+// `issues[{path,message}]` rather than only surfacing at compile time.
+import type { DeliveryEdge, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import { CONVERGE_MERGE_TARGET } from "./convergeTargets.ts";
+import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
+import { type ParsedIssue, parseIssue } from "./plan.ts";
+
+/** A path-qualified validation failure — the uniform door error contract `issues[{path,message}]`
+ * (the same shape the runtime request-validator and the S1 harness assert). */
+export interface SequenceIssueError {
+  readonly path: string;
+  readonly message: string;
+}
+
+/** The `sequenceIssues` intent body — an optional leading `behind` gate plus the ordered `issues`. */
+export interface SequenceIssuesIntent {
+  behind?: string;
+  issues: string[];
+}
+
+/** The result of {@link buildSequenceGraph}: either the constructed graph, or the path-qualified
+ * input/vocabulary rejections. */
+export type SequenceIssuesResult =
+  | { ok: true; graph: DeliveryGraph }
+  | { ok: false; issues: SequenceIssueError[] };
+
+/** The realistic merge-gate poll budget the canonical shape uses (§9.4 / §9.1): re-probe every 5
+ * minutes, budget 3 days. A `wait[pr, merged]` / `wait[epic]` waits on a human-paced merge, so the
+ * 30-minute default poll budget is a trap — always set an explicit `poll.timeoutMs` on a merge/epic
+ * gate. Exported so the regression test asserts the generated gate against the canonical values. */
+export const MERGE_POLL = { everyMs: 300_000, timeoutMs: 259_200_000 } as const;
+
+/** The wait-probe kind that observes a single in-flight PR's merge state (ADR 0005 §2). */
+const PR_PROBE_KIND = "pr";
+/** The wait-probe kind that observes a whole epic/feature lineage reaching "fully merged" (§9.5). */
+const EPIC_PROBE_KIND = "epic";
+/** The agent job type each issue node runs (a full single-issue feature implementation). */
+const AGENT_JOB_TYPE = "senior:feature";
+/** The upper bound on issues in one sequence — keeps the generated graph within the compiler's
+ * 256-node ceiling (3 nodes/issue + an optional gate) with generous headroom, and bounds the intent. */
+export const MAX_SEQUENCE_ISSUES = 64;
+
+/** A `pr`-typed emit declaration — what an `agent` node publishes for the PR it opened, so the
+ * downstream connector / `wait[pr]` node late-binds its target PR from the fact (§9.4, issue #548). */
+const PR_EMIT = { name: "pr", type: "pr" as const };
+
+/** Parse a ref into an issue target ONLY if its number is a positive, safe integer. `parseIssue`'s
+ * `\d+` accepts `#0` and precision-overflowing numbers (e.g. `#99999999999999999999`, which coerces
+ * past `Number.MAX_SAFE_INTEGER`), but such a target can never resolve to a real issue/PR — staging a
+ * gate on it would wait forever. Reject it deterministically at the door instead (Copilot review,
+ * PR #618), so only `#N` with `N >= 1 && Number.isSafeInteger(N)` is accepted. */
+function parseIssueRef(ref: unknown): ParsedIssue | null {
+  const parsed = typeof ref === "string" ? parseIssue(ref) : null;
+  if (!parsed) return null;
+  return Number.isSafeInteger(parsed.number) && parsed.number >= 1 ? parsed : null;
+}
+
+/**
+ * Build the canonical delivery graph for a `sequenceIssues` intent, or return path-qualified
+ * `issues[{path,message}]` rejections for invalid input. Validates:
+ *   - `issues` is a non-empty array within {@link MAX_SEQUENCE_ISSUES};
+ *   - every `issues[i]` and the optional `behind` parse as an `owner/repo#N` reference;
+ *   - the connector target and wait-probe kinds it emits are known to the S3 vocabulary (drift guard).
+ * Pure — no I/O. The constructed graph passes `validateDeliveryGraph` by construction.
+ */
+export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
+  const issues: SequenceIssueError[] = [];
+
+  const body = isRecord(intent) ? intent : {};
+  const rawIssues = body.issues;
+  const rawBehind = body.behind;
+
+  // ── `issues`: a non-empty, bounded array of parseable refs ───────────────────────────────────
+  const parsedIssues: string[] = [];
+  if (!Array.isArray(rawIssues)) {
+    issues.push({ path: "issues", message: "`issues` must be a non-empty array of `owner/repo#N` issue references." });
+  } else if (rawIssues.length === 0) {
+    issues.push({ path: "issues", message: "`issues` must contain at least one `owner/repo#N` issue reference." });
+  } else if (rawIssues.length > MAX_SEQUENCE_ISSUES) {
+    issues.push({
+      path: "issues",
+      message: `\`issues\` has too many entries (${rawIssues.length}) — the limit is ${MAX_SEQUENCE_ISSUES}.`,
+    });
+  } else {
+    rawIssues.forEach((ref, i) => {
+      const parsed = parseIssueRef(ref);
+      if (!parsed) {
+        issues.push({
+          path: `issues[${i}]`,
+          message: `\`${String(ref)}\` is not a valid \`owner/repo#N\` issue reference.`,
+        });
+        return;
+      }
+      parsedIssues.push(parsed.planKey);
+    });
+  }
+
+  // ── `behind` (optional): a parseable ref, when PRESENT ───────────────────────────────────────
+  // Only an OMITTED gate (`undefined`/`null`) is "no gate"; a present-but-empty `behind: ""` is a
+  // caller mistake (the schema requires `minLength: 1`), not an ungated sequence — reject it rather
+  // than silently dropping the gate the caller asked for (matters most when this builder is invoked
+  // directly, bypassing OpenAPI validation).
+  let behindKey: string | null = null;
+  if (rawBehind !== undefined && rawBehind !== null) {
+    const parsed = parseIssueRef(rawBehind);
+    if (!parsed) {
+      issues.push({
+        path: "behind",
+        message: `\`${String(rawBehind)}\` is not a valid \`owner/repo#N\` issue/epic reference.`,
+      });
+    } else {
+      behindKey = parsed.planKey;
+    }
+  }
+
+  // ── Vocabulary drift guard (S3): the target/probe kinds this generator emits MUST be known to the
+  // structured vocabulary. This can only trip if the closed vocabulary changes underneath us — it is
+  // surfaced as a door `issue` (not a throw) so the failure mode is a clean rejection, not a 500. ──
+  const vocab = deliveryGraphVocabulary();
+  const realTargets = new Set(vocab.connectorTargets.filter((t) => t.status === "real").map((t) => t.target));
+  if (!realTargets.has(CONVERGE_MERGE_TARGET)) {
+    issues.push({
+      path: "issues",
+      message: `connector target \`${CONVERGE_MERGE_TARGET}\` is not a real target in the delivery-graph vocabulary.`,
+    });
+  }
+  const probeKinds = new Set(vocab.waitProbeKinds.map((p) => p.kind));
+  for (const kind of behindKey ? [PR_PROBE_KIND, EPIC_PROBE_KIND] : [PR_PROBE_KIND]) {
+    if (!probeKinds.has(kind)) {
+      issues.push({ path: "issues", message: `wait-probe kind \`${kind}\` is not in the delivery-graph vocabulary.` });
+    }
+  }
+
+  if (issues.length > 0) return { ok: false, issues };
+
+  return { ok: true, graph: assembleGraph(parsedIssues, behindKey) };
+}
+
+/** Assemble the canonical node/edge chain for the (already-validated) issue keys + optional gate. */
+function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryGraph {
+  const nodes: DeliveryNode[] = [];
+  const edges: DeliveryEdge[] = [];
+
+  // Optional leading `wait[epic]` gate — the whole sequence waits for `behind` to be fully merged.
+  const GATE_ID = "gate-epic";
+  if (behindKey) {
+    nodes.push({
+      id: GATE_ID,
+      kind: "wait",
+      wait: {
+        kind: EPIC_PROBE_KIND,
+        target: behindKey,
+        match: { epicState: "merged" },
+        poll: { ...MERGE_POLL },
+        onTimeout: "escalate",
+      },
+      emits: [{ name: "prCount", type: "number" }],
+    });
+  }
+
+  issueKeys.forEach((issueKey, i) => {
+    const n = i + 1;
+    const openId = `open-${n}`;
+    const landId = `land-${n}`;
+    const mergedId = `merged-${n}`;
+    const prRef = `${openId}.pr`;
+
+    // agent → opens the PR, emits it as a typed `pr` fact the downstream nodes late-bind.
+    nodes.push({
+      id: openId,
+      kind: "agent",
+      agent: { jobType: AGENT_JOB_TYPE, prompt: `Implement ${issueKey} and open a PR.` },
+      emits: [{ ...PR_EMIT }],
+    });
+    // connector[converge-merge] → drive the opened PR through review convergence + the merge loop.
+    nodes.push({
+      id: landId,
+      kind: "connector",
+      connector: { target: CONVERGE_MERGE_TARGET, payload: { pr: prRef } },
+    });
+    // wait[pr, merged] → observe the PR reaching `merged`, with a realistic poll budget.
+    nodes.push({
+      id: mergedId,
+      kind: "wait",
+      wait: {
+        kind: PR_PROBE_KIND,
+        target: prRef,
+        match: { prState: "merged" },
+        poll: { ...MERGE_POLL },
+        onTimeout: "escalate",
+      },
+    });
+
+    // Thread the `pr` fact to both consumers (required — an unthreaded reference is `unbound-pr`).
+    edges.push({ from: prRef, to: landId });
+    edges.push({ from: prRef, to: mergedId });
+
+    // Sequence: this issue's agent starts once the PRIOR issue merged; the first waits on the gate.
+    if (i === 0) {
+      if (behindKey) edges.push({ from: GATE_ID, to: openId });
+    } else {
+      edges.push({ from: `merged-${i}`, to: openId });
+    }
+  });
+
+  const name =
+    issueKeys.length === 1
+      ? `sequence ${issueKeys[0]}`
+      : `sequence ${issueKeys.length} issues${behindKey ? ` behind ${behindKey}` : ""}`;
+
+  return { name, nodes, edges };
+}
+
+/** Narrow an untyped value to a plain object so its fields can be read as `unknown`. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/docs/agent-guide.md

@@ -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.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",