base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Retire completed roadmaps and collect future work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 16:04:32 +00:00
parent 260256d722
commit bc1d1d5844
12 changed files with 80 additions and 2197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

332
docs/roadmap/implementation.md
View File

@@ -1,332 +0,0 @@
# ConfigKit v1.1.0 adoption implementation plan
Status: Stages 1–6 complete.
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
**Completed.** Ckconfig now selects ConfigKit v1.1.0 and Go 1.27.0, with
authentic downloaded sums and migrated imports and native API accesses. An
offline compile of its packages and example passed with Go 1.27.0.
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
**Completed.** Text and YAML projections use the new vocabulary and include
ordered empty-import selections, including empty lists and nil version evidence.
The packages compile offline with Go 1.27.0; focused behavioral tests follow.
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
**Completed.** Focused source tests cover the new text and YAML keys, native
main layer, ordered selections, empty lists, and nil/redacted evidence. The
offline `TestSources` suite passed with Go 1.27.0.
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
**Completed.** Current guidance describes the new source report, consumer and
toolchain migration, and temporary ckprompt mismatch. The v0.3.0 candidate
note is prepared; published notes remain unchanged.
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
**Completed.** The workspace-off module graph selects ConfigKit v1.1.0 and
vanity ReleaseKit v0.9.0; old-path ReleaseKit is no longer selected. Attribution
now reflects that graph and the pinned ConfigKit copyright and license source.
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
**Completed.** With Go 1.27.0 and workspace discovery off, the complete core,
ckconfig, and ckprompt suites passed offline with read-only metadata. Ckconfig's
suite was repeated after adding an explicit native main-layer explanation
assertion. The simple example's text and YAML source reports and fixture diff
ran successfully; the focused source fixture covers nonempty import evidence.
Core and ckprompt were tested against their own declared dependency graphs,
not against local migrated ckconfig. Full local workspace composition remains
pending the later ckprompt migration. The v0.3.0 note is a candidate; no source
release or hosted delivery was performed.
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.