docs(approvals): unblock main — drop duplicated role warning, generalize approver literal

[os-zhuang]

Why

lint.yml has been red on main since #3113 — the Reserved-word ("role") docs ratchet step fails, so every open PR inherits it (e.g. #3116). Reproduces from a clean origin/main:

check-role-word: 1 problem(s)
  • content/docs/automation/approvals.mdx: role-word count grew 5 → 9. New occurrences are banned (ADR-0090 D3).

#3113 added four occurrences to content/docs/automation/approvals.mdx without ratcheting the baseline.

The decision: reword, not a baseline bump

Both obvious framings turned out to be wrong, so the evidence is worth stating.

"role is deprecated, so reword it away" — false. role is live and load-bearing:

• packages/spec/src/automation/approval.zod.ts still enumerates 'role' alongside 'position' in ApproverType — they coexist and mean different things; neither is a migration half.
• packages/spec/src/automation/approval.test.ts explicitly asserts 'role' parses.
• expandRoleUsers resolves it against sys_member.role at runtime.
• No deprecation marker anywhere on it.

role here is the better-auth org-membership tier (sys_member.role: owner/admin/member) — precisely ADR-0090 D3's single documented exception ("third-party schema we do not own"). #2738 (216fa9a) did not deprecate it; it added position beside it and documented role as "the membership tier it actually is".

"They're legitimate, so bump the baseline 5 → 9" — legitimate, but not necessary. Three of the four are a near-verbatim duplicate of the callout 80 lines earlier, and that earlier one is better (it names the approval-role-not-membership-tier lint rule). The fourth was an over-narrow API description. The baseline is for occurrences that can't be removed without losing accuracy — these can.

What changed

• Removed the duplicated warning in the lifecycle Steps. Kept the fact that section actually needs (an approver entry resolving to nobody parks the run forever — the consequence) and cross-referenced the authoritative warning under 3. The approval node.
• Generalized approverId: it was documented as accepting role:<r>. The runtime falls back to a generic `${a.type}:${a.value}` literal for every approver type (expandApprovers), and rest-server.ts only splits on commas — it never validates the prefix. <type>:<value> is the real contract; role:<r> described one arbitrary instance of it.

Net: same information, one authoritative home, no accuracy lost, and the reserved-word surface shrinks back to 5 instead of freezing 4 avoidable occurrences. The surviving 5 are the one better-auth boundary callout — deliberately untouched, since renaming a third-party identifier we don't own would make the docs wrong.

Verification

$ node scripts/check-role-word.mjs
check-role-word: OK (49 baselined file(s), no new occurrences).

scripts/role-word-baseline.json is unmodified — the diff is one file. The sibling lint.yml doc gates also pass locally:

• check:doc-authoring → 199 files clean
• check:release-notes → OK

Notes for the reviewer

• Docs-only → skip-changeset.
• ⚠️ There is an uncommitted, unpushed draft of the same fix in a sibling worktree on branch fix/role-word-approvals (no PR opened). It reaches a similar conclusion but cross-references a broken anchor (#the-approval-node; the heading is ### 3. The approval node). If that agent is still active, close whichever of these lands second.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 17, 2026 12:14pm

[os-zhuang]

关闭：与 #3122 重复，且两者都是创可贴——只把文档里的重复表述删掉，没碰造成混淆的根因（ApproverType.role 这个名字本身）。

改为按 #3133 的结论一次做对：把 role 改名成 ADR 早已规定的投影名 org_membership_level，文档随之不再需要写这个保留词，role-word 棘轮的红是改名的副产品而不是单独一轮修补。新 PR 会引用本 PR 与 #3122。