@nanobpm/nano-workforce 0.99.1 → 0.100.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.100.0](https://github.com/nanobpm/nano-workforce/compare/v0.99.1...v0.100.0) (2026-08-19)
+
+
+### Features
+
+* retire interim feature-run escalation/blocked surface ([#339](https://github.com/nanobpm/nano-workforce/issues/339)) ([525d0f7](https://github.com/nanobpm/nano-workforce/commit/525d0f7a7f9661f640899e4bdf1b32052cff4ed9)), closes [#305](https://github.com/nanobpm/nano-workforce/issues/305) [#310](https://github.com/nanobpm/nano-workforce/issues/310) [#332](https://github.com/nanobpm/nano-workforce/issues/332) [#332](https://github.com/nanobpm/nano-workforce/issues/332)
+
 ## [0.99.1](https://github.com/nanobpm/nano-workforce/compare/v0.99.0...v0.99.1) (2026-08-19)
 
 

package/app/agentCompletion.test.ts

@@ -62,11 +62,15 @@ function memData(stores: Record<string, { rows: any[]; key: string }>) {
   } as any;
 }
 
-/** A stub engine recording every `completeUserTask`, with a seeded set of open user tasks. */
+/** A stub engine recording every `completeUserTask`, with a seeded set of open user tasks. The
+ *  completers resolve tasks via `openUserTasks` (CREATED only), so the fixture exposes it; a legacy
+ *  `searchUserTasks` (ANY state) is also present to prove the completer does NOT reach for it. */
 function fakeEngine(openTasks: Array<{ userTaskKey: string; elementId?: string }>) {
   const completed: Array<{ userTaskKey: string; variables?: Record<string, unknown> }> = [];
   const engine = {
-    searchUserTasks: (_filter?: Record<string, unknown>) => Promise.resolve(openTasks),
+    openUserTasks: (_filter?: Record<string, unknown>) => Promise.resolve(openTasks),
+    searchUserTasks: (_filter?: Record<string, unknown>) =>
+      Promise.reject(new Error("completer must resolve via openUserTasks, not searchUserTasks")),
     completeUserTask: (userTaskKey: string, variables?: Record<string, unknown>) => {
       completed.push({ userTaskKey, variables });
       return Promise.resolve();
@@ -118,7 +122,7 @@ test("agent completer refuses a non-escalation user task (scoped to the migrated
   });
 
   assertEquals(r.ok, false);
-  assertEquals(r.reason, "not an escalation task");
+  assertEquals(r.reason, "not a completable task");
   assertEquals(completed.length, 0, "a non-escalation task is never completed");
   assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
 });
@@ -137,10 +141,40 @@ test("agent completer is a no-op for an unknown userTaskKey", async () => {
   });
 
   assertEquals(r.ok, false);
-  assertEquals(r.reason, "no open escalation task");
+  assertEquals(r.reason, "no open completable task");
   assertEquals(completed.length, 0);
 });
 
+test("completer resolves only OPEN tasks — a completed/canceled task's key is a 404-style no-op, not a doomed re-completion", async () => {
+  // A looping instance keeps COMPLETED/CANCELED user tasks alongside the live one. If the completer
+  // matched by key against ANY-state tasks (`searchUserTasks`), a stale key would drive a re-completion
+  // that the engine rejects with a 5xx instead of the intended "no open task" no-op. The completer must
+  // query `openUserTasks` (CREATED only), so a key that exists only as a non-open task does not match.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const completed: Array<{ userTaskKey: string }> = [];
+  const engine = {
+    // No open tasks…
+    openUserTasks: () => Promise.resolve([]),
+    // …even though a completed task with this key exists in the full (any-state) search.
+    searchUserTasks: () => Promise.resolve([{ userTaskKey: "ut-done", elementId: "feature-escalation" }]),
+    completeUserTask: (userTaskKey: string) => {
+      completed.push({ userTaskKey });
+      return Promise.resolve();
+    },
+  } as any;
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-done",
+    operatorId: "alice",
+    variables: { resolution: "abandon" },
+  });
+
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "no open completable task");
+  assertEquals(completed.length, 0, "a non-open key never drives a doomed re-completion");
+});
+
 test("a HUMAN operator completes a feature escalation via the SAME attributed resume path (issue #210)", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);
