Finalize the ConfigKit roadmap and implementation plan

docs/adr/0004-secret-references-and-explicit-bootstrap.md

@@ -0,0 +1,43 @@
+# ADR 0004: Use secret references and explicit environment bootstrap
+
+Status: accepted
+
+Date: 2026-09-06
+
+## Context
+
+Consumers need credentials without storing them in YAML and need a consistent
+way to load locally provisioned secret files. WeatherReporter already implements
+useful directory-loading code. Ordinary configuration loading must remain free
+of implicit process mutation, and operators must understand blocked secret files.
+
+## Decision
+
+Represent secrets as ConfigKit-owned typed references to environment-variable
+names. Resolve only surviving references; retain names, never credentials, in
+configuration trees and inspection. Offer directory bootstrap as a separate,
+explicit startup operation, reusing WeatherReporter code where applicable.
+Existing environment variables win even when empty. Report skipped files and
+partial failures without values. Keep bootstrap provenance separate from later
+lookup provenance rather than imply an unchanged environment between calls.
+General environment-variable configuration overlays are not on the roadmap.
+The [feature roadmap](../roadmap/initial.md#secret-references-and-explicit-bootstrap)
+owns the unimplemented contract; stages remain in the implementation plan.
+
+## Alternatives considered
+
+- Literal secrets or interpolated YAML: familiar but allows credentials into
+  configuration artifacts and expands conventions and redaction obligations.
+- Application-only directory loaders: keeps process mutation outside the library
+  but preserves duplicated infrastructure and inconsistent skip/error semantics.
+- Implicit bootstrap during loading: convenient but hides process mutation and
+  makes repeated or concurrent loads difficult to reason about.
+- Directory values overriding existing environment: simple, but defeats explicit
+  deployment environment choices and obscures why a credential was selected.
+
+## Consequences
+
+Applications migrate secret fields, choose startup ordering, and retain bootstrap
+reports. ConfigKit owns bounded loading, reference validation, safe reporting and
+inspection; applications own credential use. No multi-variable transaction or
+protection against concurrent process-environment mutation is promised.