@nanobpm/nano-workforce 0.104.0 → 0.106.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.104.0",
+  "version": "0.106.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/tasks.page.json

@@ -532,6 +532,90 @@
         },
         "refreshMs": 5000
       }
+    },
+    {
+      "type": "dataGrid",
+      "id": "conformance-reviews",
+      "props": {
+        "title": "Conformance reviews",
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "user_tasks",
+          "filter": [
+            {
+              "field": "element_id",
+              "in": [
+                "conformance-escalation"
+              ]
+            }
+          ],
+          "orderBy": {
+            "field": "updated_at",
+            "dir": "desc"
+          }
+        },
+        "columns": [
+          {
+            "field": "subject_title",
+            "template": "{{subject_title}}",
+            "header": "Epic",
+            "subtitleField": "subject_key",
+            "truncate": true,
+            "linkField": "subject_url"
+          },
+          {
+            "field": "question",
+            "header": "Findings"
+          },
+          {
+            "field": "subject_url",
+            "header": "Issue"
+          },
+          {
+            "field": "process_key",
+            "header": "Process",
+            "link": {
+              "kind": "processExplorer",
+              "keyField": "process_key"
+            }
+          },
+          {
+            "field": "updated_at",
+            "header": "Updated",
+            "format": "datetime"
+          }
+        ],
+        "rowKey": "user_task_key",
+        "detail": {
+          "linkField": "subject_url",
+          "fields": [
+            {
+              "field": "question",
+              "label": "Findings"
+            }
+          ],
+          "form": {
+            "showWhenField": "user_task_key",
+            "title": "Acknowledge conformance review",
+            "promptField": "question",
+            "inputKey": "note",
+            "inputLabel": "Disposition note (what you decided / follow-up)",
+            "submitLabel": "Acknowledge & close",
+            "action": {
+              "path": "/app/api/actions/complete-user-task",
+              "successLabel": "Acknowledged — the review will close",
+              "body": {
+                "userTaskKey": "{{row.user_task_key}}",
+                "variables": {
+                  "note": "{{form.note}}"
+                }
+              }
+            }
+          }
+        },
+        "refreshMs": 5000
+      }
     }
   ]
 }

package/resources/forms/conformance-escalation.form

@@ -0,0 +1,17 @@
+{
+  "id": "conformance-escalation",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "text": "The spec-conformance review found this epic did **not** cleanly meet its spec — a slice was reduced or could not be verified against the code, or a deviation was made that nobody raised during implementation. The delivery already landed, so this is a **non-blocking** follow-up: review the report on the epic issue, decide any remediation, then acknowledge to close it.",
+      "label": "Conformance review"
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Disposition note (what you decided / follow-up — recorded on the review)"
+    }
+  ]
+}

package/resources/processes/retro.bpmn

@@ -13,6 +13,18 @@
           <nano:extend name="pr" type="string" optional="true" />
           <nano:extend name="summary" type="string" optional="true" />
         </nano:shape>
+        <nano:shape id="ConformanceRecordIn" name="Record conformance — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="commentUrl" type="string" optional="true" />
+          <nano:extend name="slicesMet" type="integer" optional="true" />
+          <nano:extend name="slicesReduced" type="integer" optional="true" />
+          <nano:extend name="slicesNotVerified" type="integer" optional="true" />
+          <nano:extend name="deviationsRaised" type="integer" optional="true" />
+          <nano:extend name="deviationsUnraised" type="integer" optional="true" />
+          <nano:extend name="hasDeviations" type="boolean" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="Epic complete">
@@ -26,7 +38,55 @@
         </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_start</bpmn:incoming>
-      <bpmn:outgoing>f_toSynthesize</bpmn:outgoing>
+      <bpmn:outgoing>f_toConformance</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="conformance" name="Verify implementation vs spec (agent)">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:conformance" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="conformance.md" bindingType="latest" resourceType="GenericScript" linkName="prompt" />
+        </zeebe:linkedResources>
+        <zeebe:ioMapping>
+          <zeebe:input source="=conformanceDigest" target="appendPrompt" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toConformance</bpmn:incoming>
+      <bpmn:outgoing>f_toRecordConformance</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="record-conformance" name="Record conformance">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.conformance-record" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ConformanceRecordIn" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toRecordConformance</bpmn:incoming>
+      <bpmn:outgoing>f_toDeviationsGw</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:exclusiveGateway id="gw-deviations" name="deviations?" default="f_noDeviations">
+      <bpmn:incoming>f_toDeviationsGw</bpmn:incoming>
+      <bpmn:outgoing>f_deviations</bpmn:outgoing>
+      <bpmn:outgoing>f_noDeviations</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:userTask id="conformance-escalation" name="Conformance review (human)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="conformance-escalation" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_deviations</bpmn:incoming>
+      <bpmn:outgoing>f_toConformanceAck</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:serviceTask id="record-conformance-ack" name="Record acknowledgement">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.conformance-ack" />
+        <zeebe:ioMapping>
+          <zeebe:input source="=planKey" target="planKey" />
+          <zeebe:input source="=if (is defined(note)) then note else null" target="note" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toConformanceAck</bpmn:incoming>
+      <bpmn:outgoing>f_ackToSynthesize</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="synthesize" name="Synthesize &#38; promote (agent)">
       <bpmn:extensionElements>
