Plan ConfigKit adoption in five stages

docs/roadmap/configkit.md

@@ -4,7 +4,8 @@
 
 **Status:** Planned; implementation has not begun. The dependency-only review
 passed Audita's existing offline test suite in a disposable checkout. That is
-baseline compatibility evidence, not completion of the feature work below.
+baseline compatibility evidence, not completion of the feature. The
+[implementation plan](implementation.md) owns the ordered work and verification.
 
 ## Purpose and Baseline
 
@@ -37,10 +38,10 @@ and release target do not govern this incremental upgrade.
 
 - Audita uses the released ConfigKit v0.5.0 module, with no local replacement.
   PromptKit stays at v0.11.2 throughout this adoption unit.
-- Existing configurations continue through the current file-selection,
-  overlay, explicit-override, resolution, and validation flow. Retain the
-  application schema version, CLI interface, and main-file-relative resource
-  rules defined in the current contracts.
+- Configuration retains the current file-selection, overlay, explicit-override,
+  resolution, and validation flow, subject to the reserved-key compatibility
+  impact described below. Retain the application schema version, CLI interface,
+  and main-file-relative resource rules defined in the current contracts.
 - Application configuration can use ConfigKit's native sibling `extends`
   relationships. Audita does not implement a second inheritance resolver,
   special backend-only syntax, or an opt-in switch around the library feature.
@@ -64,7 +65,7 @@ value still has to satisfy Audita's field-specific rules. Parent definitions
 also undergo ordinary application validation; inheritance does not introduce
 abstract, validation-exempt backend entries.
 
-## Scope and Sequencing
+## Scope and Adoption Boundary
 
 Keep the existing `Load` integration unless implementation reveals a concrete
 need to change it. Source-backed defaults, additional operator underlay tiers,
@@ -78,96 +79,28 @@ profile formats, profile inheritance, engine construction, embedded prompts,
 and backend catalogs remain governed by the existing PromptKit integration.
 There is no application-owned translation of profile documents in this work.
 
-Complete and validate ConfigKit adoption before migrating PromptKit. PromptKit
-v0.12.0 itself requires ConfigKit v0.5.0; this sequence isolates the generic
-configuration change from the later API and profile-format migration. Each
-completed adoption unit should build and pass its applicable checks. A separate
-public release between the two units is optional, not a prerequisite.
+This is an independent ConfigKit adoption ahead of the planned PromptKit
+migration. A separate public release between the two units is optional.
 
-## Work Plan
+## Acceptance Criteria
 
-### 1. Upgrade the Dependency
-
-Update `go.mod` and `go.sum` to the released ConfigKit version. Review the
-resolved dependency diff to keep PromptKit and its catalogs at their current
-versions. Retain the existing Go minimum and other YAML dependencies used by
-Audita.
-
-Check the production loader against the new presence and inheritance semantics.
-Make only changes needed to preserve the target behavior; do not replace the
-loader simply to exercise the new layered API.
-
-### 2. Verify Inheritance at Audita's Boundary
-
-Review existing configuration tests and add focused coverage for integration
-risks not already protected:
-
-- A child backend inherits endpoint, capacity, and a credential reference while
-  retaining its own explicit overrides. Derived defaults respect inherited
-  presence, including an explicitly inherited zero queue capacity.
-- Selected overlays and explicit flags reach the final configuration under
-  ConfigKit's precedence rules. Omitted validation-role selection still derives
-  from the final proposal-role selection, while explicit invalid values fail
-  Audita's validation.
-- Surviving inherited credentials resolve and redact correctly. Null removes a
-  child's reference according to the existing credential contract; a surviving
-  reference on the parent remains subject to validation even if that backend is
-  not selected for a role.
-- A representative invalid relationship produces a configuration failure at
-  the CLI boundary. Reuse upstream coverage for the full generic inheritance
-  grammar rather than duplicating its cycle, nesting, and expansion test suite.
-
-Use synthetic credentials and real ConfigKit loading. Keep domain validation
-in Audita; inherited invalid settings must not become valid solely because the
-library successfully assembled them.
-
-### 3. Preserve Inspection and Runtime Wiring
-
-Check effective settings, explanation output, and diagnostic configuration
-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
-capacity. Reuse existing integration coverage where it already proves these
-properties; do not duplicate the full PromptKit runtime test matrix.
-
-### 4. Update Documentation, Examples, and Attribution
-
-When implementation lands, update [configuration](../config.md) with the
-reserved keyword, inheritance behavior, presence/default interactions, and
-credential implications. Link to upstream for the generic grammar. Update
-[configuration change recipes](../internal/cli-config.md) where contributor
-steps change, and the [CLI reference](../cli.md) only if its documented
-inspection behavior needs clarification.
-
-Add a small, complete inheritance example under [examples](../../examples/)
-using valid parent and child backends and existing PromptKit profile syntax.
-Validate it offline, alongside the maintained local, service, and testing-overlay
-examples, following the existing example-validation recipe.
-
-Check the selected release's license and notice files and update the ConfigKit
-entry in [attribution](../oss/attribution.md), including its commit-pinned source
-and notice links, under the [OSS policy](../policy/oss.md). The review found no
-change to ConfigKit's license or dependency declarations; verify the selected
-artifacts when making the dependency change.
-
-### 5. Validate and Close the Adoption Unit
-
-Run targeted configuration and CLI checks, then the normal build and complete
-offline test suite described in [development](../development.md). Validate
-changed examples and documentation links and run `git diff --check`. No live
-provider, paid model call, or new permanent release gate is needed.
-
-Record validation against the actual implementation revision and mark this
-roadmap complete only after the criteria below are met. The earlier disposable
-checkout result establishes that the unmodified suite passed with ConfigKit
-v0.5.0 and PromptKit v0.11.2; it does not cover newly documented inheritance
-workflows or substitute for final validation.
+- The released ConfigKit v0.5.0 dependency and exact source attribution are
+  adopted; PromptKit remains at v0.11.2 with its existing catalogs.
+- Native inheritance preserves effective endpoints, capacity, explicit zero
+  queue capacity, child overrides, and surviving credential references through
+  Audita's loading, resolution, and validation boundary.
+- Selected overlays and explicit overrides retain their precedence; omitted
+  validation-role selection still derives from the final proposal selection.
+- Null can remove a child's credential while surviving references on parents
+  and other unselected backends still follow the existing credential contract.
+- Selected roles use inherited backend settings and share its configured
+  capacity under the existing PromptKit runtime contract.
+- Effective settings remain redacted, and both CLI explanations and debug
+  configuration origins expose compact, value-free inheritance evidence while
+  retaining existing fields and application-derived explanations.
+- A maintained complete example and canonical documentation describe native
+  inheritance, its field-validation implications, and the reserved-key
+  compatibility impact. Existing workflows and applicable offline checks pass.
 
 ## Completion and Release Treatment