@nanobpm/nano-workforce 0.46.1 → 0.46.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.46.1",
+  "version": "0.46.2",
   "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",

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() };