@nanobpm/nano-workforce 0.44.1 → 0.45.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.45.0](https://github.com/nanobpm/nano-workforce/compare/v0.44.1...v0.45.0) (2026-08-12)
+
+
+### Features
+
+* **plan:** pin an epic's base branch so the fleet lands on an integration branch ([#125](https://github.com/nanobpm/nano-workforce/issues/125)) ([1c3bfa1](https://github.com/nanobpm/nano-workforce/commit/1c3bfa1a1dbc212e31e510931766f46904dae1a3)), closes [#124](https://github.com/nanobpm/nano-workforce/issues/124) [nanobpm/nano-workforce#124](https://github.com/nanobpm/nano-workforce/issues/124)
+
 ## [0.44.1](https://github.com/nanobpm/nano-workforce/compare/v0.44.0...v0.44.1) (2026-08-11)
 
 

package/app/plan.test.ts

@@ -5,7 +5,7 @@
 // planner could revise forever. `positiveIntEnv` must fall back to the default on any value that
 // is not a positive integer, so the loop is always bounded.
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertThrows } from "#test-assert";
 import { positiveIntEnv } from "./plan.ts";
 
 const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
@@ -292,3 +292,121 @@ test("answerTaskEscalation is a no-op when no open escalation matches the correl
   const r = await answerTaskEscalation(data, engine, "owner/repo#9:missing", "x");
   assertEquals(r.ok, false);
 });
+
+// Coverage for the epic base-branch control (issue nano-ide #124 / 019_plan_base_branch.sql).
+//
+// A plan may pin a base branch so the fleet branches off — and opens every PR against — a long-lived
+// integration branch instead of the repo default, keeping an epic off the default branch (and off any
+// merge-to-default side effect such as auto-publishing) until the integration branch is deliberately
+// merged. `normalizeBaseBranch` decides "unset" (fall back to default), `renderBaseBranchBrief` is the
+// authoritative prompt override, and `startPlan` must persist the branch and seed BOTH the `baseBranch`
+// variable and the `baseBranchBrief` (which rides `appendPrompt`) — or leave them null when unpinned.
+import { InvalidBaseBranchError, normalizeBaseBranch, renderBaseBranchBrief } from "./plan.ts";
+
+test("normalizeBaseBranch: blank/whitespace/undefined → null; a real branch is trimmed", () => {
+  assertEquals(normalizeBaseBranch(undefined), null);
+  assertEquals(normalizeBaseBranch(null), null);
+  assertEquals(normalizeBaseBranch(""), null);
+  assertEquals(normalizeBaseBranch("   "), null);
+  assertEquals(normalizeBaseBranch("  epic/agent-protocol  "), "epic/agent-protocol");
+});
+
+test("normalizeBaseBranch: accepts conservative git-branch shapes", () => {
+  assertEquals(normalizeBaseBranch("main"), "main");
+  assertEquals(normalizeBaseBranch("release-1.2"), "release-1.2");
+  assertEquals(normalizeBaseBranch("feature/x_y.z"), "feature/x_y.z");
+});
+
+test("normalizeBaseBranch: rejects injection-prone / implausible branch names", () => {
+  // `baseBranch` is interpolated into an authoritative agent prompt that carries shell
+  // commands, so anything that isn't a plausible git ref must be rejected at the edge —
+  // not silently rendered into `git`/`gh` snippets or the prompt Markdown.
+  const bad = [
+    "foo bar", // whitespace
+    "-rf", // leading dash → looks like a CLI flag
+    "foo; rm -rf /", // shell metacharacters
+    "foo`whoami`", // command substitution
+    "foo$(id)", // command substitution
+    "foo\nbar", // newline → breaks rendered instructions
+    "foo..bar", // git-illegal double dot
+    "/foo", // leading slash
+    "foo/", // trailing slash
+    "foo.", // trailing dot
+    "foo//bar", // empty path component
+    "foo.lock", // git-reserved .lock suffix
+    "épée", // outside the conservative allowlist
+  ];
+  for (const value of bad) {
+    assertThrows(() => normalizeBaseBranch(value), InvalidBaseBranchError);
+  }
+});
+
+test("renderBaseBranchBrief names the branch in every instruction (branch-off, read, PR base)", () => {
+  const brief = renderBaseBranchBrief("epic/agent-protocol");
+  // Authoritative marker so it overrides the static "default branch" wording.
+  assertEquals(brief.includes("authoritative"), true);
+  assertEquals(brief.includes("git checkout -b feat/<task.id> origin/epic/agent-protocol"), true);
+  assertEquals(brief.includes("gh pr create --base epic/agent-protocol"), true);
+});
+
+test("startPlan pins the base branch: persisted on the row + seeded as baseBranch/baseBranchBrief variables", async () => {
+  const PLAN_KEY = "owner/repo#124";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_escalations: { rows: [], key: "id" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const data = memData(stores);
+  let seen: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      seen = req.variables;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+
+  await startPlan(
+    data,
+    engine,
+    { repo: "owner/repo", number: 124, url: "https://github.com/owner/repo/issues/124", planKey: PLAN_KEY },
+    "  epic/agent-protocol  ",
+  );
+
+  // Persisted (trimmed) on the plan row for the epic UI + resume.
+  assertEquals((stores.plans.rows[0] as any).base_branch, "epic/agent-protocol");
+  // Process variables the implement-task consumes.
+  assertEquals(seen.baseBranch, "epic/agent-protocol");
+  assertEquals(seen.baseBranchBrief.includes("gh pr create --base epic/agent-protocol"), true);
+});
+
+test("startPlan without a base branch keeps default-branch behaviour (null row + null variables)", async () => {
+  const PLAN_KEY = "owner/repo#200";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_escalations: { rows: [], key: "id" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const data = memData(stores);
+  let seen: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      seen = req.variables;
+      return Promise.resolve({ processInstanceKey: "PI-2" });
+    },
+  } as any;
+
+  await startPlan(data, engine, {
+    repo: "owner/repo",
+    number: 200,
+    url: "https://github.com/owner/repo/issues/200",
+    planKey: PLAN_KEY,
+  });
+
+  assertEquals((stores.plans.rows[0] as any).base_branch, null);
+  assertEquals(seen.baseBranch, null);
+  assertEquals(seen.baseBranchBrief, null);
+});

