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](configkit-v1.1.0.md). 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](../release.md) govern those operations.

Start with [development guidance](../development.md) and follow the
[agent](../policy/agents.md), [architecture](../policy/architecture.md),
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
[release](../policy/release.md), and [OSS](../policy/oss.md) policies for the work
they govern. Use the repository's codebase-memory tools for code discovery.
The completed [vanity migration plan and publication evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/16584084b1b8a87dac959334ede8a47a8cfb8c0b/docs/roadmap/implementation.md)
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](deferred.md#configuration-inspection-extensions).
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:

   ```sh
   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:

   ```sh
   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.