@@ -166,6 +200,35 @@ test("a HUMAN operator completes a feature escalation via the SAME attributed re
   assertEquals(row.reversible, 0, "a human completion is the authority (not reversible)");
 });
 
+test("feature-blocked is HUMAN-completable but NOT agent-completable (issue #332)", async () => {
+  // Issue #332 folded the bespoke `acknowledge-blocked` door onto the canonical human completer, so a
+  // HUMAN operator retires a blocked run through `completeEscalationAsHuman`. It stays OUTSIDE the agent
+  // surface (`ESCALATION_TASK_ELEMENTS`) — an agent must never acknowledge a blocked run on a human's
+  // behalf — so the agent completer refuses it.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-b", elementId: "feature-blocked" }]);
+
+  const asAgent = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-b",
+    agentId: "bot",
+    variables: { note: "n" },
+  });
+  assertEquals(asAgent.ok, false, "the agent completer refuses feature-blocked");
+  assertEquals(asAgent.reason, "not a completable task");
+  assertEquals(completed.length, 0);
+
+  const asHuman = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-b",
+    operatorId: "alice",
+    variables: { note: "reassigned to a human" },
+  });
+  assertEquals(asHuman.ok, true, "the human completer retires feature-blocked");
+  assertEquals(asHuman.elementId, "feature-blocked");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { note: "reassigned to a human" });
+});
+
 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);
@@ -177,7 +240,7 @@ test("human completer refuses a non-escalation user task and is a no-op for an u
     variables: { resolution: "abandon" },
   });
   assertEquals(notEsc.ok, false);
-  assertEquals(notEsc.reason, "not an escalation task");
+  assertEquals(notEsc.reason, "not a completable task");
 
   const missing = await completeEscalationAsHuman(data, engine, {
     userTaskKey: "ut-missing",
@@ -185,7 +248,7 @@ test("human completer refuses a non-escalation user task and is a no-op for an u
     variables: { resolution: "abandon" },
   });
   assertEquals(missing.ok, false);
-  assertEquals(missing.reason, "no open escalation task");
+  assertEquals(missing.reason, "no open completable task");
 
   assertEquals(completed.length, 0, "neither refusal completes a task");
   assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
@@ -455,3 +518,26 @@ test("validateEscalationVariables derives its contract from the canonical .form
   // an element with no linked form contract is not enforced
   assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
 });
+
+test("feature-escalation demands non-blank answer on the answer path, but not on the hidden abandon path", async () => {
+  // resolution=answer shows the conditional `answer` field, which is required → blank/missing rejected.
+  assert(
+    validateEscalationVariables("feature-escalation", { resolution: "answer" }) !== null,
+    "resolution=answer with no guidance is rejected",
+  );
+  assert(
+    validateEscalationVariables("feature-escalation", { resolution: "answer", answer: "   " }) !== null,
+    "resolution=answer with whitespace-only guidance is rejected",
+  );
+  assertEquals(
+    validateEscalationVariables("feature-escalation", { resolution: "answer", answer: "use v2" }),
+    null,
+    "resolution=answer with real guidance passes",
+  );
+  // resolution=abandon HIDES the `answer` field, so its required-ness is not enforced.
+  assertEquals(
+    validateEscalationVariables("feature-escalation", { resolution: "abandon" }),
+    null,
+    "the abandon path does not demand the hidden answer field",
+  );
+});

package/app/agentCompletion.ts

@@ -71,6 +71,23 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "wait-merge-answer", // PR merge-loop escalation (merge-loop.bpmn) — same native user-task path (#256)
 ]);
 
