From 2023c91ec3f31e4ccb1a511b5f1b254982c311b6 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Sat, 3 Oct 2026 16:50:57 +0000
Subject: [PATCH] Clarify ConfigKit inheritance evidence and compatibility

---
 docs/roadmap/configkit.md | 39 ++++++++++++++++++++++++---------------
 1 file changed, 24 insertions(+), 15 deletions(-)

diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md
index c29309e..eec875d 100644
--- a/docs/roadmap/configkit.md
+++ b/docs/roadmap/configkit.md
@@ -49,8 +49,9 @@ and release target do not govern this incremental upgrade.
   In particular, inherited backend settings must not be overwritten merely
   because they were not written directly on the child.
 - Effective settings and explanations remain useful and secret-safe when
-  values are inherited. Preserve the existing Audita-owned inspection formats;
-  use ConfigKit's metadata rather than reconstructing provenance from YAML.
+  values are inherited. Preserve existing inspection fields and add compact,
+  value-free inheritance evidence from ConfigKit's metadata rather than
+  reconstructing provenance from YAML.
 - Canonical documentation and a maintained example explain the adopted
   inheritance behavior. Attribution identifies the exact new upstream source.
 
@@ -123,9 +124,12 @@ library successfully assembled them.
 ### 3. Preserve Inspection and Runtime Wiring
 
 Check effective settings, explanation output, and diagnostic configuration
-snapshots with inherited values. Inspect whether existing source and derivation
-mapping retains useful inheritance evidence; make narrow mapping changes if
-needed without exposing resolved secrets or adding an unrelated inspection API.
+snapshots with inherited values. Audita's current `ExplanationYAML` exposes
+source/layer information and application-derived defaults but does not expose
+ConfigKit's `Origin.Inheritance` evidence. Extend that projection with a compact,
+value-free explanation of inheritance, retaining existing fields and secret
+redaction. This is an explicit adoption deliverable; use upstream metadata
+without reconstructing ancestry from YAML or adding an unrelated inspection API.
 
 Use a representative controlled-provider workflow to verify that selected roles
 receive the inherited backend endpoint and credential and share its configured
@@ -169,17 +173,22 @@ workflows or substitute for final validation.
 
 Adoption is complete when the released dependency is pinned, existing workflows
 pass, representative inheritance works through loading and runtime wiring,
-inspection remains secret-safe, and the example, canonical docs, and attribution
-match the implementation. No PromptKit migration or provider behavior change is
-required to close this unit.
+inspection includes value-free inheritance evidence and remains secret-safe,
+and the example, canonical docs, and attribution match the implementation. No
+PromptKit migration or provider behavior change is required to close this unit.
 
-The recommended release treatment is a backward-compatible Audita minor release
-if this unit ships independently: it exposes a new configuration capability
-while preserving currently valid application settings. Confirm that conclusion
-against the final compatibility review, particularly the newly reserved
-`extends` key, under the [release policy](../policy/release.md). Do not select or
-publish a release as part of roadmap preparation. A later PromptKit migration's
-profile-format compatibility decision belongs to that separate feature.
+Release classification remains provisional. A minor release would be appropriate
+for a backward-compatible addition, but the newly reserved `extends` key can
+invalidate currently valid application configuration. For example, Audita
+currently permits a backend literally named `extends`; ConfigKit v0.5.0 treats
+that mapping key as an inheritance directive rather than a backend ID. Do not
+promise blanket compatibility or settle on a minor release until the final
+compatibility review resolves this impact under the
+[release policy](../policy/release.md). Describe any required migration in the
+canonical documentation and release notes when the upgrade ships. Do not select
+or publish a release as part of roadmap preparation. A later PromptKit
+migration's profile-format compatibility decision belongs to that separate
+feature.
 
 ## Selected Overlays for Testing