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

# ConfigKit v1.1.0 adoption

Status: recommended adoption scope recorded; implementation has not begun.
This roadmap covers the embedded `ckconfig` dependency and source-report
migration. [Recommended scope decisions](#recommended-scope-decisions) record
the first sprint and the extensions deferred to later work.

## 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](../policy/architecture.md#backend-and-library-integration).
The [agent](../policy/agents.md), [testing](../policy/testing.md),
[documentation](../policy/documentation.md), [release](../policy/release.md), and
[OSS](../policy/oss.md) policies govern implementation. This roadmap proposes
work; current contracts remain in GoDoc, the [CLI reference](../cli.md), and the
[consumer guide](../consumers/guide.md) 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](integration-dependency-alignment.md)
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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md)
and [v1.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md)
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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md)
and [v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md).

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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/metadata.go),
[source and diagnostic records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go),
[load-error API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/diagnostic.go),
and [comparison API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/diff.go)
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](../../integrations/ckconfig/go.mod) 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](../release.md#release-toolchain) 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 recommended as the next functional
sprint 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](deferred.md#configuration-inspection-extensions)
record owns their proposed capabilities and design considerations. None is part
of this adoption sprint 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.

### Interim workspace guidance

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, preserve the ignored local workspace and use `GOWORK=off`
for dependency preparation, tests, and example runs. From the repository root,
with the selected Go 1.27 toolchain on `PATH` and dependencies prepared:

```sh
GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
```

The unchanged ckprompt suite and composed example then use published ckconfig
v0.2.0 and their existing upstream dependencies. Their success does not validate
composition with the migrated local ckconfig. Keep local replacements and
workspace files out of the adoption commit. Resume three-module workspace and
composed-consumer validation after ckprompt's migration; update the ignored
workspace's Go version as needed for its member modules at that point.

When the dependency change lands, update the development guide's workspace
instructions to explain this interval. Restore the aligned-workspace guidance
when ckprompt adopts the new dependencies. Until implementation, the existing
development instructions describe the current compatible baseline.

## Work from the baseline

1. **Prepare module metadata for the recommended scope.** Follow OD-1 and
   OD-2; OD-3 through OD-6 remain deferred. 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. Add empty-import
   evidence, including empty lists and record order. Preserve
   current coordination and outcomes. Adapt upstream results rather than
   adding domain validation.
3. **Update canonical documentation and notices.** Revise the ckconfig README
   and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources),
   consumer guide, release toolchain instructions, and development workspace
   guidance 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. Use the interim
   workspace guidance for unchanged modules; record that their independent
   checks do not establish compatibility with the migrated ckconfig. Full
   composed-workspace validation belongs to the later ckprompt migration.
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 final validation evidence and the temporary workspace composition
status. OD-3 through OD-6 remain in deferred work; their implementation is not
a completion condition for this sprint. A future source release is reported
separately from implementation completion; preparing this roadmap does not publish a version
or migrate external applications.

## Recommended scope decisions

These dispositions record the review recommendations for the adoption sprint.
They define its planned scope, not implemented contracts or authorization to
publish. Deferred features still need focused API and CLI design.

| Decision | Recommended disposition | Reason |
| --- | --- | --- |
| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep this sprint 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 sprint 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 in this sprint. | A richer form needs a report-selection and compatibility decision. |
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering in this sprint. | Coordinate machine-readable records with shared reporting and outcome delivery. |

The first sprint 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 sprint to include
PromptKit review and ckprompt migration; publication would still proceed in
dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions)
retains the capability proposals and unresolved design choices for OD-3 through
OD-6, plus the possible source-ID filter.