Bifrost/docs/full-implementation-strategy.md

Bifrost Full Implementation Strategy

This document aligns the current Bifrost application work with the broader GameCult labor platform concept documented in E:\Projects\gamecult-site\GameCult\Docs\labor-platform.md.

The goal is to keep Bifrost implementation boring, auditable, and staged while still preserving the actual GameCult model: contributor history, governance, work priority, reward pressure, contribution points, patron points, decay, and revenue share.

Current Readiness

Bifrost is not ready for production deployment to bifrost.gamecult.org yet.

It is currently a strong first application slice, not an internet-facing alpha. The app can compile, render pages, enforce GitHub sign-in plus membership gating, and model the broad entities we need. It does not yet have the deployment and product completeness needed for a real Yggdrasil rollout.

What Exists Already

• ASP.NET Core 8 Razor Pages app
• PostgreSQL-backed EF Core model plus initial migration
• Bifrost-native identity registration, GitHub OAuth wiring, and startup config validation
• invite and approval gate with explicit member roles
• member profile editing plus patron or contributor tier snapshots
• project, work item, motion, member, and ledger UI
• first Eve Motion Verse product surface and command endpoint, with Razor motion forms routed through the same governance service
• patron support event recording with derived patron tier snapshot refresh
• work logs, work reviews, and completion flow
• GitHub App webhook ingestion for issue, pull request, and review sync
• health and readiness endpoints plus request logging
• deployment artifacts and runbooks in gamecult-ops
• integration tests covering console access, health/readiness, and GitHub webhook sync

What Is Still Missing Before Deployment

• live GitHub App installation validation against the real GameCult/Bifrost repository
• deploy rehearsal on Yggdrasil with real secrets and a real PostgreSQL database
• backup and restore rehearsal for PostgreSQL and app secrets
• fuller workflow polish around blockers, archival, and review ergonomics
• production-safe payout proposal batching and finance review workflow
• external patron provider ingestion, full contribution point rules, scheduled decay jobs, and revenue share calculation

Product Alignment With Labor Platform

The labor platform concept doc establishes the social and economic model. Bifrost should implement that model with a few v1 clarifications:

• keep Bifrost-native identity as the account root for v1, with GitHub and Heimdall-linked providers as attached external identities rather than account owners
• keep the app invite-only during alpha
• keep payout execution out of scope; only compute, review, and audit payout proposals
• treat contribution points, patron points, decay, and revenue share as first-class product systems, not spreadsheet afterthoughts
• preserve the Labor Platform loop where eligible demand raises priority/reward pressure, contributors claim valuable work, maintainers accept completion artifacts, and accepted work becomes contributor credit plus reward allocation
• preserve the concept doc's emphasis on continuous care work, not only ticket-shaped labor

Systems That Must Exist

Identity And Membership

• GitHub-authenticated UserAccount
• member profile with nickname, skills, availability, portfolio link, and internal payout metadata
• invitation, approval, suspension, and role history
• explicit admin, producer, maintainer, and finance capabilities

Work And Review

• GitHub-backed work items and internal work items in one queue
• work categories, skill level, estimated hours, deadline, and review state
• transparent priority signals and reward pressure attached to work before it is claimed
• volunteer, assignment, review, completion, and approval transitions
• maintainer-accepted completion artifacts, usually GitHub PRs, before contributor credit/reward finalization
• support for continuous roles such as maintainer, producer, community manager, and social media work

Governance

• management motions for policy, thresholds, and role changes
• project motions for work proposals and scoped decisions
• motion categories with category-specific thresholds taken from the labor platform concept:
  • bugs: 15%
  • cosmetics: 30%
  • balance changes: 40%
  • features: 50%
  • new content: 50%
  • fundamental design changes: 66%
• Discord-native and Reddit-native voting or priority prompts should eventually write into the same governance/priority records as the web app, after Heimdall-backed identity and capability claims exist.
• Reddit organizing threads in r/GameCultOrg may host public discussion and Persona-authored prompts, but Reddit reactions are evidence until Bifrost commits a linked vote or priority signal.

Accounting

• append-only ledger entries for patron credit, contribution credit, nominal compensation, decay, and adjustment activity
• payout proposal batches that stay internal and review-driven
• audit events for every override, approval, and manual correction

Points, Tiers, Decay, And Revenue Share

These concepts need a proper implementation strategy rather than a single Points field.

Patron Points

Patron points are now derived from support events and support state, not edited freehand as a main workflow. Manual patron tier edits remain an admin override/fallback, not the normal voting-power owner.

Implementation requirements:

• store recurring support state and historical donation events separately: implemented as PatronSupportEventKind.RecurringSupportSnapshot and OneTimeDonation
• calculate patron points from current recurring support plus historical donations: implemented by PatronageService
• apply the concept-doc rule that historical donations are halved after one month and then continue decaying: implemented for effective patron point calculation
• expose both raw support history and current effective patron points: implemented on the ledger surface
• ingest Patreon/Heimdall provider events into the same service path: implemented through /heimdall/patron-support/events
• ingest PayPal/Heimdall checkout, subscription, refund, reversal, and chargeback facts into the same service path: implemented as provider metadata plus support adjustments

