commandkit/docs/roadmap/implementation.md

# CommandKit vanity migration and dependency alignment plan

Status: Stages 1–3 complete; Stages 4–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

**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.

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

**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. 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

**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

**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.