From 129f95be0fdacc6deeb0e5c146e9009e7ca17deb Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 02:52:09 +0000 Subject: [PATCH] Plan ReleaseKit v0.9.0 implementation --- docs/roadmap/implementation.md | 584 ++++++++++++++---------------- docs/roadmap/releasekit-v0.9.0.md | 85 ++--- 2 files changed, 296 insertions(+), 373 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 7caf1f8..6839000 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,360 +1,320 @@ -# Release tooling implementation plan +# ReleaseKit v0.9.0 implementation plan -Status: Stages 1–6 complete. +Status: planned; Stages 1–6 are not started. -Follow the stages in integer order. This is one end-to-end sprint: intermediate -stages may temporarily leave scripts, tests, and documentation inconsistent. -Do not add compatibility scaffolding or repeat complete suites merely to make -each intermediate stage independently releasable. Follow the local commit -policy for completed, validated units; stage boundaries do not require commits. +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. -The [feature roadmap](release-simplification.md) owns the target and selected -choices. Read [development guidance](../development.md), the +Read [development guidance](../development.md), the [agent policy](../policy/agents.md), [testing policy](../policy/testing.md), -[documentation policy](../policy/documentation.md), and the applicable -[release policy](../policy/release.md) before implementation. Use codebase-memory -tools for code discovery as instructed by `AGENTS.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: `3d396b1a66bfafc509472cd74a3f8029def3d432`. At that revision: +Planning baseline: `87eb84ccb462bf54e6250c8b287ac217efe90883`. -- `go.mod` registers ReleaseKit v0.8.0. The root module owns the selected tool - version even when releasing an integration. Keep that dependency selection, - all library module paths and versions, and Go minimums unchanged. -- Three JSON profiles select core, ckconfig, and ckprompt. Their only file - selection is the explicit root shared-file list; hosted delivery is absent. -- `scripts/release` is a 49-line native-build launcher. The 506-line - `scripts/release_test.go` and 399-line `scripts/release_integration_test.go` - contain the test scaffolding being replaced. -- `.releasekit/gitea-token` is a maintainer-supplied ignored credential file. - Its contents are not input to implementation or tests. Preserve the file and - directory ignore rule. Do not add the credential to fixtures, logs, or commits. -- Both integrations declare core v0.2.0, while their current source requires - newer APIs. Workspace-off Go 1.26.8 tests fail at baseline with missing - `commandkit.CompletionHint`, `Explanation`, and other symbols. This is an - existing release-readiness issue, not a reason to change dependency versions - or weaken validation in this sprint. Stage 5 distinguishes this limitation - from verification of the current source and selected file checks. +- 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. -The former open decisions are resolved for this plan: select all four proposed -generic file checks and use host-normalized registered-tool execution. Add the -agreed forbidden token path and local page-only Gitea delivery. Keep ordinary -source publication and hosted delivery separate. No binary delivery, CI job, -library API change, dependency upgrade, or production publication is part of -this sprint. No implementation-blocking design question remains. +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: Configure the three release profiles +## Stage 1: Repair the completion assertion's ordering assumption -**Completed.** All three profiles parse as JSON and select the planned checks -and delivery destination; the credential directory remains ignored. +**Status:** not started. -Edit `releasekit.json`, `integrations/ckconfig/releasekit.json`, and -`integrations/ckprompt/releasekit.json`. +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. Preserve each profile's `product`, `module_dir`, `remote`, - `expected_push_url`, and explicit `validation.shared_files`. The endpoint - remains `ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. -2. Add `validation.go_format: true`, `validation.markdown: {}`, and - `validation.module_distribution` with `workspace_files` and - `local_replacements` both true. -3. Add `validation.forbidden_files` containing only - `.releasekit/gitea-token`. This is a literal repository-relative selection - applying to the captured repository, including integration releases. -4. Add `delivery` with `forge: "gitea"`, - `base_url: "https://forge.maximumdirect.net"`, `owner: "base-layer"`, - `repository: "commandkit"`, and `token_file: ".releasekit/gitea-token"`. - Leave `token_env` omitted, preserving ReleaseKit's default environment - override. Add no build targets or additional validators. -5. Retain `/.releasekit/` in `.gitignore`; revise its comment from executable - storage to local ReleaseKit credentials. Do not remove existing local files. +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: -Check that all three files parse as JSON. Use the pinned -[configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md) -for field semantics. Root file checks stop at independent module boundaries; -the forbidden-path check has its separately documented repository scope. -Do not create custom validators, broader forbidden lists, or blanket exclusions. + ```sh + GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \ + go test -mod=readonly -count=30 -run '^TestCompletionCommandContext$' . + ``` -**Stage result:** the intended checks and delivery destination are represented -entirely by the existing upstream profile schema. +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 2: Centralize tool invocation and module routing +**Stage result:** order-independent assertions with unchanged production +behavior. Record evidence here and commit this focused test repair separately +under the local commit policy. -**Completed.** Both scripts pass shell syntax checks; a fake Go invocation -confirmed representative publication and raw-command forwarding. Focused -coverage follows in Stage 3. +## Stage 2: Select the upstream tool and authentic metadata -Create executable POSIX-shell `scripts/releasekit` as the shared entry point. -Keep executable `scripts/release` as the existing publication convenience entry -point. No shell library, module-map file, generated script, or JSON parser is -needed in the launcher. +**Status:** not started. -The shared entry point has these forms: +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. -| Invocation | Handling | +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 + +**Status:** not started. + +Update these owners together with the tool adoption: + +| File | Required change | | --- | --- | -| `./scripts/releasekit MODULE publish [ARGS...]` | Select module defaults and invoke upstream `publish`. | -| `./scripts/releasekit MODULE check [ARGS...]` | Select module defaults and invoke upstream `check`. | -| `./scripts/releasekit MODULE deliver [ARGS...]` | Select module defaults and invoke upstream `deliver`. | -| `./scripts/releasekit version [ARGS...]` | Forward without module/profile inference. | -| `./scripts/releasekit publication-attempts [ARGS...]` | Forward without module/profile inference. | -| `./scripts/releasekit reconcile [ARGS...]` | Forward without module/profile inference. | +| `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. | -`ARGS` are ordinary upstream arguments, including the version where required; -forward them as separate quoted arguments, without shell evaluation. This -wrapper covers the selected maintainer workflow; it does not reimplement the -ReleaseKit parser. Let upstream validate versions, flags, records, and candidate -state. Reject a missing selector/operation or unsupported wrapper form with -usage on stderr and status 2 before running Go. Preserve meaningful argv -boundaries; exact usage prose is not a compatibility target. +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. -Implement the only selector mapping in `scripts/releasekit`: +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. -| Selector | Module directory | Profile | Product for profile-wiring tests | -| --- | --- | --- | --- | -| `core` | `.` | `releasekit.json` | `CommandKit` | -| `ckconfig` | `integrations/ckconfig` | `integrations/ckconfig/releasekit.json` | `CommandKit ckconfig` | -| `ckprompt` | `integrations/ckprompt` | `integrations/ckprompt/releasekit.json` | `CommandKit ckprompt` | +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. -Implementation details: +**Stage result:** current documentation and attribution match the selected tool; +historical records remain accurate and reachable. -1. Resolve the repository root from the script location using quoted POSIX - shell operations safe with spaces and inherited `CDPATH`; change there. -2. Set `GOWORK=off` and `GOTOOLCHAIN=local` before querying Go. Resolve native - `GOHOSTOS` and `GOHOSTARCH` through the selected `go`, then export them as - `GOOS` and `GOARCH` for tool execution. Do not inherit a cross-build target. -3. Read the effective flags with `go env GOFLAGS`. Append `-mod=readonly` to - that string and export it as `GOFLAGS`, preserving the other effective - flags. Appending gives read-only selection precedence over an inherited - `-mod` setting. Do not parse or evaluate the string in the shell. Go 1.26.8 - does not accept `go tool -mod=readonly`; do not use that unsupported form. -4. For module operations, prepend `OPERATION --repo ROOT --config ABS_PROFILE`. - For `publish` only, also prepend `--expected-module MODULE_DIR`. Neither - ordinary `check` nor `deliver` accepts that publication flag. Append the - supplied upstream arguments unchanged; upstream owns its flag semantics. -5. For the three raw forms, forward the command and supplied arguments without - adding profile, module, or publication flags. The working directory is the - repository root. Relative record paths therefore resolve there; document - absolute record paths in examples for clarity, without prohibiting relative - ones. Recovery identity comes from the selected saved record. -6. Finish through `exec go tool go.maximumdirect.net/releasekit/cmd/releasekit`. - Preserve the child's output streams and exit status. Do not create or build - an executable in `.releasekit/bin/`, preflight Gitea, or chain delivery after - publication. +## Stage 4: Verify the host tooling and final root snapshot -Reduce `scripts/release` to checking its existing two-argument shape, then -executing the sibling helper with `MODULE publish VERSION`. Delegate selector -validation to that helper, avoiding a second mapping. Keep -`./scripts/release MODULE VERSION` usable from outside the repository. +**Status:** not started. -**Stage result:** all selected operations share root-tool execution and one -module mapping; publication and delivery remain explicitly separate commands. +These are one-time maintenance diagnostics. Reuse successful checks for unchanged +content; do not add permanent test scaffolding, platform matrices, or additional +publication gates. -## Stage 3: Replace release-test scaffolding with focused wiring tests +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: -**Completed.** The focused scripts suite passes with the subprocess fake; the -retired publication exercise and its scaffolding have been removed. + ```sh + ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/releasekit.json v0.3.0 + ``` -Rewrite `scripts/release_test.go` around the actual scripts and a small fake Go -executable at the subprocess boundary. Remove -`scripts/release_integration_test.go` and helpers with no remaining users. + 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. -Use temporary directories, including a repository path with spaces and an -outside invocation directory. Copy the scripts and actual profiles into the -fixture. The fake Go needs only to answer the queried `go env` values and to -record the tool invocation, selected environment values, and controlled output -and status. Simple argument recording suffices: remove `goCall`, its bespoke -record parser, native-build assertions, and tests of assertion helpers. Do not -retain a fake build stage, fake publisher executable, Git repository fixture, -tag inspector, suite marker, or release-note generator. +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. -Cover these behaviors with compact cases: +**Stage result:** v0.9.0 host execution, retained wrapper behavior, the repaired +completion test, and root committed-input checks have direct final-source +evidence. -- Check the selector table against the copied profiles' module/product and the - selected destination, forbidden token path, shared files, and validation - selections. This checks CommandKit's choices, not upstream parsing semantics. -- Exercise each selector with `publish`, `check`, and `deliver`. Verify absolute - repository/profile arguments, publication-only `--expected-module`, and - unchanged forwarding of supplied upstream arguments. -- Exercise the legacy publication entry point and raw recovery/version forms. - Verify recovery receives the explicit record/options without inferred module - identity or a profile argument. -- Use foreign target values, workspace/toolchain overrides, and effective - `GOFLAGS` containing an unrelated flag and `-mod=mod`. The recorded tool - environment must select the host, disable workspace discovery, use the local - toolchain, preserve the unrelated flag, and give read-only mode precedence. - Assert effective settings rather than an incidental count/order of queries. -- Exercise statuses 0, 1, 2, and 3 on a representative operation, stdout/stderr - forwarding, and a nonzero legacy-publication result. Do not multiply all - module/operation combinations by all exit statuses. -- Exercise malformed wrapper invocations and confirm no Go command ran. Leave - invalid semantic-version and upstream-flag classification to ReleaseKit. +## Stage 5: Verify integration source and selected file checks -Use no credential file, authenticated request, or external service. Keep existing -domain package and maintained-consumer tests unchanged. Run the focused scripts -suite during development as needed; Stage 5 owns final complete validation. +**Status:** not started. -**Stage result:** local tests protect CommandKit routing and invocation behavior; -upstream tests own publication, credential handling, and hosted reconciliation. +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. -## Stage 4: Align current documentation with the implemented workflow +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: -**Completed.** The release procedure, project-specific policy, and developer -guidance describe the new launcher, checks, delivery, and recovery workflow. + ```sh + #!/bin/sh + if [ "${1-}" = test ]; then + export GOWORK="$COMMANDKIT_REVIEW_WORKSPACE" + fi + exec "$COMMANDKIT_REVIEW_GO" "$@" + ``` -Update `docs/release.md`, the CommandKit-specific scope in -`docs/policy/release.md`, and release-tooling guidance in `docs/development.md`. -Keep adopted general policy text and provenance intact. Change current owners -with the implementation; the feature roadmap supplies the design rationale. + 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: -Document these concrete invocation examples, using placeholders rather than -selecting a new release 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 + ``` -- Publish: `./scripts/release core vX.Y.Z`, with corresponding integration - selectors. Keep the existing core-then-ckconfig-then-ckprompt order. -- Diagnose: `./scripts/releasekit core check vX.Y.Z`; optional, never a required - step before publication repeats validation. -- Deliver: `./scripts/releasekit core deliver vX.Y.Z`, or either integration - selector with its own semantic version. The profile derives the full tag. -- Discover/reconcile: `./scripts/releasekit publication-attempts` and - `./scripts/releasekit reconcile --record /absolute/path/to/attempt.json`. -- Inspect the tool: `./scripts/releasekit version`. + 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. -Include the clean tagged-checkout prerequisite for delivery, later retries from -the original tagged source, the page-only body and module-specific full tags, -environment-token precedence over the repository-relative token file, and -retention of the ignored credential directory. Explain that successful source -publication completes the source release, while hosted delivery has a separate -outcome and URL. Credentials and Gitea availability do not gate publication. -Refer to upstream delivery and recovery contracts rather than duplicating an -HTTP implementation or a second status model. +**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. -Remove native executable-storage commands and the retired -`COMMANDKIT_RELEASE_INTEGRATION` exercise instructions. Explain that selected -upstream file checks inspect committed inputs, cover modules independently, -and do not replace domain review. Document future licensing footer URLs using -`https://forge.maximumdirect.net/base-layer/commandkit/src/tag/FULL_TAG/` plus -the correct repository-relative module file path. Keep existing published notes -and tags unchanged; add no speculative release note or historical backfill. -No CI workflow, provider call, runtime API, or attribution update is required. +## Stage 6: Review completion evidence and finish the sprint -Search affected documentation for stale `.releasekit/bin/` and retired test -references. Keep the credential-path references. Where baseline documentation -mentions a deleted source file, use its inline path and baseline revision -instead of leaving a broken local hyperlink. Keep stage tracking in this plan, -not in the feature roadmap. +**Status:** not started. -**Stage result:** the maintainer runbook describes the actual wrapper commands, -selected checks, separate outcomes, and recovery without obsolete scaffolding. +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 5: Verify the final source and record validation boundaries +**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. -**Completed.** With Go 1.26.8 and local toolchain selection, shell syntax, -executable modes, JSON parsing, ignored/untracked token path, and whitespace -checks passed. The real helper reported ReleaseKit v0.8.0 under foreign target -settings and an inherited workspace; a disposable copy with missing tool sums -failed under inherited `-mod=mod` without changing its sums. +## Open Questions -The staged tree was archived and committed in a disposable repository. The -pinned ReleaseKit core check passed, including the root suite and selected -committed-file checks. Both integration checks passed using the documented -temporary workspace shim, including their current-source suites and selected -file checks. Independent workspace-off tests for both integrations failed on -missing core symbols including `CompletionHint` and `Explanation`, consistent -with the baseline dependency-version mismatch. The shimmed checks do not prove -published dependency alignment or integration release readiness. - -Use Go 1.26.8 on `PATH`, `GOTOOLCHAIN=local`, and prepared dependency caches. -Reuse checks for unchanged final content instead of repeating them for each -stage. Preserve the existing ignored `go.work` (currently declaring Go 1.26.10); -use an external temporary Go 1.26.8 workspace when testing current source. - -Perform the following one-time migration checks; add no persistent validation -script or new recurring publication gate: - -1. Check shell syntax and executable modes for both scripts, parse the profiles, - review documentation links/fragments, and run `git diff --check`. Verify only - the intended files changed and the token remains ignored and untracked. -2. Exercise the real helper's `version` with foreign `GOOS`/`GOARCH`, an inherited - workspace, and an unrelated effective Go flag. Confirm ReleaseKit v0.8.0 runs - natively without changing module files. In a disposable module copy, remove - required tool checksum metadata and use inherited `-mod=mod`; confirm the - helper fails instead of repairing metadata. Do not alter the real sum files. -3. Review and stage only the intended sprint changes, including new files, for - verification. Obtain the staged tree with `git write-tree` and archive that - tree into a disposable directory; do not archive `HEAD` and accidentally - test the old implementation. Initialize and commit that snapshot in a new - local Git repository on `main`, with no copied tag refs or publication - remote. This verifies intended content before committing it in CommandKit. - Do not include ignored files, unrelated staged work, or real credentials. - Existing notes can label these local-only diagnostics: core `v0.3.0`, - integrations `v0.1.0`. No tag is created or reused in an authoritative - repository. -4. Build the pinned ReleaseKit executable once into temporary storage, using - the selected root module and read-only metadata. Run ordinary upstream - `check` on the snapshot's core profile with workspace discovery off. This - runs the root suite, including the new scripts tests, and all selected file - checks. Temporary native storage here is diagnostic setup, not launcher code. -5. For the integrations, create an external temporary workspace containing all - three snapshot modules. ReleaseKit v0.8.0 intentionally forces `GOWORK=off` - for its child suites, so exporting a workspace or alternate module-file flag - on the outer command cannot redirect those suites. For this diagnostic only, - put a temporary `go` shim on the executable's `PATH`: forward all invocations - to the absolute real Go binary, but for `go test` set `GOWORK` to that temporary - workspace before executing the real command. Do not skip tests or alter their - remaining arguments. Run upstream `check` for both integration profiles. - Real package suites then exercise current source; upstream file checks still - inspect unchanged committed inputs, including ordinary `go.mod` files. This - procedure was verified during planning and needs no committed helper. -6. Record workspace-backed integration results separately from independent - release-readiness evidence. The baseline standalone failures listed above - must remain visible. If needed, compare workspace-off tests with baseline to - distinguish new failures. Do not claim the shimmed diagnostic proves that - published dependencies are aligned, and do not add the shim to ordinary - `check`, `publish`, or the default test suite. Dependency/version alignment - and preparation of real integration candidates remain separate release work. - -Planning evidence: the four generic file checks passed for the baseline core; -all five selected file checks passed for both baseline integration snapshots -using their real workspace-backed suites. The corresponding workspace-off -integration suites failed with the known missing-core-symbol errors. Repeat -the relevant diagnostics for the final sprint content, not merely the baseline. -Investigate new failures without turning the baseline limitation into a false -green result or disabling an agreed validator. - -Do not invoke `publish`, `deliver`, or `ci-deliver` against a real destination -for verification. Configuration and forwarding are the local responsibility; -ReleaseKit owns authenticated preflight, hosted writes, and content matching. - -**Stage result:** the changed infrastructure, real current-source suites, and -selected committed-file checks are verified, with independent integration -release-readiness limits accurately reported. - -## Stage 6: Review, document completion, and commit - -**Completed.** The implementation was reviewed against the feature roadmap; -validation and the integration dependency limitation are recorded above. The -roadmap documents remain available for later release preparation. - -Review the complete diff against the feature roadmap. Confirm that all three -profiles have the selected options and destination; one shared launcher owns -module routing; the old publication exercise and unused helpers are gone; -domain tests remain; documentation uses the new invocation and separate -outcomes; and `/.releasekit/` still protects the local token directory. - -Record stages completed and final validation results in this document, including -the dependency-version limitation. Do not retire these roadmap documents during -this sprint: retain the target and completion evidence for review, then apply -the normal roadmap lifecycle during later release preparation. No new release -version or source/hosted publication is required to finish this implementation. - -Follow the local commit policy, review staged changes, and commit the intended -implementation units with short plain-English messages. Report the commit IDs, -remaining work, and verification limits. Preserve unrelated changes and private -files; do not force a clean worktree by deleting or including them. With only -the planned sprint changes present, the resulting tracked worktree should be -clean. Intermediate failures do not justify leaving the final selected scope -partially implemented. - -**Stage result:** a reviewable, committed implementation of the selected target -with accurate validation evidence and no production publication. +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. diff --git a/docs/roadmap/releasekit-v0.9.0.md b/docs/roadmap/releasekit-v0.9.0.md index 204339b..581649b 100644 --- a/docs/roadmap/releasekit-v0.9.0.md +++ b/docs/roadmap/releasekit-v0.9.0.md @@ -2,7 +2,9 @@ Status: R1 and R2 remediation is complete in separate commits. ReleaseKit v0.9.0 adoption and the completion assertion repair remain planned; the root tool still -selects v0.8.0. This document does not authorize source or hosted publication. +selects v0.8.0. The [implementation plan](implementation.md) owns stage order, +tasks, and validation tracking. This document owns the target and selected +choices; it does not authorize source or hosted publication. ## Purpose and authority @@ -20,7 +22,7 @@ and owning package tests until implementation updates them. ## Current baseline and review evidence -Current CommandKit baseline: `4d92ee4ee6a8403b22a4172e0f04face802b9499`. +Reviewed CommandKit code baseline: `4d92ee4ee6a8403b22a4172e0f04face802b9499`. The original upgrade review used `98e7e9933353cf43f2be4a96cb0436a0bce068d2`; its findings and validation history are retained below. @@ -40,7 +42,7 @@ its findings and validation history are retained below. their acceptance evidence, including passing focused tests, shell syntax checks, and profile assertions running when no shell is available. - Both integrations still require older published CommandKit dependencies than - their current source needs. The completed [implementation record](implementation.md) + their current source needs. The completed [release-tooling implementation record](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/87eb84ccb462bf54e6250c8b287ac217efe90883/docs/roadmap/implementation.md#stage-5-verify-the-final-source-and-record-validation-boundaries) distinguishes workspace-backed tests from independent release readiness. The upstream v0.9.0 tag identifies commit @@ -144,55 +146,17 @@ markers and acceptance evidence in [remediation.md](remediation.md). Preserve their selector rejection, legitimate raw helper forms, and optional-shell test boundary during adoption; no further implementation of those findings remains. -The completion test's incidental ordering assumption remains unresolved and is -separate from the completed remediation findings. Correct it in its own -reviewable commit within the remaining maintenance work. Compare the -expected alias source/target records without depending on their iteration -order, while still detecting missing, unexpected, or duplicate records. Sorting -test-owned copies is one straightforward approach. Preserve the other routing -and visible-completion assertions. Do not restore production sorting or promise -a new internal alias order merely to make this assertion pass. +The completion assertion compares the expected alias source/target records +without depending on their iteration order, while detecting missing, unexpected, +or duplicate records. Its routing and visible-completion assertions remain. +Production alias ordering and public contracts are unchanged. This correction +remains part of the maintenance scope, separate from completed R1/R2 remediation; +the implementation plan owns the test changes and focused verification. -## Work needed - -- [x] Complete R1 in its own commit (`7eac3fe`), recording verification in - [remediation.md](remediation.md). -- [x] Complete R2 in its own commit (`4d92ee4`), recording verification in - [remediation.md](remediation.md). R1/R2 scheduling is resolved by their delivery - before adoption. -- [x] Review remaining release code against v0.9.0. Retain the helper, legacy - wrapper, profiles, and focused wiring tests for the reasons above. -- [ ] Repair the completion assertion's ordering assumption and verify the - correction with focused repetitions. Preserve production ordering behavior - and the remaining routing assertions. -- [ ] Select the root tool at v0.9.0, tidy module metadata, and inspect the - actual `go.mod`/`go.sum` diff. Investigate unexpected version changes rather - than accepting unrelated upgrades. Use normal cache preparation; direct - retrieval can diagnose proxy lag without becoming permanent configuration. -- [ ] Update current owners: `docs/release.md`, the local selection in - `docs/policy/release.md`, `docs/consumers/guide.md`, and the root ReleaseKit - entry in `docs/oss/attribution.md`. Check affected source links and fragments - at the v0.9.0 commit. Update the earlier feature roadmap's pending-request - statement while retaining its historical evidence. -- [ ] Validate the actual upgraded helper with inherited foreign target values, - and run the owning offline suites with Go 1.26.8. During development, use - focused repetitions to check the completion repair; do not treat rerunning - until green as a substitute for fixing it. -- [ ] Exercise selected ReleaseKit checks on the final committed candidate - inputs using disposable source snapshots where appropriate. Reuse the - completed implementation record's one-time procedure for workspace-backed - integration diagnostics; do not add it to ordinary publication or claim it - proves independent published-dependency alignment. -- [ ] Review whitespace, affected documentation links, and the final diff; - record what passed, what remains open, and the reviewed source revision. - Commit completed units under the local commit policy. - -No live token, model call, hosted write, or authoritative tag push is needed to -verify this maintenance work. Do not read the credential file as part of the -upgrade. Ordinary releases still use their single selected-module publication -suite, with hosted delivery reported separately. Focused repetitions and -disposable-copy diagnostics here are maintenance evidence, not permanent extra -release gates. +Ordinary releases retain their single selected-module publication suite and +separate hosted-delivery outcome. One-time upgrade diagnostics are maintenance +evidence, with no new recurring release gate. Credentials and live publication +are unnecessary for this adoption. ## Completion evidence @@ -208,15 +172,14 @@ corrected launcher behavior. Independent integration dependency alignment remains separate release-preparation work; this roadmap selects no future versions or sums. -## Sequencing after remediation +## Resolved choices -The former OD-1 question about bundling R1/R2 with adoption is resolved: both -findings were corrected and committed separately before the upgrade. They are -neither open decisions nor remaining adoption tasks. +R1 and R2 were corrected in separate commits before adoption, resolving the +former OD-1 scheduling question. Their acceptance evidence remains in +[remediation.md](remediation.md). -For the remaining work, repair the completion assertion, then adopt v0.9.0 and -align current documentation and attribution, keeping the test repair and tool -adoption reviewable as separate commits. Validate the resulting source and -record the actual evidence before marking adoption complete. A passing rerun -alone does not resolve the known nondeterministic assertion. The older -integration dependency-version mismatch remains outside this maintenance scope. +The selected maintenance scope is the completion assertion repair, root tool +upgrade, aligned current documentation and attribution, and validation of the +resulting source. The older integration dependency-version mismatch remains +separate release-preparation work. The implementation plan defines execution +and commit sequencing.