External provider support facts are not payment webhooks in Bifrost. Heimdall owns provider webhook verification and account linking. Bifrost accepts only Heimdall-signed support facts, resolves the linked HeimdallAccountId, deduplicates by provider event id, records support through PatronageService, and refreshes the derived patron tier.

Contributor Points

Contributor points should be granted from approved work outcomes and approved continuous-role allocations.

Implementation requirements:

• track estimated hours, skill level, category, and approval outcome on work items
• store both the rule inputs and the awarded point transaction
• keep a small automatic starter allotment for new contributors
• split contributor points into:
  • global contributor points
  • project-specific contributor points

Decay

Decay should be implemented as an auditable ledger process, not a destructive rewrite of history.

Implementation requirements:

• run a scheduled weekly decay job
• apply 1% weekly decay on decaying historical balances, rounded down
• do not decay project-specific contribution points
• persist each decay action as its own ledger transaction
• show members both lifetime totals and current effective totals

Tiers

Tiers should be computed from effective point balances and snapshot when needed for voting or payout decisions.

Patron ladder:

• Bronze: 10 points
• Silver: 100 points
• Gold: 1,000 points
• Platinum: 10,000 points
• Unobtanium: 100,000 points

Contributor ladder:

• Postulate: 10 points
• Initiate: 100 points
• Novice: 1,000 points
• Adept: 10,000 points
• Master: 100,000 points

Revenue Share

Revenue share should be implemented as proposal generation plus statements, not direct disbursement.

Implementation requirements:

• record revenue events by project and period
• compute the labor platform split:
  • one third by total contribution points
  • one third by contribution points for the revenue-earning project
  • one third reserved for budget, expenses, and future development
• produce an admin-reviewed RevenueShareBatch or equivalent payout proposal artifact
• keep every line item explainable from the underlying point ledgers and revenue event inputs

Recommended Delivery Phases

Phase 0: Deployable Foundation

Goal: make the current slice safe to stand up on Yggdrasil as a private environment.

Deliver:

• initial migrations
• bootstrap seed path for first admin and baseline data
• config validation for OAuth, database, and host settings
• health endpoint and startup checks
• structured logging
• deployment runbook plus nginx and systemd config in gamecult-ops
• backup and restore runbook

Exit criteria:

• clean host can provision database, apply migrations, start the app, and survive restart
• private staging deployment works behind nginx

Phase 1: Member Alpha Core

Goal: make invite-only member operations actually usable.

Deliver:

• full member profile fields
• explicit role management
• GitHub App integration and issue or pull request sync
• work item lifecycle with deadlines and review state
• membership and audit admin pages
• better authorization coverage and test depth

Exit criteria:

• invited members can sign in, browse work, volunteer, be assigned, and participate in motions
• admins can review membership and core platform activity

Phase 2: Labor And Points Engine

Goal: encode the labor model itself.

Deliver:

• point transaction ledger model
• contributor point award rules
• continuous role accounting
• patron support history and patron point calculation
• Reddit account linking for discussion attribution, without using Reddit karma or upvotes as patron voting weight
• weekly decay job
• tier snapshots and effective voting weight calculation from tier state

Exit criteria:

• every effective point balance can be reconstructed from ledger events
• point changes are auditable and test-covered

Phase 3: Governance And Revenue Share

Goal: turn Bifrost into the real internal operating layer.

Deliver:

• management and project motion templates
• category-specific thresholds
• revenue event ingestion
• revenue share calculation
• payout proposal batch generation
• member-facing statements explaining how shares were derived

Exit criteria:

• governance and payout recommendation flows can run without resorting to external spreadsheets

Phase 4: Continuous Care Work And Refinement

Goal: support real organizational labor that does not map cleanly to single tickets.

Deliver:

• recurring role assignments
• periodic care-work credits
• better dashboards and reporting
• exception handling for disputes, reversals, and manual corrections

Exit criteria:

• maintainers, producers, community, and social labor are accounted for without pretending only GitHub tickets matter

Domain Additions To Plan For

The current domain is a good start, but the following models should be expected:

• WorkItemCategory
• WorkReview
• WorkCompletion
• PrioritySignal
• RewardAllocation
• CompletionArtifact
• PointTransaction
• PointBalanceSnapshot
• PatronSupportEvent
• DecayRun
• TierSnapshot
• RevenueEvent
• RevenueShareBatch
• RevenueShareLine
• RoleAssignment
• RoleContributionWindow

Deploy Decision

The current recommendation is:

• do not deploy publicly yet
• do deploy to a private or admin-only staging environment after Phase 0 work is complete
• treat public or member-alpha rollout as gated on Phase 1 plus the core parts of Phase 2

That keeps the rollout honest. We can stand something up on Yggdrasil soon, but it should be a controlled internal environment until the labor and accounting rules are implemented well enough to trust.