@nanobpm/nano-workforce 0.171.0 → 0.171.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.171.2](https://github.com/nanobpm/nano-workforce/compare/v0.171.1...v0.171.2) (2026-08-31)
+
+### Bug Fixes
+
+* surface + complete readiness/preflight escalations in the Tasks inbox ([#675](https://github.com/nanobpm/nano-workforce/issues/675)) ([9d874e8](https://github.com/nanobpm/nano-workforce/commit/9d874e889f3155b7887bb48032e39c5f78e33ce3)), closes [#674](https://github.com/nanobpm/nano-workforce/issues/674)
+
+## [0.171.1](https://github.com/nanobpm/nano-workforce/compare/v0.171.0...v0.171.1) (2026-08-31)
+
+### Code Refactoring
+
+* **agentic:** consume @nanobpm/agentic/transcript, drop the duplicated grammar ([#677](https://github.com/nanobpm/nano-workforce/issues/677)) ([8c8d3fc](https://github.com/nanobpm/nano-workforce/commit/8c8d3fc393134862557a65e2aab2dd9e16292c66)), closes [#676](https://github.com/nanobpm/nano-workforce/issues/676)
+
 ## [0.171.0](https://github.com/nanobpm/nano-workforce/compare/v0.170.1...v0.171.0) (2026-08-31)
 
 ### Features

package/app/agentCompletion.test.ts

@@ -286,6 +286,38 @@ test("empty-plan-escalation is HUMAN-completable but NOT agent-completable (issu
   assertEquals(completed[0].variables, { directive: "revise", notes: "look again" });
 });
 
+test("readiness-escalation(-pf) is HUMAN-completable but NOT agent-completable (issue #674)", async () => {
+  // A readiness/preflight gate adjudicates whether upstream is ACTUALLY ready (proceed) or the gate
+  // should be abandoned. Like feature-blocked/conformance/empty-plan it is a HUMAN operator decision —
+  // an agent must never auto-answer it, or the fleet would silently defeat the very readiness gate the
+  // task exists to enforce. So both ids stay OUTSIDE `ESCALATION_TASK_ELEMENTS` (agent-refused) but are
+  // retired by the HUMAN completer via the one canonical `complete-user-task` door.
+  for (const elementId of ["readiness-escalation-pf", "readiness-escalation"] as const) {
+    const stores = { task_completions: { rows: [] as any[], key: "id" } };
+    const data = memData(stores);
+    const { engine, completed } = fakeEngine([{ userTaskKey: "ut-r", elementId }]);
+
+    const asAgent = await completeEscalationAsAgent(data, engine, {
+      userTaskKey: "ut-r",
+      agentId: "bot",
+      variables: { resolution: "acknowledge" },
+    });
+    assertEquals(asAgent.ok, false, `the agent completer refuses ${elementId}`);
+    assertEquals(asAgent.reason, "not a completable task");
+    assertEquals(completed.length, 0);
+
+    const asHuman = await completeEscalationAsHuman(data, engine, {
+      userTaskKey: "ut-r",
+      operatorId: "alice",
+      variables: { resolution: "abandon", answer: "upstream never published" },
+    });
+    assertEquals(asHuman.ok, true, `the human completer retires ${elementId}`);
+    assertEquals(asHuman.elementId, elementId);
+    assertEquals(completed.length, 1);
+    assertEquals(completed[0].variables, { resolution: "abandon", answer: "upstream never published" });
+  }
+});
+
 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

@@ -24,7 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
-import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT } from "./userTasks.ts";
+import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -101,6 +101,16 @@ export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMEN
  *  Re-exported from the canonical `EMPTY_PLAN_ELEMENT` (app/userTasks.ts) — one source of truth. */
 export const EMPTY_PLAN_TASK_ELEMENT = EMPTY_PLAN_ELEMENT;
 
+/** The readiness/preflight escalation user-task element ids (`readiness-escalation-pf` in feature.bpmn's
+ *  readiness preflight + plan-fanout.bpmn's producer-capability preflight; `readiness-escalation` in
+ *  readiness-gate.bpmn / wait-gate.bpmn). Like `feature-blocked`, `conformance-escalation` and
+ *  `empty-plan-escalation` these are HUMAN-only decisions — an agent must never auto-answer a readiness
+ *  gate (that would silently defeat the "is upstream actually ready?" adjudication the gate exists for),
+ *  so they live OUTSIDE `ESCALATION_TASK_ELEMENTS` and only the HUMAN completer accepts them (issue
+ *  #674). Re-exported from the canonical constants in app/userTasks.ts — one source of truth. */
+export const READINESS_ESCALATION_PF_TASK_ELEMENT = READINESS_ESCALATION_PF_ELEMENT;
+export const READINESS_ESCALATION_TASK_ELEMENT = READINESS_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`
  *  and `conformance-escalation` acknowledgements, PLUS the advisory ACP permission prompt
@@ -115,6 +125,8 @@ export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   FEATURE_BLOCKED_TASK_ELEMENT,
   CONFORMANCE_ESCALATION_TASK_ELEMENT,
   EMPTY_PLAN_TASK_ELEMENT,
+  READINESS_ESCALATION_PF_TASK_ELEMENT,
+  READINESS_ESCALATION_TASK_ELEMENT,
   ACP_PERMISSION_ELEMENT,
 ]);
 
@@ -131,6 +143,8 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "feature-blocked": "feature-blocked",
   [EMPTY_PLAN_TASK_ELEMENT]: "empty-plan-escalation",
   [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
+  [READINESS_ESCALATION_PF_TASK_ELEMENT]: "readiness-escalation",
+  [READINESS_ESCALATION_TASK_ELEMENT]: "readiness-escalation",
   // NOTE: the delivery-graph `human` node (`DELIVERY_HUMAN_ELEMENT`, ADR 0005 S3) is intentionally
   // ABSENT here. Unlike the fixed-form escalations above, ONE `delivery-human-task` element is DESIGNED
   // to render DIFFERENT forms per node (explicit → category → generic → agent-router, `app/deliveryHuman.ts`

package/app/agentic/transcript-events.drift.test.ts

@@ -1,11 +1,12 @@
-// Drift-guard: exactly ONE parser of the transcript log (ADR 0056, #251).
+// Drift-guard: the transcript grammar is DERIVED from its one owner, never re-forked here (#676).
 //
-// Acceptance criterion (#251): "the cockpit renders from a single derive*() fold, with no independent
-// re-parse of raw bytes (drift-guard test asserts one parser)". This is that guard. It enforces
-// structurally — by scanning the app-tier source — that the raw-chunk → typed-event classification
-// lives in exactly one module (`transcript-events.ts`), so a second, divergent parser of the same
-// bytes cannot creep in. The whole point of the event-sourced model is "the log IS the state": every
-// view derives from the one fold, none re-parses the bytes itself.
+// nano-workforce used to carry a byte-for-byte hand-rolled copy of the transcript-event grammar
+// (marker/version, the ONE parser, the vocabulary, the derive fold). That grammar now lives in exactly
+// one place — `@nanobpm/agentic/transcript` (agentic 0.10.0) — and `transcript-events.ts` is a thin
+// re-export barrel over it. This guard secures the *class* of failure ("a consumer hand-rolls the
+// transcript grammar instead of importing it") structurally, by scanning the app-tier source: it fails
+// if the barrel stops importing agentic, if a local module re-defines the envelope marker literal, or
+// if a transcript consumer re-parses a stored chunk itself instead of folding through the one parser.
 import { test } from "node:test";
 import { readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -26,26 +27,36 @@ function sourceFiles(dir: string): string[] {
   return out;
 }
 
-const PARSER_MODULE = join(AGENTIC_DIR, "transcript-events.ts");
+const BARREL_MODULE = join(AGENTIC_DIR, "transcript-events.ts");
+const AGENTIC_TRANSCRIPT_SPECIFIER = "@nanobpm/agentic/transcript";
 
-test("the transcript-event marker literal is DEFINED in exactly one module (no second parser)", () => {
-  // Consumers reference the marker via the imported `TRANSCRIPT_EVENT_MARKER` identifier; only the ONE
-  // parser embeds the marker's string literal. A second module hardcoding it would be a second parser.
-  // Match every quote form (double, single, backtick) so a second parser can't bypass the guard by
-  // hardcoding the marker in a different literal style.
+test("the transcript grammar is imported from @nanobpm/agentic/transcript, never redefined locally", () => {
+  // The single source of truth is agentic; nano-workforce derives from it via a re-export barrel.
+  const barrel = readFileSync(BARREL_MODULE, "utf8");
+  assert(
+    barrel.includes(AGENTIC_TRANSCRIPT_SPECIFIER),
+    `${BARREL_MODULE} must re-export the grammar from "${AGENTIC_TRANSCRIPT_SPECIFIER}"`,
+  );
+});
+
+test("no local module re-defines the transcript-event marker literal (no second grammar)", () => {
+  // Consumers reference the marker via the imported `TRANSCRIPT_EVENT_MARKER` identifier; only a
+  // second, forked grammar would embed the marker's string literal in nano-workforce source. Match
+  // every quote form (double, single, backtick) so a re-fork can't bypass the guard by hardcoding the
+  // marker in a different literal style. Expect ZERO owners — the literal lives in agentic now.
   const quotedMarkerForms = ['"', "'", "`"].map((q) => `${q}${TRANSCRIPT_EVENT_MARKER}${q}`);
   const owners = sourceFiles(AGENTIC_DIR).filter((path) => {
     const src = readFileSync(path, "utf8");
     return quotedMarkerForms.some((literal) => src.includes(literal));
   });
-  assertEquals(owners, [PARSER_MODULE]);
+  assertEquals(owners, []);
 });
 
-test("no transcript consumer re-parses raw chunks — JSON.parse of the log lives only in the parser", () => {
-  // The cockpit + read projections must fold through the single parser, never JSON.parse a chunk
-  // themselves. Scan the transcript-facing consumers and assert none contains a raw JSON.parse.
-  const consumers = sourceFiles(AGENTIC_DIR).filter(
-    (path) => path !== PARSER_MODULE && /transcript-(read|render|view|derive|fork)\.ts$/.test(path),
+test("no transcript consumer re-parses raw chunks — the log is folded only through the one parser", () => {
+  // The cockpit + read projections must fold through the single parser (in agentic), never JSON.parse a
+  // chunk themselves. Scan the transcript-facing consumers and assert none contains a raw JSON.parse.
+  const consumers = sourceFiles(AGENTIC_DIR).filter((path) =>
+    /transcript-(read|render|view|derive|fork)\.ts$/.test(path),
   );
   assert(consumers.length >= 3, "expected to scan several transcript consumers");
   for (const path of consumers) {