secrets-and-config ยท diff

git:20261018.dcbc4f7 to git:20261024.f18ae25

17 added, 3 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: secrets-and-config
description: Use when changing application configuration, environment variables, SOPS secret files, or generated development environments. Keeps each value in one documented owner.
---
# Secrets and configuration
- A value is secret when disclosure enables impersonation, data access, or cost. Keep secrets only in SOPS-encrypted YAML and other values in plain configuration beside their consumer.
+ A value is secret when disclosing it enables impersonation, data access, or cost. Secrets live only in SOPS-encrypted YAML. Every other value lives in plain configuration beside the code that reads it.
- Explain each value once: plain values in their configuration, secrets in the matching `*.example.yaml`, which mirrors the encrypted target's key shape. State purpose and requiredness, plus any default or behavior its consumer does not make obvious. Use workspace READMEs only for setup those declarations cannot express.
+ Document each value once, where it is declared. A plain value is explained in its configuration file. A secret is explained in the matching `*.example.yaml`, which mirrors the key shape of the encrypted file, because the encrypted file cannot carry readable comments. Use a workspace README only for setup that these declarations cannot express.
- Development environments have three workspace-keyed layers: tracked `config/dev.yaml`, encrypted `secrets/dev.yaml`, and gitignored `config/dev.local.yaml` overrides. A key cannot live in both tracked layers. Generate `.env.local` with `bun standards dev-env`; never edit it directly.
+ SOPS identities, recipients, CI secrets, and brokered provider credentials are covered in the declarative-infra skill's [secrets reference](../declarative-infra/references/secrets.md).
+
+ ## Development environments
+
+ `just dev-env-generate` (`bun standards dev-env`) generates each workspace's `.env.local` from three layers, keyed by workspace (`apps.<name>`, `packages.<name>`). `just dev-refresh` edits the dev secrets and then regenerates.
+
+ | Layer | File | Notes |
+ | --- | --- | --- |
+ | Plain | `config/dev.yaml` | Tracked |
+ | Secret | `secrets/dev.yaml` | Tracked and encrypted; values are strings |
+ | Local | `config/dev.local.yaml` | Gitignored; overrides both tracked layers, including secret values |
+
+ A key lives in at most one of the two tracked layers. Local changes belong in `config/dev.local.yaml`, because generation rewrites the whole `.env.local`.
+
+ A plain layer can reference one half of a broker-owned S3 credential pair instead of copying it, so the value never goes stale after the broker rotates it: `{ brokeredS3: <target>, key: <dotted.key>, part: access_key_id | secret_access_key }`. The reference resolves only when encrypted `secrets/dev.yaml` authorizes that pair in its reserved top-level `brokeredReferences` list as `<target>:<dotted.key>`.