Architect a multi-step admin workflow/approval engine for role and policy changes

[Lakes41]

Difficulty: Expert
Type: feature

Background
The README lists "Complex admin workflows" among the intentionally deferred features, while the currently-implemented admin surfaces ("basic role assignment and policy editing") apply changes immediately and unilaterally via POST /v1/members/:address/roles and PUT /v1/policies/:resourceId.

Problem
For communities that want sensitive changes (revoking an admin's role, tightening an access policy) to require review or multi-admin approval rather than taking effect instantly, there's no workflow layer — every admin action is immediate and unilateral.

Expected outcome
A client-side (frontend-owned, since guildpass-core doesn't yet model this) workflow layer lets communities configure which action types require N-of-M admin approval, presenting pending actions as "proposed changes" that other admins can approve/reject before the underlying mutation actually fires, with a clear pending-changes queue in the UI.

Suggested implementation

• Design a PendingAction model (action type, payload, proposer, required approvals, current approvals, status) — since guildpass-core doesn't model this yet, decide and document whether this state lives in lib/api/mock.ts-style local persistence for now, or requires backend support (flag as a follow-up if so), being explicit about this boundary.
• Add a configuration surface (e.g., in community settings) for which action types require approval and how many approvals.
• Intercept role-assignment and policy-update mutations: if the acting admin's action type requires approval, create a PendingAction instead of calling the mutation directly; once enough approvals accumulate, execute the original mutation.
• Build a "Pending Approvals" admin view listing actions awaiting the current admin's decision, with approve/reject actions.
• Add thorough tests: single-approval-required actions execute immediately (backward compatible default), multi-approval actions correctly gate execution until threshold met, and rejected actions never execute.

Acceptance criteria

• Communities can configure per-action-type approval requirements
• Actions requiring more than one approval are correctly held pending until threshold is met
• Rejected actions are guaranteed to never execute the underlying mutation
• Clear documentation of what's frontend-only vs. what would need guildpass-core support for full correctness/security

Likely affected files/directories

• app/admin/ (pending approvals view, settings)
• lib/api/mock.ts, lib/api/live.ts
• docs/ (new design doc)

[EngrEOOnoja]

I'd like to take this on. I'll design a PendingAction model (frontend/mock-persisted for now) with configurable per-action-type N-of-M approval requirements, intercept the role-assignment and policy-update mutations to route through it when required, build the Pending Approvals admin view with idempotent approve/reject handling, and write tests covering immediate-execution defaults, multi-approval gating, and guaranteed non-execution on rejection with clear documentation of the frontend-only trust boundary and what would be needed from guildpass-core for real enforcement.

[grantfox-oss]

🦊 GrantFox — @EngrEOOnoja has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #339)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.