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

Plan vanity migration and integration releases

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 03:44:22 +00:00
parent c8d659dfe5
commit 881dae27c4
3 changed files with 316 additions and 374 deletions
Download Patch File Download Diff File Expand all files Collapse all files

592
docs/roadmap/implementation.md
View File

@@ -1,348 +1,340 @@
# ReleaseKit v0.9.0 implementation plan
# CommandKit vanity migration and dependency alignment plan
Status: Stages 1–6 complete.
Status: planned; Stages 1–7 are not started.
Implement these stages in integer order during one end-to-end sprint. The target
audience is the Luna coding agent. Intermediate stages may temporarily leave
metadata and documentation inconsistent; the final result must satisfy the
[feature roadmap](releasekit-v0.9.0.md). That document owns target behavior and
rationale; this plan owns tasks, sequencing, and implementation evidence.
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), [testing policy](../policy/testing.md),
[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 changes they govern. Use the codebase-memory tools for code discovery as
required by `AGENTS.md`.
the work they govern. Follow `AGENTS.md` codebase-memory discovery instructions.
The [release procedure](../release.md) remains the owner of operational commands.
The previous implementation plan covered the completed release simplification.
Its [stages and validation evidence](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/87eb84ccb462bf54e6250c8b287ac217efe90883/docs/roadmap/implementation.md)
remain in Git history. Its Stage 5 documents the integration diagnostic reused
below. Do not restart that completed sprint.
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: `87eb84ccb462bf54e6250c8b287ac217efe90883`.
Planning baseline: `c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a`.
- The root `go.mod` selects `go.maximumdirect.net/releasekit v0.8.0` and registers
`go.maximumdirect.net/releasekit/cmd/releasekit`. Adopt exactly v0.9.0, whose
upstream source is `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`.
- Go 1.26.0 remains the consumer minimum for all three modules. Use Go 1.26.8
for this maintenance work. Preserve the ignored local `go.work`, which at
planning time declares Go 1.26.10; use external temporary workspaces instead.
- R1 (`7eac3fe`) and R2 (`4d92ee4`) are complete in
[remediation.md](remediation.md). Preserve their fixes and tests.
- Retain `scripts/release`, `scripts/releasekit`, all three `releasekit.json`
profiles, and their existing selected validators and page-only Gitea
destination. Host normalization, full-package tool invocation, root-owned
tool selection, and separate source/delivery outcomes remain.
- The remaining code change is a test-only correction in
`completion_context_test.go`. Production completion ordering stays unchanged.
- Both integration modules require core v0.2.0, while current source needs newer
APIs. Workspace-off integration suites have known missing-symbol failures.
Updating their module versions, sums, or attribution is separate release
preparation. Workspace-backed results must not be called independent release
readiness.
- The supplied `.releasekit/gitea-token` remains ignored and untracked. Preserve
the file and ignore rule without reading its contents. Use no credentials,
real source publication, or hosted writes in this sprint.
| 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` |
Upstream v0.9.0 adds launcher/recovery fixes without changing the public API,
profile schema, publication record format, Go minimum, or upstream requirements.
The reviewed metadata change was confined to the ReleaseKit version and its
checksum entries. Verify the actual diff; investigate unrelated changes instead
of accepting them. Do not copy the upstream multi-module bootstrap, introduce
new validators, or add a local recovery implementation.
- 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.
## Stage 1: Repair the completion assertion's ordering assumption
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.
**Completed.** The alias comparison sorts cloned actual and expected records
without changing production behavior. The prescribed 30 repetitions passed
offline with Go 1.26.8.
## Execution and validation conventions
Edit only the relevant test assertions and standard-library imports in
`completion_context_test.go`. Use Go 1.26.8 on `PATH` as described in the
[toolchain setup](../release.md#release-toolchain), including for this stage.
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.
1. Read `TestCompletionCommandContext`. The `entered alias` case expects
`--detail` to `--verbose` and `--silent` to `--quiet`, but currently compares
the internal alias slice in a fixed order. Keep those exact expected records.
2. Clone the actual alias slice before comparison. Sort the test-owned actual
and expected slices by `Source`, then `Target`, using standard-library slice
sorting and comparison. Compare the complete slices, preserving length and
duplicate detection. Keep this small normalization local to the test; no
production sorting, exported helper, or test framework is needed.
3. Preserve discovery aliases, routing, operand metadata, completed-input
immutability, and visible child-order assertions. Do not turn an unordered
internal collection into a public ordering promise.
4. Run `gofmt` on the changed file and, using prepared caches, run:
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=30 -run '^TestCompletionCommandContext$' .
go test -mod=readonly -count=1 -run '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' .
```
The baseline failure already reproduced four times in 30 runs. A fresh baseline
failure is not required before editing; after the repair, all repetitions must
pass and the comparison must still reject missing, unexpected, and duplicate
records by construction. Do not add a test of the sorting helper itself or
rerun until green without correcting the assertion. These repetitions are a
one-time maintenance diagnostic, not a publication requirement.
**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:** order-independent assertions with unchanged production
behavior. Record evidence here and commit this focused test repair separately
under the local commit policy.
## Stage 2: Validate and publish core v0.3.0
## Stage 2: Select the upstream tool and authentic metadata
**Status:** not started.
**Completed.** Go 1.26.8 selected and downloaded v0.9.0; tidy changed only
the tool requirement and its two checksum entries. The helper reported
`releasekit v0.9.0` under foreign target and workspace settings without changing
module metadata. In accordance with the requested per-stage commits, metadata
was committed separately before documentation alignment and snapshot checks.
From the repository root, put Go 1.26.8 on `PATH` using the existing
[toolchain setup](../release.md#release-toolchain). Use normal dependency
retrieval for preparation, followed by offline validation.
1. Preserve the root tool declaration. With workspace discovery off and the
local toolchain selected, perform the version-specific update:
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
GOWORK=off GOTOOLCHAIN=local go mod edit -require=go.maximumdirect.net/releasekit@v0.9.0
GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/releasekit@v0.9.0
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
```
2. Inspect `go.mod` and `go.sum`. Retain authentic downloaded sums. Expected
changes are the v0.8.0-to-v0.9.0 requirement and corresponding two checksum
entries; consumer minimums and other selected versions stay unchanged.
Diagnose proxy lag with an explicitly scoped direct retrieval if necessary;
do not change persistent proxy configuration or select `@latest`.
3. Prepare any missing dependencies in caches for the later offline suites.
Keep integration declarations and the real ignored workspace unchanged.
4. Confirm the real helper prints `releasekit v0.9.0` with inherited foreign
target settings and workspace selection:
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
GOOS=windows GOARCH=arm64 GOWORK=/nonexistent/commandkit-review.work \
GOFLAGS=-trimpath GOPROXY=off GOSUMDB=off ./scripts/releasekit version
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
```
Use another foreign target if Windows/ARM64 is the actual host. Compare
module metadata before and after this invocation; it must not repair or
change it. Keep both scripts unchanged unless an actual in-scope defect is
found; the release-code review selected their present structure.
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:** the root selects v0.9.0 and its real helper runs on the host.
Stages 2 and 3 form one dependency-and-documentation unit. Keep them together
and complete the source checks in Stages 4 and 5 before committing that unit.
**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 3: Align current documentation and attribution
## Stage 6: Validate and publish ckprompt v0.2.0
**Completed.** Current tool references and attribution now identify v0.9.0 and
its pinned source. Upstream COPYRIGHT and LICENSE are unchanged; affected local
links and pinned upstream paths and recovery fragments were checked.
**Status:** not started.
Update these owners together with the tool adoption:
Review and commit the complete ckprompt candidate. From the repository root:
| File | Required change |
| --- | --- |
| `docs/release.md` | Select v0.9.0; update current upstream CLI, profile, publication, delivery, and recovery links to the v0.9.0 source commit. Preserve CommandKit's existing commands and outcomes. |
| `docs/policy/release.md` | Update only the local CommandKit tool-version selection. Keep adopted general text and policy provenance unchanged. |
| `docs/consumers/guide.md` | Update the root Go-tool selection in the Go compatibility summary. Preserve the explanation of its consumer module-graph effect. |
| `docs/oss/attribution.md` | Update the ReleaseKit version and its upstream source and notice links to `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`. Preserve House Format and faithful notices. |
| `docs/roadmap/release-simplification.md` | Record the host-safe launcher examples and regression coverage as shipped in v0.9.0. Point the completed simplification's implementation-evidence link to the immutable prior plan linked above. Preserve the earlier design rationale. |
```sh
git push origin HEAD:refs/heads/main
./scripts/release ckprompt v0.2.0
```
Check the selected upstream `COPYRIGHT` and `LICENSE`; their reviewed contents
are unchanged from v0.8.0, so retain existing license texts and copyright/SPDX
wording. Preserve transitive attribution unless its actual selection changed.
Do not update integration attribution to describe the root's new tool graph.
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.
Keep upstream recovery details linked from the procedure and use generated
recovery commands. Preserve source publication as separate from hosted delivery,
page-only profiles, token-file handling, module release order, and root tool
selection. Update current contract links, not every historical v0.8.0 reference.
Completed remediation, published release notes, and the archived implementation
record remain historical 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.
Check affected local destinations and fragments; check upstream destinations
against the pinned source, using the sibling checkout or downloaded module as
available. Sibling repositories are review evidence, not build dependencies.
Run prose whitespace checks from the developer guide and review the combined
metadata/documentation diff. Record the helper result from Stage 2; keep the
adoption unit staged for the snapshot checks below. Commit it after those
checks, as directed in Stage 6.
**Stage result:** all three matched source releases are published with vanity
module declarations and verified independent dependency graphs.
**Stage result:** current documentation and attribution match the selected tool;
historical records remain accurate and reachable.
## Stage 7: Audit the completed migration and record evidence
## Stage 4: Verify the host tooling and final root snapshot
**Status:** not started.
**Completed.** With Go 1.26.8, shell syntax, executable modes, profile JSON,
and the ignored/untracked credential path were verified. The compiled scripts
tests with empty PATH passed all profile cases and skipped each shell-dependent
case. The retained tests cover R1 and R2, routing, raw forms, and outcomes.
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.
CommandKit commit `bdc3fd8fa38245d017e1cc3f85f85b79013e6072`, tree
`3839ab66be309c095ddad8f73f6f89f778a746d8`, was archived to a disposable
repository at commit `c221ac03dea87b220148e7ead956842ea264408e` with the same
tree. The offline v0.9.0 root `check` passed its suite and selected committed
file checks; the snapshot remained clean. Later status-only edits are not part
of that tested tree.
These are one-time maintenance diagnostics. Reuse successful checks for unchanged
content; do not add permanent test scaffolding, platform matrices, or additional
publication gates.
1. Check `sh -n scripts/release scripts/releasekit`, retained executable modes,
intended JSON selections, and that the credential path is ignored/untracked.
Inspect paths and Git metadata only, never token contents.
2. The focused launcher suite remains part of the root default suite. Review
that it still covers R1 selector rejection before Go execution, legitimate
raw commands, module routing, streams/status, and R2 interpreter handling.
To verify the no-shell boundary, compile `./scripts` with `go test -c` into
external temporary storage, then execute that binary from the repository's
`scripts` directory with an empty `PATH`. Profile assertions must pass and
launcher execution cases must skip. Parent tests may report PASS when all
their child execution cases skip; inspect those child results. No native
Windows validation or new platform support promise is needed.
3. Verify the actual final content, including pending intended changes. If all
content is already committed, archive the reviewed commit; otherwise stage
intended files, obtain the tree with `git write-tree`, and archive that tree.
Do not accidentally test an older `HEAD` or include ignored private files.
Initialize and commit the archive in a disposable Git repository on `main`,
with no tag refs or publication remote. Record its source commit/tree and
which CommandKit revision or staged tree it represents.
4. Build the selected tool once to an external temporary executable with
`GOWORK=off GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off` and
`go build -mod=readonly -o ABS_TEMP_EXECUTABLE go.maximumdirect.net/releasekit/cmd/releasekit`
from the upgraded root. Use native Go host settings. This diagnostic binary
is not a new `.releasekit/bin` workflow.
5. In the disposable snapshot, invoke that executable:
```sh
ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/releasekit.json v0.3.0
```
Substitute the actual absolute paths. The existing note labels this
local-only diagnostic; it is not a new release. Ordinary upstream `check`
runs the root offline `go test -mod=readonly -count=1 ./...` suite and all
selected committed-file checks. Do not run another complete root suite
merely to duplicate that successful evidence.
Confirm no snapshot module metadata changed. Record outcomes and any diagnostics.
A root suite failure is not explained by the known integration dependency
mismatch: investigate it. If a source correction is needed, validate the changed
content rather than treating the older snapshot as final evidence.
**Stage result:** v0.9.0 host execution, retained wrapper behavior, the repaired
completion test, and root committed-input checks have direct final-source
evidence.
## Stage 5: Verify integration source and selected file checks
**Completed.** Both ckconfig and ckprompt checks passed with Go 1.26.8 on
the Stage 4 snapshot using an external workspace and the temporary test-only Go
shim. Their current-source suites, maintained consumers, and selected committed
file checks passed; snapshot module files and Git state remained unchanged.
Independent workspace-off release readiness remains unproven because the
published core dependency lacks current symbols including `CompletionHint` and
`Explanation`.
Use the same clean disposable snapshot and temporary executable from Stage 4.
The baseline independent dependency mismatch is outside this upgrade's scope.
Use the established workspace-backed diagnostic to exercise current integration
source without altering committed module declarations or weakening file checks.
1. Create a Go 1.26.8 workspace in external temporary storage, using absolute
paths to the snapshot root, `integrations/ckconfig`, and
`integrations/ckprompt`. Do not modify or reuse the real ignored `go.work`.
2. ReleaseKit v0.9.0 still forces `GOWORK=off` on child Go suites. An outer
workspace setting alone cannot redirect them. For this diagnostic only,
prepend a temporary executable `go` shim to `PATH`. Set
`COMMANDKIT_REVIEW_GO` to the absolute real Go 1.26.8 binary and
`COMMANDKIT_REVIEW_WORKSPACE` to the external workspace file. Its entire
dispatch can be:
```sh
#!/bin/sh
if [ "${1-}" = test ]; then
export GOWORK="$COMMANDKIT_REVIEW_WORKSPACE"
fi
exec "$COMMANDKIT_REVIEW_GO" "$@"
```
Forward all arguments and other commands unchanged. Export the two named
diagnostic variables for the tool process. Use temporary storage outside
the checkout, keep normal offline/read-only settings, and scope the shim's
`PATH` to these invocations. Do not commit or install this shim.
3. Invoke the same temporary executable for each profile, with options before
the version:
```sh
ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/integrations/ckconfig/releasekit.json v0.1.0
ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/integrations/ckprompt/releasekit.json v0.1.0
```
Each real integration suite, including its maintained consumer, runs once
against current workspace source. Selected file checks still inspect the
unchanged committed inputs, including ordinary module declarations. Do not
skip tests, manufacture sums, add filesystem replacements, change profiles,
or introduce the shim into normal publication.
4. Record both results explicitly as workspace-backed integration diagnostics.
Independent workspace-off release readiness remains unproven, with baseline
missing core symbols such as `CompletionHint` and `Explanation`. If a failure
needs classification, compare with the baseline using the same setup; do not
label an unexplained new failure as the known mismatch. Confirm snapshot
module files and Git state remain unchanged.
**Stage result:** both current-source integration suites and their selected
upstream file checks pass, with the independent dependency limitation stated
accurately. These results complement Stage 4; they do not authorize a release.
## Stage 6: Review completion evidence and finish the sprint
**Completed.** The complete diff was reviewed against the feature roadmap.
The only Go source change is the completion assertion; the scripts, profiles,
integration modules, production APIs, and R1/R2 fixes remain unchanged. The
root and workspace-backed integration checks cover the Stage 4 snapshot;
subsequent changes only record completion and update roadmap status.
1. Review the complete diff against the feature roadmap. Confirm the only code
change is the order-independent test assertion; metadata selects v0.9.0;
current owners and immutable upstream links agree; R1/R2 stay complete; and
scripts, profiles, integration selections, and production APIs retain their
selected behavior.
2. Replace each stage's status with a completion marker only when its result
has evidence. Record Go version, focused repetitions, real helper output,
no-shell check, source/tree identities, root check, both workspace-backed
checks, and the known independent-dependency limitation. Distinguish the
tested snapshot from any later documentation-only tracking edits.
3. Update the feature roadmap's overall status and link here for evidence.
Retain both documents for review; roadmap retirement and any real release
version are later release preparation. Do not rewrite published notes/tags.
4. Check new completion prose, local links/fragments, and staged whitespace.
Reuse suite results for unchanged code and metadata; validate any subsequently
changed source or selected file inputs as appropriate. Report accurately
which checks cover which revision instead of claiming a later tree was
tested when it was not.
5. Follow the local commit policy: inspect status and staged diff, stage only
intended sprint files, check `git diff --cached --check`, review recent
history, and commit completed nonempty units with plain-English messages.
Keep the Stage 1 test repair separate from the dependency/documentation
adoption unit. Commit the validated adoption unit with its evidence; commit
any later tracking edits as needed. Report all sprint commit IDs, results,
and limitations. No empty commits, pushes, or live publication are needed.
With only planned changes present, finish with a clean tracked worktree;
preserve ignored credentials and local environment files.
**Stage result:** the complete selected target is implemented, validated within
the stated boundaries, and committed. This is a maintenance sprint, not source
publication or hosted delivery.
**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 for implementation. The roadmap's selected scope resolves the
earlier scheduling question; integration dependency alignment remains separate
release preparation rather than an undecided part of this sprint.
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.

96
docs/roadmap/integration-dependency-alignment.md
View File

@@ -1,7 +1,9 @@
# Integration dependency alignment and vanity-path migration
Status: proposed release-preparation roadmap. This pass adds documentation only;
dependency changes and publication remain future work.
dependency changes and publication remain future work. The
[implementation plan](implementation.md) owns execution stages, concrete tasks,
and validation tracking; this roadmap owns the target and selected scope.
## Purpose and authority
@@ -111,7 +113,9 @@ new path. Core self-imports, including its `internal` packages, use
`go.maximumdirect.net/commandkit/...`; integration self-imports use
`go.maximumdirect.net/ckconfig/...` or `go.maximumdirect.net/ckprompt/...`.
Cross-module imports and requirements use the complete new paths in the table,
including ckprompt's ckconfig dependency.
including ckprompt's ckconfig dependency. Core component-version discovery uses
`go.maximumdirect.net/commandkit` as its build-info identity, retaining the
existing `version --scope commandkit` behavior with the new module path.
Update production files, tests, maintained examples, and any import-path-based
test expectations together. A declared vanity module that still imports the
@@ -150,80 +154,26 @@ outcomes. Development workspaces remain useful and ignored. Diagnostic local
replacements and the earlier temporary Go shim remain development evidence;
release validation uses normal downloaded dependencies without that redirection.
## Work needed
## Release-preparation deliverables
### Prepare the module-path migration
The core v0.3.0 draft describes the complete candidate, including completion,
reporting, aliases, tool maintenance, and the vanity-path migration. New
integration notes at `integrations/ckconfig/docs/releases/v0.2.0.md` and
`integrations/ckprompt/docs/releases/v0.2.0.md` explain the matched dependency set
and consumer migration. Their source and licensing links follow the current
release procedure; published notes and tags remain immutable.
Migrate the three module declarations and their owned source/test/example
imports using the mapping above. Update CommandKit dependency keys to the
vanity paths as each published predecessor becomes available. Preserve package
names and aliases unless an actual import-resolution change requires an edit.
Current installation examples, README module selections, consumer/developer
guidance, affected GoDoc, and maintained examples use the implemented new
identities. Import-path-aware tests retain their existing boundary assertions.
Source-hosting and license URLs remain repository links, distinct from Go
import paths. Module-local attribution describes each actual resolved graph.
Update current installation examples, module-selection guidance, package links,
and dependency descriptions in the README, consumer/developer guidance, and
affected GoDoc. Adjust import-path-aware tests to the new identities while
preserving their existing boundary assertions. Retain repository/source and
license URLs as source-hosting links; they are distinct from Go import paths.
Keep historical release records and review evidence accurate instead of doing a
repository-wide textual replacement of the old names.
Ignored development workspaces or disposable module files can support validation
before predecessor releases are downloadable. Keep that evidence separate from
the independent release graph. The migration may be prepared across all three
modules locally, while source publication and final dependency preparation
still follow core, ckconfig, then ckprompt order.
### Prepare and release core
Review the v0.3.0 draft against changes since the published v0.2.0 tag, including
completion, invocation reporting, aliases, and release-tool maintenance. Bring
its summary, vanity import migration, compatibility guidance, and immutable
source/licensing links into line with the final candidate and current release
procedure. Keep published notes and tags unchanged.
Prepare and commit the core candidate declaring `go.maximumdirect.net/commandkit`
on `main`, then use the existing source-publication workflow to publish v0.3.0.
Preserve the procedure's required candidate-commit publication before tag
publication. The root suite covers the root module; still-pending integration
alignment is separate work.
### Align and release ckconfig
After core v0.3.0 is published under its new path, prepare ckconfig declaring
`go.maximumdirect.net/ckconfig` and requiring
`go.maximumdirect.net/commandkit v0.3.0`. Remove the superseded old core
requirement, prepare dependencies with workspace discovery off, and tidy the
module metadata. Retain authentic sums from actual downloads. No future
checksum or local replacement substitutes for the published dependency.
Prepare `integrations/ckconfig/docs/releases/v0.2.0.md`, documenting the new core
requirement, vanity import migration, and reporting/completion behavior. Update
affected current guidance and module-local attribution from the actual resolved
graph, including immutable notice links. Validate and publish the selected
ckconfig candidate through the ordinary module release workflow.
### Align and release ckprompt
After ckconfig v0.2.0 is published under its new path, prepare ckprompt declaring
`go.maximumdirect.net/ckprompt` and requiring
`go.maximumdirect.net/commandkit v0.3.0` and
`go.maximumdirect.net/ckconfig v0.2.0` together. Remove the superseded old
CommandKit dependency keys. Prepare downloaded dependencies and tidy with
workspace discovery off. Retain real sums and inspect indirect changes.
Prepare `integrations/ckprompt/docs/releases/v0.2.0.md`, covering the compatible
dependency set, vanity imports, and consumer migration. Align current guidance
and module-local attribution with that selection. Validate and publish its
candidate through the ordinary module release workflow.
### Record the aligned result
Record the selected module paths and versions, candidate revisions, validation
outcomes, and source-publication outcomes separately for all three modules.
Update current dependency-readiness statements that still describe this mismatch
as unresolved; preserve historical baseline failures in completed review and
implementation records. Link future implementation tracking here without
restarting the completed ReleaseKit adoption or remediation work.
The final record identifies module paths, versions, candidate revisions,
validation evidence, and independent source-publication outcomes. Current
readiness guidance reflects the aligned state; historical failures remain in
completed investigation records. The implementation plan owns the ordered
migration, dependency preparation, release, and evidence-recording steps.
## Validation and completion boundaries

2
docs/roadmap/releasekit-v0.9.0.md
View File

@@ -1,7 +1,7 @@
# ReleaseKit v0.9.0 adoption
Status: R1 and R2 remediation, ReleaseKit v0.9.0 adoption, and the completion
assertion repair are complete. The [implementation plan](implementation.md)
assertion repair are complete. The [completed implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a/docs/roadmap/implementation.md)
records stage order, tasks, and validation evidence. This document owns the
target and selected choices; it does not authorize source or hosted publication.