@@ -38,7 +98,8 @@
           <zeebe:input source="=retroDigest" target="appendPrompt" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
-      <bpmn:incoming>f_toSynthesize</bpmn:incoming>
+      <bpmn:incoming>f_noDeviations</bpmn:incoming>
+      <bpmn:incoming>f_ackToSynthesize</bpmn:incoming>
       <bpmn:outgoing>f_toRecord</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="record" name="Record retro">
@@ -55,7 +116,15 @@
       <bpmn:incoming>f_toEnd</bpmn:incoming>
     </bpmn:endEvent>
     <bpmn:sequenceFlow id="f_start" sourceRef="Start" targetRef="gather" />
-    <bpmn:sequenceFlow id="f_toSynthesize" sourceRef="gather" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toConformance" sourceRef="gather" targetRef="conformance" />
+    <bpmn:sequenceFlow id="f_toRecordConformance" sourceRef="conformance" targetRef="record-conformance" />
+    <bpmn:sequenceFlow id="f_toDeviationsGw" sourceRef="record-conformance" targetRef="gw-deviations" />
+    <bpmn:sequenceFlow id="f_deviations" name="deviations" sourceRef="gw-deviations" targetRef="conformance-escalation">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=hasDeviations = true</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_noDeviations" sourceRef="gw-deviations" targetRef="synthesize" />
+    <bpmn:sequenceFlow id="f_toConformanceAck" sourceRef="conformance-escalation" targetRef="record-conformance-ack" />
+    <bpmn:sequenceFlow id="f_ackToSynthesize" sourceRef="record-conformance-ack" targetRef="synthesize" />
     <bpmn:sequenceFlow id="f_toRecord" sourceRef="synthesize" targetRef="record" />
     <bpmn:sequenceFlow id="f_toEnd" sourceRef="record" targetRef="End" />
   </bpmn:process>
@@ -70,33 +139,76 @@
       <bpmndi:BPMNShape id="BPMNShape_gather" bpmnElement="gather">
         <dc:Bounds x="216" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
+      <bpmndi:BPMNShape id="BPMNShape_conformance" bpmnElement="conformance">
         <dc:Bounds x="416" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
+      <bpmndi:BPMNShape id="BPMNShape_record-conformance" bpmnElement="record-conformance">
         <dc:Bounds x="616" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-deviations" bpmnElement="gw-deviations" isMarkerVisible="true">
+        <dc:Bounds x="776" y="95" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="770" y="65" width="62" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_conformance-escalation" bpmnElement="conformance-escalation">
+        <dc:Bounds x="751" y="240" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record-conformance-ack" bpmnElement="record-conformance-ack">
+        <dc:Bounds x="911" y="240" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_synthesize" bpmnElement="synthesize">
+        <dc:Bounds x="1056" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record" bpmnElement="record">
+        <dc:Bounds x="1256" y="80" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="816" y="102" width="36" height="36" />
+        <dc:Bounds x="1456" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="794" y="143" width="80" height="14" />
+          <dc:Bounds x="1434" y="143" width="80" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
         <di:waypoint x="116" y="120" />
         <di:waypoint x="216" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toSynthesize" bpmnElement="f_toSynthesize">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toConformance" bpmnElement="f_toConformance">
         <di:waypoint x="316" y="120" />
         <di:waypoint x="416" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecordConformance" bpmnElement="f_toRecordConformance">
         <di:waypoint x="516" y="120" />
         <di:waypoint x="616" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toDeviationsGw" bpmnElement="f_toDeviationsGw">
         <di:waypoint x="716" y="120" />
