@nanobpm/nano-workforce 0.142.0 → 0.144.0

package/app/deliveryRunner.test.ts

@@ -11,7 +11,7 @@
 // proven end-to-end in `e2e/delivery-graph.e2e.ts`.
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
-import { prepareDeliveryGraph, runDeliveryGraph } from "./deliveryRunner.ts";
+import { prepareDeliveryGraph, renderIdempotencyPreamble, runDeliveryGraph } from "./deliveryRunner.ts";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
 
 const GRAPH: DeliveryGraph = {
@@ -70,7 +70,9 @@ test("nodeInputs seeds the exact per-kind fields each node's subProcess ioMappin
   const byField = (pred: (v: Record<string, unknown>) => boolean) => Object.values(inputs).find((v) => pred(v as Record<string, unknown>)) as Record<string, unknown> | undefined;
 
   const agent = byField((v) => v.jobType === "senior:feature");
-  assertEquals(agent, { jobType: "senior:feature", appendPrompt: "un-draft + merge #B", timeout: "PT10M" });
+  // Every agent node's appendPrompt is prefixed with the idempotency preflight (#551), then the
+  // authored prompt (this node declares no emits, so the emit contract adds nothing).
+  assertEquals(agent, { jobType: "senior:feature", appendPrompt: renderIdempotencyPreamble() + "un-draft + merge #B", timeout: "PT10M" });
 
   const wait = byField((v) => "gateKey" in v);
   assertEquals(wait?.gateKey, "run-7:n3");
@@ -135,20 +137,60 @@ test("agent node classifier-emit contract (#506): a declared `emits` threads the
   };
   const p = await prepareOk(graph);
   const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
-  const adopt = agents.find((v) => String(v.appendPrompt).startsWith("adopt the package"));
-  const plain = agents.find((v) => String(v.appendPrompt).startsWith("just implement it"));
+  const adopt = agents.find((v) => String(v.appendPrompt).includes("adopt the package"));
+  const plain = agents.find((v) => String(v.appendPrompt).includes("just implement it"));
 
-  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact.
+  // The emit-declaring node keeps its authored prompt AND gains the emit contract naming its fact,
+  // both AFTER the unconditional idempotency preflight (#551).
   assert(adopt, "the emit-declaring agent node must be seeded");
   const adoptPrompt = String(adopt?.appendPrompt);
-  assert(adoptPrompt.startsWith("adopt the package"), "the authored prompt is preserved as the prefix");
+  assert(adoptPrompt.startsWith(renderIdempotencyPreamble()), "the idempotency preflight leads every agent prompt");
+  assert(adoptPrompt.includes("adopt the package"), "the authored prompt is preserved after the preflight");
   assert(adoptPrompt.includes("Classifier emit contract"), `the emit contract must be threaded in, got: ${adoptPrompt}`);
   assert(adoptPrompt.includes("`result`") && adoptPrompt.includes("(string)"), "the declared fact name + type must be surfaced to the agent");
   assert(adoptPrompt.includes("breaking | compatible"), "the fact's optional description rides the contract");
   assert(adoptPrompt.includes("AGENT_RESULT_FILE"), "the contract names the completion channel the fact rides");
 
-  // A node that declares NO facts is untouched — appendPrompt is exactly the authored prompt.
-  assertEquals(plain?.appendPrompt, "just implement it");
+  // A node that declares NO facts still carries the preflight, then exactly the authored prompt — the
+  // emit contract contributes nothing.
+  assertEquals(plain?.appendPrompt, renderIdempotencyPreamble() + "just implement it");
+});
+
+
+test("agent node idempotency preflight (#551): every agent prompt leads with adopt-and-report guidance; non-agent nodes are untouched", async () => {
+  // #551: a delivery agent node dispatches a raw retry-carrying `senior:feature` job with no
+  // PR-existence guard, so a re-dispatch opened a DUPLICATE PR (instance 43077 n0 → #979/#980). The
+  // fix threads an unconditional idempotency preflight into every agent node's `appendPrompt` telling
+  // the agent to CHECK for an existing claim/open PR and ADOPT-AND-REPORT it rather than open a second.
+  // Pin: (a) both agent nodes lead with the preflight regardless of emits, (b) it names the check +
+  // the adopt-and-report contract, and (c) wait/human/connector nodes never carry it.
+  const graph: DeliveryGraph = {
+    name: "idempotency",
+    nodes: [
+      { id: "emitter", kind: "agent", agent: { jobType: "senior:feature", prompt: "do X" }, emits: [{ name: "result", type: "string" }] },
+      { id: "plain", kind: "agent", agent: { jobType: "senior:feature", prompt: "do Y" } },
+      { id: "gate", kind: "wait", wait: { kind: "pr", target: "owner/repo#1", match: { prState: "merged" } } },
+    ],
+    edges: [{ from: "emitter", to: "plain" }, { from: "plain", to: "gate" }],
+  };
+  const p = await prepareOk(graph);
+  const preamble = renderIdempotencyPreamble();
+
+  // Every agent node leads with the preflight, ahead of its authored prompt (and any emit contract).
+  const agents = Object.values(p.nodeInputs).filter((v) => "jobType" in v) as Array<Record<string, unknown>>;
+  assertEquals(agents.length, 2, "both agent nodes are seeded");
+  for (const a of agents) {
+    const prompt = String(a.appendPrompt);
+    assert(prompt.startsWith(preamble), "the preflight is the leading prefix of every agent prompt");
+    assert(prompt.includes("Idempotency preflight"), "the preflight heading is present");
+    assert(prompt.includes("DO NOT open a second PR") || prompt.includes("do not open a second"), "it forbids a duplicate PR");
+    assert(prompt.includes("adopt and report"), "it names the adopt-and-report contract");
+  }
+
+  // The preflight is unconditional but AGENT-ONLY — a wait node's seed carries no prompt at all.
+  const wait = Object.values(p.nodeInputs).find((v) => "gateKey" in v) as Record<string, unknown> | undefined;
+  assert(wait, "the wait node is seeded");
+  assert(!("appendPrompt" in wait!), "a non-agent node never carries the agent idempotency preflight");
 });
 
 

