Skip to content

Commit de46ea1

Browse files
os-zhuangclaude
andcommitted
docs(approvals): drop duplicate role-vs-position callout (unbreak role-word ratchet)
The ESLint job's "Reserved-word (role) docs ratchet" step has been red on main since 25a19be, which took approvals.mdx from 5 -> 9 role-word occurrences. Every open PR inherits the red check. The occurrences are NOT ADR-0090 D3 drift and cannot be reworded away: `role` is a real, shipping approver type (spec/src/automation/approval.zod.ts:14) that resolves against better-auth's org-membership tier (`sys_member.role`), which D3 names as its single documented exception ("third-party schema we do not own"). Writing `position` in these spots would make the docs wrong -- telling the two apart is the entire point of the passage, and of the `approval-role-not-membership-tier` lint rule. What the ratchet did catch is real redundancy: the new callout under "The request opens, the run pauses" restates the callout ~75 lines above it, which says the same thing and more (it names the lint rule). Removed the duplicate. That leaves `role:<r>` in the approverId filter list -- a genuine new fact at the same sanctioned boundary (spec/src/contracts/approval-service.ts:231). Rather than delete a true API detail to satisfy a counter, the surviving callout is tightened: it stated role-the-approver-type twice ("The `role` approver type ..." and "authored as `type: 'role'`"), now once. That frees the slot, so the file lands back at exactly 5. Baseline deliberately NOT bumped -- a high-water mark that only ratchets down is the point of the gate. Verified: node scripts/check-role-word.mjs -> OK (exit 0); pnpm lint -> exit 0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 5f05de2 commit de46ea1

1 file changed

Lines changed: 4 additions & 11 deletions

File tree

content/docs/automation/approvals.mdx

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,10 @@ defineFlow({
5454

5555
<Callout type="warn">
5656
**`position` vs `role`.** `{ type: 'position', value: 'finance_manager' }` routes to the
57-
holders of a position (`sys_user_position`, ADR-0090 D3). The `role` approver type is the
58-
better-auth **org-membership tier** (`sys_member.role`: `owner`/`admin`/`member`) — a position
59-
name authored as `type: 'role'` matches nobody and the request stalls; `os lint` flags this
60-
(`approval-role-not-membership-tier`).
57+
holders of a position (`sys_user_position`, ADR-0090 D3). `type: 'role'` is a different thing
58+
entirely — the better-auth **org-membership tier** (`sys_member.role`: `owner`/`admin`/`member`)
59+
— so a business position name authored there matches nobody and the request stalls; `os lint`
60+
flags this (`approval-role-not-membership-tier`).
6161
</Callout>
6262

6363
Approving is itself a gated action — model "may approve" as a capability (`approve_invoice`) the approver's permission set grants, and gate the approve action's `requiredPermissions` on it so the gate is enforced on **both** the UI and the server (ADR-0066 D4).
@@ -132,13 +132,6 @@ and the flow run parks until a decision arrives.
132132
Only `approvers` is required on the node; everything else has a default
133133
(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`).
134134

135-
<Callout type="warn">
136-
**`type: 'role'` is not a position.** In an approver entry, `role` means the
137-
better-auth membership tier (`owner` / `admin` / `member`). Naming a business
138-
role like `sales_manager` there matches nobody and the request silently has no
139-
approvers — use `{ type: 'position', value: 'sales_manager' }`.
140-
</Callout>
141-
142135
### The approver finds it in their queue
143136

144137
Requests land in **Setup → Approvals → Requests**, whose `my_pending` view

0 commit comments

Comments
 (0)