base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 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
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.

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