@nanobpm/nano-workforce 0.73.0 → 0.74.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.74.0](https://github.com/nanobpm/nano-workforce/compare/v0.73.1...v0.74.0) (2026-08-16)
+
+
+### Features
+
+* **feature:** thread optional custom instructions to the implementation agent ([#247](https://github.com/nanobpm/nano-workforce/issues/247)) ([8b65495](https://github.com/nanobpm/nano-workforce/commit/8b65495a739b01560937fa108ed4def16c3ffd85))
+
+## [0.73.1](https://github.com/nanobpm/nano-workforce/compare/v0.73.0...v0.73.1) (2026-08-16)
+
+
+### Bug Fixes
+
+* **merge:** treat a Depends-on ref that is not a PR as non-blocking ([#246](https://github.com/nanobpm/nano-workforce/issues/246)) ([c800f81](https://github.com/nanobpm/nano-workforce/commit/c800f81b02b3a9a787d79552f4e5eef9971e3edf)), closes [Magikcraft/nano-bpm#806](https://github.com/Magikcraft/nano-bpm/issues/806)
+
 # [0.73.0](https://github.com/nanobpm/nano-workforce/compare/v0.72.1...v0.73.0) (2026-08-15)
 
 

package/app/feature.test.ts

@@ -114,6 +114,42 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.status, null);
 });
 
+test("startFeature: custom instructions ride the instance as a variable (trimmed)", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-3" });
+    },
+  } as any;
+  await startFeature(
+    memData({ feature_runs: { rows: [], key: "feature_key" } }),
+    engine,
+    PARSED,
+    "main",
+    false,
+    false,
+    "  prefer Deno; keep the diff small  ",
+  );
+  assertEquals(captured.variables.customInstructions, "prefer Deno; keep the diff small");
+});
+
+test("startFeature: blank/absent custom instructions are seeded as null", async () => {
+  let captured: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      captured = req;
+      return Promise.resolve({ processInstanceKey: "PI-4" });
+    },
+  } as any;
+  // Absent (default arg) → null.
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false);
+  assertEquals(captured.variables.customInstructions, null);
+  // Whitespace-only → null (so the appendPrompt FEEL skips the block instead of appending an empty heading).
+  await startFeature(memData({ feature_runs: { rows: [], key: "feature_key" } }), engine, PARSED, "main", false, false, "   ");
+  assertEquals(captured.variables.customInstructions, null);
+});
+
 test("startFeature: an already-running run short-circuits (no new instance)", async () => {
   const stores = {
     feature_runs: {

package/app/feature.ts

@@ -267,7 +267,14 @@ export async function startFeature(
   baseBranch: string,
   converge: boolean,
   autoMerge: boolean,
+  customInstructions: string | null = null,
 ) {
+  // Operator free-text steering for the implementation agent (issue #172 follow-on): blank/absent →
+  // null so the implement task's `appendPrompt` FEEL (`customInstructions = null`) skips the block
+  // rather than appending an empty "Operator custom instructions" heading.
+  const instructions = typeof customInstructions === "string" && customInstructions.trim() !== ""
+    ? customInstructions.trim()
+    : null;
   const table = featureRuns(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !FEATURE_TERMINAL_STATUSES.includes(existing.status)) {
@@ -356,6 +363,10 @@ export async function startFeature(
       // brief rides `appendPrompt` in the implement task, exactly like the epic implementer.
       baseBranch: base,
       baseBranchBrief: renderBaseBranchBrief(base),
+      // Optional operator steering, appended to the implement agent's prompt via the implement
+      // task's `appendPrompt` FEEL (feature.bpmn). Null when none was supplied; persists on the
+      // instance so it also rides the answer-loop redispatch back into the same implement task.
+      customInstructions: instructions,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles } from "./github.ts";
+import { BaseBranchMustExistError, ensureBaseBranch, fetchPrFiles, isNotAPullRequestError } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -236,3 +236,26 @@ test("ensureBaseBranch: missing non-epic/* branch throws BaseBranchMustExistErro
   // A rejected non-epic/* base must never spawn a wrong-rooted branch.
   assertEquals(state.creates.length, 0);
 });
+
+// A `Depends-on:` ref that resolves to an issue (or a non-existent number) can never merge, so the
+// merge-poller's dependency gate must treat it as non-blocking rather than wedging forever — the
+// exact wedge behind Magikcraft/nano-bpm#806 declaring `Depends-on:` its epic tracking *issue*
+// #796. `isNotAPullRequestError` is the discriminator: it must fire for both transports' "not a PR"
+// signals and stay false for transient failures (which must keep the dependency blocking).
+test("isNotAPullRequestError: gh GraphQL 'not a PullRequest' → true", () => {
+  const err = new Error(
+    "GraphQL: Could not resolve to a PullRequest with the number of 796. (repository.pullRequest)",
+  );
+  assertEquals(isNotAPullRequestError(err), true);
+});
+
+test("isNotAPullRequestError: token-mode 404 → true", () => {
+  assertEquals(isNotAPullRequestError(new Error("github 404 Not Found")), true);
+});
+
+test("isNotAPullRequestError: transient failures stay blocking (false)", () => {
+  assertEquals(isNotAPullRequestError(new Error("github 502 Bad Gateway")), false);
+  assertEquals(isNotAPullRequestError(new Error("API rate limit exceeded")), false);
+  assertEquals(isNotAPullRequestError(new Error("fetch failed")), false);
+  assertEquals(isNotAPullRequestError(null), false);
+});

package/app/github.ts

@@ -496,6 +496,20 @@ function allCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** True when `err` is GitHub reporting that a ref which parsed as `owner/repo#N` is not a pull
+ * request — either it's an issue (issues and PRs share GitHub's number space, so an issue number
+ * is indistinguishable from a PR number by shape alone) or the number does not exist. Both
+ * transports surface here: `gh` mode throws the GraphQL message "Could not resolve to a
+ * PullRequest with the number of N", and token mode throws `github 404 …` from
+ * `GET /repos/{repo}/pulls/{N}`. A ref that is not a pull request can never merge, so a caller
+ * gating a merge queue on it (see `isDepMerged`) must treat it as non-blocking instead of wedging
+ * forever. Transient failures (rate-limit, 5xx, network) deliberately return `false` so the caller
+ * keeps waiting/retrying rather than silently clearing a real dependency. */
+export function isNotAPullRequestError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /could not resolve to a pullrequest/i.test(msg) || /\bgithub 404\b/i.test(msg);
+}
+
 export async function fetchPrState(
   repo: string,
   number: number | string,

package/app/service.ts

@@ -20,6 +20,7 @@ import {
   fetchPrReviews,
   fetchPrState,
   hasPendingCopilotReviewer,
+  isNotAPullRequestError,
   type MergeMethod,
   type PrState,
   requestCopilotReview,
@@ -738,8 +739,23 @@ async function isDepMerged(data: DataLayer, depKey: string, token: string): Prom
   if (tracked && tracked.status === "merged") return true;
   const parsed = parsePr(depKey);
   if (!parsed) return true; // unparseable dep can't be checked on GitHub → treat as cleared so it never wedges the PR
-  const st = await fetchPrState(parsed.repo, parsed.number, token);
-  return st?.merged ?? false;
+  try {
+    const st = await fetchPrState(parsed.repo, parsed.number, token);
+    return st?.merged ?? false;
+  } catch (err) {
+    // A ref that GitHub cannot resolve to a *pull request* — it's an issue (issues and PRs share
+    // GitHub's number space) or the number doesn't exist — can never merge, so it cannot gate a
+    // merge queue. Treat it as cleared (non-blocking) rather than wedging the run at `wait-deps`
+    // forever, as happened when a PR body declared `Depends-on:` its epic tracking *issue*
+    // (Magikcraft/nano-bpm#806 → #796). Transient failures rethrow so the poller logs and retries.
+    if (isNotAPullRequestError(err)) {
+      console.warn(
+        `[poller] dep ${depKey} is not a mergeable pull request (issue or missing) — treating as non-blocking`,
+      );
+      return true;
+    }
+    throw err;
+  }
 }
 
 /** Flip a PR into the transient `merging` status and publish the correlating message, reverting

package/openapi.yaml

@@ -668,6 +668,13 @@ components:
           description: >-
             Opt in to sharing a custom integration base branch with another already-active epic. See
             `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run
+            (via the implement task's `appendPrompt`). Blank/whitespace is treated as absent. Persists
+            on the instance, so it also applies to the agent's answer-loop redispatch.
     FeatureStartByUrl:
       type: object
       additionalProperties: false
@@ -698,6 +705,12 @@ components:
         allowSharedBase:
           type: boolean
           description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        customInstructions:
+          type: string
+          maxLength: 8000
+          description: >-
+            OPTIONAL free-text steering appended to the implementation agent's prompt for this run.
+            See `FeatureStartByIssue.customInstructions`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startFeature.ts

@@ -115,12 +115,18 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
-  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge);
+  // Optional operator steering threaded to the implementation agent's prompt. Empty/whitespace is
+  // normalized to null downstream (startFeature) so it never appends an empty instruction block.
+  const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
+    ? body.customInstructions
+    : null;
+  const result = await startFeature(app.data, app.engine, parsed, normalizedBase, converge, autoMerge, customInstructions);
   app.log.info("feature run started", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
+    hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
   });
   return { status: 202, body: result };

package/package.json

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

package/pages/feature.page.json

@@ -42,6 +42,7 @@
         "fields": [
           { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text", "required": true, "requiredMessage": "An issue reference is required (owner/repo#123 or an issue URL)" },
           { "key": "baseBranch", "label": "Base branch: the branch the PR targets, e.g. main. A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text", "required": true, "requiredMessage": "Name the branch the PR targets (e.g. main or epic/agent-protocol)" },
+          { "key": "customInstructions", "label": "Custom instructions (optional) \u2014 extra steering appended to the implementation agent's prompt, e.g. \u201cprefer Deno; keep the diff small; add integration tests\u201d", "type": "text" },
           { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
           { "key": "autoMerge", "label": "Auto-merge \u2014 after convergence, drive the merge-loop (only applies when Converge is on)", "type": "checkbox" },
           { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default", "type": "checkbox" },

package/resources/processes/feature.bpmn

@@ -44,7 +44,7 @@
           <zeebe:linkedResource resourceId="feature.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
         </zeebe:linkedResources>
         <zeebe:ioMapping>
-          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief)" target="appendPrompt" />
+          <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief) + (if (customInstructions = null) then &#34;&#34; else &#34;&#10;&#10;---&#10;&#10;## Operator custom instructions&#10;&#10;The operator supplied these instructions for this run — follow them:&#10;&#10;&#34; + customInstructions)" target="appendPrompt" />
           <zeebe:output source="=status" target="status" />
           <zeebe:output source="=question" target="question" />
         </zeebe:ioMapping>