@nanobpm/nano-workforce 0.159.1 → 0.161.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **delivery-graph:** getDeliveryGraphVocabulary read tool — closed vocabulary + wait semantics as structured data (S3) ([#616](https://github.com/nanobpm/nano-workforce/issues/616)) ([8d3e90a](https://github.com/nanobpm/nano-workforce/commit/8d3e90a294f9ed195c5cc1b7a30cffb1799a053a)), closes [nanobpm/nano-workforce#605](https://github.com/nanobpm/nano-workforce/issues/605) [#609](https://github.com/nanobpm/nano-workforce/issues/609)
+
 ## [0.159.1](https://github.com/nanobpm/nano-workforce/compare/v0.159.0...v0.159.1) (2026-08-29)
 
 ### Bug Fixes

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/deliveryGraphVocabulary.test.ts

@@ -0,0 +1,102 @@
+// app/deliveryGraphVocabulary.test.ts — the DRIFT GUARD for the delivery-graph vocabulary surface
+// (epic nano-workforce#605, S3/#609). The vocabulary (`getDeliveryGraphVocabulary`) exists so agents
+// discover the closed node/probe/connector vocabulary from the surface instead of reading source; if
+// a new probe kind or connector target lands in the compiler WITHOUT a matching vocabulary entry, the
+// surface silently lies. These tests fail the build in exactly that case: they assert the vocabulary's
+// key sets are byte-identical to the closed sets in `app/deliveryGraph.ts` / `app/readiness.ts` /
+// `app/convergeTargets.ts` (AGENTS.md — "no drift surfaces").
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { CONVERGE_MERGE_TARGET, CONVERGE_TARGET, isConvergeTarget, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
+import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
+import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
+import {
+  DEFAULT_EVERY_MS,
+  DEFAULT_TIMEOUT_MS,
+  EPIC_CONDITIONS,
+  ON_TIMEOUTS,
+  PR_CONDITIONS,
+  PROBE_KINDS,
+} from "./readiness.ts";
+
+const sorted = (xs: readonly string[]): string[] => [...xs].sort();
+
+test("node kinds cover exactly DELIVERY_NODE_KINDS (add a kind to the compiler ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(
+    sorted(vocab.nodeKinds.map((n) => n.kind)),
+    sorted(DELIVERY_NODE_KINDS),
+    "vocabulary node kinds drifted from DELIVERY_NODE_KINDS — extend NODE_KIND_DETAIL",
+  );
+});
+
+test("wait probe kinds cover exactly PROBE_KINDS (add a probe kind ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(
+    sorted(vocab.waitProbeKinds.map((p) => p.kind)),
+    sorted(PROBE_KINDS),
+    "vocabulary wait probe kinds drifted from PROBE_KINDS — extend WAIT_PROBE_DETAIL",
+  );
+});
+
+test("pr / epic probe conditions match the closed PR_CONDITIONS / EPIC_CONDITIONS", () => {
+  const vocab = deliveryGraphVocabulary();
+  const pr = vocab.waitProbeKinds.find((p) => p.kind === "pr");
+  const epic = vocab.waitProbeKinds.find((p) => p.kind === "epic");
+  assert.ok(pr && epic, "pr and epic probe entries must exist");
+  assert.deepEqual(sorted(pr.conditions ?? []), sorted(PR_CONDITIONS), "pr conditions drifted from PR_CONDITIONS");
+  assert.deepEqual(sorted(epic.conditions ?? []), sorted(EPIC_CONDITIONS), "epic conditions drifted from EPIC_CONDITIONS");
+});
+
+test("every real converge-enrollment target has a real vocab entry (add a target ⇒ must add a vocab entry)", () => {
+  const vocab = deliveryGraphVocabulary();
+  const realTargets = vocab.connectorTargets.filter((t) => t.status === "real").map((t) => t.target);
+  for (const target of [CONVERGE_TARGET, CONVERGE_MERGE_TARGET, MERGE_MAIN_TARGET]) {
+    assert.ok(
+      realTargets.includes(target),
+      `converge target '${target}' is missing a 'real' vocabulary entry — extend REAL_CONNECTOR_TARGETS`,
+    );
+    // Guard the classification too: a target the compiler treats as converge-enrollment must be marked real.
+    assert.ok(isConvergeTarget(target), `sanity: '${target}' must be an isConvergeTarget`);
+  }
+  // Exactly the converge set is "real"; nothing else is claimed real, and the stub sentinel is present.
+  assert.deepEqual(sorted(realTargets), sorted([CONVERGE_TARGET, CONVERGE_MERGE_TARGET, MERGE_MAIN_TARGET]));
+  assert.ok(
+    vocab.connectorTargets.some((t) => t.status === "forward-declared"),
+    "the forward-declared stub sentinel must be present so agents learn the real-vs-stub split",
+  );
+});
+
+test("onTimeout options match the closed ON_TIMEOUTS", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(sorted(vocab.onTimeout.map((o) => o.value)), sorted(ON_TIMEOUTS), "onTimeout options drifted from ON_TIMEOUTS");
+});
+
+test("fact types + guard scalar types are derived verbatim", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.deepEqual(vocab.factTypes, [...DELIVERY_FACT_TYPES]);
+  assert.deepEqual(vocab.guardScalarTypes, [...DELIVERY_GUARD_SCALAR_TYPES]);
+});
+
+test("poll-budget carries the real defaults and names the 30-minute trap", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.equal(vocab.pollBudget.defaultTimeoutMs, DEFAULT_TIMEOUT_MS);
+  assert.equal(vocab.pollBudget.defaultEveryMs, DEFAULT_EVERY_MS);
+  assert.match(vocab.pollBudget.rule, /poll\.timeoutMs/);
+  assert.match(vocab.pollBudget.rule, /30 minutes|1800000/);
+});
+
+test("the epic probe states the FEATURE-RUN observation semantics (the #605 evidence gap)", () => {
+  const vocab = deliveryGraphVocabulary();
+  const epic = vocab.waitProbeKinds.find((p) => p.kind === "epic");
+  assert.ok(epic, "epic probe entry must exist");
+  assert.match(epic.observes, /rootRequestKey/i);
+  assert.match(epic.observes, /regardless of/i);
+  assert.match(epic.observes, /feature/i);
+  assert.match(epic.ready, /stage:"merged"|stage:\\"merged\\"|merged.*active:false/);
+});
+
+test("fact-threading rule names the unbound-pr rejection", () => {
+  const vocab = deliveryGraphVocabulary();
+  assert.match(vocab.factThreading.rule, /unbound-pr/);
+});