commandkit/docs/roadmap/implementation.md

ConfigKit v1.1.0 adoption implementation plan

Status: planned; Stages 1–6 are not started.

This plan is for a Luna coding agent implementing the selected ConfigKit adoption target. Follow Stage 1 through Stage 6 in order as one end-to-end sprint. Intermediate editing states need not compile or form independently usable releases. Reach and validate the complete selected end state before claiming completion; do not introduce compatibility machinery merely to make an intermediate stage pass.

This planning pass changes documentation only. Execution prepares a ckconfig release candidate; source publication, hosted delivery, ckprompt migration, and the deferred inspection extensions are outside this sprint. Do not push or create release tags as part of these stages. The user's later publication instructions and the release procedure govern those operations.

Start with development guidance and follow the agent, architecture, testing, documentation, release, and OSS policies for the work they govern. Use the repository's codebase-memory tools for code discovery. The completed vanity migration plan and publication evidence remain in Git history; do not restart that work or the completed ReleaseKit adoption/remediation.

Baseline and fixed choices

Source/review baseline: 16584084b1b8a87dac959334ede8a47a8cfb8c0b. The planning commit changes roadmap documents, not module code.

Item	Baseline	Selected end state
ckconfig module	go.maximumdirect.net/ckconfig, published v0.2.0	Same module identity; prepare v0.3.0
ConfigKit	gitea.maximumdirect.net/eric/ConfigKit v0.8.0	go.maximumdirect.net/configkit v1.1.0
ckconfig Go minimum	Go 1.26.0	Go 1.27.0
Core dependency	go.maximumdirect.net/commandkit v0.3.0	Retain v0.3.0
Maintainer toolchain	Go 1.26.8	Go 1.27.0 for preparation, validation, and ReleaseKit execution
Other module minimums	Core and ckprompt: Go 1.26.0	Retain their independent minimums

ConfigKit v1.1.0 is published at 191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9. Its module requires Go 1.27.0; the prior disposable migration passed ckconfig and its example tests on that toolchain. The selected report changes have not yet been implemented or tested.

The feature roadmap's selected OD-1/OD-2 choices apply: migrate ckconfig first and include empty-import-selection evidence. OD-3 through OD-6 and source-ID filtering remain in deferred work. Retain the existing configuration operations, provider facets, loading and comparison coordination, diagnostics, outcomes, and reduced diff report. ConfigKit owns domain semantics; this sprint adapts its public capabilities.

Retain root ReleaseKit v0.9.0, the release launchers and profiles, physical module directories, and integration tag prefixes. Core and ckprompt code and module selections are outside this adoption. Published old releases and notes remain immutable. A new adapter layer, legacy import bridge, duplicate legacy report fields, or local reimplementation of ConfigKit semantics is unnecessary.

Preserve ignored go.work, go.work.sum, and .releasekit/gitea-token without reading credential contents. Use GOWORK=off GOTOOLCHAIN=local throughout module preparation, validation, and example runs. Local ckprompt will not compose with migrated local ckconfig until its later ConfigKit/PromptKit migration; its independent suite continues to use published ckconfig v0.2.0. Do not edit ckprompt or introduce replacements to conceal this temporary mismatch.

Stage 1: Migrate the dependency, imports, and removed Go APIs

1. Inspect the worktree and preserve unrelated work. Select Go 1.27.0 on PATH and confirm it with GOWORK=off GOTOOLCHAIN=local go version. This version was available during planning. Reuse an existing installation, or install/download golang.org/dl/go1.27.0 using the established SDK setup pattern in the release procedure. Do not change the ignored workspace to select the toolchain.
2. In integrations/ckconfig/go.mod, set go 1.27.0, remove the old ConfigKit requirement, and require go.maximumdirect.net/configkit v1.1.0. Keep the core requirement and YAML selection unless ordinary resolution establishes a required change. Do not tidy root/ckprompt merely to raise their minima.
3. Migrate ckconfig-owned Go imports, including tests and the simple example, to the new ConfigKit identity. Preserve the package alias configkit. Inspect literals and documentation references separately from imports; old repository URLs in published history are not import-path defects.
4. Adapt the native source-field accesses in sources.go to DestinationIsFallback and VersionEvidence. Use configkit.SourceVersionEvidence in affected test fixtures. The public SourceReader contract still returns []configkit.SourceInfo through the new import identity; it needs no additional methods.
5. Update removed APIs actually used by the tests: Definition.Secret becomes Sensitive in comparison_adapter_test.go, diff_execution_test.go, and diff_report_render_test.go; the normalization call in TestFromConfigKitCompareIgnoresDefaultAndResolutionHistoryForEqualValues becomes RecordNormalization(path, reason). Preserve the existing application mutation and assertions. Search for any other used removed symbols and use the pinned upstream migration mapping, not aliases or replacement domain logic.
6. After import migration, prepare dependencies and run go mod tidy from ckconfig with workspace discovery off and the selected local toolchain. Use normal dependency retrieval during preparation; inspect the authentic resulting go.mod/go.sum changes. Do not fabricate sums or use a sibling checkout as a dependency. Format changed Go files.

