@nanobpm/nano-workforce 0.159.1 → 0.161.0

package/app/deliveryGraphVocabulary.ts

@@ -0,0 +1,319 @@
+// app/deliveryGraphVocabulary.ts — the delivery-graph vocabulary + wait-probe semantics as
+// STRUCTURED DATA (epic nano-workforce#605, S3/#609). Served by GET /app/api/delivery-graph/vocabulary
+// (operationId `getDeliveryGraphVocabulary`, a read tool projected onto the MCP surface like
+// `getAgentInstructions`), so an agent can DISCOVER the closed node/probe/connector vocabulary and the
+// non-obvious wait semantics from the surface instead of reading source (the evidence session in #605:
+// an agent had to grep `app/readiness.ts` to learn `wait[epic]` also gates a feature run).
+//
+// Derivation over duplication (AGENTS.md — "no drift surfaces"). Everything that has a closed,
+// compiler-enforced source of truth is DERIVED from it, never re-typed:
+//   • node kinds        ← `DELIVERY_NODE_KINDS`      (app/deliveryGraph.ts — the trust boundary)
+//   • fact types        ← `DELIVERY_FACT_TYPES`      (app/deliveryGraph.ts)
+//   • guardable scalars ← `DELIVERY_GUARD_SCALAR_TYPES`
+//   • wait probe kinds  ← `PROBE_KINDS`              (app/readiness.ts — what `parseProbe` accepts)
+//   • pr conditions     ← `PR_CONDITIONS`            (app/readiness.ts)
+//   • epic conditions   ← `EPIC_CONDITIONS`          (app/readiness.ts)
+//   • onTimeout options ← `ON_TIMEOUTS`              (app/readiness.ts)
+//   • poll defaults     ← `DEFAULT_TIMEOUT_MS`/`DEFAULT_EVERY_MS`/`DEFAULT_READINESS_TIMEOUT`
+//   • real connector targets ← `converge`/`converge-merge`/`merge-main` (app/convergeTargets.ts)
+// The prose (body contracts, what each probe OBSERVES, the poll-budget trap, fact-threading) is
+// co-located here; `app/deliveryGraphVocabulary.test.ts` is the drift guard — it fails the build if a
+// probe kind / connector target / node kind is added to the compiler without a vocabulary entry.
+import {
+  CONVERGE_MERGE_TARGET,
+  CONVERGE_TARGET,
+  convergeOnlyForTarget,
+  MERGE_MAIN_TARGET,
+} from "./convergeTargets.ts";
+import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
+import {
+  DEFAULT_EVERY_MS,
+  DEFAULT_READINESS_TIMEOUT,
+  DEFAULT_TIMEOUT_MS,
+  EPIC_CONDITIONS,
+  ON_TIMEOUTS,
+  PR_CONDITIONS,
+  PROBE_KINDS,
+} from "./readiness.ts";
+
+/** A node-kind entry: the closed `kind`, its per-kind config key + required/optional body fields, and
+ * whether it is side-effecting / may emit facts. `body` names the executable engine-native surface the
+ * graph layer schedules onto (the graph layer does NOT re-implement execution). */
+export interface NodeKindEntry {
+  kind: string;
+  configKey: string;
+  requiredFields: string[];
+  optionalFields: string[];
+  sideEffecting: boolean;
+  mayEmit: boolean;
+  summary: string;
+}
+
+/** A wait-probe entry: the closed `kind`, the `match` fields it reads, and — crucially — WHAT it
+ * OBSERVES (the read that decides readiness) and WHEN it is ready. */
+export interface WaitProbeEntry {
+  kind: string;
+  target: string;
+  matchFields: string[];
+  conditions?: string[];
+  observes: string;
+  ready: string;
+  binds?: string[];
+}
+
+/** A connector target: whether it is a REAL side-effecting target (a converge-enrollment target that
+ * dispatches through `submitPr`) or a FORWARD-DECLARED stub (the connector I/O surface is an ADR 0005
+ * non-goal — an unrecognised target returns a deterministic acknowledgement and performs no I/O). */
+export interface ConnectorTargetEntry {
+  target: string;
+  status: "real" | "forward-declared";
+  convergeOnlyDefault?: boolean;
+  summary: string;
+}
+
+/** An `onTimeout` option: what the bounded wait does when the engine timer arm fires. */
+export interface OnTimeoutEntry {
+  value: string;
+  meaning: string;
+}
+
+/** The whole structured vocabulary the read tool returns. */
+export interface DeliveryGraphVocabulary {
+  adr: string;
+  summary: string;
+  nodeKinds: NodeKindEntry[];
+  factTypes: string[];
+  guardScalarTypes: string[];
+  waitProbeKinds: WaitProbeEntry[];
+  connectorTargets: ConnectorTargetEntry[];
+  onTimeout: OnTimeoutEntry[];
+  pollBudget: {
+    defaultTimeoutMs: number;
+    defaultTimeoutIso: string;
+    defaultEveryMs: number;
+    rule: string;
+  };
+  factThreading: {
+    rule: string;
+    details: string[];
+  };
+  guideSection: string;
+}
+
+// ── Node kinds (DERIVED from DELIVERY_NODE_KINDS — the closed allowlist / trust boundary) ─────────
+const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
+  agent: {
+    configKey: "agent",
+    requiredFields: ["jobType"],
+    optionalFields: ["prompt", "converge", "merge"],
+    sideEffecting: true,
+    mayEmit: true,
+    summary:
+      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`). First-class " +
+      "`converge?`/`merge?` cell-policy flags declare review-convergence / landing intent (`merge` " +
+      "requires `converge`); a raw `senior:converge`/`senior:merge` jobType is rejected (`raw-converge-node`). " +
+      "An `agent` that opens a PR emits it as a `pr`-typed fact so downstream connector/wait nodes late-bind it.",
+  },
+  wait: {
+    configKey: "wait",
+    requiredFields: ["kind", "target"],
+    optionalFields: ["match", "poll", "onTimeout", "credentialEnv"],
+    sideEffecting: false,
+    mayEmit: true,
+    summary:
+      "A durable, bounded, read-only readiness probe (a `ReadinessProbe` verbatim). `wait.kind` selects " +
+      "the probe (see waitProbeKinds); `poll` is `{ everyMs?, timeoutMs?, backoff? }`. Binds observed " +
+      "facts (e.g. a merged `pr` binds `mergedSha`).",
+  },
+  human: {
+    configKey: "human",
+    requiredFields: [],
+    optionalFields: ["formKey", "prompt"],
+    sideEffecting: false,
+    mayEmit: true,
+    summary:
+      "A scheduled user task + form (the Tasks inbox). Blocks dependents, SLA-bounded, answerable by a " +
+      "human OR an agent. Config is optional (no required field).",
+  },
+  connector: {
+    configKey: "connector",
+    requiredFields: ["target"],
+    optionalFields: ["dedupeKey", "payload"],
+    sideEffecting: true,
+    mayEmit: true,
+    summary:
+      "An automated, side-effecting outbound action. `payload` for a converge target is " +
+      "`{ pr, convergeOnly?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
+      "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
+      "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
+  },
+};
+
+// ── Wait probe kinds (DERIVED from PROBE_KINDS — what `parseProbe` accepts) ───────────────────────
+const WAIT_PROBE_DETAIL: Record<string, Omit<WaitProbeEntry, "kind">> = {
+  http: {
+    target: "a URL",
+    matchFields: ["status", "bodyIncludes"],
+    observes: "an HTTP GET against `target` (optional `credentialEnv` supplies an Authorization credential by env-key name).",
+    ready: "the response status matches `match.status` (default: any 2xx) and the body contains `match.bodyIncludes` if set.",
+  },
+  command: {
+    target: "a shell command",
+    matchFields: ["exitCode", "stdoutIncludes"],
+    observes: "running `target` as a subprocess (the escape hatch for the long tail — `gh`, `curl`, `docker manifest inspect`).",
+    ready: "the exit code matches `match.exitCode` (default 0) and stdout contains `match.stdoutIncludes` if set.",
+  },
+  npm: {
+    target: "a `pkg@version` (or bare `pkg`)",
+    matchFields: ["version", "stdoutIncludes"],
+    observes: "the npm registry for a published version of the package.",
+    ready: "`match.version` (default: the version in `pkg@version`) is published.",
+  },
+  "github-check": {
+    target: "an `owner/repo@ref`",
+    matchFields: ["conclusion", "checkName"],
+    observes: "the GitHub check runs on `ref`.",
+    ready: "the check run's conclusion matches `match.conclusion` (default `success`), restricted to `match.checkName` if set.",
+  },
+  capability: {
+    target: "a package/context handle",
+    matchFields: ["capabilityRef", "package", "verifyCommand"],
+    observes:
+      "the publish-provenance substrate: which published `package` version first carries the `capabilityRef` " +
+      "issue/PR — an optional `verifyCommand` runs once at the poll-budget boundary as a gated empirical fallback.",
+    ready: "a published version of `match.package` carries `match.capabilityRef` in its provenance.",
+    binds: ["resolvedArtifact"],
+  },
+  pr: {
+    target: "an `owner/repo#N` PR (or a `<node>.pr` fact reference the compiler late-binds at dispatch)",
+    matchFields: ["prState"],
+    conditions: [...PR_CONDITIONS],
+    observes:
+      "the live GitHub state of a single in-flight PR. The ACTION (landing it) stays in a connector/merge " +
+      "node body; this kind only OBSERVES, so it is level-triggered (no missed edge).",
+    ready: "the PR reaches `match.prState` (default `merged`; one of the pr conditions).",
+    binds: ["mergedSha"],
+  },
+  epic: {
+    target:
+      "the epic's durable `planKey` — `owner/repo#NN`, the epic ISSUE, not the engine processInstanceKey, " +
+      "so a resubmit/replay still resolves (may also be a `<node>.fact` late-binding reference)",
+    matchFields: ["epicState"],
+    conditions: [...EPIC_CONDITIONS],
+    observes:
+      "the app's OWN lineage read-model (`/lineage?root=<planKey>`), resolved by `parseEpicLineage` to the " +
+      "thread whose `rootRequestKey` matches the planKey — REGARDLESS OF the thread's `kind` (feature | epic | " +
+      "pr | delivery). Because `app/lineage.ts` lands a FEATURE thread on `stage:\"merged\"` once its PR merges, " +
+      "`wait[epic]` gates a single-PR FEATURE RUN just as well as a plan-fanout epic: point `target` at the " +
+      "feature/epic root issue and it observes that thread's aggregate frontier. A failed/abandoned/mixed epic " +
+      "settles on another terminal (`abandoned`/`resolved`/`converged`) and never reports merged, so it never " +
+      "falsely releases the gate — the bounded wait routes via `onTimeout` instead of hanging.",
+    ready: "the lineage thread reaches `stage:\"merged\" && active:false` (every opened slice/PR landed). `match.epicState` (default `merged`; `done` is a synonym) both mean \"fully merged\".",
+    binds: ["prCount"],
+  },
+};
+
+// ── Connector targets (real = the converge-enrollment set from convergeTargets.ts) ────────────────
+const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
+  {
+    target: CONVERGE_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_TARGET),
+    summary: "Converge-only: drive review convergence and STOP at `converged`, never handing off to the merge loop.",
+  },
+  {
+    target: CONVERGE_MERGE_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
+    summary:
+      "Unit-level land: drive review convergence AND the merge loop, landing the PR onto its OWN base branch " +
+      "(for a unit inside an epic that base is the epic integration branch, never `main` directly).",
+  },
+  {
+    target: MERGE_MAIN_TARGET,
+    status: "real",
+    convergeOnlyDefault: convergeOnlyForTarget(MERGE_MAIN_TARGET),
+    summary:
+      "Graph-level top-level land (two-level merge, ADR 0006 §3): land the graph/epic INTEGRATION PR onto `main`. " +
+      "Dispatch-identical to `converge-merge`; the distinction is the LEVEL, kept a first-class literal.",
+  },
+];
+
+/** The sentinel that describes ANY non-converge target: the connector I/O surface is forward-declared
+ * (ADR 0005 non-goal), so an unrecognised `target` hits the default stub action and performs no real
+ * side effect. Included so a caller learns the real-vs-stub split without reading `deliveryConnector.ts`. */
+const FORWARD_DECLARED_ENTRY: ConnectorTargetEntry = {
+  target: "<any other target>",
+  status: "forward-declared",
+  summary:
+    "Forward-declared stub: the concrete connector I/O scheme is an ADR 0005 non-goal. A target outside the " +
+    "converge-enrollment set returns a deterministic acknowledgement (`connector stub — I/O surface " +
+    "forward-declared`) and fires NO real side effect until a real action is injected.",
+};
+
+const ON_TIMEOUT_DETAIL: Record<string, string> = {
+  escalate: "park a human-in-the-loop escalation (the Tasks inbox) when the bounded wait elapses; a human/agent decides whether to extend the budget or abandon.",
+  fail: "terminate the gate as failed. NOTE: not yet supported on a `wait` node (blocked on engine terminate-end wiring); the compiler rejects `onTimeout: fail` on a wait.",
+  continue: "proceed as if ready when the wait elapses — use ONLY when downstream can tolerate a not-yet-ready upstream (a soft gate).",
+};
+
+/** Build the structured delivery-graph vocabulary. Pure — no I/O; every closed set is imported from
+ * its owning module so this can never silently drift from what the compiler/runner actually accept. */
+export function deliveryGraphVocabulary(): DeliveryGraphVocabulary {
+  const nodeKinds: NodeKindEntry[] = DELIVERY_NODE_KINDS.map((kind) => {
+    const detail = NODE_KIND_DETAIL[kind];
+    if (!detail) throw new Error(`deliveryGraphVocabulary: no detail for node kind '${kind}' (drift — extend NODE_KIND_DETAIL)`);
+    return { kind, ...detail };
+  });
+
+  const waitProbeKinds: WaitProbeEntry[] = PROBE_KINDS.map((kind) => {
+    const detail = WAIT_PROBE_DETAIL[kind];
+    if (!detail) throw new Error(`deliveryGraphVocabulary: no detail for wait probe kind '${kind}' (drift — extend WAIT_PROBE_DETAIL)`);
+    return { kind, ...detail };
+  });
+
+  return {
+    adr: "ADR 0005 — agent-authored delivery graphs",
+    summary:
+      "A delivery graph is a JSON DAG `{ name?, nodes[], edges[] }` an agent authors as DATA (never BPMN/code — " +
+      "the closed node vocabulary is the trust boundary). The agent surface ends at propose → compile → stage; " +
+      "DISPATCH is an operator-only cockpit action. This tool surfaces the closed vocabulary + the non-obvious " +
+      "wait/poll/fact-threading semantics so they are discoverable, not source-only.",
+    nodeKinds,
+    factTypes: [...DELIVERY_FACT_TYPES],
+    guardScalarTypes: [...DELIVERY_GUARD_SCALAR_TYPES],
+    waitProbeKinds,
+    connectorTargets: [...REAL_CONNECTOR_TARGETS, FORWARD_DECLARED_ENTRY],
+    onTimeout: ON_TIMEOUTS.map((value) => {
+      const meaning = ON_TIMEOUT_DETAIL[value];
+      if (!meaning) throw new Error(`deliveryGraphVocabulary: no meaning for onTimeout '${value}' (drift — extend ON_TIMEOUT_DETAIL)`);
+      return { value, meaning };
+    }),
+    pollBudget: {
+      defaultTimeoutMs: DEFAULT_TIMEOUT_MS,
+      defaultTimeoutIso: DEFAULT_READINESS_TIMEOUT,
+      defaultEveryMs: DEFAULT_EVERY_MS,
+      rule:
+        `POLL-BUDGET TRAP: an omitted \`poll\`/\`poll.timeoutMs\` inherits the built-in default budget of ` +
+        `${DEFAULT_READINESS_TIMEOUT} (${DEFAULT_TIMEOUT_MS} ms), re-probing every ${DEFAULT_EVERY_MS} ms. ` +
+        `That default is right for "is the package published yet" but badly wrong for \`wait[pr, merged]\` / ` +
+        `\`wait[epic]\`, which routinely wait hours or days — such a gate would escalate after 30 minutes for ` +
+        `no visible reason (neither compile nor preview surfaces the effective bound). ALWAYS set a realistic ` +
+        `\`poll.timeoutMs\` explicitly on any merge or epic gate.`,
+    },
+    factThreading: {
+      rule:
+        "A node's emitted `fact` is carried to a consumer ONLY by an EDGE. An edge `from` is either a bare " +
+        "`<nodeId>` (the node's completion fact) or a qualified `<nodeId>.<fact>` referencing a declared `emits`. " +
+        "A node that references a fact (e.g. a connector/`wait[pr]` late-binding `open.pr`) MUST have an incoming " +
+        "edge threading that fact from every producer — an unthreaded reference is rejected (`unbound-pr`).",
+      details: [
+        "The referenced fact must be declared in the producer's `emits[]` with the right `type` (a `pr` reference must be `pr`-typed).",
+        "A connector `payload` may OMIT `pr` to auto-bind the SINGLE incoming `pr` fact; with two `pr` facts flowing in you must name one.",
+        "Only scalar facts (`string`/`number`/`boolean`) may be referenced by an edge `when` guard; `artifact`/`version`/`url`/`pr` are not guardable.",
+        "The whole edge set must be a DAG; a self-edge or cycle is rejected.",
+      ],
+    },
+    guideSection: "docs/agent-guide.md §9 (Author and run a delivery graph)",
+  };
+}

