@nanobpm/nano-workforce 0.104.0 → 0.106.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.106.0](https://github.com/nanobpm/nano-workforce/compare/v0.105.0...v0.106.0) (2026-08-20)
+
+
+### Features
+
+* escalate unmet/undisclosed conformance deviations to the Tasks inbox ([#356](https://github.com/nanobpm/nano-workforce/issues/356)) ([5ad24bc](https://github.com/nanobpm/nano-workforce/commit/5ad24bcadf833934804973a25fd96f4eb4d28a84)), closes [#354](https://github.com/nanobpm/nano-workforce/issues/354) [#354](https://github.com/nanobpm/nano-workforce/issues/354)
+
+# [0.105.0](https://github.com/nanobpm/nano-workforce/compare/v0.104.0...v0.105.0) (2026-08-19)
+
+
+### Features
+
+* examine epic implementation against spec in retro (conformance) ([#355](https://github.com/nanobpm/nano-workforce/issues/355)) ([c52d059](https://github.com/nanobpm/nano-workforce/commit/c52d0594d767c551d31ed967d1ef79cb30e82ceb)), closes [#217](https://github.com/nanobpm/nano-workforce/issues/217) [#216](https://github.com/nanobpm/nano-workforce/issues/216) [#217](https://github.com/nanobpm/nano-workforce/issues/217)
+
 # [0.104.0](https://github.com/nanobpm/nano-workforce/compare/v0.103.0...v0.104.0) (2026-08-19)
 
 

package/README.md

@@ -153,6 +153,7 @@ capability):
 | `fix-ci` | `senior:fix-ci` | `merge-loop` | Green a `blocked` PR's failing checks |
 | `rebase` | `senior:rebase` | `merge-loop` | Rebase a conflicting PR up to date with its base |
 | `retro` | `senior:retro` | `retro` | Synthesize a finished epic's learnings and promote the recurring ones |
+| `conformance` | `senior:conformance` | `retro` | Examine a finished epic's implementation against its spec; report met/deviations on the issue, and escalate an unmet/undisclosed deviation to the Tasks inbox as a non-blocking ack |
 
 - `--command 'copilot -p - --allow-all-tools'` starts the Copilot CLI reading its
   prompt from **stdin** (`-p -`). The harness pipes the whole job JSON (prompt +

package/app/abandon.ts

@@ -20,11 +20,20 @@
 import type { DataLayer } from "@nanobpm/urban";
 import { publicBaseUrl } from "./blackboard.ts";
 
-/** The one app-row status that means "this run was cancelled". Convergence/merge terminal states
- * `converged`/`merged` are NOT abandonment — only an explicit cancel flips a live run here. */
+/** The one app-row status meaning a PR is terminally abandoned — the run must not be worked on
+ * further. Two disjoint producers flip a row here, and both are non-completion terminals that must
+ * stop a servicing agent:
+ *   1. an explicit **cancel** of a live convergence/merge run (Urban's cancel primitive, via the
+ *      `instanceTracking` `onTerminated.set` patch), and
+ *   2. **`abandonClosedPr`** reconciling a wave-member PR that was **closed on GitHub without
+ *      merging** (#352) — for both `pull_requests` and its `plan_tasks`.
+ * Convergence/merge terminal states `converged`/`merged` are NOT abandonment. In either abandoned
+ * case a servicing agent should stop, so the abandon-check endpoint treating both as `abandoned:
+ * true` is correct. */
 export const ABANDONED_STATUS = "abandoned";
 
-/** True when a PR's app-row status means the run was cancelled and the agent must not act. */
+/** True when a PR's app-row status is terminally abandoned (run cancelled, or PR closed-unmerged)
+ * and the agent must not act. */
 export function isAbandoned(status: string | null | undefined): boolean {
   return status === ABANDONED_STATUS;
 }

package/app/agentCompletion.test.ts

@@ -229,6 +229,34 @@ test("feature-blocked is HUMAN-completable but NOT agent-completable (issue #332
   assertEquals(completed[0].variables, { note: "reassigned to a human" });
 });
 
+test("conformance-escalation is HUMAN-completable but NOT agent-completable (issue #216)", async () => {
+  // The retro conformance ack mirrors feature-blocked: a HUMAN operator retires it via
+  // `completeEscalationAsHuman`, but it stays OUTSIDE the agent surface (`ESCALATION_TASK_ELEMENTS`) —
+  // an agent must never acknowledge a conformance review on a human's behalf.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-c", elementId: "conformance-escalation" }]);
+
+  const asAgent = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-c",
+    agentId: "bot",
+    variables: { note: "n" },
+  });
+  assertEquals(asAgent.ok, false, "the agent completer refuses conformance-escalation");
+  assertEquals(asAgent.reason, "not a completable task");
+  assertEquals(completed.length, 0);
+
+  const asHuman = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-c",
+    operatorId: "alice",
+    variables: { note: "filed follow-up" },
+  });
+  assertEquals(asHuman.ok, true, "the human completer retires conformance-escalation");
+  assertEquals(asHuman.elementId, "conformance-escalation");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { note: "filed follow-up" });
+});
+
 test("human completer refuses a non-escalation user task and is a no-op for an unknown key", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);