Stage result: ckconfig selects the released vanity dependency and current Go APIs. Report spelling and new evidence are completed by the next stages; there is no requirement to keep this intermediate state independently usable.

Stage 2: Align source-report vocabulary and add empty-import evidence

Work in integrations/ckconfig/sources.go. Keep its existing report preparation and delivery path; no new provider capability or operation is needed.

1. Rename DTO fields/types and both text/YAML keys to match the upstream terms: DestinationIsFallback / destination_is_fallback, and VersionEvidence / version_evidence. Rename sourceVersionCheckDTO to sourceVersionEvidenceDTO. Continue projecting all existing version, location, presence, null, and redaction fields as returned. Allow the native main layer value to appear as main; do not translate it back to base.
2. Add EmptyImportSelections to each source DTO, serialized as empty_import_selections after version_evidence. Use an ordinary slice of a small DTO with fields in this order: path string, location using the existing locationDTO, and selector string. No omitempty is needed: initialize the slice so sources without records serialize as [].
3. For every native record, project Path.String(), its supplied location's source ID/line/column, and string(Selector). Preserve source and record order, source-local coordinates, empty strings, and zero coordinates. Forward selector strings without validating or remapping them. Apply no additional import discovery, filesystem access, or domain interpretation.
4. Extend the text writer with the same field names and field order. For an empty slice, print empty_import_selections: []. For nonempty slices, print one indented record per entry with path, location, and selector. Follow the existing text style: quote path/source-ID/selector strings with strconv.Quote and render a location as {source_id: "...", line: N, column: N}. YAML uses the equivalent mapping.
5. The current text writer uses continue after printing a null version check. Restructure that conditional so a null version_evidence does not skip the new empty-import field. Every reported source includes both fields, with version_evidence: null where the upstream pointer is nil.

Stage result: both report forms use the current vocabulary and expose empty-import evidence, including when no version evidence exists. Existing source inventory, explanation, diagnostic, and outcome semantics are retained.

Stage 3: Update focused report and adapter coverage

1. Extend TestSourcesProjectNativeEvidenceInTextAndYAML in sources_test.go rather than building another report-test framework. Update fixtures and assertions to the new native fields and report keys. Check that legacy destination_unresolved and version_check keys are absent from emitted source records; existing published history need not be scanned away.

2. Add controlled empty-import records to the source-reader fixture. Use multiple records with distinguishable paths, selectors, and locations so the test detects loss, reordering, or incorrect projection. Include a source with nil version evidence and nonempty import records to cover the text-writer conditional, and a source with no import records to verify [] in both forms. Preserve the existing null/redacted version-evidence cases, source order, zero-value coverage, and inventory-read count assertions.

3. Use the native LayerMain value in an appropriate fixture and verify that returned source/explanation layer names are presented faithfully. Reuse existing assertions where they already cover native origin projection; do not add a separate test of ConfigKit's layer or provenance rules.

4. Keep existing tests of loader request forwarding, comparison coordination, diagnostics, cancellation, error identity, output failures, and safe native snapshot adaptation. Adjust removed APIs or intentionally changed report expectations only. Do not rewrite behavior assertions merely to make an unexpected regression pass.

5. Run the focused source tests with prepared dependencies, from ckconfig:

   GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=1 -run '^TestSources' .
   

Stage result: durable coverage establishes CommandKit's new report projection. The fake native inventory supplies evidence; tests do not establish whether ConfigKit discovers imports, checks versions, matches records, or classifies sensitive data correctly.

Stage 4: Update current guidance and prepare the release note

1. Update ckconfig README, GoDoc, and examples/simple/README.md for the new dependency identity and Go minimum, and the planned ckconfig v0.3.0 with core v0.3.0. Keep package/provider usage consistent with actual code. Review maintained fixtures for source controls or removed APIs; migrate genuine old controls where present, without changing application fields merely because they have similar names.
2. Update docs/cli.md's configuration-source section with the renamed keys, main layer value, and empty_import_selections schema from Stage 2, including the empty-list shape. Update origin-layer examples where they describe adopted ConfigKit results. Retain existing command grammar, formats, status behavior, and reduced comparison report. Use upstream terms directly and link to the pinned upstream contracts for their semantics.
3. Update docs/consumers/guide.md and README's module-selection summary to distinguish two cases: the newly prepared ckconfig v0.3.0 with ConfigKit v1.1.0, and the existing matched ckconfig/ckprompt v0.2.0 pair. Do not imply that ckprompt v0.2.0 composes with new ckconfig. Qualify upstream links where ckconfig and unchanged ckprompt now use different ConfigKit versions.
4. Document the consumer migration: ConfigKit import/type identity, Go 1.27.0, changed report keys, and added source evidence. Link to upstream migration guidance for source-root configkit controls becoming config, import requiredness/defaults, collection registrations/operations, removed public APIs, and CLI-assignment order. Keep the detailed configuration reference upstream rather than creating a parallel CommandKit contract.
5. In docs/release.md, select Go 1.27.0 as the maintainer toolchain and adapt its existing install/download/PATH example. In that procedure and the consumer guide, distinguish ckconfig's Go 1.27.0 minimum from core and unchanged ckprompt's Go 1.26.0 minima. Keep ReleaseKit v0.9.0 and its existing launcher, profiles, guards, publication, delivery, and recovery workflow. This does not require code or profile changes.
6. Replace the development guide's unqualified three-module workspace advice with interim guidance: preserve ignored workspace files and use GOWORK=off GOTOOLCHAIN=local for preparation, suites, and example runs. Explain that ckprompt's independent suite and composed example use its published ckconfig v0.2.0 dependency; full local workspace composition is pending the later ckprompt migration. Restore aligned workspace guidance during that later work, including the workspace Go version as needed.
7. Create integrations/ckconfig/docs/releases/v0.3.0.md, subject to the existing fresh-version selection, explaining the complete v0.2.0-to-candidate changes and migration actions. End with COPYRIGHT | LICENSE | ATTRIBUTION links to the corresponding module-local paths under https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/. Future tag links need not resolve before publication. Preserve old notes.

