341 lines
19 KiB
Markdown
341 lines
19 KiB
Markdown
# CommandKit vanity migration and dependency alignment plan
|
||
|
||
Status: planned; Stages 1–7 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 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.
|
||
|
||
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.
|
||
|
||
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 decisions
|
||
|
||
Planning baseline: `c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a`.
|
||
|
||
| 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` |
|
||
|
||
- 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.
|
||
|
||
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.
|
||
|
||
## Execution and validation conventions
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
## Stage 1: Migrate core identity and prepare its release candidate
|
||
|
||
**Status:** not started.
|
||
|
||
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:
|
||
|
||
```sh
|
||
GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
|
||
go test -mod=readonly -count=1 -run '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' .
|
||
```
|
||
|
||
**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 2: Validate and publish core v0.3.0
|
||
|
||
**Status:** not started.
|
||
|
||
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:
|
||
|
||
```sh
|
||
git push origin HEAD:refs/heads/main
|
||
./scripts/release core v0.3.0
|
||
```
|
||
|
||
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.
|
||
|
||
**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 3: Migrate ckconfig and prepare its independent candidate
|
||
|
||
**Status:** not started.
|
||
|
||
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
|
||
|
||
**Status:** not started.
|
||
|
||
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
|
||
|
||
**Status:** not started.
|
||
|
||
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
|
||
|
||
**Status:** not started.
|
||
|
||
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
|
||
|
||
**Status:** not started.
|
||
|
||
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.
|