@nanobpm/nano-workforce 0.82.1 → 0.84.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.84.0](https://github.com/nanobpm/nano-workforce/compare/v0.83.0...v0.84.0) (2026-08-17)
+
+
+### Features
+
+* **ui:** render narrative epic-detail sections with urban prose renderer ([#270](https://github.com/nanobpm/nano-workforce/issues/270)) ([#271](https://github.com/nanobpm/nano-workforce/issues/271)) ([38c67a4](https://github.com/nanobpm/nano-workforce/commit/38c67a479693730b9a79f3a7b0f88ef574d3a456)), closes [nano-ide#274](https://github.com/nano-ide/issues/274) [#87](https://github.com/nanobpm/nano-workforce/issues/87) [274/#275](https://github.com/nanobpm/nano-workforce/issues/275)
+
+# [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)
 
 

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");
+});

package/app/service.ts

@@ -12,7 +12,7 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
-import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
+import { backfillFeatureStages, deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   coalesceTitle,
@@ -1647,12 +1647,27 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
  * The wave-merge barrier is now level-triggered and probes the engine's message-subscription state
  * over the same raw-REST search surface, so it runs only when `engineRest` is supplied (as in
  * production — `main.ts` always passes it). */
+/** One-shot guard so the feature-stage backfill (`backfillFeatureStages`) runs at most once per
+ * process, on the first `pollOnce`. Idempotent regardless, but there is no need to re-scan every row
+ * on every poll. */
+let featureStagesBackfilled = false;
+
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
   token: string,
   engineRest?: { restAddress: string; token?: string },
 ) {
+  // One-shot: re-project any pre-#254 feature_runs rows whose pipeline columns are still NULL. The
+  // gateway keeps every future write fresh, so this only needs to run once per process and is safe to
+  // re-run (it re-derives from each row's own stored fields).
+  if (!featureStagesBackfilled) {
+    // Only arm the one-shot guard AFTER a successful backfill: setting it first would swallow a
+    // transient failure (e.g. a DB blip) and leave legacy rows unprojected forever, since every later
+    // pass would skip. On a throw the guard stays false and the next `pollOnce` retries.
+    await backfillFeatureStages(data);
+    featureStagesBackfilled = true;
+  }
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);

package/app/stage.test.ts

@@ -0,0 +1,107 @@
+// Unit tests for the canonical feature-run pipeline stage model (issue #254 §1). `deriveStage` is the
+// ONE source of truth the feature_runs gateway projects onto the stored pipeline columns, so the
+// mapping must be TOTAL and DETERMINISTIC over every FEATURE_RUN_STATUS and emit the urban 0.53.0
+// `kind:"pipeline"` renderer's EXACT vocabulary (state `ok|failed|blocked|null`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { deriveListBucket, deriveStage, type StageInput } from "./stage.ts";
+
+const base = (over: Partial<StageInput> & { status: string }): StageInput => ({
+  pr_key: null,
+  converge: 1,
+  auto_merge: 1,
+  escalation_question: null,
+  escalation_user_task_key: null,
+  blocked_user_task_key: null,
+  ...over,
+});
+
+test("deriveStage is TOTAL: every one of the 11 statuses maps to a defined stage and state", () => {
+  assertEquals(FEATURE_RUN_STATUSES.length, 11);
+  for (const status of FEATURE_RUN_STATUSES) {
+    const d = deriveStage(base({ status }));
+    assert(d.stage !== undefined, `stage undefined for ${status}`);
+    assert(
+      ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"].includes(d.stage),
+      `stage out of range for ${status}: ${d.stage}`,
+    );
+    // state is one of the renderer's exact values (null allowed)
+    assert([null, "ok", "failed", "blocked"].includes(d.state), `state out of range for ${status}: ${d.state}`);
+  }
+});
+
+test("status -> stage mapping (each row)", () => {
+  // Terminal tier → Done.
+  for (const status of ["merged", "converged", "blocked", "failed", "skipped", "abandoned"]) {
+    assertEquals(deriveStage(base({ status })).stage, "Done", status);
+  }
+  // Live/parked tier.
+  assertEquals(deriveStage(base({ status: "converging" })).stage, "Converging");
+  assertEquals(deriveStage(base({ status: "opened" })).stage, "PR open");
+  assertEquals(deriveStage(base({ status: "running", pr_key: "o/r#9" })).stage, "PR open");
+  assertEquals(deriveStage(base({ status: "running" })).stage, "Implementing");
+  // The pre-start/created initial state (unknown non-terminal, no pr_key) → Requested.
+  assertEquals(deriveStage(base({ status: "created" })).stage, "Requested");
+});
+
+test("state: the three non-null values plus the null in-progress case", () => {
+  assertEquals(deriveStage(base({ status: "merged" })).state, "ok");
+  assertEquals(deriveStage(base({ status: "converged" })).state, "ok");
+  assertEquals(deriveStage(base({ status: "failed" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "skipped" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "abandoned" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "blocked" })).state, "blocked");
+  // Every non-terminal status → null (in-progress).
+  for (const status of ["running", "opened", "converging", "escalated", "awaiting_operator"]) {
+    assertEquals(deriveStage(base({ status })).state, null, status);
+  }
+});
+
+test("state emits 'failed' (not 'fail') so the renderer does not degrade a failure to active", () => {
+  assertEquals(deriveStage(base({ status: "failed" })).state, "failed");
+});
+
+test("skipped: the three converge/auto_merge cases", () => {
+  // converge off → skip both.
+  assertEquals(deriveStage(base({ status: "running", converge: 0, auto_merge: 0 })).skipped, "Converging Merging");
+  // converge on, auto_merge off → skip Merging only.
+  assertEquals(deriveStage(base({ status: "running", converge: 1, auto_merge: 0 })).skipped, "Merging");
+  // both on → empty.
+  assertEquals(deriveStage(base({ status: "running", converge: 1, auto_merge: 1 })).skipped, "");
+});
+
+test("attention: blocked, escalation, none", () => {
+  assertEquals(deriveStage(base({ status: "awaiting_operator", blocked_user_task_key: "ut-1" })).attention, "blocked");
+  assertEquals(deriveStage(base({ status: "escalated", escalation_user_task_key: "ut-2" })).attention, "⚠");
+  assertEquals(deriveStage(base({ status: "escalated", escalation_question: "which base?" })).attention, "⚠");
+  assertEquals(deriveStage(base({ status: "running" })).attention, null);
+});
+
+// The three parked-status rows called out by the plan review.
+test("escalated WITH pr_key → PR open / null", () => {
+  const d = deriveStage(base({ status: "escalated", pr_key: "o/r#5" }));
+  assertEquals(d.stage, "PR open");
+  assertEquals(d.state, null);
+});
+
+test("escalated WITHOUT pr_key → Implementing / null", () => {
+  const d = deriveStage(base({ status: "escalated", pr_key: null }));
+  assertEquals(d.stage, "Implementing");
+  assertEquals(d.state, null);
+});
+
+test("awaiting_operator WITHOUT pr_key → Implementing / null, attention 'blocked' when parked", () => {
+  const d = deriveStage(base({ status: "awaiting_operator", pr_key: null, blocked_user_task_key: "ut-3" }));
+  assertEquals(d.stage, "Implementing");
+  assertEquals(d.state, null);
+  assertEquals(d.attention, "blocked");
+});
+
+test("deriveListBucket: history iff terminal AND acknowledged, else active", () => {
+  assertEquals(deriveListBucket("merged", null), "active");
+  assertEquals(deriveListBucket("merged", "2024-01-01T00:00:00Z"), "history");
+  // A non-terminal status is always active, even if (spuriously) acknowledged.
+  assertEquals(deriveListBucket("running", "2024-01-01T00:00:00Z"), "active");
+  assertEquals(deriveListBucket("blocked", "2024-01-01T00:00:00Z"), "history");
+});

package/app/stage.ts

@@ -0,0 +1,111 @@
+// Canonical feature-run pipeline stage model (issue #254 §1) — the ONE source of truth for the
+// derived pipeline surface the Feature view renders. Mirrors the single-source-of-truth style of
+// `deriveDelivery` (app/delivery.ts) and `classifyEscalation` (app/escalationTaxonomy.ts): a PURE,
+// read-only function with no data access. The feature_runs gateway (app/feature.ts) projects its
+// output onto the stored `stage`/`stage_state`/`stage_skipped`/`attention` columns at write time,
+// exactly as `delivery_label` is projected — so the declarative dataGrid page consumes ready, stored
+// columns (bound by `{"field":…}`) and never has to call TS or express OR/null in its flat filter DSL.
+//
+// The mapping is TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES, computed from ONLY the
+// fields stored on the row — never a "previous"/"underlying" stage, because a FeatureRun stores only
+// its CURRENT status (any prior stage was overwritten on transition). Do NOT duplicate this mapping
+// anywhere (not in SQL, not in the page, not in each poller/worker): every writer flows through the
+// gateway, which is the single caller.
+
+/** The canonical pipeline stage keys, in path order. `Merging` is a path/visual stage the renderer
+ * fills as upcoming — no status maps to it as the ACTIVE stage (intentional). */
+export const STAGE_KEYS = ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"] as const;
+export type StageKey = (typeof STAGE_KEYS)[number];
+
+/** The active stage's render state, in the urban 0.53.0 `kind:"pipeline"` column's EXACT vocabulary:
+ * `ok` (Done ✓ success), `failed` (Done ✕ failure), `blocked` (blocked glyph), or `null` (in-progress
+ * → the renderer treats it as `active`). Any OTHER string silently degrades to `active` in the
+ * renderer, so a failed run MUST emit `'failed'` (not `'fail'`) to render as a failure. */
+export type StageState = "ok" | "failed" | "blocked" | null;
+
+/** The 6 TRULY-terminal statuses that map to the `Done` stage. Distinct from
+ * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which is the redispatch-settled set and also counts
+ * `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/`Converging`), NOT
+ * Done, so this list must stay separate. Also the basis of the `list_bucket` history partition. */
+export const STAGE_DONE_STATUSES: readonly string[] = [
+  "merged",
+  "converged",
+  "blocked",
+  "failed",
+  "skipped",
+  "abandoned",
+];
+
+/** The subset of a FeatureRun `deriveStage` reads. FeatureRun (app/feature.ts) structurally satisfies
+ * this; keeping the input structural avoids a stage.ts ↔ feature.ts import cycle. */
+export interface StageInput {
+  status: string;
+  pr_key?: string | null;
+  converge?: number | boolean | null;
+  auto_merge?: number | boolean | null;
+  escalation_question?: string | null;
+  escalation_user_task_key?: string | null;
+  blocked_user_task_key?: string | null;
+}
+
+/** The derived pipeline projection for one run. `skipped` is a space-separated set of stage keys not
+ * in this row's path (bound to the renderer's `notInPathField`). */
+export interface DerivedStage {
+  stage: StageKey;
+  state: StageState;
+  skipped: string;
+  attention: string | null;
+}
+
+const truthy = (v: number | boolean | null | undefined): boolean => v === true || (typeof v === "number" && v !== 0);
+
+/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
+ * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). */
+export function deriveStage(run: StageInput): DerivedStage {
+  const { status } = run;
+
+  // TERMINAL tier — the 6 truly-terminal statuses collapse to Done. Unconditional: terminal `blocked`
+  // is the issue §1 'Done ✕' row (state `blocked`), NOT Implementing.
+  let stage: StageKey;
+  let state: StageState;
+  if (STAGE_DONE_STATUSES.includes(status)) {
+    stage = "Done";
+    state =
+      status === "merged" || status === "converged"
+        ? "ok"
+        : status === "blocked"
+          ? "blocked"
+          : "failed"; // failed / skipped / abandoned
+  } else {
+    // LIVE/PARKED tier — one shared rule for every non-terminal status. `escalated`/`awaiting_operator`
+    // are parked but their stored fields still describe WHERE in the pipeline they stalled, so they run
+    // through the same rule as a live run; their attention comes from the badge (below), not the stage.
+    if (status === "converging") stage = "Converging";
+    else if ((run.pr_key ?? "") !== "" || status === "opened") stage = "PR open";
+    else if (status === "running" || status === "escalated" || status === "awaiting_operator") stage = "Implementing";
+    else stage = "Requested";
+    state = null;
+  }
+
+  // `skipped`: stages not in this row's path, purely from converge/auto_merge.
+  const converge = truthy(run.converge);
+  const autoMerge = truthy(run.auto_merge);
+  const skippedKeys: StageKey[] = !converge ? ["Converging", "Merging"] : !autoMerge ? ["Merging"] : [];
+
+  // `attention`: a short badge for the active stage (the renderer colours it from `state`). This is how
+  // a parked `awaiting_operator`/`escalated` run surfaces as attention WITHOUT altering its stage.
+  const attention = run.blocked_user_task_key
+    ? "blocked"
+    : run.escalation_user_task_key || run.escalation_question
+      ? "⚠"
+      : null;
+
+  return { stage, state, skipped: skippedKeys.join(" "), attention };
+}
+
+/** The Active/History partition label (§5), maintained at write time so the flat-DSL page tabs filter
+ * on a stored `list_bucket` column with only `in` clauses. `history` iff the row is in a truly-terminal
+ * status AND acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). */
+export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
+  return STAGE_DONE_STATUSES.includes(status) && acknowledgedAt != null ? "history" : "active";
+}