package/app/plan.ts

@@ -51,6 +51,10 @@ export interface Plan {
   // Minted at plan start; baked into the blackboard URL handed to implementer agents. NULL for
   // plans created before the blackboard shipped.
   blackboard_token: string | null;
+  // Optional target base branch (019_plan_base_branch.sql): when set, the fleet branches off this
+  // branch and opens every task PR against it instead of the repository's default branch, landing
+  // the whole epic on a long-lived integration branch. NULL keeps the default-branch behaviour.
+  base_branch: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -185,14 +189,79 @@ export function parseIssue(input: string): ParsedIssue | null {
   return null;
 }
 
+/** Raised when a caller supplies a `baseBranch` that isn't a plausible git branch name. The
+ * value is interpolated into the authoritative implementer prompt (which carries `git`/`gh`
+ * shell snippets and inline-code Markdown), so a non-ref value could break the rendered
+ * instructions or smuggle in a command/prompt fragment — reject it at the edge instead. */
+export class InvalidBaseBranchError extends Error {
+  readonly value: string;
+  constructor(value: string) {
+    super(`invalid base branch name: ${JSON.stringify(value)}`);
+    this.name = "InvalidBaseBranchError";
+    this.value = value;
+  }
+}
+
+/** Conservative allowlist gate for a base-branch name. Stricter than `git check-ref-format` on
+ * purpose: only `[A-Za-z0-9._/-]`, no leading `/`/`.`/`-` (a leading dash reads as a CLI flag),
+ * no trailing `/`/`.`, no `..`/`//`, no empty or `.lock`-suffixed path component, bounded length.
+ * This rejects whitespace, shell metacharacters, command substitution, and newlines outright. */
+function isPlausibleBranchName(s: string): boolean {
+  if (s.length === 0 || s.length > 255) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(s)) return false;
+  if (/^[/.-]/.test(s) || /[/.]$/.test(s)) return false;
+  if (s.includes("..") || s.includes("//")) return false;
+  return s.split("/").every((seg) => seg.length > 0 && !seg.startsWith(".") && !seg.endsWith(".lock"));
+}
+
+/** Normalise a caller-supplied base branch: trim, and treat blank as "unset" (null) so the fleet
+ * falls back to the repository's default branch — the legacy behaviour. A non-blank value that is
+ * not a plausible git branch name is rejected (`InvalidBaseBranchError`) rather than persisted or
+ * rendered into the agent prompt; the operation edge maps that to a 400. */
+export function normalizeBaseBranch(input: string | null | undefined): string | null {
+  const s = (input ?? "").trim();
+  if (s.length === 0) return null;
+  if (!isPlausibleBranchName(s)) throw new InvalidBaseBranchError(s);
+  return s;
+}
+
+/** The per-instance brief appended to an implementer agent's prompt when the plan pins a base
+ * branch. It is authoritative over the static "branch off the default branch" wording in
+ * prompts/feature.md, so the agent branches off — and opens its PR against — the integration
+ * branch, and reads the epic's latest landed state there rather than the repo default branch. */
+export function renderBaseBranchBrief(baseBranch: string): string {
+  return [
+    "",
+    "",
+    "---",
+    "",
+    `**Base branch (authoritative — overrides any "default branch" instruction above): \`${baseBranch}\`.**`,
+    "",
+    `This epic lands on \`${baseBranch}\`, NOT the repository default branch. Everywhere the`,
+    "instructions say \"default branch\", use this branch instead:",
+    "",
+    `- Branch off it: \`git fetch origin ${baseBranch} && git checkout -b feat/<task.id> origin/${baseBranch}\`.`,
+    `- Read the epic's latest landed state from \`${baseBranch}\` (your prerequisites merged there, not into the default branch).`,
+    `- Open your PR against it: \`gh pr create --base ${baseBranch} ...\`.`,
+    "",
+    "Do not target the repository default branch — a PR opened against it will not be merged into the epic.",
+  ].join("\n");
+}
+
 /** Register a plan row (if new) and start the plan-fanout process. Idempotent on
  * planKey: a plan already in flight is not restarted. */
