Finalize ConfigKit design and implementation plan

docs/adr/0002-own-yaml-semantics.md

@@ -0,0 +1,38 @@
+# ADR 0002: Own YAML Semantics Behind a Private Parser Boundary
+
+## Status
+
+Accepted. This records a design decision, not implementation completion.
+
+## Date
+
+2026-09-06
+
+## Context
+
+A shared library cannot provide consistent configuration semantics if each
+consumer inherits parser conversions, node types, and extension behavior.
+Exposing parser types also makes dependency changes part of the public API.
+
+## Decision
+
+ConfigKit defines its supported YAML policy and keeps parser integration private.
+Application types and diagnostics must not require parser-specific public types.
+Use a small internal boundary rather than a general parser/provider framework.
+The [architecture policy](../policy/architecture.md) owns this constraint; the
+[target design](../roadmap/initial.md#yaml-and-scalar-policy) owns planned syntax.
+
+## Alternatives considered
+
+- Expose parser nodes and hooks: easy integration but couples consumers to parser
+  behavior and permits bypassing library policy.
+- Adopt the parser's entire YAML behavior: reduces initial code but leaves core
+  semantics outside ConfigKit's control.
+- Abstract many configuration languages immediately: adds unsupported scope.
+
+## Consequences
+
+Parser changes require behavior-level compatibility verification. ConfigKit must
+translate errors safely and enforce its own supported subset. Some existing
+consumer custom decoders will need replacement with library-supported mechanisms
+or application resolution. No particular parser dependency is selected here.