package/db/migrations/039_feature_pipeline_stage.sql

@@ -0,0 +1,29 @@
+-- 039_feature_pipeline_stage.sql — issue #254 §1/§5: reify the feature-run pipeline stage and the
+-- Active/History tick-off partition as derived, write-time-projected columns, so the declarative
+-- Feature view can render an intent-first pipeline track and a Done tick-off with only stored
+-- `{"field":…}` bindings and flat `in` filters (the dataGrid page DSL has no OR / IS NULL / TS
+-- callback). These mirror the existing `delivery_label` / `epic_phase` display projections: each is
+-- maintained by the feature_runs gateway (app/feature.ts) from the pure `deriveStage` helper
+-- (app/stage.ts) on every write — never hand-derived in SQL, the page, or a poller.
+--
+-- Columns:
+--   • acknowledged_at — NULL until an operator dismisses a terminal run (§5, acknowledge-done).
+--   • stage           — deriveStage(...).stage: Requested|Implementing|PR open|Converging|Merging|Done
+--                       (the page's pipeline column binds `activeField` to it).
+--   • stage_state     — deriveStage(...).state: ok|failed|blocked|NULL (bound to `stateField`).
+--   • stage_skipped   — deriveStage(...).skipped: space-separated not-in-path stage keys (`notInPathField`).
+--   • attention       — deriveStage(...).attention: short badge text or NULL (`badgeField`).
+--   • list_bucket     — 'active' | 'history': history iff terminal AND acknowledged, else active
+--                       (Active = live + terminal-but-unacknowledged; History = acknowledged terminals).
+--
+-- Forward-only, additive (expand): all nullable with no default, so pre-#254 rows grandfather in as
+-- NULL and never gate control flow. `backfillFeatureStages` (app/feature.ts) stamps legacy rows once
+-- at boot, and the gateway keeps every future write fresh. Numbered after the current highest prefix
+-- on origin/main (038); the runner wraps each file in its own transaction, so this file must NOT
+-- contain BEGIN/COMMIT.
+ALTER TABLE feature_runs ADD COLUMN acknowledged_at TEXT;
+ALTER TABLE feature_runs ADD COLUMN stage TEXT;
+ALTER TABLE feature_runs ADD COLUMN stage_state TEXT;
+ALTER TABLE feature_runs ADD COLUMN stage_skipped TEXT;
+ALTER TABLE feature_runs ADD COLUMN attention TEXT;
+ALTER TABLE feature_runs ADD COLUMN list_bucket TEXT;

package/main.ts

@@ -96,7 +96,11 @@ async function pollLoop(): Promise<void> {
   }
   if (!shuttingDown) pollTimer = setTimeout(() => void pollLoop(), POLL_MS);
 }
