Docs/Concepts/Governance principles

Governance principles

Measurement changes behavior. Bill-y is designed on the assumption that a measurement system for AI-assisted engineering will be gamed, feared, or abused unless the design makes those failure modes structurally difficult. These are the principles, and how each one is enforced.

Facts, never verdicts

Bill-y reports what happened: spend, phases, distributions, rhythms. It does not label developers productive or unproductive, does not rank individuals, and ships no leaderboard. Insight cards state observable facts with their thresholds; the judgment belongs to the humans reading them.

Team-level analytics is a database grant, not a policy

The analytics plane connects to the data store as a role that has access to team-level views only. That role has no rights on the identity tables and no rights on the raw per-record table.

Person-level views exist for legitimate management use, but they are a separately gated module, subject to restriction modes, individually audited, and suppressed for small groups.

Suppression below k

Aggregates over groups smaller than a configurable threshold (suppression-k) are withheld. Small-team aggregates are person-level data wearing a disguise; Bill-y treats them accordingly. The active suppression-k is part of the governance report.

Restriction modes

Organizations choose how much person-level visibility exists at all: none, aggregate_only, anonymous, or own_team_only. The mode is enforced identically for the console, Ask Billy and the MCP tools, so there is no side channel with looser rules.

Every governed read is audited

Any read of usage data writes an audit row: who, in what role, over what scope, with what verdict. Person-level reads and identity reveals are always audited. The audit trail is itself a console view, readable by the auditor role.

The governance report is live, not a brochure

One click in the console produces a report of the deployment's current configuration: retention policy, suppression-k, restriction mode, and the role guardrails. It is generated from the running system, so it supports a data protection impact assessment with facts rather than intentions.

Why this much restraint

Token dashboards have already produced public failures: leaderboards that rewarded volume, gamed metrics, developer backlash. The industry's own guidance has converged on the same conclusion: measure outcomes and distributions at team level, never rank individuals on volume. Bill-y's position is that the restraint has to live in the architecture, because any restraint that lives in a settings page will eventually be turned off.