package/app/agentCompletion.ts

@@ -22,6 +22,7 @@
 
 import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 
 const now = () => new Date().toISOString();
 
@@ -79,13 +80,23 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
  *  `acknowledge-blocked` door onto the one canonical `complete-user-task` door). */
 export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
 
+/** The `conformance-escalation` operator user-task element id (retro.bpmn) — the native ack a retro
+ *  run parks on when the spec-conformance audit finds the epic did NOT cleanly meet its spec (a
+ *  reduced / not-verified slice, or an unraised deviation). Like `feature-blocked` it is a human-only
+ *  acknowledgement (never agent-answerable), so it lives OUTSIDE `ESCALATION_TASK_ELEMENTS` and only
+ *  the HUMAN completer accepts it (issue #216). Re-exported from the canonical
+ *  `CONFORMANCE_ESCALATION_ELEMENT` (app/conformance.ts) — one source of truth, no drift surface. */
+export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMENT;
+
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
- *  acknowledgement. The AGENT completer stays scoped to `ESCALATION_TASK_ELEMENTS` (no `feature-blocked`),
- *  so widening the human surface never lets an agent retire a blocked run. */
+ *  and `conformance-escalation` acknowledgements. The AGENT completer stays scoped to
+ *  `ESCALATION_TASK_ELEMENTS` (neither ack), so widening the human surface never lets an agent retire
+ *  a blocked run or a conformance review. */
 export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   ...ESCALATION_TASK_ELEMENTS,
   FEATURE_BLOCKED_TASK_ELEMENT,
+  CONFORMANCE_ESCALATION_TASK_ELEMENT,
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
@@ -98,6 +109,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "wait-answer": "pr-escalation",
   "wait-merge-answer": "pr-escalation",
   "feature-blocked": "feature-blocked",
