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

Plan ConfigKit adoption sprint

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 14:42:23 +00:00
parent 16584084b1
commit 1c778d7ad3
4 changed files with 315 additions and 427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

610
docs/roadmap/implementation.md
View File

@@ -1,374 +1,302 @@
# CommandKit vanity migration and dependency alignment plan
# ConfigKit v1.1.0 adoption implementation plan
Status: Stages 1–7 complete.
Status: planned; Stages 1–6 are not started.
This plan is for the Luna coding agent implementing the
[feature roadmap](integration-dependency-alignment.md). Follow the stages in
integer order during one end-to-end sprint. Unpublished editing states may be
temporarily inconsistent. Each published module must be a coherent, committed
candidate validated by its ordinary release workflow.
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. The target includes three real
source releases because later modules need downloadable predecessors. The
publication stages below describe that future work; this planning request does
not perform or authorize Git pushes. Honor the user's implementation/publication
scope when executing the plan, and report any unperformed release as pending.
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.
Read [development guidance](../development.md), the
[agent policy](../policy/agents.md), [architecture policy](../policy/architecture.md),
[testing policy](../policy/testing.md),
[documentation policy](../policy/documentation.md),
[release policy](../policy/release.md), and [OSS policy](../policy/oss.md) for
the work they govern. Follow `AGENTS.md` codebase-memory discovery instructions.
The [release procedure](../release.md) remains the owner of operational commands.
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.
The previous plan's [completed ReleaseKit v0.9.0 stages and evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md)
remain in Git history. R1/R2 in [remediation.md](remediation.md) and the ReleaseKit
adoption are complete; do not restart them or rewrite their historical evidence.
## Baseline and fixed choices
## Baseline and fixed decisions
Source/review baseline: `16584084b1b8a87dac959334ede8a47a8cfb8c0b`.
The planning commit changes roadmap documents, not module code.
Planning baseline: `c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a`.
| 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 |
| Module directory | Current module path | Target module path | Target version and full tag |
| --- | --- | --- | --- |
| `.` | `gitea.maximumdirect.net/eric/CommandKit` | `go.maximumdirect.net/commandkit` | v0.3.0; `v0.3.0` |
| `integrations/ckconfig` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `go.maximumdirect.net/ckconfig` | v0.2.0; `integrations/ckconfig/v0.2.0` |
| `integrations/ckprompt` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `go.maximumdirect.net/ckprompt` | v0.2.0; `integrations/ckprompt/v0.2.0` |
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.
- Both integrations currently require core v0.2.0; ckprompt also requires
ckconfig v0.1.0. Their source uses newer core APIs. Independent baseline suites
fail; temporary local-source selections pass only when ckprompt also uses
current ckconfig. The feature roadmap records those diagnostics.
- Target ckconfig requires `go.maximumdirect.net/commandkit v0.3.0`. Target
ckprompt requires that core and `go.maximumdirect.net/ckconfig v0.2.0`.
- Vanity discovery is verified. The integration metadata's fourth field maps
the short paths to the existing physical directories. Existing tags still
declare old identities. Discovery alone does not complete module migration.
- Preserve package names, exported declaration shapes, runtime behavior, Go
1.26.0 consumer minimums, and the Go 1.26.8 maintainer toolchain. Preserve root
ReleaseKit v0.9.0 selection, scripts, profiles, endpoints, and validators.
- Retain ConfigKit v0.8.0 and PromptKit v0.16.0; no upstream library upgrade is
selected. Inspect tidy's actual graph changes and update affected attribution.
- The three proposed tags were unused at planning time. Existing publication
guards recheck freshness; never move/reuse a published tag. A conflict needs
a deliberate new version selection and matching dependent metadata/notes.
- Retain ignored `go.work` and `go.work.sum`, and the supplied ignored
`.releasekit/gitea-token` without reading its contents. No credential or live
provider is needed for local validation. Source publication uses the existing
Git endpoint; hosted delivery remains a separate operation/outcome.
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.
Do not rename physical module directories or flatten integration tag prefixes.
Do not add an old-path forwarding module, type-interoperability layer, API
rollback, permanent validation shim, or new recurring release gate. These are
outside the selected migration, not new restrictions on application behavior.
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.
## Execution and validation conventions
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.
Use Go 1.26.8 on `PATH` following the existing
[toolchain setup](../release.md#release-toolchain). The ignored workspace declares
Go 1.26.10 at baseline; preserve it. Use `GOWORK=off GOTOOLCHAIN=local` for module
preparation and independent validation. Use normal dependency retrieval during
preparation; ReleaseKit runs the final selected-module suite offline/read-only.
## Stage 1: Migrate the dependency, imports, and removed Go APIs
Migrate module-owned source, tests, and examples together. Apply integration
path mappings before the broader core prefix when a replacement tool is used;
`go.maximumdirect.net/commandkit/integrations/ckconfig` is not the selected
ckconfig identity. Preserve import aliases such as `commandkit`. Core `internal`
imports must use the new core prefix. Review identity-sensitive strings as well
as Go import declarations.
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.
Update current prose and GoDoc for the module being migrated. Treat repository,
license, and immutable historical source links separately from Go import paths.
Keep published notes, accepted ADR history, and completed review evidence intact.
Do not globally replace every old URL or migrate unrelated upstream identities.
**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.
Publication steps use the existing protocol: prepare dependencies, review and
commit the final selected candidate on `main`, publish that candidate commit to
the authoritative branch, and invoke the module's release wrapper. The wrapper
runs the owning complete suite once, selected file checks, and publication
guards, then creates/pushes the intended tag. It does not push `main` for you.
Run validation-only `check` for diagnosis when useful; do not make it a required
duplicate suite before `publish`. Do not add CI/proxy polling or post-push
read-back as a successful-publication gate. Reuse evidence for unchanged content.
## Stage 2: Align source-report vocabulary and add empty-import evidence
Each release has its own candidate commit, suite result, and publication outcome.
The next module's dependency download is preparation for that next release;
failure to download does not undo completion of the predecessor's source push.
Use a command-scoped direct download to diagnose proxy lag if necessary rather
than permanently changing proxy settings. Retain authentic downloaded sums.
Work in `integrations/ckconfig/sources.go`. Keep its existing report preparation
and delivery path; no new provider capability or operation is needed.
## Stage 1: Migrate core identity and prepare its release candidate
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.
**Completed.** The root module, owned imports, component build identity,
consumer guidance, and v0.3.0 release note use the new core identity. The
focused build-identity test passed offline with Go 1.26.8; affected links and
whitespace were checked. The complete candidate suite belongs to publication.
**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.
1. Change only the root module declaration to `go.maximumdirect.net/commandkit`.
Migrate root-owned imports in production files, root/external tests, internal
packages, and `examples/core`. Leave nested module migration to Stages 3/5.
Preserve the root tool declaration and other dependency versions; prepare
caches and tidy the root with workspace discovery off.
2. Update `commandKitModulePath` in `builtins.go` to the new core identity.
`version --scope commandkit` uses it to find build information. Retain its
existing application/component scopes, tag/replacement handling, and `dev`
fallback; do not add a legacy-identity fallback.
3. Adapt existing identity/import-path test expectations. In
`TestCommandKitBuildIdentityProjectsEffectiveModuleVersion`, make at least
one existing successful tagged case supply the literal new module path
independently of `commandKitModulePath`. Otherwise a stale constant and its
self-referencing fixtures could agree while real version lookup fails.
Preserve all existing replacement/development cases and boundary assertions.
4. Update the root row in README's module table, current core imports and
installation guidance in `docs/consumers/guide.md`, affected developer and
internal guidance, example documentation, and GoDoc. Describe integrations
according to their implemented identity until their migration stages land;
keep the matched future set in migration guidance explicit.
5. Refresh `docs/releases/v0.3.0.md` against the full v0.2.0-to-candidate change:
aliases, reporting migration, completion, ReleaseKit maintenance, and the new
core import path. Explain consumer updates and the forthcoming matched
integration versions. Use current procedure URLs with immutable `v0.3.0`
source/licensing links. Keep the declared toolchains unchanged.
6. Format changed Go files. Review root-owned imports/identity literals and
module metadata; check affected prose links and whitespace. Run the existing
focused identity test with prepared caches:
## 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 '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' .
go test -mod=readonly -count=1 -run '^TestSources' .
```
**Stage result:** a reviewed core v0.3.0 candidate with the new identity, correct
component version lookup, migrated root consumers, and current release notes.
The full root suite belongs to Stage 2's normal publication workflow.
**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 2: Validate and publish core v0.3.0
## Stage 4: Update current guidance and prepare the release note
**Completed.** Core `go.maximumdirect.net/commandkit v0.3.0` was published as
tag `v0.3.0` at candidate `e256eb1cc02a0c72c4e23c4967ed1caeaef17008`.
The ordinary Go 1.26.8 release workflow passed the complete root suite and
selected file checks before the successful source-tag push.
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.
1. Review and commit the complete core candidate under the local commit policy.
Confirm that unrelated/private files and ignored workspaces are excluded.
The independently released integration sources may still declare old paths;
that does not make their suites a prerequisite for this root release.
2. From the repository root, execute the existing publication sequence within
the authorized release scope:
**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
git push origin HEAD:refs/heads/main
./scripts/release core v0.3.0
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 ./...)
```
3. Require the real selected-module suite and file checks to pass. Fix actual
failures in scope and commit the corrected candidate before retrying. On a
failed/ambiguous push, use the existing publication evidence and recovery
procedure. Do not force refs, bypass guards, or treat a local tag as publication.
4. Record the candidate commit, module path, full tag, validation outcome, and
confirmed source outcome here. A successful tag push completes this source
release; move to dependent preparation without waiting for hosted pages.
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:** core v0.3.0 is source-published with
`module go.maximumdirect.net/commandkit`. Actual download of this version and its
sums is part of Stage 3, not a new completion gate for core publication.
**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.
## Stage 3: Migrate ckconfig and prepare its independent candidate
**Completed.** Ckconfig declares `go.maximumdirect.net/ckconfig`, imports the
new core identity, and downloaded `go.maximumdirect.net/commandkit v0.3.0`
with authentic sums. The resolved graph retains ConfigKit v0.8.0 and selects
both the older ReleaseKit v0.4.1 and vanity ReleaseKit v0.9.0 tool modules;
module-local attribution and current guidance reflect those selections. The
v0.2.0 release note is prepared; independent suite validation follows.
1. In `integrations/ckconfig`, migrate the module declaration to
`go.maximumdirect.net/ckconfig`. Update all owned imports, tests, and the
maintained simple example to that self-path and the new core path. Keep
package names and existing adapter behavior.
2. Replace its old core dependency key with the published new-path version.
From the ckconfig module directory, use:
```sh
GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckconfig -droprequire=gitea.maximumdirect.net/eric/CommandKit -require=go.maximumdirect.net/commandkit@v0.3.0
GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0
GOWORK=off GOTOOLCHAIN=local go mod tidy
```
Perform source import migration before tidy to avoid resolving old imports.
Keep real downloaded sums. If retrieval is unavailable, resolve dependency
preparation before proceeding; do not fabricate metadata or substitute a
local replacement as final release evidence.
3. Inspect the actual direct and indirect graph, including tool requirements.
Preserve ConfigKit v0.8.0 and unrelated versions. Update affected notices in
`integrations/ckconfig/docs/oss/attribution.md` under the OSS policy using the
actual selected source revisions; add/retain applicable license texts. Do
not assume similarly named old/new upstream modules are interchangeable.
4. Prepare `integrations/ckconfig/docs/releases/v0.2.0.md` with product
`CommandKit ckconfig`, the new module/core paths, compatible dependency set,
and relevant reporting/completion migration. Immutable footer/source URLs
use the full tag `integrations/ckconfig/v0.2.0` and correct physical files.
5. Update README's ckconfig row, consumer module/import examples, the simple
example guidance, affected GoDoc, and relevant current release/development
references. Explain that applications moving to the new core identity also
use the matched new integration identity.
6. Format changed Go files. Review for stale owned imports/direct requirement
keys, accidental replacements/workspace files, and unexplained graph churn.
Check current links and whitespace. The owning complete suite runs in
Stage 4; a local workspace pass is not a substitute.
**Stage result:** a ckconfig v0.2.0 candidate whose actual dependency is
downloaded `go.maximumdirect.net/commandkit v0.3.0`, with authentic metadata and
aligned current documentation/attribution.
## Stage 4: Validate and publish ckconfig v0.2.0
**Completed.** `go.maximumdirect.net/ckconfig v0.2.0` was published as
`integrations/ckconfig/v0.2.0` at candidate
`92a327db9752e7a898d14f56e86fbdee027b3126`. The ordinary Go 1.26.8 release
workflow passed the independent suite, maintained example, and selected file
checks before the successful source-tag push.
Review and commit the complete ckconfig candidate. From the repository root,
use the same authoritative-branch protocol as Stage 2:
```sh
git push origin HEAD:refs/heads/main
./scripts/release ckconfig v0.2.0
```
The normal release command must pass the independent ckconfig suite, including
its maintained example, with workspace discovery off and without dependency
redirection. It must also pass selected committed-file checks and publication
guards. Do not insert the earlier temporary Go shim or weaken a selected check.
Apply the existing failed/ambiguous-publication procedure if needed.
Record the candidate, path, version, full tag, validation, and source outcome.
The intended tag is `integrations/ckconfig/v0.2.0`; the physical directory remains
`integrations/ckconfig` despite the short vanity module path.
**Stage result:** compatible ckconfig v0.2.0 is source-published under its vanity
identity. Downloading it for ckprompt is the next module's preparation.
## Stage 5: Migrate ckprompt and prepare its independent candidate
**Completed.** Ckprompt declares `go.maximumdirect.net/ckprompt`, uses the
new core and ckconfig imports, and downloaded their v0.3.0 and v0.2.0 releases
with authentic sums. ConfigKit v0.8.0 and PromptKit v0.16.0 remain selected;
attribution records both distinct ReleaseKit tool modules in the resolved
graph. The v0.2.0 note and current consumer guidance are prepared; independent
suite validation follows.
1. Migrate `integrations/ckprompt` to `go.maximumdirect.net/ckprompt`. Update its
owned source/tests and composed example to import the new core, ckconfig,
and ckprompt paths. Preserve PromptKit adaptation and reporting behavior.
2. From that module directory, replace both old CommandKit dependency keys:
```sh
GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckprompt -droprequire=gitea.maximumdirect.net/eric/CommandKit -droprequire=gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig -require=go.maximumdirect.net/commandkit@v0.3.0 -require=go.maximumdirect.net/ckconfig@v0.2.0
GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0 go.maximumdirect.net/ckconfig@v0.2.0
GOWORK=off GOTOOLCHAIN=local go mod tidy
```
Migrate imports before tidy. Retain actual downloaded sums; resolve fetch
failures as preparation rather than masking them with local source. A new
core with old ckconfig v0.1.0 is the known incompatible combination.
3. Review graph changes while retaining ConfigKit v0.8.0 and PromptKit v0.16.0.
Update affected module-local attribution and immutable notice links based on
the resolved graph, including transitive tools. Keep actual upstream module
identities distinct from the three CommandKit identities being migrated.
4. Prepare `integrations/ckprompt/docs/releases/v0.2.0.md` with product
`CommandKit ckprompt`, new imports/dependencies, and consumer migration.
Footer/source links use full tag `integrations/ckprompt/v0.2.0` and physical
module-local files. Preserve the published v0.1.0 record.
5. Update README's ckprompt row, consumer composition/import examples, composed
example guidance, affected GoDoc, and remaining current module descriptions.
Keep URLs to hosted repository files separate from Go package links.
6. Format changed Go files and review remaining owned old-path imports or direct
requirement keys, metadata, links, and whitespace. Keep the ordinary source
checks intact; the independent suite runs in Stage 6.
**Stage result:** ckprompt v0.2.0 composes the real new-path core and ckconfig
versions in its declared graph, with current guidance and authentic metadata.
## Stage 6: Validate and publish ckprompt v0.2.0
**Completed.** `go.maximumdirect.net/ckprompt v0.2.0` was published as
`integrations/ckprompt/v0.2.0` at candidate
`3f1ed2f107d381530312a5f96e108444aec30c17`. The ordinary Go 1.26.8 release
workflow passed the independent suite, composed example, and selected file
checks before the successful source-tag push.
Review and commit the complete ckprompt candidate. From the repository root:
```sh
git push origin HEAD:refs/heads/main
./scripts/release ckprompt v0.2.0
```
The normal publication workflow must pass the independent ckprompt suite and
composed consumer with actual downloaded predecessors, plus selected file and
publication checks. Preserve the offline/read-only suite environment and
ordinary recovery handling. No workspace or replacement shim supplies final
release evidence.
Record its candidate, module identity, full tag
`integrations/ckprompt/v0.2.0`, suite outcome, and source-publication outcome.
Report any separate hosted delivery under its own outcome; page publication
is not required to establish dependency alignment.
**Stage result:** all three matched source releases are published with vanity
module declarations and verified independent dependency graphs.
## Stage 7: Audit the completed migration and record evidence
**Completed.** The cumulative migration was reviewed: all three module
declarations, owned Go imports, examples, direct dependencies, and the core
build identity use the selected vanity paths. Physical module directories, tag
prefixes, Go minimums, ReleaseKit selection, scripts, profiles, and production
API shapes remain unchanged. Current guidance and module attribution reflect
the matched dependency graph; historical records remain intact.
The source releases and their independent Go 1.26.8 publication suites are
recorded in Stages 2, 4, and 6. Earlier local-source diagnostics in the feature
roadmap were preparation evidence, not release validation. Hosted delivery is
separate and was not performed as part of this source migration.
1. Review the cumulative diff against the feature roadmap. Confirm all three
module declarations, owned imports, examples, direct dependency keys, and
component build identity use the new paths. Preserve physical directories,
tag prefixes, root ReleaseKit selection, scripts/profiles, exported shapes,
Go minimums, and upstream versions apart from explained graph consequences.
2. Check that tests and current guidance use the new identities while historical
notes, accepted ADRs, and immutable source URLs retain their historical
meaning. Resolve current dependency-readiness claims that are now stale.
Do not mechanically rewrite every old-path reference in completed records.
3. Record each final candidate's exact commit, full tag, suite result, and
publication outcome. Identify diagnostic-only earlier evidence separately.
Reuse each successful publication suite for its unchanged candidate; do not
require another complete run just to finish this stage. Any later code or
metadata correction belongs in a new candidate/version under release policy.
4. Mark stages complete only with their stated evidence and update the feature
roadmap's status/link here. Preserve this record and prior immutable plans;
apply normal roadmap retirement only during later preparation. If publication
was outside the authorized implementation scope or could not finish, record
the actual prepared state and pending release stages rather than claiming
alignment is complete.
5. Review new evidence prose, links/fragments, intended staged files, and
`git diff --check` / `git diff --cached --check`. Commit any remaining
nonempty documentation unit with a short plain-English message, following
the local commit policy. Finish with a clean tracked worktree when only
planned work is present; preserve unrelated and ignored local files.
**Stage result:** the implemented and published matched version set has accurate
source/validation evidence, current migration guidance, and committed tracking.
Source release and hosted-delivery outcomes remain separate.
## Open Questions
None required to choose the implementation. Vanity paths, target versions,
physical layout, dependency order, validation ownership, and compatibility scope
are selected in the roadmap. Publication authorization is an execution-scope
constraint, not a reason to invent different versions, fabricated sums, or a
local-only substitute for the target end state.
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.