fix(approvals): defense-in-depth for empty-approver routing (#3424)

Two authoring-time / demo-time complements to the admin-override recovery:

- lint: new advisory rule `approval-approvers-may-resolve-empty` (info) fires
  when EVERY approver on an approval node routes to a group that can be empty
  (position/team/department) — the exact shape that dead-ends when nobody holds
  the group. It prescribes a guaranteed-staffed fallback
  (`{ type: 'org_membership_level', value: 'owner' }`). Advisory, since staffing
  is runtime data a linter can't see; individual/owner-tier fallbacks suppress
  it. Non-gating (info → suggestion).
- showcase: the seed staffed `manager`/`finance`/`legal` but not `exec`, the
  second tier of `showcase_budget_approval` (manager → exec) — a user driving a
  budget approval to step 2 hit the exact #3424 dead-end. Staff `exec` too so
  every position the showcase flows route to is actionable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VmQPXXbgomoqrXtoxr3CS2

Author: claude

examples/app-showcase/src/security/seed-approval-demo.ts

@@ -41,8 +41,16 @@ const SYS = { isSystem: true } as const;
 
 const ADMIN_EMAIL = 'admin@objectos.ai';
 
-/** Positions the admin is granted so they resolve as an approver on the demos. */
-const ADMIN_APPROVAL_POSITIONS = ['manager', 'finance', 'legal'] as const;
+/**
+ * Positions the admin is granted so they resolve as an approver on the demos.
+ * Covers every `{ type: 'position' }` the showcase approval flows route to and
+ * expect the admin to hold — including `exec`, the SECOND tier of
+ * `showcase_budget_approval` (manager → exec). Without `exec` a budget approval
+ * that a user drives to step 2 routes to an unstaffed position and dead-ends
+ * (framework#3424): undecidable request, record locked. Keep this in sync with
+ * the position values authored in `automation/flows`.
+ */
+const ADMIN_APPROVAL_POSITIONS = ['manager', 'finance', 'legal', 'exec'] as const;
 
 /** A phone-based demo persona (§6 "phone sign-in surfaces"). */
 const PHONE_DEMO_USER = {

packages/lint/src/index.ts

@@ -106,6 +106,7 @@ export {
   APPROVAL_APPROVER_TYPE_DEPRECATED,
   APPROVAL_APPROVER_TYPE_UNKNOWN,
   APPROVAL_ESCALATION_REASSIGN_NO_TARGET,
+  APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY,
 } from './validate-approval-approvers.js';
 export type { ApprovalApproverFinding, ApprovalApproverSeverity } from './validate-approval-approvers.js';
 

packages/lint/src/validate-approval-approvers.test.ts

@@ -7,6 +7,7 @@ import {
   APPROVAL_APPROVER_TYPE_DEPRECATED,
   APPROVAL_APPROVER_TYPE_UNKNOWN,
   APPROVAL_ESCALATION_REASSIGN_NO_TARGET,
+  APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY,
 } from './validate-approval-approvers.js';
 
 function stackWithApprovers(approvers: unknown[]): Record<string, unknown> {
@@ -120,6 +121,56 @@ describe('validateApprovalApprovers', () => {
     expect(validateApprovalApprovers(stack)).toEqual([]);
   });
 
+  // ── empty-slate dead-end (#3424) ─────────────────────────────────────────
+
+  it('flags a node routed only to a single group (unstaffed-position dead-end)', () => {
+    const findings = validateApprovalApprovers(stackWithApprovers([
+      { type: 'position', value: 'exec' },
+    ]));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY);
+    expect(findings[0].severity).toBe('info');
+    expect(findings[0].path).toBe('flows[0].nodes[1].config.approvers');
+    expect(findings[0].message).toContain('locked'); // lockRecord defaults true
+    expect(findings[0].hint).toContain("org_membership_level', value: 'owner'");
+  });
+
+  it('flags a node routed only to groups (all position/team/department)', () => {
+    const findings = validateApprovalApprovers(stackWithApprovers([
+      { type: 'position', value: 'finance' },
+      { type: 'team', value: 't1' },
+      { type: 'department', value: 'bu_sales' },
+    ]));
+    expect(findings.filter(f => f.rule === APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY)).toHaveLength(1);
+  });
+
+  it('does NOT flag when a guaranteed-staffed or individual fallback is present', () => {
+    // position + owner tier — the prescribed fallback.
+    expect(validateApprovalApprovers(stackWithApprovers([
+      { type: 'position', value: 'exec' },
+      { type: 'org_membership_level', value: 'owner' },
+    ]))).toEqual([]);
+    // position + a specific user.
+    expect(validateApprovalApprovers(stackWithApprovers([
+      { type: 'position', value: 'exec' },
+      { type: 'user', value: 'u1' },
+    ]))).toEqual([]);
+    // position + the submitter's manager.
+    expect(validateApprovalApprovers(stackWithApprovers([
+      { type: 'position', value: 'exec' },
+      { type: 'manager' },
+    ]))).toEqual([]);
+  });
+
+  it('drops the record-lock clause when lockRecord is false', () => {
+    const stack = stackWithApprovers([{ type: 'position', value: 'exec' }]);
+    (stack.flows as any)[0].nodes[1].config.lockRecord = false;
+    const findings = validateApprovalApprovers(stack);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY);
+    expect(findings[0].message).not.toContain('locked');
+  });
+
   it('only scans approval nodes and tolerates malformed shapes', () => {
     const findings = validateApprovalApprovers({
       flows: [{

packages/lint/src/validate-approval-approvers.ts

@@ -20,6 +20,7 @@
  * | approval-approver-type-deprecated          | warning  | ADR-0090 D3 (#3133)        |
  * | approval-approver-type-unknown             | warning  | contract-first (PD #12)    |
  * | approval-escalation-reassign-no-target     | warning  | silent notify degradation  |
+ * | approval-approvers-may-resolve-empty       | info     | empty-position dead-end (#3424) |
  *
  * The first two are mutually exclusive by construction — a bad *value* wins,
  * because its fix (`position`) differs from the deprecation's fix
@@ -44,6 +45,19 @@ export const APPROVAL_APPROVER_NOT_MEMBERSHIP_TIER = 'approval-approver-not-memb
 export const APPROVAL_APPROVER_TYPE_DEPRECATED = 'approval-approver-type-deprecated';
 export const APPROVAL_APPROVER_TYPE_UNKNOWN = 'approval-approver-type-unknown';
 export const APPROVAL_ESCALATION_REASSIGN_NO_TARGET = 'approval-escalation-reassign-no-target';
+export const APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY = 'approval-approvers-may-resolve-empty';
+
+/**
+ * Approver types that route to a GROUP whose membership is runtime data and can
+ * be empty (an unstaffed position, an empty team/department). When EVERY
+ * approver on a node is one of these, the node can resolve to an empty slate at
+ * runtime — the framework#3424 dead-end. Individually-routed types
+ * (`user`/`field`/`manager`), the guaranteed-staffed `org_membership_level`
+ * tiers, and the opaque `queue` are deliberately excluded: any of them present
+ * signals the author has a non-group route, so the node isn't purely
+ * group-gated.
+ */
+const GROUP_ROUTED_TYPES = new Set(['position', 'team', 'department']);
 
 export type ApprovalApproverSeverity = 'error' | 'warning' | 'info';
 
@@ -171,6 +185,38 @@ export function validateApprovalApprovers(stack: AnyRec): ApprovalApproverFindin
         }
       }
 
+      // Empty-slate dead-end (#3424): when EVERY approver on the node routes to
+      // a group whose membership can be empty (an unstaffed position, an empty
+      // team/department), the request can resolve to an empty `pending_approvers`
+      // at runtime — no concrete user can act, and with `lockRecord` the record
+      // stays locked with no recovery except a platform/tenant admin override.
+      // Advisory (`info`): staffing is runtime data a linter can't see, so this
+      // flags the risky SHAPE and prescribes a guaranteed-staffed fallback.
+      const routable = approvers.filter(
+        (a) => a && typeof a === 'object' && typeof (a as AnyRec).type === 'string',
+      );
+      if (
+        routable.length > 0 &&
+        routable.every((a) => GROUP_ROUTED_TYPES.has(canonicalApproverType(String((a as AnyRec).type))))
+      ) {
+        const locks = (cfg as AnyRec).lockRecord !== false; // default true
+        findings.push({
+          severity: 'info',
+          rule: APPROVAL_APPROVERS_MAY_RESOLVE_EMPTY,
+          where,
+          path: `flows[${fi}].nodes[${ni}].config.approvers`,
+          message:
+            `every approver on this node routes to a group (position/team/department) whose ` +
+            `members are runtime data — if none is staffed, the request resolves to an empty ` +
+            `slate and waits forever` +
+            (locks ? `, and (lockRecord) the record stays locked with no in-product recovery.` : `.`),
+          hint:
+            `Make sure at least one target is always staffed, or add a guaranteed-staffed ` +
+            `fallback approver, e.g. { type: 'org_membership_level', value: 'owner' }. A request ` +
+            `that still lands empty is recoverable only by a platform/tenant admin override (#3424).`,
+        });
+      }
+
       // escalation.action 'reassign' with no escalateTo silently degrades to a
       // plain SLA-breach notification at runtime — the hand-off the author
       // asked for never happens.