303 lines
19 KiB
Markdown
303 lines
19 KiB
Markdown
# 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.
|