@nanobpm/nano-workforce 0.82.0 → 0.83.0

package/.github/workflows/pr-title-lint.yml

@@ -0,0 +1,39 @@
+name: PR title lint
+
+# Squash-merge uses the PR title as the commit subject on `main`, and
+# semantic-release (Angular preset) only cuts a release for `feat:`/`fix:`/`perf:`.
+# A non-conventional title therefore lands on `main` and is silently skipped by
+# the release job — so gate the title against the Conventional Commits grammar.
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint-title:
+    name: Conventional PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Keep in lockstep with the semantic-release commit-analyzer preset.
+          types: |
+            feat
+            fix
+            perf
+            build
+            chore
+            ci
+            docs
+            refactor
+            revert
+            style
+            test
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" must start with a lowercase letter.

package/AGENTS.md

@@ -308,6 +308,16 @@ agents:
   DCO check.
 - **Conventional Commits.** `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`,
   `test:`, imperative mood. Review-comment fix-ups are `chore:`, not `fix:`.
+- **PR titles must be Conventional too — they become the release trigger.** PRs
+  land on `main` via **squash merge**, so the **PR title is the commit subject**
+  semantic-release analyses. Only `feat:` (minor) and `fix:`/`perf:` (patch) cut a
+  release; any other type — or a non-conventional title like `Redesign …` or
+  `Foundation: …` — lands on `main` and is **silently skipped** by the release job
+  (no version, no changelog, no deploy). A user-facing feature **must** be titled
+  `feat:`. The `PR title lint` workflow (`.github/workflows/pr-title-lint.yml`)
+  enforces this; if a non-conventional title ever slips through, push one empty
+  releasable commit (`git commit --allow-empty -s -m "feat(scope): …"`) to release
+  the accumulated changes.
 - **Feature work in a worktree** off `origin/main`, one branch per change; open a
   PR and reference the closing issue (`Closes #NN`).
 - **Never `git push --force` on `main`;** use `--force-with-lease` on feature

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.83.0](https://github.com/nanobpm/nano-workforce/compare/v0.82.1...v0.83.0) (2026-08-17)
+
+
+### Features
+
+* **feature-view:** release intent-first pipeline view with stage chips ([0342edb](https://github.com/nanobpm/nano-workforce/commit/0342edbf67372450d6c499c1d39dc042e8dda342)), closes [#267](https://github.com/nanobpm/nano-workforce/issues/267) [#266](https://github.com/nanobpm/nano-workforce/issues/266)
+
+## [0.82.1](https://github.com/nanobpm/nano-workforce/compare/v0.82.0...v0.82.1) (2026-08-17)
+
+
+### Bug Fixes
+
+* **plan-fanout:** make the wave-merge barrier level-triggered ([#262](https://github.com/nanobpm/nano-workforce/issues/262)) ([#264](https://github.com/nanobpm/nano-workforce/issues/264)) ([ae939d8](https://github.com/nanobpm/nano-workforce/commit/ae939d8e96f136f820fcae9149c120806ddc6f1b))
+
 # [0.82.0](https://github.com/nanobpm/nano-workforce/compare/v0.81.0...v0.82.0) (2026-08-17)
 
 

package/SPEC.md

@@ -565,11 +565,14 @@ the loop runs one parallel `implement` MI fan-out per wave:
   `dependsOn`), and advances `currentWave`.
 - **Wave-merge barrier** (`wait-wave-merged`): when a wave has a successor,
   `record-wave` sets `plans.gate_wave` to that wave's index and the process parks at
-  the `wait-wave-merged` catch event. The poller's `pollWaveGates` pass publishes the
-  `wave-merged` message (correlated on `planKey`) once **every opened PR in that wave
-  has merged** (`app/waves.ts` `waveMergeTargets` selects the PRs to wait on;
-  `blocked`/`skipped`/keyless tasks clear vacuously), then clears `gate_wave`
-  single-shot. So a `dependsOn` means the dependent wave is not **implemented** until
+  the `wait-wave-merged` catch event. The poller's `pollWaveGatesImpl` pass is
+  **level-triggered**: it publishes the `wave-merged` message (correlated on `planKey`)
+  once **every opened PR in that wave has merged** (`app/waves.ts` `waveMergeTargets`
+  selects the PRs to wait on; `blocked`/`skipped`/keyless tasks clear vacuously) **and**
+  it observes an OPEN `wait-wave-merged` subscription for the plan — so a merge that
+  lands while the token is still upstream can't drop the signal. The poller **never**
+  clears `gate_wave`; `record-wave` owns the marker's lifecycle (re-arming it to the next
+  wave, or clearing it to NULL on the final wave). So a `dependsOn` means the dependent wave is not **implemented** until
   its prerequisites have **landed on the base branch** — not merely opened. This lets
   a blocking prerequisite (e.g. app scaffolding) fully converge and merge before the
   next wave builds on it. `gate_wave` lives in `db/migrations/007_wave_gate.sql`.

package/app/feature.test.ts

@@ -239,6 +239,30 @@ test("startFeature: a settled run is restarted in place (status reset, pr/outcom
   assertEquals(row.process_key, "PI-2");
 });
 
+test("startFeature: an in-place restart clears a stale acknowledged_at (re-earn the tick-off)", async () => {
+  const stores = {
+    feature_runs: {
+      rows: [
+        {
+          feature_key: "owner/repo#42",
+          status: "merged",
+          process_key: "PI-OLD",
+          pr_key: "owner/repo#100",
+          acknowledged_at: "2024-01-01T00:00:00Z",
+          converge: 1,
+          auto_merge: 1,
+        },
+      ],
+      key: "feature_key",
+    },
+  };
+  const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-3" }) } as any;
+  await startFeature(memData(stores), engine, PARSED, "main", true, true);
+  const row = stores.feature_runs.rows[0];
+  assertEquals(row.status, "running");
+  assertEquals(row.acknowledged_at, null);
+});
+
 // Issue #248: the human-readable identity for the feature grids. Every start persists a non-blank
 // `title` — the fetched issue title when available, else the `owner/repo#N` key — on BOTH the insert
 // (new run) and update (in-place restart) paths, so the title-led grid never renders a blank cell.

package/app/feature.ts

@@ -17,6 +17,7 @@
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
+import { deriveListBucket, deriveStage } from "./stage.ts";
 
 /** The BPMN process this module drives (resources/processes/feature.bpmn). */
 export const FEATURE_PROCESS_ID = "feature";
@@ -70,6 +71,25 @@ export interface FeatureRun {
    * (`record-blocked-ack` / the acknowledge operation) and, as a self-heal, by `pollFeatureBlocked`
    * when a previously-observed task is completed out-of-band (see `deriveFeatureBlockedPatch`). */
   blocked_user_task_key: string | null;
+  /** Timestamp an operator dismissed a TERMINAL run (§5, `acknowledge-done`); NULL until then. When
+   * set on a terminal row, `list_bucket` flips from 'active' to 'history'. Projection surface. */
+  acknowledged_at: string | null;
+  /** Projection maintained by the feature_runs gateway (like `delivery_label`): the canonical pipeline
+   * stage key from `deriveStage` (Requested|Implementing|PR open|Converging|Merging|Done). The page's
+   * pipeline column binds `activeField` to it. NULL only on legacy rows before `backfillFeatureStages`. */
+  stage: string | null;
+  /** Gateway projection: the active stage's render state from `deriveStage` (`ok`|`failed`|`blocked`|
+   * NULL). The page binds `stateField` to it; NULL means in-progress (renderer shows `active`). */
+  stage_state: string | null;
+  /** Gateway projection: space-separated set of stage keys NOT in this row's path from `deriveStage`
+   * (derived from `converge`/`auto_merge`). The page binds `notInPathField` to it. */
+  stage_skipped: string | null;
+  /** Gateway projection: a short attention badge (`blocked` / `⚠`) for the active stage, or NULL, from
+   * `deriveStage`. The page binds `badgeField` to it. */
+  attention: string | null;
+  /** Gateway projection: the Active/History partition label ('active'|'history'), 'history' iff a
+   * terminal row has been acknowledged. The page's tabs filter on it with flat `in` clauses (§5). */
+  list_bucket: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -251,7 +271,128 @@ export function deriveFeatureBlockedPatch(
   return Object.keys(patch).length > 0 ? patch : null;
 }
 
-export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
+/** The feature_runs fields the projection reads. A patch touching none of these cannot change the
+ * derived `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`, so the gateway can skip the
+ * read-back+reproject for it (see the `update` proxy). Kept adjacent to `projectFeatureRun` so the two
+ * stay in lockstep — every field `projectFeatureRun` reads MUST appear here. */
+const PROJECTION_INPUT_KEYS: readonly (keyof FeatureRun)[] = [
+  "status",
+  "pr_key",
+  "converge",
+  "auto_merge",
+  "escalation_question",
+  "escalation_user_task_key",
+  "blocked_user_task_key",
+  "acknowledged_at",
+];
+
+/** The feature_runs fields the projection WRITES. Included in the reproject trigger so a caller who
+ * writes a derived column directly (e.g. `stage`/`list_bucket`) can never bypass derivation: the
+ * gateway re-reads, recomputes, and OVERRIDES the raw value with the canonical derived one, keeping
+ * "the gateway is the one projection source" a true invariant. Must mirror `projectFeatureRun`'s keys. */
+const PROJECTION_OUTPUT_KEYS: readonly (keyof FeatureRun)[] = [
+  "stage",
+  "stage_state",
+  "stage_skipped",
+  "attention",
+  "list_bucket",
+];
+
+/** True when a patch changes at least one field the projection derives from OR one it writes — i.e. the
+ * projection must be recomputed. A patch touching only projection-irrelevant fields (e.g. `updated_at`)
+ * leaves the stored projection correct, since the gateway is the sole write path (see `featureRuns`); a
+ * patch that writes a derived column directly still forces a reproject so derivation can't be bypassed. */
+function patchAffectsProjection(patch: Partial<FeatureRun>): boolean {
+  return PROJECTION_INPUT_KEYS.some((k) => k in patch) || PROJECTION_OUTPUT_KEYS.some((k) => k in patch);
+}
+
+/** Compute the write-time projection columns for a fully-merged feature_runs row. Centralised so the
+ * gateway is the ONE place `deriveStage` / `deriveListBucket` are applied — the page, SQL, pollers and
+ * workers never re-derive the mapping (AGENTS.md "derivation over duplication"). */
+function projectFeatureRun(row: Partial<FeatureRun>): Partial<FeatureRun> {
+  if (!row.status) return {};
+  const { stage, state, skipped, attention } = deriveStage({
+    status: row.status,
+    pr_key: row.pr_key ?? null,
+    converge: row.converge ?? null,
+    auto_merge: row.auto_merge ?? null,
+    escalation_question: row.escalation_question ?? null,
+    escalation_user_task_key: row.escalation_user_task_key ?? null,
+    blocked_user_task_key: row.blocked_user_task_key ?? null,
+  });
+  return {
+    stage,
+    stage_state: state,
+    stage_skipped: skipped,
+    attention,
+    list_bucket: deriveListBucket(row.status, row.acknowledged_at ?? null),
+  };
+}
+
+/** The feature_runs record gateway (keyed on `feature_key`). Wrapped in a thin projecting proxy so the
+ * derived pipeline columns (`stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`) CANNOT be
+ * missed by any writer: `insert` and `update` merge the incoming values over the current stored row,
+ * then recompute the projection from that post-write field set and write it alongside — exactly the
+ * `delivery_label`-style write-time projection, but hoisted to the single gateway so the many scattered
+ * status writers (startFeature, the service pollers/reconcilers, the acknowledge operations, and the
+ * feature workers) all stay UNCHANGED and automatically get a correct, fresh projection. `update`
+ * skips the read-back+reproject for a patch that touches no projection input (e.g. an `updated_at`-only
+ * poller write), avoiding a needless `get` roundtrip — the stored projection is already correct since
+ * this gateway is the sole write path. Every other method delegates straight through. This is the sole
+ * runtime/app-layer WRITE path to feature_runs (no app-code raw SQL, no other `data.table("feature_runs")`
+ * mutation — read-only direct reads in e2e tests, and forward-only data migrations such as
+ * `db/migrations/036_backfill_titles.sql`, notwithstanding), so
+ * `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket` are
+ * always populated and correct for every row and every transition. */
+export const featureRuns = (data: DataLayer) => {
+  const table = data.table<FeatureRun>("feature_runs", "feature_key");
+  return new Proxy(table, {
+    get(target, prop) {
+      if (prop === "insert") {
+        return (row: Partial<FeatureRun>) => target.insert({ ...row, ...projectFeatureRun(row) });
+      }
+      if (prop === "update") {
+        return async (id: unknown, patch: Partial<FeatureRun>) => {
+          // Only re-read + reproject when the patch changes a projection input. A projection-irrelevant
+          // patch (e.g. an `updated_at`-only poller write) leaves the stored projection correct — the
+          // gateway is the sole write path — so skip the extra `get` roundtrip and delegate straight.
+          if (!patchAffectsProjection(patch)) return target.update(id, patch);
+          const existing = await target.get(id);
+          const merged: Partial<FeatureRun> = { ...existing, ...patch };
+          return target.update(id, { ...patch, ...projectFeatureRun(merged) });
+        };
+      }
+      // Delegate every other method straight through. Bind functions to the real target so the
+      // gateway's private class fields (`#src`) resolve — a Proxy `this` would not carry them.
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+};
+
+/** Re-project every feature_runs row through the gateway so rows written before migration 039 (whose
+ * projection columns are NULL) get correct `stage`/`stage_state`/`stage_skipped`/`attention`/
+ * `list_bucket` values. Idempotent and safe to re-run: it re-derives from each row's own stored fields,
+ * so a second pass is a no-op. Runs once at boot (pollOnce) — the gateway keeps every future write
+ * fresh, so this only needs to catch legacy rows once. */
+export async function backfillFeatureStages(data: DataLayer): Promise<number> {
+  const table = featureRuns(data);
+  const rows = await table.all();
+  let stamped = 0;
+  for (const row of rows) {
+    // Only touch rows the projection has never reached — a legacy pre-039 row whose `stage` column is
+    // still NULL. The gateway keeps every write fresh, so an already-projected row needs no re-write;
+    // skipping them avoids a full-table rewrite on every boot and keeps `stamped` an honest count of
+    // rows actually backfilled (not the total row count).
+    if (row.stage != null) continue;
+    // Re-derive the projection from the legacy row's own stored fields and write it. (An empty patch
+    // would now short-circuit the projecting proxy — it only reprojects on a projection-input change —
+    // so backfill projects explicitly rather than relying on an empty-patch reproject.)
+    await table.update(row.feature_key, projectFeatureRun(row));
+    stamped++;
+  }
+  return stamped;
+}
 
 /** The deterministic task id for a single-issue run — the implementation agent branches
  * `feat/<task.id>` (see resources/prompts/feature.md), so it MUST be derivable from the issue alone
@@ -307,6 +448,11 @@ export async function startFeature(
       auto_merge: autoMerge ? 1 : 0,
       outcome: null,
       delivery_label: null,
+      // Clear the operator tick-off so a re-dispatched run is NOT silently dropped into History when
+      // it next settles: a stale `acknowledged_at` from the prior terminal run would make
+      // `deriveListBucket` flip the row to 'history' the moment it completes again, skipping the
+      // intended operator dismissal. A fresh run must re-earn its tick-off.
+      acknowledged_at: null,
       escalation_question: null,
       escalation_user_task_key: null,
       blocked_user_task_key: null,

package/app/featureGateway.test.ts

@@ -0,0 +1,195 @@
+// Tests for the feature_runs gateway's write-time pipeline projection (issue #254 §1/§3) and the
+// one-shot backfill. The gateway wraps the plain table so EVERY writer — no matter which module —
+// automatically gets a fresh `stage`/`stage_state`/`stage_skipped`/`attention`/`list_bucket`
+// projection, without passing them: the single write path is the only place `deriveStage` /
+// `deriveListBucket` are applied.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { backfillFeatureStages, featureRuns } from "./feature.ts";
+
+// An in-memory record gateway with the same semantics the real Table exposes (get/all/find/insert/
+// update). The featureRuns proxy wraps whatever data.table returns, so this exercises the real proxy.
+function memData(): { data: DataLayer; rows: any[] } {
+  const rows: any[] = [];
+  function tbl(_name: string, pk = "id") {
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, rows };
+}
+
+test("update with only {status:'opened'} projects PR open / null / active without the caller passing them", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#1", status: "running", pr_key: null, converge: 1, auto_merge: 1 });
+  await featureRuns(data).update("o/r#1", { status: "opened" });
+  assertEquals(rows[0].stage, "PR open");
+  assertEquals(rows[0].stage_state, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("update {status:'failed'} projects Done / failed", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#2", status: "running", converge: 1, auto_merge: 1 });
+  await featureRuns(data).update("o/r#2", { status: "failed" });
+  assertEquals(rows[0].stage, "Done");
+  assertEquals(rows[0].stage_state, "failed");
+});
+
+test("update {status:'blocked'} projects Done / blocked", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#3", status: "running", converge: 1, auto_merge: 1 });
+  await featureRuns(data).update("o/r#3", { status: "blocked" });
+  assertEquals(rows[0].stage, "Done");
+  assertEquals(rows[0].stage_state, "blocked");
+});
+
+test("update {status:'escalated'} on a row with no pr_key projects Implementing / null", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#4", status: "running", pr_key: null, converge: 1, auto_merge: 1 });
+  await featureRuns(data).update("o/r#4", { status: "escalated" });
+  assertEquals(rows[0].stage, "Implementing");
+  assertEquals(rows[0].stage_state, null);
+});
+
+test("a run with converge=false projects stage_skipped containing Converging and Merging", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#5", status: "running", converge: 0, auto_merge: 0 });
+  await featureRuns(data).update("o/r#5", { status: "running" });
+  assert(rows[0].stage_skipped.includes("Converging"));
+  assert(rows[0].stage_skipped.includes("Merging"));
+});
+
+test("insert projects the pipeline columns from status", async () => {
+  const { data, rows } = memData();
+  await featureRuns(data).insert({ feature_key: "o/r#6", status: "running", converge: 1, auto_merge: 1 } as any);
+  assertEquals(rows[0].stage, "Implementing");
+  assertEquals(rows[0].stage_state, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("setting acknowledged_at on a terminal row flips list_bucket to 'history'", async () => {
+  const { data, rows } = memData();
+  rows.push({ feature_key: "o/r#7", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null });
+  // Terminal but unacknowledged → still Active.
+  await featureRuns(data).update("o/r#7", { status: "merged" });
+  assertEquals(rows[0].list_bucket, "active");
+  // Acknowledge → History.
+  await featureRuns(data).update("o/r#7", { acknowledged_at: "2024-01-01T00:00:00Z" });
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].stage, "Done");
+});
+
+test("update touching only projection-irrelevant fields skips the read-back and reproject", async () => {
+  const { data, rows } = memData();
+  rows.push({
+    feature_key: "o/r#skip",
+    status: "merged",
+    converge: 1,
+    auto_merge: 1,
+    acknowledged_at: null,
+    stage: "Done",
+    stage_state: "ok",
+    stage_skipped: "",
+    attention: null,
+    list_bucket: "active",
+  });
+  // Count get() calls to prove the projection-irrelevant path does no read-back roundtrip.
+  let gets = 0;
+  const raw = (data as any).table;
+  (data as any).table = (n: string, pk?: string) => {
+    const t = raw(n, pk);
+    const origGet = t.get;
+    t.get = async (id: any) => {
+      gets++;
+      return origGet.call(t, id);
+    };
+    return t;
+  };
+  await featureRuns(data).update("o/r#skip", { updated_at: "2024-06-01T00:00:00Z" });
+  assertEquals(gets, 0);
+  assertEquals(rows[0].updated_at, "2024-06-01T00:00:00Z");
+  // Untouched projection stays as stored.
+  assertEquals(rows[0].list_bucket, "active");
+
+  // A projection-input change (acknowledged_at) DOES read back and reproject.
+  await featureRuns(data).update("o/r#skip", { acknowledged_at: "2024-06-01T00:00:00Z" });
+  assertEquals(gets, 1);
+  assertEquals(rows[0].list_bucket, "history");
+});
+
+test("a direct write of a projection output field forces reprojection and overrides the raw value", async () => {
+  const { data, rows } = memData();
+  rows.push({
+    feature_key: "o/r#bypass",
+    status: "running",
+    pr_key: null,
+    converge: 1,
+    auto_merge: 1,
+    stage: "Implementing",
+    stage_state: null,
+    list_bucket: "active",
+  });
+  // A caller tries to bypass derivation by writing the derived column directly. The gateway must NOT
+  // persist the raw value: it re-reads, recomputes from the merged inputs, and overrides it.
+  await featureRuns(data).update("o/r#bypass", { stage: "Done", list_bucket: "history" });
+  assertEquals(rows[0].stage, "Implementing");
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("backfillFeatureStages stamps legacy terminal and live rows with helper-derived values", async () => {
+  const { data, rows } = memData();
+  // Legacy rows written before migration 039 → projection columns absent/NULL.
+  rows.push({ feature_key: "o/r#8", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: "2024-01-01T00:00:00Z" });
+  rows.push({ feature_key: "o/r#9", status: "running", pr_key: null, converge: 0, auto_merge: 0 });
+
+  const stamped = await backfillFeatureStages(data);
+  assertEquals(stamped, 2);
+
+  const terminal = rows.find((r) => r.feature_key === "o/r#8");
+  assertEquals(terminal.stage, "Done");
+  assertEquals(terminal.stage_state, "ok");
+  assertEquals(terminal.list_bucket, "history");
+
+  const live = rows.find((r) => r.feature_key === "o/r#9");
+  assertEquals(live.stage, "Implementing");
+  assertEquals(live.stage_state, null);
+  assertEquals(live.stage_skipped, "Converging Merging");
+  assertEquals(live.list_bucket, "active");
+});
+
+test("backfillFeatureStages skips already-projected rows and counts only rows it stamps", async () => {
+  const { data, rows } = memData();
+  // One legacy row (no projection) + one already-projected row (gateway kept it fresh).
+  rows.push({ feature_key: "o/r#legacy", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null });
+  rows.push({ feature_key: "o/r#fresh", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null, stage: "Done", stage_state: "ok", stage_skipped: "", attention: null, list_bucket: "active", updated_at: "0" });
+
+  const stamped = await backfillFeatureStages(data);
+  // Only the legacy row is stamped; the already-projected row is skipped.
+  assertEquals(stamped, 1);
+  const legacy = rows.find((r) => r.feature_key === "o/r#legacy");
+  assertEquals(legacy.stage, "Done");
+  // The already-projected row was not re-written (its sentinel updated_at is untouched).
+  const fresh = rows.find((r) => r.feature_key === "o/r#fresh");
+  assertEquals(fresh.updated_at, "0");
+});