-if (app.data) pollTimer = setTimeout(() => void pollLoop(), POLL_MS);
+// Run the first pass immediately at boot (not after POLL_MS) so the one-shot feature-stage backfill
+// runs before the UI is relied upon — the Feature Runs grid/tabs filter on the stored `list_bucket`
+// projection, which is NULL on legacy rows until `backfillFeatureStages()` runs inside `pollOnce()`.
+// Deferring the first pass would leave those rows missing from Active/History for up to POLL_MS.
+if (app.data) void pollLoop();
 
 async function drainAndExit(): Promise<void> {
   if (shuttingDown) return;

package/openapi.yaml

@@ -1501,6 +1501,53 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-done:
+    post:
+      operationId: acknowledgeDone
+      summary: "Tick off a TERMINAL feature run (issue #254 §5). Stamps `acknowledged_at` on the run so
+        the gateway recomputes its `list_bucket` to 'history', dropping the finished run out of the
+        primary Active list into History. The Done twin of acknowledge-blocked, but a terminal run is
+        not parked at a user task, so this completes no user task and only writes the row. Keyed on the
+        run's `feature_key`; idempotent-safe (re-acknowledging keeps it in History)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - feature_key
+              properties:
+                feature_key:
+                  type: string
+                  minLength: 1
+                  description: The feature run's key (feature_runs.feature_key, `<owner>/<repo>#<n>`).
+      responses:
+        "200":
+          description: The terminal run was acknowledged and moved to History.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field (feature_key) was missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No feature run matches the feature_key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "409":
+          description: The feature run is not terminal, so it cannot be ticked off yet.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation

package/operations/acknowledgeDone.test.ts

@@ -0,0 +1,108 @@
+// Tests for the POST /app/api/actions/acknowledge-done operation `acknowledgeDone` (issue #254 §5).
+// The nwf UI's "tick off" affordance for a TERMINAL feature run: it stamps `acknowledged_at` via the
+// feature_runs gateway, which recomputes `list_bucket` to 'history', dropping the run from Active into
+// History. Unlike acknowledgeBlocked it completes NO user task (a terminal run is not parked). Mirrors
+// the acknowledge-blocked twin's shape.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { featureRuns } from "../app/feature.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./acknowledgeDone.ts";
+
+// An in-memory data layer wired through the REAL featureRuns gateway proxy, so the test exercises the
+// gateway's list_bucket projection exactly as production does.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  const stores: Record<string, any[]> = { feature_runs: seed };
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    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 app = {
+    data: { table: (n: string, pk?: string) => tbl(n, pk) },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, rows: stores.feature_runs };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-done: stamps acknowledged_at and flips list_bucket to 'history' on a terminal row", async () => {
+  const { app, rows } = memApp([{ feature_key: "o/r#1", status: "merged", converge: 1, auto_merge: 1, acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (terminal, unacknowledged → active).
+  await featureRuns(app.data).update("o/r#1", { status: "merged" });
+  assertEquals(rows[0].list_bucket, "active");
+
+  const res = await call(app, { feature_key: "o/r#1" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+});
+
+test("acknowledge-done: idempotent-safe — re-acknowledging keeps the row in History", async () => {
+  const { app, rows } = memApp([{ feature_key: "o/r#2", status: "failed", converge: 1, auto_merge: 1, acknowledged_at: null }]);
+  const first = await call(app, { feature_key: "o/r#2" });
+  assertEquals(first.status, 200);
+  assertEquals(rows[0].list_bucket, "history");
+  const firstStamp = rows[0].acknowledged_at;
+  // Re-acknowledge — still 200, still history.
+  const second = await call(app, { feature_key: "o/r#2" });
+  assertEquals(second.status, 200);
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(typeof firstStamp, "string");
+});
+
+test("acknowledge-done: a missing feature_key → 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, {});
+  assertEquals(res.status, 400);
+  assertEquals(res.body.ok, false);
+});
+
+test("acknowledge-done: no such feature run → 404", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { feature_key: "o/r#gone" });
+  assertEquals(res.status, 404);
+  assertEquals(res.body.ok, false);
+});
+
+test("acknowledge-done: a non-terminal run → 409, no acknowledged_at stamped", async () => {
+  const { app, rows } = memApp([{ feature_key: "o/r#live", status: "running", converge: 1, auto_merge: 1, acknowledged_at: null }]);
+  await featureRuns(app.data).update("o/r#live", { status: "running" });
+  const res = await call(app, { feature_key: "o/r#live" });
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  assertEquals(rows[0].acknowledged_at, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("acknowledge-done: a converging (redispatch-terminal but live) run → 409", async () => {
+  const { app, rows } = memApp([{ feature_key: "o/r#conv", status: "converging", converge: 1, auto_merge: 1, acknowledged_at: null }]);
+  const res = await call(app, { feature_key: "o/r#conv" });
+  assertEquals(res.status, 409);
+  assertEquals(rows[0].acknowledged_at, null);
+});

package/operations/acknowledgeDone.ts

@@ -0,0 +1,53 @@
+// POST /app/api/actions/acknowledge-done → operationId `acknowledgeDone` (issue #254 §5).
+// The nwf UI's "tick off" affordance for a TERMINAL feature run: an operator dismisses a finished
+// run (Done ✓ / Done ✕) directly from the Feature / Overview pages so it drops out of the primary
+// Active list into History. It is the DONE twin of `acknowledgeBlocked` — but a terminal run is NOT
+// parked at a user task, so this op does NOT complete a user task and touches no engine/ledger: it
+// simply stamps `acknowledged_at` on the row via the feature_runs gateway. It rejects (409) a run that
+// is not yet truly terminal, so it can never pre-seed the tick-off on a still-live run.
+//
+// The gateway (app/feature.ts) recomputes `list_bucket` on that write — a terminal row with
+// `acknowledged_at` set flips to 'history' — so this op NEVER hand-sets `list_bucket` (or any other
+// projection). Keyed on the row's `feature_key`. Idempotent-safe: re-acknowledging simply re-stamps
+// the timestamp and keeps the row in History.
+
+import { featureRuns } from "../app/feature.ts";
+import { STAGE_DONE_STATUSES } from "../app/stage.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgeDone", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-done rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "feature_key is required" } };
+  }
+
+  const featureKey = str(body.feature_key);
+  if (!featureKey) return { status: 400, body: { ok: false, error: "feature_key is required" } };
+
+  const runs = featureRuns(app.data);
+  const run = await runs.get(featureKey);
+  if (!run) {
+    app.log.warn("acknowledge-done: no such feature run", { featureKey });
+    return { status: 404, body: { ok: false, error: "no such feature run" } };
+  }
+
+  // Guard: only a TRULY-terminal run (a `Done`-stage status — the same set `deriveListBucket` moves to
+  // History) may be ticked off. Acknowledging a still-live run (e.g. `running`/`opened`/`converging`)
+  // would pre-seed `acknowledged_at`, so the moment it later settles `deriveListBucket` would drop it
+  // straight into History, skipping the operator tick-off this op exists to require.
+  if (!STAGE_DONE_STATUSES.includes(run.status)) {
+    app.log.warn("acknowledge-done rejected: run is not terminal", { featureKey, status: run.status });
+    return { status: 409, body: { ok: false, error: "feature run is not terminal" } };
+  }
+
+  // Stamp the dismissal. The gateway recomputes `list_bucket` from the merged row (→ 'history' for a
+  // terminal run), so we never hand-set it here. Idempotent: re-acknowledging re-stamps and stays in
+  // History.
+  const now = new Date().toISOString();
+  await runs.update(featureKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator ticked off feature run", { featureKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.82.1",
+  "version": "0.84.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",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.1.0",
-    "@nanobpm/urban": "^0.52.0"
+    "@nanobpm/urban": "^0.54.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/pages/epic-detail.page.json

@@ -137,38 +137,36 @@
       }
     },
     {
-      "type": "dataGrid",
+      "type": "prose",
       "id": "plan-reviews",
       "props": {
         "title": "Plan review trace",
         "refreshMs": 5000,
         "collapsible": true,
         "defaultCollapsed": true,
+        "measure": 80,
+        "empty": "No plan reviews recorded yet.",
         "data": {
           "kind": "datasource",
           "source": "app",
           "table": "plan_reviews",
-          "orderBy": { "field": "round", "dir": "asc" },
+          "orderBy": { "field": "created_at", "dir": "asc" },
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },
-        "columns": [
-          { "field": "round", "header": "Round" },
-          { "field": "epoch", "header": "Epoch" },
-          { "field": "approved", "header": "Approved? (1/0)" },
-          { "field": "findings", "header": "Reviewer findings" },
-          { "field": "created_at", "header": "Recorded" }
-        ]
+        "header": "Round {{round}} · epoch {{epoch}} · approved {{approved}} · {{created_at}}",
+        "body": "findings"
       }
     },
     {
-      "type": "dataGrid",
+      "type": "prose",
       "id": "plan-review-escalations",
       "props": {
         "title": "Plan-review escalations",
-        "rowKey": "id",
         "refreshMs": 5000,
         "collapsible": true,
         "defaultCollapsed": true,
+        "measure": 80,
+        "empty": "No plan-review escalations.",
         "data": {
           "kind": "datasource",
           "source": "app",
@@ -176,16 +174,8 @@
           "orderBy": { "field": "id", "dir": "desc" },
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },
-        "columns": [
-          { "field": "epoch", "header": "Epoch" },
-          { "field": "round", "header": "Round" },
-          { "field": "findings", "header": "Findings" },
-          { "field": "status", "header": "Status" },
-          { "field": "directive", "header": "Directive" },
-          { "field": "note", "header": "Human note" },
-          { "field": "asked_at", "header": "Asked" },
-          { "field": "answered_at", "header": "Answered" }
-        ]
+        "header": "Round {{round}} · epoch {{epoch}} · {{status}} · directive {{directive}} · asked {{asked_at}} · answered {{answered_at}} · note {{note}}",
+        "body": "findings"
       }
     },
     {
@@ -214,14 +204,15 @@
       }
     },
     {
-      "type": "dataGrid",
+      "type": "prose",
       "id": "coordination-notes",
       "props": {
         "title": "Coordination notes",
-        "rowKey": "id",
         "refreshMs": 5000,
         "collapsible": true,
         "defaultCollapsed": true,
+        "measure": 80,
+        "empty": "No coordination notes posted yet.",
         "data": {
           "kind": "datasource",
           "source": "app",
@@ -229,14 +220,8 @@
           "orderBy": { "field": "id", "dir": "asc" },
           "filter": [{ "field": "plan_key", "eqParam": true }]
         },
-        "columns": [
-          { "field": "wave", "header": "Wave" },
-          { "field": "author_task", "header": "Agent" },
-          { "field": "kind", "header": "Kind" },
-          { "field": "files", "header": "Files" },
-          { "field": "body", "header": "Note" },
-          { "field": "created_at", "header": "Posted" }
-        ]
+        "header": "Wave {{wave}} · {{author_task}} · {{kind}} · files {{files}} · {{created_at}}",
+        "body": "body"
       }
     },
     {

package/pages/feature.page.json

@@ -63,23 +63,33 @@
           "source": "app",
           "table": "feature_runs",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }]