-        <di:waypoint x="816" y="120" />
+        <di:waypoint x="776" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_noDeviations" bpmnElement="f_noDeviations">
+        <di:waypoint x="826" y="120" />
+        <di:waypoint x="1056" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_deviations" bpmnElement="f_deviations">
+        <di:waypoint x="801" y="145" />
+        <di:waypoint x="801" y="240" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toConformanceAck" bpmnElement="f_toConformanceAck">
+        <di:waypoint x="851" y="280" />
+        <di:waypoint x="911" y="280" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_ackToSynthesize" bpmnElement="f_ackToSynthesize">
+        <di:waypoint x="1011" y="280" />
+        <di:waypoint x="1106" y="280" />
+        <di:waypoint x="1106" y="160" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toRecord" bpmnElement="f_toRecord">
+        <di:waypoint x="1156" y="120" />
+        <di:waypoint x="1256" y="120" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toEnd" bpmnElement="f_toEnd">
+        <di:waypoint x="1356" y="120" />
+        <di:waypoint x="1456" y="120" />
       </bpmndi:BPMNEdge>
     </bpmndi:BPMNPlane>
   </bpmndi:BPMNDiagram>

package/resources/prompts/conformance.md

@@ -0,0 +1,105 @@
+# Conformance agent — verify the implementation against the spec, by reading the code
+
+You are the **spec-conformance agent**. An epic (a fan-out `plan`) has finished — every one of its
+slices has reached a terminal state and the landed PRs are now in the tree. Your job is to answer a
+single, evidence-based question for a human:
+
+> **Did we actually build what the spec asked for — no more, no less?**
+
+You are NOT the retro agent (that one distils lessons). You are the auditor. Crucially, **you verify
+against the real implementation, not against what the agents claimed.** Transcripts, `learning`
+notes, and even a slice's own status can be optimistic or wrong. The diff cannot. Read the code.
+
+## Input
+
+The job payload (stdin JSON) carries:
+
+- `variables.planKey` — the epic's key, e.g. `owner/repo#123`.
+- `variables.repo` — the **target repo** `owner/repo` the work landed in.
+- `variables.issueUrl` — the epic's source issue. **This issue body is the SPEC.**
+- **`variables.conformanceDigest`** — appended below the `---` separator: the spec broken into
+  slices (each slice's planner-supplied `prompt` is its acceptance brief), the list of **delivered
+  PRs** you must examine, and the deviations that were **raised** during implementation
+  (`scope-change` entries). This tells you *what to check* and *where to look* — it does NOT tell
+  you the answer.
+
+You have `gh` / git authenticated for the target repository.
+
+## What to do
+
+1. **Read the spec.** `gh issue view <n> --repo <repo>` for the epic issue body, plus every slice's
+   `prompt` in the digest. Together these are the acceptance criteria you are auditing against.
+2. **Examine the ACTUAL implementation.** For every delivered PR in the digest:
+   `gh pr diff <n> --repo <repo>`, and read the touched source and tests (clone/checkout if you
+   need to navigate). Do not trust the PR description — read what the code does.
+3. **Distinguish real delivery from the appearance of it.** This is the whole point of examining
+   code. For each spec item, decide whether it is *load-bearing* in the shipped system:
+   - Is the new code actually **wired in / reachable**, or is it a dead entrypoint behind a flag,
+     a stub, or a synthetic path nothing calls?
+   - Do the **tests exercise the real behaviour**, or are they asserting on mocks/gated paths so
+     they pass without proving the feature works?
+   - Was the item delivered **in full**, or narrowed to a subset while looking complete?
+4. **Assign each spec item an acceptance verdict**, with a one-line evidence pointer (file / PR /
+   test) for each:
+   - **met** — delivered as specified, wired in, and genuinely tested.
+   - **met-in-unit-only** — implemented and unit-tested, but not proven wired into the live system.
+   - **reduced** — delivered in a narrower form than the spec asked for.
+   - **not-verified** — you could not confirm it from the implementation (missing, stubbed, dead
+     code, or tests that don't actually exercise it).
+5. **Reconcile the raised deviations.** For each `scope-change` entry in the digest, confirm the
+   code matches what was said, and note it as a **raised** deviation.
+6. **Hunt for UNRAISED deviations** — things the code does that the spec did *not* ask for, or spec
+   items silently dropped, that were **never** flagged on the blackboard. These are the most
+   valuable finding: scope drift nobody surfaced.
+7. **Post the conformance report as a comment on the epic issue**
+   (`gh issue comment <n> --repo <repo> --body-file <file>`). Structure it: a one-line verdict, a
+   per-item table (item → verdict → evidence), the raised deviations, and the unraised deviations.
+   Be specific and cite files/PRs — this comment is the deliverable a human reads.
+
+## Do not
+
+- Do **not** open, modify, or merge any PR. You audit; you do not remediate. (A later stage decides
+  whether a finding warrants a follow-up task.)
+- Do **not** soften a `not-verified` into a `met` because the transcript sounded confident. Absence
+  of evidence in the code is `not-verified`.
+- Do **not** manufacture deviations to look thorough. A clean epic that fully met its spec is a
+  perfectly good — and common — result.
+
+## Output contract
+
+Write a JSON object of **result variables** to the file named by the `AGENT_RESULT_FILE`
+environment variable:
+
+```json
+{
+  "status": "filed",
+  "commentUrl": "https://github.com/owner/repo/issues/123#issuecomment-456",
+  "slicesMet": 4,
+  "slicesReduced": 1,
+  "slicesNotVerified": 1,
+  "deviationsRaised": 2,
+  "deviationsUnraised": 1,
+  "hasDeviations": true,
+  "summary": "6 items: 4 met, 1 reduced (auth rate-limit narrowed to per-IP), 1 not-verified (webhook retry path is dead code). 2 raised + 1 unraised deviation (added a /debug route not in spec)."
+}
+```
+
+Rules:
+
+- `status` — one of:
+  - `filed` — you examined the implementation and posted the report comment. Set `commentUrl`.
+  - `skipped` — there was no landed implementation to examine (nothing shipped). Explain in
+    `summary`; omit the counts.
+  - `blocked` — you could not proceed (e.g. no read access, could not fetch a PR). Explain in
+    `summary`.
+- `commentUrl` — the URL of the report comment you posted on the epic issue, for `filed`.
+- `slicesMet` / `slicesReduced` / `slicesNotVerified` — integer counts of your per-item verdicts
+  (count `met-in-unit-only` under `slicesReduced`, since it is not full live delivery).
+- `deviationsRaised` — count of `scope-change` deviations you reconciled.
+- `deviationsUnraised` — count of deviations you found that were never flagged.
+- `hasDeviations` — `true` when anything is reduced / not-verified / an unraised deviation exists;
+  i.e. the epic did not cleanly meet its spec. A later stage uses this to decide escalation.
+- `summary` — a short human-readable verdict.
+
+You are advisory and post-merge: you gate no delivery. Your value is an honest, code-grounded
+account of what shipped versus what was asked — surface it plainly, and let the humans act on it.

package/resources/prompts/retro.md

@@ -10,6 +10,11 @@ so the *next* fleet — and human contributors — never re-learn it the hard wa
 You are the mechanism that lifts a lesson from "a thing one agent happened to hit" to "a thing the
 repo now tells everyone up front."
 
+> **Scope:** a separate **conformance** agent runs before you and audits whether the epic met its
+> spec (posting its own report on the epic issue). That is *not* your job — do **not** re-verify
+> acceptance or re-litigate scope here. Focus purely on distilling reusable **lessons** and
+> promoting them into the repo.
+
 ## Input
 
 The job payload (stdin JSON) carries:

package/workers/conformance-ack/worker.test.ts

@@ -0,0 +1,50 @@
+// Unit coverage for pr.conformance-ack — the operator acknowledged a conformance-review escalation
+// (issue #216). It must settle the parked `plan_conformance` row at `review_status = 'reviewed'` so
+// the inbox scan drops it (the retro instance COMPLETES normally, so `instanceTracking.onTerminated`
+// never fires) and fold the operator's disposition note into the audit `summary`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp(rows: Record<string, unknown>[]) {
+  const stores: Record<string, Record<string, unknown>[]> = { plan_conformance: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  } as any;
+}
+
+test("conformance-ack: settles the review at reviewed and appends the operator note to the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#7", review_status: "reviewing", summary: "slice 2 reduced" }];
+  const app = fakeApp(rows);
+  const out = await handler({ variables: { planKey: "owner/repo#7", note: "filed follow-up #9" } } as any, app);
+  assertEquals(out, {});
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("conformance-ack: a blank note settles the review without touching the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#8", review_status: "reviewing", summary: "auth cache unverified" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { planKey: "owner/repo#8", note: "   " } } as any, app);
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "auth cache unverified");
+});

package/workers/conformance-ack/worker.ts

@@ -0,0 +1,31 @@
+// pr.conformance-ack — an operator acknowledged a conformance-review escalation (issue #216).
+//
+// When the spec-conformance audit finds the epic did NOT cleanly meet its spec, the `retro` process
+// routes to the `conformance-escalation` operator user task (retro.bpmn), which parks the instance
+// on the operators' inbox with `plan_conformance.review_status = 'reviewing'`. This worker fires once
+// the operator completes that ack task: it settles the row at `reviewed` (so the inbox scan drops it)
+// and folds the operator's optional disposition note into the audit `summary`. The instance then
+// continues to the lessons (retro) synthesis, so the ack is NON-blocking — delivery already landed.
+// Persistence goes through the record gateway (`app.data`), never hand-written SQL.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { acknowledgeConformance } from "../../app/conformance.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  note?: unknown;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const note = str(job.variables.note);
+
+  await acknowledgeConformance(app.data, planKey, note);
+  app.log.info("conformance-ack", { planKey, note: note ?? null });
+
+  return {};
+};
+
+export default handler;