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.