+          "filter": [{ "field": "list_bucket", "in": ["active"] }]
         },
         "tabs": [
-          { "label": "Active", "filter": [{ "field": "status", "in": ["running", "escalated", "awaiting_operator"] }] },
-          { "label": "History", "filter": [{ "field": "status", "in": ["opened", "converging", "merged", "converged", "blocked", "skipped", "failed", "abandoned"] }] },
+          { "label": "Active", "filter": [{ "field": "list_bucket", "in": ["active"] }] },
+          { "label": "History", "filter": [{ "field": "list_bucket", "in": ["history"] }] },
           { "label": "All", "filter": [] }
         ],
         "columns": [
-          { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "feature_key", "truncate": true, "width": "34%", "linkField": "issue_url" },
-          { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
-          { "field": "escalation_question", "header": "Escalation", "truncate": true },
-          { "field": "base_branch", "header": "Base branch" },
-          { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
-          { "field": "delivery_label", "header": "Delivery" },
-          { "field": "converge", "header": "Converge" },
-          { "field": "auto_merge", "header": "Auto-merge" },
-          { "field": "outcome", "header": "Outcome" },
+          { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "feature_key", "truncate": true, "width": "30%", "linkField": "issue_url" },
+          {
+            "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",
+            "badgeField": "attention",
+            "notInPathField": "stage_skipped",
+            "locus": { "field": "pr_key", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } }
+          },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
         ],
         "rowActions": [
@@ -100,11 +110,21 @@
               "path": "/app/api/actions/acknowledge-blocked",
               "body": { "userTaskKey": "{{row.blocked_user_task_key}}" }
             }
+          },
+          {
+            "label": "Dismiss",
+            "confirm": "Tick off this finished run? It acknowledges the run as done and files it under History.",
+            "showWhenField": "stage_state",
+            "action": {
+              "path": "/app/api/actions/acknowledge-done",
+              "body": { "feature_key": "{{row.feature_key}}" }
+            }
           }
         ],
         "detail": {
           "fields": [
             { "field": "escalation_question", "label": "Escalation question" },
+            { "field": "base_branch", "label": "Base branch" },
             { "field": "outcome", "label": "Outcome" },
             { "field": "delivery_label", "label": "Delivery" }
           ],

package/scripts/pages-contract.test.ts

@@ -112,6 +112,12 @@ function filterFields(filter: Json): string[] {
   return filter.map((f: Json) => f?.field).filter(Boolean);
 }
 
+// Pull `{{field}}` interpolation names out of a prose renderer's header template (nano-ide#274).
+function templateFields(tpl: Json): string[] {
+  if (typeof tpl !== "string") return [];
+  return [...tpl.matchAll(/\{\{([^{}]+)\}\}/g)].map((m) => m[1].trim()).filter(Boolean);
+}
+
 function collectRefs(page: string, node: Json, out: Ref[]): void {
   if (Array.isArray(node)) {
     for (const v of node) collectRefs(page, v, out);
@@ -120,10 +126,17 @@ function collectRefs(page: string, node: Json, out: Ref[]): void {
   if (!node || typeof node !== "object") return;
 
   // Top-level datasource grid: the datasource lives at `node.data`, while `columns`, `rowKey`,
-  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props).
+  // `filter`/`tabs`, and `detail` are siblings on the same `node` (the grid props). A `prose`
+  // renderer (nano-ide#274) binds the same `node.data` but has no `columns`: its displayed content
+  // is the header template's `{{field}}` refs plus the single `body` field, so fold those in as
+  // "columns" so the field-existence + surface guards below apply to prose sections too.
   const data = node.data;
   if (data && data.kind === "datasource" && typeof data.table === "string") {
-    const columns: string[] = (node.columns ?? []).map((c: Json) => c.field).filter(Boolean);
+    const columns: string[] = [
+      ...(node.columns ?? []).map((c: Json) => c.field),
+      ...templateFields(node.header),
+      ...(typeof node.body === "string" ? [node.body] : []),
+    ].filter(Boolean);
     // Every reference that resolves to a column on this table — the runtime 400s on any of them if
     // it names a column the migrations never created, so all must be guarded, not just displayed
     // columns. `detail.fields`/`detail.linkField` render columns of the same top-level row.
@@ -215,17 +228,19 @@ test("issue #87: plan_reviews is surfaced on the per-epic detail page", async ()
   const onEpicDetail = refs.some(
     (r) => r.page === "epic-detail.page.json" && r.table === "plan_reviews",
   );
-  assert(onEpicDetail, "epic-detail.page.json must bind a grid to plan_reviews (plan-review trace)");
+  assert(onEpicDetail, "epic-detail.page.json must bind the plan-review trace to plan_reviews");
 
-  // The trace is only useful with the verdict + critique columns, so pin them. Assert against the
-  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) so
-  // a column silently dropped from the grid UI can't pass by being referenced elsewhere.
+  // The trace is only useful with the verdict + critique surfaced, so pin them. Assert against the
+  // visibly displayed `columns` (not `fields`, which also holds binding refs like orderBy.field) —
+  // for the `prose` renderer (nano-ide#274) these are the header template's `{{round}}`/`{{approved}}`
+  // refs plus the `findings` body — so a field silently dropped from the UI can't pass by being
+  // referenced elsewhere.
   const required = ["round", "approved", "findings"];
   for (const r of refs.filter((x) => x.table === "plan_reviews")) {
     for (const col of required) {
       assert(
         r.columns.includes(col),
-        `${r.page}: plan_reviews grid must expose the "${col}" column`,
+        `${r.page}: plan_reviews trace must surface the "${col}" field`,
       );
     }
   }