ConfigKit/docs/adr/0005-explicit-overrides-and-safe-explanation.md

ADR 0005: Record explicit CLI overrides and safe value explanation

Status: Partially superseded by ADR 0018 for override-before-decoding ordering. The remaining ownership and safe explanation decisions remain accepted.

Date: 2026-09-06

Context

Consumers need deliberate per-invocation configuration changes and an explanation of effective values. Presence and origin records alone cannot show which values were replaced. Adding CLI parsing or arbitrary environment overlays would broaden the library beyond its consistent configuration model.

Decision

Use parser-neutral explicit path/value/flag records above selected profiles. Defaults remain below strictly composed base input. Apply overrides to the owned node tree before typed decoding, retaining the existing parser adapter boundary. Recorded domain resolution follows input selection. Provide safe structured historical values and an explanation renderer in the initial release, building on ADR 0003's presence and audited resolution decision. Applications own commands. The current override contract and explanation contract own the implemented behavior.

Alternatives considered

• Retire configuration flags in favor of profiles: smaller API, but removes useful explicit invocation choices that fit a single fixed precedence model.
• Mutate structs after loading: easy locally, but bypasses validation and leaves metadata and effective inspection inconsistent.
• Defer historical values: reduces initial implementation scope but cannot answer why an effective value differs from defaults or an earlier file.
• Publish raw history trees: flexible but couples consumers to internals and risks leaking sensitive values. Detached, redacted snapshots preserve the boundary.

Consequences

The library owns override validation and source attribution without choosing a CLI framework. History requires bounded retained state and tests for replacement, deletion, composite origins and sensitivity. Credentials never enter history; secret reference names remain explainable unless explicitly classified sensitive.