From b9f41d698e5bdfbc0bb7e1cc61104517774a0764 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Mon, 2 Nov 2026 00:30:59 +0000
Subject: [PATCH] Record document-root configuration control decision

---
 docs/adr/0011-input-destinations.md     |  3 ++
 docs/adr/0020-document-root-controls.md | 60 +++++++++++++++++++++++++
 docs/roadmap/implementation.md          |  2 +
 3 files changed, 65 insertions(+)
 create mode 100644 docs/adr/0020-document-root-controls.md

diff --git a/docs/adr/0011-input-destinations.md b/docs/adr/0011-input-destinations.md
index c56d786..a09437c 100644
--- a/docs/adr/0011-input-destinations.md
+++ b/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
diff --git a/docs/adr/0020-document-root-controls.md b/docs/adr/0020-document-root-controls.md
new file mode 100644
index 0000000..8a75fac
--- /dev/null
+++ b/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.
diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md
index 8a4155e..def4031 100644
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -43,6 +43,8 @@ renaming its input while retaining the old rejection is not sufficient.
 
 ## Stage 1 — Record the agreed architectural boundary
 
+**Status:** Complete.
+
 **Scope:** one decision record, without changing current-behavior documentation.
 
 1. Create `docs/adr/0020-document-root-controls.md`, using the repository's ADR