@nanobpm/nano-workforce 0.82.0 → 0.83.0

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.0",
+  "version": "0.83.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.53.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

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/workers/record-wave/worker.ts

@@ -293,9 +293,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
 
   // 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
-  // `wave-merged` once the wave has landed. Clear it on the final wave so a re-planned issue can't
-  // inherit a stale gate. Best-effort: a failed marker write must not fail the wave (the poller
+  // `gate_wave` is that durable marker; the level-triggered poller (`pollWaveGatesImpl`) publishes
+  // `wave-merged` once the wave has landed AND it observes an OPEN subscription, but NEVER clears
+  // `gate_wave` — record-wave owns the marker's lifecycle. Re-arm it to the next wave here, or
+  // clear it on the final wave so a re-planned issue can't inherit a stale gate. Best-effort: a
+  // failed marker write must not fail the wave (the poller
   // reconciles from `plan_tasks`/`pull_requests`), but the loop still relies on it to know which
   // wave to watch, so we log a failure loudly.
   try {