@nanobpm/nano-workforce 0.79.0 → 0.81.0

package/openapi.yaml

@@ -99,6 +99,99 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    LineagePrView:
+      type: object
+      description: A member PR of a lineage thread (issue #245).
+      additionalProperties: false
+      required:
+        - prKey
+        - title
+        - url
+        - status
+        - round
+        - processKey
+        - outcome
+      properties:
+        prKey:
+          type: string
+        title:
+          type: string
+          nullable: true
+        url:
+          type: string
+        status:
+          type: string
+        round:
+          type: integer
+        processKey:
+          type: string
+          nullable: true
+        outcome:
+          type: string
+          nullable: true
+    LineageThreadView:
+      type: object
+      description: One stitched intent → progress arc, keyed by its origin request (issue #245).
+      additionalProperties: false
+      required:
+        - rootRequestKey
+        - kind
+        - title
+        - issueUrl
+        - stage
+        - stageLabel
+        - processKey
+        - prKeys
+        - prCount
+        - active
+        - prs
+      properties:
+        rootRequestKey:
+          type: string
+          description: The origin issue key (feature_key/plan_key), or a self-rooted pr_key.
+        kind:
+          type: string
+          enum: [feature, epic, pr]
+        title:
+          type: string
+          nullable: true
+        issueUrl:
+          type: string
+          nullable: true
+        stage:
+          type: string
+          description: The active-frontier stage (implementing|converging|merged|…).
+        stageLabel:
+          type: string
+        processKey:
+          type: string
+          nullable: true
+          description: The active-frontier process instance key (for the processExplorer link).
+        prKeys:
+          type: array
+          items:
+            type: string
+        prCount:
+          type: integer
+        active:
+          type: boolean
+          description: True while the arc has an active frontier; false once every stage has settled.
+        prs:
+          type: array
+          items:
+            $ref: "#/components/schemas/LineagePrView"
+    LineageList:
+      type: object
+      required:
+        - count
+        - threads
+      properties:
+        count:
+          type: integer
+        threads:
+          type: array
+          items:
+            $ref: "#/components/schemas/LineageThreadView"
     AgenticSupplyWorker:
       type: object
       description: One connected worker in the supply mirror (H5 cockpit; sourced from the H1 presence registry).
@@ -936,6 +1029,33 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /lineage:
+    get:
+      operationId: getLineage
+      summary: "Intent to progress lineage projection (issue #245): every request stitched into one arc (request, implementation, PRs, convergence, merge, outcome), active frontier first. Pass root to fetch a single origin's thread."
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: root
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "An origin request key (feature_key/plan_key) or a self-rooted pr_key. When set, the response contains just that thread (empty if unknown)."
+      responses:
+        "200":
+          description: The stitched lineage threads.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LineageList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/supply:
     get:
       operationId: getAgenticSupply

package/operations/getLineage.test.ts

@@ -0,0 +1,105 @@
+// Tests for GET /app/api/lineage → operation `getLineage` (issue #245). Covers the stitched list
+// projection, the `root` narrowing, an unknown root (empty), and the optional shared-secret guard.
+// A minimal in-memory DataLayer backs the derivation (it reads the feature_runs / plans / plan_tasks
+// / pull_requests tables via `.all()` / `.find()`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./getLineage.ts";
+
+function memApp(stores: Record<string, any[]>): AppApi {
+  const table = (name: string) => {
+    const rows = stores[name] ?? [];
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async find(where: Record<string, unknown> = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+    };
+  };
+  return { data: { table }, log: noopLog() } as any as AppApi;
+}
+
+function input(query: Record<string, string> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/lineage",
+      query: new URLSearchParams(query),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+function fixture(): Record<string, any[]> {
+  return {
+    feature_runs: [
+      { feature_key: "o/r#1", title: "Feature", issue_url: "u1", status: "converging", process_key: "f1", pr_key: "o/r#100" },
+    ],
+    plans: [
+      { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1" },
+    ],
+    plan_tasks: [
+      { id: 1, plan_key: "o/r#2", pr_key: "o/r#200" },
+      { id: 2, plan_key: "o/r#2", pr_key: "o/r#201" },
+    ],
+    pull_requests: [
+      { pr_key: "o/r#100", title: "Feat PR", url: "x", status: "converging", current_round: 2, process_key: "c1", outcome: null, root_request_key: "o/r#1" },
+      { pr_key: "o/r#200", title: "S1", url: "x", status: "merged", current_round: 1, process_key: "c2", outcome: null, root_request_key: "o/r#2" },
+      { pr_key: "o/r#201", title: "S2", url: "x", status: "converging", current_round: 1, process_key: "c3", outcome: null, root_request_key: "o/r#2" },
+      { pr_key: "o/r#300", title: "Human PR", url: "x", status: "merged", current_round: 1, process_key: "c4", outcome: null, root_request_key: null },
+    ],
+  };
+}
+
+test("lists every stitched thread, active frontier first", async () => {
+  const res = (await handler(input(), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 3);
+  // Active threads (feature + epic) sort ahead of the settled human PR.
+  assert(res.body.threads[res.body.threads.length - 1].active === false);
+  const kinds = res.body.threads.map((t: any) => t.kind).sort();
+  assertEquals(kinds, ["epic", "feature", "pr"]);
+});
+
+test("narrows to a single origin thread via ?root=", async () => {
+  const res = (await handler(input({ root: "o/r#2" }), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 1);
+  const t = res.body.threads[0];
+  assertEquals(t.kind, "epic");
+  assertEquals(t.rootRequestKey, "o/r#2");
+  assertEquals(t.prCount, 2);
+});
+
+test("unknown root returns an empty thread list", async () => {
+  const res = (await handler(input({ root: "o/r#999" }), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.threads, []);
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getLineage.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const app = memApp(fixture());
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getLineage.ts

@@ -0,0 +1,32 @@
+// GET /app/api/lineage → operationId `getLineage` (issue #245). Project user intent → progress as
+// one lineage arc per origin request, so an operator or an external harness can see, in one place,
+// that "issue #123 → implementation → PR #45 → converging (round 2) → merged" is a single thread of
+// their intent — without opening the DB or joining the tables by hand. Read-only projection over the
+// existing record-gateway joins (the same derivation the `lineage_threads` read table is built from).
+//
+// Optional `root` query param narrows to a single origin's thread (feature_key/plan_key, or a
+// self-rooted pr_key for a human/webhook PR). Absent → every thread, active frontier first.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`):
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header.
+import { getLineage, listLineage } from "../app/lineage.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getLineage", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getLineage rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rawRoot = query.root;
+  const root = typeof rawRoot === "string" ? rawRoot.trim() : "";
+  if (root) {
+    const thread = await getLineage(app.data, root);
+    const threads = thread ? [thread] : [];
+    return { status: 200, body: { count: threads.length, threads } };
+  }
+  const threads = await listLineage(app.data);
+  return { status: 200, body: { count: threads.length, threads } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.79.0",
+  "version": "0.81.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/cockpit.page.json

@@ -10,6 +10,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/epic-detail.page.json

@@ -11,6 +11,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/epic.page.json

@@ -11,6 +11,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/feature.page.json

@@ -11,6 +11,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/home.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
           {
             "label": "Convergence",
             "page": "home"

package/pages/lineage.page.json

@@ -0,0 +1,146 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Lineage",
+  "nodes": [
+    {
+      "type": "nav",
+      "id": "nav",
+      "props": {
+        "variant": "bar",
+        "title": "Nano Workforce",
+        "items": [
+          { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
+          { "label": "Convergence", "page": "home" },
+          { "label": "Epics", "page": "epic" },
+          { "label": "Feature", "page": "feature" },
+          { "label": "Tasks", "page": "tasks" },
+          { "label": "Cockpit", "page": "cockpit" }
+        ],
+        "sticky": true
+      }
+    },
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Lineage \u2014 intent \u2192 progress", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "One narrative per request, not a card-swap. Each row is a single arc of your intent \u2014 request \u2192 implementing \u2192 PR opened \u2192 converging (round n) \u2192 merged/converged/abandoned \u2014 stitched from the feature/epic that started it, the PR(s) it produced, and their convergence + merge outcome. The Stage column is the active frontier; drill into a row for its member PR(s) and rounds. Epics fan out to N PR sub-threads. A human/webhook PR with no originating request is shown as its own root.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "threads",
+      "props": {
+        "title": "Lineage threads",
+        "collapsible": true,
+        "defaultCollapsed": false,
+        "showCount": true,
+        "rowKey": "root_request_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "lineage_threads",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "active", "in": [1] }]
+        },
+        "tabs": [
+          {
+            "label": "Active",
+            "filter": [{ "field": "active", "in": [1] }]
+          },
+          {
+            "label": "History",
+            "filter": [{ "field": "active", "in": [0] }]
+          }
+        ],
+        "columns": [
+          {
+            "field": "title",
+            "template": "{{title}}",
+            "header": "Intent",
+            "subtitleField": "root_request_key",
+            "truncate": true,
+            "width": "34%",
+            "linkField": "issue_url"
+          },
+          { "field": "kind", "header": "Kind", "width": "6rem" },
+          {
+            "field": "stage_label",
+            "header": "Stage",
+            "truncate": true,
+            "link": { "kind": "processExplorer", "keyField": "process_key" }
+          },
+          { "field": "pr_count", "header": "PRs", "width": "5rem" },
+          { "field": "updated_at", "header": "Updated", "width": "9rem" }
+        ],
+        "detail": {
+          "linkField": "issue_url",
+          "fields": [
+            { "field": "kind", "label": "Origin kind" },
+            { "field": "stage", "label": "Frontier stage" },
+            { "field": "stage_label", "label": "Frontier" },
+            { "field": "issue_url", "label": "Origin issue" },
+            { "field": "pr_count", "label": "PR count" }
+          ],
+          "children": [
+            {
+              "title": "Pull requests in this thread",
+              "source": "app",
+              "table": "pull_requests",
+              "parentField": "root_request_key",
+              "childField": "root_request_key",
+              "orderBy": { "field": "updated_at", "dir": "asc" },
+              "columns": [
+                { "field": "title", "template": "{{title}}", "header": "PR", "subtitleField": "pr_key", "truncate": true, "linkField": "url" },
+                { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+                { "field": "current_round", "header": "Round" },
+                { "field": "outcome", "header": "Outcome", "truncate": true },
+                { "field": "updated_at", "header": "Updated", "width": "9rem" }
+              ],
+              "detail": {
+                "linkField": "url",
+                "children": [
+                  {
+                    "title": "Rounds",
+                    "source": "app",
+                    "table": "rounds",
+                    "parentField": "pr_key",
+                    "childField": "pr_key",
+                    "orderBy": { "field": "round_no", "dir": "asc" },
+                    "columns": [
+                      { "field": "round_no", "header": "#" },
+                      { "field": "status", "header": "Result" },
+                      { "field": "summary", "header": "Summary" }
+                    ]
+                  },
+                  {
+                    "title": "Escalations",
+                    "source": "app",
+                    "table": "escalations",
+                    "parentField": "pr_key",
+                    "childField": "pr_key",
+                    "orderBy": { "field": "id", "dir": "asc" },
+                    "columns": [
+                      { "field": "round_no", "header": "#" },
+                      { "field": "kind", "header": "Kind" },
+                      { "field": "question", "header": "Question" },
+                      { "field": "status", "header": "Status" },
+                      { "field": "answer", "header": "Answer" }
+                    ]
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/pages/overview.page.json

@@ -11,6 +11,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/tasks.page.json

@@ -13,6 +13,10 @@
             "label": "Overview",
             "page": "overview"
           },
+          {
+            "label": "Lineage",
+            "page": "lineage"
+          },
           {
             "label": "Convergence",
             "page": "home"

package/resources/forms/readiness-escalation.form

@@ -0,0 +1,29 @@
+{
+  "id": "readiness-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "text": "The artifact-readiness wait-gate timed out before its ReadinessProbe went green. A human decision is needed on how to proceed.",
+      "label": "Readiness timeout"
+    },
+    {
+      "type": "select",
+      "key": "resolution",
+      "label": "Resolution",
+      "values": [
+        { "label": "Acknowledge — the artifact is ready / proceed", "value": "acknowledge" },
+        { "label": "Abandon — give up on this gate", "value": "abandon" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "answer",
+      "label": "Notes for the operator"
+    }
+  ]
+}