Finalize ConfigKit design and implementation plan

docs/adr/0001-separate-composition-and-overlay.md

@@ -0,0 +1,37 @@
+# ADR 0001: Separate Composition and Overlay
+
+## Status
+
+Accepted. This records a design decision, not implementation completion.
+
+## Date
+
+2026-09-06
+
+## Context
+
+Configuration fragments allow independent parts of an application to contribute
+settings. Treating every file as a precedence layer makes accidental duplicates
+silently depend on file order. Profiles, however, need intentional replacement.
+
+## Decision
+
+Use distinct strict-composition and intentional-overlay operations. Composition
+rejects conflicting definitions; overlay provides explicit precedence. Keep the
+operations opinionated rather than adding arbitrary per-field merge strategies.
+The [architecture policy](../policy/architecture.md) owns the governing boundary;
+the [target design](../roadmap/initial.md#composition-and-overlay) owns the planned
+operation table until its current contract lands.
+
+## Alternatives considered
+
+- Last-wins loading for all files: convenient but conceals accidental conflicts.
+- Strict loading for every layer: catches conflicts but cannot express profiles.
+- User-defined merge policies: flexible but weakens consistency and expands the API.
+
+## Consequences
+
+Consumers must distinguish modular contributions from intentional overrides.
+Diagnostics need both conflicting sources. File order remains useful for stable
+traversal and reporting but cannot silently authorize replacement. Named mappings
+are the natural representation for independently contributed entries.