package/app/deliveryRunner.ts

@@ -178,6 +178,48 @@ function rewriteProcessId(bpmn: string, processDefinitionId: string): string {
     .replace(`bpmnElement="${DELIVERY_GRAPH_PROCESS_ID}"`, `bpmnElement="${processDefinitionId}"`);
 }
 
+/** The idempotency preflight prepended to EVERY `agent` node's `appendPrompt` (issue #551). A delivery
+ * agent node dispatches a raw `senior:feature` job with no `feature_runs` idempotency row and no
+ * PR-existence guard, and the job carries retries — so an idle/timeout re-dispatch hands the SAME
+ * "implement #N" prompt to another worker, who (in a fresh worktree, blind to the first) opens a SECOND
+ * PR on the same issue. That is exactly how instance 43077's node n0 (`Magikcraft/nano-bpm#977`) spawned
+ * the #979/#980 duplicate. The advisory AGENTS.md claim protocol did not prevent it because nothing tells
+ * the *agent* to look first. This block does: a preflight that makes the agent **adopt-and-report** an
+ * existing PR instead of opening a duplicate. Adopt-and-report (not "escalate") because a delivery agent
+ * node has NO in-band escalate route — an in-flight agent can only complete (job done) or fail (which
+ * raises an incident, the stuck state we are avoiding); adopting completes the completion-barrier node
+ * cleanly, with no duplicate and no incident. Fixed wording (no derived data), so identical graphs still
+ * compile+seed deterministically; it is unconditional because every agent node that opens a PR is exposed
+ * to the same re-dispatch race. This is an advisory guard — the categorical fix (an engine-level
+ * preflight guard, or routing the node through the idempotent feature cell) is tracked as a follow-up. */
+export function renderIdempotencyPreamble(): string {
+  return [
+    "## Idempotency preflight (delivery graph) — check BEFORE you implement",
+    "",
+    "This node may be re-dispatched (a retry after a timeout) or run in parallel with another worker.",
+    "BEFORE you write ANY code, confirm nobody is already delivering the issue you were asked to implement:",
+    "",
+    "1. Read that issue's comments for an existing **claim** (a comment beginning `Claimed —`, an",
+    "   assignee, or a referenced in-progress branch/worktree).",
+    "2. List the repository's OPEN pull requests for one that already references the issue (a `Closes",
+    "   #N`, the issue number in its title/body, or a branch named for it).",
+    "",
+    "If an existing claim OR an open PR already covers this issue, DO NOT open a second PR — a duplicate",
+    "PR is a defect: it splits review and collides in the same files. Instead **adopt and report**:",
+    "complete WITHOUT making any changes and return the EXISTING PR as your result — put it in your `pr`",
+    "field (a URL or `owner/repo#N`) and complete with your normal success status, with a `summary` that",
+    "names the PR you adopted. This satisfies the node cleanly; a downstream door (or a human) drives the",
+    "existing PR the rest of the way.",
+    "",
+    "Only implement — and open your own PR — when NO claim and NO open PR exist for the issue.",
+    "",
+    "---",
+    "",
+    "",
+  ].join("\n");
+}
+
+
 /** Render the classifier-emit contract appended to an `agent` node's `appendPrompt` (issue #506) — the
  * instruction that turns a declared `emits[]` into completion variables a downstream guarded split (S7)
  * can route on. A `senior:*` fleet agent completes with the Output-contract envelope (`status`,
@@ -231,7 +273,7 @@ function buildNodeInput(
       // truth. A no-emit node appends nothing, so a plain implementation node is unchanged.
       const basePrompt = node.agent.prompt ?? "";
       const emits = Array.isArray(node.emits) ? node.emits.map((f) => ({ ...f })) : [];
-      return { jobType: node.agent.jobType, appendPrompt: basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
+      return { jobType: node.agent.jobType, appendPrompt: renderIdempotencyPreamble() + basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     }
     case "wait": {
       const probe = parseProbe(node.wait);

package/app/stepAxis.test.ts

@@ -0,0 +1,142 @@
+// Unit coverage for the ONE canonical progress step axis (app/stepAxis.ts) — the single source of the
+// derived stepper's vocabulary, cell→step mapping, terminal-tier normalization, and the deterministic
+// parallel-frontier reduction (ADR 0006 §4b, issue #541 / S7).
+
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { STAGE_DONE_STATUSES, STAGE_KEYS } from "./stage.ts";
+import {
+  CELL_STEP,
+  DONE_TERMINAL,
+  type FrontierBranch,
+  INITIAL_STEP,
+  reduceFrontier,
+  STEP_KEYS,
+  stepOrdinal,
+  terminalTier,
+  TERMINAL_STEP,
+} from "./stepAxis.ts";
+
+test("STEP_KEYS is SEEDED from STAGE_KEYS — the axis cannot fork across surfaces", () => {
+  assertEquals([...STEP_KEYS], [...STAGE_KEYS]);
+  // The two lifecycle bookends are the head/tail of the shared axis.
+  assertEquals(INITIAL_STEP, STAGE_KEYS[0]);
+  assertEquals(INITIAL_STEP, "Requested");
+  assertEquals(TERMINAL_STEP, STAGE_KEYS[STAGE_KEYS.length - 1]);
+  assertEquals(TERMINAL_STEP, "Done");
+});
+
+test("the explicit cell→step mapping collapses every process cell onto an existing STAGE_KEYS bracket (no new axis entries)", () => {
+  // The three executable cells map to their lifecycle bracket; the interstitial wait/human/escalation
+  // cells HOLD at the host bracket rather than owning a distinct step.
+  assertEquals(CELL_STEP.implement, "Implementing");
+  assertEquals(CELL_STEP.converge, "Converging");
+  assertEquals(CELL_STEP.merge, "Merging");
+  assertEquals(CELL_STEP.wait, "Implementing");
+  assertEquals(CELL_STEP.human, "Converging");
+  assertEquals(CELL_STEP.escalation, "Converging");
+  // Every mapped bracket is a real axis key — v1 adds no stages, so the pipeline renderer is unchanged.
+  for (const step of Object.values(CELL_STEP)) {
+    assert(STEP_KEYS.includes(step), `cell step "${step}" is not a STAGE_KEYS member`);
+  }
+});
+
+test("stepOrdinal gives the axis total order the frontier reduction compares advancement by", () => {
+  assertEquals(stepOrdinal("Requested"), 0);
+  assertEquals(stepOrdinal("Implementing"), 1);
+  assertEquals(stepOrdinal("PR open"), 2);
+  assertEquals(stepOrdinal("Converging"), 3);
+  assertEquals(stepOrdinal("Merging"), 4);
+  assertEquals(stepOrdinal("Done"), 5);
+});
+
+test("terminalTier reuses the shipped stage_state tiers (converged/merged/done→ok, blocked distinct, failed/skipped/abandoned→failed, active→null)", () => {
+  assertEquals(terminalTier("merged"), "ok");
+  assertEquals(terminalTier("converged"), "ok");
+  assertEquals(terminalTier("done"), "ok");
+  assertEquals(terminalTier("blocked"), "blocked");
+  assertEquals(terminalTier("failed"), "failed");
+  assertEquals(terminalTier("skipped"), "failed");
+  assertEquals(terminalTier("abandoned"), "failed");
+  assertEquals(terminalTier("running"), null);
+  assertEquals(terminalTier("converging"), null);
+});
+
+test("terminalTier's partition is DERIVED from STAGE_DONE_STATUSES — every canonical terminal is tiered exactly once (drift guard)", () => {
+  // The stepAxis module already throws at load if the partition drifts from STAGE_DONE_STATUSES; assert
+  // the coupling here too so a reviewer sees the invariant. Every STAGE_DONE_STATUSES member gets a
+  // non-null tier, and the only status tiered OUTSIDE that canonical set is the delivery-graph `done`.
+  for (const status of STAGE_DONE_STATUSES) {
+    assert(terminalTier(status) !== null, `STAGE_DONE_STATUSES member "${status}" must be tiered by terminalTier`);
+  }
+  assertEquals(terminalTier(DONE_TERMINAL), "ok");
+  assert(!STAGE_DONE_STATUSES.includes(DONE_TERMINAL), "`done` is the S7 canonical success value, tiered on top of STAGE_DONE_STATUSES (not a member of it)");
+});
+
+// ── reduceFrontier — the deterministic parallel-frontier rollup (§4b §280-332) ────────────────────
+
+const branch = (nodeId: string, step: FrontierBranch["step"], terminal: string | null = null): FrontierBranch => ({ nodeId, step, terminal });
+
+test("a single branch reduces trivially to itself (the feature + S7 delivery-graph coarse case)", () => {
+  assertEquals(reduceFrontier([branch("n0", "Implementing")]), { step: "Implementing", state: null });
+  assertEquals(reduceFrontier([branch("n0", "Done", "done")]), { step: "Done", state: "ok" });
+  assertEquals(reduceFrontier([branch("n0", "Done", "failed")]), { step: "Done", state: "failed" });
+});
+
+test("all-active frontier reduces to the LEAST-ADVANCED active branch (never further than the slowest in-flight branch)", () => {
+  const r = reduceFrontier([branch("a", "Merging"), branch("b", "Implementing"), branch("c", "Converging")]);
+  assertEquals(r, { step: "Implementing", state: null });
+});
+
+test("all-active ties on step break deterministically by stable node id", () => {
+  const r = reduceFrontier([branch("z", "Converging"), branch("a", "Converging")]);
+  assertEquals(r, { step: "Converging", state: null });
+});
+
+test("MIXED with only SUCCESS terminals + active branches reduces to the least-advanced ACTIVE branch (terminal branches are past, not 'still blocked on')", () => {
+  const r = reduceFrontier([branch("done1", "Done", "merged"), branch("active1", "Converging"), branch("active2", "Merging")]);
+  assertEquals(r, { step: "Converging", state: null });
+});
+
+test("MIXED: a NON-SUCCESS terminal (failed) takes precedence over in-flight siblings — the aggregate renders that branch's step + failed state", () => {
+  const r = reduceFrontier([branch("active", "Implementing"), branch("bad", "Converging", "failed"), branch("done", "Done", "merged")]);
+  assertEquals(r, { step: "Converging", state: "failed" });
+});
+
+test("MIXED: a blocked terminal surfaces as the DISTINCT blocked render state (operator-actionable), not masked by an active sibling", () => {
+  const r = reduceFrontier([branch("active", "Merging"), branch("stuck", "Implementing", "blocked")]);
+  assertEquals(r, { step: "Implementing", state: "blocked" });
+});
+
+test("MULTIPLE non-success terminals tie-break by earliest terminal step, then stable node id", () => {
+  // Two failed branches at different steps → earliest step wins.
+  assertEquals(
+    reduceFrontier([branch("a", "Converging", "failed"), branch("b", "Implementing", "blocked"), branch("act", "Merging")]),
+    { step: "Implementing", state: "blocked" },
+  );
+  // Two non-success terminals at the SAME step → stable node id wins (and its own render state).
+  assertEquals(
+    reduceFrontier([branch("z", "Converging", "failed"), branch("a", "Converging", "blocked")]),
+    { step: "Converging", state: "blocked" },
+  );
+});
+
+test("ALL-TERMINAL, all success → done (the axis tail, ok)", () => {
+  const r = reduceFrontier([branch("a", "Converging", "converged"), branch("b", "Merging", "merged")]);
+  assertEquals(r, { step: "Done", state: "ok" });
+});
+
+test("ALL-TERMINAL with any non-success → earliest non-success terminal step (same tie-break)", () => {
+  const r = reduceFrontier([branch("a", "Merging", "merged"), branch("b", "Converging", "failed"), branch("c", "Implementing", "blocked")]);
+  assertEquals(r, { step: "Implementing", state: "blocked" });
+});
+
+test("reduceFrontier throws on an empty frontier — a unit always has at least its own branch", () => {
+  let threw = false;
+  try {
+    reduceFrontier([]);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "expected reduceFrontier([]) to throw");
+});

package/app/stepAxis.ts

@@ -0,0 +1,217 @@
+// app/stepAxis.ts — the ONE canonical progress step axis for the derived stepper (ADR 0006 §4b, S7).
+//
+// §4b collapses the unit's three progress projections (feature `deriveStage`, epic write-time
+// `epic_phase`, delivery-graph `pollDeliveryGraphPhase`) onto ONE derivation over a single step axis,
+// rendered by the ONE `pipeline` renderer kind. This module owns the canonical definition of that
+// axis: the ordered steps, the explicit cell→step mapping, the terminal-tier normalization, and the
+// deterministic parallel-frontier reduction. Feature (`app/stage.ts` / `app/featureReadModel.ts`) and
+// delivery-graph (`app/deliveryGraphReadModel.ts`) both project onto it; there is no per-surface
+// re-declaration of the step vocabulary.
+//
+// SEEDED FROM `STAGE_KEYS`, OWNS THE MAPPING (§4b §217-232). `STAGE_KEYS` (app/stage.ts) is the closest
+// EXISTING projection of the axis but it is NOT literally a clean cell sequence — it mixes lifecycle
+// states (`Requested` / `PR open` / `Done`) with process cells (`implement` / `converge` / `merge`),
+// and hosts interstitial `wait` / `human` / `escalation` cells. So this module SEEDS `STEP_KEYS` from
+// `STAGE_KEYS` (the single source of truth for the six brackets) but adds the thing `STAGE_KEYS` lacks:
+// an explicit map of which cell entry/exit each step corresponds to, and how the interstitial cells
+// collapse into an existing bracket. v1 leaves the two existing axis consumers physically in place (the
+// exported `STAGE_KEYS` and the static `stages` array in `pages/feature.page.json`) and only SEEDS this
+// mapping from them — deriving/retiring those duplicates is a flagged follow-up, not S7.
+//
+// LIFECYCLE-STAGE FIDELITY ONLY (S7). Per §4b, S7 renders the coarse LIFECYCLE stage, not a per-cell
+// position: even feature is not per-cell today (`deriveStage` collapses a readiness-probe/timer park or
+// an active `implement-task` all to `Implementing`). True mid-cell / per-node resolution is the S8
+// element-instance source (#542, #473). The interstitial-cell mapping below therefore documents the
+// bracket each cell COLLAPSES into; it does not add per-cell steps.
+
+import { STAGE_DONE_STATUSES, STAGE_KEYS, type StageKey, type StageState } from "./stage.ts";
+
+/** The canonical ordered step axis — SEEDED from `STAGE_KEYS` (app/stage.ts), the single source of
+ * truth for the six pipeline brackets: Requested → Implementing → PR open → Converging → Merging →
+ * Done. This module owns the cell→step MAPPING onto these keys; the keys themselves stay sourced from
+ * `STAGE_KEYS` so the axis cannot fork across surfaces. */
+export const STEP_KEYS: readonly StageKey[] = STAGE_KEYS;
+export type StepKey = StageKey;
+
+/** The deterministic INITIAL step for a pre-run / dispatch-pending / first-observation unit — the head
+ * of the axis (`Requested`, `STAGE_KEYS[0]`). Pins the scalar `activeField` so it is never undefined on
+ * a first observation with no prior lifecycle key (§4b §431-449). */
+export const INITIAL_STEP: StepKey = STEP_KEYS[0];
+
+/** The TERMINAL step — the tail of the axis (`Done`). A terminal unit pins its `activeField` here
+ * outright (with an `ok`/`failed` render state) so it can never render an undefined/invalid active
+ * stage (§4b §436-438). */
+export const TERMINAL_STEP: StepKey = STEP_KEYS[STEP_KEYS.length - 1];
+
+/** The process-cell vocabulary of the composed unit (§2/S4): the three executable pipeline cells
+ * (`implement` / `converge` / `merge`) plus the interstitial `wait` / `human` / `escalation` cells that
+ * can be inserted around them. */
+export type ProcessCell = "implement" | "converge" | "merge" | "wait" | "human" | "escalation";
+
+/**
+ * The explicit **cell → step** mapping (§4b's first deliverable). Each executable cell ENTERS its
+ * bracket when the token arrives and EXITS it when the token advances to the next cell's bracket; the
+ * three lifecycle markers bracket the cell run — a token before `implement` reads `Requested`, raising
+ * the PR on `implement` exit enters `PR open`, and a merged/terminal token reads `Done`.
+ *
+ * The interstitial `wait` / `human` / `escalation` cells do **not** own a distinct step — they HOLD the
+ * frontier at the bracket of the cell they interrupt (a human gate mid-convergence reads `Converging`,
+ * a wait-gate before implementation reads `Implementing`), collapsing into an existing `STAGE_KEYS`
+ * bracket rather than extending the axis. This is why the `pipeline` renderer needs no new stages for
+ * v1: every cell maps onto one of the six existing keys.
+ */
+export const CELL_STEP: Readonly<Record<ProcessCell, StepKey>> = {
+  implement: "Implementing",
+  converge: "Converging",
+  merge: "Merging",
+  // Interstitial cells collapse into the host bracket (hold, do not advance).
+  wait: "Implementing",
+  human: "Converging",
+  escalation: "Converging",
+};
+
+/** The zero-based ordinal of a step on the axis — the total order the frontier reduction compares
+ * "advancement" by. `-1` for an unknown key (defensive; every derived step is a `STEP_KEYS` member). */
+export function stepOrdinal(step: StepKey): number {
+  return STEP_KEYS.indexOf(step);
+}
+
+/** The renderer's terminal render-state tiers, reusing the SHIPPED `featureReadModel` `stage_state`
+ * basis (`STAGE_DONE_STATUSES` + the `stage_state` CASE, app/featureReadModel.ts) rather than inventing
+ * a second mapping (derivation-over-duplication, §4b §296-308):
+ *   - `ok`      — a SUCCESS terminal: `merged` / `converged` / the new canonical `done`.
+ *   - `blocked` — the renderer's DISTINCT operator-actionable `blocked` terminal (never folded away).
+ *   - `failed`  — a FAILED terminal: `failed` / `skipped` / `abandoned`.
+ *   - `null`    — not terminal (in progress).
+ * Note this is the PER-CELL / per-PR tier: `converged` is a success terminal here. The EPIC rollup's
+ * shape-aware predicate (`converged` is resolved-not-landed) is applied by the caller, not here. */
+export type TerminalTier = "ok" | "failed" | "blocked";
+
+/** The delivery-graph canonical SUCCESS terminal (app/deliveryGraphReadModel.ts). `STAGE_DONE_STATUSES`
+ * predates the S7 axis and does NOT include it, so it is the one status tiered ON TOP of the shared
+ * feature basis below (special-cased per the ADR §4b `done` value). */
+export const DONE_TERMINAL = "done";
+
+/** The per-cell terminal PARTITION — the SAME basis as featureReadModel's `stage_state` CASE
+ * (app/featureReadModel.ts: `merged`/`converged`→ok, `blocked`→blocked, `failed`/`skipped`/`abandoned`→
+ * failed). It is NOT a second hand-kept copy: every member is drawn from the shipped
+ * `STAGE_DONE_STATUSES`, and the exhaustiveness guard below fails at module load if this partition ever
+ * stops covering that canonical set EXACTLY — so a terminal status added to `STAGE_DONE_STATUSES` cannot
+ * silently fall through untiered (drift becomes a hard error, not a wrong render). */
+const SUCCESS_TERMINALS: readonly string[] = ["merged", "converged"];
+const BLOCKED_TERMINAL = "blocked";
+const FAILED_TERMINALS: readonly string[] = ["failed", "skipped", "abandoned"];
+
+// Structural coupling to the single source of truth: the partition must tier EXACTLY the members of
+// STAGE_DONE_STATUSES (the delivery-graph `done` value is tiered separately, so it is excluded here).
+const _tiered = new Set<string>([...SUCCESS_TERMINALS, BLOCKED_TERMINAL, ...FAILED_TERMINALS]);
+const _canonical = new Set<string>(STAGE_DONE_STATUSES);
+if (_tiered.size !== _canonical.size || [..._canonical].some((s) => !_tiered.has(s))) {
+  throw new Error(
+    "stepAxis terminalTier partition drifted from STAGE_DONE_STATUSES — every terminal status must be " +
+      `tiered exactly once. tiered=[${[..._tiered].sort().join(",")}] canonical=[${[..._canonical].sort().join(",")}]`,
+  );
+}
+
+export function terminalTier(status: string): TerminalTier | null {
+  if (status === DONE_TERMINAL || SUCCESS_TERMINALS.includes(status)) return "ok";
+  if (status === BLOCKED_TERMINAL) return "blocked";
+  if (FAILED_TERMINALS.includes(status)) return "failed";
+  return null;
+}
+
+/** A `TerminalTier` is a NON-SUCCESS terminal (`failed` / `blocked`) iff it is operator-actionable —
+ * the thing an in-flight sibling must not mask. `ok` (success) is the only success terminal. */
+export function isNonSuccessTerminal(tier: TerminalTier): boolean {
+  return tier === "failed" || tier === "blocked";
+}
+
+/** Map a terminal tier onto the `pipeline` column's `stateField` vocabulary (`ok`/`failed`/`blocked`).
+ * The raw canonical `done` never reaches the renderer verbatim (any other string silently degrades to
+ * in-progress), so a success terminal renders as `ok`. Total over the three tiers. */
+export function tierRenderState(tier: TerminalTier): StageState {
+  return tier;
+}
+
+/** One branch of an aggregate's active frontier, projected onto the canonical axis. `terminal` is the
+ * branch's canonical terminal status when it has settled (`merged`/`converged`/`done`/`blocked`/
+ * `failed`/`skipped`/`abandoned`), or `null` while the branch is still active at `step`. `nodeId` is
+ * the stable identity used as the deterministic tie-break. */
+export interface FrontierBranch {
+  nodeId: string;
+  step: StepKey;
+  terminal: string | null;
+}
+
+/** The reduced scalar the `pipeline` column binds: one `STAGE_KEYS` step plus its render state. */
+export interface ReducedFrontier {
+  step: StepKey;
+  state: StageState;
+}
+
+/** Deterministic tie-break: earliest step ordinal, then stable `nodeId`. */
+function earliest(a: FrontierBranch, b: FrontierBranch): FrontierBranch {
+  const da = stepOrdinal(a.step);
+  const db = stepOrdinal(b.step);
+  if (da !== db) return da < db ? a : b;
+  return a.nodeId <= b.nodeId ? a : b;
+}
+
+/**
+ * Reduce a parallel active frontier to ONE deterministic step for the scalar `pipeline` `activeField`
+ * (§4b §280-332). The `pipeline` column binds a single scalar, but an N-node/parallel DAG (epic waves,
+ * delivery graphs) can occupy incomparable cells at once, so the frontier is reduced deterministically:
+ *
+ *   - A **non-success terminal** (`failed` / `blocked`) takes PRECEDENCE in every case — it is an
+ *     operator-actionable signal an in-flight sibling must not mask. Among multiple non-success
+ *     terminals the tie-break is earliest terminal step, then stable node id; the aggregate renders at
+ *     that branch's step with that terminal's render state (`failed` / `blocked`).
+ *   - Otherwise, if any branch is still ACTIVE, reduce to the **least-advanced active branch** (the
+ *     "still blocked on" read) with an in-progress state — the aggregate never renders further along
+ *     than its slowest in-flight branch. Terminal (success) branches are past, not "still blocked on".
+ *   - Otherwise every branch is a SUCCESS terminal → `done` (the axis tail, `ok`).
+ *
+ * The shape-aware epic success predicate (`converged` is resolved-not-landed for an epic rollup, not a
+ * success terminal) is applied by the CALLER when it classifies each branch's `terminal`; this reducer
+ * treats whatever terminal it is handed per the per-cell tier. A single-branch unit (feature, and a
+ * delivery-graph at S7's coarse run-level fidelity) reduces trivially to that branch.
+ *
+ * Throws on an empty frontier — a unit always has at least its own (initial) branch; an empty input is
+ * a caller bug, not a renderable state.
+ */
+export function reduceFrontier(branches: readonly FrontierBranch[]): ReducedFrontier {
+  if (branches.length === 0) {
+    throw new Error("reduceFrontier: empty frontier — a unit always has at least one branch");
+  }
+
+  const nonSuccess: FrontierBranch[] = [];
+  const active: FrontierBranch[] = [];
+  for (const b of branches) {
+    if (b.terminal === null) {
+      active.push(b);
+      continue;
+    }
+    const tier = terminalTier(b.terminal);
+    // An unrecognised terminal degrades to a failed-tier signal (defensive; the caller passes canonical
+    // union terminals) so it is never silently masked by an in-flight sibling.
+    if (tier === null || isNonSuccessTerminal(tier)) nonSuccess.push(b);
+  }
+
+  if (nonSuccess.length > 0) {
+    const pick = nonSuccess.reduce(earliest);
+    const tier = terminalTier(pick.terminal ?? "") ?? "failed";
+    return { step: pick.step, state: tierRenderState(tier) };
+  }
+
+  if (active.length > 0) {
+    const pick = active.reduce(earliest);
+    return { step: pick.step, state: null };
+  }
+
+  // All branches are success terminals → the shared success bucket (`done`).
+  return { step: TERMINAL_STEP, state: "ok" };
+}
+
+/** Re-export the shipped terminal-status set the tier basis draws on, so a consumer can reference the
+ * single source without a second import of app/featureReadModel.ts. */
+export { STAGE_DONE_STATUSES };

