[finding] No page defines the org-membership tier vocabulary — `delegated_admin` is addressable in two places and explained in none

[os-zhuang]

Found while implementing #131 (PR #152), which adds delegated_admin to the tier list on build/automation/approvals.mdx. Out of that card's scope — #131 is one file and its job is to make the vocabulary correct, not to introduce a definition.

What is missing

After #152 lands, the four-value org-membership tier vocabulary (owner, admin, delegated_admin, member — ADR-0108, sys_member.role) appears in exactly two places in the English corpus, both of which only use it:

• content/docs/configure/notifications.mdx:137 — as the values a role: principal selector accepts.
• content/docs/build/automation/approvals.mdx:77 and :88 — as the values an org_membership_level approver accepts.

No page says what the tiers are, what a delegated admin may do, or where the tier is set. A reader who meets delegated_admin on either page has nowhere in the corpus to go.

Why this is more than a missing gloss

The nearest anchor a reader (or an author adding a link) would reach for is wrong:

• configure/permissions/permission-sets.mdx:120 — Delegated administration — documents a permission set carrying an adminScope. That is a different mechanism from the delegated_admin membership tier.

Upstream is explicit that these must not be merged. objectstack:packages/spec/src/identity/membership-role.ts heads a section "Three facts that look like one — do not merge them", and says of the tier:

It carries NO ObjectStack authority by construction […] Reaching the endpoint is not authority to place — placement authority comes solely from a separately-granted adminScope. Role = can reach the endpoint; adminScope = what the endpoint permits.

The two are doubly opt-in and independent: someone must set the membership tier and grant an adminScope. So a reader who assumes the tier grants the delegated-administration powers documented at permission-sets#delegated-administration has formed exactly the belief the spec is built to prevent — and the corpus currently offers nothing that corrects it.

configure/users.mdx does not cover this either: its "memberships" section is about sys_business_unit_member (org-tree placement), a different object from sys_member.

Suggested shape (not a decision)

A short tier table on an identity/permissions page — most likely configure/users.mdx alongside memberships, or configure/permissions/ — giving each of the four tiers a one-line meaning, stating that the tier is a grade that decides what you can reach rather than a bundle of permissions, and explicitly distinguishing delegated_admin from an adminScope. The two consuming pages could then link to it instead of repeating a bare list.

Filing unassigned for triage; no page's current statement is false, so this is a coverage gap rather than a defect.

[os-zhuang]