+  [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
 };
 
 /** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use

package/app/conformance.test.ts

@@ -0,0 +1,313 @@
+// Unit tests for the spec-conformance review stage (app/conformance.ts, 052_plan_conformance.sql).
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects, assertStringIncludes } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { memBlackboardSource } from "../test/blackboardDb.ts";
+import { appendEntry } from "./blackboard.ts";
+import {
+  acknowledgeConformance,
+  activeConformanceReviews,
+  gatherConformance,
+  hasDeliveredImplementation,
+  hasDeliveredImplementationForPlan,
+  recordConformance,
+  renderConformanceBrief,
+} from "./conformance.ts";
+
+// In-memory record gateway matching the Table<T> subset conformance.ts uses.
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  const seq: Record<string, number> = {};
+  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 insert(row: any) {
+        if (pk !== "id" && rows.some((r) => r[pk] === row[pk])) {
+          throw new Error(`UNIQUE constraint failed: ${name}.${pk}`);
+        }
+        const id = (seq[name] = (seq[name] ?? 0) + 1);
+        rows.push(pk === "id" ? { id, ...row } : { ...row });
+        return pk === "id" ? id : row[pk];
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async findOne(where: any = {}) {
+        return rows.find((r) => match(r, where));
+      },
+      async get(id: any) {
+        return rows.find((row) => row[pk] === id);
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk), source: memBlackboardSource().source } as any as DataLayer;
+  return { data, stores };
+}
+
+const PLAN = "acme/widgets#7";
+
+function seedPlan(stores: Record<string, any[]>) {
+  stores["plans"] = [{
+    plan_key: PLAN,
+    repo: "acme/widgets",
+    issue_url: "https://github.com/acme/widgets/issues/7",
+    title: "Widgets epic",
+    status: "done",
+  }];
+}
+function seedTask(stores: Record<string, any[]>, task: Record<string, unknown>) {
+  (stores["plan_tasks"] ??= []).push({ plan_key: PLAN, ...task });
+}
+function seedPr(stores: Record<string, any[]>, pr_key: string, status: string) {
+  (stores["pull_requests"] ??= []).push({ pr_key, status });
+}
+
+test("gatherConformance: collects the spec, only LANDED PRs, and raised scope-changes", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", title: "Auth", prompt: "add JWT auth", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: 2, task_index: 1, task_id: "t2", title: "Rate limit", prompt: "add rate limiting", status: "opened", pr_key: "acme/widgets#11" });
+  seedTask(stores, { id: 3, task_index: 2, task_id: "t3", title: "Webhook", prompt: "retry webhooks", status: "opened", pr_key: "acme/widgets#12" });
+  seedTask(stores, { id: 4, task_index: 3, task_id: "t4", title: "Docs", prompt: "write docs", status: "skipped", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "merged"); // landed
+  seedPr(stores, "acme/widgets#11", "converged"); // landed (review-only)
+  seedPr(stores, "acme/widgets#12", "abandoned"); // NOT landed
+  await appendEntry(data, PLAN, { author_task: "t2", kind: "scope-change", body: "narrowed rate limit to per-IP only" });
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "learning", body: "not a scope change" });
+
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(d.repo, "acme/widgets");
+  assertEquals(d.issueUrl, "https://github.com/acme/widgets/issues/7");
+  assertEquals(d.slices.length, 4);
+  // Only merged/converged PRs are "delivered"; abandoned and task-less slices are excluded.
+  assertEquals(d.deliveredPrs, ["acme/widgets#10", "acme/widgets#11"]);
+  assertEquals(d.slices.find((s) => s.taskId === "t3")?.landed, false);
+  assertEquals(d.slices.find((s) => s.taskId === "t4")?.landed, false);
+  // Only scope-change entries surface as raised deviations — learnings are ignored.
+  assertEquals(d.scopeChanges.length, 1);
+  assertEquals(d.scopeChanges[0].author_task, "t2");
+});
+
+test("gatherConformance: sorts slices by task_index", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 2, task_id: "t3", status: "skipped", pr_key: null });
+  seedTask(stores, { id: 2, task_index: 0, task_id: "t1", status: "skipped", pr_key: null });
+  seedTask(stores, { id: 3, task_index: 1, task_id: "t2", status: "skipped", pr_key: null });
+  const d = await gatherConformance(data, PLAN);
+  assertEquals(d.slices.map((s) => s.taskId), ["t1", "t2", "t3"]);
+});
+
+test("gatherConformance: uses pre-fetched blackboard entries instead of re-scanning", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "skipped", pr_key: null });
+  // A scope-change lives in the store, but the caller passes an EMPTY pre-fetched snapshot — the
+  // function must honour what it was handed and not re-read the store.
+  await appendEntry(data, PLAN, { author_task: "t1", kind: "scope-change", body: "should be ignored" });
+  const d = await gatherConformance(data, PLAN, []);
+  assertEquals(d.scopeChanges.length, 0);
+});
+
+test("hasDeliveredImplementation: true iff at least one PR landed", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedPr(stores, "acme/widgets#10", "abandoned");
+  assert(!hasDeliveredImplementation(await gatherConformance(data, PLAN)));
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "merged" }];
+  assert(hasDeliveredImplementation(await gatherConformance(data, PLAN)));
+});
+
+test("hasDeliveredImplementationForPlan: matches the digest without a blackboard scan", async () => {
+  const { data, stores } = memData();
+  seedPlan(stores);
+  seedTask(stores, { id: 1, task_index: 0, task_id: "t1", status: "opened", pr_key: "acme/widgets#10" });
+  seedTask(stores, { id: 2, task_index: 1, task_id: "t2", status: "skipped", pr_key: null });
+  seedPr(stores, "acme/widgets#10", "abandoned");
+  // No landed PR yet — agrees with the full-digest helper.
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), false);
+  assertEquals(hasDeliveredImplementation(await gatherConformance(data, PLAN)), false);
+  // A landed PR flips both to true.
+  stores["pull_requests"] = [{ pr_key: "acme/widgets#10", status: "converged" }];
+  assertEquals(await hasDeliveredImplementationForPlan(data, PLAN), true);
+  assertEquals(hasDeliveredImplementation(await gatherConformance(data, PLAN)), true);
+  // The cheap check must not touch the blackboard.
+  const before = (stores["blackboard"] ?? []).length;
+  await hasDeliveredImplementationForPlan(data, PLAN);
+  assertEquals((stores["blackboard"] ?? []).length, before);
+});
+
+test("renderConformanceBrief: lists PRs to examine, the spec, and raised deviations", () => {
+  const brief = renderConformanceBrief({
+    planKey: PLAN,
+    repo: "acme/widgets",
+    issueUrl: "https://x/7",
+    title: "Epic",
+    slices: [
+      { taskId: "t1", title: "Auth", prompt: "add JWT auth", status: "opened", prKey: "acme/widgets#10", landed: true },
+      { taskId: "t2", title: "Docs", prompt: null, status: "skipped", prKey: null, landed: false },
+    ],
+    deliveredPrs: ["acme/widgets#10"],
+    scopeChanges: [{ author_task: "t1", body: "narrowed to per-IP", created_at: "now" }],
+  });
+  assertStringIncludes(brief, "gh pr diff");
+  assertStringIncludes(brief, "acme/widgets#10");
+  assertStringIncludes(brief, "add JWT auth");
+  assertStringIncludes(brief, "narrowed to per-IP");
+  assertStringIncludes(brief, "RAISED during implementation");
+});
+
+test("renderConformanceBrief: states 'none' for no delivered PRs and no scope-changes", () => {
+  const brief = renderConformanceBrief({
+    planKey: PLAN, repo: "acme/widgets", issueUrl: "", title: null,
+    slices: [], deliveredPrs: [], scopeChanges: [],
+  });
+  assertStringIncludes(brief, "no implementation to verify");
+  assertStringIncludes(brief, "treat any deviation you find as UNRAISED");
+});
+
+test("recordConformance: inserts then updates the same plan_key row in place", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#issuecomment-1",
+    slicesMet: 4,
+    slicesReduced: 1,
+    slicesNotVerified: 1,
+    deviationsRaised: 2,
+    deviationsUnraised: 1,
+    hasDeviations: true,
+    summary: "6 items, 4 met",
+    report: "full report",
+  });
+  assertEquals(stores["plan_conformance"].length, 1);
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.status, "filed");
+  assertEquals(row.comment_url, "https://x/7#issuecomment-1");
+  assertEquals(row.slices_met, 4);
+  assertEquals(row.has_deviations, 1);
+
+  await recordConformance(data, PLAN, { status: "skipped", summary: "nothing shipped" });
+  assertEquals(stores["plan_conformance"].length, 1, "same plan_key must not duplicate");
+  assertEquals(stores["plan_conformance"][0].status, "skipped");
+  assertEquals(stores["plan_conformance"][0].has_deviations, 0);
+});
+
+test("recordConformance: rethrows a non-unique (FOREIGN KEY) constraint error instead of swallowing it", async () => {
+  let updated = false;
+  const table = {
+    async insert() {
+      throw new Error("FOREIGN KEY constraint failed");
+    },
+    async update() {
+      updated = true;
+    },
+  };
+  const data = { table: () => table } as any as DataLayer;
+  let threw = false;
+  try {
+    await recordConformance(data, PLAN, { status: "filed" });
+  } catch (err) {
+    threw = true;
+    assertStringIncludes(String(err), "FOREIGN KEY");
+  }
+  assert(threw, "the FK error must propagate");
+  assertEquals(updated, false, "must not silently fall back to update on a non-unique error");
+});
+
+test("recordConformance: persists the retro instance key and the escalation review_status (issue #216)", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#c",
+    hasDeviations: true,
+    summary: "slice 2 reduced",
+    processKey: "retro-inst-7",
+    reviewStatus: "reviewing",
+  });
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.process_key, "retro-inst-7");
+  assertEquals(row.review_status, "reviewing");
+
+  // Absent tracking fields default: no processKey, and a settled `reviewed`.
+  await recordConformance(data, "acme/widgets#8", { status: "skipped" });
+  const clean = stores["plan_conformance"].find((r) => r.plan_key === "acme/widgets#8");
+  assertEquals(clean.process_key, null);
+  assertEquals(clean.review_status, "reviewed");
+});
+
+test("recordConformance: rejects an untrackable `reviewing` row with a null processKey (invariant guard)", async () => {
+  const { data, stores } = memData();
+  // A `reviewing` row with no `process_key` is unreachable: `pollUserTasks` skips rows without a
+  // key and the `instanceTracking` binding keys off `process_key`, so it would strand the review
+  // forever. The API must refuse to persist that state, not just the worker call site.
+  await assertRejects(
+    () =>
+      recordConformance(data, PLAN, {
+        status: "filed",
+        hasDeviations: true,
+        reviewStatus: "reviewing",
+      }),
+    Error,
+    "untrackable",
+  );
+  assertEquals(stores["plan_conformance"] ?? [], []);
+});
+
+test("activeConformanceReviews: returns only the rows still `reviewing`", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: "a/b#1", process_key: "p1", review_status: "reviewing", summary: "s1" },
+    { plan_key: "a/b#2", process_key: "p2", review_status: "reviewed", summary: "s2" },
+  ];
+  const active = await activeConformanceReviews(data);
+  assertEquals(active.map((r) => r.plan_key), ["a/b#1"]);
+});
+
+test("acknowledgeConformance: settles the row at reviewed and folds the note into the summary", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "slice 2 reduced" },
+  ];
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.review_status, "reviewed");
+  assertEquals(row.summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("acknowledgeConformance: fails loudly when the plan_conformance row is missing", async () => {
+  const { data } = memData();
+  await assertRejects(
+    () => acknowledgeConformance(data, PLAN, "filed follow-up #9"),
+    Error,
+    PLAN,
+  );
+});
+
+test("acknowledgeConformance: is idempotent — a retry after settling does not re-append the note", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "slice 2 reduced" },
+  ];
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  await acknowledgeConformance(data, PLAN, "filed follow-up #9");
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.review_status, "reviewed");
+  assertEquals(row.summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("acknowledgeConformance: a blank note settles the row without changing the summary", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewing", summary: "auth cache unverified" },
+  ];
+  await acknowledgeConformance(data, PLAN, "  ");
+  assertEquals(stores["plan_conformance"][0].review_status, "reviewed");
+  assertEquals(stores["plan_conformance"][0].summary, "auth cache unverified");
+});