@nanobpm/nano-workforce 0.46.1 → 0.47.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.47.0](https://github.com/nanobpm/nano-workforce/compare/v0.46.2...v0.47.0) (2026-08-12)
+
+
+### Features
+
+* **ui:** Agent Instructions button (copy-paste agent prompt) ([#126](https://github.com/nanobpm/nano-workforce/issues/126)) ([4c022ab](https://github.com/nanobpm/nano-workforce/commit/4c022abcbaa90501cacc27ac0b9c8d77b3f81df1)), closes [nanobpm/nano-ide#196](https://github.com/nanobpm/nano-ide/issues/196)
+
+## [0.46.2](https://github.com/nanobpm/nano-workforce/compare/v0.46.1...v0.46.2) (2026-08-12)
+
+
+### Bug Fixes
+
+* **prompts:** make merge-phase agents emit a machine-readable result ([#133](https://github.com/nanobpm/nano-workforce/issues/133)) ([6584092](https://github.com/nanobpm/nano-workforce/commit/6584092b3ef8f15159c024c080b312ead7484076)), closes [Magikcraft/nano-bpm#746](https://github.com/Magikcraft/nano-bpm/issues/746)
+
 ## [0.46.1](https://github.com/nanobpm/nano-workforce/compare/v0.46.0...v0.46.1) (2026-08-12)
 
 

package/e2e/convergence-loop.e2e.ts

@@ -1,10 +1,14 @@
-// End-to-end pilot for @nanobpm/urban-testkit (nano-ide issue #157, slice S3).
+// End-to-end pilot for @nanobpm/urban-testkit (nano-ide issue #157, slices S3 + S4).
 //
 // Boots this whole Urban app in-process against the WASM engine and a virtual clock via
 // `bootTestApp`, then drives its real ADR-0059 OpenAPI operations by `operationId` — the same
 // spec-driven `/app/api/*` surface a browser, a CI relay, or Swagger hit in production. No socket
 // is opened, no wall-clock is waited on, and no GitHub network is touched.
 //
+// It also adopts the S4 coverage-exhaustive gate: booted with `{ coverage: true }`, it gates a
+// curated `pilot:operations` surface (the operations this pilot claims to own) and prints an
+// informational whole-app coverage snapshot for the operations/workers it does not yet drive.
+//
 // Network isolation: the app's GitHub transport (app/github.ts) is forced to `token` mode with no
 // token, so every best-effort GitHub read short-circuits to `null`/idle instead of reaching out.
 // That keeps the pilot hermetic and deterministic in CI.
@@ -60,6 +64,14 @@ const HARNESS_ENV = {
   NANO_APP_DB_URL: `file:${join(DB_DIR, "app.db")}`,
 } as const;
 
+// The operations this pilot claims to own — the slice of the app's OpenAPI surface it drives end
+// to end. The coverage gate below is scoped to exactly these: if you add one here without a test
+// that drives it, `assertFullCoverage` goes red. (The app declares 10 operations + 16 workers in
+// total; this pilot is deliberately a representative slice, not a whole-app sweep, so it does NOT
+// gate the auto-declared "operations"/"workers" surfaces — it reports them instead, see below.)
+const PILOT_OPERATIONS = ["appendBlackboard", "readBlackboard", "startConvergenceLoop"] as const;
+const PILOT_SURFACE = "pilot:operations";
+
 describe("nano-workforce e2e (urban-testkit pilot)", () => {
   let app: TestApp;
 
@@ -68,9 +80,13 @@ describe("nano-workforce e2e (urban-testkit pilot)", () => {
       savedEnv.set(k, process.env[k]);
       process.env[k] = v;
     }
-    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV });
+    // Enable the S4 coverage gate: `app.coverage` is pre-declared with this app's "operations"
+    // (from openapi.yaml) and "workers" (from nano.app.json) surfaces, and records each hit
+    // automatically as the pilot drives operations / the engine runs jobs.
+    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV, coverage: true });
     // This app declares an `api` binding, so the spec-driven driver must be present.
     assert.ok(app.api, "app.api driver should be defined (nano.app.json declares an `api` binding)");
+    assert.ok(app.coverage, "app.coverage should be defined (booted with { coverage: true })");
   });
 
   after(async () => {
@@ -172,4 +188,35 @@ describe("nano-workforce e2e (urban-testkit pilot)", () => {
     const reconciled = await prs.findOne({ pr_key: prKey });
     assert.equal(reconciled?.status, "abandoned", "reconciler abandoned the terminated PR's row");
   });
+
+  test("coverage gate: every operation the pilot claims to own was exercised", () => {
+    const coverage = app.coverage;
+    assert.ok(coverage);
+
+    // The auto-declared "operations" surface has recorded (across the tests above) exactly the
+    // operations this pilot drove. Mirror the pilot-owned ones into a curated surface and gate
+    // THAT — so the pilot fails the moment a `PILOT_OPERATIONS` entry lacks a driving test, without
+    // demanding whole-app coverage (this is a representative slice, not a full sweep).
+    const report = coverage.report();
+    const opsExercised = new Set(
+      report.surfaces.find((s) => s.surface === "operations")?.exercised ?? [],
+    );
+    coverage.declareSurface(PILOT_SURFACE, PILOT_OPERATIONS);
+    for (const id of PILOT_OPERATIONS) {
+      if (opsExercised.has(id)) coverage.record(PILOT_SURFACE, id);
+    }
+    // Fails, naming any un-driven pilot operation, if PILOT_OPERATIONS grows without a test.
+    coverage.assertFullCoverage({ surfaces: [PILOT_SURFACE] });
+
+    // Informational (non-failing) whole-app snapshot: how much of the app's total surface this
+    // pilot exercises. Surfaces the remaining operations/workers as a roadmap for widening the
+    // pilot, without turning the deliberate slice into a red build.
+    for (const surface of report.surfaces) {
+      const { exercised, declared, missing } = surface;
+      console.log(
+        `[coverage] ${surface.surface}: ${exercised.length}/${declared.length} exercised` +
+          (missing.length ? ` — not yet driven: ${missing.join(", ")}` : ""),
+      );
+    }
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.46.1",
+  "version": "0.47.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.3.0",
+    "@nanobpm/urban-testkit": "^0.4.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

package/pages/home.page.json

@@ -27,6 +27,20 @@
         "variant": "sub"
       }
     },
+    {
+      "type": "button",
+      "id": "agent-instructions",
+      "props": {
+        "label": "🤖 Agent Instructions",
+        "variant": "ghost",
+        "modal": {
+          "title": "Point your agent at Nano Workforce",
+          "description": "Copy this prompt and paste it into your coding agent (Copilot, Claude, etc.). It tells the agent to read this workforce's live operator guide, then help you drive and debug it.",
+          "copyLabel": "Copy prompt",
+          "copyText": "You are helping me operate a running Nano Workforce instance — a durable orchestration app that drives pull requests to review convergence against an automated reviewer, merges them, and can take a whole issue and plan \u2192 implement \u2192 converge it across a fleet of coding agents.\n\nFirst, fetch and read its live operator guide. It tells you how to submit PRs and epics for convergence (including whether to go all the way to merge or stop at review consensus), how to find engine instances and relate them to PRs via the Nano/Camunda-8 REST API, how to inspect the models and prompts, and how to help me untangle escalations:\n\n    curl -sS {{appBase}}app/api/agent\n\nIf this instance is secured with a shared secret (NANO_PR_WEBHOOK_SECRET), add its value as an x-hook-secret header, otherwise the request returns 401:\n\n    curl -sS -H \"x-hook-secret: <secret>\" {{appBase}}app/api/agent\n\nThen follow that guide to help me drive and debug this workforce. If you find a bug or a stuck process, the guide explains how to raise an issue or a PR against nanobpm/nano-workforce."
+        }
+      }
+    },
     {
       "type": "actionForm",
       "id": "submit",

package/prompts/fix-ci.md

@@ -84,3 +84,48 @@ Return a structured result:
 Never report `fixed` unless you actually pushed a change. If nothing was wrong on
 the branch (the failure was transient infrastructure), say so in `summary` and
 return `blocked` so a human can decide whether to just retry the merge.
+
+### How to return it (the wire mechanism)
+
+Your result variables only reach the process if you emit them through the harness's
+result channel. Prose in your normal output is **not** parsed — if you only "say"
+your status in the transcript, the process can't read it, falls back to its safe
+default (a merge escalation a human must clear), and the merge stalls. So emit a
+machine-readable result one of two ways:
+
+1. **Write a JSON object to the file at `$AGENT_RESULT_FILE`** (an env var the
+   harness sets for you). The object's keys become process variables. Examples:
+
+   ```sh
+   # pushed a fix you believe turns the failing checks green:
+   printf '%s' '{"status":"fixed","summary":"Fixed the flaky timeout in auth.test.ts and pushed"}' > "$AGENT_RESULT_FILE"
+   # ordering constraint — must wait for another PR to land first:
+   printf '%s' '{"status":"waiting-on-pr","summary":"Blocked by the linked-issue gate","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
+   # genuinely stuck — a human must decide:
+   printf '%s' '{"status":"blocked","summary":"CI needs an NPM_TOKEN secret I cannot set","question":"Add the NPM_TOKEN repo secret, then answer to rerun."}' > "$AGENT_RESULT_FILE"
+   ```
+
+   Write this file **once**, at the very end, with your final result. Keep it a flat
+   JSON object of exactly the variables named in the return contract above.
+
+2. **Fallback** (only if you truly cannot write the file): print a single line to
+   stdout of the form `::nano:result:: {json}` — e.g.
+
+   ```
+   ::nano:result:: {"status":"fixed","summary":"Corrected the type error in handler.ts and pushed"}
+   ```
+
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
+   accepted as a last resort.
+
+Do not put the result file inside the repo checkout or `git add` it — it lives
+outside your workspace. Exit `0` for every status (including `blocked`/`waiting-on-pr`);
+a non-zero exit means a genuine crash and the job is retried.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** It is the last thing you do on every path out of this job (including after
+a push, or when you conclude nothing can be fixed). If you are ever unsure which status
+applies, return **`blocked`** with a `summary` and a concrete `question` rather than
+leaving without a result — a missing result is treated as an unclassified merge
+escalation that pulls in a human and stalls the merge, so relying on that default
+wastes the attempt.

package/prompts/rebase.md

@@ -100,3 +100,48 @@ was needed, so the process simply re-attempts the merge; the rebase budget
 bounds how many times a still-stuck PR can loop here before it escalates. Reserve
 `blocked` for a genuine semantic conflict you cannot resolve mechanically (or a
 branch that is un-rebaseable), so a human can decide.
+
+### How to return it (the wire mechanism)
+
+Your result variables only reach the process if you emit them through the harness's
+result channel. Prose in your normal output is **not** parsed — if you only "say"
+your status in the transcript, the process can't read it, falls back to its safe
+default (a merge escalation a human must clear), and the merge stalls. So emit a
+machine-readable result one of two ways:
+
+1. **Write a JSON object to the file at `$AGENT_RESULT_FILE`** (an env var the
+   harness sets for you). The object's keys become process variables. Examples:
+
+   ```sh
+   # branch tip now contains the latest base (you pushed a resolved rebase, or it was already up to date):
+   printf '%s' '{"status":"rebased","summary":"Rebased onto main, resolved 2 conflicts in router.ts, pushed"}' > "$AGENT_RESULT_FILE"
+   # ordering constraint — must wait for another PR to land first:
+   printf '%s' '{"status":"waiting-on-pr","summary":"Stacked on the base PR that has not merged","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
+   # genuine semantic conflict — a human must decide which behaviour wins:
+   printf '%s' '{"status":"blocked","summary":"main and this branch both rewrote retry() incompatibly","question":"Should retries stay capped at 3 (main) or become unbounded (this PR)?"}' > "$AGENT_RESULT_FILE"
+   ```
+
+   Write this file **once**, at the very end, with your final result. Keep it a flat
+   JSON object of exactly the variables named in the return contract above.
+
+2. **Fallback** (only if you truly cannot write the file): print a single line to
+   stdout of the form `::nano:result:: {json}` — e.g.
+
+   ```
+   ::nano:result:: {"status":"rebased","summary":"Already up to date; no push needed"}
+   ```
+
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
+   accepted as a last resort.
+
+Do not put the result file inside the repo checkout or `git add` it — it lives
+outside your workspace. Exit `0` for every status (including `blocked`/`waiting-on-pr`);
+a non-zero exit means a genuine crash and the job is retried.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** It is the last thing you do on every path out of this job (including after
+a force-push, or when the branch was already up to date). If you are ever unsure which
+status applies and the branch tip contains the latest base, return **`rebased`** with a
+`summary`; otherwise return **`blocked`** with a concrete `question` — never leave
+without a result. A missing result is treated as an unclassified merge escalation that
+pulls in a human and stalls the merge, so relying on that default wastes the attempt.

package/prompts/review-round.md

@@ -181,7 +181,7 @@ default, and you waste a round. So emit a machine-readable result one of two way
    ::nano:result:: {"status":"converged","summary":"No actionable comments left"}
    ```
 
-   The harness reads the **last** such line. A trailing ```json fenced block is also
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
    accepted as a last resort.
 
 Do not put the result file inside the repo checkout or `git add` it — it lives

package/scripts/check-agent-prompts.test.ts

@@ -30,11 +30,11 @@ function fixture(files: Record<string, string>): string {
   return root;
 }
 
-test("passes when every {{token}} resolves to a non-blank template", async () => {
+test("passes when every {{token}} resolves to a non-blank template that emits a result", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header("{{review-round}}"),
-    "prompts/review-round.md": "# Round\nDo the thing.",
+    "prompts/review-round.md": "# Round\nDo the thing, then write your result to `$AGENT_RESULT_FILE`.",
   });
   const res = checkAgentPrompts(root);
   assertEquals(res.errors, []);
@@ -75,6 +75,31 @@ test("fails when a reserved agent-prompt header is blank", async () => {
   assert(res.errors.some((e) => e.includes("is empty")));
 });
 
+test("fails when an agent-prompt template omits the machine-readable result mechanism", async () => {
+  // A prompt wired as an agent's base prompt must tell it to write $AGENT_RESULT_FILE (or use the
+  // ::nano:result:: fallback). Without it the agent finishes with prose only, `status` comes back
+  // blank, and the status gateway escalates/stalls — the fix-ci/rebase gap behind #746's stuck merge.
+  const root = await fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "prompts/review-round.md": "# Round\nReturn status: converged. (but never says how to emit it)",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("{{review-round}}") && e.includes("AGENT_RESULT_FILE")));
+});
+
+test("passes when an agent-prompt template emits via the ::nano:result:: fallback", async () => {
+  const root = await fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "prompts/review-round.md": "# Round\nEmit `::nano:result:: {\"status\":\"converged\"}` at the end.",
+  });
+  const res = checkAgentPrompts(root);
+  assertEquals(res.errors, []);
+  assert(res.ok);
+});
+
 test("checks the real repo: all committed agent prompts resolve", () => {
   // The guard must be green against the actual app it protects — this is the case CI relies on.
   const repoRoot = decodeURIComponent(new URL("../", import.meta.url).pathname);
@@ -82,7 +107,7 @@ test("checks the real repo: all committed agent prompts resolve", () => {
   assertEquals(res.errors, []);
   assert(res.ok);
   // Every senior:* agent prompt header in the three processes must have resolved.
-  for (const t of ["review-round", "fix-ci", "plan", "plan-review", "feature", "trial-merge"]) {
+  for (const t of ["review-round", "fix-ci", "plan", "plan-review", "feature", "trial-merge", "rebase", "retro"]) {
     assert(res.resolved.includes(t), `expected template ${t} to resolve`);
   }
 });

package/scripts/check-agent-prompts.ts

@@ -72,6 +72,33 @@ function hasBlankAgentPromptHeader(bpmn: string): boolean {
   return false;
 }
 
+// The template tokens a model wires as an agent's base prompt, e.g. the `fix-ci` in
+// `value="{{fix-ci}}"` on an `io.nanobpm.agentTask.task.prompt` header. These templates *drive an
+// agent*, so each must teach it to emit a machine-readable result (see agentPromptEmitsResult).
+function agentPromptTokens(bpmn: string): string[] {
+  const tokens: string[] = [];
+  const re = /<zeebe:header\s+key="([^"]*)"\s+value="([^"]*)"\s*\/?>/g;
+  let m = re.exec(bpmn);
+  while (m !== null) {
+    if (m[1] === AGENT_PROMPT_HEADER) {
+      const tok = /^\{\{\s*([^}]+?)\s*\}\}$/.exec(m[2].trim());
+      if (tok) tokens.push(tok[1]);
+    }
+    m = re.exec(bpmn);
+  }
+  return tokens;
+}
+
+// A prompt that drives an agent must tell it how to return a machine-readable result — the
+// `$AGENT_RESULT_FILE` write (or the `::nano:result::` stdout fallback). Without it the agent can
+// finish with prose only, its `status` variable comes back empty, the status gateway falls through
+// to its default escalation arm, and the run parks a human escalation / stalls the merge (the
+// fix-ci/rebase gap behind Magikcraft/nano-bpm#746's stuck merge). Prose is never parsed, so this
+// instruction is load-bearing, not documentation.
+function agentPromptEmitsResult(body: string): boolean {
+  return body.includes("AGENT_RESULT_FILE") || body.includes("::nano:result::");
+}
+
 export interface CheckResult {
   ok: boolean;
   errors: string[];
@@ -82,6 +109,7 @@ export interface CheckResult {
 export function checkAgentPrompts(root: string): CheckResult {
   const errors: string[] = [];
   const resolved = new Set<string>();
+  const agentTokens = new Set<string>();
 
   const manifestPath = join(root, "nano.app.json");
   if (!existsSync(manifestPath)) {
@@ -127,6 +155,20 @@ export function checkAgentPrompts(root: string): CheckResult {
     if (hasBlankAgentPromptHeader(content)) {
       errors.push(`${rel}: a reserved "${AGENT_PROMPT_HEADER}" header is empty (agent would run prompt-less)`);
     }
+    for (const tok of agentPromptTokens(content)) agentTokens.add(tok);
+  }
+
+  // Every template wired as an agent's base prompt must teach the agent to emit a machine-readable
+  // result; a prose-only agent leaves `status` blank and the process escalates/stalls.
+  for (const tok of [...agentTokens].sort()) {
+    const body = templates[tok];
+    if (body != null && body.trim() !== "" && !agentPromptEmitsResult(body)) {
+      errors.push(
+        `template {{${tok}}} drives an agent but never tells it to write $AGENT_RESULT_FILE ` +
+          `(or the ::nano:result:: fallback) — the agent can finish with prose only, leaving its ` +
+          `status blank so the process escalates/stalls`,
+      );
+    }
   }
 
   return { ok: errors.length === 0, errors, resolved: [...resolved].sort() };