---
id: BB-SPEC-579A27BC
type: spec
title: Repository operating contract
research:
  - BB-RESEARCH-4D80C31E
---

# Repository operating contract

## Tools

Use OpenTofu through `tofu`, never `terraform`.
Use `just` for repository tasks and lefthook for Git hooks.
Do not install or upgrade providers unless the change explicitly requires it.

## Infrastructure workflow

Before an infrastructure change:

1. inspect root modules, affected klops modules, variables, providers, templates, and deployment scripts;
2. make the smallest coherent change;
3. run `tofu fmt -recursive`;
4. run `tofu validate`;
5. validate affected Caddy and rendered Quadlet configuration;
6. create and review a `tofu plan`;
7. apply only the reviewed saved plan.

`tofu apply` executes remote klops deployment and can restart services.
Validation alone is not deployment acceptance.

`just check` mutates formatting.
Use `tofu fmt -check -recursive`, `tofu validate`, and `caddy fmt --diff` for read-only validation.
The current direct-directory CI Quadlet check does not validate the generated Luci Quadlet.

## OpenTofu conventions

Use two-space canonical formatting and `snake_case` names.
Every variable and output has an explicit type and description.
Use precise types rather than `any`.
Set `nullable = false` when null is not handled.
Secret inputs are marked sensitive.
Use relative local modules and pinned external revisions.
Keep provider constraints deliberate and lock-file changes explicit.

## Secrets and state

Never commit secret values, variable-value files, state, state backups, saved plans, or generated sensitive files.
State may contain plaintext secrets.
Sensitive marking affects display, not storage.
Use operator environment or ignored variable-value files for credentials.

## Verification by surface

Luci changes run the complete Go test suite under `services/luci` plus affected packaged and deployment checks.
Public-site changes run the real Chrome verifier at desktop and mobile viewports.
Nugu assets are regenerated with `just nugu`; generated palette files are not hand-edited.

Do not claim a check passed unless its complete fresh result was read.
Do not claim a revision is deployed without live deployment evidence.