# Devil's Advocate Review — Project Conventions

## Critical rules (must never be violated)

- **Never update `system.stateVersion`** — it must remain at the original installation version. NixOS upgrades are done by updating the `channel` file, not `stateVersion`.
- **Never modify `secrets.yaml` directly** — these are SOPS-encrypted. Changes must be made via `nix-shell -p sops --run 'sops <file>'`.
- **No plaintext secrets in Nix files** — passwords, API keys, tokens, and private keys must use `sops.secrets`, never hardcoded strings.

## Architecture rules

- **Explicit module imports only** — no wildcard or directory-level imports. Each module must be imported by its explicit path.
- **Host structure** — each host in `hosts/<name>/` must have `configuration.nix` and `hardware-configuration.nix`. Symlinks `fleet.nix` and `utils/` point to root level.
- **Shared modules** go in `utils/modules/`, not duplicated across hosts.
- **Custom packages** in `utils/pkgs/` must include an `update.sh` script for automated version updates.

## Code style

- **Two-space indentation** in all Nix files.
- **Lower kebab-case** for file and directory naming.
- **Conventional Commits** format: `fix:`, `feat:`, `chore:`, with optional scope by host (e.g., `fix(mail):`).
- No "Generated with Claude Code" or "Co-Authored-By: Claude" footers in commits.

## Common review checks

- New network services must have corresponding `networking.firewall.allowedTCPPorts` or `allowedUDPPorts` entries.
- New `sops.secrets.<name>` references must have a corresponding entry in the host's `secrets.yaml` (or the relevant module's `secrets.yaml`).
- Changes to `utils/` affect all hosts — verify cross-host compatibility.
- Package modifications should be testable with a direct `nix-build`, not just `test-configuration`.