@nanobpm/nano-workforce 0.160.0 → 0.162.0

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/docs/mcp-runbook.md

@@ -150,6 +150,22 @@ Agents without MCP are unchanged — resolve the instance, then
 live guide. `GET /app/api/agent` and `GET /app/api/agent/skill` keep working exactly as
 before.
 
+### Addressable guide (MCP) — `getAgentGuide`
+
+The full guide is ~43KB — a single `getAgentInstructions` call can overrun a tool-result
+limit. Over MCP, prefer the **addressable** companion tool `getAgentGuide(section?)`
+(`GET /app/api/agent/guide`):
+
+- **No argument** → a compact **table of contents**: every stable section id
+  (`orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`, `debug`,
+  `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`) with a one-line summary.
+- **`section=<id>`** → **only** that section's markdown, small enough to fit a typical
+  limit. An unknown id is rejected with `issues[{path,message}]` listing the valid ids.
+
+The section ids are the single source of truth in `app/agentGuide.ts` (`GUIDE_SECTIONS`),
+derived-and-checked against the authored `docs/agent-guide.md`. The `getAgentInstructions`
+/ `GET /agent` full-guide door is unchanged — the addressable tool is additive.
+
 ## 6. Regression harness — pin the MCP surface from nwf's side
 
 The MCP projection layer (schema shape, argument encoding, session handshake) is

package/e2e/addressable-guide.e2e.ts

@@ -0,0 +1,89 @@
+// Addressable operator-guide regression net (epic #605 slice S5, issue #611).
+//
+// Drives the app's REAL runtime-served MCP endpoint (`/app/mcp`, ADR 0067) via the reusable
+// `e2e/support/mcp-harness.ts` module (slice S1, #607) — it does NOT re-implement the handshake.
+// It PINS the addressable-guide contract from a client's point of view:
+//
+//   • `getAgentGuide` is projected with a `$ref`-free, explicitly-typed input schema (S0 invariant);
+//   • no argument → a compact table of contents listing every stable section id + summary, small
+//     enough to fit a typical tool-result limit;
+//   • `section=<id>` → ONLY that section, far smaller than the whole guide (the defect this fixes:
+//     `getAgentInstructions` returns ~43KB that overran the limit);
+//   • an unknown id → a uniform `issues[{path,message}]` validation error;
+//   • the full-guide fallback door (`getAgentInstructions`) is UNCHANGED — still the whole guide.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { assertSchemaSelfContained, bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+describe("S5 — the addressable operator guide over MCP (#611)", () => {
+  let h: McpHarness;
+  before(async () => {
+    h = await bootMcpHarness();
+  });
+  after(async () => {
+    await h.stop();
+  });
+
+  test("getAgentGuide is projected with a self-contained, explicitly-typed input schema", async () => {
+    const tools = await h.listTools();
+    const tool = tools.find((t) => t.name === "getAgentGuide");
+    assert(tool, "getAgentGuide must be projected onto the MCP surface");
+    assertSchemaSelfContained(tool!.inputSchema, "getAgentGuide");
+    const props = (tool!.inputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+    const section = props.section as { type?: string } | undefined;
+    assert(section, "getAgentGuide must expose a `section` argument");
+    assert.equal(section!.type, "string", "`section` must be an explicitly-typed string");
+  });
+
+  test("no argument returns a compact table of contents with every section id", async () => {
+    const res = await h.callTool("getAgentGuide", {});
+    assert(!res.isError, `getAgentGuide (TOC) must not error: ${res.text}`);
+    const body = res.json as { kind?: string; sections?: { id: string; title: string; summary: string }[] };
+    assert.equal(body.kind, "toc");
+    assert(Array.isArray(body.sections) && body.sections.length > 0, "the TOC must list sections");
+    const ids = body.sections!.map((s) => s.id);
+    for (const id of ["orient", "submit-pr", "submit-epic", "escalations", "delivery-graphs"]) {
+      assert(ids.includes(id), `the TOC must list "${id}"`);
+    }
+    for (const s of body.sections!) {
+      assert(s.title.length > 0 && s.summary.length > 0, `TOC entry "${s.id}" needs a title + summary`);
+    }
+    // The whole point: the TOC is tiny relative to the ~43KB monolith.
+    assert(res.text.length < 4000, "the TOC must fit comfortably under a tool-result limit");
+  });
+
+  test("section=delivery-graphs returns ONLY that section, under a typical result budget", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "delivery-graphs" });
+    assert(!res.isError, `getAgentGuide(delivery-graphs) must not error: ${res.text}`);
+    const body = res.json as { kind?: string; section?: { id: string; instructions: string } };
+    assert.equal(body.kind, "section");
+    assert.equal(body.section?.id, "delivery-graphs");
+    assert(body.section!.instructions.length > 200, "the section must carry real content");
+    assert(!body.section!.instructions.includes("__BASE__"), "placeholders must be substituted");
+
+    // It must be smaller than the full guide the fallback door still serves — a proper subset.
+    const full = await h.callTool("getAgentInstructions", {});
+    assert(res.text.length < full.text.length, "one section must be smaller than the whole guide");
+    assert(res.text.length < 30000, "one section must fit a typical tool-result budget in a single call");
+  });
+
+  test("an unknown section id is rejected with issues[{path,message}]", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "no-such-section" });
+    assert(res.isError, "an unknown section id must surface as a tool-level error");
+    const body = res.json as { issues?: { path: string; message: string }[] };
+    assert(Array.isArray(body.issues) && body.issues.length >= 1, "must answer with issues[]");
+    assert.equal(body.issues![0].path, "section");
+  });
+
+  test("the full-guide fallback door is unchanged — still the whole guide", async () => {
+    const res = await h.callTool("getAgentInstructions", {});
+    assert(!res.isError, `getAgentInstructions must still answer: ${res.text}`);
+    const body = res.json as { instructions?: string };
+    assert(typeof body.instructions === "string", "getAgentInstructions still returns the full guide");
+    // The monolith still contains a section the addressable tool now carves out — no content regression.
+    assert(body.instructions!.includes("delivery graph"), "the full guide still contains every section");
+    assert(body.instructions!.length > 10000, "the full guide door is unshrunk");
+  });
+});

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