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

ConfigKit v1.1.0 adoption

Status: proposed; dependency and report changes are not implemented. This roadmap covers the embedded ckconfig integration. Release coordination and additional source evidence have recommendations under Open Decisions.

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 proposes work; current contracts remain in GoDoc, the CLI reference, and the consumer guide until implementation lands.

Current baseline and review evidence

Reviewed CommandKit revision: 60841227b7e2928d3fefd3326f0e3f4694f41e6d. 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.

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.

ConfigKit's source inventory also supplies EmptyImportSelections, with declaration path, location, and selector. OD-2 addresses including this evidence in the existing source report; it is not yet a selected report-schema addition.

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. OD-1 determines scheduling; this roadmap does not select an unreviewed PromptKit release or claim a new matched integration set.

Work from the baseline

1. Confirm scope choices and prepare module metadata. Resolve OD-1 and OD-2, select the Go 1.27 maintainer toolchain, update ckconfig's requirement, imports, and minimum, and regenerate authentic sums with workspace discovery off. Inspect the resulting dependency graph; do not commit local replacements or environment files as an adoption mechanism.
2. Adapt APIs and source reports. Update the native source field accesses, DTOs, text/YAML output, affected tests, and example code. Apply the selected empty-import-evidence choice. Retain the existing coordination and outcome behavior, adapting upstream results rather than adding domain validation.
3. Update canonical documentation and notices. Revise the ckconfig README and GoDoc, CLI source-report reference, consumer guide, and release toolchain instructions with the implemented changes. Review the selected graph and upstream notices, then update ckconfig attribution with the vanity identity, selected versions, and pinned source links. Update other module notices only when their actual selections change. Preserve published release history.
4. Validate the selected end state. Run the ckconfig suite, including its maintained example, independently with GOWORK=off and read-only module metadata on the selected Go 1.27 toolchain. Update focused adapter/report assertions for the new vocabulary and faithful projection of returned evidence. Preserve coverage of request forwarding, diagnostics, cancellation, output failures, and supported error identity. Assertions establish CommandKit adaptation; ConfigKit owns tests of its domain correctness. Review changed Markdown links, fragments, and examples. If coordinated ckprompt work is selected, also validate that module and the composed consumer against the proposed dependency set; local-workspace success alone does not establish independent module compatibility.
5. Prepare the integration release. Propose ckconfig v0.3.0, subject to the existing fresh-version guards, with tag integrations/ckconfig/v0.3.0. Explain changed ConfigKit type identity, Go minimum, report fields, and consumer migration in its checked-in note with the usual licensing footer. A pre-v1 minor fits these intentional compatibility changes. Use the existing selected-module release procedure when publication is requested; this plan adds no release gate. Source publication and hosted Gitea delivery retain their separate outcomes.

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. Record the resolved scope choices and final validation evidence. A future source release is reported separately from implementation completion; preparing this roadmap does not publish a version or migrate external applications.

Open Decisions

OD-1: Release ckconfig first or coordinate both integrations?

Recommendation: implement and release ckconfig independently first, and review ckprompt's upstream migration as the next integration task. This keeps the current scope concrete and uses the established independent module releases. Existing ckprompt v0.2.0 consumers retain their published dependency set; document that moving them to the new ckconfig needs the corresponding ckprompt migration. The tradeoff is an interval with no newly aligned release pair.

Viable alternative: complete the ConfigKit/PromptKit review and both integration migrations before releasing the next pair, publishing ckconfig first in dependency order. This gives composed consumers a coordinated adoption path and validates the shared type boundaries together. It expands this work into PromptKit adoption and delays ckconfig availability while that review and implementation proceed. No simultaneous tag publication is needed.

OD-2: Include empty-import-selection evidence in this adoption?

Recommendation: add empty_import_selections to the existing text/YAML source report, projecting ConfigKit's declaration path, location, selector, and record order. This exposes structured source evidence already available upstream without a new command or a second explanation engine. It adds report mapping and focused projection coverage alongside the other schema changes; the exact empty-list presentation should be settled with the implemented report.

Viable alternative: limit this release to migrating the evidence already reported, and defer this additive field to a later inspection enhancement. That reduces the immediate report change and test scope, and still makes the native metadata available to Go consumers of ConfigKit. CLI consumers would continue to lack this upstream evidence, and a later release would need another report and documentation update.