package/db/migrations/087_delivery_graph_read_model.sql

@@ -0,0 +1,75 @@
+-- Delivery-graph read model: DECLARE ONCE, compile to BOTH backends (ADR-0065, nano-ide#452), for the
+-- ONE derived stepper (ADR 0006 §4b, issue #541 / S7).
+--
+-- Before §4b the delivery-graph surfaces rendered `delivery_graph_runs.phase` — a bare text projection
+-- the user-task park poll (`pollDeliveryGraphPhase`) recomputes — on a DIFFERENT renderer from
+-- feature's `pipeline` stepper. S7 collapses feature + delivery-graph onto the ONE canonical step axis
+-- (app/stepAxis.ts, seeded from `STAGE_KEYS`) rendered by the ONE `pipeline` kind. This migration adds
+-- the delivery-graph half: a `delivery_graph_read_model` VIEW that maps the run's lifecycle onto a
+-- CONFIGURED `STAGE_KEYS` bracket (`stage`) with a render state (`stage_state`), plus a companion
+-- `park_label` display column carrying the actionable "Parked on human node: <label>" text so promoting
+-- the stepper does not drop the detail the plain Phase cell showed.
+--
+-- Every DERIVED column below is emitted VERBATIM from the ONE declaration in
+-- app/deliveryGraphReadModel.ts — the member-PR rollup DDL from `deliveryGraphPrCounts.viewDdl()`, and
+-- `stage`/`stage_state` from `deliveryGraphReadModel.sqlSelectFor(col, { baseAlias: "dg" })` — which
+-- ALSO drive the runtime TS via `reduce`/`fnFor`. The two lowerings fall out of the same closed-DSL AST
+-- and cannot diverge; a drift guard (app/deliveryGraphReadModel.test.ts) fails if this file stops
+-- matching the declaration, and `assertRollupParity`/`assertReadModelParity` prove the SQL and TS
+-- lowerings agree.
+--
+-- PER-SHAPE CORRELATION. A delivery-graph run has no aggregate `pr_key`; its downstream PRs attach via
+-- `pull_requests.root_request_key = delivery_graph_runs.run_key`. The `delivery_graph_pr_counts` rollup
+-- folds the member PRs (through `pull_requests__tracking.derived_status`, so an out-of-band-terminated
+-- PR is not held in flight) grouped by `root_request_key`, and the read model LEFT JOINs it on
+-- `dg.run_key = pc.root_request_key`. `prs_in_flight > 0` tempers a `running` run to `Converging`,
+-- matching the shipped `deliveryOriginStage` (app/lineage.ts) — NOT a `process_key` join (that key is
+-- reassigned to the downstream convergence/merge instances).
+--
+-- SEMANTICS. The status-classifying `stage`/`stage_state` read the terminal-folded `derived_status` off
+-- the auto-provisioned `delivery_graph_runs__tracking` derived VIEW (ADR-0065), so a cancelled run
+-- renders `Done`/`failed` instead of freezing at `Implementing`/`Converging`. Base columns stay aliased
+-- identity pass-throughs (so the static pages↔schema contract guard sees the VIEW's columns), sourced
+-- off `delivery_graph_runs__tracking`'s re-export of the base `delivery_graph_runs.*`; `status` is the
+-- effective `COALESCE(derived_status, status)` so the pages' Active/History status filter tracks a
+-- terminated run. `park_label` is a hand-authored DISPLAY column (D3 — display formatting is out of the
+-- framework AST, so it carries no TS twin): the run's `phase` when it is parked on a human node
+-- (`phase_node_id` set), else NULL.
+--
+-- Forward-only VIEW definition (DROP then CREATE). `delivery_graph_runs__tracking` is the managed VIEW
+-- urban provisions at mount; SQLite does not validate a view body at CREATE time, so this migration
+-- (which runs before that mount) is created fine and resolves once the managed VIEW exists. The runner
+-- wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 085.
+
+DROP VIEW IF EXISTS delivery_graph_read_model;
+DROP VIEW IF EXISTS delivery_graph_pr_counts;
+
+CREATE VIEW IF NOT EXISTS "delivery_graph_pr_counts" AS
+SELECT
+  "__urban_rollup_src"."root_request_key" AS "root_request_key",
+  SUM(CASE WHEN COALESCE(((NOT COALESCE(("__urban_rollup_src"."root_request_key" IS NULL), 0)) AND (NOT COALESCE(COALESCE((COALESCE(("__urban_rollup_src"."derived_status" = 'converged'), 0) OR COALESCE(("__urban_rollup_src"."derived_status" = 'merged'), 0) OR COALESCE(("__urban_rollup_src"."derived_status" = 'abandoned'), 0)), 0), 0))), 0) THEN 1 ELSE 0 END) AS "prs_in_flight"
+FROM "pull_requests__tracking" "__urban_rollup_src"
+GROUP BY "__urban_rollup_src"."root_request_key";
+
+CREATE VIEW delivery_graph_read_model AS
+SELECT
+  dg.run_key AS run_key,
+  COALESCE(dg.derived_status, dg.status) AS status,
+  dg.process_key AS process_key,
+  dg.process_definition_id AS process_definition_id,
+  dg.digest AS digest,
+  dg.side_effecting AS side_effecting,
+  dg.node_count AS node_count,
+  dg.human_node_count AS human_node_count,
+  dg.side_effect_count AS side_effect_count,
+  dg.title AS title,
+  dg.phase AS phase,
+  dg.phase_node_id AS phase_node_id,
+  dg.human_labels AS human_labels,
+  dg.created_at AS created_at,
+  dg.updated_at AS updated_at,
+  CASE WHEN COALESCE(("dg"."derived_status" = 'done'), 0) THEN 'Done' WHEN COALESCE((COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("dg"."derived_status" = 'awaiting-approval'), 0) THEN 'Requested' WHEN COALESCE((COALESCE("pc"."prs_in_flight", 0) > 0), 0) THEN 'Converging' ELSE 'Implementing' END AS stage,
+  CASE WHEN COALESCE(("dg"."derived_status" = 'done'), 0) THEN 'ok' WHEN COALESCE((COALESCE(("dg"."derived_status" = 'failed'), 0) OR COALESCE(("dg"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN dg.phase_node_id IS NOT NULL THEN dg.phase ELSE NULL END AS park_label
+FROM delivery_graph_runs__tracking dg
+LEFT JOIN delivery_graph_pr_counts pc ON dg.run_key = pc.root_request_key;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.142.0",
+  "version": "0.144.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/delivery-graph-detail.page.json

@@ -85,14 +85,30 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "delivery_graph_runs",
+          "table": "delivery_graph_read_model",
           "orderBy": { "field": "updated_at", "dir": "desc" },
           "filter": [{ "field": "run_key", "eqParam": true }]
         },
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Graph", "subtitleField": "run_key", "truncate": true, "width": "30%" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          { "field": "phase", "header": "Phase", "truncate": true, "width": "30%" },
+          {
+            "field": "stage",
+            "header": "Pipeline",
+            "kind": "pipeline",
+            "stages": [
+              { "key": "Requested", "label": "Requested" },
+              { "key": "Implementing", "label": "Implementing" },
+              { "key": "PR open", "label": "PR open" },
+              { "key": "Converging", "label": "Converging" },
+              { "key": "Merging", "label": "Merging" },
+              { "key": "Done", "label": "Done" }
+            ],
+            "activeField": "stage",
+            "stateField": "stage_state",
+            "locus": { "field": "process_key", "link": { "kind": "processExplorer", "keyField": "process_key" } }
+          },
+          { "field": "park_label", "header": "Parked", "truncate": true, "width": "30%" },
           { "field": "node_count", "header": "Nodes" },
           { "field": "human_node_count", "header": "Human" },
           { "field": "side_effect_count", "header": "Side effects" },