@nanobpm/nano-workforce 0.160.0 → 0.162.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* addressable operator guide via getAgentGuide(section?) over MCP ([#615](https://github.com/nanobpm/nano-workforce/issues/615)) ([8d59f54](https://github.com/nanobpm/nano-workforce/commit/8d59f541e25478ff7a076debc053d988f1d79b29)), closes [#611](https://github.com/nanobpm/nano-workforce/issues/611)
+
 ## [0.160.0](https://github.com/nanobpm/nano-workforce/compare/v0.159.1...v0.160.0) (2026-08-29)
 
 ### Features

package/app/agentGuide.test.ts

@@ -0,0 +1,115 @@
+// Tests for the addressable operator guide (epic #605 slice S5, issue #611): the stable section
+// registry, the fence-aware markdown splitter, the table of contents, and per-section rendering.
+// The drift guard here is the load-bearing test — it fails the build if the authored guide
+// (`docs/agent-guide.md`) grows/loses a `## ` section without a matching `GUIDE_SECTIONS` entry, so
+// the addressable surface can never silently diverge from the prose.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  GUIDE_SECTIONS,
+  guideToc,
+  renderAgentGuide,
+  renderGuideSection,
+  splitGuideSections,
+} from "./agentGuide.ts";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const RAW_GUIDE = readFileSync(join(REPO_ROOT, "docs", "agent-guide.md"), "utf8");
+
+test("DRIFT GUARD: every `## ` section in docs/agent-guide.md has exactly one registry entry", () => {
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  assertEquals(
+    sections.length,
+    GUIDE_SECTIONS.length,
+    `docs/agent-guide.md has ${sections.length} top-level sections but GUIDE_SECTIONS lists ` +
+      `${GUIDE_SECTIONS.length}. Add/remove a { id, summary } entry so the addressable surface ` +
+      "matches the prose.",
+  );
+});
+
+test("section ids are unique and non-empty; summaries are non-empty", () => {
+  const ids = new Set<string>();
+  for (const s of GUIDE_SECTIONS) {
+    assert(s.id.length > 0, "section id must be non-empty");
+    assert(!ids.has(s.id), `duplicate section id "${s.id}"`);
+    ids.add(s.id);
+    assert(s.summary.trim().length > 0, `section "${s.id}" needs a one-line summary`);
+  }
+});
+
+test("the fence-aware splitter ignores `## ` inside fenced code blocks", () => {
+  const raw = [
+    "# Title",
+    "",
+    "## 0. Real heading",
+    "body",
+    "```",
+    "## not a heading (inside a fence)",
+    "```",
+    "more body",
+    "## 1. Second heading",
+    "tail",
+  ].join("\n");
+  const { sections } = splitGuideSections(raw);
+  assertEquals(sections.length, 2);
+  assertEquals(sections[0].title, "0. Real heading");
+  assert(sections[0].body.includes("## not a heading"), "fenced content stays in its section body");
+  assertEquals(sections[1].title, "1. Second heading");
+});
+
+test("guideToc lists every registry id with a derived title and its summary", () => {
+  const toc = guideToc();
+  assertEquals(toc.length, GUIDE_SECTIONS.length);
+  for (let i = 0; i < toc.length; i++) {
+    assertEquals(toc[i].id, GUIDE_SECTIONS[i].id);
+    assertEquals(toc[i].summary, GUIDE_SECTIONS[i].summary);
+    assert(toc[i].title.length > 0, `toc[${i}] must carry the derived heading title`);
+  }
+  // The TOC is compact by construction — comfortably under any tool-result limit.
+  assert(JSON.stringify(toc).length < 4000, "the table of contents must stay small");
+});
+
+test("delivery-graphs is addressable, smaller than the full guide, and base-keyed", () => {
+  const base = "https://example.test/app/api";
+  const section = renderGuideSection("delivery-graphs", base);
+  assert(section !== undefined, "delivery-graphs must resolve");
+  const full = renderAgentGuide(base);
+  assert(section!.length > 0);
+  assert(section!.length < full.length, "a single section must be smaller than the whole guide");
+  assert(section!.length < 30000, "the delivery-graphs section must fit a typical tool-result budget");
+  assert(!section!.includes("__BASE__"), "placeholders must be substituted in a section render");
+  assert(!section!.includes("__ENGINE__"), "engine placeholder must be substituted too");
+});
+
+test("a compact section is a small fraction of the whole guide", () => {
+  const base = "https://example.test/app/api";
+  const orient = renderGuideSection("orient", base)!;
+  const full = renderAgentGuide(base);
+  assert(orient.length < full.length / 10, "the orient section must be a small fraction of the guide");
+});
+
+test("every registry id resolves to a non-empty section whose heading matches its title", () => {
+  const base = "https://example.test/app/api";
+  const toc = guideToc();
+  for (const { id, title } of toc) {
+    const md = renderGuideSection(id, base);
+    assert(md !== undefined, `section "${id}" must resolve`);
+    assert(md!.startsWith(`## ${title}`), `section "${id}" body must open with its heading`);
+  }
+});
+
+test("an unknown section id resolves to undefined (the op turns that into a 400)", () => {
+  assertEquals(renderGuideSection("does-not-exist", "https://x/app/api"), undefined);
+});
+
+test("no content regression: each section body is a verbatim slice of the raw guide", () => {
+  // Rendering keys examples to an instance; the UN-substituted section bodies must be exact
+  // substrings of the authored doc, so the addressable surface never rewrites guide content.
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  for (const s of sections) {
+    assert(RAW_GUIDE.includes(s.body), `section "${s.title}" must be a verbatim slice of the guide`);
+  }
+});

package/app/agentGuide.ts

@@ -59,8 +59,117 @@ export function resolveEngineBase(): string {
 /**
  * Render the guide for a given app control-API base (e.g. "https://host/app/api"). The engine base
  * is resolved from the environment. Substitutes every `__BASE__`/`__ENGINE__` occurrence.
+ *
+ * This is the FULL guide, byte-for-byte the same content the non-MCP fallback doors serve
+ * (`GET /app/api/agent`, and — via the skill — `GET /app/api/agent/skill`). The addressable helpers
+ * below (`guideToc` / `renderGuideSection`) never touch this path, so those doors stay unchanged.
  */
 export function renderAgentGuide(apiBase: string): string {
   const base = apiBase.replace(/\/+$/, "");
   return RAW_GUIDE.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
 }
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// Addressable guide (epic nano-workforce#605, slice S5, issue #611).
+//
+// The full guide is ~43KB — a single `getAgentInstructions` call can exceed an agent's tool-result
+// limit, forcing it to persist the blob and carve out the section it wanted out-of-band. The guide
+// is already well-structured as top-level `## N. Title` sections, so we make each one individually
+// addressable: a compact table of contents (id + one-line summary), and per-section retrieval.
+//
+// STABLE IDS ARE THE CONTRACT. `GUIDE_SECTIONS` below is the single source of truth for the stable
+// section ids and their summaries, in document order. The section *bodies* are derived by parsing
+// the authored markdown (`docs/agent-guide.md`) at module load — never duplicated here — so prose
+// edits never drift from the addressable surface. The parity is guarded by a drift test
+// (`app/agentGuide.test.ts`): add or remove a `## ` section in the doc without updating this
+// registry and the build fails.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+
+/** One addressable top-level guide section: a stable id and a one-line summary, in document order.
+ *  The `id` is the durable handle agents pass to `getAgentGuide(section)`; keep it stable across
+ *  prose edits (rename the heading freely, never the id). */
+export interface GuideSectionMeta {
+  readonly id: string;
+  readonly summary: string;
+}
+
+/** The stable section registry — ONE per `## N.` heading in `docs/agent-guide.md`, in order. Adding
+ *  a section to the doc requires adding an entry here (enforced by the drift test). */
+export const GUIDE_SECTIONS: readonly GuideSectionMeta[] = [
+  { id: "orient", summary: "Orient first: confirm which instance you're driving; see the live version and every PR in flight." },
+  { id: "submit-pr", summary: "Submit a PR to the review-convergence loop — review-only vs. converge-and-merge, dependency barriers, round caps." },
+  { id: "submit-epic", summary: "Hand a whole issue to the fleet: plan → implement → converge across coding agents, against a required base branch." },
+  { id: "escalations", summary: "Find and answer parked human-in-the-loop escalations (PR-review, feature, plan-review, trial-merge) by user-task key." },
+  { id: "lifecycle", summary: "The PR/epic lifecycle and status vocabulary, so you can reason about where a run currently sits." },
+  { id: "debug", summary: "Debug: find the engine process instance behind a PR and inspect its jobs, incidents, and element-instances." },
+  { id: "debug-models", summary: "Debug the deployed BPMN models and the agent prompts a running instance is actually using." },
+  { id: "unstick", summary: "Unstick a wedged process — publish a correlating message, cancel, or otherwise recover a stalled instance." },
+  { id: "raise-issue", summary: "Raise an issue or open a PR against the nano-workforce repository itself." },
+  { id: "delivery-graphs", summary: "Author, preview, compile/stage and run an agent-authored delivery graph (ADR 0005): node/wait/connector vocabulary." },
+] as const;
+
+/** A parsed section: its stable id + summary (from the registry), the derived heading `title` (the
+ *  markdown text after `## `, e.g. "9. Author and run a delivery graph (ADR 0005)"), and the raw
+ *  section markdown `body` INCLUDING the heading line, with `__BASE__`/`__ENGINE__` un-substituted. */
+export interface ParsedGuideSection extends GuideSectionMeta {
+  readonly title: string;
+  readonly body: string;
+}
+
+/** Split raw guide markdown into its top-level `## ` sections, fence-aware (a `## ` inside a fenced
+ *  code block is content, not a heading). Everything before the first heading is the preamble.
+ *  Pure/​testable — takes the raw text so the drift test can feed it the on-disk doc directly. */
+export function splitGuideSections(raw: string): { preamble: string; sections: { title: string; body: string }[] } {
+  const lines = raw.split("\n");
+  const sections: { title: string; lines: string[] }[] = [];
+  const preambleLines: string[] = [];
+  let inFence = false;
+  let current: { title: string; lines: string[] } | null = null;
+  for (const line of lines) {
+    if (/^(```|~~~)/.test(line.trim())) inFence = !inFence;
+    const heading = !inFence ? /^## (.+)$/.exec(line) : null;
+    if (heading) {
+      current = { title: heading[1].trim(), lines: [line] };
+      sections.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preambleLines.push(line);
+    }
+  }
+  return {
+    preamble: preambleLines.join("\n"),
+    sections: sections.map((s) => ({ title: s.title, body: s.lines.join("\n").replace(/\s+$/, "") })),
+  };
+}
+
+/** The parsed sections of THIS deployment's guide, zipped against the stable registry, computed once
+ *  at module load. When the doc is unreadable (fallback guide, no `## ` headings) this is empty — the
+ *  addressable surface degrades to "no sections", never throws. Length/registry parity is asserted by
+ *  the drift test, not at runtime, so a mismatched deploy still serves what it can. */
+const PARSED_SECTIONS: readonly ParsedGuideSection[] = (() => {
+  const { sections } = splitGuideSections(RAW_GUIDE);
+  const n = Math.min(sections.length, GUIDE_SECTIONS.length);
+  const out: ParsedGuideSection[] = [];
+  for (let i = 0; i < n; i++) {
+    out.push({ ...GUIDE_SECTIONS[i], title: sections[i].title, body: sections[i].body });
+  }
+  return out;
+})();
+
+/** The compact table of contents: every addressable section's id, derived heading title, and stable
+ *  one-line summary, in document order. Small by construction — safe to return whole under any
+ *  tool-result limit. Titles reflect THIS deployment's doc; summaries come from the registry. */
+export function guideToc(): { id: string; title: string; summary: string }[] {
+  return PARSED_SECTIONS.map((s) => ({ id: s.id, title: s.title, summary: s.summary }));
+}
+
+/** Render a SINGLE section's markdown for a given app control-API base, `__BASE__`/`__ENGINE__`
+ *  substituted exactly as {@link renderAgentGuide} does for the whole guide. Returns `undefined` for
+ *  an unknown id (the caller turns that into a 400 listing the valid ids). */
+export function renderGuideSection(id: string, apiBase: string): string | undefined {
+  const section = PARSED_SECTIONS.find((s) => s.id === id);
+  if (!section) return undefined;
+  const base = apiBase.replace(/\/+$/, "");
+  return section.body.replaceAll("__BASE__", base).replaceAll("__ENGINE__", resolveEngineBase());
+}

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"));
+});