diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 11d6529..275a2f7 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/roadmap/integration-dependency-alignment.md b/docs/roadmap/integration-dependency-alignment.md index e8c2375..dff5327 100644 --- a/docs/roadmap/integration-dependency-alignment.md +++ b/docs/roadmap/integration-dependency-alignment.md @@ -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 diff --git a/docs/roadmap/releasekit-v0.9.0.md b/docs/roadmap/releasekit-v0.9.0.md index 8f2b4d0..261ec8d 100644 --- a/docs/roadmap/releasekit-v0.9.0.md +++ b/docs/roadmap/releasekit-v0.9.0.md @@ -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.