+/** The `feature-blocked` operator user-task element id (feature.bpmn) — the native wait a run parks on
+ *  when the agent reports a `blocked` outcome. Unlike an escalation it is NOT agent-answerable (only a
+ *  human operator retires a blocked run), so it lives OUTSIDE `ESCALATION_TASK_ELEMENTS` — the agent
+ *  completer (`completeEscalationAsAgent`) must never touch it — but it IS a human-completable decision
+ *  on the Tasks inbox, so the HUMAN completer accepts it (issue #332 folded the bespoke
+ *  `acknowledge-blocked` door onto the one canonical `complete-user-task` door). */
+export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
+
+/** 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. */
+export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
+  ...ESCALATION_TASK_ELEMENTS,
+  FEATURE_BLOCKED_TASK_ELEMENT,
+]);
+
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
  *  BPMN `zeebe:formDefinition formId`). Kept beside `ESCALATION_TASK_ELEMENTS` so the completer
  *  validates against the SAME `.form` the task inbox renders — one contract, no second field list. */
@@ -80,36 +97,74 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "trial-merge-decision": "trial-merge-decision",
   "wait-answer": "pr-escalation",
   "wait-merge-answer": "pr-escalation",
+  "feature-blocked": "feature-blocked",
 };
 
+/** A field's `conditional.hide` rule, parsed from the FEEL subset the `.form` files use
+ *  (`=<ref> != "<value>"` / `=<ref> == "<value>"`). A required field is only enforced when it is
+ *  actually shown, so an "answer only when resolution=answer" field is not demanded on the abandon
+ *  path. */
+interface HideRule {
+  ref: string;
+  op: "==" | "!=";
+  value: string;
+}
+
 interface FormContract {
   /** Field keys marked `validate.required` in the `.form`. */
   required: string[];
   /** `select` field key → its allowed `values`. */
   allowed: Record<string, string[]>;
+  /** Field key → its `conditional.hide` rule (only for fields whose visibility is conditional). */
+  hideWhen: Record<string, HideRule>;
 }
 
 const formContractCache = new Map<string, FormContract>();
 
-/** Derive a `.form`'s required-field + select allowed-value contract, cached per formId. The `.form`
- *  files (`resources/forms/*.form`, deployed via nano.app.json) are the CANONICAL contract, so this
- *  reads them rather than re-encoding the field lists — no drift surface. */
+/** Parse the `.form` FEEL subset used by `conditional.hide` — `=<ref> (!=|==) "<value>"` — into a
+ *  structured rule, or `null` for anything outside that subset (treated as "always shown", so a
+ *  required field is never silently skipped by an unrecognised expression). */
+function parseHide(expr: string | undefined): HideRule | null {
+  if (!expr) return null;
+  const m = /^=\s*([A-Za-z_$][\w$]*)\s*(==|!=)\s*"([^"]*)"\s*$/.exec(expr);
+  if (!m) return null;
+  const op = m[2] === "==" ? "==" : "!=";
+  return { ref: m[1], op, value: m[3] };
+}
+
+/** Whether a `conditional.hide` rule hides its field given the submitted `variables`. */
+function isHidden(rule: HideRule, variables: Record<string, unknown>): boolean {
+  const actual = String(variables[rule.ref] ?? "");
+  return rule.op === "!=" ? actual !== rule.value : actual === rule.value;
+}
+
+/** Derive a `.form`'s required-field + select allowed-value + conditional-visibility contract, cached
+ *  per formId. The `.form` files (`resources/forms/*.form`, deployed via nano.app.json) are the
+ *  CANONICAL contract, so this reads them rather than re-encoding the field lists — no drift surface. */
 function formContract(formId: string): FormContract {
   const cached = formContractCache.get(formId);
   if (cached) return cached;
   const raw: {
-    components?: { key?: string; validate?: { required?: boolean }; values?: { value?: string }[] }[];
+    components?: {
+      key?: string;
+      validate?: { required?: boolean };
+      values?: { value?: string }[];
+      conditional?: { hide?: string };
+    }[];
   } = JSON.parse(readFileSync(new URL(`../resources/forms/${formId}.form`, import.meta.url), "utf8"));
   const required: string[] = [];
   const allowed: Record<string, string[]> = {};
+  const hideWhen: Record<string, HideRule> = {};
   for (const c of raw.components ?? []) {
     if (!c.key) continue;
     if (c.validate?.required) required.push(c.key);
     if (c.values?.length) {
       allowed[c.key] = c.values.map((v) => v.value ?? "").filter((v) => v !== "");
     }
+    const hide = parseHide(c.conditional?.hide);
+    if (hide) hideWhen[c.key] = hide;
   }
-  const contract: FormContract = { required, allowed };
+  const contract: FormContract = { required, allowed, hideWhen };
   formContractCache.set(formId, contract);
   return contract;
 }