-export async function startPlan(data: DataLayer, engine: EngineClient, parsed: ParsedIssue) {
+export async function startPlan(
+  data: DataLayer,
+  engine: EngineClient,
+  parsed: ParsedIssue,
+  baseBranch: string | null = null,
+) {
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
     return { planKey: parsed.planKey, alreadyRunning: true };
   }
+  const base = normalizeBaseBranch(baseBranch);
   const ts = now();
   // Mint (or reuse, on a re-plan) this plan's blackboard capability token, and render the
   // coordination brief that carries its concrete URL. The token is the credential; agents reach
@@ -235,6 +304,7 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       open_task_corr_key: null,
       open_task_id: null,
       blackboard_token: token,
+      base_branch: base,
       updated_at: ts,
     });
   } else {
@@ -246,6 +316,7 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       status: "planning",
       task_count: 0,
       blackboard_token: token,
+      base_branch: base,
       created_at: ts,
       updated_at: ts,
     });
@@ -265,6 +336,12 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       // out-of-band.
       blackboardUrl: bbUrl,
       blackboardBrief: renderCoordinationBrief(bbUrl),
+      // Optional epic base branch (019_plan_base_branch.sql): the branch the fleet branches off and
+      // opens every PR against instead of the repo default. `baseBranchBrief` rides `appendPrompt`
+      // in the implement-task (like `blackboardBrief`); both are null when no base branch is pinned,
+      // so the agent keeps the default-branch behaviour from prompts/feature.md.
+      baseBranch: base,
+      baseBranchBrief: base == null ? null : renderBaseBranchBrief(base),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/service.test.ts

@@ -347,3 +347,39 @@ test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {
   assertEquals(Object.keys(repoEnvelopeVars("owner/repo", null)).length, 0);
 });
