Record document-root configuration control decision

docs/adr/0011-input-destinations.md

@@ -10,6 +10,9 @@ request, and review records are preserved at `e4270c9` under `docs/roadmap/` in
 Git history; the original input-destination implementation plan remains at
 `315f464:docs/roadmap/implementation.md`.
 
+[ADR 0020](0020-document-root-controls.md) amends the scope of the control-name
+reservation. The other placement decisions in this record remain in force.
+
 ## Date
 
 2026-10-14

docs/adr/0020-document-root-controls.md

@@ -0,0 +1,60 @@
+# ADR 0020: Scope Configuration Controls to Document Roots
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-11-01
+
+## Context
+
+ConfigKit interprets configuration controls during source acquisition, before
+placing and composing source payloads. Reserving the control name throughout
+application data restricts paths unrelated to source-document controls. The
+source-local position of a control and the effective application path of a
+value are different coordinates, even when their path text is identical.
+
+## Decision
+
+Use `config` as the single control mapping name at the root of each acquired
+source document. Interpret each source's controls before placing its payload,
+using the existing context-specific grammar and import opt-in. A source retains
+its own document root regardless of its eventual destination, including when
+mounted below another value or as a sequence record.
+
+Below a source root, `config` is ordinary application data, including in
+sequence records and selected overlays. Control-looking children in such data
+do not activate controls. Application-root `config` data produced by placement,
+defaults, CLI assignment, or resolution is also ordinary data. Placement and
+later lifecycle operations do not create another source-document parsing pass.
+
+The former spellings `configkit` and `_configkit` are ordinary application keys
+at any depth, subject to normal schema and structural rules; they are not
+control aliases. Source-version checks protect actual source-local controls,
+not an application path merely because its spelling matches. Existing `extends`
+inheritance semantics and restrictions remain in force.
+
+## Alternatives Considered
+
+- **Reserve the control name throughout application data.** This conflates
+  source-document syntax with application paths and prevents ordinary fields
+  unrelated to control interpretation.
+- **Recognize controls again after placement or later operations.** This makes
+  application data acquire control semantics according to its destination and
+  introduces a second interpretation pass.
+- **Support multiple or configurable control spellings.** This makes control
+  interpretation ambiguous and expands the configuration contract.
+
+## Consequences
+
+Control evidence uses source-local coordinates while assembled values use
+application coordinates. Existing source identities and contexts distinguish
+these uses without a new inspection-record format. Consumers must migrate
+genuine old control blocks and account for source-root application fields
+named `config`; ordinary nested and assembled root fields remain available.
+
+The [feature roadmap](../roadmap/config-directives.md) records the target and
+the [implementation plan](../roadmap/implementation.md) tracks its progress.
+The [configuration contract](../config.md) owns implemented behavior.