@@ -117,18 +172,23 @@ function formContract(formId: string): FormContract {
 /** Validate completion `variables` against the escalation's `.form` contract (required fields present
  *  + `select` values within the allowed set), so a completion can never resume the process with a
  *  missing/invalid decision (e.g. a `wait-answer` with no `answer`, or a `trial-merge-decision` with
- *  an `action` outside proceed/rebase/abandon). Returns a human-readable reason on violation, or
- *  `null` when the variables satisfy the contract. Derived from the canonical `.form` — the same
- *  contract the task inbox renders — so both the agent and human completers reject invalid input the
- *  exact same way, with one implementation. An element with no linked form contract is not enforced. */
+ *  an `action` outside proceed/rebase/abandon). A conditionally-shown required field is only enforced
+ *  when its `conditional.hide` rule leaves it visible — so a `feature-escalation` with
+ *  `resolution="answer"` demands a non-blank `answer` (re-dispatch guidance), but the `abandon` path,
+ *  which hides `answer`, does not. Returns a human-readable reason on violation, or `null` when the
+ *  variables satisfy the contract. Derived from the canonical `.form` — the same contract the task
+ *  inbox renders — so both the agent and human completers reject invalid input the exact same way,
+ *  with one implementation. An element with no linked form contract is not enforced. */
 export function validateEscalationVariables(
   elementId: string,
   variables: Record<string, unknown>,
 ): string | null {
   const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
   if (!formId) return null;
-  const { required, allowed } = formContract(formId);
+  const { required, allowed, hideWhen } = formContract(formId);
   for (const key of required) {
+    const hide = hideWhen[key];
+    if (hide && isHidden(hide, variables)) continue;
     const v = variables[key];
     if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) {
       return `${elementId}: "${key}" is required`;
@@ -222,19 +282,24 @@ export interface AgentCompleteResult {
   elementId?: string;
 }
 
-/** Resolve a parked escalation user task by key: return its `elementId` if it is one of the migrated
- *  escalation tasks, or a failure reason otherwise. Shared by the agent and human completers so both
- *  refuse a non-escalation / missing target the exact same way (a key with no matching open
- *  escalation task is a 404-style no-op). */
+/** Resolve a parked escalation user task by key: return its `elementId` if it is one of the `allowed`
+ *  completable tasks, or a failure reason otherwise. Shared by the agent and human completers so both
+ *  refuse a non-completable / missing target the exact same way (a key with no matching open task is a
+ *  404-style no-op). The AGENT completer passes the default `ESCALATION_TASK_ELEMENTS`; the HUMAN
+ *  completer passes the wider `HUMAN_COMPLETABLE_ELEMENTS` (which also admits `feature-blocked`).
+ *  Queries `openUserTasks` (lifecycle-state `CREATED` only), NOT `searchUserTasks` (which returns
+ *  tasks in ANY state) — a looping instance keeps COMPLETED/CANCELED tasks whose key could otherwise
+ *  match and drive a doomed re-completion (a thrown 5xx) instead of the intended 404-style no-op. */
 async function resolveEscalationTask(
   engine: EngineClient,
   userTaskKey: string,
+  allowed: ReadonlySet<string> = ESCALATION_TASK_ELEMENTS,
 ): Promise<{ ok: true; elementId: string } | { ok: false; reason: string }> {
-  const open = await engine.searchUserTasks();
+  const open = await engine.openUserTasks();
   const match = open.find((t) => t.userTaskKey === userTaskKey);
-  if (!match) return { ok: false, reason: "no open escalation task" };
-  if (!match.elementId || !ESCALATION_TASK_ELEMENTS.has(match.elementId)) {
-    return { ok: false, reason: "not an escalation task" };
+  if (!match) return { ok: false, reason: "no open completable task" };
+  if (!match.elementId || !allowed.has(match.elementId)) {
+    return { ok: false, reason: "not a completable task" };
   }
   return { ok: true, elementId: match.elementId };
 }
@@ -275,7 +340,8 @@ export async function completeEscalationAsAgent(
  *  affordance resumes the process through the one implementation a human uses from the task inbox —
  *  no parallel completion path — while recording WHO answered in the `task_completions` ledger. A
  *  human completion is the authority (not reversible). A key with no matching open escalation task is
- *  a 404-style no-op. */
+ *  a 404-style no-op. The human surface is the wider `HUMAN_COMPLETABLE_ELEMENTS`, so it also retires a
+ *  `feature-blocked` acknowledgement (issue #332 folded the bespoke `acknowledge-blocked` door here). */
 export async function completeEscalationAsHuman(
   data: DataLayer,
   engine: EngineClient,
@@ -286,7 +352,7 @@ export async function completeEscalationAsHuman(
   const operatorId = input.operatorId.trim();
   if (!operatorId) return { ok: false, reason: "operatorId is required" };
 
-  const resolved = await resolveEscalationTask(engine, userTaskKey);
+  const resolved = await resolveEscalationTask(engine, userTaskKey, HUMAN_COMPLETABLE_ELEMENTS);
   if (!resolved.ok) return resolved;
 
   const invalid = validateEscalationVariables(resolved.elementId, input.variables);
@@ -301,44 +367,6 @@ export async function completeEscalationAsHuman(
   return { ok: true, completionId, userTaskKey, elementId: resolved.elementId };
 }
 
-/** The `feature-blocked` operator user-task element id (feature.bpmn). Unlike an escalation this is not
- *  an agent-answerable task — it is a blocked-run acknowledgement only a human operator retires — so it
- *  lives outside `ESCALATION_TASK_ELEMENTS` (the agent completer must never touch it) and has its own
- *  human-only completer below. */
-export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
-
-/** Complete the `feature-blocked` operator user task AS A HUMAN (issue #220). The blocked twin of
- *  `completeEscalationAsHuman`: it resolves the parked task by key, refuses anything that is not the
- *  `feature-blocked` task, and routes the operator's typed form variables (an optional `note`) through
- *  the SAME canonical `completeUserTaskAttributed` — so the nwf "Acknowledge blocked" affordance resumes
- *  the process (→ `pr.record-blocked-ack`, which settles the row to terminal `blocked`) through the one
- *  completion a human drives from the task inbox, recording WHO acknowledged in the `task_completions`
- *  ledger. A human completion is the authority (not reversible). A key with no matching open
- *  `feature-blocked` task is a 404-style no-op. */
-export async function completeBlockedAsHuman(
-  data: DataLayer,
-  engine: EngineClient,
-  input: { userTaskKey: string; variables: Record<string, unknown>; operatorId: string },
-): Promise<AgentCompleteResult> {
-  const userTaskKey = input.userTaskKey.trim();
-  if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
-  const operatorId = input.operatorId.trim();
-  if (!operatorId) return { ok: false, reason: "operatorId is required" };
-
-  const open = await engine.searchUserTasks();
-  const match = open.find((t) => t.userTaskKey === userTaskKey);
-  if (!match) return { ok: false, reason: "no open blocked task" };
-  if (match.elementId !== FEATURE_BLOCKED_TASK_ELEMENT) return { ok: false, reason: "not a blocked task" };
-
-  const { completionId } = await completeUserTaskAttributed(
-    data,
-    engine,
-    { userTaskKey, elementId: match.elementId, variables: input.variables },
-    { kind: "human", id: operatorId },
-  );
-  return { ok: true, completionId, userTaskKey, elementId: match.elementId };
-}
-
 export interface RevertResult {
   ok: boolean;
   reason?: string;