From 5d62ea2df4694f6e040f87176eb47a8386443ff2 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 22 Apr 2026 07:35:54 +0100 Subject: [PATCH] Add aligned implementation strategy --- AGENTS.md | 4 +- README.md | 7 +- docs/bifrost-mvp-plan.md | 13 +- docs/context.md | 6 + docs/full-implementation-strategy.md | 267 +++++++++++++++++++++++++++ 5 files changed, 293 insertions(+), 4 deletions(-) create mode 100644 docs/full-implementation-strategy.md diff --git a/AGENTS.md b/AGENTS.md index 4acc67a..8e36401 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,6 +48,7 @@ - Read existing docs before reopening settled product decisions. - Keep implementation boring where possible; the product idea is ambitious enough already. +- Push changes after every implementation pass. - If a question is about trust, accountability, or payout fairness, prefer auditability over automation. - Before debugging UI/layout, inspect the live DOM and computed styles instead of guessing from templates or CSS intent. @@ -58,7 +59,8 @@ Read these files first: 1. `AGENTS.md` 2. `README.md` 3. `docs/bifrost-mvp-plan.md` -4. `docs/context.md` +4. `docs/full-implementation-strategy.md` +5. `docs/context.md` Then start the first implementation milestone: diff --git a/README.md b/README.md index 86f9209..b325e4a 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ This repository now includes the first implementation slice of the ASP.NET Core - initial member console pages for projects, work items, motions, ledger activity, and member approvals - xUnit integration tests under `tests/Bifrost.Web.Tests` +It is not yet ready for production deployment. The current state is suitable for continued development and, after deploy-foundation work, an internal staging rollout. + ## Chosen Stack - ASP.NET Core 8 LTS @@ -45,6 +47,8 @@ The next build target is to deepen the first implementation milestone by adding: - work item completion and ledger approval flow - payout proposal batch generation and review +For the full staged roadmap, including contribution points, revenue share, patron or contributor decay, and labor-platform alignment, see [docs/full-implementation-strategy.md](E:\Projects\Bifrost\docs\full-implementation-strategy.md). + ## Local Dev Notes - set `GitHubOAuth:ClientId` and `GitHubOAuth:ClientSecret` before using sign-in @@ -59,4 +63,5 @@ Before implementation work starts in a new session, read these files in order: 1. [AGENTS.md](E:\Projects\Bifrost\AGENTS.md) 2. [docs/bifrost-mvp-plan.md](E:\Projects\Bifrost\docs\bifrost-mvp-plan.md) -3. [docs/context.md](E:\Projects\Bifrost\docs\context.md) +3. [docs/full-implementation-strategy.md](E:\Projects\Bifrost\docs\full-implementation-strategy.md) +4. [docs/context.md](E:\Projects\Bifrost\docs\context.md) diff --git a/docs/bifrost-mvp-plan.md b/docs/bifrost-mvp-plan.md index feb156f..659fdf3 100644 --- a/docs/bifrost-mvp-plan.md +++ b/docs/bifrost-mvp-plan.md @@ -7,6 +7,7 @@ - Use ASP.NET Core 8 with Razor Pages + HTMX and PostgreSQL. - Support invite-only GitHub-linked members, GitHub-backed and internal work items, app-native governance, and internal ledgers. - Do not include Ethereum, wallets, DAO mechanics, or payout execution in v1. +- Align the implementation with the labor platform model in `E:\Projects\gamecult-site\GameCult\Docs\labor-platform.md`. ## System Shape @@ -43,6 +44,14 @@ - Compensation is modeled internally, not executed by the platform. - Human approval remains in the loop for governance-sensitive and payout-sensitive steps. +## Labor Platform Alignment + +- Contribution points and patron points are separate systems that both matter to tiering and governance. +- Effective balances decay over time where the labor platform rules call for decay. +- Project-specific contribution points stay distinct from global contribution points. +- Revenue share should be implemented as an internal calculation and review flow, not direct payout execution. +- Continuous care work such as maintainer, producer, and community labor must be accounted for alongside ticket-shaped work. + ## Deployment Assumptions - public hostname: `bifrost.gamecult.org` @@ -80,7 +89,7 @@ Build the minimum vertical slice for: ## Assumptions And Defaults -- Bifrost is docs-only during bootstrap; no app code exists yet. +- Bifrost now has an initial application slice, but it is not yet production-ready for deployment. - v1 optimizes for legibility, auditability, and workflow proof. -- No remote git repo is required during bootstrap. - Future sessions should treat this document and `AGENTS.md` as the durable source of truth for settled decisions. +- The full staged roadmap lives in `docs/full-implementation-strategy.md`. diff --git a/docs/context.md b/docs/context.md index c0cce6c..a1f558a 100644 --- a/docs/context.md +++ b/docs/context.md @@ -9,6 +9,7 @@ GameCult needs a platform that can connect public projects, contributor particip - `E:\Projects\gamecult-site` - public-facing Quartz site for the studio, projects, and docs - source of the Labor Platform concept and public framing + - Bifrost should stay aligned with `GameCult\Docs\labor-platform.md` for points, tiers, decay, revenue share, and workflow shape - `E:\Projects\gamecult-ops` - source of deployment and infrastructure conventions - documents Yggdrasil, nginx, systemd, and local-Postgres patterns @@ -27,6 +28,11 @@ After bootstrap, the next session should start implementing the first vertical s - motions - ledger entries +## Strategy Notes + +- Bifrost now has the first application slice, but it still needs deploy-foundation work before it should go live on Yggdrasil. +- The full implementation roadmap, including contribution points, patron points, decay, and revenue share, is documented in `docs/full-implementation-strategy.md`. + ## Product Defaults - member alpha first diff --git a/docs/full-implementation-strategy.md b/docs/full-implementation-strategy.md new file mode 100644 index 0000000..30edc70 --- /dev/null +++ b/docs/full-implementation-strategy.md @@ -0,0 +1,267 @@ +# 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, 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 scaffold +- PostgreSQL-backed EF Core model +- GitHub OAuth wiring +- invite and approval gate +- project, work item, motion, member, and ledger UI +- basic integration tests + +### What Is Still Missing Before Deployment + +- initial EF Core migrations and a repeatable database bootstrap path +- production config validation, secrets handling guidance, and startup failure checks +- GitHub App integration, webhook ingestion, and issue or pull request sync +- health checks, structured logging, and deployment smoke tests +- nginx and systemd deployment artifacts or matching runbooks in `gamecult-ops` +- backup and restore instructions for PostgreSQL and app secrets +- role and permission hardening beyond the initial admin flags +- production-safe ledger workflow, payout proposal generation, and approval gates +- contribution point rules, patron point rules, 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 GitHub sign-in only for Bifrost v1 even though the concept doc allows GitHub or GameCult accounts +- 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 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 +- volunteer, assignment, review, completion, and approval transitions +- 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% + +### 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 should be derived from support events and support state, not edited freehand as a main workflow. + +Implementation requirements: + +- store recurring support state and historical donation events separately +- calculate patron points from current recurring support plus historical donations +- apply the concept-doc rule that historical donations are halved after one month and then continue decaying +- expose both raw support history and current effective patron points + +### 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 +- 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` +- `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.