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

Plan ReleaseKit v0.9.0 implementation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 02:52:09 +00:00
parent 87eb84ccb4
commit 129f95be0f
2 changed files with 296 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files

584
docs/roadmap/implementation.md
View File

@@ -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 Implement these stages in integer order during one end-to-end sprint. The target
stages may temporarily leave scripts, tests, and documentation inconsistent. audience is the Luna coding agent. Intermediate stages may temporarily leave
Do not add compatibility scaffolding or repeat complete suites merely to make metadata and documentation inconsistent; the final result must satisfy the
each intermediate stage independently releasable. Follow the local commit [feature roadmap](releasekit-v0.9.0.md). That document owns target behavior and
policy for completed, validated units; stage boundaries do not require commits. rationale; this plan owns tasks, sequencing, and implementation evidence.
The [feature roadmap](release-simplification.md) owns the target and selected Read [development guidance](../development.md), the
choices. Read [development guidance](../development.md), the
[agent policy](../policy/agents.md), [testing policy](../policy/testing.md), [agent policy](../policy/agents.md), [testing policy](../policy/testing.md),
[documentation policy](../policy/documentation.md), and the applicable [documentation policy](../policy/documentation.md),
[release policy](../policy/release.md) before implementation. Use codebase-memory [release policy](../policy/release.md), and [OSS policy](../policy/oss.md) for
tools for code discovery as instructed by `AGENTS.md`. 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 ## 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 - The root `go.mod` selects `go.maximumdirect.net/releasekit v0.8.0` and registers
version even when releasing an integration. Keep that dependency selection, `go.maximumdirect.net/releasekit/cmd/releasekit`. Adopt exactly v0.9.0, whose
all library module paths and versions, and Go minimums unchanged. upstream source is `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`.
- Three JSON profiles select core, ckconfig, and ckprompt. Their only file - Go 1.26.0 remains the consumer minimum for all three modules. Use Go 1.26.8
selection is the explicit root shared-file list; hosted delivery is absent. for this maintenance work. Preserve the ignored local `go.work`, which at
- `scripts/release` is a 49-line native-build launcher. The 506-line planning time declares Go 1.26.10; use external temporary workspaces instead.
`scripts/release_test.go` and 399-line `scripts/release_integration_test.go` - R1 (`7eac3fe`) and R2 (`4d92ee4`) are complete in
contain the test scaffolding being replaced. [remediation.md](remediation.md). Preserve their fixes and tests.
- `.releasekit/gitea-token` is a maintainer-supplied ignored credential file. - Retain `scripts/release`, `scripts/releasekit`, all three `releasekit.json`
Its contents are not input to implementation or tests. Preserve the file and profiles, and their existing selected validators and page-only Gitea
directory ignore rule. Do not add the credential to fixtures, logs, or commits. destination. Host normalization, full-package tool invocation, root-owned
- Both integrations declare core v0.2.0, while their current source requires tool selection, and separate source/delivery outcomes remain.
newer APIs. Workspace-off Go 1.26.8 tests fail at baseline with missing - The remaining code change is a test-only correction in
`commandkit.CompletionHint`, `Explanation`, and other symbols. This is an `completion_context_test.go`. Production completion ordering stays unchanged.
existing release-readiness issue, not a reason to change dependency versions - Both integration modules require core v0.2.0, while current source needs newer
or weaken validation in this sprint. Stage 5 distinguishes this limitation APIs. Workspace-off integration suites have known missing-symbol failures.
from verification of the current source and selected file checks. 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 Upstream v0.9.0 adds launcher/recovery fixes without changing the public API,
generic file checks and use host-normalized registered-tool execution. Add the profile schema, publication record format, Go minimum, or upstream requirements.
agreed forbidden token path and local page-only Gitea delivery. Keep ordinary The reviewed metadata change was confined to the ReleaseKit version and its
source publication and hosted delivery separate. No binary delivery, CI job, checksum entries. Verify the actual diff; investigate unrelated changes instead
library API change, dependency upgrade, or production publication is part of of accepting them. Do not copy the upstream multi-module bootstrap, introduce
this sprint. No implementation-blocking design question remains. 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 **Status:** not started.
and delivery destination; the credential directory remains ignored.
Edit `releasekit.json`, `integrations/ckconfig/releasekit.json`, and Edit only the relevant test assertions and standard-library imports in
`integrations/ckprompt/releasekit.json`. `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`, 1. Read `TestCompletionCommandContext`. The `entered alias` case expects
`expected_push_url`, and explicit `validation.shared_files`. The endpoint `--detail` to `--verbose` and `--silent` to `--quiet`, but currently compares
remains `ssh://git@forge.maximumdirect.net:22222/base-layer/commandkit.git`. the internal alias slice in a fixed order. Keep those exact expected records.
2. Add `validation.go_format: true`, `validation.markdown: {}`, and 2. Clone the actual alias slice before comparison. Sort the test-owned actual
`validation.module_distribution` with `workspace_files` and and expected slices by `Source`, then `Target`, using standard-library slice
`local_replacements` both true. sorting and comparison. Compare the complete slices, preserving length and
3. Add `validation.forbidden_files` containing only duplicate detection. Keep this small normalization local to the test; no
`.releasekit/gitea-token`. This is a literal repository-relative selection production sorting, exported helper, or test framework is needed.
applying to the captured repository, including integration releases. 3. Preserve discovery aliases, routing, operand metadata, completed-input
4. Add `delivery` with `forge: "gitea"`, immutability, and visible child-order assertions. Do not turn an unordered
`base_url: "https://forge.maximumdirect.net"`, `owner: "base-layer"`, internal collection into a public ordering promise.
`repository: "commandkit"`, and `token_file: ".releasekit/gitea-token"`. 4. Run `gofmt` on the changed file and, using prepared caches, run:
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.
Check that all three files parse as JSON. Use the pinned ```sh
[configuration reference](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/23203f235cc414c4ffe0fd3941030eb0c9f9943f/docs/config.md) GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
for field semantics. Root file checks stop at independent module boundaries; go test -mod=readonly -count=30 -run '^TestCompletionCommandContext$' .
the forbidden-path check has its separately documented repository scope. ```
Do not create custom validators, broader forbidden lists, or blanket exclusions.
**Stage result:** the intended checks and delivery destination are represented The baseline failure already reproduced four times in 30 runs. A fresh baseline
entirely by the existing upstream profile schema. 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 ## Stage 2: Select the upstream tool and authentic metadata
confirmed representative publication and raw-command forwarding. Focused
coverage follows in Stage 3.
Create executable POSIX-shell `scripts/releasekit` as the shared entry point. **Status:** not started.
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.
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`. | | `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. |
| `./scripts/releasekit MODULE check [ARGS...]` | Select module defaults and invoke upstream `check`. | | `docs/policy/release.md` | Update only the local CommandKit tool-version selection. Keep adopted general text and policy provenance unchanged. |
| `./scripts/releasekit MODULE deliver [ARGS...]` | Select module defaults and invoke upstream `deliver`. | | `docs/consumers/guide.md` | Update the root Go-tool selection in the Go compatibility summary. Preserve the explanation of its consumer module-graph effect. |
| `./scripts/releasekit version [ARGS...]` | Forward without module/profile inference. | | `docs/oss/attribution.md` | Update the ReleaseKit version and its upstream source and notice links to `2180aa868ec2caa95fc8279fd59d5f0ebac41bd4`. Preserve House Format and faithful notices. |
| `./scripts/releasekit publication-attempts [ARGS...]` | Forward without module/profile inference. | | `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. |
| `./scripts/releasekit reconcile [ARGS...]` | Forward without module/profile inference. |
`ARGS` are ordinary upstream arguments, including the version where required; Check the selected upstream `COPYRIGHT` and `LICENSE`; their reviewed contents
forward them as separate quoted arguments, without shell evaluation. This are unchanged from v0.8.0, so retain existing license texts and copyright/SPDX
wrapper covers the selected maintainer workflow; it does not reimplement the wording. Preserve transitive attribution unless its actual selection changed.
ReleaseKit parser. Let upstream validate versions, flags, records, and candidate Do not update integration attribution to describe the root's new tool graph.
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.
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 | Check affected local destinations and fragments; check upstream destinations
| --- | --- | --- | --- | against the pinned source, using the sibling checkout or downloaded module as
| `core` | `.` | `releasekit.json` | `CommandKit` | available. Sibling repositories are review evidence, not build dependencies.
| `ckconfig` | `integrations/ckconfig` | `integrations/ckconfig/releasekit.json` | `CommandKit ckconfig` | Run prose whitespace checks from the developer guide and review the combined
| `ckprompt` | `integrations/ckprompt` | `integrations/ckprompt/releasekit.json` | `CommandKit ckprompt` | 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 ## Stage 4: Verify the host tooling and final root snapshot
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.
Reduce `scripts/release` to checking its existing two-argument shape, then **Status:** not started.
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.
**Stage result:** all selected operations share root-tool execution and one These are one-time maintenance diagnostics. Reuse successful checks for unchanged
module mapping; publication and delivery remain explicitly separate commands. 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 ```sh
retired publication exercise and its scaffolding have been removed. 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 Substitute the actual absolute paths. The existing note labels this
executable at the subprocess boundary. Remove local-only diagnostic; it is not a new release. Ordinary upstream `check`
`scripts/release_integration_test.go` and helpers with no remaining users. 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 Confirm no snapshot module metadata changed. Record outcomes and any diagnostics.
outside invocation directory. Copy the scripts and actual profiles into the A root suite failure is not explained by the known integration dependency
fixture. The fake Go needs only to answer the queried `go env` values and to mismatch: investigate it. If a source correction is needed, validate the changed
record the tool invocation, selected environment values, and controlled output content rather than treating the older snapshot as final evidence.
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.
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 ## Stage 5: Verify integration source and selected file checks
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.
Use no credential file, authenticated request, or external service. Keep existing **Status:** not started.
domain package and maintained-consumer tests unchanged. Run the focused scripts
suite during development as needed; Stage 5 owns final complete validation.
**Stage result:** local tests protect CommandKit routing and invocation behavior; Use the same clean disposable snapshot and temporary executable from Stage 4.
upstream tests own publication, credential handling, and hosted reconciliation. 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 ```sh
guidance describe the new launcher, checks, delivery, and recovery workflow. #!/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 Forward all arguments and other commands unchanged. Export the two named
`docs/policy/release.md`, and release-tooling guidance in `docs/development.md`. diagnostic variables for the tool process. Use temporary storage outside
Keep adopted general policy text and provenance intact. Change current owners the checkout, keep normal offline/read-only settings, and scope the shim's
with the implementation; the feature roadmap supplies the design rationale. `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 ```sh
selecting a new release version: ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/integrations/ckconfig/releasekit.json v0.1.0
ABS_TEMP_EXECUTABLE check --repo ABS_SNAPSHOT --config ABS_SNAPSHOT/integrations/ckprompt/releasekit.json v0.1.0
```
- Publish: `./scripts/release core vX.Y.Z`, with corresponding integration Each real integration suite, including its maintained consumer, runs once
selectors. Keep the existing core-then-ckconfig-then-ckprompt order. against current workspace source. Selected file checks still inspect the
- Diagnose: `./scripts/releasekit core check vX.Y.Z`; optional, never a required unchanged committed inputs, including ordinary module declarations. Do not
step before publication repeats validation. skip tests, manufacture sums, add filesystem replacements, change profiles,
- Deliver: `./scripts/releasekit core deliver vX.Y.Z`, or either integration or introduce the shim into normal publication.
selector with its own semantic version. The profile derives the full tag. 4. Record both results explicitly as workspace-backed integration diagnostics.
- Discover/reconcile: `./scripts/releasekit publication-attempts` and Independent workspace-off release readiness remains unproven, with baseline
`./scripts/releasekit reconcile --record /absolute/path/to/attempt.json`. missing core symbols such as `CompletionHint` and `Explanation`. If a failure
- Inspect the tool: `./scripts/releasekit version`. 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 **Stage result:** both current-source integration suites and their selected
the original tagged source, the page-only body and module-specific full tags, upstream file checks pass, with the independent dependency limitation stated
environment-token precedence over the repository-relative token file, and accurately. These results complement Stage 4; they do not authorize a release.
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.
Remove native executable-storage commands and the retired ## Stage 6: Review completion evidence and finish the sprint
`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.
Search affected documentation for stale `.releasekit/bin/` and retired test **Status:** not started.
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.
**Stage result:** the maintainer runbook describes the actual wrapper commands, 1. Review the complete diff against the feature roadmap. Confirm the only code
selected checks, separate outcomes, and recovery without obsolete scaffolding. 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, ## Open Questions
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.
The staged tree was archived and committed in a disposable repository. The None required for implementation. The roadmap's selected scope resolves the
pinned ReleaseKit core check passed, including the root suite and selected earlier scheduling question; integration dependency alignment remains separate
committed-file checks. Both integration checks passed using the documented release preparation rather than an undecided part of this sprint.
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.

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

@@ -2,7 +2,9 @@
Status: R1 and R2 remediation is complete in separate commits. ReleaseKit v0.9.0 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 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 ## Purpose and authority
@@ -20,7 +22,7 @@ and owning package tests until implementation updates them.
## Current baseline and review evidence ## Current baseline and review evidence
Current CommandKit baseline: `4d92ee4ee6a8403b22a4172e0f04face802b9499`. Reviewed CommandKit code baseline: `4d92ee4ee6a8403b22a4172e0f04face802b9499`.
The original upgrade review used `98e7e9933353cf43f2be4a96cb0436a0bce068d2`; The original upgrade review used `98e7e9933353cf43f2be4a96cb0436a0bce068d2`;
its findings and validation history are retained below. 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 their acceptance evidence, including passing focused tests, shell syntax
checks, and profile assertions running when no shell is available. checks, and profile assertions running when no shell is available.
- Both integrations still require older published CommandKit dependencies than - 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. distinguishes workspace-backed tests from independent release readiness.
The upstream v0.9.0 tag identifies commit 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 their selector rejection, legitimate raw helper forms, and optional-shell test
boundary during adoption; no further implementation of those findings remains. boundary during adoption; no further implementation of those findings remains.
The completion test's incidental ordering assumption remains unresolved and is The completion assertion compares the expected alias source/target records
separate from the completed remediation findings. Correct it in its own without depending on their iteration order, while detecting missing, unexpected,
reviewable commit within the remaining maintenance work. Compare the or duplicate records. Its routing and visible-completion assertions remain.
expected alias source/target records without depending on their iteration Production alias ordering and public contracts are unchanged. This correction
order, while still detecting missing, unexpected, or duplicate records. Sorting remains part of the maintenance scope, separate from completed R1/R2 remediation;
test-owned copies is one straightforward approach. Preserve the other routing the implementation plan owns the test changes and focused verification.
and visible-completion assertions. Do not restore production sorting or promise
a new internal alias order merely to make this assertion pass.
## Work needed Ordinary releases retain their single selected-module publication suite and
separate hosted-delivery outcome. One-time upgrade diagnostics are maintenance
- [x] Complete R1 in its own commit (`7eac3fe`), recording verification in evidence, with no new recurring release gate. Credentials and live publication
[remediation.md](remediation.md). are unnecessary for this adoption.
- [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.
## Completion evidence ## Completion evidence
@@ -208,15 +172,14 @@ corrected launcher behavior. Independent integration dependency alignment
remains separate release-preparation work; this roadmap selects no future remains separate release-preparation work; this roadmap selects no future
versions or sums. versions or sums.
## Sequencing after remediation ## Resolved choices
The former OD-1 question about bundling R1/R2 with adoption is resolved: both R1 and R2 were corrected in separate commits before adoption, resolving the
findings were corrected and committed separately before the upgrade. They are former OD-1 scheduling question. Their acceptance evidence remains in
neither open decisions nor remaining adoption tasks. [remediation.md](remediation.md).
For the remaining work, repair the completion assertion, then adopt v0.9.0 and The selected maintenance scope is the completion assertion repair, root tool
align current documentation and attribution, keeping the test repair and tool upgrade, aligned current documentation and attribution, and validation of the
adoption reviewable as separate commits. Validate the resulting source and resulting source. The older integration dependency-version mismatch remains
record the actual evidence before marking adoption complete. A passing rerun separate release-preparation work. The implementation plan defines execution
alone does not resolve the known nondeterministic assertion. The older and commit sequencing.
integration dependency-version mismatch remains outside this maintenance scope.