commandkit/docs/roadmap/configkit-v1.1.0.md

ConfigKit v1.1.0 adoption

Status: adoption scope selected; implementation has not begun. This roadmap defines the embedded ckconfig dependency and source-report target. Selected scope decisions distinguish adoption from deferred extensions. The implementation plan owns stage order, concrete changes, and validation steps.

Purpose and authority

Adopt go.maximumdirect.net/configkit v1.1.0 and expose its capabilities through CommandKit's existing configuration commands in a neutral, consistent way. ConfigKit owns configuration loading, composition, resolution, inspection, and their semantics. CommandKit owns command selection, coordination, presentation, and invocation outcomes. Adapt upstream capabilities faithfully, using current upstream terminology, without adding independent guarantees or commentary qualifying upstream limitations.

This follows the clarified integration goal and the existing architecture policy. The agent, testing, documentation, release, and OSS policies govern implementation. This roadmap records the selected target; current contracts remain in GoDoc, the CLI reference, and the consumer guide until implementation lands.

Current baseline and review evidence

Initial review revision: 60841227b7e2928d3fefd3326f0e3f4694f41e6d. API coverage follow-up revision: 7a9e3a1f7cdd0475f06a63ce0aababefe08651bc; library code and module selections are unchanged between these revisions. The completed dependency alignment roadmap records the preceding vanity migration and releases.

Component	Current selection
Core	go.maximumdirect.net/commandkit v0.3.0; Go 1.26.0 minimum
ckconfig	go.maximumdirect.net/ckconfig v0.2.0; Go 1.26.0 minimum
ckconfig dependencies	Core v0.3.0, gitea.maximumdirect.net/eric/ConfigKit v0.8.0, YAML v4.0.0-rc.6
ckprompt	v0.2.0; ckconfig v0.2.0, old-path ConfigKit v0.8.0 and PromptKit v0.16.0; Go 1.26.0 minimum
Maintainer release toolchain	Go 1.26.8, with GOTOOLCHAIN=local

The ConfigKit vanity endpoint and direct Go module discovery resolve v1.1.0 to published commit 191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9. Its module declares Go 1.27.0 and retains the YAML dependency and LGPL-3.0-or-later library grant. The upstream v1.0 migration notes and v1.1 release notes describe the adopted API and behavior changes. Upgrading from v0.8.0 also crosses the import, collection, CLI-assignment, and discovery changes documented in the v0.9 notes and v0.10 notes.

A disposable ckconfig copy passed its complete module suite and maintained simple example tests on Go 1.27.0 after changing the dependency/import path, minimum, two source-reader fields, and affected test APIs. This establishes that the existing adapter structure remains suitable. It did not exercise the proposed report-field renames, additional source evidence, or a migrated ckprompt; final implementation still needs validation of those selected changes.

API coverage findings

The follow-up compared the public API of the pinned v1.1.0 module with ckconfig's provider facets, adapters, and report projections. These are gaps in current integration coverage, not necessarily APIs newly introduced in v1.1.0.

Capability	Current ckconfig exposure	Recommendation
SourceInfo.EmptyImportSelections	Omitted from the source report.	Include in adoption; OD-2.
Result.Metadata(), Metadata.Lookup, and IsExplicit	No metadata facet in View; explanation reports do not expose explicit input presence.	Prioritize optional field-metadata inspection as the next functional expansion; OD-3.
Metadata.HistoricalPaths and History	Operators must already know a path to request an explanation; metadata history records are not exposed.	Pair path discovery and provenance history with metadata inspection; OD-3.
LoadError.Sources() and Source(id)	Acquired sources support diagnostic context, but config sources returns before reporting an inventory on acquisition failure.	Consider failed-load source inspection separately; OD-4.
Full Difference records	The Go comparison provider returns native records; the CLI reduces them to additions, right-side changes, and deletion paths.	Consider an additional detailed comparison report; OD-5.
Structured Diagnostic records	Native writers present diagnostic content; there is no structured native diagnostic report.	Lower-priority candidate, coordinated with shared reporting; OD-6.