+
+test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", () => {
+  // Defence in depth: a repo that isn't exactly `owner/repo` would build a bogus clone URL, so the
+  // helper emits no envelope (harness falls back to the launch dir) rather than a malformed URL.
+  for (const bad of [
+    "",
+    "noslash",
+    "a/b/c",
+    "owner /repo",
+    "owner/re po",
+    "/repo",
+    "owner/",
+    // A trailing `.git` would build a double-suffixed clone URL (…/owner/repo.git.git).
+    "owner/repo.git",
+    "owner/repo.GIT",
+    // Query/fragment/host-injection characters must never reach the clone URL.
+    "owner/repo?x",
+    "owner/repo#frag",
+    "owner/repo:x",
+    "owner/re~po",
+    // Owner is a GitHub login: no dots or underscores allowed there.
+    "own.er/repo",
+    "own_er/repo",
+  ]) {
+    assertEquals(Object.keys(repoEnvelopeVars(bad, "feat/x")).length, 0, `expected no envelope for "${bad}"`);
+  }
+  // Well-formed repos still emit (guard is not over-eager): hyphens, dots and underscores
+  // are legal in the repo-name segment, mixed case is preserved.
+  for (const good of ["owner/repo", "my-org/my.repo", "Owner123/Repo_2", "a-b/c-d"]) {
+    assertEquals(
+      ((repoEnvelopeVars(good, "feat/x") as any)["io.nanobpm.agentTask"].repository.url),
+      `https://github.com/${good}.git`,
+      `expected envelope for "${good}"`,
+    );
+  }
+});

package/app/service.ts