package/app/readiness.ts

@@ -56,11 +56,16 @@ export type OnTimeout = "escalate" | "fail" | "continue";
 /** Backoff policy between poll attempts. */
 export type Backoff = "fixed" | "exponential";
 
-const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
-const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
-const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
-const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
-const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
+// The CLOSED per-field vocabularies `parseProbe` validates against — the single runtime source of
+// truth for "which probe kinds / onTimeout options / conditions are legal". Exported so the
+// delivery-graph vocabulary surface (`app/deliveryGraphVocabulary.ts`, S3/#609) DERIVES its
+// structured description from these exact arrays and a drift test fails the build if a kind/condition
+// is added here without a matching vocabulary entry (AGENTS.md: no drift surfaces).
+export const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
+export const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
+export const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
+export const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
+export const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
 
 /** The per-kind readiness predicate. Every field is optional; each kind reads only the ones it
  * understands and applies a sensible default when a field is absent (see the matchers below). */

package/docs/agent-guide.md

@@ -412,6 +412,15 @@ PR #202 → a human does a manual OTP publish → PR #303 consumes the just-publ
 **delivery graph** ([ADR 0005](https://github.com/nanobpm/nano-workforce/blob/main/docs/adr/0005-agent-authored-delivery-graphs.md))
 lets you compose exactly that as **data** and hand it to a generic runner.
 
+> **Discover the vocabulary from the surface.** Everything this section describes — the four
+> node kinds and their body contracts, every `wait` probe kind and **what it observes**, the
+> real-vs-stub connector targets, the `onTimeout` options, the poll-budget trap, and the
+> fact-threading rules — is also available as **structured JSON** from the read tool
+> **`getDeliveryGraphVocabulary`** (`GET __BASE__/delivery-graph/vocabulary`). It is derived
+> from the implementing code (a drift test fails the build if the two disagree), so prose and
+> data can never drift. Fetch it to author against the live vocabulary; this section is the
+> narrative companion.
+
 You author the graph as **JSON — never BPMN or code** (Decision 1: the agent must never
 author the executable artifact; the closed node vocabulary is the trust boundary). Your
 surface ends at **propose → compile → stage**: a single `compile` door validates the JSON,
@@ -741,3 +750,9 @@ Semantics:
   B before its dependency merged. Size `timeoutMs` to how long the epic realistically takes.
 - On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
   output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).
+- **It also gates a single-PR *feature run*, not just a plan-fanout epic.** The gate resolves the
+  lineage thread whose **`rootRequestKey`** matches `target` **regardless of the thread's `kind`**
+  (`feature` | `epic` | `pr` | `delivery`), and `app/lineage.ts` lands a *feature* thread on
+  `stage:"merged"` once its PR merges. So `wait[epic]` targeting a feature/epic **root issue**
+  observes that thread's aggregate frontier and releases on `stage:"merged" && active:false` either
+  way — see `getDeliveryGraphVocabulary` (the `epic` probe entry) for the structured contract.

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