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.
validate affected Caddy and rendered Quadlet configuration;
create and review a tofu plan;
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.
---
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.