Stage result: current owners describe implemented adoption and the interim module relationship; a checked-in candidate release note is ready. No deferred feature, release publication, or external application migration is claimed.

Stage 5: Align module attribution with the actual selected graph

1. From ckconfig, inspect GOWORK=off GOTOOLCHAIN=local go list -m -json all after tidy. Compare it with the existing module attribution. ConfigKit's own tool requirement does not select CommandKit's release tool: retain the root-selected ReleaseKit v0.9.0 and inspect the effective transitive graph.
2. Update integrations/ckconfig/docs/oss/attribution.md's ConfigKit entry to go.maximumdirect.net/configkit v1.1.0 and pinned commit 191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9 on the new forge. Verify its actual copyright, grant, license, and applicable notices. Reuse existing complete standard license texts when they match the selected terms.
3. Remove/update entries for dependencies no longer selected or whose selected versions changed; the baseline includes old-path ReleaseKit v0.4.1 and its dependencies as well as vanity ReleaseKit v0.9.0. Follow the actual graph, not a global old-host replacement or an assumption that every tool module disappears. Keep the House Format and exact-revision notice/source links.
4. Core and ckprompt dependency selections remain unchanged. Preserve their corresponding notices and published release records. Update shared material only if its actual scope or selection changes; adoption alone does not require revising unrelated grants or copying upstream policy documents.

Stage result: ckconfig's notices correspond to its real selected modules, with authentic source/license references and no unrelated attribution rewrite.

Stage 6: Validate the final state and finish the sprint

1. Format changed Go files; inspect final diffs and module metadata. Confirm ckconfig-owned Go imports use the vanity ConfigKit identity, the old requirement is gone, its Go minimum is 1.27.0, core stays at v0.3.0, and no local replacements/workspaces enter tracked module inputs. Confirm root and ckprompt still have their existing module selections and Go minima.

2. Prepare any missing dependency caches for all three modules using normal retrieval with workspace discovery off. On Go 1.27.0, run each independent complete suite with read-only offline dependencies:

   GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=1 ./...
   (cd integrations/ckconfig && \
     GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=1 ./...)
   (cd integrations/ckprompt && \
     GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=1 ./...)
   

   This includes ckconfig's maintained example tests. Record the unchanged modules' results as validation of their own published dependency graphs, not composition with local migrated ckconfig. Do not add a workspace shim or change ckprompt to obtain a green three-module workspace.

3. Exercise the simple example's config sources text/YAML reports and its existing fixture comparison with workspace discovery off. Use a controlled native source fixture from Stage 3 for nonempty import evidence; a new application import system or live service is unnecessary. Confirm only the selected presentation and wiring behavior, not upstream domain correctness.

4. Check affected current documentation, local links/fragments, whitespace, candidate note paths, attribution entries, and pinned-source provenance. Ensure future behavior is not described as implemented, and distinguish prepared v0.3.0 from a published release. Run git diff --check and the staged counterpart, including intended new files in the review.

5. Record stage completion, final validation evidence, and the temporary workspace mismatch in this plan. Mark the feature roadmap's implementation status accordingly while leaving publication and external adoption pending. Keep deferred capabilities in their owning record without starting them.

6. Review the worktree and staged changes, commit completed units under the agent policy with concise messages, and finish with a clean worktree apart from explicitly preserved unrelated work. Summarize the module/dependency changes, report migration, tests, commits, and remaining ckprompt follow-up. Do not publish; the normal selected-module release workflow remains the owner of future candidate validation, guards, and publication outcomes.

Stage result: the selected ckconfig adoption is implemented, documented, validated, committed, and prepared for a later release request. Intermediate compile failures and deferred work are not substitutes for this final result.

No required scope questions remain open. Routine implementation choices follow the selected upstream contracts and the report shape fixed above; deferred extensions do not need to be designed to complete this sprint.