Agency/docs/decisions/008-platform-weight-governance.md

# ADR 008 — Platform weight governance

**Date:** 2026-05-14
**Status:** Proposed

---

## Context

[ADR 002](002-weighted-scoring.md) establishes that platform weights are configurable values
in `config.yaml`. [ADR 005](005-git-native-voting-system.md) establishes that governance
proposals — including weight changes — use equal-weight voting above a participation threshold.

What neither ADR defines is *how* weight decisions are made: who proposes them, how often,
by what mechanism, and what distinguishes a routine adjustment from a structural change.

Left unresolved, this defaults to individual contributors opening PRs against `config.yaml`
— which reintroduces individual authority over the values that determine community standing.
That is precisely the capture risk ADR 005 was designed to prevent.

---

## Decision

**Platform weights are determined by periodic community votes using averaged proposals,
not by individual contributors opening PRs. No maintainer sets or overrides weights.**

Three tiers of weight-related decision are defined, each with a distinct mechanism:

| Tier | Scope | Mechanism |
|---|---|---|
| Founding | Initial weights before live scores exist | Averaged proposals, initiator-defined eligibility |
| Routine adjustment | Shifting weights among existing platforms | Annual averaged proposals, participation threshold |
| Structural change | Adding/removing platforms, changing the mechanism | Higher quorum, supermajority |

---

## Why other approaches were rejected

**Maintainer-set weights**
The obvious default. One person or a small group decides what participation means. This is
how most scoring systems work and how most of them get captured — weights drift toward
whatever the maintainers value, regardless of what the community values. Rejected as
inconsistent with the project's core premise.

**Per-proposal binary votes**
A contributor opens a PR proposing a specific weight change; the community votes yes or no.
This is the standard governance PR flow and is already defined in ADR 005 for structural
changes. But for weight adjustments it has a problem: it anchors the vote on a single
proposer's preferred outcome. Strategic proposers can shade their proposal knowing the
alternative is the status quo. Binary votes also produce winner-takes-all results that
ignore the full distribution of community preferences.

**Continuous open voting**
Weights are always open for adjustment; any member can submit a revised preference at any
time; the live average is the current weight. Too unstable — weights would shift
unpredictably as participation patterns change throughout the year, making it impossible for
contributors to understand the rules they are operating under.

**Lazy consensus (silence = approval)**
Proposal posted, passes unless N people actively object within a window. Low friction, but
weights are the most consequential thing Agency does — they determine who has standing.
Letting that drift via inattention is a legitimacy problem. Someone who missed the window
would rightly say they never consented to a change that affects their score.

---

## Founding vote

Before live scores exist, no contributor meets the routine eligibility criteria. A founding
vote is required to establish initial weights.

**Initiator role**
The person deploying Agency for a community defines the founding eligible set: who can
participate in the founding vote. This is explicitly the initiator's decision — there is
no community yet to delegate it to. The initiator's choice must be committed to the repo
as a named, dated file before the vote opens. It is transparent, not hidden.

The goal is to involve as many community members as possible. The initiator should
cast the net wide — the founding vote is more legitimate the more of the community it
reflects. The initiator defines the quorum floor (minimum number of participants required
for the vote to be valid) appropriate for their community's size and context.

**Mechanism**
Each eligible founding member submits a proposed weight distribution: a set of percentages,
one per platform, summing to 100%. Submissions are anonymous (ring signatures per ADR 005).
The founding weights are the **median** of all submitted distributions, computed per platform.

**Initiator power is self-terminating**
The initiator controls eligibility only. They have no influence over the outcome — the
median of submissions determines the weights regardless of the initiator's own preferences.
Once the founding vote closes and live scores begin accumulating, initiator authority over
eligibility expires. Future weight votes use the routine mechanism.

The founding vote's first act may amend any of the founding parameters (eligibility
criteria, quorum floor, vote frequency) for future votes. The founding itself is
explicitly provisional.

---

## Routine weight adjustment

**Schedule**
Weight adjustment votes are held on a fixed annual schedule, not triggered by individual
proposals. A community deploying Agency commits to a vote date in `config.yaml` at founding.
An early vote may be called if a significant structural event warrants it (platform added,
platform collapsed, major community growth), but only through the structural change process
below — not by individual initiative.

**All platforms simultaneously**
Every platform is voted on in the same vote. This forces voters to reason in tradeoffs —
weights must sum to 100%, so increasing one platform requires decreasing others. Per-platform
votes in isolation invite maximalism; simultaneous distribution votes produce genuine
preference expression.

**Eligibility**
Any community member whose participation score exceeds the configured threshold and meets
the multi-platform and tenure criteria from ADR 005 may vote. Eligibility is snapshotted
at vote open; score changes during the voting period do not affect eligibility.

**Mechanism**
Each eligible voter submits a proposed weight distribution summing to 100%. Submissions are
anonymous (ring signatures per ADR 005). The new weights are the **median** of all submitted
distributions, computed per platform. The median is used rather than the mean to limit the
influence of outlier submissions.

**Quorum**
A minimum number of eligible members must submit for the result to be valid. The default
is the greater of 5 or 20% of eligible members. Communities may configure a higher floor.
If quorum is not met, weights remain unchanged and a new vote opens within 30 days.

**Phase-in**
New weights take effect on a 30-day linear transition from old to new. This prevents abrupt
score discontinuities for contributors whose standing straddles a vote boundary.

---

## Structural changes

The following are structural changes, not routine adjustments, and require a distinct process:

- Adding a new platform to the scoring system
- Removing a platform entirely
- Changing the vote mechanism (this ADR) or scoring formula (ADR 002)
- Changing who is eligible to vote or how eligibility is calculated
- Changing the vote schedule or quorum floor

Structural changes use the standard governance proposal process from ADR 005:
- Minimum 14-day discussion period before voting opens
- Quorum: at least 33% of eligible members must vote
- Passage: supermajority (67%) of votes cast

A weight percentage change is not a structural change, even if the magnitude is large.
The mechanism, not the magnitude, determines the tier.

---

## Relationship to ADR 005

ADR 005 defines the cryptographic mechanism (ring signatures), the vote lifecycle (proposal
→ snapshot → submission → tally → result), and the distinction between governance proposals
(equal-weight) and general proposals (score-weighted).

This ADR defines what weight governance proposals look like specifically: continuous
distributions rather than binary choices, median aggregation rather than vote counting,
periodic rather than ad-hoc. The cryptographic mechanism and git lifecycle from ADR 005
apply unchanged.

---

## Consequences

- `config.yaml` may not be edited directly to change platform weights; changes must go
  through the founding or routine vote process
- The vote tooling in `src/voting/` must support distribution submission and median
  aggregation in addition to binary yes/no tallying
- Communities must commit a vote schedule and founding parameters to `config.yaml` before
  the first vote opens
- The founding file (eligible members, quorum floor, date) must be committed to the repo
  and clearly labeled as a bootstrap artifact that expires once live scores are available
- ADR 005's bootstrap problem section describes how to derive the founding eligible set from
  existing community signals; this ADR defers to that approach