@nanobpm/nano-workforce 0.161.0 → 0.162.1

package/AGENTS.md

@@ -120,7 +120,8 @@ GENERATED, never hand-edited.**
 ## Deploy by convention: `resources/` (ADR 0062)
 
 **Deployables live under `resources/` and deploy by convention — `nano.app.json`
-declares no `models`.** urban walks `resources/` (shallow, one level deep) and deploys
+declares no `models`.** urban walks `resources/` **recursively (every file at any depth)** and
+deploys
 every file: `resources/processes/*.bpmn`, `resources/forms/*.form`, and one prompt per
 task under `resources/prompts/*.md`.
 
@@ -131,15 +132,20 @@ task under `resources/prompts/*.md`.
 - **No `models` block.** Rely on the convention; add a `models` override *only* for a
   genuinely non-standard layout (nwf doesn't need one). An explicit `models` is used
   verbatim and skips the convention walk.
-- **Basenames must be unique across the deploy set** — the deploy dedupe key is the
-  filename only, so two files sharing a basename in different dirs collide. `npm run
-  check:prompts` fails loudly on that.
+- **Prompt ids are `resources/`-relative; basenames must be unique only within a
+  `models` override.** A convention resource's deploy id (`resourceId`) is its path
+  **relative to `resources/`** — `resources/prompts/plan.md` → `prompts/plan.md` — so files
+  sharing a basename in different sub-dirs deploy as distinct resources. Only a `models`
+  override keys by basename (and so must avoid basename collisions). `npm run check:prompts`
+  validates each prompt link against the actual deployed id and fails loudly on a mismatch.
 - **Agent prompts: linkedResource is the blessed *and only* path.** Each agent service
   task links its base prompt with
-  `<zeebe:linkedResource resourceId="<token>.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
+  `<zeebe:linkedResource resourceId="prompts/<token>.md" bindingType="latest" resourceType="GenericScript" linkName="prompt"/>`,
   which the engine resolves to the latest deployed `resources/prompts/<token>.md` at job
   activation, combined at runtime with the per-task `appendPrompt` FEEL. `bindingType="latest"`
-  lets a prompt update land mid-epic without a process redeploy.
+  lets a prompt update land mid-epic without a process redeploy. **The id is the
+  `resources/`-relative path (`prompts/<token>.md`), NOT the bare basename** — a bare id
+  resolves to nothing and the engine silently omits the link, so the agent runs prompt-less.
 - **Deploy-time `{{token}}` templating is removed — no back-compat.** To inject a per-run
   value (URL, flag) into an agent, pass it as a runtime job variable / `appendPrompt`
   FEEL; never bake it into a model at deploy time.

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.162.1](https://github.com/nanobpm/nano-workforce/compare/v0.162.0...v0.162.1) (2026-08-30)
+
+### Bug Fixes
+
+* **prompts:** reference prompts by resources-relative id so agents get their base prompt ([#628](https://github.com/nanobpm/nano-workforce/issues/628)) ([084e8f8](https://github.com/nanobpm/nano-workforce/commit/084e8f8f4ad842cc9f9e92c25b4ef80d0b0b66e1)), closes [#241](https://github.com/nanobpm/nano-workforce/issues/241)
+
+## [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/README.md

@@ -499,7 +499,7 @@ agent's base prompt is **not** in the job payload — it is delivered as a
 **linked resource** (likewise `plan.md`, `feature.md`, `fix-ci.md`, …):
 
 ```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 resolves to the latest deployed `resources/prompts/*.md` at job

package/SPEC.md

@@ -164,7 +164,7 @@ Notes:
 
 The base instructions are **not** a job variable: they are delivered as a
 **linked resource** on the `senior:pr-review` task —
-`<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"/>`,
 which the engine resolves to the latest deployed `resources/prompts/review-round.md` at job
 activation.
 
@@ -319,14 +319,16 @@ when the engine data is purged, to keep app state and engine state consistent).
 Each agent task's base prompt lives **only** in its `resources/prompts/*.md` side-car,
 deployed as a **generic resource** and **linked** — not baked — into the model (issue
 #169). Under the ADR 0062 `resources/` deploy-by-convention layout, `nano.app.json`
-declares **no `models`**, so `@nanobpm/urban` walks `resources/` (shallow, one level) and
-deploys each file as an `application/octet-stream` resource whose deployed **name is
-the file's basename** (`resources/prompts/review-round.md` → resource `review-round.md`).
-Each agent service task links it:
+declares **no `models`**, so `@nanobpm/urban` walks `resources/` **recursively (every file at any
+depth)** and deploys each file as an
+`application/octet-stream` resource whose deployed **id is its path relative to `resources/`**
+(`resources/prompts/review-round.md` → resource `prompts/review-round.md`). Each agent service
+task links it by that `resources/`-relative id (a bare basename resolves to nothing and the
+engine silently omits the link, leaving the agent prompt-less):
 
 ```xml
 <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>
 ```
 

package/app/convergeGate.test.ts

@@ -394,7 +394,7 @@ test("classify-scope is an agent task servicing senior:scope-classify with a lin
   const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="classify-scope"[^>]*>.*?<\/bpmn:serviceTask>/);
   assert(task, "classify-scope service task missing");
   assertStringIncludes(task[0], 'type="senior:scope-classify"');
-  assertStringIncludes(task[0], 'resourceId="scope-classify.md"');
+  assertStringIncludes(task[0], 'resourceId="prompts/scope-classify.md"');
   assertStringIncludes(task[0], 'linkName="prompt"');
   // After honouring (or ignoring) the human's scope answer, it clears the one-shot
   // scopeAnswer so a later round does not re-honour a stale decision.

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/app/service.ts

@@ -193,7 +193,7 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
 // The `senior:pr-review` agent prompt is no longer read by the host: it is a generic resource
 // (`resources/prompts/review-round.md`, deployed under the `resources/` deploy-by-convention layout
 // — nano.app.json declares no `models`) linked into the task
-// as `<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>`
+// as `<zeebe:linkedResource resourceId="prompts/review-round.md" bindingType="latest" linkName="prompt"/>`
 // and resolved by the engine at job activation. The host only carries runtime PR identity + the
 // round counter now.