commandkit/docs/roadmap/implementation.md

# ReleaseKit v0.9.0 implementation plan

Status: Stages 1–4 complete; Stages 5–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](releasekit-v0.9.0.md). That document owns target behavior and
rationale; this plan owns tasks, sequencing, and implementation evidence.

Read [development guidance](../development.md), the
[agent policy](../policy/agents.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 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.

## 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](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](../release.md#release-toolchain), 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:

   ```sh
   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

**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. Documentation alignment and snapshot checks follow.

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:

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

   ```sh
   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

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

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

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

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

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

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

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