commandkit/docs/roadmap/implementation.md

ReleaseKit v0.9.0 implementation plan

Status: Stage 1 complete; Stages 2–6 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. That document owns target behavior and rationale; this plan owns tasks, sequencing, and implementation evidence.

Read development guidance, the agent policy, testing policy, documentation policy, release policy, and OSS policy for the changes they govern. Use the codebase-memory tools for code discovery as required by AGENTS.md.

The previous implementation plan covered the completed release simplification. Its stages and validation evidence remain in Git history. Its Stage 5 documents the integration diagnostic reused below. Do not restart that completed sprint.

Baseline and fixed decisions

Planning baseline: 87eb84ccb462bf54e6250c8b287ac217efe90883.

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

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.

Stage 1: Repair the completion assertion's ordering assumption

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.

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, including for this stage.

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:

   GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=30 -run '^TestCompletionCommandContext$' .
   

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: order-independent assertions with unchanged production behavior. Record evidence here and commit this focused test repair separately under the local commit policy.

Stage 2: Select the upstream tool and authentic metadata

Status: not started.

From the repository root, put Go 1.26.8 on PATH using the existing toolchain setup. 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:

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

   GOOS=windows GOARCH=arm64 GOWORK=/nonexistent/commandkit-review.work \
     GOFLAGS=-trimpath GOPROXY=off GOSUMDB=off ./scripts/releasekit version
   

   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.

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 3: Align current documentation and attribution

Status: not started.

Update these owners together with the tool adoption:

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.

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.

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.

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: current documentation and attribution match the selected tool; historical records remain accurate and reachable.

Stage 4: Verify the host tooling and final root snapshot

Status: not started.

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:

   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

Status: not started.

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:

   #!/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:

   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

Status: not started.

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.

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.