Design and implement the Governance module (deferred) behind its existing feature flag

[Lakes41]

Difficulty: Expert
Type: feature

Background
The README already reserves NEXT_PUBLIC_FEATURE_GOVERNANCE (default false everywhere) and lists "Advanced analytics and governance" as intentionally deferred, but no governance UI or data model currently exists in this frontend.

Problem
Communities have no way to propose, discuss, or vote on decisions (role policy changes, resource additions, community rules) through the dashboard, and there's no defined contract for how this frontend would talk to a (currently non-existent, or future guildpass-core) governance backend.

Expected outcome
A feature-flagged Governance module lets members view active proposals, cast votes (weighted by role/tier if applicable), and lets admins create new proposals, backed by a clearly documented API contract this frontend expects from guildpass-core (to be implemented there separately), with a full mock-mode implementation so the module is demoable without a live governance backend.

Suggested implementation

• Design the proposal/vote data shapes in lib/api/types.ts (or a new governance-specific types module) and document the expected guildpass-core endpoints (e.g., GET /v1/governance/proposals, POST /v1/governance/proposals/:id/vote) in a new docs/governance-contract.md.
• Implement lib/api/mock.ts support for the full proposal lifecycle (draft → active → closed → resolved) with simulated votes.
• Build the /governance route (proposal list, proposal detail with voting UI, admin proposal-creation form), gated via <FeatureGate enabled={features.governance} name="Governance"> following the documented pattern.
• Ensure vote-casting respects the existing SIWE-authenticated admin/member patterns (voting likely requires an authenticated wallet at minimum, even if not full admin SIWE).
• Add lib/api/live.ts implementations calling the documented (new) endpoints, with clear 503/graceful-degradation behavior if the live backend doesn't yet support them (consistent with the existing integration-gateway pattern).

Acceptance criteria

• Module fully functions in mock mode (create proposal, vote, see results)
• API contract for guildpass-core documented clearly enough to be implemented independently
• Live-mode implementation degrades gracefully (not a hard crash) if the backend doesn't support governance endpoints yet
• Module is properly hidden/flagged per the existing feature-flag pattern

Likely affected files/directories

• app/governance/ (new)
• lib/api/mock.ts, lib/api/live.ts, lib/api/types.ts
• lib/features.ts
• docs/governance-contract.md (new)

[Six2world]

I'll take this one.

Plan:

1. Define proposal/vote types in lib/api/types.ts (or new lib/api/governance-types.ts) covering the full lifecycle: draft → active → closed → resolved, plus vote weighting by role/tier.
2. Document the expected guildpass-core contract in docs/governance-contract.md — endpoints like GET /v1/governance/proposals and POST /v1/governance/proposals/:id/vote, request/response shapes, auth requirements.
3. Implement lib/api/mock.ts with a full simulated lifecycle so the module is demoable standalone.
4. Build /governance (list, detail + voting UI, admin create-proposal form) gated behind <FeatureGate enabled={features.governance} name="Governance">.
5. Voting requires at least an authenticated wallet, reusing existing SIWE patterns rather than inventing a new auth path.
6. Add lib/api/live.ts calls to the documented endpoints with graceful 503/degradation handling if guildpass-core doesn't support them yet — no hard crash.
7. Tests around mock-mode lifecycle and live-mode graceful degradation.

Assigning to myself.

[grantfox-oss]

🦊 GrantFox — @Six2world 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 #337)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.