docs(spec): state minApprovals' real per-behavior default in the schema prose

.changeset/min-approvals-default-prose.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+Approval nodes: `minApprovals` now documents its real per-behavior default.
+
+The property described itself as "Default 1", but an omitted threshold has never
+meant 1 under `behavior: 'quorum'` — the approval runtime falls back to the
+resolvable approver count, so a quorum node authored without `minApprovals`
+requires **every** approver rather than one. Under `behavior: 'per_group'` the
+fallback really is one approval per group.
+
+The schema text and the generated reference table now state both defaults. This
+is a documentation correction only: no schema default was added, the accepted
+value set is unchanged, and no stored approval flow changes behavior.

content/docs/references/automation/approval.mdx

@@ -69,7 +69,7 @@ const result = ApprovalDecision.parse(data);
 | :--- | :--- | :--- | :--- |
 | **approvers** | `{ type: Enum<'manager' \| 'position' \| 'department' \| 'team' \| 'field' \| 'expression' \| …>; value?: string; resolveAs?: Enum<'user' \| 'department' \| 'position' \| 'team'>; group?: string; … }[]` | ✅ | Allowed approvers for this node |
 | **behavior** | `Enum<'first_response' \| 'unanimous' \| 'quorum' \| 'per_group'>` | optional (default: `"first_response"`) | How to combine multiple approvers |
-| **minApprovals** | `integer` | optional | Approvals required — total (quorum) or per group (per_group). Default 1 |
+| **minApprovals** | `integer` | optional | Approvals required — total (quorum) or per group (per_group). Omitted ⇒ all resolvable approvers for quorum, 1 per group for per_group |
 | **lockRecord** | `boolean` | optional (default: `true`) | Lock the record from editing while pending |
 | **approvalStatusField** | `string` | optional | Business-object field to mirror request status onto |
 | **onEmptyApprovers** | `Enum<'admin_rescue' \| 'fail' \| 'auto_approve'>` | optional (default: `"admin_rescue"`) | Behavior when no concrete approver resolves at node entry |

packages/spec/scripts/liveness/empty-state-registry.mts

@@ -117,6 +117,16 @@ export const EMPTY_STATE_REGISTRY: EmptyStateEntry[] = [
       'packages/core/src/security/resolve-authz-context.ts (resolveAuthzContext.hasPlatformAdminGrant — the single source of truth) and packages/plugins/plugin-security/src/explain-engine.ts (the identical predicate, replicated so the panel cannot overstate)',
   },
 
+  {
+    file: 'packages/spec/src/automation/approval.zod.ts',
+    property: 'minApprovals',
+    semantics: 'closed',
+    rationale:
+      "The approval threshold of a `quorum` / `per_group` node, and a case where the permissive-looking word is the restrictive one. Omitted under `quorum` the runtime requires EVERY resolvable approver — the threshold falls back to the resolved approver count, so a node whose author never wrote the key blocks until all of them sign, the least-privilege direction rather than the widest. Under `per_group` omission means one approval per group, and every group must still reach it. The `all` in the declared text therefore names APPROVERS REQUIRED, never access granted. Registered rather than reworded around the scanner because that sentence is the only place an author learns the omitted threshold is not 1 — which is precisely the drift this classification exists to keep visible.",
+    evidence:
+      'packages/plugins/plugin-approvals/src/approval-service.ts (ApprovalService.isApprovalSatisfied — the omitted-threshold fallbacks and their clamp to the resolvable count)',
+  },
+
   // ---- Scope selectors ---------------------------------------------------
 
   {

packages/spec/src/automation/approval.test.ts

@@ -296,6 +296,26 @@ describe('ApprovalNodeConfigSchema', () => {
     expect(perGroup.behavior).toBe('per_group');
     expect(perGroup.approvers[0].group).toBe('legal');
   });
+
+  // The schema injects NO default for `minApprovals`: omitting it leaves the
+  // key undefined and the enforced threshold is then chosen by `behavior` —
+  // every resolvable approver under `quorum`, one per group under `per_group`.
+  // The `.describe()` prose is the only place an author can read that, so pin
+  // both halves together: a threshold silently declared as 1 while the runtime
+  // demands unanimity is the drift this test exists to catch.
+  it('declares the per-behavior default of an omitted minApprovals', () => {
+    const quorum = ApprovalNodeConfigSchema.parse({ ...minimal, behavior: 'quorum' });
+    expect(quorum.minApprovals).toBeUndefined();
+    const perGroup = ApprovalNodeConfigSchema.parse({ ...minimal, behavior: 'per_group' });
+    expect(perGroup.minApprovals).toBeUndefined();
+
+    const doc = ApprovalNodeConfigSchema.shape.minApprovals.description ?? '';
+    expect(doc).toContain('quorum');
+    expect(doc).toContain('per_group');
+    expect(doc).toContain('all resolvable approvers for quorum');
+    expect(doc).toContain('1 per group for per_group');
+    expect(doc).not.toContain('Default 1');
+  });
 });
 
 describe('ApprovalEscalationSchema', () => {

packages/spec/src/automation/approval.zod.ts

@@ -711,11 +711,16 @@ export const ApprovalNodeConfigSchema = lazySchema(() => strictObject(
 
   /**
    * Threshold for `quorum` (total approvals required, M of N) and `per_group`
-   * (approvals required from EACH group). Defaults to 1. Clamped at runtime so
-   * it can never exceed the resolvable approver count (no deadlock).
+   * (approvals required from EACH group). Omitted, the threshold follows the
+   * behaviour rather than a fixed 1: `quorum` requires every resolvable
+   * approver, `per_group` requires one approval per group. Clamped at runtime
+   * so it can never exceed the resolvable approver count (no deadlock).
    */
   minApprovals: z.number().int().min(1).optional()
-    .describe('Approvals required — total (quorum) or per group (per_group). Default 1'),
+    .describe(
+      'Approvals required — total (quorum) or per group (per_group). '
+      + 'Omitted ⇒ all resolvable approvers for quorum, 1 per group for per_group',
+    ),
 
   /** Lock the triggering record from edits while this node is pending. */
   lockRecord: z.boolean().default(true).describe('Lock the record from editing while pending'),