ADR 019: Configuration and secret handling policy

This page is generated from docs/decisions/*.yaml by task docs:export-adr-markdown. Do not edit manually.

• Number: 019
• Title: Configuration and secret handling policy
• Category: development
• Status: accepted
• Provenance: guided-ai
• Source: docs/decisions/019-configuration-and-secret-handling-policy.yaml

Decision

Use typed configuration with strict validation and environment-backed secret inputs. Secrets must never be logged or returned in plain text and must be redacted in diagnostics.

Agent Instructions

Validate configuration at startup and fail fast with actionable, non-secret error messages. Keep secret values out of logs, panic output, and CLI JSON payloads. Prefer environment variables or secure stores over checked-in configuration files. A configuration file bb found and could not read is an error that names the file, never an empty configuration, and bb does not rewrite a file it could not read: no command does, and no flag makes it. BB_DISABLE_STORED_CONFIG=1 means the stored file is not read at all.

Rationale

Strong config validation and secret hygiene reduce operational incidents and data exposure risk. This policy aligns local-first development with production-grade safety expectations.

Rejected Alternatives

• Best-effort validation and permissive startup: Delays failures and increases debugging complexity.
• Allow plaintext secret echo for troubleshooting convenience: Unacceptable security risk.