The upstream metadata API, source and diagnostic records, load-error API, and comparison API own the returned evidence and its semantics.

The current explanation projection covers every field of v1.1.0's Explanation: effective and historical snapshots, origin and inheritance, reasons, dependencies, and secret-reference names. Improved list-history behavior can flow through that existing adapter. Metadata queries add distinct information: explicitness and null state from FieldInfo, observed paths including removed ones, and Change records with previous origins and operation paths. They need not replace the value-oriented explanation report.

Result.Source(id) is a convenient lookup of records already available through the source inventory. A source-ID filter is a possible usability refinement; it does not inherently require another command or a required lookup method on every custom source provider. Discovery, import defaults, collection identities, and field-level resolution recording fit the application-supplied loader. Source resource contexts and explicit secrets-directory bootstrap primarily serve application loading and startup; there is no immediate recommendation to add standard inspection operations for them. A consumer need could motivate later presentation of their upstream results.

Targeted end state

Dependency and toolchain

The ckconfig module requires go.maximumdirect.net/configkit v1.1.0, and its production code, tests, and maintained example use that import identity. Raise its consumer minimum to Go 1.27.0. Retain its core v0.3.0 requirement unless implementation identifies a concrete need for a newer core API. Core remains independent of ConfigKit and retains its own Go minimum.

Use a Go 1.27 toolchain for ckconfig dependency preparation and validation. Update the maintainer procedure to select an available Go 1.27 release and distinguish the per-module consumer minimums. The existing host-native, workspace-off launcher can use that toolchain without a new toolchain-selection mechanism.

Faithful adaptation and reports

Retain the existing scope, loader, comparison, diagnostic, and reporting structure. Continue using ConfigKit's public results, native rendering, and diff APIs rather than reproducing its domain logic locally. New collection, discovery, and resolution features can be used by application loaders through the adopted library; they do not inherently require additional CLI flags or CommandKit-owned loading policy.

Align the existing source report with ConfigKit's current vocabulary:

Current API or report spelling	Target
SourceInfo.DestinationUnresolved	SourceInfo.DestinationIsFallback
SourceInfo.VersionCheck / SourceVersionCheck	SourceInfo.VersionEvidence / SourceVersionEvidence
Text/YAML destination_unresolved	destination_is_fallback
Text/YAML version_check	version_evidence
Native main layer value base	Native main layer value main

Update DTOs and both report formats together. Preserve the upstream evidence and its supported presence, null, location, ordering, and redaction information through adaptation. Use the upstream terms directly in help and documentation; link to the owning inspection contract for their semantics. Describe the report migration plainly in the release note. The target uses the new field names without duplicate legacy report fields.

Include EmptyImportSelections as empty_import_selections in both text and YAML source reports under OD-2. Project each declaration path, location, and native selector in the returned record order. Emit empty_import_selections: [] when there are no records. These are planned report changes; update the owning CLI contract when implemented.

Deferred inspection expansion

Metadata inspection and path discovery are the next functional work proposed after adoption (OD-3). Failed-load source inventory, detailed comparison, and structured diagnostics remain separate later proposals (OD-4 through OD-6). The configuration inspection extensions record owns their proposed capabilities and design considerations. None is part of this adoption scope or a new requirement on existing providers.

Consumer migration and module coordination

Public ckconfig signatures expose ConfigKit types, so switching import identity requires consumers to migrate the ConfigKit values they pass across those boundaries. Use the adopted upstream API names in maintained consumers and fixtures. Known test changes include Definition.Secret to Sensitive and Resolution.Record(..., ChangeNormalization, ...) to RecordNormalization. Review other removed pre-v1 symbols where actually used.