Triage: pm:queue, Task. Author the four-tier table (one-line meaning each, tier = reach-grade not permission bundle, delegated_admin ≠ adminScope — the spec's own "three facts that look like one" header is the oracle to cite), then link the two consuming pages to it. Location (users.mdx vs permissions/) is the author's call, stated in the PR body.

---

Generated by Claude Code

[os-zhuang]

Claim: PM loop round 1
Session: session_016TUrhcggSFrYctvp5dsV1A
Branch: claude/issue-153-org-membership-tier-vocabulary
Worktree: objectos-issue-153
Domain: n/a — objectos is a single-lane repo and carries no domain:* labels
File surface: content/docs/configure/users.mdx (primary), plus link-only edits to content/docs/configure/notifications.mdx and content/docs/build/automation/approvals.mdx (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — dispatch-gates.mjs --tier reports no path-derived mandate for objectos paths, so the tier is this seat's call. Above the floor because the page must draw a distinction the spec is explicitly built to protect, and getting it subtly wrong plants the exact belief the card exists to prevent.
Clause-②: no
Serial constraints cleared: the serial predecessor on configure/permissions/ has landed — #154 merged as b0b159b, so nothing is in flight there. #159 is in flight on .github/dependabot.yml and #165 on .github/workflows/ + a new scripts/ tree — both disjoint. ⚠️ permission-sets.mdx was just rewritten by #154; if you touch anything near it, read the file rather than any snippet.

---

Location — adjudicated by this seat, so it is no longer an open question

The card offers configure/users.mdx or somewhere under configure/permissions/ and explicitly declines to choose ("Suggested shape (not a decision)"). Decision: configure/users.mdx, in its own section. Three measured reasons, not a preference:

1. That page already declares the object and never explains it. configure/users.mdx:12 lists the objects the page covers and sys_member is among them (sys_member, sys_business_unit, sys_team, sys_invitation). So the page has already claimed the thing whose role field this vocabulary is; the gap is that it claims it and then never defines its tiers. That makes this an omission on an existing owner page, not a new home to invent.

2. configure/permissions/ is the wrong shelf, and putting it there would cause the exact error the card is about. That section documents what a principal may do — its own structure is "Layer 1 — Identity / Layer 2 — Positions / Layer 3 — Permission sets / …". But upstream is explicit (packages/spec/src/identity/membership-role.ts:77-82, which I read rather than took from the card):

   It carries NO ObjectStack authority by construction … Reaching the endpoint is not authority to place — placement authority comes solely from a separately-granted adminScope. Role = can reach the endpoint; adminScope = what the endpoint permits.

   A tier that confers no authority, filed inside the authority model, invites a reader to read it as authority. That is the misreading the card is trying to prevent.

3. The spec states the placement principle itself. Same file, :47-48: "A future reader will be tempted to 'unify the role lists'. Only the first of these is a list; the other two are rules that belong near what they govern." Near what it governs = near sys_member, i.e. the users page.

⛔ And the trap inside that decision — do not put it in the existing memberships section

configure/users.mdx:90 is "Place people in the org tree (memberships)" and it is about sys_business_unit_member (user + business unit) — a different object from sys_member. Dropping the tier table in there merges two of the three facts the spec names as "look like one — do not merge them". Give it its own section, and make the distinction explicit rather than leaving it to the reader's inference. The page using the word "membership" for both is precisely why this needs saying out loud.

What the section must carry

• The four tiers — owner, admin, delegated_admin, member (ADR-0108, sys_member.role) — each with a one-line meaning.
• That the tier is a grade deciding what you can reach, not a bundle of permissions.
• The delegated_admin ≠ adminScope distinction, stated plainly. configure/permissions/permission-sets.mdx:120 documents Delegated administration as a permission set carrying an adminScope — a different mechanism, and the nearest thing a reader or a future link-adder would wrongly reach for. The two are doubly opt-in and independent: someone must set the tier and be granted an adminScope.
• That it is distinct from the org-tree placement the page already documents.

Then point the two consuming pages at it instead of repeating a bare list: configure/notifications.mdx:137 and build/automation/approvals.mdx:77/:88. Link edits only there — ⛔ do not rewrite those pages' surrounding prose.

PM mechanism assumptions (test these; falsifying one is a good outcome)

• I assume the four tiers and their meanings are current on objectstack origin/main. Re-verify against packages/spec/src/identity/membership-role.ts and ADR-0108 — I confirmed the file defines MEMBERSHIP_ROLE_OWNER and MEMBERSHIP_ROLE_DELEGATED_ADMIN and carries the framing above, but I did not enumerate all four tiers' semantics. That is yours, and it is the substance of the page.
• I assume configure/users.mdx has a natural insertion point near its existing membership material. If reading the page shows the section order makes that awkward, place it where it reads best within that page and say why — the page is adjudicated, the position inside it is your call.
• ⚠️ delegated_admin's meaning is the one most likely to be written wrong. Upstream notes better-auth grants invitation: ["create"] to some tiers (membership-role.ts:70), so "what a delegated admin may do" is subtler than the name suggests. If you cannot state it from measurement, say so and write less rather than guessing — an under-specified true table beats a confident wrong one.

Scope

⛔ Do not restructure configure/permissions/. ⛔ Do not touch permission-sets.mdx (just landed via #154). ⛔ Do not sweep locale siblings — translations are never a dev agent's output here. ⛔ No new page: this is a section on an existing one.

Verification

No changeset flow, no packages/. pnpm turbo run build, pnpm turbo run test, and node .github/scripts/check-locale-surface.mjs from the repo root — wrong cwd exits 1 with MODULE_NOT_FOUND, an invocation error not a red gate. Use --force; capture exit codes before any pipe. Adding a section changes no advertised URL, so the locale-surface gate's oracle should be unchanged — say so explicitly, since an unchanged oracle is the positive evidence you added no page and dropped none.

If you add an anchor other pages link to, confirm the links resolve to it; a broken in-page anchor 404s silently and no gate here catches it.

Reporting

Post your report as a comment on this issue first, then return it. The sanitizer eats a leading HTML-comment marker — fall back to a literal first line os-dev-report. Read it back with a GET, never PATCH. Leave your own claim comment with your session ID and branch before you start implementing. I hold the assignee field; do not touch it. premise_still_valid: false with no PR is a legitimate delivery.

---

Generated by Claude Code

[os-zhuang]

Claim (dev agent, PM dispatch round 1)

Session: session_016TUrhcggSFrYctvp5dsV1A
Branch: claude/issue-153-org-membership-tier-vocabulary (pushed, empty, at base b0b159b)
Worktree: objectos-issue-153
File surface: content/docs/configure/users.mdx (new section), plus link-only edits to content/docs/configure/notifications.mdx and content/docs/build/automation/approvals.mdx.

Location is taken as adjudicated by the PM (configure/users.mdx, own section, not folded into the existing org-tree memberships section). Not touching configure/permissions/**, no locale siblings, no new page, assignee left alone.

---

Generated by Claude Code