@nanobpm/nano-workforce 0.81.0 → 0.82.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.82.0](https://github.com/nanobpm/nano-workforce/compare/v0.81.0...v0.82.0) (2026-08-17)
+
+
+### Features
+
+* reify epic domain lifecycle as derived plans.epic_phase ([#261](https://github.com/nanobpm/nano-workforce/issues/261)) ([#265](https://github.com/nanobpm/nano-workforce/issues/265)) ([4cc9dee](https://github.com/nanobpm/nano-workforce/commit/4cc9deee86b800206d264d96269e6a98e8753883)), closes [#266](https://github.com/nanobpm/nano-workforce/issues/266) [nwf#245](https://github.com/nwf/issues/245) [nano-ide#254](https://github.com/nano-ide/issues/254)
+
 # [0.81.0](https://github.com/nanobpm/nano-workforce/compare/v0.80.0...v0.81.0) (2026-08-17)
 
 

package/SPEC.md

@@ -530,6 +530,17 @@ History: done/failed/abandoned) with a `plan_tasks` child grid showing each task
 status and the PR it produced (`pr_key` cross-references the Pull requests grid for
 convergence status).
 
+**Epic domain phase** (issue #261): `plans.status` only distinguishes the process-instance
+terminal (`dispatched` = "fan-out job done"), not the epic's *domain* lifecycle. The read model
+therefore also carries a derived, display-only `plans.epic_phase` — **Planning → Reviewing →
+Implementing (wave n/t) → Trial merging → Finalizing → Dispatched** — projected at write time from
+`plan-fanout.bpmn`'s named activities via each spine worker's BPMN element id (`app/epicPhase.ts`,
+the single binding; nwf is the first consumer of the urban phase-projection primitive, nano-ide#266).
+The `Implementing` band is wave-labelled from the levelize records (`plan_tasks` waves). The epic /
+epic-detail pages surface it as a **Phase** column. It never gates control flow (that stays driven by
+the process `currentWave`/`waveCount`/`gate_wave`); a post-dispatch cross-instance rollup into
+Converging/Merging is a later seam (nwf#245 / nano-ide#254).
+
 ### 13.1 Dependency waves + merge barrier (issues #20, #26, release-notes-concierge)
 
 The flat `implement → record-results` shape above evolved into a **wave loop**. The

package/app/epicPhase.test.ts

@@ -0,0 +1,62 @@
+// Read-model derivation test for the epic domain phase (issue #261). `deriveEpicPhase` /
+// `implementingPhase` are the single source of truth for the write-time projection each spine
+// worker stamps onto `plans.epic_phase`. The projection binds structurally to plan-fanout.bpmn's
+// named activities via the job's BPMN element id (mirroring the urban #266 phase primitive), so the
+// epic view can show WHICH phase an epic is in — not only the process-instance terminal status.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { deriveEpicPhase, EPIC_PHASE, implementingPhase } from "./epicPhase.ts";
+
+test("deriveEpicPhase maps each spine element to its domain phase", () => {
+  // Planning genesis + hand-off into Reviewing when the plan is recorded.
+  assertEquals(deriveEpicPhase("plan"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("ensure-base-branch"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("record-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("review-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("record-plan-review"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("plan-review-decision"), EPIC_PHASE.REVIEWING);
+  // Trial-merge band.
+  assertEquals(deriveEpicPhase("trial-merge"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("record-trial-merge"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("trial-merge-decision"), EPIC_PHASE.TRIAL_MERGING);
+  assertEquals(deriveEpicPhase("resolve-trial-attention"), EPIC_PHASE.TRIAL_MERGING);
+  // Finalize step's lasting result is the "Fleet dispatched" terminal.
+  assertEquals(deriveEpicPhase("record-results"), EPIC_PHASE.DISPATCHED);
+});
+
+test("deriveEpicPhase wave-labels the Implementing band from the levelize records", () => {
+  // select-wave / record-wave / the implement MI + wait-wave-merged all read as Implementing,
+  // labelled with the 1-based wave from the wave/levelize records (0-based `current`).
+  assertEquals(
+    deriveEpicPhase("select-wave", { current: 0, total: 3 }),
+    "Implementing (wave 1/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("record-wave", { current: 2, total: 3 }),
+    "Implementing (wave 3/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("wait-wave-merged", { current: 1, total: 3 }),
+    "Implementing (wave 2/3)",
+  );
+  assertEquals(deriveEpicPhase("implement-task", { current: 0, total: 1 }), "Implementing (wave 1/1)");
+});
+
+test("deriveEpicPhase returns null for a non-spine element so a stray write never clobbers", () => {
+  assertEquals(deriveEpicPhase(undefined), null);
+  assertEquals(deriveEpicPhase(null), null);
+  assertEquals(deriveEpicPhase(""), null);
+  assertEquals(deriveEpicPhase("some-unrelated-element"), null);
+});
+
+test("implementingPhase clamps the 1-based label to the total and degrades gracefully", () => {
+  assertEquals(implementingPhase(0, 2), "Implementing (wave 1/2)");
+  // A `current` at/over the last index (record-wave pins current_wave to waveCount-1 on the final
+  // wave) never reads past n/n.
+  assertEquals(implementingPhase(5, 3), "Implementing (wave 3/3)");
+  // Unusable wave numbers (taskless plan / NaN counter) degrade to a bare Implementing — never
+  // "wave NaN/…".
+  assertEquals(implementingPhase(0, 0), "Implementing");
+  assertEquals(implementingPhase(undefined, undefined), "Implementing");
+  assertEquals(implementingPhase("x", "y"), "Implementing");
+});

package/app/epicPhase.ts

@@ -0,0 +1,125 @@
+// app/epicPhase.ts — reify the epic's own domain lifecycle as a derived `epic_phase` (issue #261).
+//
+// `plans.status` only distinguishes `planning` / `dispatched` / `done` / `failed` / `abandoned` —
+// and `dispatched` is the `plan-fanout.bpmn` PROCESS-INSTANCE terminal ("fan-out job done"), not the
+// epic's domain phase. `plan-fanout.bpmn` already models the rich lifecycle as named activities
+// (Ensure base branch → Plan → Review plan → Select wave → Implement task → Trial merge → Finalize
+// → "Fleet dispatched"); this module reifies that lifecycle as a stored, display-only projection so
+// the epic view can show which phase the epic is in.
+//
+// Convention over declaration: the phases ARE the activities plan-fanout.bpmn already names. Each
+// spine worker derives its projection from its OWN BPMN element id (`job.elementId`) — no annotation
+// map on the model, no second reconciliation pass — mirroring the urban structural phase-projection
+// primitive (nano-ide#266), which derives the phase from the furthest element reached in
+// write-provenance. This module is the single binding (nwf is #266's first consumer).
+//
+// Write-time projection: because the phase only advances when a worker writes, each spine worker
+// stamps the phase the epic is ENTERING as a result of its write — the write points ARE the phase
+// boundaries. Two structural defaults are coarsened where the raw activity label would mislead
+// (documented on `ELEMENT_PHASE` below): `select-wave` reads as `Implementing (wave n/t)` because it
+// dispatches and durably marks the (write-silent) `implement` multi-instance subProcess, and
+// `record-results` reads as the `Dispatched` terminal ("Fleet dispatched").
+//
+// Cross-instance rollup (later): post-dispatch, the epic's effective phase extends into the
+// convergence/merge loops carried on separate top-level instances correlated by lineage
+// (`rootRequestKey`, nwf#245 / nano-ide#254). Once #266's Tier-2 rollup lands, `epic_phase` can
+// advance past `Dispatched` into Converging/Merging with no new wiring here — the seam is this
+// module's derivation staying the single source.
+
+/** The epic's domain phases — the vocabulary the derivation projects onto `plans.epic_phase`.
+ *  Shared with the feature-view stage vocabulary (nwf#254), which uses the same stored-projection
+ *  pattern. `Implementing` is wave-labelled at derivation time (see {@link implementingPhase}). */
+export const EPIC_PHASE = {
+  PLANNING: "Planning",
+  REVIEWING: "Reviewing",
+  IMPLEMENTING: "Implementing",
+  TRIAL_MERGING: "Trial merging",
+  FINALIZING: "Finalizing",
+  DISPATCHED: "Dispatched",
+} as const;
+
+/** Coerce a wave index/count to a non-negative integer, or null when it isn't one. Mirrors the
+ *  `toWave` coercion the wave workers already apply, so a NaN/absent counter degrades to an
+ *  unlabelled `Implementing` rather than emitting `wave NaN/…`. */
+const toWave = (v: unknown): number | null => {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n >= 0 ? n : null;
+};
+
+/**
+ * `Implementing (wave n/t)` — special-cased from the wave/levelize records (`plan_tasks` waves),
+ * NOT the raw multi-instance counter. `current` is the 0-based wave index carried on the process
+ * (`currentWave` / the projected `current_wave`); the label is 1-based and clamped to `total` so a
+ * final wave reads `n/n`. Falls back to a bare `Implementing` when the wave numbers aren't usable
+ * (e.g. a taskless plan with `total` 0), so the phase never renders `wave NaN`.
+ */
+export function implementingPhase(current: unknown, total: unknown): string {
+  const t = toWave(total);
+  const c = toWave(current);
+  if (t !== null && t > 0 && c !== null) {
+    const n = Math.min(c + 1, t);
+    return `${EPIC_PHASE.IMPLEMENTING} (wave ${n}/${t})`;
+  }
+  return EPIC_PHASE.IMPLEMENTING;
+}
+
+/**
+ * Structural binding: `plan-fanout.bpmn` element id → the domain phase the epic is IN while that
+ * element (or the write-silent agent step it hands off to) runs. Complete over the epic's spine, so
+ * the projection is derivable from provenance alone (the urban #266 semantics). Two entries are
+ * deliberately COARSENED from their raw activity label because the structural default misleads:
+ *   • `record-plan` ("Record plan & levelize") → Reviewing: recording the plan hands the epic to the
+ *     `review-plan` agent, so the review phase should already read while that (write-silent) agent
+ *     runs. `record-plan-review` re-affirms Reviewing on each round/escalation.
+ *   • `select-wave` ("Select wave") → Implementing: it dispatches the wave and is the last host write
+ *     before the write-silent `implement` MI, so it durably marks the implementation phase for the
+ *     wave it launches (wave-labelled via {@link implementingPhase} at the call site).
+ *   • `record-results` ("Finalize plan") → Dispatched: the finalize step's lasting result is the
+ *     "Fleet dispatched" terminal end event.
+ * `record-wave`'s next phase is data-dependent (trial-merge vs. next wave vs. finalize), so it is
+ * resolved at its call site rather than from the element id alone; its structural fallback here is
+ * the wave it just landed.
+ */
+const ELEMENT_PHASE: Readonly<Record<string, string>> = {
+  "ensure-base-branch": EPIC_PHASE.PLANNING,
+  "plan": EPIC_PHASE.PLANNING,
+  "record-plan": EPIC_PHASE.REVIEWING,
+  "review-plan": EPIC_PHASE.REVIEWING,
+  "record-plan-review": EPIC_PHASE.REVIEWING,
+  "plan-review-decision": EPIC_PHASE.REVIEWING,
+  "select-wave": EPIC_PHASE.IMPLEMENTING,
+  "implement": EPIC_PHASE.IMPLEMENTING,
+  "implement-task": EPIC_PHASE.IMPLEMENTING,
+  "feature-escalation": EPIC_PHASE.IMPLEMENTING,
+  "record-wave": EPIC_PHASE.IMPLEMENTING,
+  "wait-wave-merged": EPIC_PHASE.IMPLEMENTING,
+  "trial-merge": EPIC_PHASE.TRIAL_MERGING,
+  "record-trial-merge": EPIC_PHASE.TRIAL_MERGING,
+  "trial-merge-decision": EPIC_PHASE.TRIAL_MERGING,
+  "resolve-trial-attention": EPIC_PHASE.TRIAL_MERGING,
+  "record-results": EPIC_PHASE.DISPATCHED,
+};
+
+/** Optional wave context for a wave-bearing phase, sourced from the wave/levelize records. */
+export interface WaveContext {
+  current?: unknown;
+  total?: unknown;
+}
+
+/**
+ * Derive the epic phase for a spine element from its BPMN element id, or `null` when the element
+ * doesn't mark a phase — so a non-spine write (e.g. a poller reconcile pass) never clobbers
+ * `epic_phase`. A wave-bearing phase (`Implementing`) is wave-labelled from {@link WaveContext} when
+ * supplied. This is the single structural deriver; workers pass `job.elementId` so the phase name is
+ * never hardcoded at the call site.
+ */
+export function deriveEpicPhase(
+  elementId: string | undefined | null,
+  wave?: WaveContext,
+): string | null {
+  if (!elementId) return null;
+  const base = ELEMENT_PHASE[elementId];
+  if (base === undefined) return null;
+  if (base === EPIC_PHASE.IMPLEMENTING) return implementingPhase(wave?.current, wave?.total);
+  return base;
+}

package/app/plan.ts

@@ -11,6 +11,7 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
 import { coalesceTitle, ensureBaseBranch, fetchDefaultBranch, fetchIssueTitle } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
@@ -82,6 +83,12 @@ export interface Plan {
   // in app/service.ts); `delivery_label` is the human rollup for the epic detail view. Display-only.
   delivery: string | null;
   delivery_label: string | null;
+  // Derived epic domain phase (038_plan_epic_phase.sql, #261): the epic's own lifecycle phase —
+  // Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
+  // projected at write time from plan-fanout.bpmn's named activities (app/epicPhase.ts), so the epic
+  // view can show which phase the epic is IN rather than only the process-instance terminal status.
+  // Display-only; NULL until the lifecycle first stamps it (grandfathers pre-#261 rows).
+  epic_phase: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -436,6 +443,9 @@ export async function startPlan(
       issue_url: parsed.url,
       title,
       outcome: null,
+      // Genesis of the domain lifecycle (#261): the epic re-enters Planning. Cleared of any stale
+      // terminal phase from the prior run so the re-plan reads correctly from the first pass.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       updated_at: ts,
@@ -449,6 +459,8 @@ export async function startPlan(
       title,
       status: "planning",
       task_count: 0,
+      // Genesis of the domain lifecycle (#261): a fresh epic starts in Planning.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       created_at: ts,

package/db/migrations/038_plan_epic_phase.sql

@@ -0,0 +1,12 @@
+-- 038_plan_epic_phase.sql — issue #261: reify the epic's own domain lifecycle as a derived,
+-- write-time-projected `epic_phase`, so the epic/plan view can show WHICH phase an epic is in —
+-- Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
+-- instead of only the process-instance terminal status (`plans.status`, whose `dispatched` is the
+-- `plan-fanout.bpmn` fan-out terminal, not the epic's domain phase).
+--
+-- Forward-only, additive (expand): a nullable TEXT column, display-only. NULL until the plan
+-- lifecycle first stamps it (grandfathering pre-#261 rows), so it never gates control flow. The
+-- value is derived structurally from `plan-fanout.bpmn`'s named activities via each spine worker's
+-- BPMN element id (`app/epicPhase.ts`) and written through the existing plan write path — mirroring
+-- the wave-progress / delivery display projections already on this table.
+ALTER TABLE plans ADD COLUMN epic_phase TEXT;

package/package.json

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

@@ -57,6 +57,7 @@
         },
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "34%", "linkField": "issue_url" },
+          { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "wave_label", "header": "Wave" },

package/pages/epic.page.json

@@ -75,6 +75,7 @@
         ],
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "34%", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
+          { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "base_branch", "header": "Base branch" },

package/workers/record-plan/worker.ts

@@ -16,6 +16,7 @@
 // warning; the ordering is lost but every task still runs. No `plan_task_deps` are recorded
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
@@ -127,6 +128,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     wave_label: tasks.length > 0 ? `1/${waveCount}` : null,
     updated_at: ts,
   };
+  // Domain-phase projection (#261): recording the plan hands the epic to the `review-plan` agent,
+  // so it enters the Reviewing phase (derived structurally from this worker's BPMN element id).
+  // Guard against a null derivation (element id absent) clobbering the genesis phase.
+  const epicPhase = deriveEpicPhase(job.elementId);
+  if (epicPhase) patch.epic_phase = epicPhase;
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
   await app.data.table("plans", "plan_key").update(planKey, patch);
 

package/workers/record-results/worker.ts

@@ -13,6 +13,7 @@
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import { BpmnError } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -49,9 +50,16 @@ const handler: AppJobHandler<In> = async (job, app) => {
     throw new BpmnError("NO_WORK_DISPATCHED", `${planKey}: ${outcome}`);
   }
 
+  // Domain-phase projection (#261): the finalizer landed with opened PRs — the epic reaches its
+  // terminal "Fleet dispatched" phase (derived structurally from this worker's BPMN element id).
+  // The failed/no-work path above leaves epic_phase untouched: its terminal signal is status +
+  // outcome, and stamping "Dispatched" against a failed epic would misread. A null derivation
+  // (element id absent) must not clobber the last implementing phase.
+  const epicPhase = deriveEpicPhase(job.elementId);
   await app.data.table("plans", "plan_key").update(planKey, {
     status: "done",
     outcome: `${opened} PR(s) dispatched to convergence`,
+    ...(epicPhase ? { epic_phase: epicPhase } : {}),
     updated_at: ts,
   });
 

package/workers/record-wave/worker.test.ts

@@ -144,6 +144,8 @@ test("record-wave retries the same wave when a task is still pending", async ()
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, 1);
   // Retry keeps the projection on the same (still-pending) wave.
   assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 1);
+  // Domain-phase projection (#261): more waves remain, so the epic stays Implementing (wave n/t).
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Implementing (wave 2/2)");
 });
 
 test("record-wave pins current_wave to the last index and clears gate_wave on the final wave", async () => {
@@ -174,6 +176,9 @@ test("record-wave pins current_wave to the last index and clears gate_wave on th
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, null);
   assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 2);
   assertEquals((planUpdates[0].patch as Record<string, unknown>).wave_label, "3/3");
+  // Domain-phase projection (#261): the final wave landed with no successor and no trial merge, so
+  // the epic enters Finalizing (record-results then advances to the Dispatched terminal).
+  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Finalizing");
 });
 
 test("record-wave keeps all wave-progress fields NULL for a taskless plan (waveCount 0)", async () => {

package/workers/record-wave/worker.ts

@@ -15,6 +15,7 @@
 // and, crucially, so a later wave's `dependsOn` can reference the PR keys earlier waves produced.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { appendEntry } from "../../app/blackboard.ts";
+import { EPIC_PHASE, implementingPhase } from "../../app/epicPhase.ts";
 import { fetchPrFiles, fetchPrHead } from "../../app/github.ts";
 import { deriveExclusions, recordExclusions } from "../../app/mergeExclusion.ts";
 import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
@@ -280,6 +281,16 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const currentWaveProjection = waveCount > 0 ? projectedCurrentWave : null;
   const waveLabel = waveCount > 0 ? `${projectedCurrentWave + 1}/${waveCount}` : null;
 
+  // Domain-phase projection (#261): the wave landed — stamp the phase the epic is ENTERING next,
+  // which is data-dependent here (unlike the structural spine writers). A trial merge runs → Trial
+  // merging; another wave follows → Implementing (next wave n/t); otherwise the finalizer runs →
+  // Finalizing (record-results then advances to the Dispatched terminal).
+  const epicPhase = runTrialMerge
+    ? EPIC_PHASE.TRIAL_MERGING
+    : hasMoreWaves
+      ? implementingPhase(projectedCurrentWave, waveCount)
+      : EPIC_PHASE.FINALIZING;
+
   // Wave-merge barrier: when another wave follows, park the plan-fanout instance at the
   // `wait-wave-merged` catch event until THIS wave's opened PRs have MERGED (not merely opened).
   // `gate_wave` is that durable marker; the poller (`pollWaveGates`) clears it and publishes
@@ -292,6 +303,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       gate_wave: hasMoreWaves ? currentWave : null,
       current_wave: currentWaveProjection,
       wave_label: waveLabel,
+      epic_phase: epicPhase,
       updated_at: ts,
     });
   } catch (err) {

package/workers/select-wave/worker.test.ts

@@ -67,7 +67,7 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   ];
   const plans: Record<string, unknown>[] = [{ plan_key: "owner/repo#63", current_wave: 0 }];
   const out = await handler(
-    { variables: { planKey: "owner/repo#63", currentWave: 1 } } as any,
+    { variables: { planKey: "owner/repo#63", currentWave: 1 }, elementId: "select-wave" } as any,
     fakeApp(rows, [], plans),
   );
   assertEquals((out as { waveTasks: unknown[] }).waveTasks.length, 1);
@@ -76,6 +76,9 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   // is pre-formatted for the epics-index at-a-glance column.
   assertEquals(plans[0].wave_count, 2);
   assertEquals(plans[0].wave_label, "2/2");
+  // Domain-phase projection (#261): dispatching the wave marks the epic Implementing (wave n/t),
+  // derived from this worker's BPMN element id + the levelize records.
+  assertEquals(plans[0].epic_phase, "Implementing (wave 2/2)");
 });
 
 test("select-wave nulls all three progress fields when there are no levelized rows", async () => {

package/workers/select-wave/worker.ts

@@ -15,6 +15,7 @@
 // Emitting an empty `waveTasks` is fine: the MI activity over an empty collection completes
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -53,6 +54,13 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // display-only — it must never gate control flow, which stays driven by the process
   // `currentWave`/`waveCount`/`gate_wave` state.
   const waveCount = rows.reduce((m, r) => Math.max(m, r.wave ?? 0), -1) + 1;
+  // Domain-phase projection (#261): select-wave dispatches this wave and is the last host write
+  // before the write-silent `implement` MI, so it durably marks the implementation phase for the
+  // wave it launches — `Implementing (wave n/t)` from the levelize records (job.elementId +
+  // current/total waves). A null derivation (element id absent) must not clobber the phase.
+  const epicPhase = waveCount > 0
+    ? deriveEpicPhase(job.elementId, { current: currentWave, total: waveCount })
+    : null;
   try {
     await plans(app.data).update(planKey, {
       // Keep the three progress fields consistent: with no levelized rows (waveCount 0) there is
@@ -60,6 +68,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       current_wave: waveCount > 0 ? currentWave : null,
       wave_count: waveCount > 0 ? waveCount : null,
       wave_label: waveCount > 0 ? `${currentWave + 1}/${waveCount}` : null,
+      ...(epicPhase ? { epic_phase: epicPhase } : {}),
       updated_at: ts,
     });
   } catch (err) {