Migration guidance should link to upstream for source-root configkit controls becoming config, optional becoming required with changed defaults, identified-collection registrations and operations, and CLI-assignment ordering. Change affected maintained fixtures when present. Application configuration and validation choices remain application-owned; CommandKit does not introduce a compatibility loader or impose new configuration restrictions.

ckprompt's current ConfigKit types come from the old package identity. It cannot simply select the new ckconfig release while retaining that wiring. Its later adoption needs a coordinated ConfigKit/PromptKit migration and review of its own adapters and composed example. Under OD-1, prepare ckconfig independently first and review ckprompt next. This roadmap does not select an unreviewed PromptKit release or claim a new matched integration set.

Independent module compatibility

Once local ckconfig uses the vanity ConfigKit types, the usual three-module go.work selects it for local ckprompt as well. Until ckprompt migrates, its old-path ConfigKit inspection and comparison types cannot satisfy the new ckconfig contracts. This is a temporary composition mismatch, even though each module can be validated independently against its own dependencies.

During that interval, each module's independent validation uses its own declared dependencies with workspace discovery off. The unchanged ckprompt and composed example retain published ckconfig v0.2.0 and their existing upstream libraries; their success does not establish compatibility with migrated local ckconfig. Development and consumer guidance explain the temporary mismatch. Existing ignored workspace files remain local; restoring aligned workspace composition belongs to the later ckprompt migration.

Release preparation

The target candidate is ckconfig v0.3.0, with full tag integrations/ckconfig/v0.3.0, subject to the existing fresh-version guards. A pre-v1 minor fits the intentional ConfigKit type-identity, consumer-minimum, and report-schema changes. Its checked-in note explains these changes and consumer migration, with the usual immutable licensing footer. Current module notices describe the selected graph and pinned upstream source.

Adoption includes release preparation, not source publication or hosted delivery. The existing release procedure owns those operations and their separate outcomes when requested; this target adds no release gate.

Completion evidence

Implementation is complete when ckconfig's actual module metadata and imports select the new dependency, the selected report changes faithfully expose its returned evidence, the module suite and maintained consumer pass independently, and current documentation, notices, and release preparation describe that state. Completion evidence distinguishes independent module validation from the temporary workspace composition mismatch. OD-3 through OD-6 remain in deferred work; their implementation is not a completion condition for adoption. A future source release is reported separately from implementation completion.

Selected scope decisions

These dispositions record the user's selected adoption scope. They define the target, not implemented contracts or authorization to publish. Deferred features still need focused API and CLI design.

Decision	Selected disposition	Reason
OD-1: Integration sequencing	Implement and prepare ckconfig independently first; review ckprompt next.	Independent releases keep adoption focused. Document the temporary workspace mismatch and lack of a newly aligned release pair.
OD-2: Empty-import evidence	Include empty_import_selections, with [] when empty, in text and YAML source reports.	Exposes existing upstream evidence alongside the other report-schema changes.
OD-3: Metadata and path discovery	Defer to the next functional work after adoption.	A coherent optional capability needs its own field/history report and command design.
OD-4: Failed-load source inventory	Defer to a separate source-inspection enhancement.	Requires source evidence on error and deliberate report/failure coordination.
OD-5: Detailed comparison	Defer; retain the existing reduced report during adoption.	A richer form needs a report-selection and compatibility decision.
OD-6: Structured diagnostics	Defer; retain native diagnostic rendering during adoption.	Coordinate machine-readable records with shared reporting and outcome delivery.

Adoption therefore covers dependency and API migration, source-report terminology and empty-import evidence, documentation and notices, independent module validation, and ckconfig release preparation. Core retains its own Go minimum. Application loaders continue to own discovery and loading policy.

Coordinating both integrations before release remains an alternative if a matched adoption path becomes necessary. It would expand the scope to include PromptKit review and ckprompt migration; publication would still proceed in dependency order. The deferred feature record retains the capability proposals and unresolved design choices for OD-3 through OD-6, plus the possible source-ID filter.