@@ -292,6 +292,14 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * `task.prompt` header on the service task deep-merges with this over the same namespace. */
 export function repoEnvelopeVars(repo: string, ref: string | null): Record<string, unknown> {
   if (!ref) return {};
+  // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
+  // `owner/repo`), but this is an exported helper the fan-out epic gives many new callers. A repo
+  // that is not exactly `owner/repo` would build a bogus clone URL, so emit nothing (the harness
+  // then falls back to the launch-dir behaviour) rather than handing the harness a malformed URL.
+  // The owner is a GitHub login (alphanumeric + hyphen); the repo-name segment additionally allows
+  // `.` and `_`. A trailing `.git` is rejected outright so we never emit a double-suffixed
+  // `…/owner/repo.git.git`, and the anchored allowlist bars query/fragment/host-injection chars.
+  if (!/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(repo) || /\.git$/i.test(repo)) return {};
   return {
     [AGENT_TASK_NS]: {
       repository: { provider: "github", url: `https://github.com/${repo}.git`, ref },

package/db/migrations/019_plan_base_branch.sql

@@ -0,0 +1,8 @@
+-- Per-plan target base branch (epic base-branch control). When set, the fleet branches off this
+-- branch and opens every task PR against it instead of the repository's default branch, so an
+-- entire epic can land on a long-lived integration branch (e.g. `epic/agent-protocol`) and reach
+-- the default branch — and any merge-to-default side effect such as auto-publishing a package —
+-- only when the integration branch is deliberately merged. NULL keeps the legacy behaviour (the
+-- repo default branch), so pre-migration plans are unaffected.
+
+ALTER TABLE plans ADD COLUMN base_branch TEXT;

package/openapi.yaml

@@ -271,6 +271,15 @@ components:
         issue:
           type: string
           description: "Issue reference: owner/repo#123."
+        baseBranch:
+          type: string
+          description: >-
+            Optional target branch the fleet branches off and opens every PR against, instead of the
+            repository's default branch. Use this to land an entire epic on a long-lived integration
+            branch (e.g. `epic/agent-protocol`) so nothing reaches the default branch — and any
+            merge-to-default side effect, such as auto-publishing a package — until you deliberately
+            merge the integration branch. Blank/omitted keeps the current behaviour (the repo
+            default branch).
     PlanStartByUrl:
       type: object
       additionalProperties: false
@@ -280,6 +289,11 @@ components:
         url:
           type: string
           description: A bare issue URL, when no `owner/repo#123` reference is supplied.
+        baseBranch:
+          type: string
+          description: >-
+            Optional target branch the fleet branches off and opens every PR against, instead of the
+            repository's default branch. See `PlanStartByIssue.baseBranch`.
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startAndMessage.test.ts

@@ -121,6 +121,18 @@ test("startPlanFanout → 400 (not 500) on a missing request body", async () =>
   assertEquals(typeof r.body.error, "string");
 });
 
+test("startPlanFanout → 400 on an invalid baseBranch (not persisted/rendered)", async () => {
+  // A non-blank baseBranch that isn't a plausible git branch name (shell metacharacters here)
+  // must be rejected at the edge as a 400 — never persisted or interpolated into the agent prompt.
+  const res = await startPlanFanout(
+    input({ issue: "owner/repo#123", baseBranch: "epic/agent; rm -rf /" }),
+    app,
+  );
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
 test("startConvergenceLoop narrows the `url` variant (no `pr` key)", async () => {
   await withGithubOff(async () => {
     const { app: capApp } = captureApp();

package/operations/startPlanFanout.ts

@@ -10,7 +10,7 @@
 // ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
 // narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
-import { parseIssue, startPlan } from "../app/plan.ts";
+import { InvalidBaseBranchError, normalizeBaseBranch, parseIssue, startPlan } from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
@@ -26,9 +26,29 @@ export default defineOperation("startPlanFanout", async ({ body }, app) => {
     app.log.warn("start-plan rejected: unparseable issue reference", { raw });
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
   }
-  const result = await startPlan(app.data, app.engine, parsed);
+  // Optional epic base branch: the branch the fleet branches off and opens every PR against instead
+  // of the repo default. Present on both oneOf variants; blank/absent keeps the default-branch
+  // behaviour. It is later interpolated into the authoritative implementer prompt (with `git`/`gh`
+  // shell snippets), so validate/normalise it HERE — a non-blank value that isn't a plausible git
+  // branch name is a 400 at the edge, never persisted or rendered. `normalizeBaseBranch` blank → null.
+  const baseBranch = "baseBranch" in body && typeof body.baseBranch === "string" ? body.baseBranch : null;
+  let normalizedBase: string | null;
+  try {
+    normalizedBase = normalizeBaseBranch(baseBranch);
+  } catch (err) {
+    if (err instanceof InvalidBaseBranchError) {
+      app.log.warn("start-plan rejected: invalid base branch", { baseBranch: err.value });
+      return {
+        status: 400,
+        body: { error: "invalid baseBranch (must be a plausible git branch name, e.g. epic/agent-protocol)" },
+      };
+    }
+    throw err;
+  }
+  const result = await startPlan(app.data, app.engine, parsed, normalizedBase);
   app.log.info("plan fan-out started", {
     planKey: parsed.planKey,
+    baseBranch: normalizedBase ?? "(default branch)",
     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.44.1",
+  "version": "0.45.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/epic.page.json

@@ -35,7 +35,8 @@
         "submitLabel": "Plan & implement",
         "action": { "path": "/app/api/actions/start/plan-fanout", "body": "{{form}}" },
         "fields": [
-          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" }
+          { "key": "issue", "label": "owner/repo#123 or a GitHub issue URL", "type": "text" },
+          { "key": "baseBranch", "label": "Base branch (blank = repo default; e.g. epic/agent-protocol to land the whole epic on an integration branch)", "type": "text" }
         ]
       }
     },
@@ -76,6 +77,7 @@
           "fields": [
             { "field": "repo", "label": "Repository" },
             { "field": "issue_number", "label": "Issue number" },
+            { "field": "base_branch", "label": "Base branch (blank = repo default)" },
             { "field": "outcome", "label": "Outcome" },
             { "field": "open_task_question", "label": "Open escalation question" }
           ]

package/prompts/feature.md

@@ -26,14 +26,26 @@ process with no memory of your last run, the branch name MUST be derivable from
 (`git ls-remote --heads origin feat/<task.id>` or
 `gh pr list --head feat/<task.id> --state all`):
 
-- **It does not exist** → this is a first run. Branch off the default branch.
+- **It does not exist** → this is a first run. Branch off the base branch (see
+  the note below — usually the repository default branch, but an epic may pin an
+  integration branch in your appended task context).
 - **It exists** → this is a **resume**. `git fetch` and check it out, read its diff
   and any open (draft) PR, and **continue from there** — do not restart from
   scratch. Fold in `variables.answer` as the guidance you were waiting on.
 
+## Your base branch (default branch, unless the epic pins one)
+
+Branch off — and open your PR against — the repository's **default branch**,
+UNLESS your appended task context carries a **"Base branch (authoritative)"**
+note pinning an epic integration branch. When it does, that branch wins
+everywhere below: branch off `origin/<that branch>`, read the epic's latest
+landed state there, and pass `gh pr create --base <that branch>`. A PR opened
+against the wrong base will not be merged into the epic.
+
 ## What to do
 
-1. Clone / check out the repository's default branch (first run) or your existing
+1. Clone / check out your base branch (first run — the default branch, or the
+   pinned epic branch if your context names one) or your existing
    `feat/<task.id>` branch (resume — see above).
 2. Implement `task.prompt`. Keep the change scoped to this slice only.
 3. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the

package/prompts/review-round.md

@@ -50,11 +50,21 @@ Because several agents may run on the same host at once:
 
 1. **Read the latest review.** Fetch the newest Copilot review + its inline
    comments on the PR (`gh pr view`, `gh api .../pulls/{n}/reviews`, `.../comments`).
+   Also read Copilot's **suppressed / low-confidence** advisories — the collapsed
+   "low confidence" list Copilot folds into the **review body** (`.../reviews`
+   `body`). These are NOT in the default inline-comment API set, so a plain
+   `.../comments` read misses them; scan the review body for them explicitly.
    If `answer` is present, treat it as the human's decision on the escalation you
    raised last round and act on it first.
 2. **Triage each comment** into: *fix* (correct, worth doing), *nitpick* (apply
    silently), *needs human input* (design/product/tradeoff you can't decide), or
    *push back* (wrong / false positive — reply with evidence, make no change).
+   Triage the suppressed / low-confidence advisories the **same** way — but do not
+   treat "suppressed" as either automatically actionable or automatically ignorable:
+   if one is a **cheap, correct** robustness/correctness win, just do it (a
+   *nitpick*); otherwise **decline it explicitly with a one-line rationale in your
+   `summary`** (e.g. "declined suppressed advisory X — input already validated
+   upstream at Y"). Never silently drop one.
 3. **Act.** Make the code changes for all fixes + nitpicks in your workspace (`cwd`)
    in one coherent, signed-off commit (`git commit -s`). Run the repo's
    build/test/lint locally before pushing. Push to the PR's head branch (the branch
@@ -107,6 +117,9 @@ Consider the PR **converged** when the latest review has no actionable comment:
   comments") and there are no new inline comments, **or**
 - every new comment is a nitpick you already handled or intentionally declined,
   **or**
+- the only remaining items are suppressed / low-confidence advisories you have
+  triaged and either applied or declined-with-rationale (a suppressed advisory
+  you have recorded a decision on does **not** block convergence), **or**
 - Copilot is looping — reiterating a point you already addressed or pushed back
   on (two rounds of the same substantive point = converged).
 

package/resources/processes/plan-fanout.bpmn

@@ -93,7 +93,7 @@
             <zeebe:header key="io.nanobpm.agentTask.task.prompt" value="{{feature}}" />
           </zeebe:taskHeaders>
           <zeebe:ioMapping>
-            <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (blackboardBrief = null) then &#34;&#34; else blackboardBrief)" target="appendPrompt" />
+            <zeebe:input source="=&#34;&#10;&#10;---&#10;&#10;&#34; + task.prompt + (if (blackboardBrief = null) then &#34;&#34; else blackboardBrief) + (if (baseBranchBrief = null) then &#34;&#34; else baseBranchBrief)" target="appendPrompt" />
           </zeebe:ioMapping>
         </bpmn:extensionElements>
         <bpmn:incoming>w_toImpl</bpmn:incoming>